创建 Web 知识源资源

注释

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

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

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

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

使用 Web 知识源时，请记住以下几点：

响应始终是查询的单个、已表述的答案，而不是来自 Web 的原始搜索结果。
由于 Web 知识源不支持提取数据，因此知识库必须使用答案合成和低或中等推理工作量。也不能定义答案说明。

使用支持

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

先决条件

一个具有访问Web 知识源权限的 Azure 订阅。默认情况下，access处于启用状态。如果访问权限被禁用，请与管理员联系。
在任何区域中提供代理检索服务的 Azure AI 搜索服务。必须启用语义排名器。该服务还必须位于 Azure 公共区域中，因为私有云或主权云不支持 Web 知识源。
在Azure AI 搜索上创建和使用对象的权限。我们建议使用基于角色的访问控制，但如果角色分配不可行，可以使用 API 密钥。有关详细信息，请参阅连接到搜索服务。

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

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

2025-11-01-preview 版本的 Search Service REST 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));

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

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

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

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

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

# 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

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 = [ { "address": "learn.microsoft.com", "include_subpages": True } ],
            blocked_domains = [ { "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.")

使用知识源 - 创建或更新（REST API）创建 Web 知识源资源。

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

特定于源的属性

可以传递以下属性来创建 Web 知识源资源。

Name	Description	类型	可编辑	必选
`Name`	知识源的名称，该名称在知识源集合中必须唯一，并遵循Azure AI 搜索中对象的命名准则。	String	否	是的
`Description`	知识源的说明。如果未指定，Azure AI 搜索应用默认说明。	String	是的	否
`EncryptionKey`	客户管理的密钥，用于加密知识源中的敏感信息。	物体	是的	否
`WebParameters`	特定于 Web 知识源的参数。目前，只有 `Domains`。	物体	是的	否
`Domains`	用于在搜索空间中允许或阻止的域。默认情况下，知识源使用 Grounding 和Bing搜索来搜索整个公共 Internet。指定域时，知识源使用 Grounding 和Bing自定义搜索来限制指定域的结果。在这两种情况下，Bing自定义搜索是搜索提供程序。	物体	是的	否
`AllowedDomains`	需要包含在搜索空间中的域。对于每个域，必须以`address`格式指定其`website.com`。也可以通过将 ``IncludeSubpages`` 设置为 ``true`` 或 ``false`` 来指定是否包括域的子页。	Array	是的	否
`BlockedDomains`	需要排除在搜索空间之外的域名。对于每个域，必须以`address`格式指定其`website.com`。也可以通过将 ``IncludeSubpages`` 设置为 ``true`` 或 ``false`` 来指定是否包括域的子页。	Array	是的	否

Name	Description	类型	可编辑	必选
`name`	知识源的名称，该名称在知识源集合中必须唯一，并遵循Azure AI 搜索中对象的命名准则。	String	否	是的
`description`	知识源的说明。如果未指定，Azure AI 搜索应用默认说明。	String	是的	否
`encryption_key`	客户管理的密钥，用于加密知识源中的敏感信息。	物体	是的	否
`web_parameters`	特定于 Web 知识源的参数。目前，只有 `domains`。	物体	是的	否
`domains`	用于在搜索空间中允许或阻止的域。默认情况下，知识源使用 Grounding 和Bing搜索来搜索整个公共 Internet。指定域时，知识源使用 Grounding 和Bing自定义搜索来限制指定域的结果。在这两种情况下，Bing自定义搜索是搜索提供程序。	物体	是的	否
`allowed_domains`	需要包含在搜索空间中的域。对于每个域，必须以`address`格式指定其`website.com`。也可以通过将 ``include_subpages`` 设置为 ``true`` 或 ``false`` 来指定是否包括域的子页。	Array	是的	否
`blocked_domains`	需要排除在搜索空间之外的域名。对于每个域，必须以`address`格式指定其`website.com`。也可以通过将 ``include_subpages`` 设置为 ``true`` 或 ``false`` 来指定是否包括域的子页。	Array	是的	否

Name	Description	类型	可编辑	必选
`name`	知识源的名称，该名称在知识源集合中必须唯一，并遵循Azure AI 搜索中对象的命名准则。	String	否	是的
`kind`	知识源的类型，其为`web`在本例中。	String	否	是的
`description`	知识源的说明。如果未指定，Azure AI 搜索应用默认说明。	String	是的	否
`encryptionKey`	客户管理的密钥，用于加密知识源中的敏感信息。	物体	是的	否
`webParameters`	特定于 Web 知识源的参数。目前，只有 `domains`。	物体	是的	否
`domains`	用于在搜索空间中允许或阻止的域。默认情况下，知识源使用 Grounding 和Bing搜索来搜索整个公共 Internet。指定域时，知识源使用 Grounding 和Bing自定义搜索来限制指定域的结果。在这两种情况下，Bing自定义搜索是搜索提供程序。	物体	是的	否
`allowedDomains`	需要包含在搜索空间中的域。对于每个域，必须以`address`格式指定其`website.com`。也可以通过将 ``includeSubpages`` 设置为 ``true`` 或 ``false`` 来指定是否包括域的子页。	Array	是的	否
`blockedDomains`	需要排除在搜索空间之外的域名。对于每个域，必须以`address`格式指定其`website.com`。也可以通过将 ``includeSubpages`` 设置为 ``true`` 或 ``false`` 来指定是否包括域的子页。	Array	是的	否

分配给知识库

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

配置知识库后，使用执行 retrieve 操作来查询知识源。

删除知识来源

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

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

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

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

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

创建 Web 知识源资源

使用支持

先决条件

检查现有知识来源

创建知识来源

特定于源的属性

分配给知识库

删除知识来源

相关内容

Ressources supplémentaires