Open Responses API를 사용하여 모델 쿼리

이 문서에서는 Open Responses API 를 사용하여 기본 모델을 쿼리하는 방법을 설명하고 수행할 때 고려할 공급자별 동작에 대해 설명합니다.

Open Responses API는 응답 스타일 요청 형식의 개방형 다중 공급자 구현입니다. input 대신 messages 필드를 사용하고 구조화된 output 배열을 반환합니다. 요청 본문의 /serving-endpoints/open-responses 필드에 모델 서빙 엔드포인트 이름을 넣고 model 경로로 요청을 보내세요.

쿼리 예제

다음 예제에서는 Open Responses API를 사용하여 기본 모델 엔드포인트를 쿼리합니다.

curl \
  -u token:$DATABRICKS_TOKEN \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "model": "databricks-claude-sonnet-4-5",
    "input": [
      {
        "role": "user",
        "content": "What is a mixture of experts model?"
      }
    ],
    "max_output_tokens": 256
  }' \
  https://<workspace_host>.databricks.com/serving-endpoints/open-responses

응답은 response 배열이 있는 output 개체입니다. 스트리밍 요청(stream: true)의 경우, 응답은 각 이벤트가 응답 청크인 text/event-stream입니다.

공급자별 동작

Databricks는 Open Responses 요청을 각 공급자의 네이티브 형식으로 변환합니다. 동작은 대부분의 요청에 대해 일관되지만 다음과 같은 공급자별 차이점이 적용됩니다.

모든 공급자

• 대화는 상태를 유지하지 않습니다. previous_response_id 서버 쪽 대화 스토리지는 지원되지 않습니다. 각 턴에 input 필드에서 전체 대화를 보냅니다.
• 일부 OpenAI 관련 필드는 허용되지만 비 OpenAI 공급자에서는 무시됩니다. 와 usersafety_identifiermetadata 같은 truncation필드는 이식성을 위해 응답에서 반환되지만 공급자 동작은 변경하지 않습니다.

Databricks에서 호스팅하는(오픈 소스) 모델

• 기능 지원은 모델별로 지원됩니다. 모델별로 함수 호출, 추론, 구조적 출력 및 이미지 입력이 사용됩니다. 모델에서 지원하지 않는 기능을 사용하는 요청은 오류를 반환합니다. 예를 들어 추론을 지원하는 모델은 이미지 입력을 지원하지 않을 수 있습니다.
• 이미지 입력은 URL 또는 데이터 URI여야 합니다. image_url를 통해 이미지를 https URL 또는 data: URI로 제공합니다. 파일 참조(file_id) 및 문서 입력(input_file)은 지원되지 않습니다.

인류식 클로드 모델

• 온도는 0~2 척도를 사용합니다. Claude는 기본적으로 0–1 범위를 사용하므로 Databricks는 값을 절반으로 스케일 조정합니다. 즉, temperature: 1.0는 0.5처럼 동작합니다.
• 추론은 여러 턴에 걸쳐 왕복합니다. 모델이 다중 턴 대화에서 이전 사고 과정을 추론할 수 있도록 하려면, 반환된 reasoning 항목을 encrypted_content는 변경하지 않은 채 다음 요청의 input로 다시 보내세요. 쿼리 추론 모델을 참조하세요.
• 이미지 및 문서 입력은 base64 데이터 URI여야 합니다. base64 image_url URI로 이미지를 data: 제공하고 base64 file_data URI로 문서를 data: 제공합니다. https URL 및 file_id 참조는 지원되지 않습니다.
• 구조적 출력에는 제약 조건이 있습니다. text.format 형식 json_schema 은 지원되지만 json_object 그렇지 않으며 오류를 반환합니다. 구조적 출력은 스트리밍 또는 추론과 결합할 수 없으며 사용할 때 특정 도구에 고정 tool_choice 할 수 없습니다. Azure Databricks에서 구조적 출력 을(를) 참조하세요.
• 추론 토큰은 별도로 보고되는 대신 usage.output_tokens에 포함됩니다.

Google Gemini 모델

• 온도는 0~2 척도를 사용합니다. Gemini는 고유한 0~1 범위를 사용하므로 Databricks는 값을 절반으로 줄여 다시 스케일링합니다. 즉, temperature: 1.0는 0.5처럼 동작합니다.
• 추론은 여러 턴에 걸쳐 왕복합니다. 모델이 다중 턴 대화에서 이전 사고 과정을 추론할 수 있도록 하려면, 반환된 reasoning 항목을 encrypted_content는 변경하지 않은 채 다음 요청의 input로 다시 보내세요. 쿼리 추론 모델을 참조하세요.
• 이미지 입력은 URL과 base64 데이터 URI를 모두 https 허용합니다.
• 추론 토큰은 usage.output_tokens_details.reasoning_tokens에 보고됩니다.

다음 예제에서는 도구 결과를 반환할 때 function_call 항목(encrypted_content과 함께)을 유지합니다.

{
  "model": "databricks-gemini-2-5-pro",
  "input": [
    { "role": "user", "content": "What's the weather in San Francisco?" },
    {
      "type": "function_call",
      "call_id": "call_abc123",
      "name": "get_weather",
      "arguments": "{\"city\": \"San Francisco\"}",
      "encrypted_content": "<opaque-provider-signature>"
    },
    {
      "type": "function_call_output",
      "call_id": "call_abc123",
      "output": "{\"temp_f\": 64}"
    }
  ]
}

Tools

Open Responses API는 여러 공급자에서 function 유형 도구를 지원합니다. 자세한 내용 및 지원되는 모델은 Azure Databricks 함수 호출을 참조하세요. 웹 검색 기본 제공 도구는 Azure Databricks 웹 검색을 참조하세요.

다른 기본 제공 및 사용자 지정 도구 형식(예custom: , apply_patchimage_generation및mcp)은 OpenAI 응답 API를 통해서만 사용할 수 있습니다.

지원되는 모델

Open Responses API는 Anthropic Claude, Google Gemini 및 Databricks 호스팅 오픈 모델을 비롯한 Databricks 기본 모델에서 사용할 수 있으며 지원은 앞으로 새로운 모델로 확장됩니다. 현재 사용 가능한 모델 목록은 Foundation 모델 형식을 참조하세요.

함수 호출, 추론, 구조적 출력 및 이미지 입력과 같은 기능 지원은 기본 모델에 따라 달라집니다. 공급자별 동작을 참조하세요.

지원되는 입력 유형

입력 지원은 모델 및 공급자에 따라 달라집니다. 텍스트 입력은 모든 모델에서 지원됩니다. 이미지 입력의 경우 공급자별 동작의 공급자 별 노트와 Query Vision 모델의 형식 및 크기 요구 사항을 참조하세요. 모델별 입력 형식은 Foundation Model API에서 사용할 수 있는 Databricks 호스팅 기본 모델을 참조하세요.

추가 리소스

• OpenAI 응답 API를 사용하여 쿼리
• 채팅 모델 쿼리
• Azure Databricks 함수 호출
• Azure Databricks 웹 검색
• Azure Databricks 구조화된 출력
• Databricks 기반 모델 API