创建搜索索引知识源 - Azure AI Search

注释

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

搜索索引知识源指定与 Azure AI 搜索索引的连接，该索引在代理检索管道中提供可搜索内容。知识源是独立创建的，在知识库中引用，并在代理或聊天机器人在查询时调用检索作时用作基础数据。

先决条件

提供代理检索功能的任何区域内的 Azure AI 搜索。必须启用语义排名器。
包含具有语义配置的纯文本或矢量内容的搜索索引。查看用于代理检索的索引条件。索引必须与知识库位于同一搜索服务上。
适用于 .NET SDK 的 Azure.Search.Documents 客户端库的最新预览版本。
在 Azure AI 搜索中创建和使用对象的权限。我们建议使用基于角色的访问，但如果角色分配不可行，则可以使用 API 密钥。有关详细信息，请参阅 “连接到搜索服务”。

注释

尽管可以使用 Azure 门户创建搜索索引知识源，但门户使用 2025-08-01-preview，该预览版使用以前的“知识代理”术语，并且不支持所有 2025-11-01-preview 功能。如需中断性变更方面的帮助，请参阅迁移智能体检索代码。

检查现有知识来源

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

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

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

以下 JSON 是搜索索引知识源的示例响应。请注意，知识来源指定单个索引名称以及要包含在查询中的索引中的字段。

{
  "SearchIndexParameters": {
    "SearchIndexName": "earth-at-night",
    "SourceDataFields": [
      {
        "Name": "id"
      },
      {
        "Name": "page_chunk"
      },
      {
        "Name": "page_number"
      }
    ],
    "SearchFields": [],
    "SemanticConfigurationName": "semantic-config"
  },
  "Name": "earth-knowledge-source",
  "Description": null,
  "EncryptionKey": null,
  "ETag": "<redacted>"
}

创建知识来源

运行以下代码以创建搜索索引知识源。

using Azure.Search.Documents.Indexes.Models;

// Create the knowledge source
var indexKnowledgeSource = new SearchIndexKnowledgeSource(
    name: knowledgeSourceName,
    searchIndexParameters: new SearchIndexKnowledgeSourceParameters(searchIndexName: indexName)
    {
        SourceDataFields = { new SearchIndexFieldReference(name: "id"), new SearchIndexFieldReference(name: "page_chunk"), new SearchIndexFieldReference(name: "page_number") }
    }
);

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

特定于源的属性

可以传递以下属性来创建搜索索引知识源。

Name	Description	类型	可编辑	必选
`Name`	知识源的名称，该名称在知识源集合中必须是唯一的，并遵循 Azure AI 搜索中对象的命名准则。	String	否	是的
`Description`	知识源的说明。	String	是的	否
`EncryptionKey`	客户管理的密钥，用于加密知识源和生成的对象中的敏感信息。	物体	是的	否
`SearchIndexParameters`	特定于搜索索引知识源的参数： `search_index_name`、 `SemanticConfigurationName`、 `SourceDataFields`和 `SearchFields`。	物体	是的	是的
`SearchIndexName`	现有搜索索引的名称。	String	是的	是的
`SemanticConfigurationName`	替代搜索索引的默认语义配置。	String	是的	否
`SourceDataFields`	在知识库定义中指定 `include_reference_source_data` 时返回的索引字段。这些字段用于引文，应为 `retrievable`。示例包括文档名称、文件名、页码或章节号。	Array	是的	否
`SearchFields`	要专门搜索的索引字段。如果未指定，将搜索所有字段。	Array	是的	否

分配给知识库

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

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

删除知识来源

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

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

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

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

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

注释

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

搜索索引知识源指定与 Azure AI 搜索索引的连接，该索引在代理检索管道中提供可搜索内容。知识源是独立创建的，在知识库中引用，并在代理或聊天机器人在查询时调用检索作时用作基础数据。

先决条件

提供代理检索功能的任何区域内的 Azure AI 搜索。必须启用语义排名器。
包含具有语义配置的纯文本或矢量内容的搜索索引。查看用于代理检索的索引条件。索引必须与知识库位于同一搜索服务上。
适用于 Python 的 azure-search-documents 客户端库的最新预览版。
在 Azure AI 搜索中创建和使用对象的权限。我们建议使用基于角色的访问，但如果角色分配不可行，则可以使用 API 密钥。有关详细信息，请参阅 “连接到搜索服务”。

注释

尽管可以使用 Azure 门户创建搜索索引知识源，但门户使用 2025-08-01-preview，该预览版使用以前的“知识代理”术语，并且不支持所有 2025-11-01-preview 功能。如需中断性变更方面的帮助，请参阅迁移智能体检索代码。

检查现有知识来源

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

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

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

以下 JSON 是搜索索引知识源的示例响应。请注意，知识来源指定单个索引名称以及要包含在查询中的索引中的字段。

{

  "name": "my-search-index-ks",
  "kind": "searchIndex",
  "description": "A sample search index knowledge source.",
  "encryptionKey": null,
  "searchIndexParameters": {
    "searchIndexName": "my-search-index",
    "semanticConfigurationName": null,
    "sourceDataFields": [],
    "searchFields": []
  }
}

创建知识来源

运行以下代码以创建搜索索引知识源。

# Create a search index knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import SearchIndexKnowledgeSource, SearchIndexKnowledgeSourceParameters, SearchIndexFieldReference

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

knowledge_source = SearchIndexKnowledgeSource(
    name = "my-search-index-ks",
    description= "This knowledge source pulls from an existing index designed for agentic retrieval.",
    encryption_key = None,
    search_index_parameters = SearchIndexKnowledgeSourceParameters(
        search_index_name = "search_index_name",
        semantic_configuration_name = "semantic_configuration_name",
        source_data_fields = [
            SearchIndexFieldReference(name="description"),
            SearchIndexFieldReference(name="category"),
        ],
        search_fields = [
            SearchIndexFieldReference(name="id")
        ],
    )
)

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

特定于源的属性

可以传递以下属性来创建搜索索引知识源。

Name	Description	类型	可编辑	必选
`name`	知识源的名称，该名称在知识源集合中必须是唯一的，并遵循 Azure AI 搜索中对象的命名准则。	String	否	是的
`description`	知识源的说明。	String	是的	否
`encryption_key`	客户管理的密钥，用于加密知识源和生成的对象中的敏感信息。	物体	是的	否
`search_index_parameters`	特定于搜索索引知识源的参数： `search_index_name`、 `semantic_configuration_name`、 `source_data_fields`和 `search_fields`。	物体	是的	是的
`search_index_name`	现有搜索索引的名称。	String	是的	是的
`semantic_configuration_name`	替代搜索索引的默认语义配置。	String	是的	否
`source_data_fields`	在知识库定义中指定 `include_reference_source_data` 时返回的索引字段。这些字段用于引文，应为 `retrievable`。示例包括文档名称、文件名、页码或章节号。	Array	是的	否
`search_fields`	要专门搜索的索引字段。如果未指定，将搜索所有字段。	Array	是的	否

分配给知识库

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

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

删除知识来源

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

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

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

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

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

注释

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

搜索索引知识源指定与 Azure AI 搜索索引的连接，该索引在代理检索管道中提供可搜索内容。知识源是独立创建的，在知识库中引用，并在代理或聊天机器人在查询时调用检索作时用作基础数据。

先决条件

提供代理检索功能的任何区域内的 Azure AI 搜索。必须启用语义排名器。
包含具有语义配置的纯文本或矢量内容的搜索索引。查看用于代理检索的索引条件。索引必须与知识库位于同一搜索服务上。
搜索服务 REST API 的 2025-11-01 预览版。
在 Azure AI 搜索中创建和使用对象的权限。我们建议使用基于角色的访问，但如果角色分配不可行，则可以使用 API 密钥。有关详细信息，请参阅 “连接到搜索服务”。

注释

尽管可以使用 Azure 门户创建搜索索引知识源，但门户使用 2025-08-01-preview，该预览版使用以前的“知识代理”术语，并且不支持所有 2025-11-01-preview 功能。如需中断性变更方面的帮助，请参阅迁移智能体检索代码。

检查现有知识来源

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

使用知识源 - 获取（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}}

以下 JSON 是搜索索引知识源的示例响应。请注意，知识来源指定单个索引名称以及要包含在查询中的索引中的字段。

{

  "name": "my-search-index-ks",
  "kind": "searchIndex",
  "description": "A sample search index knowledge source.",
  "encryptionKey": null,
  "searchIndexParameters": {
    "searchIndexName": "my-search-index",
    "semanticConfigurationName": null,
    "sourceDataFields": [],
    "searchFields": []
  }
}

创建知识来源

使用知识源 - 创建或更新（REST API）创建搜索索引知识源。

POST {{search-url}}/knowledgesources/my-search-index-ks?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
    "name": "my-search-index-ks",
    "kind": "searchIndex",
    "description": "This knowledge source pulls from an existing index designed for agentic retrieval.",
    "encryptionKey": null,
    "searchIndexParameters": {
        "searchIndexName": "<YOUR INDEX NAME>",
        "semanticConfigurationName": "my-semantic-config",
        "sourceDataFields": [
          { "name": "description" },
          { "name": "category" }
        ],
        "searchFields": [
          { "name": "*" }
        ]
    }
}

特定于源的属性

可以传递以下属性来创建搜索索引知识源。

Name	Description	类型	可编辑	必选
`name`	知识源的名称，该名称在知识源集合中必须是唯一的，并遵循 Azure AI 搜索中对象的命名准则。	String	否	是的
`kind`	知识源的类型，其为`searchIndex`在本例中。	String	否	是的
`description`	知识源的说明。	String	是的	否
`encryptionKey`	客户管理的密钥，用于加密知识源和生成的对象中的敏感信息。	物体	是的	否
`searchIndexParameters`	特定于搜索索引知识源的参数： `searchIndexName`、 `semanticConfigurationName`、 `sourceDataFields`和 `searchFields`。	物体	是的	是的
`searchIndexName`	现有搜索索引的名称。	String	是的	是的
`semanticConfigurationName`	替代搜索索引的默认语义配置。	String	是的	否
`sourceDataFields`	在知识库定义中指定 `includeReferenceSourceData` 时返回的索引字段。这些字段用于引文，应为 `retrievable`。示例包括文档名称、文件名、页码或章节号。	Array	是的	否
`searchFields`	要专门搜索的索引字段。如果未指定，将搜索所有字段。	Array	是的	否

分配给知识库

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

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

删除知识来源

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

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

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

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

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

次の方法で共有

创建搜索索引知识来源

先决条件

检查现有知识来源

创建知识来源

特定于源的属性

分配给知识库

删除知识来源

先决条件

检查现有知识来源

创建知识来源

特定于源的属性

分配给知识库

删除知识来源

先决条件

检查现有知识来源

创建知识来源

特定于源的属性

分配给知识库

删除知识来源

相关内容

その他のリソース