Databricks にデプロイされたエージェントをクエリする

Databricks Appsまたはモデルサービング エンドポイントにデプロイされたエージェントにリクエストを送信する方法を学びます。 Databricks は、さまざまなユースケースや統合ニーズに合わせて複数のクエリ メソッドを提供します。

ユースケースに最適なクエリ アプローチを選択します。

手法	主なメリット
Databricks OpenAI クライアント (推奨)	ネイティブ統合、フル機能サポート、ストリーミング機能
REST API	OpenAI互換、言語非依存、既存のツールと連携
AI Functions ： ai_query	OpenAI互換、モデルビング エンドポイントのみでホストされているレガシー エージェントのクエリ

Databricks では、新しいアプリケーションには Databricks OpenAI クライアント を推奨しています。OpenAI 互換のエンドポイントを期待するプラットフォームと統合する場合は、 REST API を選択します。

Databricks OpenAI クライアント (推奨)

Databricks では、デプロイされたエージェントをクエリするにはDatabricksOpenAI クライアントを使用することをお勧めします。デプロイされたエージェントの API に応じて、応答クライアントまたはチャット完了クライアントのいずれかを使用します。

Agents deployed to Apps

ResponsesAgentインターフェイスに従ってDatabricks Appsでホストされるエージェントの場合は、次の例を使用します。これは、エージェントを構築するための推奨されるアプローチです。 Databricks Appsでホストされているエージェントにクエリを実行するには、 Databricks OAuthを使用する必要があります。

Python

from databricks.sdk import WorkspaceClient
from databricks_openai import DatabricksOpenAI

input_msgs = [{"role": "user", "content": "What does Databricks do?"}]
app_name = "<agent-app-name>"  # TODO: update this with your app name

# The WorkspaceClient must be configured with OAuth authentication
# See: https://docs.databricks.com/aws/en/dev-tools/auth/oauth-u2m.html
w = WorkspaceClient()

client = DatabricksOpenAI(workspace_client=w)

# Run for non-streaming responses. Calls the "invoke" method
# Include the "apps/" prefix in the model name
response = client.responses.create(model=f"apps/{app_name}", input=input_msgs)
print(response)

# Include stream=True for streaming responses. Calls the "stream" method
# Include the "apps/" prefix in the model name
streaming_response = client.responses.create(
    model=f"apps/{app_name}", input=input_msgs, stream=True
)
for chunk in streaming_response:
    print(chunk)

custom_inputsを渡したい場合は、 extra_bodyパラメータを使用して追加できます。

Python

streaming_response = client.responses.create(
    model=f"apps/{app_name}",
    input=input_msgs,
    stream=True,
    extra_body={
        "custom_inputs": {"id": 5},
    },
)
for chunk in streaming_response:
    print(chunk)

Agents on Model Serving

ResponsesAgentインターフェースに従ってモデルサービングでホストされているレガシー エージェントには、次の例を使用します。 Databricks OAuth VPN または Personal ACCESS (PAT) のいずれかを使用して、モデルサービングでホストされているエージェントにクエリを実行できます。

Python

from databricks_openai import DatabricksOpenAI

input_msgs = [{"role": "user", "content": "What does Databricks do?"}]
endpoint = "<agent-endpoint-name>" # TODO: update this with your endpoint name

client = DatabricksOpenAI()

# Run for non-streaming responses. Invokes `predict`
response = client.responses.create(model=endpoint, input=input_msgs)
print(response)

# Include stream=True for streaming responses. Invokes `predict_stream`
streaming_response = client.responses.create(model=endpoint, input=input_msgs, stream=True)
for chunk in streaming_response:
  print(chunk)

custom_inputsまたはdatabricks_optionsを渡す場合は、 extra_bodyパラメータを使用して追加できます。

Python

streaming_response = client.responses.create(
    model=endpoint,
    input=input_msgs,
    stream=True,
    extra_body={
        "custom_inputs": {"id": 5},
        "databricks_options": {"return_trace": True},
    },
)
for chunk in streaming_response:
    print(chunk)

ChatAgent または ChatModel インターフェイスに続くモデルサービング上のレガシー エージェントには、次の例を使用します。

Python

from databricks.sdk import WorkspaceClient

messages = [{"role": "user", "content": "What does Databricks do?"}]
endpoint = "<agent-endpoint-name>" # TODO: update this with your endpoint name

ws_client = WorkspaceClient()
client = ws_client.serving_endpoints.get_open_ai_client()

# Run for non-streaming responses. Invokes `predict`
response = client.chat.completions.create(model=endpoint, messages=messages)
print(response)

# Include stream=True for streaming responses. Invokes `predict_stream`
streaming_response = client.chat.completions.create(model=endpoint, messages=messages, stream=True)
for chunk in streaming_response:
  print(chunk)

custom_inputsまたはdatabricks_optionsを渡す場合は、 extra_bodyパラメータを使用して追加できます。

Python

streaming_response = client.chat.completions.create(
    model=endpoint,
    messages=messages,
    stream=True,
    extra_body={
        "custom_inputs": {"id": 5},
        "databricks_options": {"return_trace": True},
    },
)
for chunk in streaming_response:
    print(chunk)

REST API

Databricks REST API は、OpenAI と互換性のあるモデルのエンドポイントを提供します。これにより、Databricks エージェントを使用して、OpenAI インターフェースを必要とするアプリケーションを提供できるようになります。

このアプローチは次のような場合に最適です。

• HTTPリクエストを使用する言語に依存しないアプリケーション
• OpenAI互換APIsを期待するサードパーティプラットフォームとの統合
• 最小限のコード変更でOpenAIからDatabricksに移行する

Databricks OAuth トークンを使用して REST API で認証します。詳細なオプションと情報については、 Databricks 認証ドキュメントを参照してください。

Agents deployed to Apps

ResponsesAgentインターフェイスに従ってDatabricks Appsでホストされるエージェントの場合は、次の例を使用します。これは、エージェントを構築するための推奨されるアプローチです。 Databricks Appsでホストされているエージェントにクエリを実行するには、 Databricks OAuthを使用する必要があります。

Bash

curl --request POST \
  --url <app-url>.databricksapps.com/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true
  }'

custom_inputsを渡したい場合は、リクエスト本体に追加できます。

Bash

curl --request POST \
  --url <app-url>.databricksapps.com/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true,
    "custom_inputs": { "id": 5 }
  }'

Agents on Model Serving

ResponsesAgentインターフェースに従ってモデルサービングでホストされているレガシー エージェントには、次の例を使用します。 Databricks OAuth VPN または Personal ACCESS (PAT) のいずれかを使用して、モデルサービングでホストされているエージェントにクエリを実行できます。 REST API 呼び出しは次のものと同等です:

• responses.createで Databricks OpenAI クライアントを使用します。
• 特定のエンドポイントの URL (例: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations ) に POST リクエストを送信します。詳細については、エンドポイントのモデルサービング ページおよびモデルサービング ドキュメントを参照してください。

Bash

curl --request POST \
  --url https://<host.databricks.com\>/serving-endpoints/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "model": "\<model-name\>",
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true
  }'

custom_inputsまたはdatabricks_optionsを渡す場合は、それらをリクエスト本文に追加できます。

Bash

curl --request POST \
  --url https://<host.databricks.com\>/serving-endpoints/responses \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "model": "\<model-name\>",
    "input": [{ "role": "user", "content": "hi" }],
    "stream": true,
    "custom_inputs": { "id": 5 },
    "databricks_options": { "return_trace": true }
  }'

従来の ChatAgent または ChatModel インターフェースで作成されたエージェントには以下を使用します。これは次と同等です:

• chat.completions.createで Databricks OpenAI クライアントを使用します。
• 特定のエンドポイントの URL (例: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations ) に POST リクエストを送信します。詳細については、エンドポイントのモデルサービング ページおよびモデルサービング ドキュメントを参照してください。

Bash

curl --request POST \
  --url https://<host.databricks.com\>/serving-endpoints/chat/completions \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "model": "\<model-name\>",
    "messages": [{ "role": "user", "content": "hi" }],
    "stream": true
  }'

custom_inputsまたはdatabricks_optionsを渡す場合は、それらをリクエスト本文に追加できます。

Bash

curl --request POST \
  --url https://<host.databricks.com\>/serving-endpoints/chat/completions \
  --header 'Authorization: Bearer <OAuth token>' \
  --header 'content-type: application/json' \
  --data '{
    "model": "\<model-name\>",
    "messages": [{ "role": "user", "content": "hi" }],
    "stream": true,
    "custom_inputs": { "id": 5 },
    "databricks_options": { "return_trace": true }
  }'

AI Functions ： ai_query

ai_queryを使用すると、 SQLを使用してモデルサービングでホストされているデプロイされたエージェントをクエリできます。 SQL構文と問題の定義については、 ai_query関数を参照してください。

SQL

SELECT ai_query(
  "<model name>", question
) FROM (VALUES ('what is MLflow?'), ('how does MLflow work?')) AS t(question);

次のステップ

本番運用で GenAI を監視する