Azure Content Understanding 기술을 사용하여 콘텐츠 청크 및 벡터화

이 문서에서는 Azure Content Understanding 기술을 사용하여 다음을 수행합니다.

Azure Content Understanding 기술은 문서당 하나 이상의 청크를 반환합니다. 각 청크에는 Markdown 형식의 콘텐츠, 위치 메타데이터(페이지 번호 및 경계 다각형) 및 추출된 이미지에 대한 선택적 참조가 포함됩니다. chunkingProperties.method를 semantic(으)로 설정하면 청크는 고정된 문자 범위 대신 단락 및 제목 경계를 따릅니다. modelName 및 modelDeployment 설정하면 기술은 Azure OpenAI 채팅 완성 배포를 호출하여 포함된 이미지에 대한 설명을 생성합니다. 그런 다음 스킬은 그 설명들을 청크 콘텐츠에 병합합니다.

이 문서에서는 예시를 위해 샘플 건강 보험 플랜 PDF를 사용합니다. Content Understanding에서 지원하는 형식으로 파일을 노출하는 지원되는 모든 데이터 원본에 대해 동일한 파이프라인을 실행할 수 있습니다.

사전 요구 사항

• 지원되는 모든 지역의 Azure AI 검색 서비스입니다. 이 시나리오에서는 검색 서비스 자체가 지역 제약을 받지 않습니다.

• Azure Content Understanding 기능에서 지원되는 지역에 있는 Microsoft Foundry 리소스입니다. 이미지 설명 및 청킹은 Foundry 리소스의 리전에서 처리됩니다.

• 청구용 기술 세트에 연결된 Microsoft Foundry 리소스. Azure Content Understanding 기술은 Azure Content Understanding 가격 책정 청구됩니다.

• (선택 사항) 이미지 설명을 생성하는 데 사용되는 동일한 Foundry 리소스에서 채팅 완성 모델(예: gpt-4.1)의 Azure OpenAI 배포입니다. AI 기반 이미지 설명을 원하는 경우에만 필요합니다.

• 청크를 벡터화하는 데 text-embedding-3-small에서 사용하는 임베딩 모델(예: )의 Azure OpenAI 배포입니다.

• 인덱싱할 파일이 있는 Azure Blob Storage 컨테이너입니다. 이 문서에서는 인덱서 설정과 함께 allowSkillsetToReadFileData Blob 데이터 원본을 사용합니다(Content Understanding 기술에 파일 콘텐츠를 전달하는 데 사용됨).

개요

이 문서에서는 일대다 인덱싱 파이프라인을 구축합니다. 각 원본 문서는 여러 검색 문서를 생성합니다(청크당 하나).

1. 인덱서는 Azure Blob Storage의 각 파일을 읽고 /document/file_data를 통해 이진 콘텐츠를 기술 집합에 전달합니다.

2. Azure Content Understanding 기능은 의미론적 청킹(미리 보기)을 사용하여 text_sections을 생성합니다. modelDeployment 및 modelName이 설정되면, 삽입된 이미지에 대한 AI 생성 설명(미리 보기)도 생성하여 각 청크의 Markdown에 인라인으로 삽입합니다.

3. Azure OpenAI 포함 기술 청크당 한 번씩 실행되며 청크 콘텐츠에 대한 벡터를 생성합니다.

4. 인덱스 프로젝션은 청크당 하나의 검색 문서를 대상 인덱스에 쓰고, 콘텐츠, 페이지 메타데이터, 이미지 참조 및 벡터를 필드에 매핑합니다.

5. (선택 사항) 지식 저장소는 클라이언트 앱이 URL을 통해 추출된 이미지를 가져올 수 있도록 normalized_images를 Azure Blob Storage에 프로젝션합니다.

데이터 파일 준비

Azure Content Understanding 기술은 각 문서의 이진 콘텐츠를 처리하므로 소스 파일은 기술이 지원하는 형식이어야 합니다. 현재 목록은 Content Understanding 서비스 제한을 참조하세요. 지원되는 일반적인 형식에는 PDF, DOCX, XLSX, PPTX 및 많은 이미지 형식이 포함됩니다.

지원되는 데이터 원본에 파일을 업로드합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 데이터 원본을 만들 수 있습니다.

다음 최소 요청은 이 연습 전체에서 사용되는 데이터 원본을 만듭니다.

POST {endpoint}/datasources?api-version=2026-08-01-preview

{
  "name": "my_blob_datasource",
  "type": "azureblob",
  "credentials": {
    "connectionString": "<your-blob-connection-string>"
  },
  "container": {
    "name": "my-container"
  }
}

일대다 인덱싱을 위한 인덱스 만들기

각 검색 문서는 Content Understanding 기술에서 생성된 하나의 청크에 해당합니다. 인덱스 요구 사항:

• 키 필드(chunk_id)입니다.
• 청크가 어떤 소스 문서에서 추출되었는지 식별하는 부모 필드입니다(parent_id).
• 청크 콘텐츠, 페이지 메타데이터 및 이미지 참조를 저장하는 필드입니다.
• 청크 임베딩용 벡터 필드입니다.

다음 인덱스 정의는 다음 섹션에서 만든 기술 세트와 일치합니다.

{
  "name": "my_content_understanding_index",
  "fields": [
    {
      "name": "chunk_id",
      "type": "Edm.String",
      "key": true,
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false,
      "analyzer": "keyword"
    },
    {
      "name": "parent_id",
      "type": "Edm.String",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "title",
      "type": "Edm.String",
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "chunk",
      "type": "Edm.String",
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "page_number_from",
      "type": "Edm.Int32",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false
    },
    {
      "name": "page_number_to",
      "type": "Edm.Int32",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false
    },
    {
      "name": "image_path",
      "type": "Edm.String",
      "searchable": false,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "text_vector",
      "type": "Collection(Edm.Single)",
      "searchable": true,
      "retrievable": true,
      "stored": false,
      "dimensions": 1536,
      "vectorSearchProfile": "profile"
    }
  ],
  "vectorSearch": {
    "profiles": [
      {
        "name": "profile",
        "algorithm": "algorithm"
      }
    ],
    "algorithms": [
      {
        "name": "algorithm",
        "kind": "hnsw"
      }
    ]
  }
}

의미 체계 청크(미리 보기) 및 벡터화를 위한 기술 세트 정의

대상 인덱스를 사용하여 청크, 벡터 및 이를 공급하는 프로젝션 매핑을 생성하는 기술 세트를 정의합니다.

기술 세트에는 다음 두 가지 기술이 있습니다.

• Azure Content Understanding 스킬은 각 문서를 청크로 나눕니다. chunkingProperties.method를 semantic로 설정하면 스킬이 단락 및 제목 경계를 준수합니다. modelDeployment 및 modelName을 설정하면 AI 생성 이미지 설명(미리 보기)을 사용할 수 있으며, 해당 스킬은 벡터화 전에 이 설명을 청크 콘텐츠에 인라인합니다. 지원되는 채팅 완료 모델 및 기타 매개 변수 세부 정보 목록은 기술 매개 변수를 참조하세요.

• Azure OpenAI 포함 기술 각 청크의 콘텐츠에 대한 벡터를 생성합니다.

기술 세트는 indexProjections를 사용하여 각 청크를 별도의 검색 문서에 매핑합니다. 자세한 내용은 인덱스 프로젝션 정의를 참조하세요.

요청을 보내기 전에 <subdomain>를 Azure OpenAI 하위 도메인으로, <Azure OpenAI api key>를 embedding-resource 키로, <Foundry resource key>를 기술 세트에 연결된 Foundry 리소스의 키로 바꿉니다.

POST {endpoint}/skillsets?api-version=2026-08-01-preview

{
  "name": "my_content_understanding_skillset",
  "description": "Semantic chunking, image descriptions, and vectorization with the Azure Content Understanding skill",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Util.ContentUnderstandingSkill",
      "name": "my_content_understanding_skill",
      "context": "/document",
      "modelName": "gpt-4.1",
      "modelDeployment": "my-gpt-4-1-deployment",
      "chunkingProperties": {
        "method": "semantic",
        "unit": "tokens",
        "maximumLength": 500
      },
      "extractionOptions": ["images", "locationMetadata"],
      "inputs": [
        {
          "name": "file_data",
          "source": "/document/file_data"
        }
      ],
      "outputs": [
        {
          "name": "text_sections",
          "targetName": "text_sections"
        },
        {
          "name": "normalized_images",
          "targetName": "normalized_images"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
      "name": "my_azure_openai_embedding_skill",
      "context": "/document/text_sections/*",
      "inputs": [
        {
          "name": "text",
          "source": "/document/text_sections/*/content"
        }
      ],
      "outputs": [
        {
          "name": "embedding",
          "targetName": "text_vector"
        }
      ],
      "resourceUri": "https://<subdomain>.openai.azure.com",
      "deploymentId": "text-embedding-3-small",
      "modelName": "text-embedding-3-small",
      "apiKey": "<Azure OpenAI api key>"
    }
  ],
  "cognitiveServices": {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "key": "<Foundry resource key>"
  },
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "my_content_understanding_index",
        "parentKeyFieldName": "parent_id",
        "sourceContext": "/document/text_sections/*",
        "mappings": [
          {
            "name": "chunk",
            "source": "/document/text_sections/*/content"
          },
          {
            "name": "text_vector",
            "source": "/document/text_sections/*/text_vector"
          },
          {
            "name": "page_number_from",
            "source": "/document/text_sections/*/locationMetadata/pageNumberFrom"
          },
          {
            "name": "page_number_to",
            "source": "/document/text_sections/*/locationMetadata/pageNumberTo"
          },
          {
            "name": "image_path",
            "source": "/document/text_sections/*/imagePath"
          },
          {
            "name": "title",
            "source": "/document/metadata_storage_name"
          }
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

Content Understanding 기술에 대한 전체 매개 변수 참조, 지원되는 값 및 유효성 검사 규칙은 Azure Content Understanding 기술 참조하세요.

인덱서 구성 및 실행

데이터 원본에서 읽고 기술 집합을 호출하며 청크를 인덱스에 투영하는 인덱서를 만들고 실행합니다. allowSkillsetToReadFileData을(를) true로 설정하여 Content Understanding 기술이 파일 콘텐츠를 수신하도록 하고, parsingMode을(를) default로 설정합니다.

이 시나리오에서는 outputFieldMappings이 필요하지 않습니다. 스킬셋의 indexProjections 블록은 이미 각 청크를 대상 인덱스 필드에 매핑하고 있습니다.

POST {endpoint}/indexers?api-version=2026-08-01-preview

{
  "name": "my_content_understanding_indexer",
  "dataSourceName": "my_blob_datasource",
  "targetIndexName": "my_content_understanding_index",
  "skillsetName": "my_content_understanding_skillset",
  "parameters": {
    "batchSize": 1,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "default",
      "allowSkillsetToReadFileData": true
    }
  },
  "fieldMappings": [],
  "outputFieldMappings": []
}

인덱서가 실행되면 Content Understanding 기술은 의미 체계 청크(미리 보기)를 사용하고, 필요에 따라 AI 기반 이미지 설명(미리 보기)을 생성하고, 청크당 하나의 검색 문서를 인덱스에 씁니다.

인덱서 상태 확인

쿼리하기 전에 인덱서 실행이 완료된 것을 확인합니다.

GET {endpoint}/indexers/my_content_understanding_indexer/status?api-version=2026-08-01-preview

lastResult.status이(가) success인지 확인합니다. transientFailure이고 itemsProcessed이 0보다 높다면 실행은 부분 성공으로 간주되며, 채워진 청크를 계속 쿼리할 수 있습니다. 자세한 내용은 인덱서 상태 모니터링을 참조하세요.

결과 확인

인덱스를 쿼리하여 청크에 예상 콘텐츠가 포함되고 해당 벡터 검색이 예상대로 작동하는지 확인합니다. 검색 탐색기 또는 HTTP 요청을 보내는 도구를 사용합니다.

다음 요청은 하이브리드 쿼리(chunk에 대한 키워드 검색 및 text_vector에 대한 벡터 쿼리)를 실행하여 청크로 분할된 텍스트와 임베딩이 모두 채워져 있는지 확인합니다.

POST /indexes/my_content_understanding_index/docs/search?api-version=2026-08-01-preview
{
  "search": "copay for in-network providers",
  "count": true,
  "searchMode": "all",
  "vectorQueries": [
    {
      "kind": "text",
      "text": "copay for in-network providers",
      "fields": "text_vector"
    }
  ],
  "select": "chunk, title, page_number_from, page_number_to, image_path"
}

성공적인 응답은 다음과 유사합니다(간결성을 위해 트리밍됨).

{
  "@odata.count": 2,
  "value": [
    {
      "@search.score": 0.0317,
      "chunk": "## Cost sharing\n\nFor in-network providers, the copay is $20 per visit...\n\n![Chart: Copay comparison across plans](figures/3)",
      "title": "Northwind_Standard_Benefits_Details.pdf",
      "page_number_from": 4,
      "page_number_to": 4,
      "image_path": "figures/3"
    },
    {
      "@search.score": 0.0289,
      "chunk": "### Out-of-network providers\n\nWhen you visit a provider that isn't in the Northwind network, the copay is $40 per visit...",
      "title": "Northwind_Standard_Benefits_Details.pdf",
      "page_number_from": 5,
      "page_number_to": 6,
      "image_path": null
    }
  ]
}

응답에는 다음이 포함됩니다.

• chunk: 각 청크의 Markdown 콘텐츠입니다. modelName 및 modelDeployment을 구성하면 AI 생성 이미지 설명(미리 보기)이 Markdown 내에서 인라인으로 표시됩니다.
• page_number_from 및 page_number_to: 청크를 생성한 페이지 범위입니다.
• image_path: 청크를 사용하여 추출된 이미지의 경로이거나 청크가 여러 이미지에 걸쳐 있을 때 세미콜론으로 구분된 경로 목록입니다. 정확한 모양은 지식 저장소 파일 프로젝션이 구성되었는지 여부에 따라 달라집니다. 파일 프로젝션이 없으면 경로는 예제(figures/3)에 표시된 짧은 형식입니다. 파일 프로젝션을 사용하면 경로는 지식 저장소에 있는 이미지의 상대 경로입니다. 클라이언트 앱에서 이러한 이미지를 사용할 수 있도록 하려면 검색을 위해 (선택 사항) Project 이미지를 참조하세요.

(선택 사항) 검색용 프로젝트 이미지

인덱스에 저장된 image_path 값은 직접 액세스할 수 있는 URL이 아니라 스킬의 보강 트리 내 포인터입니다. 이미지를 검색하려면 지식 저장소를 사용해 normalized_images를 Azure Blob Storage로 프로젝션한 다음, 각 청크와 함께 blob URL을 생성합니다.

이 단계는 선택 사항입니다. 클라이언트 앱에서 추출된 이미지를 표시하거나 다운로드해야 하는 경우에만 추가합니다.

이전 섹션의 기술 세트 페이로드에 다음 속성을 추가합니다. 기술 세트 요청은 api-version=2026-08-01-preview를 사용합니다.

"knowledgeStore": {
  "storageConnectionString": "<your-azure-storage-connection-string>",
  "projections": [
    {
      "files": [
        {
          "storageContainer": "extracted-images",
          "source": "/document/normalized_images/*"
        }
      ],
      "tables": [],
      "objects": []
    }
  ]
}

인덱서가 실행된 후 extracted-images 컨테이너의 각 blob은 하나의 normalized_images 요소에 대응합니다. Blob URL은 https://<storage-account>.blob.core.windows.net/<container>/<imagePath> 형식이며, <imagePath>은 image_path 필드에 저장된 값과 일치합니다.

추가 프로젝션 형식( 및 ) 및 인증 옵션을 포함한 전체 스키마는 Azure AI 검색Knowledge 저장소 "프로젝션"을 참조하세요>.

자원을 정리하세요

완료되면 Content Understanding 및 Azure OpenAI 요금이 더 이상 발생하지 않도록 인덱서, 기술 세트 및 인덱스를 삭제하세요. Azure Blob Storage 원본 파일과 Foundry 리소스 자체는 삭제할 때까지 유지됩니다.

Troubleshooting

인덱서가 실패하거나 예기치 않은 결과를 반환하는 경우 다음과 같은 일반적인 원인을 확인합니다.

스킬셋 유효성 검사에 400 오류가 발생함

매개 변수 조합이 400 Skill validation failed 충돌하면 기술이 오류를 반환합니다. 일반적인 원인:

• modelName 없이 modelDeployment가 설정되었거나, 그 반대의 경우입니다. 둘 다 함께 설정해야 합니다.
• method가 semantic (미리 보기)이고 overlapLength가 0보다 큽니다. overlapLength을(를) 0로 설정하거나 생략합니다.
• method 및 unit은(는) 지원되는 조합이 아닙니다. fixedSize와 함께 characters 또는 semantic와 함께 tokens를 사용합니다.

Foundry 리소스에 대한 권한 부여 실패

Foundry 리소스를 호출할 때 기술이 401 또는 403을 반환하는 경우 다음을 확인합니다.

• 기술 세트의 cognitiveServices 블록은 올바른 Foundry 리소스를 가리킵니다.
• 검색 서비스에서 사용하는 ID에는 Foundry 리소스에 필요한 역할이 있습니다. 관리 ID 구성의 경우 Azure AI 검색에서 기술 세트에 청구 가능 리소스 연결을 참조하세요.

text_sections 비어 있음

인덱싱된 문서에 청크가 없는 경우 다음을 확인하세요:

• 파일 형식이 지원됩니다. 목록은 지원되는 파일 형식을 참조하세요.
• Foundry 리소스는 지원되는 지역에 있습니다.
• 암호로 보호된 PDF는 인덱싱하기 전에 잠금 해제됩니다.

이미지 설명(미리 보기)이 없습니다.

청크에 인라인 이미지 설명이 포함되지 않은 경우 다음을 확인합니다.

• modelName 및 modelDeployment는 기술 집합에 설정됩니다.
• modelName의 채팅 완성 모델은 기술 집합에서 참조하는 동일한 Foundry 리소스에 배포됩니다.
• 배포에는 문서 볼륨에 대한 충분한 TPM 또는 RPM 할당량이 있습니다.

대용량 문서에서 인덱서 시간 초과 발생

Content Understanding은 문서별 처리 시간 제한을 적용합니다. 큰 PDF가 실패하는 경우:

• 인덱싱하기 전에 원본 문서를 더 작은 파일로 분할합니다.
• 각 문서가 독립적으로 처리되도록 batchSize을 1로 줄이세요.

Azure Content Understanding 기술의 전체 데이터 제한은 데이터 제한 참조하세요.

관련 콘텐츠

• Azure Content Understanding 스킬
• Azure OpenAI 포함 기술
• Azure AI 검색의 멀티모달 검색
• 부모-자식 인덱싱에 대한 인덱스 프로젝션 정의
• RAG 및 벡터 검색을 위한 대용량 문서 청크