배포된 Mosaic AI 에이전트를 쿼리하기

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

에이전트를 배포하는 방법을 알아보려면 생성 AI 애플리케이션에 대한 에이전트 배포를 참조하세요.

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

메서드	주요 이점
Databricks OpenAI 클라이언트 (권장)	네이티브 통합, 전체 기능 지원, 스트리밍 기능
MLflow 배포 클라이언트	기존 MLflow 패턴, 설정된 ML 파이프라인
REST API	OpenAI 호환 언어에 구애받지 않고 기존 도구에서 작동합니다.
AI 함수: `ai_query`	OpenAI 호환, 기존 도구와 작동

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

Databricks OpenAI 클라이언트(권장)

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 호출은 다음과 같습니다.

에서 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를 전달하려면, 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 인터페이스를 사용하여 만든 에이전트에 이 기능을 사용합니다. 이 인터페이스는 여전히 지원되지만 새 에이전트에는 권장되지 않습니다. 이는 다음과 같습니다.

에서 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를 전달하려면, 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`

SQL을 사용하여 배포된 AI 에이전트를 쿼리하는 데 사용할 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 2025-11-13

다음을 통해 공유

배포된 Mosaic AI 에이전트를 쿼리하기

Databricks OpenAI 클라이언트(권장)

ResponsesAgent 엔드포인트

ChatAgent 또는 ChatModel 종단점

MLflow 배포 클라이언트

ResponsesAgent 엔드포인트

ChatAgent 또는 ChatModel 종단점

REST API

ResponsesAgent 엔드포인트

ChatAgent 또는 ChatModel 종단점

AI 함수: ai_query

다음 단계

피드백

추가 리소스

AI 함수: `ai_query`