基盤モデルとエンベディングモデルをクエリーする

Databricks では、基盤モデルをクエリーする方法をいくつか提供しています。プロバイダー非依存の API、プロバイダー固有の機能、またはバッチ推論のいずれが必要かに応じて、インターフェイスを選択します。

モデルにクエリーを実行する方法

アプローチ	使用する場合
統合API	OpenResponsesおよびOpenAI Chat Completionsと互換性のあるインターフェイスを使用します。Databricksは各リクエストをダウンストリームモデルのネイティブ形式に変換するため、クライアントコードを変更することなく、プロバイダー間でモデルを切り替えることができます。
プロバイダー・ネイティブAPI	プロバイダー固有の機能や、既存の OpenAI、Anthropic、Google の SDK コードを使用します。
ai_query	SQL または Python からバッチ推論を実行します。

アプローチ	使用する場合
統合API	OpenResponsesおよびOpenAI Chat Completionsと互換性のあるインターフェイスを使用します。Databricksは各リクエストをダウンストリームモデルのネイティブ形式に変換するため、クライアントコードを変更することなく、プロバイダー間でモデルを切り替えることができます。
プロバイダー・ネイティブAPI	プロバイダー固有の機能や、既存の OpenAI、Anthropic、Google の SDK コードを使用します。
ai_query	SQL または Python からバッチ推論を実行します。

クイックスタート

次の2つのステップでモデルサービスにクエリーを実行します：

ステップ1: モデルを選択

Databricksでは、claude-sonnet-4-5やgpt-5-6-solなどのモデルをすぐに使用できる状態で提供しています。Databricks提供のモデルは、system.aiの下でUnity Catalogに登録されます。

ステップ2: 統合されたOpenAI互換APIを使用してリクエストを送信する

OpenAI Python SDK で MLflow Chat Completions API を使用する:

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,  # your personal access token
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"  # your Databricks workspace instance
)

chat_completion = client.chat.completions.create(
  messages=[
    {"role": "user", "content": "What is Databricks?"},
  ],
  model="system.ai.claude-sonnet-4-5",
  max_tokens=256
)

print(chat_completion.choices[0].message.content)

要件

• Unity Gateway がサポートされているリージョン内の Databricks ワークスペース。
• ワークスペースでUnity Catalog有効化されていること。 Unity Catalog のワークスペースを有効にする方法をご覧ください。
• クエリーを実行するためのワークスペース資格： ワークスペースアクセス 、またはアカウントで Unity Gateway へのコンシューマーアクセス プレビューが有効になっている コンシューマーアクセス （パブリックプレビュー）。資格の管理および Databricks プレビューの管理を参照してください。

統合APIsでモデルサービスをクエリする

統合されたAPIsは、OpenAI互換のインターフェースを提供し、Databricks上のモデルをクエリします。統合されたAPIsを使用して、コードを変更することなく、異なるプロバイダーのモデル間をシームレスに切り替えることができます。

Unified Responses API

Unified Responses API

Unified Responses API (/mlflow/v1/responses) は、Databricks上でモデルをクエリするための、OpenResponses互換かつプロバイダー非依存のAPIです。Databricksでは、MLflow Chat Completions APIよりもこちらが推奨されます。コードを変更せずに、プロバイダーをまたいでユースケースに最適なモデルを選択します。

Python

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

response = client.responses.create(
  model="<model-service>",
  input=[{"role": "user", "content": "What is Databricks?"}]
)

print(response.output_text)

REST API

Bash

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "input": [
      {"role": "user", "content": "What is Databricks?"}
    ]
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/responses

<workspace-url> を Databricks ワークスペースの URL に置き換え、<model-service> をモデルサービスの完全修飾名に置き換えます。

MLflow Chat Completions API

MLflow Chat Completions API

Python

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

chat_completion = client.chat.completions.create(
  messages=[
    {"role": "user", "content": "Hello!"},
    {"role": "assistant", "content": "Hello! How can I assist you today?"},
    {"role": "user", "content": "What is Databricks?"},
  ],
  model="system.ai.gpt-5-6-sol",
  max_tokens=256
)

print(chat_completion.choices[0].message.content)

REST API

Bash

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "system.ai.gpt-5-6-sol",
    "max_tokens": 256,
    "messages": [
      {"role": "user", "content": "Hello!"},
      {"role": "assistant", "content": "Hello! How can I assist you today?"},
      {"role": "user", "content": "What is Databricks?"}
    ]
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/chat/completions

<workspace-url> を Databricks ワークスペースの URL に置き換えます。

MLflow Embeddings API

MLflow Embeddings API

Python

Python

from openai import OpenAI
import os

DATABRICKS_TOKEN = os.environ.get('DATABRICKS_TOKEN')

client = OpenAI(
  api_key=DATABRICKS_TOKEN,
  base_url="https://<workspace-url>/ai-gateway/mlflow/v1"
)

embeddings = client.embeddings.create(
  input="What is Databricks?",
  model="<model-service>"
)

print(embeddings.data[0].embedding)

REST API

Bash

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model-service>",
    "input": "What is Databricks?"
  }' \
  https://<workspace-url>/ai-gateway/mlflow/v1/embeddings

<workspace-url> を Databricks ワークスペースの URL に置き換え、<model-service> をモデルサービスの完全修飾名に置き換えます。

モデルサービスをクエリーする ai_query

ai_query関数を使用して、SQLまたはPythonから直接モデルサービスをクエリーできます。これにより、バッチ推論ワークロードの使用状況追跡情報を取得できます。

ai_query を使用してモデルサービスにクエリーを実行するには、モデルサービスに対して ai_query をランします：

SQL

SELECT ai_query(
  'system.ai.claude-sonnet-4-5',
  'Summarize the following text: ' || text_column
) AS summary
FROM my_table
LIMIT 10

使用状況追跡システムテーブル（system.ai_gateway.usage）は、ai_queryを通じてモデルサービスに対して行われたリクエストをキャプチャします。これらのリクエストは、組み込みの使用状況ダッシュボードにも表示されます。

詳細なai_query構文とパラメーターのリファレンスについては、ai_query関数を参照してください。ベストプラクティスとサポートされているモデルについては、Use ai_queryを参照してください。

Limitations

• ai_query Unity Gateway のサポートは、Databricks が提供するモデルでのみ利用可能です。system.ai モデルサービス名（例: system.ai.claude-sonnet-4-5 または system.ai.gpt-5-6-sol）を渡します。Unity Gateway で作成したモデルサービスは、まだサポートされていません。
• Only usage tracking applies to ai_query batch inference workloads.Other Unity Gateway features such as rate limits, guardrails implemented with service policies, inference tables, and fallbacks do not apply.

Query model services with native APIs

ネイティブ APIs は、Databricks でモデルをクエリーするためのプロバイダー固有のインターフェイスを提供します。ネイティブ APIs を使用して、最新のプロバイダー固有の機能にアクセスします。

各ネイティブAPIは、基盤となるモデルが対応するAPI形式を使用するモデルサービスでのみ機能します。

• OpenAI Responses API を使用して、OpenAI (GPT) モデルを利用したモデルサービスをクエリーします。
• Anthropic Messages APIを使用して、Claudeモデルを基盤とするモデルサービスをクエリします。
• Google Gemini APIを使用して、Geminiモデルを基盤とするモデルサービスをクエリします。

基盤となるモデルに関係なくモデルサービスをクエリするには、代わりに 統合API を使用してください。

次のステップ

• モデルサービスへのアクセスを検出し、管理します
• コーディングエージェントと統合する