Referência da API REST do modelo básico

Este artigo fornece API informações gerais sobre Databricks o Foundation Model APIs e os modelos que ele suporta. As APIs do Foundation Model foram projetadas para serem semelhantes à API REST da OpenAI para facilitar a migração de projetos existentes. Tanto o endpoint de pagamento por tokens quanto o de provisionamento aceitam o mesmo formato de solicitação REST API .

ponto final

O Foundation Model APIs oferece suporte ao endpoint pay-per-tokens e ao endpoint de provisionamento da Taxa de transferência.

Um endpoint pré-configurado está disponível em seu workspace para cada modelo compatível com pay-per-tokens, e os usuários podem interagir com esse endpoint usando solicitações HTTP POST. Consulte Pay-per-tokens para ver os modelos compatíveis.

provisionamento O ponto de extremidade da taxa de transferência pode ser criado usando o site API ou a UI de serviço. Esses endpoints suportam vários modelos por endpoint para testes A/B, desde que ambos os modelos atendidos exponham o mesmo formato API. Por exemplo, os dois modelos são modelos de bate-papo. Consulte POST /api/2.0/serving-endpoint para os parâmetros de configuração do endpoint.

As solicitações e respostas usam JSON, e a estrutura exata do JSON depende do tipo de tarefa de um endpoint. O chat e o endpoint de conclusão suportam respostas de transmissão.

Uso

As respostas incluem uma submensagem usage que informa o número de tokens na solicitação e na resposta. O formato dessa submensagem é o mesmo em todos os tipos de tarefa.

campo	Tipo	Descrição
completion_tokens	Integer	Número de tokens gerados. Não incluído na incorporação de respostas.
prompt_tokens	Integer	Número de tokens do(s) prompt(s) de entrada.
total_tokens	Integer	Número total de tokens.

Para modelos como databricks-meta-llama-3-3-70b-instruct, um prompt do usuário é transformado usando um padrão de prompt antes de ser passado para o modelo. Para o endpoint pay-per-tokens, um prompt do sistema também pode ser adicionado. prompt_tokens inclui todo o texto adicionado pelo nosso servidor.

Chat tarefa

As tarefas de bate-papo são otimizadas para conversas de várias voltas com um modelo. A resposta do modelo fornece a próxima mensagem assistant na conversa. Consulte POST /serving-endpoint/{name}/invocations para consultar os parâmetros de endpoint.

Solicitação de bate-papo

campo	Padrão	Tipo	Descrição
messages		Lista de mensagens de bate-papo	Obrigatório . Uma lista de mensagens representando a conversa atual.
max_tokens	null	null, o que significa que não há limite ou um número inteiro maior que zero	O número máximo de tokens a serem gerados.
stream	true	Booleana	transmite respostas de volta para um cliente para permitir resultados parciais para solicitações. Se esse parâmetro for incluído na solicitação, as respostas serão enviadas usando o padrão de eventos enviados pelo servidor.
temperature	1.0	Flutuar em [0,2]	A temperatura de amostragem. 0 é determinístico e valores mais altos introduzem mais aleatoriedade.
top_p	1.0	Flutuar em (0,1]	O limite de probabilidade usado para a amostragem do núcleo.
top_k	null	null, o que significa que não há limite ou um número inteiro maior que zero	Define o número de k tokens mais prováveis a serem usados na filtragem top-k. Defina esse valor como 1 para tornar as saídas determinísticas.
stop	[]	strings ou List[strings]	O modelo para de gerar mais tokens quando qualquer uma das sequências em stop é encontrada.
n	1	Número inteiro maior que zero	A API retorna n conclusões de bate-papo independentes quando n é especificado. Recomendado para cargas de trabalho que geram várias conclusões na mesma entrada para maior eficiência de inferência e economia de custos. Disponível apenas para o endpoint de provisionamento Taxa de transferência.
tool_choice	none	strings ou ToolChoiceObject	Usado somente em conjunto com o campo tools. tool_choice suporta uma variedade de palavras-chave strings, como auto, required e none. auto significa que você está deixando o modelo decidir qual ferramenta (se houver) é relevante usar. Com auto, se o modelo não acreditar que nenhuma das ferramentas em tools seja relevante, o modelo gera uma mensagem de assistente padrão em vez de uma chamada de ferramenta. required significa que o modelo escolhe a ferramenta mais relevante em tools e deve gerar uma chamada de ferramenta. none significa que o modelo não gera nenhuma chamada de ferramenta e, em vez disso, deve gerar uma mensagem de assistente padrão. Para forçar uma chamada de ferramenta com uma ferramenta específica definida em tools, use ToolChoiceObject. Em default, se o campo tools estiver preenchido tool_choice = "auto". Caso contrário, o campo tools terá como padrão tool_choice = "none"
tools	null	Objeto de ferramenta	Uma lista de tools que o modelo pode chamar. Atualmente, function é o único tipo tool suportado e um máximo de 32 funções são suportadas.
response_format	null	Objeto de formato de resposta	Um objeto especificando o formato que o modelo deve gerar. Os tipos aceitos são text, json_schema ou json_object A configuração como { "type": "json_schema", "json_schema": {...} } permite saídas estruturadas que garantem que o modelo siga o esquema JSON fornecido. Definir como { "type": "json_object" } garante que as respostas geradas pelo modelo sejam JSON válidas, mas não garante que as respostas sigam um esquema específico.
logprobs	false	Booleana	Esse parâmetro indica se o senhor deve fornecer a log probabilidade de um token ser amostrado.
top_logprobs	null	Integer	Esse parâmetro controla o número de candidatos a tokens mais prováveis para retornar log probabilidades em cada etapa de amostragem. Pode ser de 0 a 20. logprobs deve ser true se estiver usando esse campo.

ChatMessage

campo	Tipo	Descrição
role	String	Obrigatório . O papel do autor da mensagem. Pode ser "system", "user", "assistant" ou "tool".
content	strings ou List[ContentItem]	Necessário para tarefas de chat que não envolvam chamadas de ferramentas. O conteúdo pode ser uma cadeia de caracteres ou uma matriz que contém uma série de elementos multimodais em uma única interação de bate-papo. Esses elementos seguem a sequência na qual são processados como entradas ou saídas pelos modelos. Essa entrada de matriz foi projetada especificamente para uso com modelos proprietários acessíveis somente por meio de fornecedores de modelos externos. Atualmente, somente os modelos Claude são suportados. Use conteúdo do tipo string para outros provedores de modelos externos, modelos de código aberto (Llama) ou modelos hospedados por clientes em Databricks. list[ContentItem] não é compatível com as especificações da OpenAI.
tool_calls	Lista de ToolCall	A lista de tool_calls que o modelo gerou. Deve ter role como "assistant" e nenhuma especificação para o campo content.
tool_call_id	String	Quando role é "tool", o ID associado ao ToolCall ao qual a mensagem está respondendo. Deve estar vazio para outras opções de role.

A função system só pode ser usada uma vez, como a primeira mensagem em uma conversa. Ele substitui o prompt do sistema default do modelo.

ContentItem

ContentItem é um dos seguintes tipos de conteúdo: TextContent, ReasoningContent, DocumentContent ou ImageContent

TextContent

campo	Tipo	Descrição
type	String	Obrigatório . Deve ser texto.
text	String	Conteúdo de texto obrigatório .
citation	Lista [Citação]	Informação de citação opcional. Veja a tabela abaixo.

Os campos de citação são os seguintes:

campo	Tipo	Descrição
type	String	Obrigatório . Deve ser char_location.
cited_text	String	O texto citado no documento.
document_index	Integer	O índice do documento citado.
document_title	String	O título do documento citado.
start_char_index	Integer	O índice inicial do texto citado no documento.
end_char_index	Integer	O índice final do texto citado no documento.

ImageContent

campo	Tipo	Descrição
type	String	Obrigatório . Deve ser um image_url.
image_url	URL da imagem	Equivalente ao objeto image_url do OpenAI.

Os campos ImageURL estão abaixo:

campo	Tipo	Descrição
url	String	Um URL da imagem ou os dados da imagem codificados em base64.
detail	String	Especifica o nível de detalhe da imagem.

ReasoningContent

campo	Tipo	Descrição
type	String	Obrigatório . Deve ser um reasoning.
summary	Lista [Resumo]	Raciocínio do conteúdo do texto. O resumo pode ser TextSummary ou EncryptedTextSummary

TextSummary

campo	Tipo	Descrição
type	String	Obrigatório . Deve ser um summary_text.
text	String	Um breve resumo do raciocínio usado pelo modelo ao gerar a resposta.
signature	String	Criptografia opcional tokens para verificar a autenticidade dos dados.

EncryptedTextSummary

campo	Tipo	Descrição
type	String	Obrigatório . Deve ser um summary_encrypted_text.
data	String	Conteúdo de texto criptografado que não é legível por humanos por motivos de segurança.

DocumentContent

DocumentContent é somente para solicitações.

campo	Tipo	Descrição
type	String	Obrigatório . Deve ser document.
title	String	Título do documento.
context	String	Descrição do documento.
source	Origem	Obrigatório . Especifica mais informações sobre o documento, incluindo formato e conteúdo.
citations	Map[strings, bool]	Mapa com um único campo “ativado” que mapeia para um bool indicando se as citações devem ser habilitadas para o documento.

Source

campo	Tipo	Descrição
type	String	Obrigatório . Deve ser base64 (PDF), text, content ou url (URLPDFSource).
media_type	String	Obrigatório para PDF e tipo de texto. - Deve ser application ou pdf para PDF. - Deve ser text ou plain para texto.
data	String	Obrigatório para PDF e texto. Os dados que contêm a fonte do documento.
content	strings ou List[TextContent] ou List[ImageContent]	Obrigatório para o tipo content. O conteúdo do documento.
url	String	Obrigatório para o tipo URLPDFSource. O URL do documento PDF.

ToolCall

Uma sugestão de ação de chamada de ferramenta feita pelo modelo. Consulte Chamada de função em Databricks.

campo	Tipo	Descrição
id	String	Obrigatório . Um identificador exclusivo para essa sugestão de chamada de ferramenta.
type	String	Obrigatório . Somente "function" é suportado.
function	Conclusão da chamada de função	Obrigatório . Uma chamada de função sugerida pelo modelo.

FunctionCallCompletion

campo	Tipo	Descrição
name	String	Obrigatório. O nome da função recomendada pelo modelo.
arguments	Objeto	Obrigatório. Argumentos para a função como um dicionário JSON serializado.

ToolChoiceObject

Consulte Chamada de função em Databricks.

campo	Tipo	Descrição
type	String	Obrigatório . O tipo da ferramenta. Atualmente, somente "function" é suportado.
function	Objeto	Obrigatório . Um objeto que define qual ferramenta chamar no formato {"type": "function", "function": {"name": "my_function"}}, onde "my_function é o nome de um FunctionObject no campo tools.

ToolObject

Consulte Chamada de função em Databricks.

campo	Tipo	Descrição
type	String	Obrigatório . O tipo da ferramenta. Atualmente, somente function é suportado.
function	Objeto de função	Obrigatório . A definição da função associada à ferramenta.

FunctionObject

campo	Tipo	Descrição
name	String	Obrigatório . O nome da função a ser chamada.
description	Objeto	Obrigatório . A descrição detalhada da função. O modelo usa essa descrição para entender a relevância da função para o prompt e gerar as chamadas da ferramenta com maior precisão.
parameters	Objeto	Os parâmetros que a função aceita, descritos como um objeto de esquema JSON válido. Se a ferramenta for chamada, a chamada da ferramenta será adequada ao esquema JSON fornecido. A omissão de parâmetros define uma função sem nenhum parâmetro. O número de properties é limitado a 15 teclas.
strict	Booleana	Se deve habilitar a adesão estrita ao esquema ao gerar a chamada de função. Se definido como true, o modelo segue o esquema exato definido no campo esquema. Somente um subconjunto do esquema JSON é suportado quando strict é true

ResponseFormatObject

Consulte Saídas estruturadas em Databricks.

campo	Tipo	Descrição
type	String	Obrigatório . O tipo de formato de resposta que está sendo definido. text para texto não estruturado, json_object para objetos JSON não estruturados ou json_schema para objetos JSON que aderem a um esquema específico.
json_schema	Objeto do esquema JSON	Obrigatório . O esquema JSON a ser seguido se type for definido como json_schema

JsonSchemaObject

Consulte Saídas estruturadas em Databricks.

campo	Tipo	Descrição
name	String	Obrigatório . O nome do formato de resposta.
description	String	Uma descrição da finalidade do formato de resposta, usada pelo modelo para determinar como responder no formato.
schema	Objeto	Obrigatório . O esquema do formato de resposta, descrito como um objeto de esquema JSON.
strict	Booleana	Se deve habilitar a adesão estrita ao esquema ao gerar a saída. Se definido como true, o modelo segue o esquema exato definido no campo esquema. Somente um subconjunto do esquema JSON é suportado quando strict é true

Resposta do chat

Para solicitações sem transmissão, a resposta é um único objeto de conclusão de chat. Para solicitações de transmissão, a resposta é um text/event-stream em que cada evento é um objeto de bloco de conclusão. A estrutura de nível superior de objetos de conclusão e fragmentação é quase idêntica: somente choices tem um tipo diferente.

campo	Tipo	Descrição
id	String	Identificador exclusivo para a conclusão do bate-papo.
choices	List[ChatCompletionChoice] ou List[ChatCompletionChunk] (transmissão)	Lista de textos de conclusão de bate-papo. As opções n serão retornadas se o parâmetro n for especificado.
object	String	O tipo de objeto. Igual a "chat.completions" para não transmissão ou "chat.completion.chunk" para transmissão.
created	Integer	A hora em que a conclusão do bate-papo foi gerada em segundos.
model	String	A versão do modelo usada para gerar a resposta.
usage	Uso	metadados de uso de tokens. Pode não estar presente nas respostas de transmissão.

ChatCompletionChoice

campo	Tipo	Descrição
index	Integer	O índice da escolha na lista de opções geradas.
message	Mensagem de bate-papo	Uma mensagem de conclusão do bate-papo retornada pela modelo. O papel será assistant.
finish_reason	String	O motivo pelo qual o modelo parou de gerar tokens.
extra_fields	String	Ao usar modelos proprietários de provedores de modelos externos, as APIs do provedor podem incluir metadados adicionais nas respostas. A Databricks filtra essas respostas e retorna apenas um subconjunto dos campos originais do provedor. O safetyRating é o único campo extra suportado no momento. Consulte a documentação do Gemini para obter mais detalhes.

ChatCompletionChunk

campo	Tipo	Descrição
index	Integer	O índice da escolha na lista de opções geradas.
delta	Mensagem de bate-papo	Uma mensagem de conclusão de bate-papo que faz parte das respostas de transmissão geradas pelo modelo. É garantido que apenas o primeiro pedaço tenha role preenchido.
finish_reason	String	O motivo pelo qual o modelo parou de gerar tokens. Somente o último pedaço terá isso preenchido.

Tarefa de conclusão

A tarefa de conclusão de texto serve para gerar respostas a um único prompt. Ao contrário do Chat, essa tarefa suporta muitas entradas: vários prompts independentes podem ser enviados em uma única solicitação. Consulte POST /serving-endpoint/{name}/invocations para consultar os parâmetros de endpoint.

Solicitação de conclusão

campo	Padrão	Tipo	Descrição
prompt		strings ou List[strings]	Obrigatório . As instruções para o modelo.
max_tokens	null	null, o que significa que não há limite ou um número inteiro maior que zero	O número máximo de tokens a serem gerados.
stream	true	Booleana	transmite respostas de volta para um cliente para permitir resultados parciais para solicitações. Se esse parâmetro for incluído na solicitação, as respostas serão enviadas usando o padrão de eventos enviados pelo servidor.
temperature	1.0	Flutuar em [0,2]	A temperatura de amostragem. 0 é determinístico e valores mais altos introduzem mais aleatoriedade.
top_p	1.0	Flutuar em (0,1]	O limite de probabilidade usado para a amostragem do núcleo.
top_k	null	null, o que significa que não há limite ou um número inteiro maior que zero	Define o número de k tokens mais prováveis a serem usados na filtragem top-k. Defina esse valor como 1 para tornar as saídas determinísticas.
error_behavior	"error"	"truncate" ou "error"	Para tempos limite e erros de comprimento de contexto excedido. Uma das opções: "truncate" (retorna o maior número possível de tokens) e "error" (retorna um erro). Esse parâmetro só é aceito pelo endpoint pay per tokens.
n	1	Número inteiro maior que zero	A API retorna n conclusões de bate-papo independentes quando n é especificado. Recomendado para cargas de trabalho que geram várias conclusões na mesma entrada para maior eficiência de inferência e economia de custos. Disponível apenas para o endpoint de provisionamento Taxa de transferência.
stop	[]	strings ou List[strings]	O modelo para de gerar mais tokens quando qualquer uma das sequências em stop é encontrada.
suffix	""	String	Uma cadeia de caracteres que é anexada ao final de cada conclusão.
echo	false	Booleana	Retorna o prompt junto com a conclusão.
use_raw_prompt	false	Booleana	Se true, passe o prompt diretamente para o modelo sem nenhuma transformação.

Resposta de conclusão

campo	Tipo	Descrição
id	String	Identificador exclusivo para o preenchimento do texto.
choices	Opção de conclusão	Uma lista de conclusões de texto. Para cada prompt passado, as opções n são geradas se n for especificado. O padrão n é 1.
object	String	O tipo de objeto. Igual a "text_completion"
created	Integer	A hora em que a conclusão foi gerada em segundos.
usage	Uso	metadados de uso de tokens.

CompletionChoice

campo	Tipo	Descrição
index	Integer	O índice do prompt na solicitação.
text	String	A conclusão gerada.
finish_reason	String	O motivo pelo qual o modelo parou de gerar tokens.

Tarefa de incorporação

A tarefa de incorporação mapeia a entrada strings em vetores de incorporação. Muitas entradas podem ser agrupadas em cada solicitação. Consulte POST /serving-endpoint/{name}/invocations para consultar os parâmetros de endpoint.

Solicitação de incorporação

campo	Tipo	Descrição
input	strings ou List[strings]	Obrigatório . O texto de entrada a ser incorporado. Pode ser uma cadeia de caracteres ou uma lista de strings.
instruction	String	Uma instrução opcional a ser passada para o modelo de incorporação.

As instruções são opcionais e altamente específicas do modelo. Por exemplo, os autores do The BGE não recomendam nenhuma instrução ao indexar blocos e recomendam o uso da instrução "Represent this sentence for searching relevant passages:" para consultas de recuperação. Outros modelos, como o Instructor-XL, suportam uma ampla gama de instruções strings.

Resposta de incorporações

campo	Tipo	Descrição
id	String	Identificador exclusivo para a incorporação.
object	String	O tipo de objeto. Igual a "list".
model	String	O nome do modelo de incorporação usado para criar a incorporação.
data	Objeto de incorporação	O objeto de incorporação.
usage	Uso	metadados de uso de tokens.

EmbeddingObject

campo	Tipo	Descrição
object	String	O tipo de objeto. Igual a "embedding".
index	Integer	O índice da incorporação na lista de incorporações gerada pelo modelo.
embedding	Lista [Float]	O vetor de incorporação. Cada modelo retornará um vetor de tamanho fixo (1024 para BGE-Large)

Recurso adicional

• APIs do Foundation Model do Databricks

• Use modelos de fundação

• Modelos compatíveis com as APIs do Databricks Foundation Models