查詢部署於 Azure Databricks 的代理程式

學習如何向部署於 Databricks Apps 或 Model Serving 端點的代理發送請求。 Databricks 提供多種查詢方法，以符合不同的使用案例和整合需求。

選取最適合您使用案例的查詢方法：

方法	主要優點
Databricks OpenAI 客戶端（推薦）	原生整合、全功能支援、串流功能
REST API	與 OpenAI 兼容，與語言無關，可與現有工具配合使用
人工智慧功能： `ai_query`	兼容 OpenAI 的查詢舊有代理，僅託管於 Model Serving 端點

Databricks 建議針對新應用程式使用 Databricks OpenAI 用戶端 。與預期 OpenAI 相容端點的平台整合時，請選擇 REST API 。

Databricks OpenAI 客戶端（推薦）

Databricks 建議你使用 DatabricksOpenAI 用戶端來查詢已部署的代理程式。根據您已部署的代理程式的 API，您將使用回應客戶端或聊天完成客戶端。

部署到應用程式的代理程式

請參考以下範例，針對託管在 Databricks 應用程式上的代理，遵循 ResponsesAgent 介面，這是建置代理的推薦方法。你必須使用 Databricks OAuth 代幣來查詢託管在 Databricks Apps 上的代理程式。

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參數來加入。

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)

若要從回應中取得追蹤 ID，請包含x-mlflow-return-trace-id 標頭並使用 extra_headers。然後用 MLflow get_trace 取得完整的追蹤。

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

模特服務代理人

請參考以下範例，針對在 Model Serving 上託管的舊有代理，依照介面說明 ResponsesAgent 。你可以使用 Databricks OAuth 令牌或個人存取令牌（Personal Access Token，PAT）來查詢 Model Serving 上託管的代理程式。

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 參數來添加它們：

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 介面進行模型提供服務的傳統代理。

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 參數來添加它們：

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 相容 API 的第三方平台整合
從 OpenAI 遷移到 Databricks，只需最少的代碼更改

用 REST API 使用 Databricks OAuth 憑證來認證。請參閱 Databricks 認證文件以獲得更多選項與資訊。

部署到應用程式的代理程式

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，可以將它們加入請求正文：

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 取得完整記錄。

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" }]
  }'

模特服務代理人

請參考以下範例，針對在 Model Serving 上託管的舊有代理，依照介面說明 ResponsesAgent 。你可以使用 Databricks OAuth 令牌或個人存取令牌（Personal Access Token，PAT）來查詢 Model Serving 上託管的代理程式。 REST API 呼叫等同於：

使用 Databricks OpenAI 用戶端搭配 responses.create。
將 POST 請求傳送至特定端點的 URL （例如： 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，可以將它們加入請求文：

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 介面所建立的代理。這相當於：

使用 Databricks OpenAI 用戶端搭配 chat.completions.create。
將 POST 請求傳送至特定端點的 URL （例如： 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，可以將它們加入請求文：

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 功能： `ai_query`

你可以用 ai_query SQL 查詢部署在模型服務上的代理程式。如需 SQL 語法及參數定義，請參閱 ai_query 函數。

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

下一步

監控生產環境中的生成式人工智慧應用程式

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-09-11

查詢部署於 Azure Databricks 的代理程式

Databricks OpenAI 客戶端（推薦）

部署到應用程式的代理程式

模特服務代理人

REST API

部署到應用程式的代理程式

模特服務代理人

AI 功能： ai_query

下一步

意見反應

其他資源

AI 功能： `ai_query`