次の方法で共有

ai_query 関数

  • [アーティクル]

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

重要

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

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

要件

  • この関数は、Azure Databricks SQL クラシックでは使用できません。
  • Foundation Model API のクエリは、既定で有効になっています。 カスタム モデルまたは外部モデルを提供するエンドポイントに対してクエリを実行するには、Databricks プレビュー UI で カスタム モデルと外部モデルの AI_Query を有効にします。
  • 現行 DLT ウェアハウス チャネルでは、ai_query()をサポートする最新の Databricks Runtime バージョンは使用されません。 テーブル プロパティの pipelines.channel を 'preview' として設定し、ai_query() を使用します。 サンプル クエリについては、例を参照してください。

Note

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

構文

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

ai_query(endpointName, request)

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

ai_query(endpointName, request)

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

ai_query(endpointName, request, returnType)

引数

  • endpointName: STRING リテラル、Databricks Foundation Model サービス エンドポイントの名前、エンドポイントを提供する外部モデル、または同じワークスペース内のカスタム モデル エンドポイントの呼び出しに使用されるもの。 定義者には、エンドポイントに対するクエリ可能アクセス許可が必要です。
  • request: 式。エンドポイントの呼び出しに使用される要求。
    • エンドポイントが、外部モデル提供エンドポイントまたは Databricks Foundation Model API エンドポイントの場合、要求は STRING である必要があります。
    • エンドポイントがカスタム モデル提供エンドポイントである場合、要求には単一の列または構造体式を指定できます。 構造体フィールド名は、エンドポイントで予期される入力機能名と一致する必要があります。
  • returnType: 式。エンドポイントからの予期される returnType。 これは、from_json 関数 のスキーマ パラメーターに似ています。このパラメーターは、文字列式または schema_of_json の呼び出しの両方を受け入れます。
    • Databricks Runtime 14.2 以降では、この式が提供されない場合、ai_query() はカスタム モデル サービス エンドポイントのモデル スキーマから戻り値の型を自動的に推論します。
    • Databricks Runtime 14.1 以下では、この式は、カスタム モデル サービス エンドポイントのクエリするために必要です。

返品

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

例

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

> 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-llama-2-70b-chat',
    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

> 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