ai_embeddings プラグイン (プレビュー)

適用対象: ✅Microsoft Fabric✅Azure データ エクスプローラー

[前提条件]

• 使用されている ID に少なくとも (Cognitive Services OpenAI ユーザー) ロールが割り当てられた Azure OpenAI サービス。
• AI サービスへの呼び出しを許可するように構成された コールアウト ポリシー 。

構文

evaluate ai_embeddings ( text, connectionString [,options [,IncludeErrorMessages]])

構文規則の詳細について説明します。

パラメーター

オプション

次の表では、埋め込みモデル エンドポイントに対する要求の実行方法を制御するオプションについて説明します。

吹き出しポリシーの構成

azure_openai callout ポリシーにより、Azure AI サービスへの外部呼び出しが有効になります。

AI モデル エンドポイント ドメインを承認するようにコールアウト ポリシーを構成するには:

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

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

返品ポリシー

次の新しい埋め込み列を返します。

• 埋め込み値を含む _embeddings サフィックスを持つ列
• エラーを返すように構成されている場合、 _embedding_error サフィックスを持つ列。エラー文字列が含まれているか、操作が成功した場合は空のままです。

入力の種類に応じて、プラグインは異なる結果を返します。

• 列参照: 追加の列を含む 1 つ以上のレコードの前に参照列名が付いているレコードを返します。 たとえば、入力列の名前が TextData の場合、出力列の名前は TextData_embedding になり、エラーを返すように構成されている場合は TextData_embedding_error。
• 定数スカラー: プレフィックスのない追加の列を含む 1 つのレコードを返します。 列名は _embedding され、エラーを返すように構成されている場合は _embedding_error。

例示

次の例では、Azure OpenAI Embedding モデルを使用してテキスト 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_embeddings(expression, connectionString)

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;impersonate';
evaluate ai_embeddings(expression, connectionString)

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;impersonate';
evaluate ai_embeddings(expression, connectionString)

次の例では、Azure OpenAI Embedding モデルを使用して複数のテキストを埋め込みます。

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_embeddings(TextData, connectionString, options , true)

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;impersonate';
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_embeddings(TextData, connectionString, options , true)

let connectionString = 'https://myaccount.openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2024-06-01;impersonate';
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_embeddings(TextData, connectionString, options , true)

ベスト プラクティス

Azure OpenAI 埋め込みモデルは、高い調整の影響を受けます。このプラグインを頻繁に呼び出す場合は、すぐに調整制限に達する可能性があります。

調整とコストを最小限に抑えながら ai_embeddings プラグインを効率的に使用するには、次のベスト プラクティスに従います。

• 要求サイズの制御: 要求あたりのレコード数 (RecordsPerRequest) と文字数 (CharsPerRequest) を調整します。
• クエリのタイムアウトの制御: GlobalTimeout をクエリ timeout より小さい値に設定して それまでの呼び出しが成功した場合に進行状況が失われないようにします。
• レート制限をより適切に処理する: 調整時に再試行を設定します (RetriesOnThrottling)。

関連コンテンツ

• series_cosine_similarity()