共用方式為

Azure OpenAI 內嵌技能

  • 發行項

重要

此功能在補充使用規定下處於公開預覽狀態。 2023-10-01-preview REST API 支援此功能的第一個反覆運算。 2024-05-01-preview REST API 會新增更多屬性，並支援 Azure OpenAI 上的更多文字內嵌模型。

Azure OpenAI 內嵌技能連線到 Azure OpenAI 資源上已部署的內嵌模型，以在技能執行期間產生內嵌。 您的數據會在部署模型的地理位置中處理。

Azure 入口網站中的匯入和向量化資料精靈會使用 Azure OpenAI 內嵌技能將內容向量化。 您可以執行精靈並檢閱產生的技能，以查看精靈如何建置 text-embedding-ada-002 模型的技能。

注意

此技能會繫結至 Azure OpenAI，並以現有的 Azure OpenAI 隨用隨付價格計費。

@odata.type

Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

資料限制

文字輸入的大小上限應為 8,000 個權杖。 如果輸入超過允許的最大值，則模型會擲回無效的要求錯誤。 如需詳細資訊，請參閱 Azure OpenAI 文件中的權杖金鑰概念。 如果您需要資料區塊處理，請考慮使用文字分割技能。

技能參數

這些參數會區分大小寫。

輸入 描述
resourceUri 模型提供者的 URI，例如 Azure OpenAI 資源或 OpenAI URL。
apiKey 用於存取模型的祕密金鑰。 如果您提供金鑰，請將 authIdentity 保留空白。 如果您同時設定 apiKey 和 authIdentity，則會在連線上使用 apiKey。
deploymentId 已部署的 Azure OpenAI 內嵌模型名稱。 此模型應該是內嵌模型，例如 text-embedding-ada-002。 如需支援的模型，請參閱 OpenAI 模型清單。
authIdentity 搜尋服務用來連線到 Azure OpenAI 的使用者受控識別。 您可以使用系統或使用者受控的識別。 若要使用系統管理的身分識別，請將 apiKey 和 authIdentity 保留空白。 自動使用系統管理的身分識別。 受控識別必須具有認知服務 OpenAI 使用者權限，才能將文字傳送至 Azure OpenAI。
modelName 如果您的技能是使用 2024-05-01-preview REST API 建立，則需要此屬性。 將此屬性設定為 Azure OpenAI 內嵌模型部署在透過 resourceUri 指定的提供者上、並透過 deploymentId 識別的部署名稱。 目前支援的值為 text-embedding-ada-002、text-embedding-3-large 和 text-embedding-3-small。
dimensions (選擇性，於 2024-05-01-preview REST API 中引進)。 您要產生的內嵌維度 (如果模型支援減少內嵌維度)。 支援的範圍如下所列。 如果未指定，則預設為每個模型的最大維度。 針對使用 2023-10-01-preview 建立的技能，維度會固定在 1536。

modelName 支援的維度

Azure OpenAI 內嵌技能的支援維度取決於所設定的 modelName。

modelName 最小維度 最大維度
text-embedding-ada-002 1536 1536
text-embedding-3-large 1 3072
text-embedding-3-small 1 1536

技能輸入

輸入 描述
text 要向量化的輸入文字。 如果您使用資料區塊處理，來源可能是 /document/pages/*。

技能輸出

輸出 描述
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"
    }
  ]
}

範例輸出

針對指定的輸入文字，會產生向量化內嵌輸出。

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

輸出位於記憶體中。 若要將此輸出傳送至搜尋索引中的欄位，您必須定義 outputFieldMapping，將向量化內嵌輸出 (這是陣列) 對應至向量欄位。 假設技能輸出位於文件的內嵌節點，且 content_vector 是搜尋索引中的欄位，索引子中的 outputFieldMapping 看起來應該會像這樣：

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

最佳作法

以下是使用此技能時所需考量的一些最佳做法：

  • 如果您達到 Azure OpenAI TPM (每分鐘權杖數) 限制，請考慮配額限制諮詢，以便據以處理。 如需 Azure OpenAI 執行個體效能的詳細資訊，請參閱 Azure OpenAI 監視文件。

  • 您用於此技能的 Azure OpenAI 內嵌模型部署應與用於其他使用案例的部署分開，包括查詢向量化工具。 這可協助每個部署針對其特定使用案例量身打造，進而使效能最佳化，並輕鬆地識別來自索引子和索引內嵌呼叫的流量。

  • 您的 Azure OpenAI 執行個體應該位於相同區域，或至少在地理上與 AI 搜尋服務裝載所在的區域相近。 這可減少延遲，並改善服務之間的資料傳輸速率。

  • 如果您的預設 Azure OpenAI TPM (每分鐘權杖數) 限制 (如配額與限制文件中所發佈) 大於預設，請向 Azure AI 搜尋服務小組開啟支援案例，因此可據以調整。 這可協助您的編製索引程序不會因記載的預設 TPM 限制而不必要地變慢 (如果您的限制較高)。

  • 如需使用此技能的範例和運作程式碼範例，請參閱下列連結：

錯誤和警告

Condition 結果
Null 或無效的 URI 錯誤
Null 或無效的 deploymentID 錯誤
文字是空的 警告
文字大於 8,000 個權杖 錯誤

另請參閱