인덱싱된 SharePoint 기술 원본 만들기

참고

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

Important

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

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

외부 데이터 원본에 연결할 때 적용되는 용어는 외부 데이터 원본에서 확인하세요.

인덱싱된 SharePoint 기술 자료 원본은 SharePoint 콘텐츠를 Foundry IQ(Azure AI 검색)의 에이전트 검색 파이프라인으로 수집합니다. 일반적으로 REST API에서 2026-10-01 사용할 수 있습니다. 지식 소스는 독립적으로 생성되고, 지식 베이스에서 참조되며, 런타임에 지식 베이스를 쿼리할 때 근거 데이터로 사용됩니다.

인덱싱된 SharePoint 기술 원본을 만들 때 SharePoint 연결 문자열, 모델 및 속성을 지정하여 다음 Foundry IQ 개체를 자동으로 생성합니다.

  • SharePoint 사이트를 가리키며 연결 문자열을 변경하지 않고 사용하는 데이터 원본입니다. 생성된 데이터 원본은 SharePoint 인덱서의 TenantId 규칙을 따릅니다.
  • 다중 모달 콘텐츠를 청크하고 선택적으로 벡터화하는 기술 세트입니다.
  • 보강된 콘텐츠를 저장하고 에이전트 검색 조건을 충족하는 인덱스입니다.
  • 이전 개체를 사용하여 인덱싱 및 보강 파이프라인을 구동하는 인덱서입니다.

생성된 인덱서는 Microsoft 365의 SharePoint 인덱서를 따르며, 해당 인덱서의 필수 구성 요소, 지원되는 문서 형식 및 제한 사항은 인덱싱된 SharePoint 지식 원본에도 동일하게 적용됩니다. 자세한 내용은 SharePoint 인덱서 설명서 및 인덱서 제한을 참조하세요. 생성된 기술 세트가 외부 서비스를 호출하는 경우 해당 기술의 입력 및 서비스 제한도 적용됩니다.

contentExtractionMode 때 를 사용하여 minimal 또는 standard 콘텐츠 추출을 선택합니다. 파일, 목록 및 모던 페이지의 차이점에 대해서는 SharePoint 콘텐츠 표현을 참조하세요.

사용량 지원

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

REST 예제에서는 안정적인 2026-10-01 API를 사용합니다. SDK 예제에는 아래에 나열된 패키지 요구 사항이 그대로 적용됩니다. REST 가용성이 SDK 패키지 릴리스 상태를 의미하지는 않습니다. 미리 보기 레이블이 지정된 기능은 독립적인 상태를 유지합니다.

필수 구성 요소

  • 최신 Azure.Search.Documents 미리 보기 패키지: dotnet add package Azure.Search.Documents --prerelease

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

REST 클라이언트의 경우 사용자의 .http 파일에서 이러한 변수를 설정합니다. 이 문서의 뒷부분에 있는 리소스 관리 예제에서는 동일한 엔드포인트, API 버전 및 기술 자료 이름을 사용합니다.

@search-url = https://<search-service-name>.search.windows.net
@api-version = 2026-10-01
@knowledge-source-name = my-indexed-sharepoint-ks
@knowledge-base-name = <your-knowledge-base-name>
@sharepoint-federated-connection-string = <your-federated-connection-string>
@aoai-endpoint = https://<resource-name>.openai.azure.com

연결 문자열 자리 표시자를 구성된 페더레이션된 연결 문자열 바꿉다. 포함 배포를 호스트하는 Azure OpenAI 리소스로 설정합니다aoai-endpoint. 만들기 요청에서 embeddingModel.azureOpenAIParameters.resourceUri을 {{aoai-endpoint}}으로 바꾸고, 샘플 deploymentId를 배포 이름으로 바꾸고, modelName을 배포된 모델로 설정합니다.

삭제 예제에서도 knowledge-base-name를 사용합니다. 해당 예제를 실행하기 전에 이를 업데이트하거나 삭제하려는 참조 기술 자료로 설정합니다.

리소스 소유권 선택

이 문서에서는 기술 자료 API를 사용하여 수집을 관리하고 지원 인덱스 만들기를 수행합니다. 지식 소스에서 소스 선택, 콘텐츠 추출 및 기타 지원되는 옵션을 구성합니다. 생성된 리소스를 검토하지만 직접 편집하지 마십시오.

인덱스 스키마를 제어하거나 사용자 지정 처리 파이프라인을 빌드해야 하는 경우 SharePoint 인덱스를 구성하고 검색 인덱스 지식 원본을 통해 채워진 인덱스를 연결합니다. 원격 가져오기 및 사용자 지정 수집 대안은 SharePoint 아키텍처 선택 항목을 참조하세요.

SharePoint 그룹 권한에 대한 토폴로지 계획

애플리케이션에 SharePoint 그룹 권한이 필요한 경우 기술 자료를 만들기 전에 해당 사이트 적용 범위를 평가합니다. sharepointSiteUrl: true로 표시된 필드를 사용하는 생성된 각 인덱스는 최대 5개의 고유한 사이트 URL 값을 지원합니다. 추가 사이트 URL에 대한 쓰기가 거부됩니다. 별도의 100 URL 쿼리 시간 집계 한도는 이 제한을 증가하지 않습니다. SharePoint 그룹 권한 사이트 제한 정보를 참조하세요.

더 큰 사이트 범위의 경우 다음 토폴로지를 평가합니다.

  1. 생성된 각 인덱스가 5개 값 제한 내에 유지되도록 사이트 범위를 별도의 인덱싱된 SharePoint 기술 자료로 나눕니다. 모든 인덱스 및 파생 문서에서 필요한 사용 권한 필드와 원본 사이트 컨텍스트를 유지합니다.
  2. 소스를 지식 베이스당 최대 소스 수 이내에서 지식 베이스에 할당합니다. 예를 들어 S1은 기술 자료당 최대 10개의 원본을 지원합니다. 이 제한이 모든 서비스에 적용된다고 가정하지 말고 계층과 서비스 생성 날짜를 확인하세요.
  3. 모든 필수 데이터 원본이 하나의 기술 자료에 맞지 않는 경우 여러 기술 자료를 고려해 보세요. 이 토폴로지를 선택하기 전에 지식 소스, 지식 베이스, 인덱스 및 인덱서에 대한 서비스별 제한을 확인하세요.
  4. 여러 기술 자료 저장소에 대한 애플리케이션 수준 라우팅 또는 오케스트레이션을 구현합니다. 검색 요청은 서비스의 모든 기술 자료가 아니라 하나의 기술 자료를 대상으로 합니다. 각 요청과 결과 및 인용을 결합할 때 최종 사용자의 권한 컨텍스트를 유지하세요.

검색 수행 중 지식 소스 선택도 확인합니다. 지식 베이스에 구성된 소스 수와 요청에 대해 선택된 소스 수는 별도의 고려 사항입니다.

기존 지식 원본 확인

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

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

// 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}}

참조:Knowledge Sources - Get

다음 응답은 민감한 값을 가립니다. 다른 지식 원본을 만들기 위해 이를 다시 사용하기 전에 대상 연결 설정 및 자격 증명을 제공하거나 지원되는 비밀 없는 인증을 구성하세요; 수정된 값은 자격 증명이 아닙니다.

{
  "name": "my-indexed-sharepoint-ks",
  "kind": "indexedSharePoint",
  "description": "A sample indexed SharePoint knowledge source",
  "encryptionKey": null,
  "indexedSharePointParameters": {
    "connectionString": "<redacted>",
    "containerName": "defaultSiteLibrary",
    "query": null,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "minimal",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<redacted>",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large",
          "authIdentity": null
        }
      },
      "chatCompletionModel": null,
      "ingestionSchedule": null,
      "aiServices": null
    },
    "createdResources": {
      "datasource": "my-indexed-sharepoint-ks-datasource",
      "indexer": "my-indexed-sharepoint-ks-indexer",
      "skillset": "my-indexed-sharepoint-ks-skillset",
      "index": "my-indexed-sharepoint-ks-index"
    }
  }
}

기술 자료 만들기

다음 코드를 실행하여 인덱싱된 SharePoint 기술 자료를 만듭니다.

이 예제에서는 사이트의 기본 문서 라이브러리를 선택합니다. 다른 라이브러리, 목록, 페이지 또는 사이트를 선택하려면 indexedSharePointParameters에서 containerName 및 query을 구성하세요. SharePoint 콘텐츠 선택 옵션 및 사이트 간 선택 요구 사항을 따릅니다.

// Create an IndexedSharePoint knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure.Identity;

var foundryEndpoint = "https://<foundry-resource>.services.ai.azure.com";
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());

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

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

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

var sharePointParams = new IndexedSharePointKnowledgeSourceParameters(
    connectionString: sharePointConnectionString,
    containerName: "defaultSiteLibrary")
{
    IngestionParameters = ingestionParams
};

var knowledgeSource = new IndexedSharePointKnowledgeSource(
    name: "my-indexed-sharepoint-ks",
    indexedSharePointParameters: sharePointParams)
{
    Description = "A sample indexed SharePoint knowledge source."
};

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

참조:SearchIndexClient, IndexedSharePointKnowledgeSource

# Create an indexed SharePoint knowledge source
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import IndexedSharePointKnowledgeSource, IndexedSharePointKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceContentExtractionMode
from azure.search.documents.knowledgebases.models import KnowledgeSourceIngestionParameters, KnowledgeSourceNetworkAccessMode, KnowledgeSourceAzureOpenAIVectorizer

foundry_endpoint = "https://<foundry-resource>.services.ai.azure.com"
index_client = SearchIndexClient(endpoint = "<search-endpoint>", credential = DefaultAzureCredential())

knowledge_source = IndexedSharePointKnowledgeSource(
    name = "my-indexed-sharepoint-ks",
    description = "A sample indexed SharePoint knowledge source.",
    encryption_key = None,
    indexed_share_point_parameters = IndexedSharePointKnowledgeSourceParameters(
        connection_string = "connection_string",
        container_name = "defaultSiteLibrary",
        query = None,
        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 = foundry_endpoint,
                    deployment_name = "<aoai-gpt-deployment>",
                    model_name = "<aoai-gpt-model>",
                )
            ),
            embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
                azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
                    resource_url = foundry_endpoint,
                    deployment_name = "<aoai-embedding-deployment>",
                    model_name = "<aoai-embedding-model>",
                )
            ),
            content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
            ingestion_schedule = None,
            ingestion_permission_options = None
        )
    )
)

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

참조:SearchIndexClient

### Create an indexed SharePoint knowledge source
PUT {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "{{knowledge-source-name}}",
    "kind": "indexedSharePoint",
    "description": "A sample indexed SharePoint knowledge source.",
    "encryptionKey": null,
    "indexedSharePointParameters": {
        "connectionString": "{{sharepoint-federated-connection-string}}",
        "containerName": "defaultSiteLibrary",
        "query": null,
        "ingestionParameters": {
            "networkAccessMode": "public",
            "identity": null,
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "https://<foundry-resource>.services.ai.azure.com"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": false,
            "ingestionSchedule": null,
            "ingestionPermissionOptions": [],
            "contentExtractionMode": "minimal"
        }
    }
}

참조:지식 원본 - 만들기 또는 업데이트

표준 추출 설정

표준 추출은 선택적 이미지 설명과 함께 지원되는 SharePoint 문서의 레이아웃 인식 구문 분석 및 의미 체계 청크에 Content Understanding을 사용합니다. 필수 구성 요소에 설명된 Foundry 리소스 및 배포를 사용합니다.

만들기 또는 업데이트 요청에서 indexedSharePointParameters.ingestionParameters을 구성합니다:

  1. standard를 contentExtractionMode로 설정하고 aiServices를 Foundry 리소스 엔드포인트로 구성합니다.
  2. SharePoint 문서 사용 권한을 유지하도록 ["userIds", "groupIds"]를 ingestionPermissionOptions(으)로 설정합니다.
  3. 이미지 언어화를 위해 chatCompletionModel을 해당 Foundry 리소스에서 지원되는 모델 및 배포로 구성합니다. false을(를) disableImageVerbalization(으)로 설정된 상태로 두거나 생략합니다.
  4. resourceUri에서 https://<embedding-resource>.services.ai.azure.com를 Foundry 리소스 엔드포인트로 구성합니다. 예를 들어 embeddingModel.azureOpenAIParameters입니다. 포함 배포에 대해 modelName 및 deploymentId을 설정하고, 생성 예제의 필수 연결 설정을 유지하세요.

생성된 임베딩 기술은 벡터를 인덱스에 쓰기 전에 생성된 이미지 설명을 포함하여 Content Understanding의 청크 콘텐츠를 해당 임베딩 엔드포인트로 보냅니다.

검색은 데이터 원본, 인덱서, Content Understanding 기술 세트 및 보안 청크 인덱스를 생성합니다. 수집에 성공하면 지식 원본이 지식 기반에 할당할 준비가 되었습니다.

Content Understanding 시맨틱 청킹 및 이미지 설명은 일반적으로 Search REST API 2026-10-01에서 사용할 수 있습니다. 구성에 사용되는 API 버전은 SharePoint 커넥터 및 권한 기능도 지원하는 버전을 사용하세요.

SharePoint 인덱서와 Content Understanding 기술 모두에서 지원되는 파일을 사용합니다. 텍스트로 구문 분석된 목록 항목 또는 사이트 페이지에 파일 처리 구성을 적용하지 마세요.

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

기술, 청크 및 보안 프로젝션을 더 세밀하게 제어하려면 SharePoint 인덱서 및 Content Understanding 기술 세트 구성을 참조하세요.

수집 일정 구성

구성된 수집 일정이 없으면 인덱싱된 SharePoint 기술 소스는 기본적으로 24시간마다 생성된 인덱서가 실행됩니다. 권한 새로 고침에 더 짧은 되풀이 간격을 사용하려면 기술 자료를 만들거나 업데이트할 때 indexedSharePointParameters.ingestionParameters.ingestionSchedule를 설정합니다. interval를 XSD 기간으로 설정합니다. 예를 들어 PT5M는 5분을 나타내며, 이는 지원되는 최소 간격입니다.

일정 속성은 일정 정의를 참조하세요. 타이밍 제한에 대한 SharePoint 권한 새로 고침 권장 사항을 따릅니다. 간격은 완료 마감일 또는 권한 철회 SLA가 아닙니다.

이 기술 자료 기본값은 되풀이 일정이 아닌 요청 시 실행되는 인덱서 없이 schedule직접 만든 인덱서와 다릅니다.

언어별 자동 분석기 사용

언어별 자동 분석기는 미리 보기로 제공됩니다. 다음 섹션의 설정 및 확인 단계를 따릅니다. 생성된 인덱스에서 분석기를 직접 구성할 필요가 없습니다. 관리되는 언어 분석과 직접 구성된 언어 분석을 구분하려면 언어별 자동 분석기를 참조하세요.

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

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

키 없는 인증의 경우 Microsoft Foundry 리소스에서 Cognitive Services 사용자 역할을 생략 aiServices.apiKey 하고 Foundry IQ 서비스의 관리 ID에 할당합니다. 키 기반 인증의 경우 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년에도 새로 추가되었습니다.

첫 번째 동기화가 완료되면 lastSynchronizationState.endTime에 값이 있고 itemsUpdatesFailed이 0인지 확인합니다. 항목 처리에 실패한 경우 기술 자료를 쿼리하기 전에 보고된 오류 및 생성된 인덱서의 실행 기록을 검사합니다.

생성된 개체 검토

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

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

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

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

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

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

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

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

생성된 데이터 원본이 의도한 SharePoint 사이트 및 콘텐츠를 선택하는지 확인합니다. 알려진 원본 항목에 대해 채워진 인덱스에서 확인한 다음, 지식 베이스를 통해 검색 결과와 해당 원본 인용을 확인합니다. 리소스 만들기에 성공해도 수집이 완료되었는지는 확인되지 않습니다.

기술 자료에 할당

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

인덱싱된 SharePoint 지식 기반을 지정하는 경우 includeReferenceSourceData을(를) true로 설정해야 합니다. 이 단계는 원본 문서 URL을 인용으로 끌어와야 합니다.

지식 베이스 질의

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

문서 수준 권한 적용

명시적 사용자 및 그룹 할당을 수집하려면 ["userIds", "groupIds"]를 indexedSharePointParameters.ingestionParameters.ingestionPermissionOptions로 설정합니다. 쿼리 시 권한 적용(미리 보기)에 설명된 대로 검색 요청에 사용자의 액세스 토큰을 포함하세요.

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

필요한 그룹 유형에 대한 인증 및 권한 옵션을 선택합니다.

Authentication groupIds 포함됨 그룹 권한 수집됨
페더레이션 인증 Yes Microsoft Entra 및 네이티브 SharePoint 사이트 그룹입니다.
클라이언트 암호 Yes Microsoft Entra 그룹만.
두 방법 중 하나 No 그룹 ACL 수집 없음 명시적 사용자 할당에 대해 별도로 구성 userIds 합니다.

페더레이션된 그룹 지원을 위해서는 ACL 시나리오에 대한 Microsoft Graph 및 SharePoint 권한이 필요합니다. 생성된 인덱스에서 sharePointConnectorAppRegistration.federatedCredentialId 페더레이션 자격 증명 개체의 ID가 아닌 선택한 관리 ID의 애플리케이션 ID를 사용합니다.

권한 필터링 검색에 의존하기 전에 생성된 개체 를 검사합니다.

  1. 생성된 데이터 원본의 indexerPermissionOptions이(가) 요청된 사용자 및 그룹 수집 옵션과 일치하는지 확인합니다.
  2. 인덱스에서 permissionFilterOption이(가) 활성화되어 있고, 요청된 permissionFilter 값으로 주석이 지정된 필드와 필수 metadata_spo_item_path 소스 경로 필드가 있는지 확인합니다. 채워진 경로가 없는 기존 레코드의 경우 백필 지침을 따릅니다. 필드만 추가해도 채워지지 않습니다.
  3. 페더레이션된 groupIds의 경우 sharepointSiteUrl: true, 해당 애플리케이션 식별자, 그리고 sharePointConnectorAppRegistration로 표시된 필드를 확인합니다. 교차 사이트 선택을 포함하여 사이트 매핑이 각 항목의 metadata_spo_site_url을 사용하는지 확인합니다.
  4. 모든 청크에서 원본 경로, 요청된 사용자 및 그룹 ACL 및 해당 사이트 URL에 대한 기술 세트 프로젝션을 검사합니다. 프로젝션 생성 키와 부모 식별자를 매핑하지 않은 상태로 둡니다.
  5. 인덱서 실행 결과를 확인한 다음 ACL 확인을 사용하여 대표 문서 및 청크를 검사합니다. 수집 또는 권한 새로 고침 후 허용된 테스트 사용자 결과와 거부된 테스트 사용자 결과를 비교합니다.

SharePoint 필드 및 매핑 요구 사항을 사용하여 원본 경로, 사이트 컨텍스트, 그리고 라이브러리인지 자산 및 항목 식별 정보인지 구분합니다.

지원되는 권한 모델에는 사이트 수준 중첩 해상도 제한에 따라 5개 수준 내에서 상속된 할당 및 그룹 중첩이 포함됩니다. 조직 전체 공유 링크("조직 내 사용자")는 SharePoint ACL 수집 또는 쿼리 시간 권한 적용에 대해 지원되지 않습니다. 공유 링크 만료 적용은 지원되지 않습니다. 생성된 리소스는 만료 강제 적용을 추가하지 않습니다. 별도의 지원되는 명시적 권한 부여는 링크의 만료와 독립적입니다.

이 지식 원본은 조건부 액세스 제한을 포함한 SharePoint의 권한 모델과의 차이점 및 상속된 커넥터 제한 사항이 있는 복제된 SharePoint 권한 하위 집합을 평가합니다. 원격, 인덱싱 및 푸시 API 절충의 경우 새로 고침에 대한 검색 방법 선택을 참조하세요. 권한 업데이트는 생성된 인덱서의 SharePoint 동기화 동작을 따릅니다.

인덱싱된 SharePoint 권한 쿼리에서 누락되거나 예기치 않거나 실패한 결과는 SharePoint 권한 필터링 문제 해결을 참조하세요.

기존 지식 원본의 경우 현재 위치에서 연결 문자열 및 수집 권한 옵션을 변경할 수 없습니다. 이 설정을 변경하려면:

  1. 필요한 인증, 사이트 권한 부여 및 권한 옵션을 사용하여 대체 지식 원본을 만듭니다.
  2. 이전 단계의 검사를 사용하여 수집을 완료하고 생성된 개체를 검사합니다.
  3. 대체를 사용하도록 기술 자료를 업데이트하기 전에 허용된 사용자 결과와 거부된 사용자 결과를 확인합니다. 이전 인덱서를 다시 설정하거나 다시 동기화해도 해당 지식 원본의 사용 권한 옵션은 변경되지 않습니다.

Surface 문서에 포함된 이미지

이미지 제공은 미리 보기 상태이며 지원되는 미리 보기 API가 필요합니다.

답변 합성 응답에서 문서에 포함된 이미지(예: 다이어그램 또는 스캔)를 표시하려면 이 지식 소스에서 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}}
    

    참조:지식 소스 - 삭제

알려진 오류

생성된 SharePoint 데이터 원본 및 인덱서는 직접 구성된 SharePoint 인덱서와 동일한 Microsoft Entra 테넌트 유효성 검사 및 인증 동작을 사용합니다. 테넌트 관련 오류의 경우 생성된 인덱서의 상태 및 실행 기록을 검토한 다음 수정을 Invalid AAD tenant따릅니다.

다른 인증, 연결 또는 권한 오류의 경우 실패한 연결을 식별합니다. Foundry IQ 서비스, SharePoint 수집, 쿼리 시간 권한 확인 및 모델 또는 Foundry 엔드포인트 호출에 대한 액세스를 구분합니다.