生成式AI提示技能

Note

Foundry IQ(Azure AI 搜尋服務)提供直接的索引與查詢 API,並搭配高階知識來源與知識庫 API 用於受控檢索。 使用 Azure 入口網站、REST API 或 Azure SDK 來設定這些功能,或將代理連線到 Microsoft Foundry 入口網站 中的知識庫。

有關適用於非 Microsoft 模型的支援直接或 API 管理連線的術語,請參閱「第三方模型」。

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

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

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

使用 2026-10-01 搜尋服務 REST API 來取得一般可用的 GenAI 提示詞技能功能。 這項技能也可在支援它的 Azure SDK 中取得。 此技能支援文字、圖片及多模態內容,例如帶有視覺效果的圖片,以及從 PDF 檔案擷取的文字。

Tip

這項技能常常會與資料分塊技能結合使用。 多模態教學示範了兩種不同的資料分塊策略來進行影像語言化。

支援的模型

  • 使用部署於 Microsoft Foundry 的聊天完成推論模型,該模型接受技能的輸入與生成參數。 設定支援您技能所使用的參數與回應格式的聊天完成作業。

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

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

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

Note

除非您設定符合資格的私有執行路由,否則模型呼叫會使用公開端點。 請參閱 API 管理連線資格。 在選擇部署位置時,請檢查 Foundry IQ(Azure AI 搜尋服務)區域及 Azure OpenAI 模型區域。

先決條件

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

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

    • 對於 Azure OpenAI,請以資源openai.azure.com端點為基礎,以網域為基礎,建立完整的聊天完成呼叫 URI:https://<resource-name>.openai.azure.com/openai/deployments/<deployment-name>/chat/completions?api-version=<downstream-api-version>。 將部署名稱及下游 API 版本替換為您的 Azure OpenAI 部署所支援的值。 設定 uri 為完整 URL,而非資源基底端點。 下游 API 版本與搜尋 API 版本是分開的。

    • 對於 Foundry,請使用部署中完整的聊天完成目標 URI,包括操作路徑及任何必要的查詢參數。uri

  • 認證可以是基於金鑰的,使用 Foundry 或 Azure OpenAI 資源的 API 金鑰。 不過,我們建議使用指派給角色的 Foundry IQ 服務管理式身份 ,進行基於角色的存取。

    • 針對 Azure OpenAI 部署,請將 Cognitive Services OpenAI User 指派至 Foundry IQ 服務的系統指派或選取的使用者指派管理身份。 請使用承載部署且擁有已設定端點的 Azure OpenAI 或父 Foundry/Azure AI Services 資源,而非專案物件或 Foundry IQ 服務。

    • 對於其他支援的 Foundry 託管模型端點,請將 Foundry User 指派給該模型連線所需的資源範圍的管理身份。

      Important

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

    • 如果 API 管理終止搜尋驗證並使用其自身的後端身份,請在閘道授權搜尋。 改為將模型角色指派給模型託管資源上的該閘道識別碼。 請參閱 角色範圍與身份識別碼。

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

資料限制

極限 Notes
maxTokens 若省略,預設為 1024 。 最大值依模型而異。
要求逾時 修正為30秒。 在選擇批量索引模型時,請考慮這個限制,因為推理模型(如 o1 和 o3)可能會超過這個限制。
圖片 支援 Base 64 編碼的圖片與圖片網址。 尺寸限制依模型而異。

技能參數

房產 類型 Required Notes
uri 字串 Yes 完整的模型呼叫 URL,包括操作路徑及任何必要的查詢參數。 支援的資源網域包括 openai.azure.com、 services.ai.azure.com、 cognitiveservices.azure.com及 models.ai.azure.com。 API 管理預設及自訂閘道網域亦支援。 僅僅一個閘道基底 URL 並不構成完整的操作 URL。 有關協定、驗證及私有連線資格,請參閱使用 API 管理搭配 Foundry IQ 模型呼叫。 關於啟用權限的 SharePoint 索引器,請參閱〈SharePoint 權限限制〉。
apiKey 字串 Cond.* 模型的秘密金鑰。 使用受管理身份時請留空。
authIdentity 物件 Cond.* SearchIndexerDataIdentity選取附加使用者指派的受管理身份的物件,而非用戶端 ID 字串。 在 中使用 及 @odata.type: "#Microsoft.Azure.Search.DataUserAssignedIdentity" 身份的資源 ID userAssignedIdentity。 省略此屬性,並 apiKey 使用系統指派的身份。 請參閱 受控識別。
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、 。

若要進行金鑰驗證,請設定 apiKey。 對於管理身份,省略 apiKey 並使用系統指派的身份或 authIdentity 上述物件。

commonModelParameters 預設值

參數 預設值
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 字串 (low | high | auto) No Fidelity hint for Azure OpenAI multimodal models.

技能產出

輸出名稱 類型 Description
response 字串 或 JSON 物件 模型輸出格式依 。responseFormat.type
usageInformation JSON 物件 代幣數量與模型參數的回聲。

範例定義

僅文字摘要

此完整技能範例摘要文件內容,並包含可選的指示,用於為產生的回應標註。 請以您支援的模型配置替換端點、部署與金鑰。 該 URL 的 Azure OpenAI API 版本與搜尋 API 版本是分開的。

{
  "@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. Begin the response with \"AI-generated content:\".'"
    },
    { "name": "userMessage", "source": "='Summarize the following text:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview",
  "apiKey": "<api-key>",
  "commonModelParameters": { "temperature": 0.3 }
}

參考資料: 技能組合 - 建立或更新。

可選擇為產生的文字標註

前述範例位於 Begin the response with "AI-generated content:".systemMessage。 您也可以將此指令放入 userMessage。 你可以自行選擇措辭、位置與語言,若不需要明顯揭露,則可省略說明。

示範教學遵循方式可能有所不同。 如果每個回應都必須有標籤,請在應用程式中以確定性的方式新增或驗證,而非僅依賴提示。 Foundry IQ 不會自動插入揭露文字。

這個可選的可見文字並非機器驗證來源、浮水印、內容憑證或 C2PA 實作。 它並不定義法律或合規要求。 同樣的提示方式也適用於支援的直接模型、API 管理以及與管理員連結的模型配置;它不會改變他們的模型、驗證、網路或受權限保護的豐富化限制。

文字 + 圖片說明

{
  "@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": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>"
  },
  "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 工作負載的代幣配額不受影響。
  • 為降低延遲,請將模型與您的 Foundry IQ 服務共置於同一 Azure 區域。
  • 搭配 responseFormat.json_schemaGPT-4o 進行可靠的結構化擷取,並更容易映射到索引欄位。
  • 監控代幣使用情況,若索引器達到每分鐘代幣數(TPM)上限,請提交 配額增加請求 。

錯誤與警告

狀況 結果
缺失或無效 uri Error
未指定認證方法 Error
兩者皆apiKeyauthIdentity有供應 Error
多模態提示詞的不支援模型 Error
輸入超過模型代幣限制 Error
模型會回傳無效的 JSON 對 json_schema 警告:原始字串已返回於 response

SharePoint 權限的限制

當您的索引器匯入 SharePoint ACL 時,此技能支援以下領域的第一方 Azure、OpenAI 與 Microsoft Foundry 端點:openai.azure.com、 cognitiveservices.azure.comservices.ai.azure.commodels.ai.azure.com及 。

無論驗證或網路設定如何,此配置均不支援 APIM、自訂網域及第三方路由。 使用支援的端點,或省略可選的模型豐富功能,同時保留 ACL 匯入。

此技能不支援敏感度標籤匯入,包括將敏感度標籤與 ACL 結合時。

管理身份驗證的安全考量

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

所uri參考的端點預期是你自己的 Azure OpenAI 或 Foundry 資源。 有關支援的端點網域,請參閱 技能參數。

同時也支援 Azure API 管理 (APIM) 端點(*.azure-api.net)以及用於這些資源前方的自訂網域。 由於自訂網域或 APIM 主機名稱無法僅憑名稱驗證,Foundry IQ 會在設定時進行即時連線檢查,而非透過網域匹配來驗證這些端點。 你負責配置並維護端點與其背後的 Azure OpenAI 或 Foundry 資源之間的關係。

關於啟用權限的 SharePoint 索引器,請參閱〈SharePoint 權限限制〉。

Note

為 Foundry Tools 受眾發行的管理身份憑證,對該身份授權的 Foundry Tools 或 Azure OpenAI 資源有效。 將它傳送到不受信任的端點可能會暴露該憑證。

為維持部署安全,請遵循以下做法:

  • 只設定 uri 你擁有且信任的端點。 偏好前面提到的 Foundry Tools 網域。 如果你使用 APIM 或自訂網域端點,請確認它在啟用受管理身份前端是你自己的資源。 看起來可信的主機名稱並不代表擁有權。
  • 將最小權限原則應用於 Foundry IQ 服務所使用的管理身份:
    • 在 Azure OpenAI 中,只指定認知服務為 OpenAI 使用者。
    • 在 Foundry 中,只指派 Foundry 使用者。 避免授予較廣泛的職務。
  • 使用 網路安全邊界(NSP) 與私有端點或 VNet 整合,限制 Foundry IQ 服務可存取的端點,以及目標資源接受哪些來源的請求。
  • 如果你使用 APIM 或自訂網域端點,請確保閘道驗證入站請求,並只轉發到預期的後端。 你也應該定期檢視其存取政策。
  • 偏好管理身份而非 apiKey。 如果你使用 apiKey,請安全儲存並旋轉它,不要嵌入到原始碼控制中。 服務會拒絕同時設定 apiKey 和 authIdentity的配置。
  • 定期檢視技能組定義、受管理身份角色指派,以及 APIM 與自訂領域設定,以確認值、存取控制與身份權限是否 uri 保持最新且適當。 透過您已建立的變更管理與安全審查流程來審查組態變更。
  • 監控 Azure OpenAI、Foundry Tools 及 Foundry 的登入日誌、認證事件,以及存取日誌中是否有意外或未經授權的活動。
  • 移除不再需要的技能、端點、角色指派和 API 金鑰。

限制技能組設定的存取

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

另請參閱