Azure Databricks에 배포된 에이전트 쿼리

Databricks 앱 또는 모델 서비스 엔드포인트에 배포된 에이전트에 요청을 보내는 방법을 알아봅니다. Databricks는 다양한 사용 사례 및 통합 요구 사항에 맞게 여러 쿼리 메서드를 제공합니다.

사용 사례에 가장 적합한 쿼리 방법을 선택합니다.

메서드	주요 이점
Databricks OpenAI 클라이언트(권장)	네이티브 통합, 전체 기능 지원, 스트리밍 기능
REST API	OpenAI 호환 언어에 구애받지 않고 기존 도구에서 작동합니다.
AI 함수: `ai_query`	모델 서비스 엔드포인트에서만 호스트되는 OpenAI 호환 쿼리 레거시 에이전트

Databricks는 새 애플리케이션에 Databricks OpenAI 클라이언트 를 권장합니다. OpenAI 호환 엔드포인트가 예상되는 플랫폼과 통합할 때 REST API 를 선택합니다.

Databricks OpenAI 클라이언트(권장)

Databricks는 DatabricksOpenAI 클라이언트를 사용하여 배포된 에이전트를 쿼리하는 것이 좋습니다. 배포된 에이전트의 API에 따라 응답 또는 채팅 완료 클라이언트를 사용합니다.

앱에 배포된 에이전트

에이전트를 빌드하는 데 권장되는 접근 방식인 인터페이스에 따라 ResponsesAgent되는 에이전트에 다음 예제를 사용합니다. Databricks OAuth 토큰을 사용하여 Databricks 앱에서 호스트되는 에이전트를 쿼리해야 합니다.

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)

모델 서빙 에이전트

ResponsesAgent 인터페이스를 따르는 Model Serving에서 호스트되는 레거시 에이전트에 대해 다음 예제를 사용합니다. Databricks OAuth 토큰 또는 PAT(개인용 액세스 토큰)를 사용하여 모델 서비스에서 호스트되는 에이전트를 쿼리할 수 있습니다.

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로 마이그레이션

Databricks OAuth 토큰을 사용하여 REST API로 인증합니다. 자세한 옵션 및 정보는 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 }
  }'

모델 서빙 에이전트

인터페이스를 따라 Model Serving에서 호스트되는 레거시 에이전트에 대해 다음 예제를 ResponsesAgent 사용합니다. Databricks OAuth 토큰 또는 PAT(개인용 액세스 토큰)를 사용하여 모델 서비스에서 호스트되는 에이전트를 쿼리할 수 있습니다. REST API 호출은 다음과 같습니다.

에서 Databricks OpenAI 클라이언트 responses.create사용
특정 엔드포인트의 URL(예: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations)에 POST 요청을 보냅니다. 자세한 내용은 엔드포인트의 모델 서비스 페이지 및 모델 서비스 설명서를 참조하세요.

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사용
특정 엔드포인트의 URL(예: https://<host.databricks.com>/serving-endpoints/\<model-name\>/invocations)에 POST 요청을 보냅니다. 자세한 내용은 엔드포인트의 모델 서비스 페이지 및 모델 서비스 설명서를 참조하세요.

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`

SQL을 사용하여 제공하는 모델에서 호스트되는 배포된 에이전트를 쿼리하는 데 사용할 ai_query 수 있습니다. 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 2026-02-14

다음을 통해 공유

Azure Databricks에 배포된 에이전트 쿼리

Databricks OpenAI 클라이언트(권장)

앱에 배포된 에이전트

모델 서빙 에이전트

REST API

앱에 배포된 에이전트

모델 서빙 에이전트

AI 함수: ai_query

다음 단계

피드백

추가 리소스

AI 함수: `ai_query`