你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

创建文件知识源（预览版）

注释

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。 它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

Important

标记为“预览”的特性、功能或属性不受服务级别协议 (SLA) 保障，不建议用于生产工作负载，并且在正式发布之前可能会更改或受到限制。 Azure AI 搜索预览条款适用于所有预览功能，无论是独立功能还是正式版功能的一部分。

文件知识源（预览版）将小型文件集直接上传到Azure AI 搜索进行代理检索。 知识库是在运行时查询知识库时独立创建的、在知识库中引用的，并用作基础数据。

如果需要托管上传体验，而不是预配Azure 存储、配置访问权限以及通过外部容器创建索引器管道，则文件知识源非常有用。 Azure AI 搜索处理上传的文件，以便从知识库检索其提取的内容。

如果文件已存储在 Azure Blob 存储 或 Azure Data Lake Storage Gen2 中，如果文件集已超过或可能会超过 文件知识源限制，或者如果需要计划内引入，请改用 Blob 知识源。 如果需要使用 Azure Blob 存储 生命周期管理策略管理源 Blob，或者需要基于 Azure 存储 权限的文档级权限（预览），也请使用 Blob 知识源。

使用支持

Azure 门户 Microsoft Foundry 门户 .NET SDK Python SDK Java SDK JavaScript SDK REST API
❌ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

先决条件

  • 在任意提供代理检索功能的区域中提供的 Azure AI 搜索服务。 文件知识源支持专用和无服务器定价模型。 有关模型和层详细信息，请参阅 “选择定价模型和服务层”。

  • 查看Azure AI 搜索 的费用。 模型调用、矢量化和其他 AI 处理可能会产生单独的费用。

  • 在无服务器环境中，成功的文件摄取操作会消耗计费计算资源。 失败的上传不会产生无服务器计算费用。

  • 如果需要超出每月免费津贴的付费代理检索， 请启用标准代理检索计划。 该 knowledgeRetrieval=standard 设置独立于无服务器计算和存储费用，不选择定价模型。

  • 受支持格式的文件。

  • 创建知识源的权限。 使用分配给用户帐户的搜索服务参与者角色（建议）或使用管理员 API 密钥配置无密钥身份验证。

  • 如果知识源指定使用 Azure OpenAI 模型进行嵌入，则搜索服务必须具有托管标识，并且该标识在 Microsoft Foundry 资源上具有Cognitive Services User权限。

  • 如果知识源指定standard内容提取模式，请查看Azure内容理解技能的要求。

    • 使用量将按照 Foundry Tools 中 Azure 内容理解的定价计费，并计入通过 aiServices 配置的 Foundry 资源。

    • 某些内置技能可享有的每日 20 份免费额度不适用。

    • 对于本文中的示例，需要 Foundry 资源终结点和密钥，以及Azure OpenAI 嵌入和聊天完成模型信息。

  • 最新的 Azure.Search.Documents 预览包：dotnet add package Azure.Search.Documents --prerelease

  • 对于无密钥身份验证，请使用 Azure.Identity 软件包：dotnet add package Azure.Identity

  • 最新的 azure-search-documents 预览包：pip install --pre azure-search-documents

  • 对于无密钥身份验证，请使用 azure-identity 软件包：pip install azure-identity

文件支持和限制

在创建文件知识源之前，请查看影响文件上传、提取和管理的要求和限制。

支持的内容类型

文件知识源接受基于检测到的内容类型的文件。 调用方提供的内容类型不会替代检测。

受支持的内容类型包括：

  • PDF
  • Word （.doc， .docx）
  • PowerPoint （.ppt， .pptx）
  • Excel （.xls， .xlsx）
  • JSON
  • Shell 脚本
  • 检测到 text/*的内容，例如 .txt、 .md、 .html和 .csv

支持的提取模式

  • 对于所列内容类型，2026-05-01-preview和2026-08-01-preview均支持minimal。 standard 仅在 2026-08-01-preview 中可用。

  • 检测为2026-05-01-preview的内容在image/*中不受支持。 在 2026-08-01-preview 中，使用 standard 提取方式。 minimal 提取操作在两个版本中均返回 HTTP 状态 415。

限制和文件操作

限制和支持的文件操作因 API 版本而异。

能力 2026-05-01-preview 2026-08-01-preview
每个知识源的最大文件数 100 200
文件大小上限 所有受支持的定价层级均为 50 MB 免费版和基本版为 50 MB；其他受支持的专用层级和无服务器层级为 100 MB
处理持续时间 上传最长可持续 180 秒 上传和更新最多可以运行 180 秒
上传内容和元数据 原始文件内容 包含元数据的原始文件内容或多部分内容
列出上传的文件 列出文件 按路径或文件名进行筛选，并返回更丰富的文件详细信息
替换现有文件内容 删除并重新上传 执行更新操作
浏览器对文件操作的访问 CORS 不可用 配置 CORS

注释

  • 生成的搜索索引存储上传的内容。 有关按定价层排序的总存储限制，请参阅 服务限制。
  • 如果将文件知识源配置为区块或向量化上传的内容，则模型和下游处理限制也适用。

检查现有知识源

知识源是顶级可重用对象。 了解现有知识源有助于重复使用或命名新对象。

运行以下代码，按名称和类型列出知识源。

// 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}");
}

Reference：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})")

Reference：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));

Reference：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))

Reference：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;

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);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

Reference：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)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

Reference：SearchIndexClient

PUT {{search-endpoint}}/knowledgesources/my-file-ks?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
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"
    }
  }
}

参考：知识源 - 创建或更新

配置标准提取

从 2026-08-01-preview API 版本开始， standard 提取使用内容理解来提取、语义化区块和扩充上传的文件。 Azure AI 搜索 将此处理作为知识源的一部分进行管理，且 内容理解费用 另行计费。

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);
Console.WriteLine($"Configured standard extraction for '{knowledgeSource.Name}'.");

Reference：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)
print(f"Configured standard extraction for '{knowledge_source.name}'.")

Reference：SearchIndexClient

PUT {{search-endpoint}}/knowledgesources/my-file-ks?api-version=2026-08-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}}"
      }
    }
  }
}

参考：知识源 - 创建或更新

用于文件操作的 CORS

若要允许基于浏览器的文件操作，请在具有受信任源的文件知识源上设置 corsOptions ，并为应用程序设置最大预检缓存持续时间。

Important

在 2026-08-01-preview API 版本中， corsOptions 适用于独立于提取模式的文件上传、列出、更新和删除终结点。 如果省略 corsOptions，则文件知识源没有浏览器跨源策略。 CORS 不授权请求。 启用源可以在浏览器上下文中公开服务操作和数据，并引入安全风险。 仅指定受信任的源，并且不要在生产中使用通配符源。 对于浏览器请求，请使用 Microsoft Entra 令牌身份验证，并按需分配最低角色。 切勿在浏览器代码中公开访问令牌或服务密钥。

上传文件

创建知识源后，将文件直接上传到该源。 每个上传都是同步调用：Azure AI 搜索提取内容、分块、在需要时创建嵌入、为区块编制索引，并在调用返回之前保留文件元数据。 无需配置或运行单独的引入管道。

有关上传和管理文件相关的错误的帮助，请参阅 文件操作疑难解答。

上传原始文件

对于原始上传方式，所列出的 fileName 取自 Content-Disposition: attachment; filename="..." 标头。 REST 调用和.NET SDK 直接设置此标头，而 Python SDK 接受 filename 参数并自动生成标头。 如果您未提供文件名，该服务将分配一个自动生成的 fileName。

文件名可以包含相对路径，例如 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;

Console.WriteLine($"Uploaded file ID: {uploadedFile.FileId}");

Reference：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,
)
print(f"Uploaded file ID: {uploaded_file.file_id}")

参考：SearchIndexClient.upload_knowledge_source_file

POST {{search-endpoint}}/knowledgesources/my-file-ks/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="installation-guide.pdf"

<binary file content>

参考：知识源 - 上传文件

上传具有可选元数据的文件

从 2026-08-01-preview API 版本开始，使用多部分请求上传一个具有可选自定义元数据的二进制文件。 该请求只包括一个 content 部分和一个可选的 JSON metadata 部件。

如果同时指定了两个名称， metadata.fileName 则优先于部件 content 上的文件名。 如果未指定这两个名称，服务将分配自动生成的文件名。

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

Console.WriteLine($"Uploaded file ID: {uploadedFile.FileId}");

参考：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,
)
print(f"Uploaded file ID: {uploaded_file.file_id}")

参考：SearchIndexClient.upload_knowledge_source_file_multipart

POST {{search-endpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-08-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--

参考：知识源 - 上传文件

注释

上传文件不会替换现有文件，即使重复使用相同 fileName文件也是如此。 每次成功上传都会创建一个带有其自身 fileId 的新文件，因此已上传文件的列表中可能包含多个共享同一 fileName 的条目。

使用 2026-05-01-preview，通过删除原文件并上传替换文件来替换内容。 对于 2026-08-01-preview，请使用更新操作。

列出上传的文件

列出知识源上的文件以检查上传的文件集。

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

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

await foreach (KnowledgeSourceFile file in indexClient.GetKnowledgeSourceFilesAsync("my-file-ks"))
{
    Console.WriteLine($"{file.FileName} ({file.FileSizeBytes} bytes) error={file.ErrorMessage}");
}

Reference：SearchIndexClient.GetKnowledgeSourceFilesAsync

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

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

for file in index_client.list_knowledge_source_files("my-file-ks"):
    print(f"{file.file_name} ({file.file_size_bytes} bytes) error={file.error_message}")

参考：SearchIndexClient.list_knowledge_source_files

GET {{search-endpoint}}/knowledgesources/my-file-ks/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}

参考：知识源 - 列出文件

响应包括每个上传文件的元数据。 成功列出的文件的 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
    }
  ]
}

如果新的上传失败，请求将返回错误，并且不会创建文件元数据记录。 失败的上传不会显示在后面的列表结果中，也不会计费。

如果发生模型访问失败，并且承载嵌入模型的 Foundry 资源使用专用网络，请确认 foundry_account 已批准共享专用链接并启用受信任的服务绕过。 某个被禁用的旁路返回了 403 Public access is disabled。 有关设置详细信息，请参阅 先决条件。

列出和筛选文件

从 2026-08-01-preview API 版本开始，用于 prefix 按相对路径筛选文件或 search 按文件名前缀进行筛选。 设置为 pageSize 控制结果数。

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

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

await foreach (KnowledgeSourceFile file in indexClient.GetKnowledgeSourceFilesAsync(
  "my-file-ks",
  prefix: "manuals/",
  pageSize: 100))
{
  Console.WriteLine($"{file.FileName} ({file.FileId})");
}

Reference：SearchIndexClient.GetKnowledgeSourceFilesAsync

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

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

files = index_client.list_knowledge_source_files(
  "my-file-ks",
  prefix="manuals/",
  page_size=100,
)
for file in files:
  print(f"{file.file_name} ({file.file_id})")

参考：SearchIndexClient.list_knowledge_source_files

GET {{search-endpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-08-01-preview&prefix=manuals/&pageSize=100
Authorization: Bearer {{search-access-token}}

参考：知识源 - 列出文件

响应包括服务选择的分析和提取模式，以及用于文件管理的用户元数据。 用户元数据不可搜索或可筛选。

{
  "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，不要更改查询参数。

更新上传的文件

从 2026-08-01-preview API 版本开始，按其 fileId更新文件。 多部分请求需要二进制 content 部分。 元数据 JSON 部分是可选的，因此支持仅内容更新。 不支持仅元数据更新。

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

Console.WriteLine($"Updated file ID: {updatedFile.FileId}");

Reference：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,
)
print(f"Updated file ID: {updated_file.file_id}")

参考：SearchIndexClient.update_knowledge_source_file

PUT {{search-endpoint}}/knowledgesources('my-file-ks')/files('{{file-id}}')?api-version=2026-08-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");

Reference：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 {{search-endpoint}}/knowledgesources/my-file-ks/files/file-abc123?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}

参考：知识源 - 删除文件

分配给知识库

如果对知识源感到满意， 请将其添加到知识库。

查询知识库

配置知识库后， 调用检索操作或 MCP 终结点 以查询知识源。

删除知识源

在删除知识源之前，必须删除引用它的任何知识库或更新知识库定义来去除该引用。 对于生成索引和索引器管道的知识源，所有 生成的对象 都会被删除。 但是，如果使用现有索引创建知识源，则不会删除索引。

如果尝试删除正在使用的知识源，该操作将失败并返回受影响的知识库列表。

要删除知识源，请执行以下步骤：

  1. 获取搜索服务上所有知识库的列表。

    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}");
}

    Reference：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);

    Reference：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.");

    Reference：SearchIndexClient

  4. 删除知识源。

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

    Reference：SearchIndexClient

  1. 获取搜索服务上所有知识库的列表。

    # 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}")

    Reference：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)

    Reference：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.")

    Reference：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.")

    Reference：SearchIndexClient

  1. 获取搜索服务上所有知识库的列表。

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

    参考：知识源 - 删除

文件操作疑难解答

以下状态代码特定于文件知识源操作。

状态代码 原因和操作
400 该文件为空，不包含可提取的文本、具有不安全的相对路径或无效的延续请求。 验证文件是否受支持、可读内容和有效的文件名。 对于列表操作，请完全按照 @odata.nextLink 返回的操作进行操作。 不要将 $skiptoken 与 search 或 pageSize 组合使用。
409 文件知识源已达到 API 版本的文件限制。 在上传更多文件之前删除文件。
415 服务检测到不支持的 MIME 类型，或者当知识源使用最少提取时检测到图像。 使用支持的格式。 对于图像，请使用标准提取。 仅更改调用方提供的内容类型不会替代检测。
429 处理队列已满。 使用有界并行，并采用指数退避进行重试。 服务不保证标头 Retry-After 。
504 在文件上传或更新期间处理超过 180 秒。 减小文件大小或复杂性，然后重试。

相关内容

  • Last updated on