创建 Web 知识源资源

注释

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符合性边界的数据。

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

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

重要

Web 知识源是一个使用“必应搜索”和/或“必应自定义搜索”为基础的信息服务，它作为一种第一方消费服务，受基于必应的使用条款和Microsoft 隐私声明的约束。
Microsoft数据保护附录不适用于发送到 Web 知识源的数据。当客户使用 Web 知识源时，客户数据将流出 Azure 合规性和地理边界。这也意味着，使用 Web 知识源可免除所有政府社区云的安全和合规性承诺，包括数据主权和基于公民身份筛选的支持（如适用）。
使用 Web 知识源会产生成本;详细了解定价。
详细了解 Azure 管理员如何管理对 Web 知识源的访问权限。

Web 知识源可以通过基于代理的检索管道，从 Microsoft 必应获取实时 Web 数据。知识库是在运行时查询知识库时独立创建的、在知识库中引用的，并用作基础数据。

Bing自定义搜索始终是 Web 知识源的搜索提供程序。虽然不能指定备用搜索提供程序或引擎，但可以包括或排除特定域，例如 https://learn.microsoft.com。如果未指定任何域，Web知识库对整个公共互联网的访问权限不受限制。

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

使用支持

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

先决条件

一个具有访问Web 知识源权限的 Azure 订阅。默认情况下，access处于启用状态。如果访问权限被禁用，请与管理员联系。
提供代理式检索的任何公共区域中的Azure AI 搜索服务。私有云或主权云不支持 Web 知识源。
创建知识源的权限。使用分配给用户帐户的搜索服务参与者角色（建议）或使用 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

所需的 REST API 版本：
- 有关预览功能： Search Service 2026-05-01-preview
- 一般可用的功能：搜索服务 2026-04-01

限制和注意事项

Web 内容始终由 LLM 汇总，然后再将其包含在检索结果中。结果被引用摘要，而不是逐字 Web 文本。
对于 2026-04-01 API 版本，知识库必须包含模型引用，以便为网页内容摘要提供LLM。检索始终是提取性的（引用摘要）。此版本不提供答案合成和可配置推理工作。
对于 2026-05-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 知识源。

2026-05-01-预览
2026-04-01

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

2026-05-01-预览
2026-04-01

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

2026-05-01-预览
2026-04-01

### Create Web Knowledge Source
PUT {{search-url}}/knowledgesources/my-web-ks?api-version=2026-05-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 } ]
    }
  }
}

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

### Create Web Knowledge Source
PUT {{search-url}}/knowledgesources/my-web-ks?api-version=2026-04-01
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 } ]
    }
  }
}

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

分配给知识库

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

查询知识库

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

捕获 web 用于请求的运行时参数的记录。
捕获令牌使用情况的modelWebSummarization记录，用于LLM的摘要步骤。

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

删除知识来源

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

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

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

获取在你的搜索服务中所有知识库的列表。

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

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

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
 }

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

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

删除知识来源。

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

Reference：SearchIndexClient

获取在你的搜索服务中所有知识库的列表。

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

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

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

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

# 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

删除知识来源。

# 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

获取在你的搜索服务中所有知识库的列表。

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

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

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

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

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

参考：知识库 - 删除

删除知识来源。

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

参考：知识源 - 删除

Last updated on 2026-07-27

创建 Web 知识源资源

使用支持

先决条件

限制和注意事项

检查现有知识来源

创建知识来源

分配给知识库

查询知识库

删除知识来源

相关内容

其他资源