在 Azure AI 搜索中创建知识库

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

先决条件

• 提供代理检索功能的任何区域内的 Azure AI 搜索。 必须 启用语义排名器。

• 包含具有语义配置的纯文本或矢量内容的搜索索引。 查看用于代理检索的索引条件。 索引必须与知识库位于同一搜索服务上。

• 适用于 .NET SDK 的 Azure.Search.Documents 客户端库 的最新预览版本。

• 在 Azure AI 搜索中创建和使用对象的权限。 我们建议 使用基于角色的访问，但如果角色分配不可行，则可以使用 API 密钥 。 有关详细信息，请参阅 “连接到搜索服务”。

检查现有知识来源

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

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

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

特定于源的属性

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

分配给知识库

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

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

删除知识来源

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

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

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

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

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

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

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

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

在 Azure AI 搜索中， 知识库 是协调 代理检索的顶级对象。 它定义要查询的知识源以及用于检索作的默认行为。 在查询时， 检索方法 以知识库为目标，以运行配置的检索管道。

知识库指定：

• 指向可搜索内容的一个或多个知识源。
• 一个可选的 LLM，它提供查询规划和答案表述的推理功能。
• 用于确定是否调用 LLM 并管理成本、延迟和质量的检索推理工作。
• 控制路由、源选择、输出格式和对象加密的自定义属性。

创建知识库后，可以随时更新其属性。 如果知识库正在使用中，更新将对下一次检索生效。

先决条件

• 提供代理检索功能的任何区域内的 Azure AI 搜索。 必须 启用语义排名器。 如果使用 托管标识 对已部署模型进行基于角色的访问，则搜索服务必须设置为基本定价层或更高。

• Azure OpenAI 支持 LLM 部署。

• 搜索服务上的一个或多个 知识源 。

• 在 Azure AI 搜索中创建和使用对象的权限。 建议 使用基于角色的访问。 搜索服务参与者 可以创建和管理知识库。 搜索索引数据读取器 可以运行查询。 或者，如果角色分配不可行，则可以使用 API 密钥 。 有关详细信息，请参阅 “连接到搜索服务”。

• 适用于 Python 的 azure-search-documents 客户端库 的最新预览版。

支持的模型

使用 Azure OpenAI 中的以下 LLM 之一或等效的开源模型。 有关部署说明，请参阅 使用 Azure Foundry 部署 Azure OpenAI 模型。

• gpt-4o
• gpt-4o-mini
• gpt-4.1
• gpt-4.1-nano
• gpt-4.1-mini
• gpt-5
• gpt-5-nano
• gpt-5-mini

配置访问权限

Azure AI 搜索需要访问 Azure OpenAI 的 LLM。 我们建议使用 Microsoft Entra ID 进行身份验证，并使用基于角色的访问控制进行授权。 你必须是 所有者或用户访问管理员 才能分配角色。 如果角色不可行，请改用基于密钥的身份验证。

检查现有知识库

了解现有知识库有助于重复使用或命名新对象。 任何 2025-08-01-preview 知识代理都返回在知识库集合中。

运行以下代码，按名称列出现有知识库。

# List knowledge bases by name
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))

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

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

以下 JSON 是知识库的示例响应。

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

创建知识库

知识库驱动代理检索管道。 在应用程序代码中，它由其他代理或聊天机器人调用。

知识库将知识库（可搜索内容）连接到 Azure OpenAI 中的 LLM 部署。 LLM 上的属性建立连接，而知识源上的属性建立默认值，用于通知查询执行和响应。

运行以下代码来创建知识库。

# Create a knowledge base
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import KnowledgeBase, KnowledgeBaseAzureOpenAIModel, KnowledgeSourceReference, AzureOpenAIVectorizerParameters, KnowledgeRetrievalOutputMode, KnowledgeRetrievalLowReasoningEffort

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

aoai_params = AzureOpenAIVectorizerParameters(
    resource_url = "aoai_endpoint",
    deployment_name = "aoai_gpt_deployment",
    model_name = "aoai_gpt_model",
)

knowledge_base = KnowledgeBase(
    name = "my-kb",
    description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    retrieval_instructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    answer_instructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
    output_mode = KnowledgeRetrievalOutputMode.ANSWER_SYNTHESIS,
    knowledge_sources = [
        KnowledgeSourceReference(name = "hotels-ks"),
        KnowledgeSourceReference(name = "earth-at-night-ks"),
    ],
    models = [KnowledgeBaseAzureOpenAIModel(azure_open_ai_parameters = aoai_params)],
    encryption_key = None,
    retrieval_reasoning_effort = KnowledgeRetrievalLowReasoningEffort,
)

index_client.create_or_update_knowledge_base(knowledge_base)
print(f"Knowledge base '{knowledge_base.name}' created or updated successfully.")

知识库属性

可以传递以下属性来创建知识库。

查询知识库

在 retrieve 知识库上调用操作以验证 LLM 连接并返回结果。 有关请求和响应架构的详细信息 retrieve ，请参阅 在 Azure AI 搜索中使用知识库检索数据。

将“海洋在何处看起来绿色？”替换为对知识源有效的查询字符串。

# Send grounding request
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import KnowledgeBaseMessage, KnowledgeBaseMessageTextContent, KnowledgeBaseRetrievalRequest, RemoteSharePointKnowledgeSourceParams

kb_client = KnowledgeBaseRetrievalClient(endpoint = "search_url", knowledge_base_name = "knowledge_base_name", credential = AzureKeyCredential("api_key"))

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role = "assistant",
            content = [KnowledgeBaseMessageTextContent(text = "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know.")]
        ),
        KnowledgeBaseMessage(
            role = "user",
            content = [KnowledgeBaseMessageTextContent(text = "Where does the ocean look green?")]
        ),
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name = "earth-at-night-ks",
            include_references = True,
            include_reference_source_data = True,
            always_query_source = False,
        )
    ],
    include_activity = True,
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

要点：

• messages 是必需的，但只能使用 user 提供查询的角色运行此示例。

• knowledge_source_params 指定一个或多个查询目标。 对于每个知识源，可以指定要包含在输出中的信息量。

对示例查询的响应可能如以下示例所示：

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica's Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

删除知识库

如果不再需要知识库或需要在搜索服务上重新生成它，请使用此请求删除该对象。

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

在 Azure AI 搜索中， 知识库 是协调 代理检索的顶级对象。 它定义要查询的知识源以及用于检索作的默认行为。 在查询时， 检索方法 以知识库为目标，以运行配置的检索管道。

知识库指定：

• 指向可搜索内容的一个或多个知识源。
• 一个可选的 LLM，它提供查询规划和答案表述的推理功能。
• 用于确定是否调用 LLM 并管理成本、延迟和质量的检索推理工作。
• 控制路由、源选择、输出格式和对象加密的自定义属性。

创建知识库后，可以随时更新其属性。 如果知识库正在使用中，更新将对下一次检索生效。

先决条件

• 提供代理检索功能的任何区域内的 Azure AI 搜索。 必须 启用语义排名器。 如果使用 托管标识 对已部署模型进行基于角色的访问，则搜索服务必须设置为基本定价层或更高。

• Azure OpenAI 支持 LLM 部署。

• 搜索服务上的一个或多个 知识源 。

• 在 Azure AI 搜索中创建和使用对象的权限。 建议 使用基于角色的访问。 搜索服务参与者 可以创建和管理知识库。 搜索索引数据读取器 可以运行查询。 或者，如果角色分配不可行，则可以使用 API 密钥 。 有关详细信息，请参阅“连接到搜索服务”

• 适用于 .NET SDK 的 Azure.Search.Documents 客户端库 的最新预览版本。

支持的模型

使用 Azure OpenAI 中的以下 LLM 之一或等效的开源模型。 有关部署说明，请参阅 使用 Azure Foundry 部署 Azure OpenAI 模型。

• gpt-4o
• gpt-4o-mini
• gpt-4.1
• gpt-4.1-nano
• gpt-4.1-mini
• gpt-5
• gpt-5-nano
• gpt-5-mini

配置访问权限

Azure AI 搜索需要访问 Azure OpenAI 的 LLM。 我们建议使用 Microsoft Entra ID 进行身份验证，并使用基于角色的访问控制进行授权。 你必须是 所有者或用户访问管理员 才能分配角色。 如果角色不可行，请改用基于密钥的身份验证。

检查现有知识库

知识库是顶级可重用对象。 了解现有知识库有助于重复使用或命名新对象。 任何 2025-08-01-preview 知识代理都返回在知识库集合中。

使用 知识库 - 列表（REST API） 按名称和类型列出知识库。

# List knowledge bases
GET {{search-url}}/knowledgebases?api-version=2025-11-01-preview&$select=name
Content-Type: application/json
api-key: {{search-api-key}}

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

# Get knowledge base
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

以下 JSON 是知识库的示例响应。

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

创建知识库

知识库驱动代理检索管道。 在应用程序代码中，它由其他代理或聊天机器人调用。

知识库将知识库（可搜索内容）连接到 Azure OpenAI 中的 LLM 部署。 LLM 上的属性建立连接，而知识源上的属性建立默认值，用于通知查询执行和响应。

使用 知识库 - 创建或更新（REST API） 来制定请求。

# Create a knowledge base
PUT {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

{
    "name" : "my-kb",
    "description": "This knowledge base handles questions directed at two unrelated sample indexes.",
    "retrievalInstructions": "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    "answerInstructions": null,
    "outputMode": "answerSynthesis",
    "knowledgeSources": [
        {
            "name": "hotels-ks"
        },
        {
            "name": "earth-at-night-ks"
        }
    ],
    "models" : [ 
        {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{model-provider-url}}",
                "apiKey": "{{model-api-key}}",
                "deploymentId": "gpt-4.1-mini",
                "modelName": "gpt-4.1-mini"
            }
        }
    ],
    "encryptionKey": null,
    "retrievalReasoningEffort": {
        "kind": "low"
    }
}

知识库属性

可以传递以下属性来创建知识库。

查询知识库

在 retrieve 知识库上调用操作以验证 LLM 连接并返回结果。 有关请求和响应架构的详细信息 retrieve ，请参阅 在 Azure AI 搜索中使用知识库检索数据。

使用 知识检索 - 检索（REST API） 来构建请求。 将“海洋在何处看起来绿色？”替换为对知识源有效的查询字符串。

# Send grounding request
POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

{
    "messages" : [
        { "role" : "assistant",
                "content" : [
                  { "type" : "text", "text" : "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know." }
                ]
        },
        {
            "role" : "user",
            "content" : [
                {
                    "text" : "Where does the ocean look green?",
                    "type" : "text"
                }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "earth-at-night-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": true,
            "alwaysQuerySource": false
        }
  ]
}

要点：

• messages 是必需的，但只能使用 user 提供查询的角色运行此示例。

• knowledgeSourceParams 指定一个或多个查询目标。 对于每个知识源，可以指定要包含在输出中的信息量。

对示例查询的响应可能如以下示例所示：

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica's Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ]

删除知识库

如果不再需要知识库或需要在搜索服务上重新生成它，请使用此请求删除该对象。

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