从 Azure Blob 存储 或 ADLS Gen2 创建 Blob 知识源

注释

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。

注释

此智能检索功能在 2026-04-01 REST API 版本中通过编程接口普遍可用。 Azure门户继续提供对所有代理检索功能的仅限预览的访问权限。

如果选择使用预览版 REST API 版本，则可以访问尚未正式发布此功能的功能。 预览版功能在没有服务级别协议的情况下提供，不建议用于生产工作负荷。

重要

这些特性和功能是 2026-05-01 预览版 REST API 的一部分。 2026-05-01-preview 作为Azure订阅的一部分获得许可，并受Microsoft产品条款、Microsoft产品和服务数据保护附录（“DPA”）和Azure预览版补充使用条款的约束。

2026-05-01-preview 支持连接到其他 Microsoft 服务和第三方服务。 使用这些服务受其各自的条款的约束，可能会导致数据处理或存储超出Azure符合性边界，以及流入Azure符合性边界的数据。

2026-05-01-preview 无法修改在 2026-05-01-preview 之外设置的访问权限。 如果您使用 2026-05-01-preview 处理受访问限制或权限限制的内容，则在 2026-05-01-preview 识别到这些访问或权限限制的更改之前，会存在一段时间延迟。

您有责任管理您的数据是否会流出您组织的合规和地理边界之外及其任何相关影响，并确保已配置适当的权限、边界和审批。

你负责仔细查看和测试在特定用例上下文中生成的应用程序，并做出所有适当的决策和自定义。 这包括实施自己的负责任的 AI 缓解措施，例如元系统、内容筛选器或其他安全系统，并确保应用程序满足适当的质量、可靠性、安全性和可信度标准。

blob 知识源将Azure Blob 存储或 ADLS Gen2 内容引入Azure AI 搜索代理检索管道。 知识库是在运行时查询知识库时独立创建的、在知识库中引用的，并用作基础数据。

创建 Blob 知识源时，请指定外部数据源、模型和属性以自动生成以下Azure AI 搜索对象：

  • 表示 Blob 容器的数据源。
  • 一个技能包，用于对来自容器内的多模态内容进行分块处理和可选矢量化。
  • 存储扩充内容并满足代理检索条件的索引。
  • 使用先前的对象来驱动索引和扩展管道的索引器。

注释

如果在 Azure 存储中的文档（blob）级别指定了用户访问，知识源可以将权限元数据转发到 Azure AI 搜索中的索引内容。 有关详细信息，请参阅 ADLS Gen2 权限元数据 或 Blob RBAC 范围。

使用支持

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

先决条件

  • 所需 Azure.Search.Documents 软件包：

    • 对于 2026-05-01-preview 功能，最新的预览包为：dotnet add package Azure.Search.Documents --prerelease

    • 关于2026-04-01的功能，最新的稳定包是：dotnet add package Azure.Search.Documents

  • 所需 azure-search-documents 软件包：

    • 对于 2026-05-01-preview 功能，最新的预览包为：pip install --pre azure-search-documents

    • 关于2026-04-01的功能，最新的稳定包是：pip install azure-search-documents

检查现有知识来源

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

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

// 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
api-key: {{api-key}}

参考：知识源 - 列表

还可以按名称返回单个知识来源以查看其 JSON 定义。

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

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

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

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

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

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}}
api-key: {{api-key}}

参考：知识源 - 获取

注释

敏感信息经过修订。 生成的资源显示在响应的末尾。

创建知识源

运行以下代码以创建 Blob 知识源。

检查引入状态

运行以下代码来监视引入进度和运行状况，包括知识源类型以及生成索引器管道并填充搜索索引的知识源的详细索引错误。

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

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

Reference：SearchIndexClient

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

参考：知识源 - 获取状态

包含引入参数且正在主动引入内容的请求的响应可能如以下示例所示。

{
  "kind": "azureBlob",
  "synchronizationStatus": "active",
  "synchronizationInterval": "1d",
  "currentSynchronizationState": {
    "startTime": "2026-04-10T19:30:00Z",
    "itemUpdatesProcessed": 1100,
    "itemsUpdatesFailed": 100,
    "itemsSkipped": 1100,
    "errors": [
      {
        "key": "Item id 1",
        "docURL": "https://contoso.blob.core.chinacloudapi.cn/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
  }
}

注释

从 2026-04-01 API 版本开始，文档级错误详细信息的 kind 属性和 currentSynchronizationState.errors[] 数组即可使用。 对于早期 API 版本，不会返回这些字段。 该 lastSynchronizationState.status 字段也是 2026-04-01 中的新增字段。

查看生成的对象

创建此知识源时，Azure AI 搜索自动生成数据源、技能集、索引器和索引。 创建响应将列出下 createdResources的每个对象。

这些对象根据固定模板生成，其名称基于知识源的名称。 无法更改对象名称。 避免直接编辑这些对象，因为更改可能会引入中断索引器管道的错误或不兼容。

可以使用Azure门户验证对象创建。 工作流为：

  1. 检查索引器是否有成功或失败的消息。 此处会显示连接或配额错误。

  2. 检查数据源以验证与数据存储的连接。 该连接使用连接字符串或托管标识，具体取决于你如何配置知识源。

  3. 检查技能集以查看内容是如何分块和选择性的矢量化的。

  4. 检查索引以了解您的内容是如何被编制索引和公开以供检索的，包括哪些字段可供搜索和筛选，以及哪些字段存储用于相似性搜索的向量。 使用搜索资源管理器针对生成的索引运行查询。

分配给知识库

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

查询知识库

配置知识库后， 调用检索操作或 MCP 终结点 以查询知识源。 此知识源支持文档级权限强制和文档嵌入图像呈现的可选配置。

强制实施文档级权限（预览版）

若要强制实施文档级权限，请在创建此知识源时设置 ingestionPermissionOptions ，然后在检索请求中包含用户的访问令牌。 有关详细信息，请参阅在查询时强制实施权限（预览版）。

删除知识来源

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

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

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

  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.azure.cn/$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.azure.cn/$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
api-key: {{api-key}}

    参考：知识库 - 列表

    示例响应可能如下所示：

     {
     "@odata.context": "https://my-search-service.search.azure.cn/$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}}
api-key: {{api-key}}

    参考：知识库 - 获取

    示例响应可能如下所示：

     {
   "name": "my-kb",
   "description": null,
   "retrievalInstructions": null,
   "answerInstructions": null,
   "outputMode": null,
   "knowledgeSources": [
     {
       "name": "my-blob-ks",
     }
   ],
   "models": [],
   "encryptionKey": null,
   "retrievalReasoningEffort": {
     "kind": "low"
   }
 }

  3. 删除知识库，或者如果有多个知识库，请更新知识库以删除源。 此示例显示删除。

    ### Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
api-key: {{api-key}}

    参考：知识库 - 删除

  4. 删除知识来源。

    ### Delete a knowledge source
DELETE {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
api-key: {{api-key}}

    参考：知识源 - 删除

已知错误

创建此知识源并 contentExtractionMode 设置为 standard 时，可能会收到以下错误。

Failed to create custom analyzer 'azs_tmp': BadRequest - {"error":{"code":"InvalidRequest","message":"Invalid request.","innererror":{"code":"DefaultsNotSet","message":"Defaults have not yet been set. Call 'PATCH /contentunderstanding/defaults' first."}}}

若要解决此错误，请根据 内容理解先决条件中的说明定义默认值。 之后，可以继续创建知识源。

相关内容

  • Last updated on