ai_embed_text プラグイン (プレビュー)
適用対象: ✅Azure データ エクスプローラー
ai_embed_text プラグインを使用すると、言語モデルを使用してテキストを埋め込み、取得拡張生成 (RAG) アプリケーションやセマンティック検索など、さまざまな AI 関連のシナリオを実現できます。 このプラグインは、マネージド ID を使用してアクセスされる Azure OpenAI Service 埋め込みモデルをサポートしています。
前提条件
- 管理 ID で構成された Azure OpenAI サービス
- マネージド ID とコールアウト ポリシー Azure OpenAI サービスとの通信を許可するように構成されている
構文
evaluateai_embed_text (text, connectionString [, options [, IncludeErrorMessages]])
構文規則について詳しく知る。
パラメーター
| 件名 | タイプ | Required | 説明 |
|---|---|---|---|
| text | string |
✔️ | 埋め込むテキスト。 値には、列参照または定数スカラーを指定できます。 |
| connectionString | string |
✔️ | <ModelDeploymentUri>;<AuthenticationMethod>形式の言語モデルの接続文字列。<ModelDeploymentUri>と<AuthenticationMethod>をそれぞれ AI モデルのデプロイ URI と認証方法に置き換えます。 |
| options | dynamic |
埋め込みモデル エンドポイントの呼び出しを制御するオプション。 オプションに関するページを参照してください。 | |
| IncludeErrorMessages | bool |
出力テーブルの新しい列にエラーを出力するかどうかを示します。 既定値: false。 |
[オプション]
次の表では、埋め込みモデル エンドポイントに対する要求の実行方法を制御するオプションについて説明します。
| 名前 | 種類 | 説明 |
|---|---|---|
RecordsPerRequest |
int |
要求ごとに処理するレコードの数を指定します。 既定値: 1。 |
CharsPerRequest |
int |
要求ごとに処理する最大文字数を指定します。 既定値: 0 (無制限)。 Azure OpenAI ではトークンがカウントされ、各トークンは約 4 文字に変換されます。 |
RetriesOnThrottling |
int |
調整が発生したときの再試行回数を指定します。 既定値: 0。 |
GlobalTimeout |
timespan |
埋め込みモデルからの応答を待機する最大時間を指定します。 既定値:null |
ModelParameters |
dynamic |
埋め込みモデルに固有のパラメーター (監視用の埋め込みディメンションやユーザー識別子など)。 既定値: null。 |
ReturnSuccessfulOnly |
bool |
正常に処理された項目のみを返すかどうかを示します。 既定値: false。 IncludeErrorMessages パラメーターが true に設定されている場合、このオプションは常に false に設定されます。 |
マネージド ID とコールアウト ポリシーを構成する
ai_embed_text プラグインを使用するには、次のポリシーを構成する必要があります。
これらのポリシーを構成するには、次の手順のコマンドを使用します。
マネージド ID を構成します。
.alter-merge cluster policy managed_identity ``` [ { "ObjectId": "system", "AllowedUsages": "AzureAI" } ] ```吹き出しポリシーを構成します。
.alter-merge cluster policy callout ``` [ { "CalloutType": "azure_openai", "CalloutUriRegex": "https://[A-Za-z0-9\\-]{3,63}\\.openai\\.azure\\.com/.*", "CanCall": true } ] ```
返品
次の新しい埋め込み列を返します。
- 埋め込み値を含む _embedding サフィックスを持つ列
- エラーを返すように構成されている場合、 _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_embed_text(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_embed_text(TextData, connectionString, options , true)
ベスト プラクティス
Azure OpenAI 埋め込みモデルは、高い調整の影響を受けます。このプラグインを頻繁に呼び出す場合は、すぐに調整制限に達する可能性があります。
調整とコストを最小限に抑えながら ai_embed_text プラグインを効率的に使用するには、次のベスト プラクティスに従います。
- 要求サイズの制御: 要求あたりのレコード数 (
RecordsPerRequest) と文字数 (CharsPerRequest) を調整します。 - クエリのタイムアウトの制御:
GlobalTimeoutをクエリ timeout より小さい値に設定して それまでの呼び出しが成功した場合に進行状況が失われないようにします。 - レート制限をより適切に処理する: 調整時に再試行を設定します (
RetriesOnThrottling)。