에이전트 검색에서 문서에 포함된 이미지 표시(프리뷰)

에이전트 검색 중에 이미지 제공(미리 보기)을 사용하여 원본 문서에 포함된 이미지(예: 다이어그램, 차트, 인포그래픽, 스캔된 양식 및 제품 이미지)를 표시하므로 LLM(대규모 언어 모델)은 답변을 합성할 때 텍스트와 함께 시각적 컨텍스트를 추론할 수 있습니다.

이미지 제공을 사용하도록 설정하면 Azure AI 검색는 다음을 수행합니다:

• 인덱싱 시 지원되는 문서에서 이미지를 추출하고 고객이 제공한 Azure Blob 자산 저장소에 저장합니다.

• 쿼리 시 검색 작업 중에 해당 이미지를 가져오고 base64로 인코딩한 다음 합성된 답변을 생성하는 다중 모달 콘텐츠로 LLM 프롬프트에 삽입합니다.

이 문서에서는 기술 자료에서 이미지 서비스를 사용하도록 설정하고, 요청별로 재정의하고, 이미지 서비스 통계를 검사하고, 스토리지 계정 수명 주기 요구 사항을 계획하는 방법을 보여 줍니다.

사용량 지원

사전 요구 사항

• Azure AI 검색 서비스는 LLM을 지정하는 지식 베이스를 포함합니다. 지식 베이스는 답변 합성을 사용해야 합니다.

• 해당 assetStore에 ingestionParameters가 구성된 파일 기반 인덱스 참조 자료 원본입니다. 지원되는 종류:

  • Blob 지식 원본(Azure Blob Storage 또는 Azure Data Lake Storage Gen2)
  • 인덱싱된 OneLake 지식 원본
  • 인덱스된 SharePoint 지식 원본

  표준 추출을 사용하는 Blob 지식 원본의 경우 Blob 지식 원본 필수 구성 요소를 완료합니다.

• 지식 소스는 ingestionPermissionOptions를 구성해서는 안 됩니다.

• PNG 파일, JPEG 파일 또는 포함된 이미지가 있는 PDF와 같이 추출 가능한 이미지가 포함된 원본 문서입니다.

• Foundry Tools의 Azure Content Understanding이 지원하는 지역 내 Microsoft Foundry 리소스로, Azure OpenAI 임베딩 및 다중 모드 채팅 모델이 배포되어 있습니다. https://<resource-name>.services.ai.azure.com 형식의 리소스 엔드포인트를 사용하세요.

• 기술 자료 및 관리되는 기술 원본을 만들거나 업데이트할 수 있는 권한입니다. 이러한 관리 작업을 수행하는 사용자 또는 자동화 ID에 할당된 Search Service 기여자 및 검색 인덱스 데이터 기여자 역할을 사용하여 키 없는 인증을 구성합니다(권장). 또는 관리자 API 키를 사용합니다.

• 검색 작업을 호출할 수 있는 권한입니다. 검색 요청을 보내는 ID에 검색 인덱스 데이터 판독 기 역할을 할당하거나(권장) 쿼리 API 키를 사용합니다.

• 응답 합성 중 LLM으로 아웃바운드 호출을 수행하려면, 검색 서비스에는 LLM을 호스팅하는 Microsoft Foundry 리소스에 대해 Cognitive Services 사용자 권한이 있는 관리 ID가 있어야 합니다.

• 자산 저장소 액세스의 경우 자산 저장소 및 애플리케이션 액세스 구성에 설명된 대로 검색 서비스 관리 ID를 구성합니다.

• 2026-08-01-preview REST API 또는 해당하는 Azure SDK 미리 보기 패키지: .NET | Java | JavaScript | Python

제한 사항 및 고려 사항

• 이미지 제공은 에이전트 검색에서 API를 retrieve 통해서만 사용할 수 있습니다. 클래식 /docs/search 쿼리는 사용자 지정 솔루션 또는 구성 없이 다운스트림 응답 합성에 문서 포함 이미지를 제공하지 않습니다.

• 이미지 제공은 응답 합성 출력 모드에서만 실행됩니다. extractiveData 출력 모드는 이미지 제공을 건너뜁니다.

• 이미지 제공은 assetStore가 구성되어 있고 image_path 값이 채워진 인덱싱된 청크가 있는 파일 기반 인덱싱 지식 원본에만 적용됩니다.

• 혼합 지식 베이스에서는 지원되는 지식 소스 유형(blob, 인덱싱된 OneLake, 인덱싱된 SharePoint)만 후속 답변 합성에 문서에 포함된 이미지를 제공합니다. 다른 유형도 여전히 텍스트 기반화에 기여할 수 있습니다.

• ACL, RBAC 범위 또는 Microsoft Purview 민감도 레이블을 포함한 문서 수준 권한을 수집하기 위해 ingestionPermissionOptions를 사용하는 지식 원본에서는 이미지 제공이 지원되지 않습니다. 자산 저장소는 기본 지식 저장소를 만들고 지식 저장소는 권한 상속을 지원하지 않습니다.

• 검색 응답 스키마는 모델에 전송된 개별 자산 저장소 이미지 경로 또는 이미지 바이트에 대한 필드를 정의하지 않습니다. imageServing 활동 보고서는 검색되어 모델에 전송된 이미지에 대한 집계된 통계를 제공합니다.

• 이미지에 대한 액세스는 인덱싱된 콘텐츠에 대한 액세스와는 별도로 스토리지 계정 수준에서 제어됩니다. 자산 스토리지 계정에 대한 읽기 권한이 있는 모든 ID는 해당 이미지를 가져올 수 있습니다.

• 콘텐츠가 접지 데이터로 반환될 수 있으므로 원본 문서에 비밀(계정 키, 토큰, 연결 문자열)을 저장하지 마세요.

• 이미지 제공은 이미지 다운로드 및 다중 모드 토큰 처리로 인해 응답 합성 대기 시간을 증가시킬 수 있습니다. 이미지 서비스 사용 및 사용 안 함으로 대표 쿼리를 실행하고 응답 대기 시간을 보고된 imageServing 활동과 비교합니다.

• Content Understanding은 PDF 및 DOCX 파일에 대해 다른 이미지 결과를 생성할 수 있습니다. 일관된 포함된 이미지 추출 및 언어화가 필요한 경우 원본 문서를 PDF로 변환하거나 대표 콘텐츠로 각 원본 형식을 테스트합니다.

이미지 서비스 작동 방식

이미지 제공에는 다음 두 단계가 있습니다.

• 인덱싱: 기술 원본에서 표준 콘텐츠 추출 및 자산 저장소를 구성할 때 생성된 Content Understanding 기술은 의미상 문서를 청크하고, 테이블을 Markdown으로 유지하고, 구성된 LLM을 사용하여 포함된 수치를 설명합니다. 그림 설명은 임베딩 기술이 벡터화하는 보강된 Markdown의 일부가 됩니다. 또한 이 스킬은 이미지를 blob 자산 저장소에 추출하고 겹치는 청크에 image_path 참조를 추가합니다.

  자산 저장소를 구성할 때 검색 서비스는 기술 자료와 함께 지식 저장소 를 프로비전하여 추출된 이미지 아티팩트를 유지합니다. 다른 지식 저장소와 마찬가지로 이 지식 저장소를 검사하고 관리할 수 있습니다.

• 검색: 검색 작업이 이미지 서비스를 사용하도록 설정된 상태로 실행되면 검색 서비스는 자산 저장소에서 일치하는 이미지를 가져오고 base64로 인코딩하며 응답 합성 프롬프트에 다중 모달 콘텐츠로 포함합니다.

자산 저장소 및 애플리케이션 액세스 구성

이미지 제공은 세 가지 신뢰 경계에 걸쳐 있습니다. 인덱싱 시 검색 서비스는 이미지 아티팩트를 자산 저장소에 기록합니다. 쿼리 시 검색 서비스는 자산 저장소에서 읽어 이미지를 검색합니다. 또한 애플리케이션은 UI에서 이미지를 렌더링해야 하는 경우 자산 저장소에서 읽습니다. 최소 권한 액세스를 따르도록 각 경로를 구성합니다.

자산 저장소에 대한 검색 서비스 액세스

• 검색 서비스에 Microsoft Entra ID 및 관리 ID 사용합니다. 인덱서가 이미지 아티팩트를 작성하고, 검색 작업이 이를 읽기 때문에, 스토리지 계정 범위에서 해당 ID에 Storage Blob 데이터 기여자 역할을 할당하십시오. 원본 및 자산 컨테이너가 해당 계정을 공유하는 경우 역할은 원본 Blob 읽기 액세스도 제공합니다.

• 자산 저장소 컨테이너에서 익명 공용 액세스를 사용하도록 설정하지 마세요.

이미지 참조에 대한 애플리케이션 액세스

생성된 인덱스는 자산 저장소의 이미지에 대한 참조를 저장 image_path 합니다. 검색 응답 스키마는 모델에 전송된 개별 자산 저장소 이미지 경로 또는 이미지 바이트에 대한 전용 필드를 정의하지 않습니다. 선택 항목 sourceData 은 구조화된 참조 데이터이며 image_path 필요하지 않습니다.

애플리케이션에 인덱싱된 이미지를 표시하려면 다음을 수행합니다.

1. 자산 스토리지 계정 범위에서 애플리케이션의 ID에 Storage Blob 데이터 판독기 역할을 할당합니다.

2. 생성된 인덱스를 쿼리할 수 있도록 애플리케이션 ID에 Search Index Data Reader 역할을 할당하세요.

3. 애플리케이션이 제어하는 쿼리 또는 서비스 엔드포인트를 통해 생성된 인덱스에서 승인된 image_path를 가져옵니다.

4. 참조가 예상 스토리지 계정 및 자산 컨테이너로 확인되는지 확인합니다. Blob 조회 전에 신뢰할 수 없는 경로를 거부합니다.

5. 애플리케이션의 ID를 사용하여 자산 컨테이너에서 결과 Blob 이름을 가져옵니다.

이러한 분리를 통해 검색 API를 호출할 수 있는 사람과 독립적으로 원본 이미지를 볼 수 있는 사용자를 제어할 수 있습니다.

지식 원본에서 자산 저장소 구성

지원되는 인덱싱된 지식 원본의 assetStore에서 ingestionParameters을 구성합니다. 자산 저장소는 사용자가 소유하고 검색 서비스에서 이미지 아티팩트를 기록하는 Blob 컨테이너입니다.

원본 관련 지침은 다음을 참조하세요.

• Blob 데이터 소스 만들기
• 인덱싱된 SharePoint 기술 원본 만들기
• OneLake 기술 자료 만들기

이미지 제공이 활성화된 최소 Blob 지식 소스는 다음과 같습니다.

PUT https://{service-name}.search.windows.net/knowledgesources/my-blob-ks?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "azureBlobParameters": {
    "connectionString": "ResourceId=<storage-resource-id>",
    "containerName": "source-documents",
    "ingestionParameters": {
      "assetStore": {
        "connectionString": "ResourceId=<storage-resource-id>",
        "containerName": "image-assets"
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "https://{foundry-resource}.services.ai.azure.com",
          "deploymentId": "gpt-4o",
          "modelName": "gpt-4o"
        }
      },
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "https://{foundry-resource}.services.ai.azure.com",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large"
        }
      },
      "contentExtractionMode": "standard",
      "aiServices": {
        "uri": "https://{foundry-resource}.services.ai.azure.com"
      }
    }
  }
}

구성 결과

및 assetStoredisableImageVerbalization 인덱서의 chatCompletionModel조합은 인덱서가 저장하는 내용과 쿼리 시 모델이 보는 내용을 결정합니다.

• 자산 저장소 + 음성화(기본값):assetStore 설정, disableImageVerbalizationfalse 그대로 둠, chatCompletionModel 설정. 인덱서는 이미지를 자산 저장소에 보관하고 인덱스에 텍스트 설명을 저장합니다. 검색 활동은 verbalizationUsed을(를) true(으)로 보고할 수 있습니다.

• 에셋 스토어 전용:assetStore 설정, disableImageVerbalizationtrue로 설정, chatCompletionModel 필수 아님. 인덱서는 이미지를 자산 저장소에 유지하지만 텍스트 설명을 생성하지는 않습니다. 검색 활동은 verbalizationUsed을(를) false(으)로 보고할 수 있습니다.

• 자산 저장소 없음, 모델 세트:assetStore 설정 안 됨, chatCompletionModel 설정됨. 텍스트 설명만, 이미지 아티팩트가 없습니다. 이미지 제공은 적용되지 않습니다.

• 자산 저장소 없음, 모델 없음: 이미지 처리가 없습니다.

자산 저장소 구성 확인

계속하기 전에 수집이 완료될 때까지 기다리십시오.

• Azure 포털에서 인덱서 상태를 확인하거나 Get 인덱서 상태(REST API)를 사용합니다.

• 인덱싱된 청크에 채워진 image_path 필드가 있는지 확인합니다. 비어 있는 경우 image_path 인덱서 상태, 기술 자료 자산 저장소 구성, 원본 문서 콘텐츠 및 자산 컨테이너 콘텐츠를 확인합니다.

• 자산 저장소 컨테이너를 검사합니다. 수집 과정에서 인덱서가 기록한 이미지 blob을 확인할 수 있습니다.

지식 베이스에서 이미지 제공 활성화

지식 베이스 정의 내의 지식 원본 참조에서 enableImageServing을(를) true(으)로 설정합니다. 이 설정은 기술 원본을 대상으로 하는 모든 검색 요청에 대한 기본값이 됩니다.

기술 자료 정의는 쿼리 시 응답 합성에 사용되는 LLM도 지정합니다. 이 설정은 색인 생성 중 이미지 언어화를 제어하는​지식 소스의 chatCompletionModel에 설정한 ingestionParameters와는 별개입니다.

기술 자료가 여러 지식 소스를 참조하는 경우, enableImageServing이 구성된 지원되는 파일 기반 인덱스 종류에만 assetStore을 설정하세요. 지원되지 않는 종류(예: 검색 인덱스, 원격 SharePoint 또는 웹)는 여전히 텍스트 접지에 기여하지만 다운스트림 응답 합성에 문서 포함 이미지를 제공하지 않습니다.

PUT https://{service-name}.search.windows.net/knowledgebases/my-kb?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "my-kb",
  "knowledgeSources": [
    {
      "name": "my-blob-ks",
      "enableImageServing": true
    }
  ],
  "outputMode": "answerSynthesis",
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://{foundry-resource}.services.ai.azure.com",
        "deploymentId": "gpt-4o",
        "modelName": "gpt-4o"
      }
    }
  ]
}

이미지 제공 활성화 여부 확인

지식 베이스 엔드포인트에 GET 요청을 보내고 지식 소스 참조에 "enableImageServing": true가 포함되어 있는지 확인합니다.

이미지 서비스로 검색

지식 기반에 대해 가져오기 작업을 호출합니다. 요청별로 지식 베이스 기본값을 재정의하려면 enableImageServing 아래의 일치하는 항목에서 knowledgeSourceParams를 설정하세요.

POST https://{service-name}.search.windows.net/knowledgebases/my-kb/retrieve?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "retrievalReasoningEffort": { "kind": "medium" },
  "outputMode": "answerSynthesis",
  "includeActivity": true,
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What's the wiring configuration shown in the installation guide?" }
      ]
    }
  ],
  "knowledgeSourceParams": [
    {
      "knowledgeSourceName": "my-blob-ks",
      "kind": "azureBlob",
      "enableImageServing": true
    }
  ]
}

검색 시 발생하는 일

일치하는 콘텐츠와 연결된 이미지 참조의 경우 검색 서비스는 자산 저장소에서 해당 이미지를 다운로드하고 base64로 인코딩한 후 다중 모달 콘텐츠로 다운스트림 응답 합성 모델에 전달합니다. activity.imageServing에서 집계된 이미지 제공 통계를 확인합니다. 정확한 응답 셰이프는 기술 자료 검색 - 검색 (REST API)에 대한 참조 설명서를 참조하세요.

가져오기 동작 확인

검색 응답은 다음 이미지 제공 신호를 제공할 수 있습니다.

• includeActivity이(가) activity인 경우, 서비스가 이미지 제공 작업을 기록할 때 true 배열은 지식 원본에 대한 imageServing 활동을 보고합니다.

• imagesSentToModel보다 큰 0 값은 서비스가 다운스트림 응답 합성 모델에 이미지를 제공했다고 보고했음을 의미합니다.

우선 순위 규칙

지식 베이스 정의와 retrieve 요청 둘 다 enableImageServing를 지정하는 경우, retrieve 요청의 값이 우선 적용됩니다. 전체 우선 순위는 다음과 같습니다.

1. 검색 요청의 값 knowledgeSourceParams[].enableImageServing 입니다(설정된 경우).
2. 기술 자료 정의에서 일치하는 기술 원본 참조의 값입니다(설정된 경우).
3. false (기본값).

다음 표에서는 9개의 조합을 요약합니다.

이미지 서비스 통계 검사

이미지 서빙이 실행되면 가져오기 응답에는 imageServing 배열 내 각 지식 소스에 대해 activity 섹션이 포함됩니다. 이 섹션을 사용하여 자산 저장소에서 검색된 이미지를 모델로 보낸 이미지와 비교합니다.

"activity": [
  {
    "type": "azureBlob",
    "knowledgeSourceName": "my-blob-ks",
    "imageServing": {
      "verbalizationUsed": true,
      "imagesRetrieved": 5,
      "imagesSentToModel": 4,
      "totalImageSizeBytes": 248361
    }
  }
]

필드 보고서:

• verbalizationUsed: 검색 활동에 대한 서비스에서 보고한 이미지 언어화 통계입니다.

• imagesRetrieved: 자산 저장소에서 검색된 이미지 수입니다.

• imagesSentToModel: 다운스트림 모델로 전송된 이미지 수입니다.

• totalImageSizeBytes: 모델로 전송된 이미지의 총 크기(바이트)입니다.

imagesSentToModel가 imagesRetrieved보다 크면, 검색된 모든 이미지가 모델에 전송된 것은 아닙니다.

imagesSentToModel 및 verbalizationUsed를 각각 검사합니다. 응답은 true를 verbalizationUsed로 보고하고, 모델에 전송된 하나 이상의 이미지를 함께 보고할 수 있습니다.

엔드-엔드를 제공하는 테스트 이미지

다음 샘플 중 하나를 사용하여 전체 설정을 테스트합니다.

• C# 이미지 제공 샘플
• Python 이미지 제공 샘플

샘플에서는 Blob 지식 소스와 지식 기반을 만들고, 이미지 제공을 사용 안 함으로 설정한 경우와 사용으로 설정한 경우의 검색 요청을 비교하며, 이미지 제공 통계를 확인합니다. 또한 독립적인 와일드카드 인덱스 쿼리를 사용해 image_path를 선택한 후 해당 자산을 다운로드합니다. 샘플은 세미콜론으로 구분된 참조를 하나 선택하거나, 상대 경로와 같은 11.7: 프로젝션 접두사를 제거하거나, 절대 경로를 URL로 디코딩하고 선행 자산 컨테이너 세그먼트를 제거합니다. 이러한 변환은 검색 API를 보장하지 않고 샘플 동작입니다. 선택한 자산은 동일한 이미지가 특정 검색 응답에 기여했다는 증거가 아닙니다.

일반적인 A/B 비교 검사 목록:

• 다이어그램, 차트 또는 스캔한 이미지에서만 답변할 수 있는 질문을 선택합니다.

• 검색 요청을 enableImageServing: false 실행하고 답변을 캡처합니다.

• 동일한 검색 요청을 enableImageServing: true 실행하고 답변, 대기 시간 및 보고된 활동을 비교합니다.

• 응답 차이를 관찰 A/B 신호로 처리하고 이미지가 차이를 유발했다는 증거가 아닙니다. imagesSentToModel보다 큰 0 값은 서비스가 모델에 이미지를 제공했다고 보고했음을 의미합니다.

자원을 정리하세요

지식 소스를 삭제하기 전에 지식 기반을 삭제합니다. 이러한 Azure AI 검색 리소스를 삭제해도 Azure Storage 원본 문서 또는 프로젝팅된 이미지 Blob은 삭제되지 않습니다. 보존된 수집 또는 검색 파이프라인이 아직 필요하지 않은 경우에만 해당 Blob을 별도로 삭제합니다.

Troubleshooting

imageServing의 활동 블록을 첫 번째 진단 도구로 사용하세요. 다음 표에서는 단일 원인을 가정하지 않고 일반적인 증상을 검사합니다.

관련 콘텐츠

• 기술 자료 쿼리
• 인용 기반 응답에 응답 합성 사용
• 지식 원본이란?
• 지식 저장소 개념