メインコンテンツまでスキップ
に最終更新

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

Databricks Apps または Model Serving Endpoint にデプロイされたエージェントに要求を送信する方法について説明します。Databricks では、さまざまなユースケースと統合ニーズに対応するための複数のクエリー方法を提供しています。

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

手法

主なメリット

Databricks OpenAIクライアント（推奨）

ネイティブ統合、全機能サポート、ストリーミング機能

REST API

OpenAIと互換性があり、言語に依存せず、既存のツールと連携します。

AI Functions: ai_query

OpenAI と互換性があり、Model Serving Endpoint でホストされているレガシーエージェントのみをクエリーします。

手法

主なメリット

Databricks OpenAIクライアント（推奨）

ネイティブ統合、全機能サポート、ストリーミング機能

REST API

OpenAIと互換性があり、言語に依存せず、既存のツールと連携します。

AI Functions: ai_query

OpenAI と互換性があり、Model Serving Endpoint でホストされているレガシーエージェントのみをクエリーします。

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

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

Databricks は、デプロイされたエージェントにクエリーするためにDatabricks OpenAI Clientを使用することをお勧めします。デプロイされたエージェントのAPIに応じて、レスポンスまたはチャット補完クライアントを使用します。

エージェント構築の推奨アプローチである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={
        &quot;custom_inputs&quot;: {&quot;id&quot;: 5},
    },
)
for chunk in streaming_response:
    print(chunk)

応答からトレースIDを取得するには、x-mlflow-return-trace-idヘッダーをextra_headersを使用して含めます。その後、MLflow get_trace を使用して完全なトレースを取得します。

Python
response = client.responses.create(
    model=f"apps/{app_name}",
    input=input_msgs,
    extra_headers={&quot;x-mlflow-return-trace-id&quot;: &quot;true&quot;},
)
trace_id = response.metadata["trace_id"]
trace = client.get_trace(trace_id)

REST API​

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

このアプローチは次の用途に最適です：

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

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

エージェント構築の推奨アプローチである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 }
  }'

応答からトレースIDを取得するには、リクエストにx-mlflow-return-trace-idヘッダーを含めてください。応答本文には、トレースIDが含まれるmetadata.trace_idフィールドが含まれています。ストリーミングリクエストの場合、トレースIDはストリームの終わりに個別のSSEイベント (data: {"trace_id": "tr-..."}) として送信されます。次に、MLflow get_traceを使用して、トレースIDで完全なトレースを取得します。

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

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 アプリを監視します。

このページの見出し