ai_query
関数
適用対象: Databricks SQL
Databricks Runtime
重要
この機能はパブリック プレビュー段階にあります。
既存の Azure Databricks Model Serving エンドポイントを呼び出し、その応答を解析して返します。
さまざまなユース ケースで 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
である必要があります。 - エンドポイントがカスタム モデル提供エンドポイントである場合、要求には単一の列または構造体式を指定できます。 構造体フィールド名は、エンドポイントで予期される入力機能名と一致する必要があります。
- エンドポイントがエンドポイントまたは Databricks Foundation Model API エンドポイントを提供する外部モデルである場合、要求は
returnType
: 式。エンドポイントからの予期されるreturnType
。 これは、STRING
式または schema_of_json 関数の呼び出しのいずれかを受け入れる、from_json 関数のスキーマパラメーターに似ています。- Databricks Runtime 14.2 以降では、この式が提供されない場合、
ai_query()
はカスタム モデル サービス エンドポイントのモデル スキーマから戻り値の型を自動的に推論します。 - Databricks Runtime 14.1 以下では、この式は、カスタム モデル サービス エンドポイントのクエリするために必要です。
- Databricks Runtime 14.2 以降では、この式が提供されない場合、
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;