生成式AI提示技能

GenAI（生成式人工智慧）提示技能，會對部署於 Azure OpenAI in Foundry Models或 Microsoft Foundry 中部署的大型語言模型（LLM）執行chat 完成請求。 利用這項技能創造可索引並儲存為可搜尋內容的新資訊。

以下是生成式AI提示技能如何幫助你創作內容的一些範例：

• 將影像轉為文字描述
• 摘要長篇文字
• 簡化複雜內容
• 做任何你能在提示中表達的任務

GenAI 提示技能通常可在 2026-04-01 Search Service REST API 以及針對此版本的Azure SDK中取得。 此技能支援文字、圖片及多模態內容，例如帶有視覺效果的圖片，以及從 PDF 檔案擷取的文字。

支援的模型

• 你可以使用 Foundry 中部署的任何 聊天完成推論模型 ，例如 GPT 模型、DeepSeek-R#、Llama-4-Maverick 和 Cohere-command-r。 針對 GPT 模型，僅支援聊天完成 API 端點。 使用 Azure OpenAI 回應 API（URI 中包含 /openai/responses）的端點目前不相容。

• 對於影像語言化，你用來分析影像的模型決定支援哪些影像格式。

• 對於 GPT-5 模型，該 temperature 參數的支援方式與先前模型不同。 若定義，必須設為 1.0，否則其他值會導致錯誤。

• 帳單是根據你所使用的模式定價來計算的。

先決條件

• 一個Azure OpenAI in Foundry Models 資源或 Foundry 專案。

• 一個已部署到你的資源或專案 上的支援模型 。

  • 對於 OpenAI Azure，請從 Azure 入口網站的 openai.azure.com 頁面複製帶有 網域的端點。 用這個端點來設定 Uri 這個技能的參數。

  • 對於 Foundry，請從 Foundry 入口網站的 模型 頁面複製部署的目標 URI。 用這個端點來設定 Uri 這個技能的參數。

• 認證可以是基於金鑰的，使用 Foundry 或 Azure OpenAI 資源的 API 金鑰。 不過，我們建議使用分配給角色的 搜尋服務管理身份 來使用基於角色的存取。

  • 在 Azure OpenAI 上，將 Cognitive Services OpenAI User 指派到受管理身份。

  • 在 Foundry 中，將 Foundry User 指派到受管理身份。

    Important

    Foundry RBAC 職務最近已更名。 Foundry 用戶、Foundry 擁有者、Foundry Account Owner 以及 Foundry Project Manager 先前分別被稱為 Azure AI 使用者、Azure AI 擁有者、Azure AI 帳戶擁有者及 Azure AI Project 管理者。 在更名期間，你可能還會在某些地方看到之前的名字。角色 ID 與核心權限不會因命名而改變。

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

資料限制

技能參數

* 必須使用服務系統指派的身份中apiKeyauthIdentity、 。

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_schemaGPT-4o 進行可靠的結構化擷取，並更容易映射到索引欄位。
• 監控代幣使用情況，若索引器達到每分鐘代幣數（TPM）上限，請提交 配額增加請求 。

錯誤與警告

管理身份驗證的安全考量

當 GenAI 提示技能使用管理式身份驗證時，Azure AI 搜尋服務 會取得 Microsoft Entra 存取權杖，用於 Foundry Tools 受眾https://cognitiveservices.azure.com（），並將該憑證包含在發送給指定uri端點的請求中。 管理式身份驗證適用於authIdentity設定 時，或當 和 apiKey 皆authIdentity為空且服務使用系統指派的身份時。

所uri參考的端點預期是你自己的 Azure OpenAI 或 Foundry 資源。 支援的網域有：

• 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 Tools 及 Foundry 的登入日誌、認證事件，以及存取日誌中是否有意外或未經授權的活動。
• 移除不再需要的技能、端點、角色指派和 API 金鑰。

限制技能組設定的存取

能建立、修改或執行技能組的使用者，同時控制目標端點（uri）及技能所使用的認證設定。 由於該技能會將 Foundry Tools 受眾的管理身份憑證傳送到該端點，請將這些權限限制給受信任的管理員，並在配置啟用管理身份的技能時，遵循標準的變更管理與安全審查流程。

另請參閱

• Azure AI 搜尋服務內建索引器
• 整合向量化
• 如何定義技能組合
• 如何用Azure AI 模型推理產生聊天完成（Foundry）
• OpenAI