Foundation 모델 REST API 레퍼런스
Foundation 모델 REST API 레퍼런스 (Foundation Model REST API)
Databricks Foundation Model APIs의 일반 API 정보와 지원 모델에 대해 다루는 레퍼런스 문서예요. Foundation Model APIs는 OpenAI의 REST API와 유사하게 설계돼서, 기존 프로젝트를 Databricks로 옮기기 쉽다는 점이 특징이에요. pay-per-token 엔드포인트와 provisioned throughput 엔드포인트가 동일한 REST API 요청 형식을 받아요.
기본 구조
pay-per-token 지원 모델마다 워크스페이스에 사전 구성된 엔드포인트가 있고, HTTP POST 요청으로 상호작용할 수 있어요. provisioned throughput 엔드포인트는 API나 Serving UI로 만들 수 있으며, 서빙하는 두 모델이 같은 API 형식을 노출한다면 엔드포인트 하나로 여러 모델을 서빙해 A/B 테스트를 할 수 있어요. 엔드포인트 설정 파라미터는 POST /api/2.0/serving-endpoints에서 확인할 수 있어요.
요청·응답은 JSON을 쓰고, 정확한 구조는 엔드포인트의 태스크 유형(chitchat, completion, embedding)에 따라 달라져요. 채팅·완료 엔드포인트는 스트리밍 응답을 지원해요.
usage 필드
응답에는 usage 하위 메시지가 포함되어 요청·응답의 토큰 수를 알려줘요. 이 형식은 모든 태스크 유형에서 동일해요.
| 필드 | 타입 | 설명 |
|---|---|---|
completion_tokens |
Integer | 생성된 토큰 수. 임베딩 응답에는 포함되지 않아요. |
prompt_tokens |
Integer | 입력 프롬프트의 토큰 수. |
total_tokens |
Integer | 총 토큰 수. |
reasoning_tokens |
Integer | 사고(thinking) 토큰 수. 추론 모델에만 적용돼요. |
cache_read_input_tokens |
Integer | 프롬프트 캐시에서 읽은 입력 토큰 수. 캐시가 활성인 Databricks 호스팅 Claude 엔드포인트에서 최상위 usage 필드로 반환돼요. |
cache_creation_input_tokens |
Integer | 프롬프트 캐시에 쓴 입력 토큰 수. 캐시가 활성인 경우 최상위 usage 필드로 반환돼요. |
databricks-meta-llama-3-3-70b-instruct 같은 모델은 사용자 프롬프트가 모델에 전달되기 전에 프롬프트 템플릿으로 변환돼요. pay-per-token 엔드포인트에서는 시스템 프롬프트가 추가될 수도 있고, prompt_tokens에 서버가 추가한 모든 텍스트가 포함돼요.
Responses API (OpenAI 모델)
Responses API는 모델과의 다중 턴 대화를 가능하게 하고, Chat Completions와 달리 messages 대신 input을 사용해요. Anthropic Claude·Google Gemini·Databricks 호스팅 오픈 모델에서는 별도 가이드를 참고해야 해요.
다음 파라미터는 Databricks에서 지원되지 않아 지정하면 400 에러를 반환해요.
background— 백그라운드 처리는 미지원store— 응답 저장은 미지원conversation— Conversation API 미지원
input 필드는 문자열 또는 role/content가 있는 입력 메시지 객체 목록을 받아요. role은 "user" 또는 "assistant", content는 문자열 또는 콘텐츠 블록 배열이에요. 콘텐츠 블록 타입은 type 필드로 결정되는데, 대표적으로 input_text, output_text, input_image, input_file, function_call, function_call_output, custom_tool_call, custom_tool_call_output이 있어요. 이미지는 image_url(URL 또는 base64 데이터 URI), 파일은 file_data(예: data:application/pdf;base64,<base64 data>)로 주면 돼요.
추론 설정
추론 모델(o-series, gpt-5 계열)에서는 reasoning 동작 설정으로 effort("low"·"medium"·"high", 기본 "medium")를 쓸 수 있어요. 구조화된 출력은 format의 type을 "text", "json_object", "json_schema" 중에 고르고, json_schema를 쓰면 그 구조를 정의하는 스키마 객체를 넘겨요.
커스텀 도구
Responses API에서 지원하는 도구 타입은 function, custom, mcp, image_generation, shell이에요. 커스텀 도구 명세는 OpenAI와 비슷하게 JSON 객체로 정의해요.
{
"type": "custom",
"name": "code_exec",
"description": "Executes arbitrary Python code. Return only valid Python code."
}
필요하면 format으로 출력 형식을 지정할 수 있어요. 기본은 {"type": "text"}이고, 구조화된 출력을 원하면 {"type": "grammar", "definition": "<grammar>", "syntax": "lark"}를 써요. 커스텀 도구와 문법 기반 출력 형식은 GPT-5 계열 모델에서만 지원돼요. 커스텀 도구가 호출되면 JSON arguments 대신 텍스트 input을 담은 custom_tool_call 출력 항목이 응답에 포함돼요.
태스크 유형
- Text completion: 단일 프롬프트에 대한 응답 생성. 채팅과 달리 배치 입력을 지원해서 여러 독립 프롬프트를 한 요청에 보낼 수 있어요. 응답은
choices에 담기고,n을 지정하면 프롬프트마다 그만큼의 완료를 생성해요(기본 1). - Embedding: 입력 문자열을 임베딩 벡터로 매핑. 여러 입력을 한 요청에 배치할 수 있어요. 요청 필드는
input(문자열 또는 문자열 목록), 선택적으로instruction과dimensions(32~1024, 2의 거듭제곱,databricks-qwen3-embedding-0-6b만 지원)를 받아요.
instruction은 모델마다 다르게 쓰는 게 좋아요. 예: BGE는 청크 인덱싱 시엔 넣지 않고 검색 쿼리에는 "Represent this sentence for searching relevant passages:"를, Qwen3-Embedding은 검색 쿼리에 "Given a web search query, retrieve relevant passages that answer the query"를 권장해요.