Azure OpenAI 嵌入技能

Note

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

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

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

Note

這項技能必須Azure OpenAI,收費標準為 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 關鍵概念。 如果你需要資料分塊,可以考慮使用 文字分割技能 。

技能參數

參數依大小寫區分。

輸入 Description
resourceUri (必填)模型資源基礎 URI。 支援的資源網域包括:

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

同時也支援 Azure API 管理 HTTPS 閘道基礎 URI,包括預設azure-api.net主機與已設定的自訂網域。 另行設定 deploymentId ;不提供完整的嵌入操作 URL。 有關路由、驗證、RBAC 及私有連線資格,請參閱〈在 Foundry IQ(Azure AI 搜尋服務)模型呼叫中使用 API 管理〉。

apiKey 用來存取模型的秘密金鑰。 如果你提供鑰匙,請保持 authIdentity 空。 如果你同時設定 apiKey 和 authIdentity, apiKey 則會用於連接。
deploymentId (必修)已部署的 Azure OpenAI 嵌入模型的識別碼。 這是你部署模型時指定的部署名稱。
authIdentity 用於連線的 使用者指派管理識別碼 。 兩者皆省apiKeyauthIdentity略,改為使用 Foundry IQ 服務的系統指派身份。 若要直接呼叫或代幣直通,請將 Cognitive Services OpenAI User 指派至承載模型的 Azure OpenAI 或父 Foundry 資源。 關於身份選擇及獨立閘道/後端指派,請參閱 角色範圍與身份識別碼。
modelName (必修)部署於指定 deploymentId 的 OpenAI 模型Azure名稱。 支援的值有:

  • text-embedding-ada-002
  • text-embedding-3-large
  • text-embedding-3-small
dimensions (可選)你想產生的嵌入維度,假設模型 支援多種維度。 預設尺寸是每個模型的最大尺寸。 對於在 2023-10-01 預覽版之前使用 REST API 版本建立的技能組,尺寸固定為 1536。 如果你在這個技能中設定了dimensions屬性,向dimensions量場定義上的屬性也設定為相同的值。

支援的維度由 modelName

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

關於 API 管理端點、驗證及私有網路需求,請參閱使用 API 管理搭配 Foundry IQ 模型呼叫。

modelName 最小尺寸 最大尺寸
文本嵌入-ada-002 1536 1536
文本嵌入-3-大型 1 3072
文本嵌入-3-小型 1 1536

技能輸入

輸入 Description
text 輸入文字要向量化。 如果你使用資料分塊,來源可能是 /document/pages/*。

技能產出

Output Description
embedding 輸入文字的向量化嵌入。

範例定義

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

{
    "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"
    }
  ]
}

API 管理自訂網域範例

此完整技能定義使用已設定的 API 管理自訂閘道網域及附加的使用者指派搜尋識別碼。 請將範例主機名稱、部署名稱及身份資源 ID 替換為您的值。 若要改用預設閘道網域,請將 設 resourceUri 為 https://<apim-name>.azure-api.net。

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "name": "apim-embedding",
  "context": "/document",
  "resourceUri": "https://apim.contoso.com",
  "deploymentId": "my-text-embedding-3-small",
  "modelName": "text-embedding-3-small",
  "dimensions": 1536,
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>"
  },
  "inputs": [{ "name": "text", "source": "/document/content" }],
  "outputs": [{ "name": "embedding" }]
}

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

省略 authIdentity , apiKey 以使用系統指派的搜尋識別碼。 對於金鑰驗證,請使用 supply apiKey 而非 authIdentity;搜尋會把它送到頁首。api-key 為 原生嵌入路由與驗證設定閘道。

範例輸出

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

{
  "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 實例應該位於與 Foundry IQ 服務所託管區域相同或至少地理上接近。 這降低了延遲並提升了服務間的資料傳輸速度。

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

  • 如果你的 Azure OpenAI TPM(每分鐘代幣數)限制超出配額與限制文件中公布的預設,請向 Foundry IQ 團隊開啟支援案件,以便調整。 這有助於避免因預設 TPM 限制而被記錄的 TPM 限制不必要地拖慢,前提是你的 TPM 限制較高。

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

錯誤與警告

狀況 Result
空或無效 URI 錯誤
空或無效的部署ID 錯誤
文字是空白的 警告
文字超過 8,000 個標記 錯誤

管理身份驗證的安全考量

當 Azure OpenAI 嵌入技能使用管理式身份驗證時,Foundry IQ 會為 Foundry 工具受眾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 主機名稱無法僅憑名稱驗證,Foundry IQ 會在設定時進行即時連線檢查,而非透過網域匹配來驗證這些端點。 你負責配置並維護 APIM 端點與其背後 Azure OpenAI 或 Foundry Tools 資源之間的關係。

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

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

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

限制技能組設定的存取

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

另請參閱