Azure Blob Storage 또는 ADLS Gen2에서 Blob 지식 원본 만들기

참고

Foundry IQ (Azure AI 검색)는 관리형 검색을 위한 상위 수준의 지식 원본 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.

Important

이 문서에서 (미리 보기)로 표시된 기능 또는 성능은 공개 미리 보기로 제공되며 Microsoft Azure 미리 보기에 대한 추가 사용 약관의 적용을 받습니다.

Foundry IQ(Azure AI 검색) 관련 미리 보기 약관은 미리 보기 기능을 참조하세요.

Blob 지식 원본은 Azure Blob Storage 또는 ADLS Gen2 콘텐츠를 foundry IQ(Azure AI 검색)의 에이전트 검색 파이프라인으로 수집합니다. 기술 원본은 독립적으로 생성되고, 기술 자료에서 참조되며, 런타임에 기술 자료를 쿼리할 때 접지 데이터로 사용됩니다.

Blob 지식 원본을 만들 때 외부 데이터 원본, 모델 및 속성을 지정하여 다음 Foundry IQ 개체를 자동으로 생성합니다.

  • Blob 컨테이너를 나타내는 데이터 원본입니다.
  • 컨테이너에서 다중 모달 콘텐츠를 청크하고 필요에 따라 벡터화하는 기술 세트입니다.
  • 보강된 콘텐츠를 저장하고 에이전트 검색 조건을 충족하는 인덱스입니다.
  • 이전 개체를 사용하여 인덱싱 및 보강 파이프라인을 구동하는 인덱서입니다.

생성된 인덱서는 필수 구성 요소, 지원되는 문서 형식 및 제한이 Blob 지식 원본에도 적용되는 Blob 인덱서를 준수합니다. 자세한 내용은 Blob 인덱서 설명서 및 인덱서 제한을 참조하세요. 생성된 기술 세트가 외부 서비스를 호출하는 경우 해당 기술의 입력 및 서비스 제한도 적용됩니다.

사용량 지원

Azure 포털 Microsoft Foundry 포털 .NET SDK Python SDK Java SDK JavaScript SDK REST API
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

필수 구성 요소

  • 에이전트형 검색을 제공하는 모든 지역의 Foundry IQ 서비스

  • Azure Blob Storage 또는 ADLS(Azure Data Lake Storage) Gen2 계정입니다.

  • 텍스트 콘텐츠에 대해 지원되는 콘텐츠 형식이 있는 Blob 컨테이너입니다. 선택적 이미지 언어화의 경우 지원되는 콘텐츠 유형은 채팅 완성 모델이 이미지 파일을 분석하고 설명할 수 있는지 여부에 따라 달라집니다.

  • contentExtractionMode이 standard인 경우, https://<resource-name>.services.ai.azure.com 엔드포인트가 있는 Foundry Tools의 Content Understanding에서 지원되는 지역의 Microsoft Foundry 리소스를 사용합니다. 리소스에는 포함 모델 배포가 있어야 하며 이미지 언어화를 사용하도록 설정하는 경우 다중 모드 채팅 모델 배포가 있어야 합니다.

  • 지식 원본을 만들 수 있는 권한입니다. 사용자 계정에 할당된 Search Service 기여자 및 검색 인덱스 데이터 기여자 역할을 사용하여 키 없는 인증을 구성하거나 관리자 API 키를 사용합니다.

  • 원본 스토리지 계정 범위에서 Storage Blob Data Reader 역할과 Microsoft Foundry 리소스에서 Cognitive Services User 역할이 부여된 Foundry IQ 서비스용 관리 ID입니다. 다른 스토리지 계정에서 자산 저장소를 구성하는 경우 해당 스토리지 계정 범위에서 Storage Blob 데이터 기여자 도 할당합니다. 원본 및 자산 컨테이너가 계정을 공유하는 경우 Storage Blob 데이터 기여자는 원본 읽기 액세스 및 자산 저장소 읽기/쓰기 액세스를 모두 제공합니다.

    • Azure OpenAI 포함 또는 채팅 배포에 대한 관리 ID 호출의 경우 Azure OpenAI 또는 일치하는 resourceUri부모 Foundry 리소스의 선택한 ID에 Cognitive Services OpenAI 사용자를 할당합니다. 추출 서비스 권한은 별개입니다. 역할 할당하기를 참조하세요.
  • networkAccessMode을 private(으)로 설정하면 다음 요구 사항을 충족하세요.

    • S2, S3, L1 또는 L2 Foundry IQ 서비스를 사용합니다. 구성 및 계층 자격 요건은 정식 공유 프라이빗 링크 지원 매트릭스를 확인하세요.

    • Foundry IQ 서비스에서 시스템 할당 또는 사용자 할당 관리 ID를 사용하도록 설정하고, 스토리지 계정에 스토리지 Blob 데이터 판독기 역할을 부여하고, 연결 문자열 사용합니다 ResourceId=/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account> . 사용자 할당 ID의 경우 ingestionParameters.identity도 설정합니다.

    • 지원되는 리소스 유형에 나열된 스토리지 링크를 만들고 승인합니다. ADLS Gen2의 경우 dfs 링크와 blob 링크가 모두 필요합니다.

    • 구성에서 사용 중인 각 보호된 모델, 추출, 보강 또는 자산 스토리지 종속성에 대한 링크를 생성하고 승인합니다. 각 대상 및 그룹 ID에 대해 지원되는 리소스 유형을 따르세요.

  • 필수 Azure.Search.Documents 패키지:

    • 2026-08-01-preview 기능의 경우, 최신 미리 보기 패키지: dotnet add package Azure.Search.Documents --prerelease

    • 2026-10-01의 경우 최신 안정 패키지: dotnet add package Azure.Search.Documents

  • 키 없는 인증의 경우 패키지:Azure.Identitydotnet add package Azure.Identity

  • 필수 azure-search-documents 패키지:

    • 2026-08-01-preview 기능의 경우, 최신 미리 보기 패키지: pip install --pre azure-search-documents

    • 2026-10-01의 경우 최신 안정 패키지: pip install azure-search-documents

  • 키 없는 인증의 경우 패키지:azure-identitypip install azure-identity

  • 필수 Search Service REST API 버전:

  • 키 없는 인증의 경우 각 HTTP 요청의 헤더에 Microsoft Entra ID 토큰을 Authorization 포함합니다.

권한 수집의 경우 2026-10-01에 표시된 대로 REST 를 사용합니다. 안정적인 2026-04-01 SDK 예제는 권한 수집을 구성하지 않습니다. 패키지 변경 로그에서 필요한 API 버전 및 속성을 지원하는지 확인합니다.

REST 예제는 최신 미리 보기 API인 2026-11-01-preview를 사용합니다. 미리 보기 SDK 예제는 문서화된 2026-08-01-preview 계약을 유지합니다. 최신 API 버전을 대상으로 지정하기 전에 패키지 변경 로그를 확인합니다.

기존 지식 원본 확인

기술 자료는 재사용 가능한 최상위 개체입니다. 기존 지식 원본에 대해 아는 것은 새 개체를 다시 사용하거나 이름을 지정하는 데 유용합니다.

다음 코드를 실행하여 이름 및 형식별로 기술 자료를 나열합니다.

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

참조:SearchIndexClient

# List knowledge sources by name and type
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

for ks in index_client.list_knowledge_sources():
    print(f"  - {ks.name} ({ks.kind})")

참조:SearchIndexClient

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}

참조:지식 소스 - 목록

이름으로 단일 기술 원본을 반환하여 JSON 정의를 검토할 수도 있습니다.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

참조:SearchIndexClient

# Get a knowledge source definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

ks = index_client.get_knowledge_source("knowledge_source_name")
print(json.dumps(ks.as_dict(), indent = 2))

참조:SearchIndexClient

### Get a knowledge source definition
GET {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
Authorization: Bearer {{token}}

참조:기술 자료 - 가져오기

다음 응답은 민감한 값을 숨기고 createdResources 아래에 생성된 개체를 나열합니다. 다시 사용하여 다른 지식 원본을 만들기 전에 대상 자격 증명을 제공하거나 지원되는 관리 ID를 구성한 후, 수정된 값은 자격 증명이 아닙니다.

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "A sample blob knowledge source.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<REDACTED>",
    "containerName": "blobcontainer",
    "folderPath": null,
    "isADLSGen2": false,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "standard",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large",
          "authIdentity": null
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<aoai-endpoint>",
          "deploymentId": "gpt-5-mini",
          "modelName": "gpt-5-mini",
          "authIdentity": null
        }
      },
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": {
        "uri": "<aoai-endpoint>"
      }
    },
    "createdResources": {
      "datasource": "my-blob-ks-datasource",
      "indexer": "my-blob-ks-indexer",
      "skillset": "my-blob-ks-skillset",
      "index": "my-blob-ks-index"
    }
  }
}

기술 자료 만들기

다음 코드를 실행하여 Blob 기술 자료를 만듭니다.

// Create a blob knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());

var chatCompletionParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiGptDeployment,
    ModelName = aoaiGptModel
};

var embeddingParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiEmbeddingDeployment,
    ModelName = aoaiEmbeddingModel
};

var ingestionParams = new KnowledgeSourceIngestionParameters
{
    NetworkAccessMode = KnowledgeSourceNetworkAccessMode.Public,
    DisableImageVerbalization = false,
    ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: chatCompletionParams),
    EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
    {
        AzureOpenAIParameters = embeddingParams
    },
    IngestionPermissionOptions = new List<KnowledgeSourceIngestionPermissionOption>
    {
        KnowledgeSourceIngestionPermissionOption.RbacScope
    }
};

var blobParams = new AzureBlobKnowledgeSourceParameters(
    connectionString: connectionString,
    containerName: containerName
)
{
    IsAdlsGen2 = false,
    IngestionParameters = ingestionParams
};

var knowledgeSource = new AzureBlobKnowledgeSource(
    name: "my-blob-ks",
    azureBlobParameters: blobParams
)
{
    Description = "This knowledge source pulls from a blob storage container."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

참조:SearchIndexClient, AzureBlobKnowledgeSource

# Create a blob knowledge source
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import AzureBlobKnowledgeSource, AzureBlobKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceAzureOpenAIVectorizer, KnowledgeSourceContentExtractionMode, KnowledgeSourceIngestionParameters
from azure.search.documents.knowledgebases.models import KnowledgeSourceNetworkAccessMode

index_client = SearchIndexClient(endpoint = "<search-endpoint>", credential = DefaultAzureCredential())

knowledge_source = AzureBlobKnowledgeSource(
    name = "my-blob-ks",
    description = "This knowledge source pulls from a blob storage container.",
    encryption_key = None,
    azure_blob_parameters = AzureBlobKnowledgeSourceParameters(
        connection_string = "blob_connection_string",
        container_name = "blob_container_name",
        folder_path = None,
        is_adls_gen2 = False,
        ingestion_parameters = KnowledgeSourceIngestionParameters(
            network_access_mode = KnowledgeSourceNetworkAccessMode.PUBLIC,
            identity = None,
            disable_image_verbalization = False,
            chat_completion_model = KnowledgeBaseAzureOpenAIModel(
                azure_open_ai_parameters = AzureOpenAIVectorizerParameters(
                    resource_url = "<aoai-endpoint>",
                    deployment_name = "<aoai-gpt-deployment>",
                    model_name = "<aoai-gpt-model>",
                )
            ),
            embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
                azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
                    resource_url = "<aoai-endpoint>",
                    deployment_name = "<aoai-embedding-deployment>",
                    model_name = "<aoai-embedding-model>",
                )
            ),
            content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
            ingestion_schedule = None,
            ingestion_permission_options = ["rbacScope"]
        )
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

참조:SearchIndexClient

### Create a blob knowledge source
PUT {{search-endpoint}}/knowledgesources/my-blob-ks?api-version=2026-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "This knowledge source pulls from a blob storage container.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "ResourceId=<storage-resource-id>",
    "containerName": "<blob-container-name>",
    "folderPath": null,
    "isADLSGen2": false,
    "ingestionParameters": {
        "networkAccessMode": "public",
        "identity": null,
        "disableImageVerbalization": null,
        "chatCompletionModel": {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{aoai-endpoint}}",
                "deploymentId": "{{aoai-gpt-deployment}}",
                "modelName": "{{aoai-gpt-model}}"
            }
        },
        "embeddingModel": {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{aoai-endpoint}}",
                "deploymentId": "{{aoai-embedding-deployment}}",
                "modelName": "{{aoai-embedding-model}}"
            }
        },
        "contentExtractionMode": "minimal",
        "ingestionSchedule": null,
        "ingestionPermissionOptions": ["rbacScope"]
    }
  }
}

참조:지식 소스 - 만들기 또는 업데이트

수집 일정 구성

ingestionParameters.ingestionSchedule를 설정하여 생성된 인덱서가 원본 변경 내용을 폴링하는 빈도를 제어합니다. 적격 미완성 수집은 다음 폴링을 기다리지 않고 실행 시간 제한으로 중지된 후 자동으로 계속될 수 있습니다.

표준 추출 설정

앞의 예제에서 minimal 추출 대신 레이아웃 추출 및 의미 체계 청크에 Content Understanding을 사용하려면 standard을 contentExtractionMode로 설정하고 Foundry 리소스 엔드포인트로 aiServices을 구성합니다. 필수 구성 요소에 설명된 리소스 및 배포를 사용합니다.

표준 추출은 Content Understanding 요금을 발생시키고 이미지 구두화를 사용하도록 설정하면 모델 사용 요금이 부과됩니다. 자세한 내용은 청구 및 이미지 설명 컨트롤을 참조하세요.

프라이빗 네트워크로 수집 제한

안정 버전 2026-10-01 API에서 networkAccessMode는 Blob 지식 원본에 대해 생성된 인덱서가 실행되는 네트워크 환경을 제어합니다. 이 설정은 수집에만 영향을 미치며 기술 자료 검색 요청 또는 응답을 변경하지 않습니다. 적합한 구성에 대한 공유 프라이빗 링크 지원 매트릭스 를 확인합니다. 자동 언어별 분석기 및 이미지 제공과 같은 독립적인 미리 보기 기능은 자체 API 요구 사항을 유지합니다.

networkAccessMode 기본값은 public기존 공용 네트워크 동작을 유지하는 입니다. 이 경우 networkAccessModeprivate생성된 인덱서는 프라이빗 실행 환경에서 실행됩니다. 승인된 공유 프라이빗 링크를 사용하여 Azure Blob Storage 또는 ADLS Gen2 원본 연결에 액세스하고 Azure OpenAI 모델 및 Microsoft Foundry 리소스와 같은 지원되는 Azure 종속성에 액세스합니다.

프라이빗 네트워크 액세스를 구성하고 확인하려면 다음을 수행합니다.

  1. 프라이빗 네트워크 필수 구성 요소를 완료합니다.

  2. 지식 소스 생성 요청에서 private을(를) networkAccessMode(으)로 설정합니다. 안정적인 2026-10-01 API를 포함하여 만드는 동안에만 이 속성을 설정할 수 있습니다. 저장 모드를 나중에 변경하려면 지식 원본을 삭제하고 다시 만듭니다. 적격 Blob, ADLS Gen2 및 Azure SQL 원본은 대신 임시로 생성된 인덱서 네트워킹 재정의를 사용할 수 있습니다. 이 예외는 인덱싱된 SharePoint 또는 다른 원본 종류에는 적용되지 않습니다.

    서비스 계층 또는 런타임이 프라이빗 실행을 지원하지 않거나 필요한 공유 프라이빗 링크가 없는 경우 생성이 실패할 수 있습니다. 서버리스 및 S3 HD는 프라이빗 실행을 지원하지 않습니다. 네트워크 보안 경계 구성은 프라이빗 실행이 아니라 지원되는 퍼블릭 엔드포인트 액세스를 제어합니다.

  3. 생성된 인덱서가 parameters.configuration.executionEnvironment .인지 private확인합니다.

  4. 필요한 각 공유 프라이빗 링크가 승인되고 프로비전되었으며 올바른 종속성을 대상으로 하는지 확인합니다. 만들기에 성공해도 링크 승인 또는 대상 지정은 확인되지 않습니다. 포털 검사에서 구독 간 리소스를 확인할 수 없는 경우 대상 리소스 및 Foundry IQ 서비스에 대한 승인 및 준비 상태를 수동으로 확인합니다.

  5. lastSynchronizationState.endTime에 값이 있을 때까지 지식 소스 상태를 폴링합니다. itemsUpdatesFailed이(가) 0인지 확인한 다음, 커넥터별 원본 콘텐츠를 확인합니다. 종속성에 연결할 수 없는 경우 동기화가 실패합니다.

언어별 자동 분석기 사용(미리 보기)

2026-08-01-preview API 버전부터 Blob, 인덱싱된 OneLake 및 인덱싱된 SharePoint 기술 원본에 대해 언어별 자동 분석기를 사용할 수 있습니다. 사용하도록 설정하면 Foundry IQ(Azure AI 검색)가 각 원본 문서의 언어를 검색하고 일치하는 Microsoft 언어 분석기를 자동으로 적용합니다. 기술 자료 정의 또는 쿼리에서 분석기를 지정하지 않습니다.

언어별 자동 분석기를 사용하도록 설정하려면 minimal를 contentExtractionMode(으)로 설정하고 지식 원본 정의에서 ingestionParameters.aiServices를 구성합니다.

키 없는 인증의 경우 를 생략하고 Microsoft Foundry 리소스에서 Foundry IQ 서비스의 관리 ID에 aiServices.apiKey 역할을 할당합니다. 키 기반 인증의 경우 Foundry 리소스에 유효한 키로 설정합니다 aiServices.apiKey .

지원되는 언어는 다음과 같습니다.

  • English
  • Japanese
  • French
  • 스페인어
  • German
  • 네덜란드어
  • Italian
  • 포르투갈어(브라질)
  • 유럽 포르투갈어
  • 중국어(간체)
  • 중국어 - 번체
  • 한국어

다국어 콘텐츠의 경우 Foundry IQ는 주로 감지된 언어를 기반으로 분석기를 선택합니다. 언어가 지원되지 않거나 불확실한 경우 표준 분석기를 사용합니다.

언어별 자동 분석기를 사용하도록 설정하면 Foundry IQ는 데이터에 해당 언어의 문서가 포함되어 있는지 여부에 관계없이 지원되는 모든 언어에 대한 언어별 콘텐츠 필드를 생성된 인덱스 스키마에 추가합니다. 수집 중 문서는 감지된 언어에 따라 적절한 언어별 필드로 라우팅됩니다.

사용되지 않는 언어 필드에는 인덱싱된 콘텐츠가 포함되지 않고 스토리지에 미치는 영향이 최소화되지만 인덱스 스키마의 일부로 유지되며 인덱스 필드 제한에 포함됩니다. 인덱스 디자인, 필드 수 및 스토리지 요구 사항을 계획할 때 추가 필드를 고려합니다. 자세한 내용은 인덱스 제한 및 Foundry IQ 서비스의 용량 추정 및 관리를 참조하세요.

언어 감지는 무료 AI 보강 할당량 이후에는 요금이 청구됩니다. 자세한 내용은 무료 보강을 참조하세요.

수집 후 생성된 개체를 편집하지 않고 언어 라우팅을 확인합니다.

  1. 생성된 인덱스 스키마를 검사합니다. 언어별 필드에 해당하는 분석기가 올바르게 연결되어 있는지(예: snippet_en에는 en.microsoft 적용)와 snippet_default가 표준 분석기 대체를 제공하는지 확인합니다.
  2. 생성된 의미 체계 구성에 언어별 콘텐츠 필드 및 snippet_default가 나열되는지 확인합니다.
  3. 지원되는 언어로 감지된 문서에 대해 인덱싱된 청크를 검사합니다. 각 청크의 텍스트는 해당 언어 필드에 속합니다. 지원되지 않거나 불확실한 감지는 텍스트를 snippet_default로 라우팅합니다.
  4. 채워진 언어 또는 대체 필드에서 콘텐츠를 읽습니다. 이 모드에서는 생성된 스키마에 별도의 snippet 필드가 포함되지 않습니다.

스키마 또는 결과가 일치하지 않는 경우 위의 활성화 설정과 인덱서 오류를 검토하세요. 이러한 검사는 기존 생성된 인덱스의 업데이트 또는 마이그레이션 프로시저를 정의하지 않습니다.

수집 상태 확인

다음 코드를 실행하여 인덱서 파이프라인을 생성하고 검색 인덱스를 채우는 지식 원본에 대한 기술 자료 종류 및 자세한 인덱싱 오류를 포함하여 수집 진행률 및 상태를 모니터링합니다.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

// Get knowledge source ingestion status
var statusResponse = await indexClient.GetKnowledgeSourceStatusAsync(knowledgeSourceName);
var status = statusResponse.Value;

// Serialize to JSON for display
var json = JsonSerializer.Serialize(status, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

참조:SearchIndexClient

# Check knowledge source ingestion status
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json

index_client = SearchIndexClient(endpoint="search_url", credential=AzureKeyCredential("api_key"))

status = index_client.get_knowledge_source_status("knowledge_source_name")
print(json.dumps(status.as_dict(), indent=2))

참조:SearchIndexClient

### Check knowledge source ingestion status
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}/status?api-version={{api-version}}
Authorization: Bearer {{token}}
Content-Type: application/json 

참조:지식 원본 - 상태 조회

수집 매개 변수를 포함하고 콘텐츠를 적극적으로 수집하는 요청에 대한 응답은 다음 예제와 같습니다.

{
  "kind": "azureBlob",
  "synchronizationStatus": "active",
  "synchronizationInterval": "1d",
  "currentSynchronizationState": {
    "startTime": "2026-04-10T19:30:00Z",
    "itemUpdatesProcessed": 1100,
    "itemsUpdatesFailed": 100,
    "itemsSkipped": 1100,
    "errors": [
      {
        "key": "Item id 1",
        "docURL": "https://contoso.blob.core.windows.net/contracts/2024/Q4/doc-00023.csv",
        "statusCode": 400,
        "componentName": "DocumentExtraction.AzureBlob.MyDataSource",
        "errorMessage": "Could not read the value of column 'foo' at index '0'.",
        "details": "The file could not be parsed.",
        "documentationLink": "https://go.microsoft.com/fwlink/?linkid=2049388"
      }
    ]
  },
  "lastSynchronizationState": {
    "status": "partialSuccess",
    "startTime": "2026-04-09T19:30:00Z",
    "endTime": "2026-04-09T19:40:01Z",
    "itemUpdatesProcessed": 1100,
    "itemsUpdatesFailed": 100,
    "itemsSkipped": 1100,
    "errors": null
  },
  "statistics": {
    "totalSynchronizations": 25,
    "averageSynchronizationDuration": "00:15:20",
    "averageItemsProcessedPerSynchronization": 500
  }
}

참고

kind 문서 수준 오류 세부 정보가 포함된 속성 및 currentSynchronizationState.errors[] 배열은 2026-04-01 API 버전부터 사용할 수 있습니다. 이전 API 버전의 경우 이러한 필드는 반환되지 않습니다. 이 lastSynchronizationState.status 필드는 2026-04-01년에도 새로 추가되었습니다.

생성된 개체 검토

이 지식 원본을 만들면 Foundry IQ (Azure AI 검색)는 데이터 원본, 인덱서, 인덱스를 자동으로 생성하며, 수집 파이프라인에 필요한 경우 기술 집합도 생성합니다. 만들기 응답은 아래 createdResources의 각 개체를 나열합니다.

이러한 개체는 고정 템플릿에 따라 생성되며 해당 이름은 기술 자료의 이름을 기반으로 합니다. 개체 이름은 변경할 수 없습니다. 변경으로 인해 인덱서 파이프라인을 중단하는 오류 또는 비호환성이 발생할 수 있으므로 이러한 개체를 직접 편집하지 마십시오.

적격한 Blob, ADLS Gen2 및 Azure SQL 원본에만 임시 네트워킹 재정의를 통해 생성된 인덱서의 실행 환경을 변경할 수 있습니다. 이 예외는 인덱싱된 SharePoint 또는 OneLake에는 적용되지 않으며 다른 생성된 개체 변경은 허용하지 않습니다. 나중에 지식 원본 업데이트 또는 다시 생성은 재정의를 덮어쓸 수 있습니다.

Azure 포털을 사용하여 개체 만들기의 유효성을 검사할 수 있습니다. 워크플로는 다음과 같습니다.

  1. 인덱서에서 성공 또는 실패 메시지를 확인합니다. 연결 또는 할당량 오류가 여기에 표시됩니다.

  2. 데이터 원본을 확인하여 데이터 저장소에 대한 연결을 확인합니다. 연결은 지식 원본을 구성한 방식에 따라 연결 문자열 또는 관리되는 ID를 사용합니다.

  3. 기술 집합이 생성되면 해당 보강 및 벡터화 설정을 확인합니다. SQL 지식 원본은 embeddingColumns를 지정할 때만 기술 세트를 생성합니다.

  4. 검색 가능하고 필터링 가능한 필드와 유사성 검색을 위해 벡터를 저장하는 필드를 포함하여 검색을 위해 콘텐츠가 인덱싱되고 노출되는 방식을 확인하려면 인덱스를 확인합니다. 검색 탐색기를 사용하여 생성된 인덱스에 대해 쿼리를 실행합니다.

생성된 데이터 원본, 인덱서, 인덱스 및 기술 세트(있는 경우)를 하나의 수집 구성으로 처리합니다. 해당 구성을 변경하거나 인덱스로 문서를 게시할 수 있는 사용자를 제한합니다. 생성된 식별자 및 권한 필드 이름은 문서 소유권을 설정하거나 일반 콘텐츠를 권한 부여의 승인된 출처로 만들지 않습니다. 예방 수집 지침 및 문서화된 사용자 지정 경계를 따르며, 생성된 키 또는 매핑에 대한 임의의 직접 편집을 소유권 제어 수단으로 사용하지 마세요.

기술 자료에 할당

기술 자료에 만족하는 경우 기술 자료에 추가합니다.

지식 베이스 질의

기술 자료를 구성한 후 검색 작업 또는 MCP 엔드포인트를 호출 하여 기술 자료를 쿼리합니다. 시나리오와 일치하는 구성을 선택합니다.

문서 수준 권한 적용

기본 추출 옵션(contentExtractionMode: "minimal") 또는 지원되는 경우 Content Understanding 기반 표준 추출(contentExtractionMode: "standard")을 사용합니다. 생성된 모든 청크는 원본 항목의 권한 메타데이터 및 원본 컨텍스트를 유지합니다. 문서 수준 권한은 고객이 선택한 특수 구문 분석 모드를 지원하지 않습니다. 권한 수집에 대한 지원되는 구문 분석 및 콘텐츠 추출을 참조하세요. 기술 원본에서 이러한 옵션을 구성합니다. 생성된 파서 설정을 변경하지 마세요.

REST API2026-10-01를 사용하여 기술 자료를 만들 때 설정합니다ingestionPermissionOptions.

  • 표준 Blob Storage의 경우 isADLSGen2를 rbacScope로 설정하고 false를 요청합니다. 전체 Blob REST 구성을 참조하세요.
  • ADLS Gen2의 경우 isADLSGen2을 true(으)로 설정하고 userIds, groupIds, rbacScope를 요청합니다. ADLS REST 구성으로 시작하고 배열에 ingestionPermissionOptions 추가하여 rbacScope ACL 및 컨테이너 RBAC 범위를 모두 수집합니다.

생성된 인덱스에는 metadata_storage_path 및 구성된 사용 권한 필드가 포함되며, 프로젝션된 청크에 대한 매핑도 포함됩니다. 경로는 RBAC 전용 수집을 포함한 ADLS 권한 수집에 필수입니다. 생성된 표준 Blob 스키마에 있는 경우 직접 Blob 인덱서의 컨테이너 범위를 계산하기 위한 요구 사항이 아닙니다.

생성된 인덱스, 기술 세트 프로젝션 및 인덱서와 함께 검토합니다. 보호된 모든 청크에서 원본 경로 컨텍스트 및 신뢰할 수 있는 권한 매핑을 유지합니다. 값이 누락된 기존 레코드의 경우 스키마만 수정해서는 메타데이터가 백필되지 않습니다. 스키마 및 프로젝션 수정 지침을 따르세요.

생성된 ADLS 인덱서는 자동 ACL 새로 고침 설정 및 주기를 따릅니다. 생성된 인덱서에서 parameters.configuration.refreshAllAcls을 구성합니다. 주문형 새로 고침의 경우 사용 권한 재동기 절차에서 해당 인덱서의 이름을 사용합니다.

위임된 사용자의 액세스 토큰을 검색 요청에 포함합니다. 요청 헤더는 쿼리 시 사용 권한 적용을 참조하세요.

문서에 포함된 이미지 표시(미리 보기)

답변 합성 응답에서 문서에 포함된 이미지(예: 다이어그램 또는 스캔)를 표시하려면 이 지식 소스에서 assetStore를 구성한 다음 지식 베이스에서 이미지 제공 기능을 사용하도록 설정합니다. ingestionPermissionOptions이 구성된 경우 이미지 제공은 지원되지 않습니다. 자세한 내용은 에이전트형 검색에서 문서에 포함된 이미지 표시(미리 보기)를 참조하세요.

지식 원본 삭제

기술 자료를 삭제하려면 먼저 이를 참조하는 기술 자료를 삭제하거나 기술 자료 정의를 업데이트하여 참조를 제거해야 합니다. 인덱스 및 인덱서 파이프라인을 생성하는 기술 원본의 경우 생성된 모든 개체 도 삭제됩니다. 그러나 기존 인덱스로 기술 원본을 만든 경우 인덱스가 삭제되지 않습니다.

사용 중인 기술 원본을 삭제하려고 하면 작업이 실패하고 영향을 받는 기술 자료 목록이 반환됩니다.

기술 자료를 삭제하려면 다음을 수행합니다.

  1. Foundry IQ 서비스의 모든 기술 자료 베이스 목록을 가져옵니다.

    using Azure.Search.Documents.Indexes;
    
    var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
    var knowledgeBases = indexClient.GetKnowledgeBasesAsync();
    
    Console.WriteLine("Knowledge Bases:");
    
    await foreach (var kb in knowledgeBases)
    {
        Console.WriteLine($"  - {kb.Name}");
    }
    

    참조:SearchIndexClient

    예제 응답은 다음과 같을 수 있습니다.

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. 개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.

    using Azure.Search.Documents.Indexes;
    using System.Text.Json;
    
    var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
    
    // Specify the knowledge base name to retrieve
    string kbNameToGet = "earth-knowledge-base";
    
    // Get a specific knowledge base definition
    var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
    var kb = knowledgeBaseResponse.Value;
    
    // Serialize to JSON for display
    string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
    Console.WriteLine(json);
    

    참조:SearchIndexClient

    예제 응답은 다음과 같을 수 있습니다.

     {
       "Name": "earth-knowledge-base",
       "KnowledgeSources": [
         {
           "Name": "earth-knowledge-source"
         }
       ],
       "Models": [
         {}
       ],
       "RetrievalReasoningEffort": {},
       "OutputMode": {},
       "ETag": "\u00220x8DE278629D782B3\u0022",
       "EncryptionKey": null,
       "Description": null,
       "RetrievalInstructions": null,
       "AnswerInstructions": null
     }
    
  3. 기술 자료를 삭제하거나 여러 기술 자료가 있는 경우 기술 자료를 업데이트하여 원본을 제거합니다. 이 예제에서는 삭제를 보여줍니다.

    using Azure.Search.Documents.Indexes;
    var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
    
    await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
    System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");
    

    참조:SearchIndexClient

  4. 기술 자료를 삭제합니다.

    await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
    System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");
    

    참조:SearchIndexClient

  1. Foundry IQ 서비스의 모든 기술 자료 목록을 가져옵니다.

    # Get knowledge bases
    from azure.core.credentials import AzureKeyCredential
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    
    print("Knowledge Bases:")
    for kb in index_client.list_knowledge_bases():
        print(f"  - {kb.name}")
    

    참조:SearchIndexClient

    예제 응답은 다음과 같을 수 있습니다.

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. 개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.

    # Get a knowledge base definition
    from azure.core.credentials import AzureKeyCredential
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    kb = index_client.get_knowledge_base("knowledge_base_name")
    print(kb)
    

    참조:SearchIndexClient

    예제 응답은 다음과 같을 수 있습니다.

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. 기술 자료를 삭제하거나 여러 기술 자료가 있는 경우 기술 자료를 업데이트하여 원본을 제거합니다. 이 예제에서는 삭제를 보여줍니다.

    # Delete a knowledge base
    from azure.core.credentials import AzureKeyCredential 
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    index_client.delete_knowledge_base("knowledge_base_name")
    print(f"Knowledge base deleted successfully.")
    

    참조:SearchIndexClient

  4. 기술 자료를 삭제합니다.

    # Delete a knowledge source
    from azure.core.credentials import AzureKeyCredential 
    from azure.search.documents.indexes import SearchIndexClient
    
    index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
    index_client.delete_knowledge_source("knowledge_source_name")
    print(f"Knowledge source deleted successfully.")
    

    참조:SearchIndexClient

  1. Foundry IQ 서비스의 모든 기술 자료 목록을 가져옵니다.

    ### Get knowledge bases
    GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
    Authorization: Bearer {{token}}
    

    참조:지식 베이스 - 목록

    예제 응답은 다음과 같을 수 있습니다.

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. 개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.

    ### Get a knowledge base definition
    GET {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    참조:지식 베이스 - 가져오기

    예제 응답은 다음과 같을 수 있습니다.

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. 기술 자료를 삭제하거나 여러 기술 자료가 있는 경우 기술 자료를 업데이트하여 원본을 제거합니다. 이 예제에서는 삭제를 보여줍니다.

    ### Delete a knowledge base
    DELETE {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    참조:기술 자료실 - 삭제

  4. 기술 자료를 삭제합니다.

    ### Delete a knowledge source
    DELETE {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    참조:지식 소스 - 삭제