次の方法で共有

デプロイされたモザイク AI エージェントのクエリを実行する

モデル サービス エンドポイントにデプロイされたエージェントに要求を送信する方法について説明します。 Databricks には、さまざまなユース ケースと統合のニーズに合わせて複数のクエリ メソッドが用意されています。

エージェントをデプロイする方法については、「 生成 AI アプリケーション用のエージェントをデプロイする」を参照してください。

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

方式 主な利点
Databricks OpenAI クライアント (推奨) ネイティブ統合、完全な機能サポート、ストリーミング機能
MLflow デプロイ クライアント 既存の MLflow パターン、確立された ML パイプライン
REST API OpenAI と互換性があり、言語に依存せず、既存のツールで動作します
AI 関数: ai_query OpenAI と互換性があり、既存のツールで動作します

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

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

ResponsesAgent エンドポイント

エージェントを構築する場合に推奨される方法である ResponsesAgent インターフェイスを使用して作成されたエージェントの例を次に示します。

from databricks.sdk import WorkspaceClient

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

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

## 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パラメーターを使用して追加できます。

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 エンドポイント

従来の ChatAgent または ChatModel インターフェイスを使用して作成されたエージェントについては、次の例を使用します。これは引き続きサポートされますが、新しいエージェントでは推奨されません。

from databricks.sdk import WorkspaceClient

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

w = WorkspaceClient()
client = w.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パラメーターを使用して追加できます。

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)

MLflow デプロイ クライアント

既存の MLflow ワークフローとパイプライン内で作業する場合は、MLflow デプロイ クライアントを使用します。 このアプローチは、MLflow の追跡と実験の管理と自然に統合されます。

次の例では、 MLflow デプロイ クライアントを使用してエージェントにクエリを実行する方法を示します。 新しいアプリケーションの場合、Databricks では、強化された機能とネイティブ統合のために Databricks OpenAI クライアントを使用することをお勧めします。

デプロイされたエージェントの API に応じて、ResponsesAgent または ChatAgent 形式を使用します。

ResponsesAgent エンドポイント

エージェントを構築する場合に推奨される方法である ResponsesAgent インターフェイスを使用して作成されたエージェントの例を次に示します。

from mlflow.deployments import get_deploy_client

client = get_deploy_client()
input_example = {
    "input": [{"role": "user", "content": "What does Databricks do?"}],
    ## Optional: Include any custom inputs
    ## "custom_inputs": {"id": 5},
    "databricks_options": {"return_trace": True},
}
endpoint = "<agent-endpoint-name>" # TODO: update this with your endpoint name

## Call predict for non-streaming responses
response = client.predict(endpoint=endpoint, inputs=input_example)

## Call predict_stream for streaming responses
streaming_response = client.predict_stream(endpoint=endpoint, inputs=input_example)

ChatAgent または ChatModel エンドポイント

これは、 従来の ChatAgent または ChatModel インターフェイスで作成されたエージェントに使用します。これは引き続きサポートされますが、新しいエージェントでは推奨されません。

from mlflow.deployments import get_deploy_client

client = get_deploy_client()
input_example = {
    "messages": [{"role": "user", "content": "What does Databricks do?"}],
    ## Optional: Include any custom inputs
    ## "custom_inputs": {"id": 5},
    "databricks_options": {"return_trace": True},
}
endpoint = "<agent-endpoint-name>" # TODO: update this with your endpoint name

## Call predict for non-streaming responses
response = client.predict(endpoint=endpoint, inputs=input_example)

## Call predict_stream for streaming responses
streaming_response = client.predict_stream(endpoint=endpoint, inputs=input_example)

client.predict() と client.predict_stream() は、エージェントの作成時に定義したエージェント関数を呼び出します。 ストリーミング 応答を参照してください。

REST API

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

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

  • HTTP 要求を使用する言語に依存しないアプリケーション
  • OpenAI と互換性のある API を必要とするサード パーティ製プラットフォームとの統合
  • コードの変更を最小限に抑えた OpenAI から Databricks への移行

Databricks OAuth トークンまたは個人用アクセス トークン (PAT) を使用して REST API で認証します。 以下の例では、Databricks OAuth トークンを使用します。その他のオプションと情報については、 Databricks 認証ドキュメント を参照してください。

ResponsesAgent エンドポイント

エージェントを構築する場合に推奨される方法である ResponsesAgent インターフェイスを使用して作成されたエージェントの例を次に示します。 REST API 呼び出しは、次に相当します。

  • responses.createで Databricks OpenAI クライアントを使用する。
  • 特定のエンドポイントの URL に POST 要求を送信する (例: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations)。 詳細については、エンドポイントのモデル サービス ページと モデル サービスのドキュメントを参照してください。
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を渡す場合は、extra_bodyパラメーターを使用して追加できます。

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,
    "extra_body": {
      "custom_inputs": { "id": 5 },
      "databricks_options": { "return_trace": true }
    }
  }'

ChatAgent または ChatModel エンドポイント

これは、 従来の ChatAgent または ChatModel インターフェイスで作成されたエージェントに使用します。これは引き続きサポートされますが、新しいエージェントでは推奨されません。 これは次の内容に相当します。

  • chat.completions.createで Databricks OpenAI クライアントを使用する。
  • 特定のエンドポイントの URL に POST 要求を送信する (例: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations)。 詳細については、エンドポイントのモデル サービス ページと モデル サービスのドキュメントを参照してください。
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を渡す場合は、extra_bodyパラメーターを使用して追加できます。

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,
    "extra_body": {
      "custom_inputs": { "id": 5 },
      "databricks_options": { "return_trace": true }
    }
  }'

AI 関数: ai_query

ai_queryを使用して、SQL を使用してデプロイされた AI エージェントにクエリを実行できます。 SQL 構文とパラメーター定義については、ai_query関数を参照してください。

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

次のステップ

GenAI の運用環境の監視

  • Last updated on