将 Azure AI 服务资源附加到 Azure AI 搜索中的技能组

2025-09-15

如果您要在 Azure AI 搜索中使用内置技能来增强可选的 AI 功能，可以免费增强少量文档，每个索引每天最多可处理 20 个事务。对于更大且更频繁的工作负荷，应附加可计费的 Azure AI 服务多服务资源。

Azure AI 搜索使用专用的、内部托管的 Azure AI 服务多项服务资源来执行内置技能，但出于计费目的，需要使用你的多项服务资源。

Azure AI 服务多服务资源提供一系列 Azure AI 服务，而不是单个服务。在 Azure AI 搜索技能集中提供多服务资源后，Azure 可以向你收取使用这些服务的费用：

Azure AI 视觉，用于图像分析、光学字符识别 (OCR) 和多模态嵌入
用于语言检测、实体识别、情绪分析和关键短语提取的 Azure AI 语言
用于机器文本翻译的Azure AI 翻译

通过多服务资源计费的例外情况包括 AzureOpenAIEmbedding 计费。 Azure AI 搜索不会直接托管来自 Azure OpenAI 或 Azure AI Foundry 模型目录的模型。 AML 和 Azure OpenAI 技能与矢量化工具的使用费用分别通过 Azure OpenAI 标准预付费套餐定价和 Azure 机器学习标准预付费套餐定价计算。其他一些技能（如文本拆分和文本合并）不可计费。

若要附加 Azure AI 多服务资源，必须在技能集中提供连接信息。可以在连接上使用密钥，也可以实现当前处于预览状态的无密钥方法。

提示

Azure 提供用于监视计费和预算的基础结构。

先决条件

除非你的搜索服务满足与 Azure AI 服务多服务资源的专用连接的创建日期、层和区域要求，否则通过公共终结点建立连接。

注意

如果 Azure AI 资源配置为使用专用终结点，Azure AI 搜索可以使用共享专用链接进行连接。有关详细信息，请参阅使用共享专用链接的要求和限制。

通过无密钥连接计费

使用 Azure 门户或较新的预览版 REST API 和 beta 版 SDK 包，可以使用托管标识和权限附加 Azure AI 服务多服务资源。此方法的优点是计费是无密钥的，并且不依赖于区域。

将 Azure AI 搜索配置为使用托管标识。
在 Azure AI 服务多服务资源上，将标识分配给认知服务用户角色。
使用 Azure 门户或技能集 2024-11-01-preview REST API 或更高版本，或者使用提供语法的 Azure SDK beta 版包配置技能集以使用标识：
- 连接中使用的托管标识属于搜索服务。可以是系统托管的，也可以是用户分配的。
- 标识必须具有对 Azure AI 资源的“认知服务用户”权限。
- @odata.type 始终为 #Microsoft.Azure.Search.AIServicesByIdentity。
- subdomainUrl 是 Azure AI 服务多服务资源的终结点。子域 URL 必须包含唯一的名称（例如 https://hereismyuniquename.cognitiveservices.azure.com）。如果服务是通过 Azure 门户创建的，则会在服务设置过程中自动生成唯一子域。确保在将服务与 Azure AI 搜索集成之前，服务中已包含一个独特子域名。

与密钥一样，提供有关 Azure AI 服务资源的详细信息用于计费，而不是连接。 Azure AI 搜索向 Azure AI 服务发出的用于内置技能处理的所有 API 请求将继续保持为内部请求，并由 Azure 管理。

示例：系统分配的托管标识

标识设置为 null。

POST https://[service-name].search.azure.cn/skillsets/[skillset-name]?api-version=2024-11-01-Preview  

{  
    "name": "my skillset name",  
    "skills":   
    [  
      // skills definition goes here 
    ],  
    "cognitiveServices": {  
        "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",  
        "description": "",  
        "subdomainUrl": "https://[subdomain-name].cognitiveservices.azure.com",  
        "identity": null 
    }  
}

示例：用户分配的托管标识

标识设置为用户分配的托管标识的资源 ID。若要查找现有的用户分配的托管标识，请参阅管理用户分配的托管标识。

对于用户分配的托管标识，请设置 @odata.type 和 userAssignedIdentity 属性。

POST https://[service-name].search.azure.cn/skillsets/[skillset-name]?api-version=2024-11-01-Preview  

{  
    "name": "my skillset name",  
    "skills":   
    [  
      // skills definition goes here 
    ],  
    "cognitiveServices": {  
        "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",  
        "description": "",  
        "subdomainUrl": "https://[subdomain-name].cognitiveservices.azure.com",  
        "identity": {   
            "@odata.type":  "#Microsoft.Azure.Search.DataUserAssignedIdentity",   
            "userAssignedIdentity": ""/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"" 
        }
    } 
}

通过资源密钥计费

Azure AI 搜索还可以使用 Azure AI 服务多服务资源密钥对事务收费。此方法是默认方法，已正式发布。可以使用 Azure 门户、REST API 或 Azure SDK 将密钥添加到技能集。

有两种受支持的密钥类型：调用区域终结点的 #Microsoft.Azure.Search.CognitiveServicesByKey 和调用子域的 "#Microsoft.Azure.Search.AIServicesByKey。建议使用 AIServicesByKey 来提供其共享专用链接支持，并支持在没有与搜索服务相关的区域要求的情况下正常运行。

Azure AI 服务多服务资源必须与 Azure AI 搜索位于同一区域。有关详细信息，请参阅 Azure AI 搜索支持的区域，并选择提供 AI 服务集成的区域。

如果未指定 cognitiveServices 属性，搜索服务会尝试使用索引器每天可用的免费扩充量。每个索引器调用执行 20 个事务后会停止执行计费技能，索引器执行历史记录中会显示“超时”消息。

Azure 门户
休息
.NET SDK

登录 Azure 门户。
在搜索服务所在的同一区域中创建 Azure AI 服务多服务资源。
从“资源”“密钥和终结点”页获取资源密钥。>
向技能组定义添加密钥：
- 如果使用导入数据向导，请创建或选择 Azure AI 服务资源。该向导会将资源密钥添加到技能集定义。
- 对于新的或现有的技能集，请提供技能集定义中的密钥。

注意

Azure 门户会自动附加 #Microsoft.Azure.Search.CognitiveServicesByKey 类型的密钥。

使用创建或更新技能集 API，指定请求正文中的 cognitiveServices 部分：

PUT https://[servicename].search.azure.cn/skillsets/[skillset name]?api-version=2024-11-01-Preview
api-key: [admin key]
Content-Type: application/json
{
    "name": "skillset name",
    "skills": 
    [
      {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "categories": [ "Organization" ],
        "defaultLanguageCode": "en",
        "inputs": [
          {
            "name": "text", "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "organizations", "targetName": "organizations"
          }
        ]
      }
    ],
    "cognitiveServices": {
        "@odata.type": "#Microsoft.Azure.Search.AIServicesByKey",
        "description": "mycogsvcs",
        "subdomainUrl": "https://[subdomain-name].cognitiveservices.azure.cn",
        "key": "<your key goes here>"
    }
}

以下代码片段来自 azure-search-dotnet-samples，为简洁起见，已进行剪裁。

IConfigurationBuilder builder = new ConfigurationBuilder().AddJsonFile("appsettings.json");
IConfigurationRoot configuration = builder.Build();

string searchServiceUri = configuration["SearchServiceUri"];
string adminApiKey = configuration["SearchServiceAdminApiKey"];
string cognitiveServicesKey = configuration["CognitiveServicesKey"];

SearchIndexerClient indexerClient = new SearchIndexerClient(new Uri(searchServiceUri), new AzureKeyCredential(adminApiKey));

// Create the skills
Console.WriteLine("Creating the skills...");
OcrSkill ocrSkill = CreateOcrSkill();
MergeSkill mergeSkill = CreateMergeSkill();

// Create the skillset
Console.WriteLine("Creating or updating the skillset...");
List<SearchIndexerSkill> skills = new List<SearchIndexerSkill>();
skills.Add(ocrSkill);
skills.Add(mergeSkill);

SearchIndexerSkillset skillset = CreateOrUpdateDemoSkillSet(indexerClient, skills, cognitiveServicesKey);

删除密钥

扩充是收费操作。如果不再需要调用 Azure AI 服务，请按照这些说明移除多服务密钥并阻止使用外部资源。如果没有密钥，技能组会还原为每天为每个索引器默认分配 20 个免费事务。在达到 20 个事务后会停止执行计费技能，在分配用完时，索引器执行历史记录中会显示“超时”消息。

Azure 门户
休息

登录 Azure 门户。
在“搜索管理 > 技能集”下，从列表中选择技能集。
滚动到文件中包含 "cognitiveServices" 的部分。
从 JSON 中删除密钥值并保存技能集。

获取技能组，以便获得完整定义。
制定更新技能组请求，提供技能组的 JSON 定义。

删除定义正文中的密钥，然后发送请求：

PUT https://[servicename].search.azure.cn/skillsets/[skillset name]?api-version=2024-07-01
api-key: [admin key]
Content-Type: application/json
{
    "name": "skillset name",
    "skills": 
    [
      {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "categories": [ "Organization" ],
        "defaultLanguageCode": "en",
        "inputs": [
          {
            "name": "text", "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "organizations", "targetName": "organizations"
          }
        ]
      }
    ],
    "cognitiveServices": {
        "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
        "description": "mycogsvcs",
        "key": ""
    }
}

或者，可以将“cognitiveServices”设置为 null：

"cognitiveServices": null,

如何使用密钥

如果每个索引器每天对 Azure AI 服务资源的 API 调用数超过 20 次 API 调用，则计费将生效。可以重置索引器以重置 API 计数。

无密钥连接和基于密钥的连接用于计费，但不用于扩充操作的连接。

对于基于键的连接，搜索服务通过内部网络连接到位于同一物理区域中的 Azure AI 服务资源。提供 Azure AI 搜索的大多数区域也提供其他 Azure AI 服务，例如语言。如果尝试在不同时具备这两种服务的区域中进行 AI 扩充，则会看到以下消息：“提供的密钥不是搜索服务区域的有效 CognitiveServices 类型密钥。”

对于无密钥连接，搜索服务使用其标识和角色分配进行身份验证，目标是指定为完全限定 URI 的 Azure AI 服务多服务资源，且在该 URI 中具有唯一的子域。

可以将索引器配置为在专用执行环境中运行，仅使用自己的搜索服务的搜索节点进行专用处理。即使使用的是专用执行环境，Azure AI 搜索仍使用其内部预配的 Azure AI 服务多服务资源来执行所有技能扩充。

注意

某些内置技能基于非区域 Azure AI 服务（例如文本翻译技能）。使用非区域性技能意味着可能会在 Azure AI 搜索区域以外的区域中为你的请求提供服务。有关非区域性服务的详细信息，请参阅 Azure AI 服务产品（按区域）页。

公共连接要求

根据搜索服务的创建时间、层级和区域，内置技能的计费可能需要通过公共连接从 Azure AI 搜索连接到 Azure AI 服务多服务。在某些情况下，禁用公用网络访问会中断计费。查看通过共享专用链接进行连接的要求，以确定搜索服务是否需要公共连接。

如果无法使用公用网络，可以配置使用 Azure Function 实现的自定义 Web API 技能，该功能支持专用终结点，并且将 Azure AI 服务资源添加到同一 VNET。在这种方式下，您可以通过私有终结点直接从自定义技能调用 Azure AI 服务资源。

关键要求特殊情况

自定义实体查找是由 Azure AI 搜索（而不是 Azure AI 服务）进行计量的，但要解锁超过每天每个索引器 20 次的事务，则需要 Azure AI 服务的多服务资源密钥。仅针对此技能，资源键解锁事务数量，但与计费无关。

免费扩充

AI 扩充为可计费扩充提供少量免费处理，因此你无需附加 Azure AI 服务多服务资源即可完成简短练习。每个索引器每天的免费扩充量为 20 个文档。如果你需要重复练习，可以重置索引器以重置计数器。

有些扩充始终免费：

不调用 Azure AI 服务的实用工具技能（即条件、文档提取、整形程序、文本合并和文本拆分技能）不可进行计费。
从 PDF 文档和其他应用程序文件提取文本是不计费的。文本提取在文档破解期间发生，它不是扩充，但在 AI 扩充过程中发生，因此在此进行说明。

可计费的扩充

在 AI 扩充期间，Azure AI 搜索会调用 Azure AI 服务 API，以获取基于 Azure AI 视觉、翻译和 Azure AI 语言的内置技能。

向 Azure AI 服务进行后端调用的可计费内置技能包括实体链接、实体识别、图像分析、关键短语提取、语言检测、OCR、个人身份信息 (PII) 检测、情绪、文本翻译和 Azure AI 视觉多模型嵌入技能。

Azure AI 视觉多模式嵌入模型支持的查询时间矢量化器也是可计费的扩充。

图像提取是一种 Azure AI 搜索操作，该操作在文档扩充前被破解时发生。图像提取对所有层都是收费的，免费层每日 20 次免费提取除外。图像提取成本适用于 blob 中的图像文件、其他文件（PDF 和其他应用程序文件）中的嵌入图像以及使用 Document Extraction 提取的图像。有关图像提取定价，请参阅 Azure AI 搜索定价页。

提示

为了降低技能组处理的成本，启用增量扩充以缓存和重复使用任何不受技能组更改影响的扩充。缓存需要 Azure 存储（请参阅定价），但如果可以重复使用现有的扩充，则技能组执行的累积成本会降低，尤其是对于使用图像提取和分析的技能组。

示例：估算成本

若要估算 Azure AI 搜索索引编制的相关成本，请先构想一下文档的大致结构，以便能够得出一些数字。例如，可以使用以下似近值：

1,000 个 PDF。
每个 PDF 有 6 个页面。
每个页面包含一个图像（共 6,000 个图像）。
每个页面包含 3,000 个字符。

假设管道的功能包括：每个 PDF 的文档破解、图像和文本提取、图像的光学字符识别 (OCR)，以及组织的实体识别。

本文中所示的价格是虚构的。这些价格用于演示估算过程。你的成本可能更低。有关事务的实际价格，请参阅 Azure AI 服务定价。

破解包含文本和图像内容的文档时，文本提取目前是免费的。对于 6,000 个图像，假设每提取 1,000 个图像需要 $1。则此步骤的成本是 $6.00。
对于英语环境中 6000 个图像的 OCR，OCR 认知技能使用最佳算法 (DescribeText)。假设每分析 1,000 个图像的成本为 $2.50，则这一步需要支付 $15.00。
提取实体时，每页总共有 3 个文本记录。每条记录包含 1,000 个字符。每页 3 个文本记录 * 6,000 页 = 18,000 个文本记录。假设 1000 个文本记录的成本为 $2.00，则这一步的成本为 $36.00。

综合起来，在使用上述技能组引入 1,000 个此类 PDF 文档时，需要支付大约 $57.00。

共用方式為