Foundation 모델 REST API 참조

아티클
10/18/2024

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

엔드포인트

각 토큰당 종량제 모델에는 단일 엔드포인트가 있으며 사용자는 HTTP POST 요청을 사용하여 이러한 엔드포인트와 상호 작용할 수 있습니다. 프로비전된 처리량 엔드포인트는 API 또는 서비스 UI를 사용하여 만들 수 있습니다. 이러한 엔드포인트는 제공된 두 모델이 동일한 API 형식을 노출하는 한 A/B 테스트를 위해 엔드포인트당 여러 모델을 지원합니다. 예를 들어 두 모델 모두 채팅 모델입니다.

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

토큰당 종량제 워크로드는 특정 모델을 지원하며, 해당 모델 및 허용되는 API 형식에 대한 토큰당 종량제 및 지원되는 모델을 참조하세요.

사용

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

필드	형식	설명
`completion_tokens`	정수	생성된 토큰 수입니다. 응답 포함에는 포함되지 않습니다.
`prompt_tokens`	정수	프롬프트 입력으로부터의 토큰 수입니다.
`total_tokens`	정수	총 토큰 수입니다.

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

채팅 작업

채팅 작업은 모델과의 멀티 턴 대화에 최적화되어 있습니다. 각 요청은 messages 필드가 user 메시지로 끝나는 assistant 및 user 역할을 번갈아 사용해야 하는 지금까지의 대화를 설명합니다. 모델 응답은 대화의 다음 assistant 메시지를 제공합니다.

채팅 요청

필드	기본값	Type	설명
`messages`		ChatMessage 목록	필수입니다. 현재 대화를 나타내는 메시지 목록입니다.
`max_tokens`	`null`	`null`, 제한이 없거나 0보다 큰 정수를 의미합니다.	생성할 최대 토큰 수
`stream`	`true`	Boolean	요청에 대한 부분 결과를 허용하기 위해 클라이언트로 응답을 다시 스트리밍합니다. 이 매개 변수가 요청에 포함되면 서버에서 보낸 이벤트 표준을 사용하여 응답이 전송됩니다.
`temperature`	`1.0`	Float in [0,2]	샘플링 온도 0은 결정적이며 값이 높을수록 더 많은 임의성이 발생합니다.
`top_p`	`1.0`	Float in (0,1]	핵 샘플링에 사용되는 확률 임계값
`top_k`	`null`	`null`, 제한이 없거나 0보다 큰 정수를 의미합니다.	상위 k 필터링에 사용할 가능성이 가장 큰 k 토큰 수를 정의합니다. 출력을 결정적으로 만들려면 이 값을 1로 설정합니다.
`stop`	[]	String 또는 List[String]	모델은 `stop` 내 시퀀스 중 하나가 발견되면 추가 토큰 생성을 중지합니다.
`n`	1	0보다 큰 정수	API는 `n`이(가) 지정된 경우 `n` 독립적인 채팅 완료를 반환합니다. 추가 유추 효율성 및 비용 절감을 위해 동일한 입력에서 여러 완료를 생성하는 워크로드에 권장됩니다. 프로비전된 처리량 엔드포인트에만 사용할 수 있습니다.
`tool_choice`	`none`	String 또는 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`	ToolObject	모델이 호출할 수 있는 `tools` 목록입니다. 현재 `function`은(는) 지원되는 유일한 `tool` 형식이며 최대 32개의 함수가 지원됩니다.
`response_format`	`null`	ResponseFormatObject	모델이 출력해야 하는 형식을 지정하는 개체입니다. 허용되는 형식은 `json_schema` 입니다.`textjson_object` `{ "type": "json_schema", "json_schema": {...} }` 모델이 제공된 JSON 스키마를 따르도록 하는 구조적 출력을 사용하도록 설정합니다. `{ "type": "json_object" }` 모델이 생성하는 응답이 유효한 JSON인지 확인하도록 설정하지만 응답이 특정 스키마를 따르는지 확인하지는 않습니다.
`logprobs`	`false`	Boolean	이 매개 변수는 샘플링되는 토큰의 로그 확률을 제공할지 여부를 나타냅니다.
`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	필수입니다. 모델에서 제안하는 함수 호출입니다.

`FunctionCallCompletion`

필드	형식	설명
`name`	문자열	필수입니다. 모델이 권장하는 함수의 이름입니다.
`arguments`	Object	필수입니다. 직렬화된 JSON 사전으로 함수에 대한 인수입니다.

`ToolChoiceObject`

Azure Databricks에서 함수 호출을 참조하세요.

필드	형식	설명
`type`	문자열	필수입니다. 도구의 형식입니다. 현재는 `"function"`만 지원됩니다.
`function`	Object	필수입니다. `"my_function`이(가) `tools` 필드에서 FunctionObject 이름인 폼 `{"type": "function", "function": {"name": "my_function"}}`을(를) 호출할 도구를 정의하는 개체입니다.

`ToolObject`

Azure Databricks에서 함수 호출을 참조하세요.

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

`FunctionObject`

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

`ResponseFormatObject`

Azure Databricks의 구조적 출력을 참조 하세요.

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

`JsonSchemaObject`

Azure Databricks의 구조적 출력을 참조 하세요.

필드	형식	설명
`name`	문자열	필수입니다. 응답 형식의 이름.
`description`	문자열	모델이 해당 형식에 따라 응답하는 방법을 결정하는 데 사용되는 응답 형식의 설명입니다.
`schema`	Object	필수입니다. JSON 스키마 개체로 설명된 응답 형식에 대한 스키마입니다.
`strict`	Boolean	출력을 생성할 때 엄격한 스키마 준수를 사용하도록 설정할지 여부를 나타냅니다. 이 스키마로 `true`설정하면 모델은 스키마 필드에 정의된 정확한 스키마를 따릅니다. strict인 경우 JSON 스키마의 하위 집합만 지원됩니다. `true`

채팅 응답

비 스트리밍 요청의 경우 응답은 단일 채팅 완료 개체입니다. 스트리밍 요청의 경우 응답은 각 이벤트가 완료 청크 개체인 위치 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`	문자열	모델이 토큰 생성을 중지한 이유. 마지막 청크만 채워집니다.

작업 완료

텍스트 완성 작업은 단일 프롬프트에 대한 응답을 생성하기 위한 것입니다. 채팅과 달리 이 작업은 일괄 처리된 입력을 지원합니다. 하나의 요청으로 여러 개의 독립적인 프롬프트를 보낼 수 있습니다.

완료 요청

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

응답 완료

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

`CompletionChoice`

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

작업 포함

작업을 포함하면 입력 문자열이 포함 벡터에 매핑됩니다. 각 요청에서 많은 입력을 함께 일괄 처리할 수 있습니다.

요청 포함

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

지침은 선택 사항이며 모델별로 매우 다릅니다. 예를 들어 BGE 작성자는 청크를 인덱싱할 때 아무런 명령도 권장하지 않으며 검색 쿼리에 대한 "Represent this sentence for searching relevant passages:" 지침을 사용하는 것이 좋습니다. Instructor-XL과 같은 다른 모델은 다양한 명령 문자열을 지원합니다.

포함 응답

필드	형식	설명
`id`	문자열	포함의 고유 식별자입니다.
`object`	문자열	개체 유형입니다. `"list"`와(과) 같음
`model`	문자열	포함을 만드는 데 사용된 포함 모델의 이름입니다.
`data`	EmbeddingObject	포함 개체체
`usage`	사용법	토큰 사용 메타데이터입니다.

`EmbeddingObject`

필드	형식	설명
`object`	문자열	개체 유형입니다. `"embedding"`와(과) 같음
`index`	정수	모델에서 생성한 임베딩 목록의 임베딩 인덱스입니다.
`embedding`	List[Float]	포함 벡터. 각 모델은 고정 크기 벡터를 반환합니다(BGE-Large의 경우 1024).

다음을 통해 공유