Azure OpenAI Embedding skill

Azure OpenAI Embedding 技能可連接部署於 Azure OpenAI in Foundry Models 資源或 Microsoft Foundry專案中的嵌入模型，用於索引時產生嵌入。 你的資料會在模型部署的 地理環境中 被處理。

Azure入口網站中的 Import data 利用 Azure OpenAI 嵌入技能來向量化內容。 你可以執行巫師並檢視生成的技能組，看看巫師是如何建立嵌入模型的技能。

先決條件

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

  • 你的 Azure OpenAI 資源必須有 custom 子網域，例如 https://<resource-name>.openai.azure.com。 你可以在Azure入口的 Keys and Endpoint 頁面找到這個端點，並用它來執行這個技能中的 resourceUri 屬性。

  • 你的 Foundry 專案的 父資源 提供多個端點存取權限，包括 https://<resource-name>.openai.azure.com、 https://<resource-name>.services.ai.azure.com和 https://<resource-name>.cognitiveservices.azure.com。 你可以在Azure入口網站的 Keys 和 Endpoint 頁面找到這些端點，並在此技能中使用 resourceUri 屬性。

• 部署到你的資源或專案中的 Azure OpenAI 嵌入模型。 支援模型請參見 技能參數 章節。

@odata.type

Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

資料限制

文字輸入的最大大小應為 8,000 個標記。 若輸入超過最大允許值，模型會拋出無效請求錯誤。 欲了解更多資訊，請參閱 Azure OpenAI 文件中的 tokens 關鍵概念。 如果你需要資料分塊，可以考慮使用 文字分割技能 。

技能參數

參數依大小寫區分。

支援的維度由 modelName

Azure OpenAI 嵌入技能所支援的尺寸取決於所設定的 modelName。

技能輸入

技能產出

範例定義

考慮一個記錄包含以下欄位：

{
    "content": "Microsoft released Windows 10."
}

那麼你的技能定義可能會是這樣：

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://my-demo-openai-eastus.openai.azure.com/",
  "deploymentId": "my-text-embedding-ada-002-model",
  "modelName": "text-embedding-ada-002",
  "dimensions": 1536,
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

範例輸出

對於給定的輸入文本，會產生一個向量化的嵌入輸出。

{
  "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... 
        0.021276434883475304,
      ]
}

輸出存在於記憶體中。 要將這個輸出傳送到搜尋索引中的欄位，你必須定義一個 outputFieldMapping ，將向量化嵌入的輸出（即陣列）映射到 向量場。 假設技能輸出位於文件的 嵌入 節點， content_vector 是搜尋索引中的欄位，索引器中的 outputFieldMapping 應該如下所示：

  "outputFieldMappings": [
    {
      "sourceFieldName": "/document/embedding/*",
      "targetFieldName": "content_vector"
    }
  ]

最佳做法

以下是你在運用這項技能時需要考慮的一些最佳實務：

• 如果你已經達到Azure OpenAI TPM（每分鐘代幣數）上限，請考慮quota limits advisory，以便你能相應處理。 請參考 Azure OpenAI monitoring 文件，了解你Azure OpenAI 實例效能的更多資訊。

• 你用來執行這項技能的 OpenAI 嵌入模型部署Azure，理想上應該與其他使用情境（包括 query vectorizer）的部署分開。 這有助於每次部署都針對其特定使用情境量身打造，進而優化效能，並輕鬆辨識來自索引器及索引嵌入呼叫的流量。

• 你的 Azure OpenAI 實例應該位於同一個區域，或至少地理上接近你 AI 搜尋服務所托管的區域。 這降低了延遲並提升了服務間的資料傳輸速度。

• 為避免頻繁遇到 429 錯誤代碼，建議透過 API 管理實作負載平衡，在多個 Azure OpenAI 嵌入模型部署前設置閘道器。

• 如果你的 OpenAI TPM（每分鐘代幣數）限制大於預設quotas and limits文件中公布的，請向Azure AI 搜尋服務團隊開啟support案件，以便調整。 這有助於避免因預設 TPM 限制而被記錄的 TPM 限制不必要地拖慢，前提是你的 TPM 限制較高。

• 關於使用此技能的範例與工作程式碼範例，請參考以下連結：

  • 整合向量化（Python）
  • 整合向量化（C#）
  • 整合向量化（Java）

錯誤與警告

管理身份驗證的安全考量

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

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

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

Azure API 管理 （APIM） 端點*.azure-api.net（）亦被支援。 由於 APIM 主機名稱無法僅靠名稱驗證，Azure AI 搜尋服務 在設定時透過即時連線檢查來驗證這些端點，而非透過網域匹配。 你負責配置並維護 APIM 端點與其背後 Azure OpenAI 或 Foundry Tools 資源之間的關係。

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

建議的安全性做法

為維持部署安全，請遵循以下做法：

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

限制技能組設定的存取

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

另請參閱

• 內建技能
• 如何定義技能組合
• 如何定義輸出場映射