使用范围筛选结果

Microsoft Web IQ 中的作用域使你可以通过包括或排除 Web 搜索、新闻搜索和自动结果中的 URL、网站和域来微调地面 API 请求。

开发人员和企业管理员可以使用 Scopes,将 AI 体验建立在已批准和所需的 Web 源之上。 为 URL、域和路径定义可重用的包含和排除列表,以控制你的 grounding 搜索可返回的源。

范围是包含和排除规则的命名配置。 在 Web IQ 门户或计费帐户的客户管理 API 中创建它,然后在 Web 搜索、新闻搜索或自动请求中按名称选择它。 这两个管理选项都可与相同的命名作用域配合使用。 这些搜索范围不是 Microsoft Entra OAuth 权限范围。

Warning

对于 Auto,范围仅限制 Web 和新闻结果。 其他答案类型不会按范围进行筛选,并且可能包含其外部的结果,即使 scopeApplied 是 true。

业务方案和常见用例

Scenario 示例用例 如何使用作用域
精选研究 让研究助理基于贵组织审核过的来源,例如获批准的医学出版物。 包括已批准的域、子域或单个页面。
组织来源策略 从 Web 搜索和新闻搜索依据结果中排除贵组织限制的域名。 维护排除列表,并为每个请求选择范围。
自有站点搜索 将支持助理或面向员工的搜索体验限制为对外公开的产品、帮助或公司网站。 包括你自己的域和相关文档路径。
精选新闻监测 基于所选的一组发布商生成新闻摘要。 在新闻搜索请求中包含发布者域并选择范围。

范围用于筛选可用于所选搜索终结点的内容。 包含的源并不能保证匹配内容已编入索引或会被返回。

Prerequisites

  • 有效的 Web IQ 计费帐户。
  • 若要使用 API 创建范围,请使用现有Microsoft Entra应用程序、其租户 ID 和应用程序(客户端)ID 以及 OAuth 2.0 客户端凭据流的凭据。 其工作负荷标识必须处于活动状态,并且在预期的 Web IQ 计费帐户上具有 CustomerApiAccess。

Important

单独授予对搜索 API 和 Web IQ 管理 API 的访问权限。 绑定到 Web IQ 运行时配置文件的工作搜索 API 密钥或 Entra 应用程序不授予创建范围的权限。 工作负荷需要单独的计费帐户管理授予。

若要检查门户访问权限,请打开 Scopes 并查找预期的计费帐户和 New scope 控件。 如果页面、帐户或创建控件不可用,请让帐户管理员检查访问权限,或联系 Web IQ 支持部门。

为范围命名并选择来源

剪裁后,选择最多包含 128 个字符的范围名称。 支持的字符包括 ASCII 字母、数字、句点(.)、下划线(_)和连字符(-)。 不支持空格和斜杠。 名称在作用域集合内以不区分大小写的方式保持唯一。

Web IQ 计费账户中的 Web IQ AppID 通过该账户分配的范围集合共享这些范围。 它们不是每个 AppID 的单独配置。 如果计费帐户共享集合,则它们共享相同的范围和名称。

  • 包含 将结果限制为与范围包含列表中至少一个条目匹配的源。 如果列表为空,则所有非排除源都符合条件。
  • 排除 会排除与范围排除列表中任何条目匹配的结果,即使它们也与包含规则匹配。 排除始终优先。

可以包括或排除域、URL 路径或单个网页。 每个条目称为 选择器:

Selector Example 匹配
域名 example.com 域及其后代子域
路径前缀 docs.example.org/products 该主机上的指定路径及其子路径,但不包括诸如 /products-old 之类的路径
确切 URL https://docs.example.org/products/guide 确切的 HTTPS URL,而不是路径下的每一页

添加 https:// 使选择器与确切 URL 匹配,而不是域名前缀或路径前缀。 不支持通配符,例如 *.example.com、显式端口、查询字符串和片段。 保留路径大小写。 命名范围选择器对子目录深度没有单独的限制,但在修整和规范化之后,每个选择器必须容纳在 2,048 个字符内。

API 会对条目进行规范化、排序和去重。 已接受的选择器并不能保证对匹配的内容建立索引或返回。

在门户中创建范围定义

  1. 打开 Web IQ 门户中的“Scopes”。
  2. 选择预期的 计费帐户。
  3. 选择“新建范围”。 在 “创建新作用域”中,输入 作用域名称,例如 ProductDocs,并创建作用域。
  4. 在范围详细信息页上,使用“添加网站”按钮在“包含”选项卡上添加要包含的源。 使用 “排除 ”选项卡上的相同按钮添加要排除的源,例如 ads.example.com。
  5. 查看这两个列表,选择“发布”,然后确认“发布更改?”

发布后,传播到搜索通常需要大约 10 分钟,但在某些情况下最多可能需要 30 分钟。 在应用程序中依赖它之前,请验证范围。

在搜索请求中选择作用域

单独配置 运行时搜索身份验证 。 所选的 Web IQ 应用配置文件必须属于其集合包含您的作用域的 Web IQ 计费账户。

对于 、 或 ,请在 JSON 请求正文中设置以下可选字段。 所有三个终结点都使用相同的命名范围设置。

参数 类型 Behavior
scopeName 字符串 现有范围的名称,例如 ProductDocs。 它的包含和排除规则筛选请求的结果。 对于“自动”,范围仅限制 Web 和新闻结果。 其他答案类型不会按范围进行筛选,并且可能包含其外部的结果,即使 scopeApplied 是 true。 如果省略或为 null,则不请求任何命名范围。
failOnMissingScope boolean 默认为 true,包括省略时或 null。 当 true 时,报告的范围应用失败会返回错误,而不是未限定范围的结果。 如果无法应用搜索范围,则搜索可以在没有该范围的情况下继续进行。 仅当未限定范围的结果可以接受时使用 false。 没有 scopeName 时不起作用。

在以下示例中使用单独配置的运行时 API 密钥。

筛选 Web 搜索结果

若要搜索 ProductDocs 允许的网页,请发送:

POST /v3/search/web HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json

{
  "query": "product setup guide",
  "scopeName": "ProductDocs",
  "failOnMissingScope": true,
  "maxResults": 10,
  "contentFormat": "passage",
  "maxLength": 3000
}

筛选新闻搜索结果

若要搜索同一范围允许的新闻文章,请使用新闻搜索终结点。 选择包含索引新闻内容的源;包含的网页不一定可通过新闻搜索获得。

POST /v3/search/news HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json

{
  "query": "product announcements",
  "scopeName": "ProductDocs",
  "failOnMissingScope": true,
  "maxResults": 10,
  "contentFormat": "passage",
  "maxLength": 3000
}

筛选 Auto 结果

对于“自动”,范围仅限制 Web 和新闻结果。 其他答案类型不会按范围进行筛选,并且可能包含其外部的结果,即使 scopeApplied 是 true。 如果只想包含限定范围内的 Web 和新闻证据,请包括 responseFilter: ["web", "news"]:

POST /v3/auto HTTP/1.1
Host: api.microsoft.ai
x-apikey: <runtime-api-key>
Content-Type: application/json

{
  "query": "product setup guide",
  "scopeName": "ProductDocs",
  "failOnMissingScope": true,
  "mode": "lite",
  "responseFilter": ["web", "news"]
}

解读结果

Web 搜索在 webResults 中返回结果,新闻搜索在 newsResults 中返回结果,Auto 在 results 中返回证据项(AutoEvidenceResponse)。 有效的范围可能返回无匹配结果,例如,当没有已编制索引的内容同时匹配查询和该范围的规则时。

使用 failOnMissingScope: true(默认值)时,出现的范围应用失败将返回错误,而不是未应用范围的结果。 已确认缺少作用域时,返回 HTTP 400(HandlerInvalidInput);其他作用域应用失败返回 HTTP 500(ScopeFailedToApply)。 有关恢复指导,请参阅 命名范围错误。

如果将设置为且找不到该作用域,则搜索将在没有该作用域的整个索引上运行,并且响应包含。 当名称不正确或范围尚未传播到处理请求的分区或副本时,可能会发生这种情况。

找到并应用所请求的范围时,响应包含 false,即使 "scopeApplied": true 为 failOnMissingScope。 这确认了该请求已应用该范围,而不是其最新定义已被使用,或者该更改已传播到每个分区或副本。 如果未报告任何应用结果,则响应将省略 scopeApplied;不要将缺失的属性视为证明已应用该范围的证据。

如果省略 scopeName 或将其设置为 null,则不会请求命名范围,并且 failOnMissingScope 不起作用。 对于没有命名作用域的请求,不要认为 scopeApplied 始终会以 false 的值出现。

仅当应用程序可以接受无作用域的结果时,才使用 scopeApplied,并检查响应中的 false。 当需要作用域时,请不要实现一种回退机制,即移除该作用域后重试不受限请求。 有关请求参数和响应字段,请参阅 Web 搜索、 新闻搜索和 自动 引用。

使用 API 创建范围

所有管理请求都使用 /v1/customer/,路径以 https://api.microsoft.ai 开头。 将示例中的 <access-token> 和 <billingAccountId> 替换为预期的帐户 ID 和仅限应用的访问令牌。 授权资源引用和范围管理参考描述了端点约定。

授予应用程序对管理 API 的访问权限

计费帐户或客户管理员授予访问权限:

  1. 使用现有的Microsoft Entra应用注册或在Azure门户中注册应用程序。
  2. 在 Web IQ 门户中打开帐户设置。
  3. 选择预期的计费帐户。
  4. 在 “管理 API 访问权限”下,选择“授予对 Entra 应用的访问权限”。
  5. 在 “向此计费帐户授予 Entra 应用程序访问权限”对话框 中,确认计费帐户名称和 ID。 输入应用程序的 租户 ID 和 应用程序(客户端)ID,以及所需 显示名称的非空白值。
  6. 选择 “授予管理 API 对此应用程序的访问权限”,然后选择 “授予访问权限”。

授予访问权限可授权现有标识。 它不会创建 Entra 应用程序、机密、证书或搜索 API 密钥。 该授予适用于所选计费帐户。

该授权会分配 CustomerApiAccess 角色。 它不是仅限作用域的权限或只读权限:它允许帐户发现、范围读取和写入,以及配置文件的运行时 Entra ID 管理。 它不允许应用程序授予对其他应用程序的访问权限。 将授予限制为需要这些管理功能的应用程序。

获取仅限应用的令牌

使用应用程序的现有凭据和客户端凭据流来请求Microsoft Entra访问令牌:

设置 价值
权威 https://login.microsoftonline.com/<tenant-id>
令牌请求范围 https://api.microsoft.ai/.default

使用确切的 .default scope,而不是要创建的搜索范围的名称。 在每个管理请求上发送令牌:

Authorization: Bearer <access-token>

不要为这些管理调用使用搜索 API 密钥。 不要将访问令牌和应用程序凭据提交到源代码管理或写入诊断报告。

查找计费帐户

使用仅限应用的令牌调用 GET https://api.microsoft.ai/v1/customer/authorized-resources。 为创建请求选择目标账户的billingAccounts[].billingAccountId;不要自动选择第一个账户。

将 授权资源引用 用于响应架构、ID 定义和权限字段解释。

发送创建请求

使用所选的计费帐户 ID,使用范围名称和规则发送 POST /v1/customer/billing-accounts/{billingAccountId}/scopes 。 例如:

{
  "name": "ProductDocs",
  "includeSites": ["example.com", "docs.example.org/products"],
  "excludeSites": ["ads.example.com"]
}

提供这两个数组,使用 [] 表示有意留空的列表。 在 201 Created 上,保存返回的定义和 ETag 以供以后更改。

有关标头、验证规则和响应详细信息,请参阅 创建范围协定。 若要更改现有范围而不是创建新范围,请使用 更新操作。

使用前验证作用域

  1. 读取已保存的范围 ,并确认其规则与预期源匹配。
  2. 使用 运行具有代表性的failOnMissingScope: true。 在启用依赖流量之前,请检查包含和排除的情况。

Important

生效通常需要大约 10 分钟,但在某些情况下最多可能需要 30 分钟。 没有传播 SLA,而且这些时间不作保证。 成功的管理写入或读取、发布或 scopeApplied: true 并不能证明最新定义已生效。 不要单独使用已用时间作为准备情况检查。 有关详情,请参阅 搜索传播。

发布更改后的定义

如果暂时使用以前的定义是不可接受的,请创建具有新名称的范围,例如 ProductDocs-v2。 在切换呼叫者之前完成上述验证步骤,并保留以前的范围,直到调用方不再依赖它。

这将在验证期间保留旧名称的含义不变;它不提供原子全局开关。

保留并发保护以供以后更改

在编辑或删除当前范围之前读取当前范围,并在 If-Match 中发送其带引号的 ETag。 在协调并发编辑或重试写入时,请遵循 并发和不确定结果指南 。 如果需要更改历史记录,请将审阅的定义保留在您自己的权威信息源中。

排查创建过程中的问题

如果预期帐户不在发现中,请让管理员检查工作负荷的标识、管理授权和帐户资格。 对于其他故障,请使用 发现状态引用 或 范围管理错误引用。

对于持续出现的失败,请联系 Web IQ 支持 部门,并提供计费帐户 ID、范围名称、UTC 操作时间、HTTP 状态和可用的请求 ID。 包括经脱敏处理的预期行为和实际行为,绝不包括令牌、API 密钥或应用程序凭据。