共用方式為

ai_embed_text外掛程式 （預覽）

  • 發行項

適用於： ✅Azure 數據總管

外掛程式 ai_embed_text 允許使用語言模型內嵌文字，並啟用各種 AI 相關案例，例如擷取擴增世代 （RAG） 應用程式和語意搜尋。 外掛程式支援使用受控識別存取的 Azure OpenAI 服務內嵌模型。

必要條件

語法

evaluateai_embed_text (text， connectionString [, options [, IncludeErrorMessages]])

深入瞭解 語法慣例。

參數

姓名 類型​​ 必要 描述
text string ✔️ 要內嵌的文字。 值可以是數據行參考或常數純量。
connectionString string ✔️ 格式<ModelDeploymentUri>;<AuthenticationMethod>的語言模型 連接字串;分別以 AI 模型部署 URI 和驗證方法取代 <ModelDeploymentUri> 和 <AuthenticationMethod> 。
options dynamic 控制呼叫內嵌模型端點的選項。 請參閱選項。
IncludeErrorMessages bool 指出是否要在輸出數據表的新數據行中輸出錯誤。 預設值: false。

選項。

下表描述控制對內嵌模型端點提出要求方式的選項。

名稱 類型​​ 描述
RecordsPerRequest int 指定要處理每個要求的記錄數目。 預設值: 1。
CharsPerRequest int 指定要處理每個要求的字元數目上限。 預設值： 0 （無限制）。 Azure OpenAI 會計算令牌，每個令牌大約會轉譯為四個字元。
RetriesOnThrottling int 指定發生節流時重試嘗試次數。 預設值: 0。
GlobalTimeout timespan 指定等候內嵌模型響應的時間上限。 預設值：null
ModelParameters dynamic 內嵌模型特有的參數，例如內嵌維度或使用者標識符，以供監視之用。 預設值: null。
ReturnSuccessfulOnly bool 指出是否只傳回已成功處理的專案。 預設值: false。 如果 IncludeErrorMessages 參數設定為true，這個選項一律會設定為 false。

設定受控識別和註標原則

若要使用 ai_embed_text 外掛程式，您必須設定下列原則：

  • 受控識別：允許系統指派的受控識別向 Azure OpenAI 服務進行驗證。
  • 註標：授權 AI 模型端點網域。

若要設定這些原則，請使用下列步驟中的命令：

  1. 設定受控識別：

    .alter-merge cluster policy managed_identity
```
[
  {
    "ObjectId": "system",
    "AllowedUsages": "AzureAI"
  }
]
```

  2. 設定註標原則：

    .alter-merge cluster policy callout
```
[
    {
        "CalloutType": "azure_openai",
        "CalloutUriRegex": "https://[A-Za-z0-9\\-]{3,63}\\.openai\\.azure\\.com/.*",
        "CanCall": true
    }
]
```

傳回

傳回下列新的內嵌資料列：

  • 包含 內嵌值之 _embedding後綴的數據行
  • 如果設定為傳回錯誤，則具有 _embedding_error 後綴的數據行，其中包含錯誤字串，如果作業成功，則為空白。

根據輸入類型，外掛程式會傳回不同的結果：

  • 數據行參考：傳回一或多個具有其他數據行的記錄前面會加上參考數據行名稱。 例如，如果輸入數據行名為 TextData，則輸出數據行會命名為 TextData_embedding，如果設定為傳回錯誤，TextData_embedding_error。
  • 常數純量：傳回具有未加上前置詞之其他數據行的單一記錄。 數據行名稱會 _embedding ，如果設定為傳回錯誤， _embedding_error。

範例

下列範例會使用 Azure OpenAI 內嵌模型內嵌文字 Embed this text using AI 。

let expression = 'Embed this text using AI';
let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
evaluate ai_embed_text(expression, connectionString)

下列範例會使用 Azure OpenAI 內嵌模型內嵌多個文字。

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;managed_identity=system';
let options = dynamic({
    "RecordsPerRequest": 10,
    "CharsPerRequest": 10000,
    "RetriesOnThrottling": 1,
    "GlobalTimeout": 2m
});
datatable(TextData: string)
[
    "First text to embed",
    "Second text to embed",
    "Third text to embed"
]
| evaluate ai_embed_text(TextData, connectionString, options , true)

最佳作法

Azure OpenAI 內嵌模型受限於繁重的節流，而且經常呼叫此外掛程式可能會快速達到節流限制。

若要有效率地使用 ai_embed_text 外掛程式，同時將節流和成本降至最低，請遵循下列最佳做法：

  • 控制要求大小：調整每個要求的記錄數 （RecordsPerRequest） 和字元數 （CharsPerRequest）。
  • 控制查詢逾時：設定GlobalTimeout為低於查詢逾時的值，以確保成功呼叫到該點時不會遺失進度。
  • 更正常地處理速率限制：設定節流RetriesOnThrottling （） 的重試。

相關內容