你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

GenAI 提示技能

2025-09-18

Note

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

GenAI（生成 AI）提示技能针对 Azure AI Foundry 或 Azure AI Foundry 模型中部署的大型语言模型（LLM）执行聊天完成请求。使用此功能可创建可索引并存储为可搜索内容的新信息。

下面是 GenAI 提示技能如何帮助你创建内容的一些示例：

对图像进行口头处理
汇总大段文本
简化复杂内容
执行可在提示中阐明的任何其他任务

GenAI 提示技能在最新的预览版 REST API 中可用。此技能支持文本、图像和多模式内容，例如包含文本和图像的 PDF。

Tip

通常将此技能与数据分块技能结合使用。以下教程演示了使用两种不同的数据分块技术进行图像语言化：

支持的模型

可以使用 AI Foundry 中部署的任何聊天完成推理模型，例如 GPT 模型、Deepseek R#、Llama-4-Mavericj、Cohere-command-r 等。
对于图像语言化，用于分析图像的模型决定了支持哪些图像格式。
对于 GPT-5 模型， temperature 参数与以前的模型一样不受支持。如果已定义，则必须将其设置为 1.0，因为其他值将导致错误。
计费基于你使用的模型的定价。

Note

搜索服务通过公共终结点连接到模型，因此没有区域位置要求，但如果使用的是全面 Azure 解决方案，则应检查 Azure AI 搜索区域和 Azure OpenAI 模型区域以查找合适的对，尤其是在数据驻留要求的情况下。

Prerequisites

Azure AI Foundry 或 Azure OpenAI 中部署的聊天完成模型（例如 gpt-4o 或任何兼容的开源软件（OSS）模型。
- 从 Foundry 门户中的 Models + Endpoints 或 Azure OpenAI 资源子域（*.openai.azure.com）复制终结点。
- 在 Uri 技能定义的参数中提供此终结点。
可以使用 Azure AI Foundry 或 Azure OpenAI 资源的 API 密钥基于密钥进行身份验证。但是，我们建议使用分配给角色的搜索服务托管标识进行基于角色的访问。
- 在 Azure OpenAI 上，将 认知服务 OpenAI 用户 分配到托管标识。
- 对于 AI Foundry 模型，请分配 Azure AI 用户。

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

数据限制

Limit	Notes
`maxTokens`	如果省略，则默认值为 1024 。最大值取决于模型。
请求超时	30 秒（默认值）。使用 `timeout` 属性（`PT##S`）替代。
Images	支持 Base 64 编码的图像和图像 URL。大小限制依赖于模型。

技能参数

Property	类型	Required	Notes
`uri`	字符串	Yes	已部署模型的公共终结点。
`apiKey`	字符串	Cond.*	模型的密钥。使用托管标识时留空。
`authIdentity`	字符串	Cond.*	用户分配的托管标识客户端 ID（仅限 Azure OpenAI）。留空以使用系统分配的标识。
`commonModelParameters`	对象	No	标准生成控件，例如 `temperature`， `maxTokens`等等。
`extraParameters`	对象	No	打开传递到基础模型 API 的字典。
`extraParametersBehavior`	字符串	No	`"pass-through"` \| `"drop"` \| `"error"` （默认值 `"error"`）。
`responseFormat`	对象	No	控制模型是返回文本、自由格式 JSON 对象还是强类型 JSON 架构。 `responseFormat` 有效负载示例：{responseFormat： { type： text }}， {responseFormat： { type： json_object }}， {responseFormat： { type： json_schema }}

* 必须使用服务的系统apiKey标识之一authIdentity。

`commonModelParameters` 违约

Parameter	Default
`model`	（部署默认值）
`frequencyPenalty`	0
`presencePenalty`	0
`maxTokens`	1024
`temperature`	0.7
`seed`	null
`stop`	null

技能输入

输入名称	类型	Required	Description
`systemMessage`	字符串	Yes	系统级指令（例如：“你是一个有用的助手”。
`userMessage`	字符串	Yes	用户提示。
`text`	字符串	No	追加到 `userMessage` （仅限文本的方案）的可选文本。
`image`	string （Base 64 data-URL）	No	将图像添加到提示（仅多模式模型）。
`imageDetail`	string （`low` \| `high` \| `auto`）	No	Azure OpenAI 多模式模型的保真提示。

技能输出

输出名称	类型	Description
`response`	字符串或 JSON 对象	采用所 `responseFormat.type`请求格式的模型输出。
`usageInformation`	JSON 对象	模型参数的令牌计数和回显。

示例定义

仅限文本的摘要

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Summarizer",
  "description": "Summarizes document content.",
  "context": "/document",
  "timeout": "PT30S",
  "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 区域中共同定位模型和 Azure AI 搜索服务。
与 responseFormat.json_schema 一起使用，以实现可靠的结构化提取，并更轻松地映射到索引字段。
如果索引器使令牌每分钟（TPM）限制饱和，请监视令牌使用情况并提交 配额增加请求 。

错误和警告

Condition	Result
缺失或无效 `uri`	Error
未指定身份验证方法	Error
同时 `apiKey` 提供和 `authIdentity` 提供	Error
多模式提示的不受支持的模型	Error
输入超过模型令牌限制	Error
模型返回无效的 JSON `json_schema`	警告 - 在 <a0/> 中返回的原始字符串

另请参阅

反馈

此页面是否有帮助？