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

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 のワークスペースを有効にする方法をご覧ください。
• クエリーを実行するためのワークスペース権限: ワークスペースアクセスまたはコンシューマーアクセス。エンタイトルメントの管理を参照してください。

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

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

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を参照してください。

制限

• ai_query Unity Gateway のサポートは、Databricks が提供するモデルでのみ利用可能です。system.ai モデルサービス名（例: system.ai.claude-sonnet-4-5 または system.ai.gpt-5-6-sol）を渡します。Unity Gateway で作成したモデルサービスは、まだサポートされていません。
• ai_query バッチ推論ワークロードには、使用量追跡 のみが適用されます。レート制限、サービスポリシーで実装されたガードレール、推論テーブル、フォールバックなど、Unity Gatewayのその他の機能は適用されません。

ネイティブAPIでモデルサービスにクエリーする

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

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

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

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

次のステップ

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