ai_query 関数

適用対象: Databricks SQL Databricks Runtime

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

ai_query は、リアルタイム推論またはバッチ推論ワークロードについて既存のエンドポイントにクエリを実行できる汎用 AI 関数 です。

• サポートされているモデルと必要なエンドポイント構成については、「サポートされているモデル」を参照してください。
• ai_queryを使用して、ML モデルサービス エンドポイントにデプロイされた AI エージェントに対してクエリを実行することもできます。「Azure Databricks にデプロイされたエージェントのクエリ」を参照してください。
• 運用ワークフローで ai_query を使用するには、「 バッチ推論パイプラインのデプロイ」を参照してください。

要件

• この関数は、Pro または Classic SQL ウェアハウスでは使用できません。
• Databricks Runtime 18.2 以降が必要です。
• ノートブックと Databricks ワークフローには、サーバーレス コンピューティングが必要です。
• ワークスペースは、サポートされている Model Serving リージョンにある必要があります。
• モデルが読み込まれた既存のモデル サービス エンドポイント。 Databricks でホストされる基盤モデルを使用している場合は、エンドポイントが自動的に作成されます。 それ以外の場合は、「 エンドポイントを提供するカスタム モデルを作成する 」または「 エンドポイントを提供する基盤モデルを作成する」を参照してください。
• カスタム モデル エンドポイントと外部モデル エンドポイントのクエリは、サポートされているリージョンで既定で有効になっています。 カスタム エンドポイントまたは外部エンドポイントに対するアクセス許可エラーが ai_query() 返された場合、ワークスペース管理者が プレビューの管理で無効にしている可能性があります。

Syntax

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

ai_query(endpoint, request)

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

ai_query(endpoint, request)

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

ai_query(endpoint, request, returnType, failOnError)

引数と戻り値

例: 基礎モデルのクエリを実行する

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

> 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-3-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-3-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;

マルチモーダル入力

ai_query では、マルチモーダル イメージ入力がネイティブにサポートされます。 サポートされている Databricks でホストされるビジョン モデルについては、Foundation モデルの 種類 を参照してください。

サポートされている入力の種類を次に示します。

• JPEG
• PNG

次の例は、Databricks Foundation Model API でサポートされている基盤モデルに対してマルチモーダル入力のクエリを実行する方法を示しています。 この例では、files => content パラメーターを使用して画像ファイルデータをai_queryに渡します。

• files: マルチモーダル入力のモデルで予期されるパラメーター名
• content: READ_FILESによって返される DataFrame 内の列。イメージ ファイルのバイナリ コンテンツが含まれます。

> SELECT *, ai_query(
  'databricks-llama-4-maverick',
 'what is this image about?', files => content)
as output FROM READ_FILES("/Volumes/main/multimodal/unstructured/image.jpeg");

Databricks Foundation Model API でサポートされている基本モデルに対してマルチモーダル入力のクエリを実行し、構造化された出力を指定するには:

> SELECT *, ai_query(
  'databricks-llama-4-maverick', 'What is interesting or important about this image?',
    responseFormat => ‘{
      "type": "json_schema",
        "json_schema": {
          "name": "output",
          "schema": {
            "type": "object",
            "properties": {
              "summary": {"type": "string"},
              "num_people": {"type": "integer"},
              "num_animals": {"type": "integer"},
              "interesting_fact": {"type": "string"},
              "possible_context": {"type": "string"}
            }
        },
        "strict": true
      }
    }’,
    files => content
  )
  as output FROM READ_FILES("/Volumes/main/user/volume1/image.jpeg");

次の例では、ai_query形式のread_filesでbinaryFileを使用して、クラウド ストレージからイメージ ファイルに対して推論を実行します。 WHERE句は、_metadata フィールドをフィルター処理して、サイズと名前で特定のファイルを対象とします。

SELECT
  path AS file_path,
  ai_query(
    'databricks-llama-4-maverick',
    'Describe this image in ten words or less: ',
    files => content
  ) AS result
FROM read_files(
  's3://my-s3-bucket/path/to/images/',
  format => 'binaryFile',
  fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size < 1000000
  AND _metadata.file_name LIKE '%robots%';

例: 従来の ML モデルのクエリを実行する

カスタム モデルまたは従来の ML モデルサービス エンドポイントに対してクエリを実行するには:

> 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

高度なシナリオの例

次のセクションでは、エラー処理やユーザー定義関数に ai_query を組み込む方法などの高度なユース ケースの例を示します。

メッセージ配列を渡す

次の例は、 ai_queryを使用して、メッセージ配列をモデルまたはエージェント アプリケーションに渡す方法を示しています。

> SELECT ai_query(
    'custom-llama-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."]}

プロンプトと推論列を連結する

||、CONCAT()、format_string()の使用など、プロンプトと推論列を連結する方法は複数あります。

SELECT
CONCAT('${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};

Alternatively:

SELECT
'${prompt}' || ${input_column_name} AS concatenated_prompt
FROM ${input_table_name};

または、 format_string()を使用します。

SELECT
format_string('%s%s', '${prompt}', ${input_column_name}) AS concatenated_prompt
FROM ${input_table_name};

モデル パラメーターを渡してモデルを構成する

最大トークンや温度などの特定のパラメーターを渡して、モデルの動作をカスタマイズします。 例えば次が挙げられます。

SELECT text, ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "Please summarize the following article: " || text,
    modelParameters => named_struct('max_tokens', 100, 'temperature', 0.7)
) AS summary
FROM uc_catalog.schema.table;

を使用してエラーを処理する failOnError

エラーを処理するには、failOnErrorに ai_query 引数を使用します。 次の例は、1 つの行にエラーがある場合に、クエリ全体の実行を停止しないようにする方法を示しています。 この引数の設定方法に基づく予期される動作については、「 引数と戻り 値」を参照してください。

SELECT text, ai_query(
    "databricks-meta-llama-3-3-70b-instruct",
    "Summarize the given text comprehensively, covering key points and main ideas concisely while retaining relevant details and examples. Ensure clarity and accuracy without unnecessary repetition or omissions: " || text,
failOnError => false
) AS summary
FROM uc_catalog.schema.table;

構造化された出力を使用して出力スキーマを適用する

responseFormatを使用してダウンストリーム処理を容易にするために、出力が特定のスキーマに準拠していることを確認します。 Azure Databricks の 構造化出力を参照してください。

次の例では、DDL スタイルの JSON 文字列スキーマを適用します。

SELECT ai_query(
    "databricks-gpt-oss-20b",
    "Extract research paper details from the following abstract: " || abstract,
    responseFormat => 'STRUCT<research_paper_extraction:STRUCT<title:STRING, authors:ARRAY<STRING>, abstract:STRING, keywords:ARRAY<STRING>>>'
)
FROM research_papers;

または、JSON スキーマ応答形式を使用します。

SELECT ai_query(
    "databricks-gpt-oss-20b",
    "Extract research paper details from the following abstract: " || abstract,
    responseFormat => '{
      "type": "json_schema",
      "json_schema": {
        "name": "research_paper_extraction",
        "schema": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "authors": {"type": "array", "items": {"type": "string"}},
            "abstract": {"type": "string"},
            "keywords": {"type": "array", "items": {"type": "string"}}
          }
      },
      "strict": true
    }
  }'
)
FROM research_papers;

予想される出力は次のようになります。

{ "title": "Understanding AI Functions in Databricks", "authors": ["Alice Smith", "Bob Jones"], "abstract": "This paper explains how AI functions can be integrated into data workflows.", "keywords": ["Databricks", "AI", "LLM"] }

ユーザー定義関数で ai_query を使用する

の呼び出しを UDF でラップできるため、さまざまなワークフローで関数を簡単に使用して共有できます。

CREATE FUNCTION correct_grammar(text STRING)
  RETURNS STRING
  RETURN ai_query(
    'databricks-meta-llama-3-3-70b-instruct',
    CONCAT('Correct this to standard English:\n', text));

GRANT EXECUTE ON correct_grammar TO ds;

SELECT
    * EXCEPT text,
    correct_grammar(text) AS text
  FROM articles;