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

创建 Web 知识源资源

重要

  • Web 知识来源使用“使用 Bing Search 建立事实依据”和“使用必应自定义搜索建立事实依据”，它是一项第一方消费服务，受必应使用条款和 Microsoft 隐私声明的约束。

  • Microsoft数据保护附录不适用于发送到 Web 知识源的数据。 当客户使用 Web 知识源时，客户数据会流出Azure合规性和地理边界。 这也意味着，使用 Web 知识源可免除所有政府社区云的安全和合规性承诺，包括数据主权和基于公民身份筛选的支持（如适用）。

  • 使用 Web 知识源会产生成本;详细了解 定价。

  • 详细了解Azure管理员如何管理访问 Web 知识源。

注意

此智能检索功能在 2026-04-01 REST API 版本中通过编程接口普遍可用。 Azure门户和 Microsoft Foundry 门户继续提供对所有代理检索功能的仅限预览的访问权限。 有关迁移指南，请参阅 将代理检索代码迁移到最新版本。

如果选择使用预览版 REST API 版本，则可以访问尚未正式发布此功能的功能。 预览版功能在没有服务级别协议的情况下提供，不建议用于生产工作负荷。 有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

Web 知识源能够通过智能体检索管道从 Microsoft 必应检索实时 Web 数据。 知识源 是独立创建的，在 知识库中引用，并在代理或聊天机器人在查询时调用 检索操作 时用作基础数据。

必应自定义搜索始终是 Web 知识源的搜索提供程序。 虽然不能指定备用搜索提供程序或引擎，但可以包括或排除特定 域，例如 https://dotnet.territoriali.olinfo.it。 如果未指定任何域，Web 知识源将不受限制地访问整个公共 Internet。

Web 知识源与其他知识源一起效果最佳。 请使用 Web 知识源，当您的专有内容未能提供完整、最新的答案，或当您希望通过商业搜索引擎的信息来补充结果时。

使用支持

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

先决条件

  • 必需Azure.Search.Documents 包：

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

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

  • 所需的 azure-search-documents 包：

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

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

限制和注意事项

  • Web 内容始终由 LLM 汇总，然后再将其包含在检索结果中。 结果被引用摘要，而不是逐字 Web 文本。

  • 对于 2026-04-01 API 版本，知识库必须包含模型引用，以提供用于 Web 内容汇总的 LLM。 检索始终是提取性的（引用摘要）。 此版本不提供答案合成和可配置推理工作。

  • 对于 2025-11-01-preview API 版本，知识库模型参考还支持答案合成，这会产生单个 LLM 生成的响应，而不是提取的引文。

检查现有知识源

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

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

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

参考：知识源 - 获取

以下 JSON 是 Web 知识源资源的示例响应。

{
  "name": "my-web-ks",
  "kind": "web",
  "description": "A sample Web Knowledge Source.",
  "encryptionKey": null,
  "webParameters": {
    "domains": null
  }
}

创建知识源

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

// Create Web Knowledge Source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure;

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

var knowledgeSource = new WebKnowledgeSource(name: "my-web-ks")
{
    Description = "A sample Web Knowledge Source.",
    WebParameters = new WebKnowledgeSourceParameters
    {
        Domains = new WebKnowledgeSourceDomains
        {
            AllowedDomains = 
            {
                new WebKnowledgeSourceDomain(address: "learn.microsoft.com") { IncludeSubpages = true }
            },
            BlockedDomains = 
            {
                new WebKnowledgeSourceDomain(address: "bing.com") { IncludeSubpages = false }
            }
        }
    }
};

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

Reference：SearchIndexClient、 WebKnowledgeSource

# Create Web Knowledge Source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import WebKnowledgeSource, WebKnowledgeSourceParameters, WebKnowledgeSourceDomains, WebKnowledgeSourceDomain

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

knowledge_source = WebKnowledgeSource(
    name = "my-web-ks",
    description = "A sample Web Knowledge Source.",
    encryption_key = None,
    web_parameters = WebKnowledgeSourceParameters(
        domains = WebKnowledgeSourceDomains(
            allowed_domains = [ WebKnowledgeSourceDomain(address="learn.microsoft.com", include_subpages=True) ],
            blocked_domains = [ WebKnowledgeSourceDomain(address="bing.com", include_subpages=False) ]
        )
    )
)

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

Reference：SearchIndexClient

### Create Web Knowledge Source
PUT {{search-url}}/knowledgesources/my-web-ks?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{api-key}}

{
  "name": "my-web-ks",
  "kind": "web",
  "description": "This knowledge source pulls content from the web.",
  "encryptionKey": null,
  "webParameters": {
    "domains": {
      "allowedDomains": [ { "address": "learn.microsoft.com", "includeSubpages": true } ],
      "blockedDomains": [ { "address": "bing.com", "includeSubpages": false } ]
    }
  }
}

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

特定于源的属性

对于 2025-11-01-preview 和 2026-04-01 API 版本，可以传递以下属性来创建 Web 知识源。

名字 描述 类型 可编辑的 必填
Name 知识源的名称，该名称在知识源集合中必须唯一，并遵循Azure AI 搜索中对象的命名准则。 字符串 不 是的
Description 知识源的说明。 如果未指定，Azure AI 搜索应用默认说明。 字符串 是的 不
EncryptionKey 客户 管理的密钥 ，用于加密知识源中的敏感信息。 对象 是的 不
WebParameters 特定于 Web 知识源的参数。 目前，这只是 Domains。 对象 是的 不
Domains 在搜索空间中允许或屏蔽的域名。 默认情况下，知识来源使用“使用 Bing Search 建立事实依据”搜索整个公共互联网。 指定域时，知识来源使用“使用必应自定义搜索建立事实依据”将结果限制在指定领域内。 在这两种情况下，必应自定义搜索都是搜索提供程序。 对象 是的 不
AllowedDomains 要包含在搜索空间中的域。 对于每个领域，必须以 website.com 格式指定其 address。 你还可以通过将IncludeSubpages设置为true或false来指定是否包括域的子页。 阵 列 是的 不
BlockedDomains 要从搜索空间中排除的域。 对于每个领域，必须以 website.com 格式指定其 address。 你还可以通过将IncludeSubpages设置为true或false来指定是否包括域的子页。 阵 列 是的 不
名字 描述 类型 可编辑的 必填
name 知识源的名称，该名称在知识源集合中必须唯一，并遵循Azure AI 搜索中对象的命名准则。 字符串 不 是的
description 知识源的说明。 如果未指定，Azure AI 搜索应用默认说明。 字符串 是的 不
encryption_key 客户 管理的密钥 ，用于加密知识源中的敏感信息。 对象 是的 不
web_parameters 特定于 Web 知识源的参数。 目前，这只是 domains。 对象 是的 不
domains 在搜索空间中允许或屏蔽的域名。 默认情况下，知识来源使用“使用 Bing Search 建立事实依据”搜索整个公共互联网。 指定域时，知识来源使用“使用必应自定义搜索建立事实依据”将结果限制在指定领域内。 在这两种情况下，必应自定义搜索都是搜索提供程序。 对象 是的 不
allowed_domains 要包含在搜索空间中的域。 对于每个领域，必须以 website.com 格式指定其 address。 你还可以通过将include_subpages设置为true或false来指定是否包括域的子页。 阵 列 是的 不
blocked_domains 要从搜索空间中排除的域。 对于每个领域，必须以 website.com 格式指定其 address。 你还可以通过将include_subpages设置为true或false来指定是否包括域的子页。 阵 列 是的 不
名字 描述 类型 可编辑的 必填
name 知识源的名称，该名称在知识源集合中必须唯一，并遵循Azure AI 搜索中对象的命名准则。 字符串 不 是的
kind 知识源的类型为web，在本例中。 字符串 不 是的
description 知识源的说明。 如果未指定，Azure AI 搜索应用默认说明。 字符串 是的 不
encryptionKey 客户 管理的密钥 ，用于加密知识源中的敏感信息。 对象 是的 不
webParameters 特定于 Web 知识源的参数。 目前，这只是 domains。 对象 是的 不
domains 在搜索空间中允许或屏蔽的域名。 默认情况下，知识来源使用“使用 Bing Search 建立事实依据”搜索整个公共互联网。 指定域时，知识来源使用“使用必应自定义搜索建立事实依据”将结果限制在指定领域内。 在这两种情况下，必应自定义搜索都是搜索提供程序。 对象 是的 不
allowedDomains 要包含在搜索空间中的域。 对于每个领域，必须以 website.com 格式指定其 address。 你还可以通过将includeSubpages设置为true或false来指定是否包括域的子页。 阵 列 是的 不
blockedDomains 要从搜索空间中排除的域。 对于每个领域，必须以 website.com 格式指定其 address。 你还可以通过将includeSubpages设置为true或false来指定是否包括域的子页。 阵 列 是的 不

分配给知识库

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

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

查看检索输出

查询包含 Web 知识库的知识库时，检索响应 activity 数组可以包含两条与 Web 相关的记录：

  • 捕获 web 用于请求的运行时参数的记录。
  • 捕获 LLM 摘要步骤的令牌使用情况的 modelWebSummarization 记录。
{
  "activity": [
    {
      "id": 1,
      "type": "web",
      "knowledgeSourceName": "my-web-ks",
      "elapsedMs": 212,
      "webArguments": {
        "search": "What is the latest news about AI in education?",
        "language": "en",
        "market": "en-US",
        "count": 10,
        "freshness": "2026-03-01..2026-03-31"
      }
    },
    {
      "id": 2,
      "type": "modelWebSummarization",
      "elapsedMs": 87,
      "inputTokens": 1234,
      "outputTokens": 256
    }
  ]
}

删除知识源

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

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

删除知识源：

  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

    示例响应可能如下所示：

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

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

    参考：知识库 - 列表

    示例响应可能如下所示：

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

    参考：知识源 - 删除

相关内容

  • Last updated on