生成式AI提示技能

GenAI（生成式人工智能）提示词技能对部署在Azure OpenAI in Foundry Models或Microsoft Foundry中部署的大型语言模型（LLM）执行chat 请求。 利用这项技能创建新的信息，这些信息可以被索引并存储为可搜索内容。

以下是生成式AI提示技能如何帮助你创作内容的一些示例：

• 对图像进行口头处理
• 总结大量文本
• 简化复杂内容
• 做任何你能在提示中表达出来的任务

生成式AI提示技能通常可在2026-04-01 Search Service REST API以及针对该版本的Azure SDK中提供。 该技能支持文本、图像和多模态内容，如带视觉图像的图像和从PDF文件提取的文本。

支持的模型

• 可以使用 Foundry 中部署的任何 聊天完成推理模型 ，例如 GPT 模型、DeepSeek-R#、Llama-4-Maverick 和 Cohere-command-r。 针对GPT模型，只支持聊天完成API端点。 使用Azure OpenAI Responses API（URI 中包含 /openai/responses）的终端目前不兼容。

• 对于图像语言化，你用来分析图像的模型决定支持哪些图像格式。

• 对于GPT-5模型，该 temperature 参数的支持方式与以往模型不同。 如果定义了，必须设置为 1.0，否则其他值会导致错误。

• 计费是基于你所用模型的定价。

先决条件

• 一个Azure OpenAI in Foundry Models资源或 Foundry 项目。

• 一个已部署到你的资源或项目 中支持的模型 。

  • 对于Azure OpenAI，从Azure门户的openai.azure.com页面复制带有域的端点。 用这个端点表示 Uri 该技能的参数。

  • 对于 Foundry，从 Foundry 门户的 模型 页面复制部署的目标 URI。 用这个端点表示 Uri 该技能的参数。

• 认证可以基于密钥，使用来自 Foundry 或 Azure OpenAI 资源的 API 密钥。 不过，我们建议使用分配给角色的 搜索服务托管身份 进行基于角色的访问。

  • 在Azure OpenAI上，将Cognitive Services OpenAI User分配到托管身份。

  • 在 Foundry 上，将 Foundry 用户 分配到托管标识。

    Important

    最近重命名了 Foundry RBAC 角色。 Foundry User、Foundry Owner、 Foundry 帐户所有者，Foundry Project Manager以前被命名Azure AI 用户、Azure AI 所有者、Azure AI 帐户所有者和Azure AI Project 管理器。 在重命名推出时，你仍可能会在某些位置看到以前的名称。重命名后，角色 ID 和核心权限保持不变。

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

数据限制

技能参数

* 必须使用服务中恰好一个apiKey、 authIdentity或服务系统分配的身份。

commonModelParameters 默认值

技能输入

技能输出

示例定义

仅限文本的摘要

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Summarizer",
  "description": "Summarizes document content.",
  "context": "/document",
  "inputs": [
    { "name": "text", "source": "/document/content" },
    { "name": "systemMessage", "source": "='You are a concise AI assistant.'" },
    { "name": "userMessage", "source": "='Summarize the following text:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "apiKey": "<api-key>",
  "commonModelParameters": { "temperature": 0.3 }
}

文本 + 图片描述

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Image Describer",
  "context": "/document/normalized_images/*",
  "inputs": [
    { "name": "image", "source": "/document/normalized_images/*/data" },
    { "name": "imageDetail", "source": "=high" },
    { "name": "systemMessage", "source": "='You are a useful AI assistant.'" },
    { "name": "userMessage", "source": "='Describe this image:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "authIdentity": "11111111-2222-3333-4444-555555555555",
  "responseFormat": { "type": "text" }
}

结构化数值事实查找器

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "NumericalFactFinder",
  "context": "/document",
  "inputs": [
    { "name": "systemMessage", "source": "='You are an AI assistant that helps people find information.'" },
    { "name": "userMessage", "source": "='Find all the numerical data and put it in the specified fact format.'"}, 
    { "name": "text", "source": "/document/content" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "apiKey": "<api-key>",
  "responseFormat": {
    "type": "json_schema",
    "jsonSchemaProperties": {
      "name": "NumericalFactObj",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": "{\"facts\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"number\":{\"type\":\"number\"},\"fact\":{\"type\":\"string\"}},\"required\":[\"number\",\"fact\"]}}}",
        "required": [ "facts" ],
        "additionalProperties": false
      }
    }
  }
}

采样输出（截断）

{
  "response": {
    "facts": [
      { "number": 32.0, "fact": "Jordan scored 32 points per game in 1986-87." },
      { "number": 6.0,  "fact": "He won 6 NBA championships." }
    ]
  },
  "usageInformation": {
    "usage": {
      "completion_tokens": 203,
      "prompt_tokens": 248,
      "total_tokens": 451
    }
  }
}

最佳做法

• 用 文本拆分 技能创建分块长文档，保持在模型的上下文窗口内。
• 对于高流量索引，应专门为该技能部署一个模型，以确保查询时RAG工作负载的令牌配额不受影响。
• 为了最小化延迟，将模型和你的 Azure AI 搜索 服务共置在同一 Azure 区域。
• 配合responseFormat.json_schema使用，实现可靠的结构化提取和更便捷的索引字段映射。
• 监控代币使用情况，如果索引器超过了你的每分钟代币数（TPM）限制，请提交 配额增加请求 。

错误与警告

托管标识身份验证的安全注意事项

当 GenAI 提示技能使用托管标识身份验证时，Azure AI 搜索获取 Foundry 工具访问群体（https://cognitiveservices.azure.com）的Microsoft Entra访问令牌，并将其包含在发送到指定uri终结点的请求中。 托管标识身份验证适用于设置时authIdentity或同时为apiKeyauthIdentity空且服务使用系统分配的标识。

引用的uri终结点应是你自己的 openAI 或 Foundry 资源Azure。 支持的域名有：

• openai.azure.com
• cognitiveservices.azure.com
• services.ai.azure.com

Azure API 管理（APIM）终结点（*.azure-api.net）和前面这些资源的自定义域也受支持。 由于自定义域或 APIM 主机名不能单独从其名称进行验证，因此Azure AI 搜索在配置时通过实时连接检查来验证这些终结点，而不是通过域匹配来验证这些终结点。 你负责配置和维护终结点与其后面的 Azure OpenAI 或 Foundry 资源之间的关系。

建议的安全做法

若要帮助维护安全部署，请遵循以下做法：

• 仅设置为 uri 你拥有和信任的终结点。 首选前面列出的 Foundry Tools 域。 如果使用 APIM 或自定义域终结点，请在启用托管标识之前确认它位于自己的资源前面。 受信任的主机名不是所有权证明。
• 将最低特权原则应用于搜索服务使用的托管标识：
  • 在 Azure OpenAI 上，仅分配认知服务 OpenAI 用户。
  • 在 Foundry 上，仅分配 Foundry 用户。 避免授予更广泛的角色。
• 使用 网络安全外围（NSP） 和专用终结点或 VNet 集成来限制搜索服务可以访问的终结点，以及目标资源接受来自哪些源的请求。
• 如果使用 APIM 或自定义域终结点，请确保网关验证入站请求，并将请求转发到预期后端。 还应定期查看其访问策略。
• 首选托管标识而不是 apiKey。 如果使用 apiKey，请安全地存储和旋转它，不要将其嵌入源代码管理中。 服务拒绝同时设置 apiKey 和 authIdentity设置的配置。
• 定期查看技能组定义、托管标识角色分配以及 APIM 和自定义域配置，以确认 uri 值、访问控制和标识权限保持最新且合适。 通过建立的变更管理和安全评审流程查看配置更改。
• 监视 Azure OpenAI、Foundry 工具和 Foundry 登录日志、身份验证事件以及访问日志，以获取意外或未经授权的活动。
• 删除不再需要的技能、终结点、角色分配和 API 密钥。

限制对技能集配置的访问

可以创建、修改或运行技能集的用户控制目标终结点（uri）和技能使用的身份验证配置。 由于技能向该终结点发送 Foundry 工具受众的托管标识令牌，因此请在配置已启用托管标识的技能时将这些权限限制为受信任的管理员，并遵循标准变更管理和安全评审过程。

另请参阅

• Azure AI 搜索内置索引器
• 集成向量化
• 如何定义技能组
• 如何用Azure AI模型推理生成聊天完成（Foundry）
• 结构化输出Azure OpenAI