다음을 통해 공유

Foundation 모델에 대한 REST API 참조

  • 아티클

이 문서에서는 Databricks Foundation 모델 API 및 지원하는 모델에 대한 일반 API 정보를 제공합니다. Foundation Model API는 기존 프로젝트를 보다 쉽게 마이그레이션할 수 있도록 OpenAI의 REST API와 유사하게 설계되었습니다. 토큰당 종량제 및 프로비전된 처리량 엔드포인트는 모두 동일한 REST API 요청 형식을 허용합니다.

엔드포인트

Foundation Model API는 토큰당 종량제 엔드포인트 및 프로비전된 처리량 엔드포인트를 지원합니다.

미리 구성된 엔드포인트는 각 토큰당 종량제 지원 모델에 대해 작업 영역에서 사용할 수 있으며 사용자는 HTTP POST 요청을 사용하여 이러한 엔드포인트와 상호 작용할 수 있습니다. 지원되는 모델은 토큰당 종량제 참조하세요.

프로비전 처리량 엔드포인트는 API 또는 서빙 UI를 사용하여 생성할 수 있습니다. 이러한 엔드포인트는 제공된 두 모델이 동일한 API 형식을 노출하는 한 A/B 테스트를 위해 엔드포인트당 여러 모델을 지원합니다. 예를 들어 두 모델 모두 채팅 모델입니다. 엔드포인트 구성 매개 변수는 POST /api/2.0/serving-endpoints 참조하세요.

요청 및 응답은 JSON을 사용합니다. 정확한 JSON 구조는 엔드포인트의 작업 유형에 따라 달라집니다. 채팅 및 완료 엔드포인트는 스트리밍 응답을 지원합니다.

사용법

응답에는 요청 및 응답의 토큰 수를 보고하는 usage 하위 메시지가 포함됩니다. 이 하위 메시지의 형식은 모든 작업 유형에서 동일합니다.

필드 유형 묘사
completion_tokens 정수 생성된 토큰 수입니다. 임베딩 응답에 포함되지 않습니다.
prompt_tokens 정수 입력 프롬프트의 토큰 수입니다.
total_tokens 정수 총 토큰 수입니다.

Meta-Llama-3.3-70B-Instruct 같은 모델의 경우 사용자 프롬프트가 모델에 전달되기 전에 프롬프트 템플릿을 사용하여 변환됩니다. 토큰당 종량제 엔드포인트의 경우 시스템 프롬프트도 추가될 수 있습니다. prompt_tokens는 서버가 추가한 모든 텍스트를 포함합니다.

채팅 작업

채팅 작업은 모델과의 멀티 턴 대화에 최적화되어 있습니다. 모델 응답은 대화의 다음 assistant 메시지를 제공합니다. 엔드포인트 매개 변수를 쿼리하는 POST /serving-endpoints/{name}/invocations 참조하세요.

채팅 요청

필드 기본값 유형 묘사
messages ChatMessage 목록 필수. 현재 대화를 나타내는 메시지 목록입니다.
max_tokens null null- 제한이 없거나 0보다 큰 정수입니다. 생성할 최대 토큰 수입니다.
stream true 부울 요청에 대한 부분 결과를 허용하기 위해 클라이언트로 응답을 다시 스트리밍합니다. 이 매개 변수가 요청에 포함된 경우, 서버에서 보낸 이벤트 표준을 사용하여 응답이 전송됩니다.
temperature 1.0 [0,2] 범위의 실수 샘플링 온도입니다. 0은 결정적이며 값이 높을수록 더 많은 임의성이 발생합니다.
top_p 1.0 실수 (0,1] 안에 핵 샘플링에 사용되는 확률 임계값입니다.
top_k null null- 제한이 없거나 0보다 큰 정수입니다. 상위 k 필터링에 사용할 가능성이 가장 큰 k 토큰 수를 정의합니다. 출력을 결정적으로 만들려면 이 값을 1로 설정합니다.
stop [] 문자열 또는 목록[문자열] stop 시퀀스 중 하나가 발견되면 모델이 추가 토큰 생성을 중지합니다.
n 1 0보다 큰 정수 API는 n 지정되면 n 독립적인 채팅 완료를 반환합니다. 추가 유추 효율성 및 비용 절감을 위해 동일한 입력에서 여러 완료를 생성하는 워크로드에 권장됩니다. 프로비전된 처리량 엔드포인트에만 사용할 수 있습니다.
tool_choice none 문자열 또는 ToolChoiceObject tools 필드와 함께만 사용됩니다. tool_choice auto, required및 none같은 다양한 키워드 문자열을 지원합니다. auto 모델에서 사용과 관련된 도구(있는 경우)를 결정하도록 하는 것을 의미합니다. 모델에서 auto 도구가 관련이 있다고 생각하지 않는 경우 tools 사용하여 모델은 도구 호출 대신 표준 도우미 메시지를 생성합니다. required 모델이 tools 가장 관련성이 큰 도구를 선택하고 도구 호출을 생성해야 했음을 의미합니다. none 모델이 도구 호출을 생성하지 않고 대신 표준 도우미 메시지를 생성해야 했음을 의미합니다. tools정의된 특정 도구를 사용하여 도구를 강제로 호출하려면 ToolChoiceObject사용합니다. 기본적으로 tools 필드가 채워지면 tool_choice = "auto". 그렇지 않으면 tools 필드는 기본적으로 tool_choice = "none"
tools null 도구 개체 모델이 호출할 수 있는 tools 목록입니다. 현재 function 유일하게 지원되는 tool 형식이며 최대 32개의 함수가 지원됩니다.
response_format null ResponseFormatObject 모델이 출력해야 하는 형식을 지정하는 개체입니다. 허용되는 형식은 text, json_schema 또는 json_object

{ "type": "json_schema", "json_schema": {...} } 설정하면 모델이 제공된 JSON 스키마를 따르도록 하는 구조화된 출력을 사용할 수 있습니다.

{ "type": "json_object" } 설정하면 모델이 생성하는 응답이 유효한 JSON이지만 응답이 특정 스키마를 따르는지 확인하지는 않습니다.
logprobs false 부울 이 매개 변수는 샘플링되는 토큰의 로그 확률을 제공할지 여부를 나타냅니다.
top_logprobs null 정수 이 매개 변수는 각 샘플링 단계에서 로그 확률을 반환할 가능성이 가장 높은 토큰 후보 수를 제어합니다. 0-20일 수 있습니다. 이 필드를 사용하는 경우 logprobs는 true이어야 합니다.

ChatMessage

필드 유형 묘사
role 문자열 필수. 메시지 작성자의 역할입니다. "system", "user", "assistant" 또는 "tool"수 있습니다.
content 문자열 메시지의 내용입니다. 도구 호출이 필요하지 않은 채팅 작업에 필요한.
tool_calls ToolCall 목록 모델이 생성한 tool_calls 목록입니다. role는 "assistant"로 있어야 하며, content 필드에 대한 사양은 없어야 합니다.
tool_call_id 문자열 role가 "tool"일 때, 메시지가 응답하는 ToolCall와 연관된 ID입니다. 다른 role 옵션의 경우 비어 있어야 합니다.

system 역할은 대화의 첫 번째 메시지로 한 번만 사용할 수 있습니다. 모델의 기본 시스템 프롬프트를 재정의합니다.

ToolCall

모델의 도구 호출 작업 제안입니다. Azure Databricks호출하는 함수를 참조하세요.

필드 유형 묘사
id 문자열 필수. 이 도구 호출 제안에 대한 고유 식별자입니다.
type 문자열 필수. "function"만 지원됩니다.
function 함수호출완료 필수. 모델에서 제안하는 함수 호출입니다.

FunctionCallCompletion

필드 유형 묘사
name 문자열 필수. 모델이 권장하는 함수의 이름입니다.
arguments 객체 필수. 함수에 대한 인수는 직렬화된 JSON 사전입니다.

ToolChoiceObject

Azure Databricks호출하는 함수를 참조하세요.

필드 유형 묘사
type 문자열 필수. 도구의 유형입니다. 현재는 "function"만 지원됩니다.
function 객체 필수. {"type": "function", "function": {"name": "my_function"}} 형식의 도구를 정의하는 객체로, "my_function은 tools 필드의 FunctionObject의 이름입니다.

ToolObject

Azure Databricks호출하는 함수를 참조하세요.

필드 유형 묘사
type 문자열 필수. 도구의 유형입니다. 현재는 function만 지원됩니다.
function FunctionObject 필수. 도구와 연결된 함수 정의입니다.

FunctionObject

필드 유형 묘사
name 문자열 필수. 호출할 함수의 이름입니다.
description 객체 필수. 함수에 대한 자세한 설명입니다. 모델은 이 설명을 사용하여 프롬프트에 대한 함수의 관련성을 이해하고 더 높은 정확도로 도구 호출을 생성합니다.
parameters 객체 유효한 JSON 스키마 개체로 설명된 함수가 허용하는 매개 변수입니다. 도구가 호출되면 도구 호출이 제공된 JSON 스키마에 적합합니다. 매개 변수를 생략하면 매개 변수가 없는 함수가 정의됩니다. properties 수는 15개 키로 제한됩니다.
strict 부울 함수 호출을 생성할 때 엄격한 스키마 준수를 사용하도록 설정할지 여부입니다. true설정하면 모델은 스키마 필드에 정의된 정확한 스키마를 따릅니다. strict가 true 경우 JSON 스키마의 하위 집합만 지원됩니다.

ResponseFormatObject

Azure Databricks에서 구조적 출력 을(를) 참조하세요.

필드 유형 묘사
type 문자열 필수. 정의되는 응답 형식의 유형입니다. 구조화되지 않은 텍스트에 대한 text, 구조화되지 않은 JSON 개체에 대한 json_object 또는 특정 스키마를 준수하는 JSON 개체에 대한 json_schema.
json_schema JsonSchemaObject 필수. type json_schema 설정된 경우 준수할 JSON 스키마

JsonSchemaObject

Azure Databricks에서 구조적 출력 을(를) 참조하세요.

필드 유형 묘사
name 문자열 필수. 응답 형식의 이름입니다.
description 문자열 응답 형식의 용도에 대한 설명이며, 모델에서 형식으로 응답하는 방법을 결정하는 데 사용됩니다.
schema 객체 필수. JSON 스키마 개체로 설명된 응답 형식에 대한 스키마입니다.
strict 부울 출력을 생성할 때 엄격한 스키마 준수를 사용하도록 설정할지 여부입니다. true설정하면 모델은 스키마 필드에 정의된 정확한 스키마를 따릅니다. strict가 true 경우 JSON 스키마의 하위 집합만 지원됩니다.

채팅 응답

비 스트리밍 요청의 경우 응답은 단일 채팅 완료 개체입니다. 스트리밍 요청에 대한 응답은 text/event-stream이며, 각 이벤트는 완성된 청크 객체입니다. 완성 및 청크 개체의 최상위 구조는 거의 동일합니다. choices만 다른 유형을 가지고 있습니다.

필드 유형 묘사
id 문자열 채팅 완료를 위한 고유 식별자입니다.
choices List[ChatCompletionChoice] 또는 List[ChatCompletionChunk] (스트리밍) 채팅 완료 텍스트 목록입니다. n 매개 변수를 지정하면 n 선택 항목이 반환됩니다.
object 문자열 개체 유형 스트리밍이 아닌 경우 "chat.completions"에 해당하고, 스트리밍의 경우 "chat.completion.chunk"에 해당합니다.
created 정수 채팅 완료가 생성된 시간(초 단위)입니다.
model 문자열 응답을 생성하는 데 사용되는 모델 버전입니다.
usage 사용량 토큰 사용 메타데이터입니다. 스트리밍 응답에 없을 수 있습니다.

ChatCompletionChoice

필드 유형 묘사
index 정수 생성된 선택 항목의 목록에서 선택의 인덱스입니다.
message chatMessage 모델에서 반환한 채팅 완료 메시지입니다. 역할은 assistant.
finish_reason 문자열 모델이 토큰 생성을 중지한 이유입니다.

ChatCompletionChunk

필드 유형 묘사
index 정수 생성된 선택 항목 목록에서의 인덱스입니다.
delta chatMessage 모델에서 생성된 스트리밍 응답 중 하나인 채팅 완료 메시지입니다. 첫 번째 청크만 role가 포함됨이 보장됩니다.
finish_reason 문자열 모델이 토큰 생성을 중지한 이유입니다. 마지막 청크에만 이 내용이 채워집니다.

작업 완료

텍스트 완성 작업은 단일 프롬프트에 대한 응답을 생성하기 위한 것입니다. 채팅과 달리 이 작업은 일괄 처리된 입력을 지원합니다. 하나의 요청으로 여러 개의 독립적인 프롬프트를 보낼 수 있습니다. 엔드포인트 매개 변수를 쿼리하는 POST /serving-endpoints/{name}/invocations 참조하세요.

완료 요청

필드 기본값 유형 묘사
prompt String(문자열) 또는 List[String](리스트) 필수. 모델용 프롬프트입니다.
max_tokens null null- 제한이 없거나 0보다 큰 정수입니다. 생성할 최대 토큰 수입니다.
stream true 부울 요청에 대한 부분 결과를 허용하기 위해 클라이언트로 응답을 다시 스트리밍합니다. 이 매개 변수가 요청에 포함된 경우, 서버에서 보낸 이벤트 표준을 사용하여 응답이 전송됩니다.
temperature 1.0 [0,2] 범위의 실수 샘플링 온도입니다. 0은 결정적이며 값이 높을수록 더 많은 임의성이 발생합니다.
top_p 1.0 실수 (0,1] 안에 핵 샘플링에 사용되는 확률 임계값입니다.
top_k null null- 제한이 없거나 0보다 큰 정수입니다. 상위 k 필터링에 사용할 가능성이 가장 큰 k 토큰 수를 정의합니다. 출력을 결정적으로 만들려면 이 값을 1로 설정합니다.
error_behavior "error" "truncate" 또는 "error" 시간 제한 및 컨텍스트 길이 초과 오류의 경우 "truncate"(가능한 한 많은 토큰 반환) 및 "error"(오류 반환) 중 하나입니다. 이 매개 변수는 토큰 엔드포인트당 지불로만 허용됩니다.
n 1 0보다 큰 정수 API는 n 지정되면 n 독립적인 채팅 완료를 반환합니다. 추가 유추 효율성 및 비용 절감을 위해 동일한 입력에서 여러 완료를 생성하는 워크로드에 권장됩니다. 프로비전된 처리량 엔드포인트에만 사용할 수 있습니다.
stop [] 문자열 또는 List[String] stop 시퀀스 중 하나가 발견되면 모델이 추가 토큰 생성을 중지합니다.
suffix "" 문자열 모든 완료의 끝에 추가되는 문자열입니다.
echo false 부울 완료와 함께 프롬프트를 반환합니다.
use_raw_prompt false 부울 만약 true라면, prompt을 변환 없이 모델에 직접 전달합니다.

완료 응답

필드 유형 묘사
id 문자열 텍스트 완성을 위한 고유 식별자입니다.
choices CompletionChoice 텍스트 완성 목록입니다. 전달된 모든 프롬프트에 대해 n이 지정된 경우 n 선택 항목이 생성됩니다. 기본 n 1입니다.
object 문자열 개체 유형 "text_completion" 같음
created 정수 완료가 생성된 시간(초)입니다.
usage 사용량 토큰 사용 메타데이터입니다.

CompletionChoice

필드 유형 묘사
index 정수 요청에서 프롬프트의 인덱스입니다.
text 문자열 생성된 완료입니다.
finish_reason 문자열 모델이 토큰 생성을 중지한 이유입니다.

포함 작업

임베딩 작업은 입력 문자열을 임베딩 벡터로 매핑합니다. 각 요청에서 많은 입력을 함께 일괄 처리할 수 있습니다. 엔드포인트 매개 변수를 쿼리하는 POST /serving-endpoints/{name}/invocations 참조하세요.

삽입 요청

필드 유형 묘사
input 문자열(String) 또는 목록(List)[문자열] 필수. 삽입할 입력 텍스트. 문자열 또는 문자열 목록일 수 있습니다.
instruction 문자열 포함 모델에 전달할 선택적 명령입니다.

지침은 선택 사항이며 모델에 매우 의존적입니다. 예를 들어, BGE 작성자는 청크를 인덱싱할 때 별도의 지시를 사용하지 말 것을 권장하며, 검색 쿼리를 위해 명령 "Represent this sentence for searching relevant passages:"을 사용하는 것을 추천합니다. Instructor-XL 같은 다른 모델은 다양한 명령 문자열을 지원합니다.

임베딩 응답

필드 유형 묘사
id 문자열 임베딩의 고유 식별자입니다.
object 문자열 개체 유형 "list"와 같다.
model 문자열 임베딩을 생성하는 데 사용된 임베딩 모델의 이름입니다.
data 임베딩오브젝트 임베딩 개체입니다.
usage 사용량 토큰 사용 메타데이터입니다.

EmbeddingObject

필드 유형 묘사
object 문자열 개체 유형 "embedding"와 같다.
index 정수 모델에서 생성된 임베딩 목록에서 임베딩의 인덱스입니다.
embedding 리스트[실수형] 임베딩 벡터입니다. 각 모델은 고정 크기 벡터를 반환합니다(BGE-Large경우 1024).

추가 리소스