파일 지식 소스 만들기

메모

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

Important

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

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

파일 지식 소스는 에이전트형 검색을 위해 중소형 파일 집합을 Foundry IQ에 직접 업로드합니다. 지식 원본은 독립적으로 생성되고, 지식 기반에서 참조되며, 지식 기반이 런타임에 쿼리될 때 근거 데이터로 사용됩니다.

파일 지식 원본은 Azure Storage 프로비전하고, 액세스를 구성하고, 외부 컨테이너를 통해 인덱서 파이프라인을 만드는 대신 관리되는 업로드 환경을 원하는 경우에 유용합니다. Foundry IQ는 추출된 콘텐츠를 기술 자료에서 검색할 수 있도록 업로드된 파일을 처리합니다.

파일이 이미 Azure Blob Storage 또는 Azure Data Lake Storage Gen2에 있거나, 파일 집합이 파일 지식 원본 제한을 초과하거나 초과할 가능성이 있거나, 예약된 수집이 필요한 경우에는 대신 blob 지식 원본을 사용하세요. 또한 Azure Blob Storage 수명 주기 관리 정책을 사용하여 원본 blob을 관리하려는 경우나 Azure Storage의 사용 권한을 기반으로 한 문서 수준 권한이 필요한 경우에도 blob 지식 원본을 사용합니다.

사용량 지원

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

사전 요구 사항

  • 에이전트 검색을 제공하는 모든 지역의 Foundry IQ 서비스 파일 지식 원본은 전용 및 서버리스 가격 책정 모델을 모두 지원합니다. 모델 및 계층 세부 정보는 가격 책정 모델 및 서비스 계층 선택을 참조하세요.

  • Foundry IQ 비용을 검토합니다. 모델 호출, 벡터화 및 기타 AI 처리에는 별도의 요금이 부과될 수 있습니다.

  • 서버리스에서 성공적인 파일 수집 작업은 청구 가능한 컴퓨팅을 사용합니다. 업로드에 실패해도 서버리스 컴퓨팅 요금이 발생하지 않습니다.

  • 월별 무료 수당을 초과하는 유료 에이전트 검색이 필요한 경우 표준 에이전트 검색 계획을 사용하도록 설정합니다. 이 knowledgeRetrieval=standard 설정은 서버리스 컴퓨팅 및 스토리지 요금과 별개이며 가격 책정 모델을 선택하지 않습니다.

  • 지원되는 형식의 파일입니다.

  • 지식 원본을 만들 수 있는 권한입니다. 사용자 계정에 할당된 Search Service 기여자 역할로 키 없는 인증을 구성하거나(권장) 관리자 API 키를 사용합니다.

  • Azure OpenAI 임베딩에 대한 관리 ID 호출의 경우, 와 일치하는 Azure OpenAI 또는 상위 Foundry 리소스에서 선택한 ID에 resourceUri를 할당합니다. Content Understanding 추출에는 별도의 권한이 필요합니다. 역할 할당을 참조하세요.

    • Foundry 리소스에 공용 네트워크 액세스가 비활성화된 경우 적격 전용 서비스를 사용하여 Foundry 리소스에 대한 foundry_account를 만듭니다. 신뢰할 수 있는 서비스 목록 설정에서 리소스의 Azure 서비스 허용을 사용하도록 설정합니다. 서버리스는 이 공유 프라이빗 링크 구성을 지원하지 않습니다. 지원되는 퍼블릭 엔드포인트 액세스 제어는 네트워크 보안 경계를 참조하세요. 다만 경계는 프라이빗 연결을 만들지 않습니다.

    • 지식 원본 구성 및 계층 매트릭스를 확인합니다. 파일 업로드로는 인덱서가 생성되지 않으므로 generated-indexer 네트워킹 재정의가 적용되지 않습니다.

  • 지식 원본이 콘텐츠 추출 모드를 standard 지정하는 경우 Azure Content Understanding 기술에 대한 요구 사항을 검토합니다.

    • 이 문서의 예제에서는 Foundry 리소스 엔드포인트 및 키와 Azure OpenAI 포함 및 채팅 완성 모델 정보가 필요합니다.
  • 최신 Azure.Search.Documents 미리 보기 패키지: dotnet add package Azure.Search.Documents --prerelease

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

파일 지원 및 제한

파일 기술 자료를 만들기 전에 파일 업로드, 추출 및 관리에 영향을 주는 요구 사항 및 제한을 검토합니다.

지원되는 콘텐츠 형식

Foundry IQ는 파일 바이트에서 MIME 형식을 감지합니다.

minimal 추출은 검색된 text/* 유형을 포함한 지원되는 문서 형식을 허용합니다.

standard 추출은 Azure Content Understanding 스킬에서 지원하는 파일 형식을 기준으로 더 제한적입니다. 이미지에는 standard 추출 및 지원되는 감지된 형식이 필요합니다.

지원되는 추출 모드

minimal 는 기본 제공 추출을 사용하며 기본값입니다. standard는 모든 파일을 Content Understanding으로 전송하며 aiServices 구성이 필요합니다.

  • 콘텐츠가 2026-05-01-preview(으)로 감지되었으며 image/*에서는 지원되지 않습니다. 2026-10-01에서는 standard 추출을 사용합니다. minimal 추출은 두 버전 모두에서 HTTP 상태 415를 반환합니다.

제한 및 파일 작업

제한 및 지원되는 파일 작업은 API 버전 및 수집 방법에 따라 다릅니다.

역량 2026-11-01-preview 비동기 2026-10-01 동기식 2026-08-01-preview 동기식
지식 원본당 최대 파일 수 10,000 200 200
최대 파일 크기 512MiB 무료 및 기본에서는 50MiB; 다른 지원되는 계층에서는 100MiB 무료 및 기본은 50 MiB, 지원되는 다른 Dedicated tiers 및 Serverless는 100 MiB
처리 기간 완료될 때까지 폴링 180초 180초

생성된 검색 인덱스가 업로드된 콘텐츠를 저장합니다. 가격 책정 계층별 총 스토리지 제한은 서비스 제한을 참조하세요. 벡터화를 구성하는 경우 모델 및 다운스트림 처리 제한도 적용됩니다.

기존 지식 원본 확인

C# 및 Python 예제에서는 11월 미리 보기 SDK를 사용합니다. REST 요청의 경우 2026-11-01-preview를 {{api-version}}로 설정합니다.

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

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

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

참조:지식 원본 - 가져오기

다음 JSON은 파일 지식 원본에 대한 예제 응답입니다.

{
  "name": "my-file-ks",
  "kind": "file",
  "description": "A sample file knowledge source.",
  "encryptionKey": null,
  "fileParameters": {
    "ingestionParameters": {
      "contentExtractionMode": "minimal",
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large"
        }
      }
    }
  }
}

기술 자료 만들기

업로드된 콘텐츠를 벡터화하는 데 사용되는 포함 모델을 지정하는 파일 지식 원본을 만듭니다.

각 파일 지식 원본은 인덱스는 생성하지만 인덱서나 일정은 생성하지 않습니다. fileParameters.ingestionParameters 개체를 포함해야 합니다. 서비스는 networkAccessMode를 지정한 요청을 거부합니다.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;

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

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

var ingestionParams = new KnowledgeSourceIngestionParameters
{
    ContentExtractionMode = "minimal",
    EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
    {
        AzureOpenAIParameters = embeddingParams
    }
};

var fileParams = new FileKnowledgeSourceParameters
{
    IngestionParameters = ingestionParams
};

var knowledgeSource = new FileKnowledgeSource(
    name: "my-file-ks",
    fileParameters: fileParams
)
{
    Description = "This knowledge source uses directly uploaded product manuals."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);

참조:SearchIndexClient

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    AzureOpenAIVectorizerParameters,
    FileKnowledgeSource,
    FileKnowledgeSourceParameters,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeSourceAzureOpenAIVectorizer,
    KnowledgeSourceIngestionParameters,
)

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

embedding_params = AzureOpenAIVectorizerParameters(
    resource_url="<aoai-endpoint>",
    deployment_name="<aoai-embedding-deployment>",
    model_name="<aoai-embedding-model>",
)

ingestion_params = KnowledgeSourceIngestionParameters(
    content_extraction_mode="minimal",
    embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
        azure_open_ai_parameters=embedding_params
    ),
)

knowledge_source = FileKnowledgeSource(
    name="my-file-ks",
    description="This knowledge source uses directly uploaded product manuals.",
    file_parameters=FileKnowledgeSourceParameters(ingestion_parameters=ingestion_params),
)

index_client.create_or_update_knowledge_source(knowledge_source=knowledge_source)

참조:SearchIndexClient

PUT {{searchEndpoint}}/knowledgesources('my-file-ks')?api-version=2026-10-01
Authorization: ******
Content-Type: application/json
Prefer: return=representation

{
  "name": "my-file-ks",
  "kind": "file",
  "description": "This knowledge source uses directly uploaded product manuals.",
  "encryptionKey": null,
  "fileParameters": {
    "ingestionParameters": {
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "{{aoai-embedding-deployment}}",
          "modelName": "{{aoai-embedding-model}}"
        }
      },
      "contentExtractionMode": "minimal"
    }
  }
}

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

새 원본의 경우 200가 예상됩니다(201 기존 원본을 업데이트합니다). 정의를 다시 읽어 이름, 종류 및 생성된 인덱스를 확인하세요.

GET {{searchEndpoint}}/knowledgesources('my-file-ks')?api-version=2026-10-01
Authorization: ******

참조:지식 소스

표준 추출 설정

standard API 버전부터 2026-08-01-preview 추출은 Content Understanding을 사용하여 업로드된 파일에서 추출하고, 의미 단위로 청크화하고, 보강합니다. Foundry IQ는 aiServices에 지정된 Foundry 리소스를 사용하여 수집 파이프라인을 관리합니다.

C# 및 Python 구성 예제에서는 11월 미리 보기 SDK를 사용합니다. REST 예제에서는 2026-11-01-preview를 사용합니다. 사용하기 전에 Content Understanding 요구 사항을 검토합니다.

표준 설정은 구성된 Content Understanding 계정에 계정 전체 모델 매핑을 추가할 수 있습니다. 표준 원본을 만들거나 업데이트하기 전에 공유 구성을 확인합니다. 최소 설정은 해당 계정을 구성하거나 모델 자격 증명을 사용하도록 해당 계정을 구성하지 않습니다.

표준 추출에는 Content Understanding 요금이 발생하며, 이미지 설명 생성이 사용하도록 설정된 경우 모델 사용 요금도 발생합니다. 자세한 내용은 청구 및 이미지 설명 컨트롤을 참조하세요.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;

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

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

var ingestionParameters = new KnowledgeSourceIngestionParameters
{
  ContentExtractionMode = KnowledgeSourceContentExtractionMode.Standard,
  AiServices = new AIServices(new Uri(foundryEndpoint)) { ApiKey = foundryKey },
  EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
  {
    AzureOpenAIParameters = embeddingParameters
  },
  ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(
    new AzureOpenAIVectorizerParameters
    {
      ResourceUri = new Uri(aoaiEndpoint),
      DeploymentName = aoaiChatDeployment,
      ModelName = aoaiChatModel
    })
};

var knowledgeSource = new FileKnowledgeSource(
  "my-file-ks",
  new FileKnowledgeSourceParameters { IngestionParameters = ingestionParameters });

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);

참조:SearchIndexClient

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
  AzureOpenAIVectorizerParameters,
  FileKnowledgeSource,
  FileKnowledgeSourceParameters,
  KnowledgeBaseAzureOpenAIModel,
)
from azure.search.documents.knowledgebases.models import (
  AIServices,
  KnowledgeSourceAzureOpenAIVectorizer,
  KnowledgeSourceIngestionParameters,
)

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

embedding_parameters = AzureOpenAIVectorizerParameters(
  resource_url="<aoai-endpoint>",
  deployment_name="<aoai-embedding-deployment>",
  model_name="<aoai-embedding-model>",
)
ingestion_parameters = KnowledgeSourceIngestionParameters(
  content_extraction_mode="standard",
  ai_services=AIServices(
    uri="<foundry-resource-endpoint>",
    api_key="<foundry-resource-key>",
  ),
  embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
    azure_open_ai_parameters=embedding_parameters
  ),
  chat_completion_model=KnowledgeBaseAzureOpenAIModel(
    azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
      resource_url="<aoai-endpoint>",
      deployment_name="<aoai-gpt-deployment>",
      model_name="<aoai-gpt-model>",
    )
  ),
)
knowledge_source = FileKnowledgeSource(
  name="my-file-ks",
  file_parameters=FileKnowledgeSourceParameters(
    ingestion_parameters=ingestion_parameters
  ),
)

index_client.create_or_update_knowledge_source(knowledge_source)

참조:SearchIndexClient

PUT {{searchEndpoint}}/knowledgesources('my-file-ks')?api-version=2026-11-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}
Prefer: return=representation

{
  "name": "my-file-ks",
  "kind": "file",
  "description": "This knowledge source uses standard extraction.",
  "fileParameters": {
    "ingestionParameters": {
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "{{aoai-embedding-deployment}}",
          "modelName": "{{aoai-embedding-model}}"
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "{{aoai-gpt-deployment}}",
          "modelName": "{{aoai-gpt-model}}"
        }
      },
      "contentExtractionMode": "standard",
      "aiServices": {
        "uri": "{{foundry-resource-endpoint}}",
        "apiKey": "{{foundry-resource-key}}"
      }
    }
  }
}

참조:Knowledge Sources - 만들기 또는 업데이트

파일 작업에 대한 CORS

파일 업로드, 나열, 업데이트 및 삭제에 대해 신뢰할 수 있는 브라우저 원본을 허용하도록 전체 소스 정의에서 corsOptions를 설정합니다.

Important

2026-10-01 API 버전 corsOptions 에서는 추출 모드와 독립적으로 파일 업로드, 나열, 업데이트 및 삭제 엔드포인트에 적용됩니다. corsOptions를 생략하면 파일 지식 원본에는 브라우저 교차 출처 정책이 적용되지 않습니다. CORS는 요청에 권한을 부여하지 않습니다. 원본을 사용하도록 설정하면 브라우저 컨텍스트에서 서비스 작업 및 데이터를 노출하고 보안 위험을 초래할 수 있습니다. 신뢰할 수 있는 원본만 지정하고 프로덕션 환경에서 와일드카드 원본을 사용하지 마세요. 브라우저 요청의 경우 필요한 최소 역할로 Microsoft Entra 토큰 인증을 사용합니다. 브라우저 코드에서 액세스 토큰 또는 서비스 키를 노출하지 않습니다.

PUT {{searchEndpoint}}/knowledgesources('my-file-ks')?api-version=2026-10-01
api-key: {{searchAdminKey}}
Content-Type: application/json

{
  "name": "my-file-ks",
  "kind": "file",
  "fileParameters": {
    "ingestionParameters": {
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "{{aoai-embedding-deployment}}",
          "modelName": "{{aoai-embedding-model}}"
        }
      },
      "contentExtractionMode": "minimal"
    }
  },
  "corsOptions": {
    "allowedOrigins": ["https://files.example.com"],
    "maxAgeInSeconds": 300
  }
}

참조:지식 소스

OPTIONS {{searchEndpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-10-01
Origin: https://files.example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: authorization,content-type

참조:지식 소스

파일 업로드

지식 소스를 만든 후 다중 파트 업로드를 사용하여 파일을 직접 업로드합니다. 각 업로드는 동기 호출입니다. Foundry IQ는 콘텐츠를 추출하고, 청크로 분할하고, 필요한 경우 포함을 만들고, 청크를 인덱싱하고, 파일 메타데이터를 저장합니다. 별도의 수집 파이프라인을 설정하거나 실행할 필요가 없습니다.

파일 업로드 및 관리와 관련된 오류에 대한 도움말은 파일 작업 문제 해결을 참조하세요.

POST {{searchEndpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-10-01
Authorization: ******
Content-Type: multipart/form-data; boundary=file-boundary

--file-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
  "fileName": "manuals/handbook.txt"
}
--file-boundary
Content-Disposition: form-data; name="content"; filename="handbook.txt"
Content-Type: application/octet-stream

Employees request production access through the engineering access portal.
--file-boundary--

참조:지식 소스

원시 파일 업로드

원시 업로드는 미리 보기 API에서만 사용할 수 있습니다. GA 파일 업로드의 경우 파일 업로드를 참조하세요.

C# 및 Python 원시 예제는 11월 미리 보기 SDK를 사용합니다. REST 예제에서는 2026-11-01-preview 동기 엔드포인트를 사용합니다.

파일 이름에는 다음과 같은 manuals/installation-guide.pdf상대 경로가 포함될 수 있습니다. 서비스는 백슬래시(\)를 슬래시(/)로 정규화합니다. 절대 경로, 빈 경로 세그먼트 또는 .. 세그먼트, . 콜론이 포함된 세그먼트 및 HTTP 상태400의 잘못된 파일 이름 문자를 거부합니다.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

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

string fileName = "installation-guide.pdf";
byte[] fileBytes = await File.ReadAllBytesAsync(fileName);
string contentDisposition = $"attachment; filename=\"{fileName}\"";

KnowledgeSourceFile uploadedFile = (await indexClient.UploadKnowledgeSourceFileAsync(
    "my-file-ks",
    contentDisposition,
    BinaryData.FromBytes(fileBytes))).Value;

참조:SearchIndexClient.UploadKnowledgeSourceFileAsync

from pathlib import Path

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

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

file_path = Path("installation-guide.pdf")
uploaded_file = index_client.upload_knowledge_source_file(
    "my-file-ks",
    file_path.read_bytes(),
    filename=file_path.name,
)

참조:SearchIndexClient.upload_knowledge_source_file

원시 파일 바이트를 미리 보기 동기 엔드포인트로 보냅니다. application/octet-stream는 텍스트 콘텐츠에도 사용합니다.

POST {{searchEndpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-11-01-preview
Authorization: ******
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="manuals/raw-handbook.txt"

Employees request production access through the engineering access portal.

참조:지식 소스

선택적 메타데이터를 사용하여 파일 업로드

다중 파트 요청을 사용하여 하나의 이진 파일을 업로드합니다. JSON 개체가 있는 파트 metadata 하나와 비어 있지 않은 부분을 추가합니다 content . metadata 파트는 사용자 지정 메타데이터가 없더라도 필요합니다. 이 경우 {}를 사용합니다. 사용자 지정 메타데이터를 추가하는 경우 문자열 값의 플랫 백을 사용합니다.

두 이름이 모두 지정된 경우 content 부분의 파일 이름보다 metadata.fileName가 우선합니다. 둘 다 지정하지 않으면 서비스는 자동 생성된 파일 이름을 할당합니다.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var metadata = new FileUploadMetadata
{
  FileName = "installation-guide.pdf",
  Metadata =
  {
    ["department"] = "support",
    ["product"] = "contoso-100"
  }
};

#pragma warning disable SCME0004
var request = new UploadKnowledgeSourceFileMultipartRequest(
  metadata,
  "installation-guide.pdf");
KnowledgeSourceFile uploadedFile = (await indexClient
  .UploadKnowledgeSourceFileMultipartAsync("my-file-ks", request)).Value;
#pragma warning restore SCME0004

참조:SearchIndexClient.UploadKnowledgeSourceFileMultipartAsync

from pathlib import Path

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
  FileUploadMetadata,
  UploadKnowledgeSourceFileMultipartRequest,
)

index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
file_path = Path("installation-guide.pdf")
request = UploadKnowledgeSourceFileMultipartRequest(
  metadata=FileUploadMetadata(
    file_name=file_path.name,
    metadata={"department": "support", "product": "contoso-100"},
  ),
  content=(file_path.name, file_path.read_bytes(), "application/pdf"),
)

uploaded_file = index_client.upload_knowledge_source_file_multipart(
  name="my-file-ks",
  body=request,
)

참조:SearchIndexClient.upload_knowledge_source_file_multipart

POST {{search-endpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: multipart/form-data; boundary=file-boundary

--file-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
  "fileName": "installation-guide.pdf",
  "metadata": {
    "department": "support",
    "product": "contoso-100"
  }
}
--file-boundary
Content-Disposition: form-data; name="content"; filename="installation-guide.pdf"
Content-Type: application/octet-stream

< ./installation-guide.pdf
--file-boundary--

참조:Knowledge Sources - 파일 업로드

파일을 업로드해도 동일한 fileName파일을 다시 사용하는 경우에도 기존 파일이 대체되지 않습니다. 업로드에 성공한 각 파일은 자체 fileId적으로 새 파일을 만들므로 업로드된 파일 목록에는 공유 fileName되는 여러 항목이 포함될 수 있습니다.

업로드된 파일 나열

지식 소스의 파일을 나열해 업로드된 파일 세트를 확인합니다.

using System.Collections.Generic;
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var files = new List<KnowledgeSourceFile>();
await foreach (KnowledgeSourceFile file in indexClient.GetAllKnowledgeSourceFilesAsync("my-file-ks"))
{
  files.Add(file);
}

참조:SearchIndexClient

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
files = list(index_client.list_knowledge_source_files("my-file-ks"))

참조:SearchIndexClient.list_knowledge_source_files

GET {{searchEndpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-10-01
Authorization: ******

참조:지식 소스

응답에는 업로드된 각 파일에 대한 메타데이터가 포함됩니다. 성공적으로 나열된 파일의 errorMessage 값은 null입니다.

{
  "value": [
    {
      "fileId": "file-abc123",
      "fileName": "installation-guide.pdf",
      "fileSizeBytes": 1048576,
      "createdAt": "2026-05-07T18:10:00Z",
      "lastUpdatedAt": "2026-05-07T18:14:00.803Z",
      "errorMessage": null
    }
  ]
}

새 업로드가 실패하면 요청이 오류를 반환하고 파일 메타데이터 레코드를 만들지 않습니다.

파일 나열 및 필터링

파일을 나열할 때 다음 쿼리 매개 변수를 사용하여 결과를 필터링하고 페이지별로 확인합니다.

  • prefix: 대/소문자를 구분하여 전체 상대 파일 이름의 시작 부분과 일치하는지 확인합니다. 슬래시 또는 점이 포함된 경로에는 prefix가 아니라 search를 사용합니다.
  • search: 전체 상대 파일 이름에서 대/소문자를 구분하지 않는 시작 일치를 수행합니다. 영문 소문자, 숫자, 하이픈 및 밑줄로 구성되고 영문 소문자 또는 숫자로 시작하는 resource-name-prefix 구문만 허용합니다. 이 일치 모드를 선택하려면 prefix를 유일하게 지원되는 값인 searchType로 설정합니다. 이 값은 별도의 search 매개 변수가 아니라 prefix에 적용됩니다.
  • pageSize: 최소 1, 최대 3,000, 기본값은 3,000입니다.
using System.Collections.Generic;
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var filteredFiles = new List<KnowledgeSourceFile>();
await foreach (KnowledgeSourceFile file in indexClient.GetAllKnowledgeSourceFilesAsync(
  "my-file-ks",
  prefix: "manuals/",
  pageSize: 100))
{
  filteredFiles.Add(file);
}

참조:SearchIndexClient

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

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

files = list(index_client.list_knowledge_source_files(
  "my-file-ks",
  prefix="manuals/",
  page_size=100,
))

참조:SearchIndexClient.list_knowledge_source_files

GET {{searchEndpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-10-01&prefix=manuals%2F&search=manuals&searchType=prefix&pageSize=1
Authorization: ******

참조:지식 소스

응답에는 서비스 선택 구문 분석 및 추출 모드와 파일 관리를 위한 사용자 메타데이터가 포함됩니다. 사용자 메타데이터는 검색하거나 필터링할 수 없습니다.

{
  "value": [
    {
      "fileId": "file-abc123",
      "fileName": "manuals/installation-guide.md",
      "prefix": "manuals/",
      "metadata": {
        "department": "support",
        "product": "contoso-100"
      },
      "parsingMode": "markdown",
      "extractionMode": "minimal",
      "fileSizeBytes": 1048576,
      "createdAt": "2026-08-03T18:10:00Z",
      "lastUpdatedAt": "2026-08-03T18:14:00Z",
      "errorMessage": null
    }
  ],
  "@odata.nextLink": "<service-generated continuation URL>"
}

모든 결과를 가져오려면 @odata.nextLink가 더 이상 없을 때까지 이를 따르세요. 쿼리 매개 변수를 변경하지 않고 반환된 대로 정확하게 전체 URL을 보냅니다.

업로드된 파일 업데이트

반환fileId된 요청을 전송 PUT 하여 파일을 업데이트합니다. 파일 이름을 유지하려면 다시 포함합니다 fileName .

사용자 지정 metadata 모음을 생략하거나 설정 null하면 이전 사용자 지정 메타데이터 값이 유지됩니다. 사용자 지정 metadata 백을 제공하는 경우 이전 가방을 병합하는 대신 바꿉니다. 사용자 지정 메타데이터 모음 "metadata": {}을 지우려면 .

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var metadata = new FileUploadMetadata
{
  FileName = "installation-guide.pdf",
  Metadata =
  {
    ["department"] = "support",
    ["product"] = "contoso-200"
  }
};

#pragma warning disable SCME0004
var request = new UpdateKnowledgeSourceFileRequest(
  metadata,
  "installation-guide.pdf");
KnowledgeSourceFile updatedFile = (await indexClient.UpdateKnowledgeSourceFileAsync(
  fileId,
  "my-file-ks",
  request)).Value;
#pragma warning restore SCME0004

참조:SearchIndexClient.UpdateKnowledgeSourceFileAsync

from pathlib import Path

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
  FileUploadMetadata,
  UpdateKnowledgeSourceFileRequest,
)

index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
file_path = Path("installation-guide.pdf")
request = UpdateKnowledgeSourceFileRequest(
  metadata=FileUploadMetadata(
    file_name=file_path.name,
    metadata={"department": "support", "product": "contoso-200"},
  ),
  content=(file_path.name, file_path.read_bytes(), "application/pdf"),
)

updated_file = index_client.update_knowledge_source_file(
  name="my-file-ks",
  file_id=file_id,
  body=request,
)

참조:SearchIndexClient.update_knowledge_source_file

PUT {{search-endpoint}}/knowledgesources('my-file-ks')/files('{{file-id}}')?api-version=2026-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: multipart/form-data; boundary=file-boundary

--file-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
  "fileName": "installation-guide.pdf",
  "metadata": {
    "department": "support",
    "product": "contoso-200"
  }
}
--file-boundary
Content-Disposition: form-data; name="content"; filename="installation-guide.pdf"
Content-Type: application/octet-stream

< ./installation-guide.pdf
--file-boundary--

참조:지식 소스 - 파일 업데이트

업데이트에 실패하면 이전 메타데이터 레코드가 유지되지만 이전 인덱싱된 콘텐츠는 이미 제거되었을 수 있습니다.

업로드된 파일 삭제

더 이상 검색에 사용할 수 없도록 하려면 기술 원본에서 파일을 삭제합니다.

using Azure.Identity;
using Azure.Search.Documents.Indexes;

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

await indexClient.DeleteKnowledgeSourceFileAsync("my-file-ks", "file-abc123");

참조:SearchIndexClient.DeleteKnowledgeSourceFileAsync

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

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

index_client.delete_knowledge_source_file("my-file-ks", "file-abc123")

참조:SearchIndexClient.delete_knowledge_source_file

DELETE {{searchEndpoint}}/knowledgesources('my-file-ks')/files('{{fileId}}')?api-version=2026-10-01
Authorization: ******

참조:지식 소스

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

파일을 비동기적으로 수집(미리 보기)

별도의 :ingest 작업을 사용하여 백그라운드에서 파일을 처리합니다. 비동기 수집 및 작업 모니터링에는 2026-11-01-preview이(가) 필요합니다.

  • 비동기 수집은 고객 관리형 키로 보호되는 지식 소스를 지원하지 않습니다.
  • 비동기 수집은 스로틀링 중에 503를 반환할 수 있습니다.
using Azure;
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

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

var initialMetadata = new FileUploadMetadata
{
  FileName = "manuals/async-handbook.txt",
  Metadata = { ["stage"] = "initial" }
};

var ingestRequest = new UploadKnowledgeSourceFileMultipartRequest(
  initialMetadata,
  BinaryData.FromString(
    "Employees request production access through the engineering access portal."));
Operation<KnowledgeSourceFile> ingestOperation = await asyncIndexClient
  .IngestKnowledgeSourceFileMultipartAsync(
    WaitUntil.Completed,
    "my-file-ks",
    ingestRequest);
KnowledgeSourceFile ingestedFile = ingestOperation.Value;

var updatedMetadata = new FileUploadMetadata
{
  FileName = "manuals/async-handbook.txt",
  Metadata = { ["stage"] = "updated" }
};
var replacementRequest = new UpdateKnowledgeSourceFileRequest(
  updatedMetadata,
  BinaryData.FromString(
    "Employees request production access through the engineering access portal. " +
    "Manager approval is required before access is granted."));
Operation<KnowledgeSourceFile> replacementOperation = await asyncIndexClient
  .IngestKnowledgeSourceFileReplacementAsync(
    WaitUntil.Completed,
    "my-file-ks",
    ingestedFile.FileId,
    replacementRequest);
KnowledgeSourceFile replacedFile = replacementOperation.Value;

참조:SearchIndexClient

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
  FileUploadMetadata,
  UpdateKnowledgeSourceFileRequest,
  UploadKnowledgeSourceFileMultipartRequest,
)

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

ingest_request = UploadKnowledgeSourceFileMultipartRequest(
  metadata=FileUploadMetadata(
    file_name="manuals/async-handbook.txt",
    metadata={"stage": "initial"},
  ),
  content=(
    "handbook.txt",
    b"Employees request production access through the engineering access portal.",
    "application/octet-stream",
  ),
)
ingest_poller = async_index_client.begin_ingest_knowledge_source_file_multipart(
  name="my-file-ks",
  body=ingest_request,
)
ingested_file = ingest_poller.result()

replacement_request = UpdateKnowledgeSourceFileRequest(
  metadata=FileUploadMetadata(
    file_name="manuals/async-handbook.txt",
    metadata={"stage": "updated"},
  ),
  content=(
    "handbook.txt",
    (
      b"Employees request production access through the engineering access portal. "
      b"Manager approval is required before access is granted."
    ),
    "application/octet-stream",
  ),
)
replacement_poller = (
  async_index_client.begin_ingest_knowledge_source_file_replacement(
    name="my-file-ks",
    file_id=ingested_file.file_id,
    body=replacement_request,
  )
)
replaced_file = replacement_poller.result()

참조:SearchIndexClient

수집 시작 및 완료 모니터링

리터럴 멀티파트 메타데이터 및 콘텐츠가 포함된 파일 하나를 업로드합니다.

POST {{searchEndpoint}}/knowledgesources('my-file-ks')/files:ingest?api-version=2026-11-01-preview
Authorization: ******
Content-Type: multipart/form-data; boundary=file-boundary

--file-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
  "fileName": "manuals/async-handbook.txt",
  "metadata": {
    "stage": "initial"
  }
}
--file-boundary
Content-Disposition: form-data; name="content"; filename="handbook.txt"
Content-Type: application/octet-stream

Employees request production access through the engineering access portal.
--file-boundary--

참조:지식 소스

202이 예상됩니다. 지연 후 Retry-After 작업이 완료될 때까지 URL Operation-Location 을 폴링합니다.

GET {{operationLocation}}
Authorization: ******
Accept: application/json

참조:지식 원본

수집이 진행되는 동안과 완료된 후 모니터가 HTTP 200를 반환합니다. status를 확인하여 결과를 확인하세요.

status 액션
NotStarted, Running Retry-After를 기다린 다음 동일한 URL을 다시 폴링합니다.
Succeeded {{asyncFileId}}을(를) result.fileId로 저장하고 result.createdAt은(는) 교체 확인을 위해 보관합니다.
Failed 중지하고 error.code(OperationFailed) 및 error.message을(를) 검사합니다.
Canceled 멈추십시오. 작업이 성공하지 못했습니다.

파일을 비동기적으로 바꾸기

해당 파일을 바꾸기 전에 업로드가 성공할 때까지 기다립니다. 반환된 파일 ID와 함께 별도의 POST 작업을 보냅니다.

POST {{searchEndpoint}}/knowledgesources('my-file-ks')/files('{{asyncFileId}}'):ingest?api-version=2026-11-01-preview
Authorization: ******
Content-Type: multipart/form-data; boundary=file-boundary

--file-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
  "fileName": "manuals/async-handbook.txt",
  "metadata": {
    "stage": "updated"
  }
}
--file-boundary
Content-Disposition: form-data; name="content"; filename="handbook.txt"
Content-Type: application/octet-stream

Employees request production access through the engineering access portal. Manager approval is required before access is granted.
--file-boundary--

참조:지식 출처

202이 예상됩니다. 이 응답의 {{replacementOperationLocation}}을(를) Operation-Location로 저장하고 해당 Retry-After을(를) 준수합니다. 동일한 40-GET-or-20-minute client policy and unresolved-outcome handling을 대체 모니터링에 적용합니다.

GET {{replacementOperationLocation}}
Authorization: ******
Accept: application/json

참조:지식 원본

Succeeded 후, result.fileId 및 result.createdAt가 원본 파일과 일치하는지 확인합니다.

유지된 작업 목록

목록 파일과 별도로 이 지식 소스에 속하는 모니터를 나열합니다.

GET {{searchEndpoint}}/knowledgesources('my-file-ks')/files/operations?api-version=2026-11-01-preview
Authorization: ******

참조:지식 소스

지식 원본 삭제

다음 C# 및 Python 예제에서는 11월 미리 보기 SDK를 사용합니다. REST 요청의 경우 2026-11-01-preview를 {{api-version}}로 설정합니다.

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

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

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

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

    참조:지식 소스 - 삭제

DELETE {{searchEndpoint}}/knowledgesources('my-file-ks')?api-version=2026-10-01
Authorization: ******

참조:지식 소스

204이 예상됩니다. 정리하기 전에 모든 비동기 작업이 완료되기를 기다립니다.

파일 작업 문제 해결

다음 상태 코드는 파일 기술 자료 작업과 관련이 있습니다.

상태 코드 원인 및 조치
400 빈 콘텐츠, 누락되거나 중복된 다중 파트 부분, 잘못된 메타데이터 JSON, 안전하지 않은 상대 경로 및 잘못된 목록 쿼리를 확인합니다.
404 요청된 범위에 파일, 소스 또는 작업 모니터가 없습니다. 실제 응답의 source 및 ID를 사용합니다. 반복된 파일 삭제 시에도 404가 반환됩니다.
409 유효 파일 수가 소진되거나 변경이 활성 비동기 수집과 충돌합니다. 리소스를 수정하거나 삭제하기 전에 종료 작업이 끝날 때까지 기다립니다.
413 파일 바이트가 엔드포인트 및 계층의 유효 크기 제한을 초과합니다. 파일 크기를 줄입니다.
415 동기 업로드에서 지원되지 않는 MIME 형식을 감지했거나 지원되지 않는 외부 콘텐츠 형식을 사용했습니다. 이미지의 경우 표준 추출 및 명시적으로 지원되는 형식을 선택합니다. 제공된 MIME 형식을 변경해도 감지가 재정의되지 않습니다.
503 비동기 수집을 사용할 수 없거나 적격 작업자가 없습니다. 인덱싱 종속성은 이 상태를 반환할 수도 있습니다.
504 동기 처리가 구성된 시간 제한을 초과했습니다(기본적으로 180초). 파일 크기 또는 복잡성을 줄입니다. 이는 비동기 폴링 마감일이 아닙니다.