스킬셋 보강과 RAG 수집 흐름 구성

색인 설계 노트에서 인덱서의 세 부품 중 하나로 기술 집합을 잠깐 봤습니다. 이 노트는 그 부품을 엽니다. 문서를 읽어 와서 색인에 넣기 전에 무엇을 어떤 순서로 가공하는가가 RAG 품질의 절반을 정하고, 시험은 그 순서와 각 단계의 입출력 경로를 구성 값으로 묻습니다.

보강 파이프라인

스킬셋

스킬은 입력을 받아 새 값을 만드는 가공 단계 하나이고, 스킬셋은 인덱서에 붙는 스킬들의 묶음입니다. 앞 노트에서 부른 「기술 집합」이 이것이고 문서와 포털에서는 스킬셋이라고 씁니다. 스킬마다 세 가지를 적습니다 — 어느 값을 읽을지(입력), 무엇을 내놓을지(출력), 그리고 어느 단위로 돌지(컨텍스트)입니다. 컨텍스트가 문서 전체면 문서마다 한 번, 문서 안 이미지 하나하나면 이미지마다 한 번 돕니다.

스킬의 실행 순서는 적은 차례가 아니라 입력과 출력의 의존 관계가 정합니다. 임베딩 스킬이 분할 스킬의 출력을 읽으면 분할이 먼저 돌고, 서로 기대지 않는 스킬은 함께 돕니다.

보강 트리

스킬들이 주고받는 값은 문서마다 하나씩 생기는 보강 트리에 쌓입니다. 뿌리가 /document이고, 원본에서 뽑은 텍스트가 /document/content, 문서에서 꺼낸 이미지가 /document/normalized_images/*에 놓입니다. 별표는 「그 배열의 원소마다」라는 뜻입니다. 스킬의 출력은 이 트리에 새 가지로 붙고, 다음 스킬은 그 경로를 입력으로 적습니다.

「색인 필드가 비어 있다」는 증상의 절반이 이 경로 오타입니다. 스킬 출력은 /document/pages/*에 놓였는데 매핑이 /document/chunks/*를 읽으면, 오류 없이 빈 값이 들어갑니다.

과금

분할·병합처럼 텍스트만 다루는 스킬은 따로 돈이 안 들지만, OCR·이미지 분석·언어 분석처럼 AI 서비스를 부르는 스킬은 과금 대상입니다. 이런 스킬을 문서 수가 많은 데 쓰려면 스킬셋에 Foundry 리소스를 연결해 요금을 그쪽으로 받게 해야 합니다. 연결하지 않으면 무료 한도 안에서만 돌고, 한도를 넘으면 인덱서가 그 문서들에서 멈춥니다. 「며칠 동안 잘 돌던 OCR 인덱서가 문서가 늘자 실패한다」는 문항의 답이 여기입니다.

기본 제공 스킬

텍스트 스킬

PII 감지는 RAG에서 자주 묻습니다. 근거 문서에 주민번호나 전화번호가 있으면 모델이 그대로 답에 옮길 수 있으므로, 색인에 넣기 전에 가린 텍스트를 만들어 그쪽을 색인하는 구성이 답입니다.

이미지 스킬

OCR 스킬은 이미지에서 글자를 읽어 텍스트로 내고, 이미지 분석 스킬은 장면을 설명하는 캡션과 태그를 냅니다. 둘 다 이미지 하나를 단위로 돌므로 컨텍스트가 /document/normalized_images/*입니다. 스캔 문서처럼 글자가 그림 안에 있으면 OCR이고, 제품 사진처럼 무엇이 찍혔는지가 중요하면 이미지 분석입니다.

레이아웃 스킬

문서 레이아웃 스킬은 PDF의 제목·문단·표 구조를 읽어 마크다운으로 내고, 절 단위로 나눈 조각도 낼 수 있습니다. 글자 수로 자르는 분할 스킬은 표나 절 한가운데를 자르기 쉬운데, 레이아웃 스킬은 문서 자신의 구조를 따라 자릅니다. 매뉴얼·규정집처럼 절 제목이 뚜렷한 문서라면 이쪽이 조각의 맥락을 더 잘 지킵니다.

사용자 정의 스킬

Web API 스킬

기본 제공 스킬에 없는 가공은 사용자 정의 스킬로 붙입니다. 가장 흔한 꼴이 Web API 스킬로, 인덱서가 우리가 만든 HTTP 엔드포인트(대개 Azure Functions)에 레코드를 묶어 보내고 결과를 받아 트리에 붙입니다. 주고받는 꼴이 정해져 있습니다.

{
  "values": [
    { "recordId": "0", "data": { "text": "반품은 수령 후 14일 이내에 신청합니다." } },
    { "recordId": "1", "data": { "text": "해외 배송 상품은 반품 비용을 고객이 부담합니다." } }
  ]
}

응답도 같은 values 배열이고, 레코드마다 같은 recordId로 data·errors·warnings를 돌려줘야 합니다. 순서가 바뀌어도 되지만 recordId가 빠지거나 바뀌면 인덱서는 결과를 어느 문서에 붙일지 몰라 그 레코드를 실패로 칩니다.

시간 제한과 배치

Web API 스킬에는 세 손잡이가 있습니다. timeout은 한 번 호출을 기다리는 시간(기본 30초)이고, batchSize는 한 번에 묶어 보내는 레코드 수, degreeOfParallelism은 동시에 여는 호출 수입니다. 레코드 1,200개를 batchSize 4로 보내면 호출이 300번이고, 동시 호출 5개에 호출마다 2초가 걸리면 대략 300 ÷ 5 × 2 = 120초입니다. 엔드포인트가 느려 시간 초과가 나면 배치를 줄이거나 시간 제한을 늘리고, 엔드포인트가 429를 내면 동시 호출 수를 줄입니다.

Azure Machine Learning에 배포한 모델을 부르는 스킬도 있습니다. 직접 학습한 분류 모델로 문서에 태그를 달고 싶을 때 씁니다.

수집 흐름

이미지 정규화

스캔 PDF나 이미지가 섞인 원본을 다루려면 먼저 인덱서가 이미지를 꺼내야 합니다. 인덱서 구성의 imageAction을 generateNormalizedImages로 두면 문서 안 이미지를 꺼내 크기와 방향을 맞춘 정규화 이미지를 트리에 둡니다. 이 값을 안 켜면 이미지 경로가 비어 있어 OCR 스킬이 읽을 것이 없습니다.

병합과 분할

RAG 수집 흐름은 대개 이 순서로 섭니다.

1. 인덱서가 텍스트를 뽑고 이미지를 정규화한다.
2. OCR 스킬이 이미지마다 글자를 읽는다.
3. 병합 스킬이 OCR 결과를 원래 텍스트의 그 이미지 자리에 끼워 넣는다.
4. 분할 스킬이 합친 텍스트를 조각으로 자른다.
5. 임베딩 스킬이 조각마다 벡터를 만든다.
6. 조각마다 색인 문서를 만들어 넣는다.

병합이 분할보다 앞에 서는 것이 핵심입니다. 분할을 먼저 하면 그림 속 글자가 조각에 들어가지 못하고 따로 떠돕니다. 아래가 2·3단계의 스킬 정의입니다.

[
  { "@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
    "context": "/document/normalized_images/*",
    "inputs":  [ { "name": "image", "source": "/document/normalized_images/*" } ],
    "outputs": [ { "name": "text", "targetName": "text" } ] },
  { "@odata.type": "#Microsoft.Skills.Text.MergeSkill",
    "context": "/document",
    "inputs": [
      { "name": "text",          "source": "/document/content" },
      { "name": "itemsToInsert", "source": "/document/normalized_images/*/text" },
      { "name": "offsets",       "source": "/document/normalized_images/*/contentOffset" } ],
    "outputs": [ { "name": "mergedText", "targetName": "merged_content" } ] }
]

출력 매핑

보강 트리의 값을 색인 필드로 보내는 것이 출력 필드 매핑입니다. 문서 하나가 색인 문서 하나가 되는 흐름이면 이것으로 충분합니다. 조각마다 색인 문서를 만드는 6단계는 다른 장치가 맡는데, 앞 노트에서 본 인덱스 투영입니다. 투영은 조각의 컨텍스트(/document/pages/*)와 부모 문서를 가리킬 키 필드를 받아, 조각 하나를 색인 문서 하나로 펼칩니다.

지식 저장소

프로젝션 세 갈래

지식 저장소는 보강 결과를 색인이 아니라 Azure Storage에 남기는 곳입니다. 검색이 아니라 분석·감사·다른 시스템 재사용이 목적일 때 씁니다. 무엇을 어떤 꼴로 남길지가 프로젝션이고 세 갈래입니다.

여러 프로젝션을 한 프로젝션 그룹에 묶으면 그 안의 테이블들이 서로 키로 이어지고, 그룹을 나누면 서로 독립된 사본이 됩니다.

인덱스 투영과의 차이

이름이 비슷해 자주 섞어 냅니다. 인덱스 투영은 조각을 검색 색인에 펼치는 것이고, 지식 저장소 프로젝션은 보강 결과를 스토리지에 남기는 것입니다. 「추출한 엔터티를 표로 집계하고 싶다」는 지식 저장소, 「조각 단위로 찾게 하고 싶다」는 인덱스 투영입니다.

오류 처리

실패 허용 한도

인덱서는 기본적으로 문서 하나만 실패해도 실행 전체를 실패로 칩니다. 문서 수만 건 중 몇 건이 깨진 PDF라는 이유로 수집이 서면 곤란하므로, maxFailedItems(실행 전체에서 허용할 실패 수)와 maxFailedItemsPerBatch(배치 하나에서 허용할 실패 수)를 늘립니다. -1이면 무제한입니다. 1,000건 중 12건이 실패했는데 maxFailedItems가 10이면 실행은 실패로 끝나고, 20이면 성공으로 끝나되 12건이 오류 목록에 남습니다.

실행 기록과 디버그 세션

실행마다 성공·실패 수와 오류·경고 목록이 실행 기록에 남습니다. 오류는 그 문서가 색인에 안 들어갔다는 뜻이고, 경고는 들어갔지만 일부가 빠졌다는 뜻입니다 — 텍스트가 너무 길어 잘렸거나 한 스킬이 빈 값을 냈을 때입니다. 경로가 왜 비는지 모를 때는 포털의 디버그 세션으로 문서 하나의 보강 트리를 열어 스킬마다 입력과 출력을 확인하고, 거기서 고친 정의를 스킬셋에 반영합니다.

증분 보강

스킬셋을 고칠 때마다 모든 문서의 OCR과 임베딩을 다시 돌리면 비용이 큽니다. 증분 보강은 스킬 출력을 스토리지의 캐시에 남겨 두고, 스킬셋이 바뀌면 바뀐 스킬과 그 뒤에 매달린 스킬만 다시 돌립니다. 병합 스킬 하나를 고쳤다면 OCR은 캐시에서 다시 쓰고 병합·분할·임베딩만 다시 돕니다.

연습 문제

1. 스캔 PDF를 색인하는 스킬셋에 OCR 스킬을 넣었는데 색인된 내용에 그림 속 글자가 하나도 없습니다. 스킬 정의에는 문제가 없습니다. 먼저 볼 곳은?
   ① 인덱서 구성의 imageAction
   ② 색인의 filterable 속성
   ③ 시맨틱 구성
   ④ 지식 저장소의 객체 프로젝션

   ①. 이미지를 정규화하라는 설정이 없으면 /document/normalized_images/*가 비어 OCR이 읽을 것이 없습니다.
2. OCR → 분할 → 병합 순서로 구성했더니 그림 속 글자가 조각에 안 들어갑니다. 바른 순서는?
   ① OCR → 병합 → 분할 → 임베딩
   ② 분할 → OCR → 병합 → 임베딩
   ③ 임베딩 → OCR → 병합 → 분할
   ④ 병합 → OCR → 분할 → 임베딩

   ①. OCR 결과를 원래 텍스트에 끼워 넣은 뒤에 잘라야 조각에 그림 속 글자가 함께 들어갑니다. 임베딩은 조각이 생긴 뒤에야 만들 수 있습니다.
3. Web API 스킬에 레코드 2,000개를 batchSize 10, degreeOfParallelism 4로 보냅니다. 호출 하나에 3초가 걸리면 대략 얼마나 걸립니까?
   ① 50초
   ② 150초
   ③ 600초
   ④ 1,500초

   ②. 호출 수는 2,000 ÷ 10 = 200번이고, 4개씩 동시에 돌면 200 ÷ 4 = 50차례, 차례마다 3초라 150초입니다.
4. 사용자 정의 스킬의 응답에서 일부 레코드가 실패로 처리됩니다. 엔드포인트 로그에는 정상 처리로 남았습니다. 가장 의심스러운 것은?
   ① 응답에 요청과 같은 recordId를 돌려주지 않았다
   ② timeout이 너무 길다
   ③ 스킬셋에 Foundry 리소스가 연결돼 있다
   ④ 색인에 벡터 필드가 없다

   ①. 인덱서는 recordId로 결과를 문서에 되붙이므로 빠지거나 바뀐 레코드는 실패가 됩니다.
5. 문서 5,000건 중 깨진 파일 30건 때문에 인덱서 실행이 매번 실패합니다. 나머지 문서는 색인돼야 합니다. 알맞은 조치는?
   ① 인덱서를 지우고 새로 만든다
   ② maxFailedItems를 30 이상(또는 -1)으로 둔다
   ③ batchSize를 1로 줄인다
   ④ 증분 보강을 켠다

   ②. 기본값은 실패를 하나도 허용하지 않습니다. 한도를 올리면 실행은 성공으로 끝나고 실패한 30건은 오류 목록에서 따로 다룰 수 있습니다.
6. 문서에서 뽑은 조직 이름과 핵심 구를 Power BI로 집계하려 합니다. 알맞은 구성은?
   ① 인덱스 투영
   ② 지식 저장소의 테이블 프로젝션
   ③ 출력 필드 매핑에 facetable 필드 추가
   ④ 지식 저장소의 파일 프로젝션

   ②. 집계 도구가 읽을 행을 남기는 것은 테이블 프로젝션입니다. ①은 검색 색인에 펼치는 것이고 ④는 이미지 파일을 남깁니다.
7. 분할 길이만 바꿨는데 문서 전체의 OCR이 다시 돌아 비용이 커졌습니다. 다음부터 이를 줄이는 방법은?
   ① maxFailedItemsPerBatch를 늘린다
   ② 증분 보강 캐시를 켠다
   ③ OCR 스킬의 컨텍스트를 /document로 바꾼다
   ④ 지식 저장소를 지운다

   ②. 캐시가 있으면 바뀐 분할 스킬과 그 뒤 스킬만 다시 돌고 OCR 결과는 재사용됩니다.

이 노트의 문항은 대부분 경로와 순서로 풀립니다. 스킬 하나하나의 이름보다, 각 스킬이 트리의 어느 가지를 읽고 어디에 쓰는지를 그림으로 그려 두면 「왜 비었나」·「왜 다시 돌았나」가 한 번에 보입니다.