참고
이 에이전트 검색 기능은 일반적으로 프로그래밍 방식 액세스를 통해 2026-04-01 REST API 버전에서 사용할 수 있습니다. Azure 포털 및 Microsoft Foundry 포털은 모든 에이전트 검색 기능에 대한 미리 보기 전용 액세스를 계속 제공합니다. 마이그레이션 지침은 에이전트 검색 코드를 최신 버전으로 마이그레이션을 참조하세요.
인덱싱된 OneLake 지식 원본을 사용하여 에이전트 검색 파이프라인에서 Microsoft OneLake 파일을 인덱싱하고 쿼리합니다. 지식 원본 은 독립적으로 생성되고, 기술 자료에서 참조되며, 에이전트 또는 챗봇이 쿼리 시 검색 작업을 호출할 때 접지 데이터로 사용됩니다.
인덱싱된 OneLake 기술 원본을 만들 때 외부 데이터 원본, 모델 및 속성을 지정하여 다음 Azure AI 검색 개체를 자동으로 생성합니다.
- 레이크하우스를 나타내는 데이터 원본입니다.
- 레이크하우스에서 다중 모달 콘텐츠를 분할하여 선택적으로 벡터화할 수 있는 기술입니다.
- 보강된 콘텐츠를 저장하고 에이전트 검색 조건을 충족하는 인덱스입니다.
- 이전 개체를 사용하여 인덱싱 및 보강 파이프라인을 구동하는 인덱서입니다.
생성된 인덱서는 필수 구성 요소, 지원되는 작업, 지원되는 문서 형식, 지원되는 바로 가기 및 제한 사항이 OneLake 기술 원본에도 적용되는 OneLake 인덱서를 준수합니다. 자세한 내용은 OneLake 인덱서 설명서를 참조하세요.
사용량 지원
| Azure 포털 | Microsoft Foundry 포털 | .NET SDK | Python SDK | Java SDK | JavaScript SDK | REST API |
|---|---|---|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
필수 구성 요소
에이전트 검색을 제공하는 모든 지역의 Azure AI 검색.
Azure AI 검색 개체를 만들고 사용할 수 있는 권한입니다. 역할 기반 액세스를 권장하지만 역할 할당이 불가능한 경우 API 키를 사용할 수 있습니다. 자세한 내용은 검색 서비스에 연결을 참조하세요.
필수 Azure. Search.Documents 패키지:
2025-11-01-preview 기능의 경우 최신 미리 보기 패키지:
dotnet add package Azure.Search.Documents --prerelease2026-04-01 기능의 경우 안정적인 최신 패키지:
dotnet add package Azure.Search.Documents
필수 azure-search-documents 패키지:
2025-11-01-preview 기능의 경우 최신 미리 보기 패키지:
pip install azure-search-documents --pre2026-04-01 기능의 경우 안정적인 최신 패키지:
pip install azure-search-documents
필수 REST API 버전:
미리 보기 기능: Search Service 2025-11-01-preview
일반 출시 기능: Search Service 2026-04-01
기존 지식 원본 확인
기술 자료는 재사용 가능한 최상위 개체입니다. 기존 지식 원본에 대해 아는 것은 새 개체를 다시 사용하거나 이름을 지정하는 데 유용합니다.
다음 코드를 실행하여 이름 및 형식별로 기술 자료를 나열합니다.
// 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}");
}
# 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})")
### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
api-key: {{api-key}}
참조:기술 자료 - 목록
이름으로 단일 기술 원본을 반환하여 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));
# 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))
### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
api-key: {{api-key}}
참조:기술 자료 - 가져오기
다음 JSON은 인덱싱된 OneLake 지식 원본에 대한 예제 응답입니다.
{
"name": "my-onelake-ks",
"kind": "indexedOneLake",
"description": "A sample indexed OneLake knowledge source.",
"encryptionKey": null,
"indexedOneLakeParameters": {
"fabricWorkspaceId": "<REDACTED>",
"lakehouseId": "<REDACTED>",
"targetPath": null,
"ingestionParameters": {
"disableImageVerbalization": false,
"ingestionPermissionOptions": [],
"contentExtractionMode": "standard",
"identity": null,
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<REDACTED>",
"deploymentId": "text-embedding-3-large",
"apiKey": "<REDACTED>",
"modelName": "text-embedding-3-large"
}
},
"chatCompletionModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<REDACTED>",
"deploymentId": "gpt-5-mini",
"apiKey": "<REDACTED>",
"modelName": "gpt-5-mini"
}
},
"ingestionSchedule": null,
"aiServices": {
"uri": "<REDACTED>",
"apiKey": "<REDACTED>"
}
},
"createdResources": {
"datasource": "my-onelake-ks-datasource",
"indexer": "my-onelake-ks-indexer",
"skillset": "my-onelake-ks-skillset",
"index": "my-onelake-ks-index"
}
}
}
참고
중요한 정보가 수정됩니다. 생성된 리소스는 응답의 끝에 표시됩니다.
기술 자료 만들기
다음 코드를 실행하여 인덱싱된 OneLake 기술 원본을 만듭니다.
// Create an indexed OneLake knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));
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
{
DisableImageVerbalization = false,
ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: chatCompletionParams),
EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
{
AzureOpenAIParameters = embeddingParams
},
IngestionPermissionOptions = new List<KnowledgeSourceIngestionPermissionOption>
{
KnowledgeSourceIngestionPermissionOption.UserIds,
KnowledgeSourceIngestionPermissionOption.GroupIds
}
};
var oneLakeParams = new IndexedOneLakeKnowledgeSourceParameters(
fabricWorkspaceId: fabricWorkspaceId,
lakehouseId: lakehouseId)
{
IngestionParameters = ingestionParams
};
var knowledgeSource = new IndexedOneLakeKnowledgeSource(
name: "my-onelake-ks",
indexedOneLakeParameters: oneLakeParams)
{
Description = "This knowledge source pulls content from a lakehouse."
};
await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");
# Create an indexed OneLake knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import IndexedOneLakeKnowledgeSource, IndexedOneLakeKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceAzureOpenAIVectorizer, KnowledgeSourceContentExtractionMode, KnowledgeSourceIngestionParameters
index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
knowledge_source = IndexedOneLakeKnowledgeSource(
name = "my-onelake-ks",
description= "This knowledge source pulls content from a lakehouse.",
encryption_key = None,
indexed_one_lake_parameters = IndexedOneLakeKnowledgeSourceParameters(
fabric_workspace_id = "fabric_workspace_id",
lakehouse_id = "lakehouse_id",
target_path = None,
ingestion_parameters = KnowledgeSourceIngestionParameters(
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",
api_key = "aoai_api_key"
)
),
embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
resource_url = "aoai_endpoint",
deployment_name = "aoai_embedding_deployment",
model_name = "aoai_embedding_model",
api_key = "aoai_api_key"
)
),
content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
ingestion_schedule = None,
ingestion_permission_options = ["user_ids", "group_ids"]
)
)
)
index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")
### Create an indexed OneLake knowledge source
PUT {{search-url}}/knowledgesources/my-onelake-ks?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json
{
"name": "my-onelake-ks",
"kind": "indexedOneLake",
"description": "This knowledge source pulls content from a lakehouse.",
"indexedOneLakeParameters": {
"fabricWorkspaceId": "<YOUR FABRIC WORKSPACE GUID>",
"lakehouseId": "<YOUR LAKEHOUSE GUID>",
"targetPath": null,
"ingestionParameters": {
"identity": null,
"disableImageVerbalization": null,
"chatCompletionModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"deploymentId": "{{aoai-gpt-deployment}}",
"modelName": "{{aoai-gpt-model}}",
"apiKey": "{{aoai-key}}"
}
},
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"deploymentId": "{{aoai-embedding-deployment}}",
"modelName": "{{aoai-embedding-model}}",
"apiKey": "{{aoai-key}}"
}
},
"contentExtractionMode": "minimal",
"ingestionSchedule": null,
"ingestionPermissionOptions": ["userIds", "groupIds"]
}
}
}
참고
문서 수준 권한 적용을 사용 ingestionPermissionOptions 하려면 2025-11-01-preview API 버전이 필요합니다. 2026-04-01은 이 기능을 지원하지 않습니다.
원본별 속성
2025-11-01-preview 및 2026-04-01 API 버전 모두에 대해 다음 속성을 전달하여 인덱싱된 OneLake 기술 원본을 만들 수 있습니다.
| 이름 | 설명 | 타입 | 수정 가능 | 필수 |
|---|---|---|---|---|
Name |
기술 자료 컬렉션 내에서 고유해야 하며 Azure AI 검색 개체에 대해 이름 지정 지침 따라야 하는 기술 자료의 이름입니다. | 문자열 | 아니요 | 예 |
Description |
지식 원본에 대한 설명입니다. | 문자열 | 예 | 아니요 |
EncryptionKey |
기술 원본과 생성된 개체 모두에서 중요한 정보를 암호화하는 고객 관리형 키 입니다. | 개체 | 예 | 아니요 |
IndexedOneLakeKnowledgeSourceParameters |
OneLake 기술 원본과 관련된 매개 변수: FabricWorkspaceId, LakehouseId및 TargetPath. |
개체 | 예 | |
FabricWorkspaceId |
Lakehouse를 포함하는 작업 영역의 GUID입니다. | 문자열 | 아니요 | 예 |
LakehouseId |
레이크하우스의 GUID입니다. | 문자열 | 아니요 | 예 |
TargetPath |
레이크하우스 내의 폴더 또는 바로 가기입니다. 지정되지 않으면 전체 레이크하우스가 인덱싱됩니다. | 문자열 | 아니요 | 아니요 |
| 이름 | 설명 | 타입 | 수정 가능 | 필수 |
|---|---|---|---|---|
name |
기술 자료 컬렉션 내에서 고유해야 하며 Azure AI 검색 개체에 대해 이름 지정 지침 따라야 하는 기술 자료의 이름입니다. | 문자열 | 아니요 | 예 |
description |
지식 원본에 대한 설명입니다. | 문자열 | 예 | 아니요 |
encryption_key |
기술 원본과 생성된 개체 모두에서 중요한 정보를 암호화하는 고객 관리형 키 입니다. | 개체 | 예 | 아니요 |
indexed_one_lake_parameters |
OneLake 기술 원본과 관련된 매개 변수: fabric_workspace_id, lakehouse_id및 target_path. |
개체 | 예 | |
fabric_workspace_id |
Lakehouse를 포함하는 작업 영역의 GUID입니다. | 문자열 | 아니요 | 예 |
lakehouse_id |
레이크하우스의 GUID입니다. | 문자열 | 아니요 | 예 |
target_path |
레이크하우스 내의 폴더 또는 바로 가기입니다. 지정되지 않으면 전체 레이크하우스가 인덱싱됩니다. | 문자열 | 아니요 | 아니요 |
| 이름 | 설명 | 타입 | 수정 가능 | 필수 |
|---|---|---|---|---|
name |
기술 자료 컬렉션 내에서 고유해야 하며 Azure AI 검색 개체에 대해 이름 지정 지침 따라야 하는 기술 자료의 이름입니다. | 문자열 | 아니요 | 예 |
kind |
이 경우 지식 원본의 종류입니다 indexedOneLake . |
문자열 | 아니요 | 예 |
description |
지식 원본에 대한 설명입니다. | 문자열 | 예 | 아니요 |
encryptionKey |
기술 원본과 생성된 개체 모두에서 중요한 정보를 암호화하는 고객 관리형 키 입니다. | 개체 | 예 | 아니요 |
indexedOneLakeParameters |
OneLake 기술 원본과 관련된 매개 변수: fabricWorkspaceId, lakehouseId및 targetPath. |
개체 | 예 | |
fabricWorkspaceId |
Lakehouse를 포함하는 작업 영역의 GUID입니다. | 문자열 | 아니요 | 예 |
lakehouseId |
레이크하우스의 GUID입니다. | 문자열 | 아니요 | 예 |
targetPath |
레이크하우스 내의 폴더 또는 바로 가기입니다. 지정되지 않으면 전체 레이크하우스가 인덱싱됩니다. | 문자열 | 아니요 | 아니요 |
수집 매개 변수 속성
인덱싱된 기술 자료의 경우에만 다음 ingestionParameters 속성을 전달하여 콘텐츠를 수집하고 처리하는 방법을 제어할 수 있습니다.
| 이름 | 설명 | 타입 | 수정 가능 | 필수 |
|---|---|---|---|---|
Identity |
생성된 인덱서에서 사용할 관리 ID 입니다. | 개체 | 예 | 아니요 |
DisableImageVerbalization |
이미지 설명 기능을 활성화하거나 비활성화합니다. 기본값은 False이미지 언어화를 사용하도록 설정하는 것입니다.
True 이미지 음성 설명을 비활성화하도록 설정합니다. |
부울 | 아니요 | 아니요 |
ChatCompletionModel |
이미지를 구두로 처리하거나 콘텐츠를 추출하는 채팅 완성 모델입니다. 지원되는 모델은 gpt-4o, gpt-4o-mini,gpt-4.1, gpt-4.1-minigpt-4.1-nano, gpt-5, gpt-5-mini및 gpt-5-nano.
GenAI 프롬프트 기술은 생성된 기술 세트에 포함됩니다. 또한 이 매개 변수를 설정하려면 이 DisableImageVerbalization 매개 변수를 .로 설정해야 합니다 False. |
개체 |
ApiKey 및 DeploymentName만 편집할 수 있습니다. |
아니요 |
EmbeddingModel |
인덱싱 중 및 쿼리 시간에 텍스트 및 이미지 콘텐츠를 벡터화하는 텍스트 포함 모델입니다. 지원되는 모델은 text-embedding-ada-002, text-embedding-3-small및 text-embedding-3-large.
Azure OpenAI Embedding skill은 생성된 기술 집합에 포함되며, 생성된 인덱스로 Azure OpenAI 벡터라이저 포함됩니다. |
개체 |
ApiKey 및 DeploymentName만 편집할 수 있습니다. |
아니요 |
ContentExtractionMode |
파일에서 콘텐츠를 추출하는 방법을 제어합니다. 기본값은 minimal텍스트 및 이미지에 표준 콘텐츠 추출을 사용하는 것입니다. 생성된 기술 세트에 포함된 standard을 사용하여 고급 문서 크래킹 및 청크 분할을 위해 로 설정합니다.
standard만을 위해 파라미터 AiServices을(를) 지정할 수 있습니다. |
문자열 | 아니요 | 아니요 |
AiServices |
Foundry 도구의 Azure Content Understanding에 액세스하기 위한 Microsoft Foundry 리소스입니다. 이 매개 변수를 설정하려면 이 ContentExtractionMode 매개 변수를 .로 설정해야 합니다 standard. |
개체 | 오직 ApiKey만 편집 가능 |
아니요 |
IngestionSchedule |
생성된 인덱서에 예약 정보를 추가합니다. 나중에 일정을 추가하여 데이터 새로 고침을 자동화할 수도 있습니다. | 개체 | 예 | 아니요 |
IngestionPermissionOptions |
콘텐츠와 함께 수집할 문서 수준 권한입니다.
UserIds, GroupIds, 또는 RbacScope를 지정하여 권한 메타데이터를 인덱스에 저장합니다. 원본별 지침은 Blob Storage에서 RBAC 권한 수집 및 ADLS Gen2에서 ACL 수집을 참조하세요. 쿼리 시 이러한 권한을 적용하려면 쿼리 시 사용 권한 적용을 참조하세요. |
배열 | 아니요 | 아니요 |
| 이름 | 설명 | 타입 | 수정 가능 | 필수 |
|---|---|---|---|---|
identity |
생성된 인덱서에서 사용할 관리 ID 입니다. | 개체 | 예 | 아니요 |
disable_image_verbalization |
이미지 설명 기능을 활성화하거나 비활성화합니다. 기본값은 False이미지 언어화를 사용하도록 설정하는 것입니다.
True 이미지 음성 설명을 비활성화하도록 설정합니다. |
부울 | 아니요 | 아니요 |
chat_completion_model |
이미지를 구두로 처리하거나 콘텐츠를 추출하는 채팅 완성 모델입니다. 지원되는 모델은 gpt-4o, gpt-4o-mini,gpt-4.1, gpt-4.1-minigpt-4.1-nano, gpt-5, gpt-5-mini및 gpt-5-nano.
GenAI 프롬프트 기술은 생성된 기술 세트에 포함됩니다. 또한 이 매개 변수를 설정하려면 이 disable_image_verbalization 매개 변수를 .로 설정해야 합니다 False. |
개체 |
api_key 및 deployment_name만 편집할 수 있습니다. |
아니요 |
embedding_model |
인덱싱 중 및 쿼리 시간에 텍스트 및 이미지 콘텐츠를 벡터화하는 텍스트 포함 모델입니다. 지원되는 모델은 text-embedding-ada-002, text-embedding-3-small및 text-embedding-3-large.
Azure OpenAI Embedding skill은 생성된 기술 집합에 포함되며, 생성된 인덱스로 Azure OpenAI 벡터라이저 포함됩니다. |
개체 |
api_key 및 deployment_name만 편집할 수 있습니다. |
아니요 |
content_extraction_mode |
파일에서 콘텐츠를 추출하는 방법을 제어합니다. 기본값은 minimal텍스트 및 이미지에 표준 콘텐츠 추출을 사용하는 것입니다. 생성된 기술 세트에 포함된 standard을 사용하여 고급 문서 크래킹 및 청크 분할을 위해 로 설정합니다.
standard만을 위해 파라미터 ai_services을(를) 지정할 수 있습니다. |
문자열 | 아니요 | 아니요 |
ai_services |
Foundry 도구의 Azure Content Understanding에 액세스하기 위한 Microsoft Foundry 리소스입니다. 이 매개 변수를 설정하려면 이 content_extraction_mode 매개 변수를 .로 설정해야 합니다 standard. |
개체 | 오직 api_key만 편집 가능 |
아니요 |
ingestion_schedule |
생성된 인덱서에 예약 정보를 추가합니다. 나중에 일정을 추가하여 데이터 새로 고침을 자동화할 수도 있습니다. | 개체 | 예 | 아니요 |
ingestion_permission_options |
콘텐츠와 함께 수집할 문서 수준 권한입니다.
user_ids, group_ids, 또는 rbac_scope를 지정하여 권한 메타데이터를 인덱스에 저장합니다. 원본별 지침은 Blob Storage에서 RBAC 권한 수집 및 ADLS Gen2에서 ACL 수집을 참조하세요. 쿼리 시 이러한 권한을 적용하려면 쿼리 시 사용 권한 적용을 참조하세요. |
배열 | 아니요 | 아니요 |
| 이름 | 설명 | 타입 | 수정 가능 | 필수 |
|---|---|---|---|---|
identity |
생성된 인덱서에서 사용할 관리 ID 입니다. | 개체 | 예 | 아니요 |
disableImageVerbalization |
이미지 설명 기능을 활성화하거나 비활성화합니다. 기본값은 false이미지 언어화를 사용하도록 설정하는 것입니다.
true 이미지 음성 설명을 비활성화하도록 설정합니다. |
부울 | 아니요 | 아니요 |
chatCompletionModel |
이미지를 구두로 처리하거나 콘텐츠를 추출하는 채팅 완성 모델입니다. 지원되는 모델은 gpt-4o, gpt-4o-mini,gpt-4.1, gpt-4.1-minigpt-4.1-nano, gpt-5, gpt-5-mini및 gpt-5-nano.
GenAI 프롬프트 기술은 생성된 기술 세트에 포함됩니다. 또한 이 매개 변수를 설정하려면 이 disableImageVerbalization 매개 변수를 .로 설정해야 합니다 false. |
개체 |
apiKey 및 deploymentId만 편집할 수 있습니다. |
아니요 |
embeddingModel |
인덱싱 중 및 쿼리 시간에 텍스트 및 이미지 콘텐츠를 벡터화하는 텍스트 포함 모델입니다. 지원되는 모델은 text-embedding-ada-002, text-embedding-3-small및 text-embedding-3-large.
Azure OpenAI Embedding skill은 생성된 기술 집합에 포함되며, 생성된 인덱스로 Azure OpenAI 벡터라이저 포함됩니다. |
개체 |
apiKey 및 deploymentId만 편집할 수 있습니다. |
아니요 |
contentExtractionMode |
파일에서 콘텐츠를 추출하는 방법을 제어합니다. 기본값은 minimal텍스트 및 이미지에 표준 콘텐츠 추출을 사용하는 것입니다. 생성된 기술 세트에 포함된 standard을 사용하여 고급 문서 크래킹 및 청크 분할을 위해 로 설정합니다.
standard만을 위해 파라미터 aiServices을(를) 지정할 수 있습니다. |
문자열 | 아니요 | 아니요 |
aiServices |
Foundry 도구의 Azure Content Understanding에 액세스하기 위한 Microsoft Foundry 리소스입니다. 이 매개 변수를 설정하려면 이 contentExtractionMode 매개 변수를 .로 설정해야 합니다 standard. |
개체 | 오직 apiKey만 편집 가능 |
아니요 |
ingestionSchedule |
생성된 인덱서에 예약 정보를 추가합니다. 나중에 일정을 추가하여 데이터 새로 고침을 자동화할 수도 있습니다. | 개체 | 예 | 아니요 |
ingestionPermissionOptions |
콘텐츠와 함께 수집할 문서 수준 권한입니다.
userIds, groupIds, 또는 rbacScope를 지정하여 권한 메타데이터를 인덱스에 저장합니다. 원본별 지침은 Blob Storage에서 RBAC 권한 수집 및 ADLS Gen2에서 ACL 수집을 참조하세요. 쿼리 시 이러한 권한을 적용하려면 쿼리 시 사용 권한 적용을 참조하세요. |
배열 | 아니요 | 아니요 |
수집 상태 확인
다음 코드를 실행하여 인덱서 파이프라인을 생성하고 검색 인덱스를 채우는 지식 원본에 대한 기술 자료 종류 및 자세한 인덱싱 오류를 포함하여 수집 진행률 및 상태를 모니터링합니다.
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);
# 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))
### Check knowledge source ingestion status
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}/status?api-version={{api-version}}
api-key: {{api-key}}
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년에도 새로 추가되었습니다.
생성된 개체 검토
인덱싱된 OneLake 기술 원본을 만들 때 검색 서비스에서도 인덱서, 인덱스, 기술 세트 및 데이터 원본을 만듭니다. 오류 또는 비호환성을 도입하면 파이프라인이 중단 될 수 있으므로 이러한 개체를 편집하지 않는 것이 좋습니다.
기술 자료를 만든 후에는 생성된 개체가 응답에 나열됩니다. 이러한 개체는 고정 템플릿에 따라 만들어지고 해당 이름은 기술 자료의 이름을 기반으로 합니다. 개체 이름은 변경할 수 없습니다.
Azure 포털을 사용하여 출력 만들기의 유효성을 검사하는 것이 좋습니다. 워크플로는 다음과 같습니다.
- 인덱서에서 성공 또는 실패 메시지를 확인합니다. 연결 또는 할당량 오류가 여기에 표시됩니다.
- 인덱스에서 검색 가능한 콘텐츠를 확인합니다. 검색 탐색기를 사용하여 쿼리를 실행합니다.
- 스킬셋을 확인하여 콘텐츠가 청크화되고 선택적으로 벡터화되는 방법을 알아봅니다.
- 데이터 원본에서 연결 세부 정보를 확인합니다. 이 예제에서는 단순성을 위해 API 키를 사용하지만 인증 및 권한 부여를 위한 역할 기반 액세스 제어에 Microsoft Entra ID 사용할 수 있습니다.
기술 자료에 할당
기술 자료에 만족하는 경우 기술 자료에서 기술 원본을 지정하는 다음 단계를 계속 진행 합니다.
인덱싱된 OneLake 지식 소스를 지정하는 지식 기반의 경우, 반드시 includeReferenceSourceData를 true로 설정해야 합니다. 이 단계는 원본 문서 URL을 인용으로 끌어와야 합니다.
기술 자료가 구성되면 검색 작업을 사용하여 기술 원본을 쿼리합니다.
팁
문서 수준 권한을 적용하려면 이 기술 자료를 생성할 때 ingestionPermissionOptions을(를) 설정하고, 그런 다음 사용자의 액세스 토큰을 검색 요청에 포함합니다. 자세한 내용은 쿼리 시 사용 권한 적용을 참조하세요.
지식 원본 삭제
기술 자료를 삭제하려면 먼저 이를 참조하는 기술 자료를 삭제하거나 기술 자료 정의를 업데이트하여 참조를 제거해야 합니다. 인덱스 및 인덱서 파이프라인을 생성하는 기술 원본의 경우 생성된 모든 개체 도 삭제됩니다. 그러나 기존 인덱스로 기술 원본을 만든 경우 인덱스가 삭제되지 않습니다.
사용 중인 기술 원본을 삭제하려고 하면 작업이 실패하고 영향을 받는 기술 자료 목록이 반환됩니다.
기술 자료를 삭제하려면 다음을 수행합니다.
검색 서비스의 모든 기술 자료 목록을 가져옵니다.
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}"); }예제 응답은 다음과 같을 수 있습니다.
Knowledge Bases: - earth-knowledge-base - hotels-sample-knowledge-base - my-demo-knowledge-base개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.
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);예제 응답은 다음과 같을 수 있습니다.
{ "Name": "earth-knowledge-base", "KnowledgeSources": [ { "Name": "earth-knowledge-source" } ], "Models": [ {} ], "RetrievalReasoningEffort": {}, "OutputMode": {}, "ETag": "\u00220x8DE278629D782B3\u0022", "EncryptionKey": null, "Description": null, "RetrievalInstructions": null, "AnswerInstructions": null }기술 자료를 삭제하거나 여러 기술 자료가 있는 경우 기술 자료를 업데이트하여 원본을 제거합니다. 이 예제에서는 삭제를 보여줍니다.
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.");기술 자료를 삭제합니다.
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName); System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");
검색 서비스의 모든 기술 자료 목록을 가져옵니다.
# 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}")예제 응답은 다음과 같을 수 있습니다.
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-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)예제 응답은 다음과 같을 수 있습니다.
{ "name": "my-kb", "description": null, "retrievalInstructions": null, "answerInstructions": null, "outputMode": null, "knowledgeSources": [ { "name": "my-blob-ks", } ], "models": [], "encryptionKey": null, "retrievalReasoningEffort": { "kind": "low" } }기술 자료를 삭제하거나 여러 기술 자료가 있는 경우 기술 자료를 업데이트하여 원본을 제거합니다. 이 예제에서는 삭제를 보여줍니다.
# 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.")기술 자료를 삭제합니다.
# 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.")
검색 서비스의 모든 기술 자료 목록을 가져옵니다.
### Get knowledge bases GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name api-key: {{api-key}}참조:기술 자료 - 목록
예제 응답은 다음과 같을 수 있습니다.
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }개별 기술 자료 정의를 가져와서 기술 자료 참조를 확인합니다.
### Get a knowledge base definition GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}} api-key: {{api-key}}참조:기술 자료 - 가져오기
예제 응답은 다음과 같을 수 있습니다.
{ "name": "my-kb", "description": null, "retrievalInstructions": null, "answerInstructions": null, "outputMode": null, "knowledgeSources": [ { "name": "my-blob-ks", } ], "models": [], "encryptionKey": null, "retrievalReasoningEffort": { "kind": "low" } }기술 자료를 삭제하거나 여러 기술 자료가 있는 경우 기술 자료를 업데이트하여 원본을 제거합니다. 이 예제에서는 삭제를 보여줍니다.
### Delete a knowledge base DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}} api-key: {{api-key}}참조:기술 자료 - 삭제
기술 자료를 삭제합니다.
### Delete a knowledge source DELETE {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}} api-key: {{api-key}}참조:기술 자료 - 삭제