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

注释

此功能目前处于公开预览状态。此预览版未随附服务级别协议，建议不要用于生产工作负载。某些功能可能不受支持或者受限。有关详细信息，请参阅适用于 Azure 预览版的补充使用条款。

使用 Blob 知识来源在代理检索管道中为 Azure Blob 内容编制索引并对其进行查询。知识源是独立创建的，在知识库中引用，并在代理或聊天机器人在查询时调用检索作时用作基础数据。

与指定现有合格索引的搜索索引知识源不同，Blob 知识源指定外部数据源、模型和属性，以自动生成以下 Azure AI 搜索对象：

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

注释

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

使用支持

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

先决条件

提供代理检索功能的任何区域内的 Azure AI 搜索。必须启用语义排名器。
Azure Blob 存储帐户或Azure Data Lake Storage （ADLS） Gen2帐户。
一个 Blob 容器，其中包含文本内容支持的内容类型。对于可选的图像语言化，支持的内容类型取决于聊天完成模型是否可以分析和描述图像文件。
在 Azure AI 搜索中创建和使用对象的权限。我们建议使用基于角色的访问，但如果角色分配不可行，则可以使用 API 密钥。有关详细信息，请参阅 “连接到搜索服务”。

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

最新的azure-search-documents预览版软件包：pip install --pre azure-search-documents

搜索服务 REST API 的 2025-11-01 预览版。

检查现有知识来源

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

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

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

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

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

还可以按名称返回单个知识来源以查看其 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));

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

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

# List knowledge sources by name and type
import requests
import json

endpoint = "{search_url}/knowledgesources"
params = {"api-version": "2025-11-01-preview", "$select": "name, kind"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

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

# Get a knowledge source definition
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

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

使用知识源 - 获取（REST API）按名称和类型列出知识源。

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version=2025-11-01-preview&$select=name,kind
api-key: {{api-key}}

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

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

注释

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

检查引入状态

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

// Get knowledge source ingestion status
using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

// Get the knowledge source 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);

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

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

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

# Check knowledge source ingestion status
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_name}/status"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

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

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

使用知识源 - 状态（REST API）监视引入进度和运行状况，包括生成索引器管道并填充搜索索引的知识源的索引器状态。

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

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

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

查看创建的对象

创建 Blob 知识源时，搜索服务还会创建索引器、索引、技能集和数据源。不建议编辑这些对象，因为引入错误或不兼容可能会中断管道。

创建知识源后，响应会列出已创建的对象。这些对象是根据固定模板创建的，其名称基于知识源的名称。无法更改对象名称。

建议使用 Azure 门户验证输出创建。工作流为：

检查索引器是否有成功或失败的消息。此处会显示连接或配额错误。
检查可搜索内容的索引。使用搜索资源管理器运行查询。
检查技能集，了解如何对内容进行分块和选择性地矢量化。
检查数据源以获取连接详细信息。我们的示例使用 API 密钥来简单起见，但可以使用 Microsoft Entra ID 进行身份验证，并使用基于角色的访问控制进行授权。

分配给知识库

如果对知识源感到满意，请继续执行下一步：在知识库中指定知识库中的知识源。

配置知识库后，使用检索作查询知识源。

Tip

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

Tip

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

Tip

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

删除知识来源

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

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

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

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

using Azure.Search.Documents.Indexes;

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

Console.WriteLine("Knowledge Bases:");

await foreach (var kb in knowledgeBases)
{
    Console.WriteLine($"  - {kb.Name}");
}

示例响应可能如下所示：

 Knowledge Bases:
   - earth-knowledge-base
   - hotels-sample-knowledge-base
   - my-demo-knowledge-base

获取单个知识库定义以检查知识源引用。

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

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

// Specify the knowledge base name to retrieve
string kbNameToGet = "earth-knowledge-base";

// Get a specific knowledge base definition
var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
var kb = knowledgeBaseResponse.Value;

// Serialize to JSON for display
string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

示例响应可能如下所示：

 {
   "Name": "earth-knowledge-base",
   "KnowledgeSources": [
     {
       "Name": "earth-knowledge-source"
     }
   ],
   "Models": [
     {}
   ],
   "RetrievalReasoningEffort": {},
   "OutputMode": {},
   "ETag": "\u00220x8DE278629D782B3\u0022",
   "EncryptionKey": null,
   "Description": null,
   "RetrievalInstructions": null,
   "AnswerInstructions": null
 }

删除知识库或更新知识库以删除知识库（如果有多个源）。此示例显示删除。

using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName);
System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");

删除知识来源。

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

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

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

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

# Get knowledge bases
import requests
import json

endpoint = "{search_url}/knowledgebases"
params = {"api-version": "2025-11-01-preview", "$select": "name"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

示例响应可能如下所示：

 {
     "@odata.context": "https://my-search-service.search.azure.cn/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

获取单个知识库定义以检查知识源引用。

# Get a knowledge base definition
import requests
import json

endpoint = "{search_url}/knowledgebases/{knowledge_base_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

示例响应可能如下所示：

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

删除知识库或更新知识库以删除知识库（如果有多个源）。此示例显示删除。

# Delete a knowledge base
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_base("knowledge_base_name")
print(f"Knowledge base deleted successfully.")

删除知识来源。

# Delete a knowledge source
from azure.core.credentials import AzureKeyCredential 
from azure.search.documents.indexes import SearchIndexClient

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
index_client.delete_knowledge_source("knowledge_source_name")
print(f"Knowledge source deleted successfully.")

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

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

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

### Get knowledge bases
GET {{search-endpoint}}/knowledgebases?api-version=2025-11-01-preview&$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"
     }
     ]
 }

获取单个知识库定义以检查知识源引用。

### Get a knowledge base definition
GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

示例响应可能如下所示：

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

如果有多个源，您可以选择删除知识库，或者通过删除知识源来更新知识库。此示例显示删除。

### Delete a knowledge base
DELETE {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

删除知识来源。

### Delete a knowledge source
DELETE {{search-endpoint}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

Last updated on 2026-04-30

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

使用支持

先决条件

检查现有知识来源

检查引入状态

查看创建的对象

分配给知识库

删除知识来源

相关内容

Ressources supplémentaires