`ai_query` 関数

[アーティクル]
02/04/2025

適用対象: 「はい」のチェックマーク Databricks SQL Databricks Runtime

重要

この機能はパブリックプレビュー段階にあります。

既存の Azure Databricks Model Serving エンドポイントを呼び出し、その応答を解析して返します。

さまざまなユースケースで ai_query を使用する方法については、次のガイドを参照してください。

ai_query を使用してバッチ LLM 推論を実行する
ai_query を使用して外部モデルを照会する
ai_query を使用して提供されたモデルのクエリを実行する

要件

この関数は、Azure Databricks SQL クラシックでは使用できません。
プロ SQL ウェアハウスでこの機能を使うには、Azure Private Link を有効にする必要があります。
Databricks Runtime 15.3 以降をお勧めします。 Databricks Runtime 15.2 以下を使用すると、パフォーマンス速度が低下する可能性があります。
現行DLT ウェアハウスチャネルでは、ai_query()をサポートする最新の Databricks Runtime バージョンは使用されません。テーブルプロパティの pipelines.channel を 'preview' として設定し、ai_query() を使用します。サンプルクエリについては、例を参照してください。
モデルが読み込まれた既存のモデルサービスエンドポイント。「カスタムモデル提供エンドポイントを作成する」を参照してください。
ワークスペースは、サポートされている Model Serving リージョンにある必要があります。
Foundation Model API のクエリは、既定で有効になっています。カスタムモデルまたは外部モデルを提供するエンドポイントに対してクエリを実行するには:
- Databricks Previews UI でカスタムモデルと外部モデル用の AI_Query を有効にします。
- 外部モデルに ai_queryを使用してクエリを実行するには、を参照してください。
- ai_queryを使用したバッチ LLM 推論の実行を参照してください

Note

Databricks Runtime 14.2 以降では、この機能は Databricks ワークフローのタスクとして実行されるノートブックなどの Databricks ノートブックでサポートされています。
Databricks Runtime 14.1 以下の場合、この関数は Databricks ノートブックではサポートされていません。

構文

外部モデルまたは基盤モデルを提供するエンドポイントに対してクエリを実行するには:

ai_query(endpoint, request)

カスタムモデル提供エンドポイントにモデルスキーマをクエリするには:

ai_query(endpoint, request)

カスタムモデル提供エンドポイントにモデルスキーマなしでクエリするには:

ai_query(endpoint, request, returnType, failOnError)

引数

endpoint: STRING リテラル。呼び出し用の同じワークスペース内の Databricks Foundation Model サービングエンドポイント、外部モデルサービングエンドポイント、またはカスタムモデルエンドポイントの名前。定義子には、エンドポイントに対する CAN QUERY アクセス許可が必要です。
request: 式。エンドポイントの呼び出しに使用される要求。
- エンドポイントがエンドポイントまたは Databricks Foundation Model API エンドポイントを提供する外部モデルである場合、要求は STRINGである必要があります。
- エンドポイントがカスタムモデル提供エンドポイントである場合、要求には単一の列または構造体式を指定できます。構造体フィールド名は、エンドポイントで予期される入力機能名と一致する必要があります。
returnType: 式。エンドポイントからの予期される returnType。これは、STRING 式または schema_of_json 関数の呼び出しのいずれかを受け入れる、from_json 関数のスキーマパラメーターに似ています。
- Databricks Runtime 14.2 以降では、この式が提供されない場合、ai_query() はカスタムモデルサービスエンドポイントのモデルスキーマから戻り値の型を自動的に推論します。
- Databricks Runtime 14.1 以下では、この式は、カスタムモデルサービスエンドポイントのクエリするために必要です。
failOnError: (省略可能) 既定値が true のブールリテラル。このフラグは、エラー状態を ai_query 応答に含めるかどうかを示します。
modelParameters (省略可能): 基礎モデルまたは外部モデルを提供するためのチャット、完了、埋め込みモデルパラメーターを含む構造体フィールド。これらのモデルパラメーターは、データ依存ではなく定数パラメーターである必要があります。これらのモデルパラメーターが指定されていない場合、または既定値が使用 null に設定されている場合。既定値が 0.0の temperature を除き、これらのモデルパラメーターの既定値は、Foundation モデル REST API リファレンスに記載されているものと同じです。
responseFormat (省略可能): モデルに従う応答形式を指定する JSON 文字列フィールド。次の 3 種類の応答形式がサポートされています。
- text
- json_object
- json_schema

返品

エンドポイントから解析された応答。

failOnError => true場合、関数は、エンドポイントからの解析された応答である既存の動作と同じ結果を返します。解析された応答のデータ型は、returnType関数のモデル型、モデルスキーマエンドポイント、または ai_query パラメーターから推論されます。
failOnError => false場合、関数は解析された応答とエラー状態文字列を STRUCT オブジェクトとして返します。
- 行の推論が成功した場合、errorStatus フィールドは null。
- モデルエンドポイントエラーが原因で行の推論に失敗した場合、response フィールドは null。
- 他のエラーが原因で行の推論に失敗した場合、クエリ全体が失敗します。
responseFormatで指定された JSON 文字列型に応じて、次の応答が返されます。
- responseFormat => '{“type”, “text”}'の場合、応答は “Here is the response”などの文字列です。
- responseFormat => '{“type”, “json_object”}'の場合、応答はキーと値のペアの JSON 文字列 ({“key”: “value”}など) です。
- responseFormat => '{“type”, “json_schema”...}'の場合、応答は JSON 文字列です。例を参照してください。
failOnError => false し、responseFormatを指定した場合、関数は解析された応答とエラー状態文字列を STRUCT オブジェクトとして返します。

の例

次の例では、json_schema 応答形式を指定します。


SELECT
  ai_query(
    "llama-3-1-70b",
    <request>,
    responseFormat =>'{
                        "type": "json_schema",
                        "json_schema":
                          {
                           "name": "research_paper_extraction",
                           "schema":
                             {
                              "type": "object",
                              "properties":
                               {
                                "title": { "type": "string" }
                               }
                             },
                            "strict": true
                          }
                      }'
  )

指定した json_schema 応答形式の出力例を次に示します。

{"title": "<the title of the paper>"}

failOnErrorとmodelParametersでmax_tokensとtemperatureを使用したバッチ推論の例を次に示します。この例では、 concat()を使用してモデルのプロンプトと推論列を連結する方法も示します。連結を実行するには、 ||、 concat()、 format_string()の使用など、複数の方法があります。


CREATE OR REPLACE TABLE ${output_table_name} AS (
  SELECT
      ${input_column_name},
      AI_QUERY(
        "${endpoint}",
        CONCAT("${prompt}", ${input_column_name}),
        failOnError => false,
        modelParameters => named_struct('max_tokens', ${num_output_tokens},'temperature', ${temperature})
      ) as response
    FROM ${input_table_name}
    LIMIT ${input_num_rows}
)

外部モデルを提供するエンドポイントに対してクエリを実行する場合:

> SELECT ai_query(
    'my-external-model-openai-chat',
    'Describe Databricks SQL in 30 words.'
  ) AS summary

  "Databricks SQL is a cloud-based platform for data analytics and machine learning, providing a unified workspace for collaborative data exploration, analysis, and visualization using SQL queries."

Databricks Foundation Model API でサポートされる基盤モデルに対してクエリを実行する場合:

> SELECT *,
  ai_query(
    'databricks-meta-llama-3-1-70b-instruct',
    "Can you tell me the name of the US state that serves the provided ZIP code? zip code: " || pickup_zip
    )
  FROM samples.nyctaxi.trips
  LIMIT 10

必要に応じて、次のように、関数呼び出しのために UDF で ai_query() の呼び出しをラップすることもできます。

> CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-1-70b-instruct',
    CONCAT('Correct this to standard English:\n', text));
> GRANT EXECUTE ON correct_grammar TO ds;
- DS fixes grammar issues in a batch.
> SELECT
    * EXCEPT text,
    correct_grammar(text) AS text
  FROM articles;

カスタムモデル提供エンドポイントにクエリを実行するには:


> SELECT text, ai_query(
    endpoint => 'spam-classification-endpoint',
    request => named_struct(
      'timestamp', timestamp,
      'sender', from_number,
      'text', text),
    returnType => 'BOOLEAN') AS is_spam
  FROM messages
  LIMIT 10

> SELECT ai_query(
    'weekly-forecast',
    request => struct(*),
    returnType => 'FLOAT') AS predicted_revenue
  FROM retail_revenue

> SELECT ai_query(
    'custom-llama-2-7b-chat',
    request => named_struct("messages",
        ARRAY(named_struct("role", "user", "content", "What is ML?"))),
    returnType => 'STRUCT<candidates:ARRAY<STRING>>')

  {"candidates":["ML stands for Machine Learning. It's a subfield of Artificial Intelligence that involves the use of algorithms and statistical models to enable machines to learn from data, make decisions, and improve their performance on a specific task over time."]}

DLT チャネルをプレビューに設定するためのクエリ例:

> create or replace materialized view
    ai_query_mv
    TBLPROPERTIES('pipelines.channel' = 'PREVIEW') AS
  SELECT
    ai_query("databricks-dbrx-instruct", text) as response
  FROM
    messages
  LIMIT 10;

次の方法で共有

`ai_query` 関数

要件

構文

引数

返品

の例

フィードバック

その他のリソース

次の方法で共有

ai_query 関数

要件

構文

引数

返品

の例

フィードバック

その他のリソース

`ai_query` 関数