Azure OpenAI 向量化工具

註

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

Azure OpenAI 向量化器連接部署於您的 Azure OpenAI in Foundry Models 資源或 Microsoft Foundry專案中的嵌入模型,以便在查詢時產生嵌入。 你的資料會在模型部署的 地理環境中 被處理。

雖然向量化工具是在查詢時使用,但您會在索引定義中加以指定,並透過向量設定檔在向量欄位上參考它們。 欲了解更多資訊,請參閱 「在搜尋索引中配置向量器」。

Azure OpenAI 向量器在 REST API 中稱為 AzureOpenAIVectorizer。 請使用最新穩定版的 Indexes - Create (REST API) 或提供此功能的 Azure SDK 套件。

註

此向量化工具綁定於 Azure OpenAI,並按照Azure OpenAI Standard 的價格收費。

先決條件

  • Foundry 模型中的 Azure OpenAI 資源或 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 嵌入模型。 關於支援的模型,請見下一節。

向量器參數

參數依大小寫區分。

參數名稱 描述
resourceUri (必填)模型資源基礎 URI。 支援的資源網域為:

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

也支援 Azure API 管理 HTTPS 閘道基礎 URI,包括預設 azure-api.net 主機和已設定的自訂網域。 請分開設定 deploymentId;不要提供完整的 embeddings 作業 URL。 有關路由、驗證、RBAC 與私人連線需求,請參閱〈將 API Management 與 Foundry IQ (Azure AI 搜尋服務) 模型呼叫搭配使用〉。

apiKey 用來存取模型的秘密金鑰。 只設定一種驗證方式;使用金鑰時,請留 authIdentity 空。
deploymentId (必修)已部署的 Azure OpenAI 嵌入模型的識別碼。 這是你部署模型時指定的部署名稱。
authIdentity 用於連線的 使用者指派管理識別碼 。 省略 apiKey 和 authIdentity,即可使用 Foundry IQ 服務的系統指派身分。 若要直接呼叫或代幣直通,請將 Cognitive Services OpenAI User 指派至承載模型的 Azure OpenAI 或父 Foundry 資源。 關於身份選擇及獨立閘道/後端指派,請參閱 角色範圍與身份識別碼。
modelName (必填)部署於指定 deploymentId 的 Azure OpenAI 模型名稱。 支援的值有:

  • text-embedding-ada-002
  • text-embedding-3-large
  • text-embedding-3-small

支援的向量查詢類型

Azure OpenAI 向量器只支援 text 向量查詢。

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

期望場維度

使用 Azure OpenAI 向量化工具設定的欄位,其預期欄位維度取決於設定的modelName。

modelName 最小尺寸 最大尺寸
文本嵌入-ada-002 1536 1536
text-embedding-3-large 1 3072
text-embedding-3-small 1 1536

範例定義

以下索引定義片段會設定直接的 Azure OpenAI 連線。 在發送請求前,請先替換 <api-key> 為您的憑證。

{
  "vectorizers": [
    {
        "name": "my-openai-vectorizer",
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
            "resourceUri": "https://my-fake-azure-openai-resource.openai.azure.com",
            "apiKey": "<api-key>",
            "deploymentId": "my-ada-002-deployment",
            "authIdentity": null,
            "modelName": "text-embedding-ada-002"
        }
    }
  ]
}

API 管理自訂網域範例

此索引定義片段會配置一個具有 API 管理自訂閘道網域及 Foundry IQ 服務系統指派身份的向量器。 請將主機名稱與部署名稱替換為您的值。 若要改用預設閘道網域,請將 resourceUri 設為 https://<apim-name>.azure-api.net。

{
  "vectorizers": [
    {
      "name": "apim-embedding",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://apim.contoso.com",
        "deploymentId": "my-text-embedding-3-small",
        "modelName": "text-embedding-3-small"
      }
    }
  ]
}

參考資料:Indexes - Create。

在與索引時所用嵌入模型相符的 向量設定檔 中選取此向量化器。 若要改為選取附加的使用者指派 Search 身分識別,請在 azureOpenAIParameters 內新增以下物件:

{
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>"
  }
}

對於金鑰驗證,提供 apiKey 並省略 authIdentity;Search 會在 api-key 標頭中傳送金鑰。 為 原生嵌入路由與驗證設定閘道。

效能最佳做法

以下是使用此向量器時需要考慮的一些最佳實務:

  • 如果你已經達到 Azure OpenAI TPM(每分鐘代幣數)的上限,可以考慮參考配額限制建議,以便能夠相應處理。 請參考 Azure OpenAI monitoring 文件,了解你Azure OpenAI 實例效能的更多資訊。

  • 理想情況下,你用於這個向量器的 Azure OpenAI 嵌入模型部署應該與用於其他使用案例(包括 嵌入技能)的部署分開。 這有助於每次部署都針對其特定使用情境量身打造,進而優化效能,並輕鬆辨識來自索引器及索引嵌入呼叫的流量。

  • 您的 Azure OpenAI 實例應該位於與 Foundry IQ 服務所託管的區域相同,或至少在地理上接近該區域。 這降低了延遲並提升了服務間的資料傳輸速度。

  • 為避免頻繁出現 429 錯誤代碼,建議透過 API Management 實作負載平衡,並在多個 Azure OpenAI 嵌入模型部署前實作負載平衡閘道器。

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

管理身份驗證的安全考量

當 Azure OpenAI 向量器使用管理身份時,Foundry IQ 會將 Cognitive Services 受眾()https://cognitiveservices.azure.com的 Microsoft Entra 存取權杖及查詢文字傳送到已設定的resourceUri端點。 當您選擇搭配 authIdentity 的使用者指派身分,或同時省略 authIdentity 和 apiKey 以使用系統指派的身分時,此流程適用。

只設定您信任且可控且預期同時接收權杖與文字的端點。 僅僅有一個主機名稱並不能證明所有權或信任。 不要依賴連線檢查來判斷 API 管理閘道是否為你擁有的資源提供前端代理。

設定接收端點以驗證令牌的簽章及標準聲明,包括發行者、受眾、租戶、有效期限及所需權限。 對 Foundry IQ 服務的受控識別套用最小權限。 關於閘道設定及獨立的 API Management 到後端的身分識別,請參閱〈在 Foundry IQ 模型呼叫中使用 API 管理〉。

註

為 Foundry Tools 受眾簽發的管理身分識別權杖,可用於該身分識別已獲授權的任何 Foundry Tools 或 Azure OpenAI 資源。 將它傳送到不受信任的端點可能會暴露該權杖。

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

  • 只設定 resourceUri 你擁有且信任的端點。 在 向量化器參數中使用資源網域。 如果您使用 APIM 端點,請在啟用受管理身份之前確認其路由。 看起來可信的主機名稱並不代表擁有權。
  • 對每個連線套用最小權限。 對於直接呼叫 Azure OpenAI 或有意的權杖直通,請將所選搜尋身分授予 Azure OpenAI 或承載部署的父 Foundry 資源上的 OpenAI 使用者。 當 APIM 終止搜尋驗證並使用自身身份時,請在 APIM 授權搜尋,並將該後端角色授予模型寄存資源上的 APIM 身份,而非搜尋。 避免使用較廣泛的角色。
  • 評估特定工作負載的 網路安全邊界(NSP) 及私人連線性。 僅在接收端進行私有端點或 VNet 整合,並不會從查詢執行主機配置路由。
  • 如果你使用 APIM 端點,請確保閘道驗證入站請求,並只轉發到預期的後端。 你也應該定期檢視其存取政策。
  • 偏好使用受控識別,而非 apiKey。 如果你使用 apiKey,請安全地儲存並定期輪替它,且不要將它嵌入原始碼控制中。 只設定一種驗證方式。
  • 定期檢視索引定義、管理身份角色指派及 APIM 設定,以確保 resourceUri 值、存取控制及身份權限保持最新且適當。 透過您已建立的變更管理與安全審查流程來審查組態變更。
  • 監控 Azure OpenAI 與 Foundry 工具的登入日誌、認證事件,以及存取日誌,查看是否有意外或未經授權的活動。
  • 移除不再需要的未使用向量化工具、端點、角色指派及 API 金鑰。

限制對索引與向量化器配置的存取

能建立或修改索引定義的使用者,同時控制目的地端點(resourceUri)及向量器所使用的認證設定。 由於向量器會將認知服務受眾的受管理身份權杖傳送至該端點,請將這些權限限制給受信任的管理員,並在配置啟用受管理身份的向量工具時,遵循您的標準變更管理與安全性審查流程。

不要以為管理設定properties.dataExfiltrationProtections: ["BlockAll"]會讓所有 Azure OpenAI 向量器都被停用。 限制索引編輯權限並檢視目的地、閘道原則及角色指派。 關於索引中相同的目的地信任相關責任,請參閱 自訂 Web API 技能安全性考量。

參見