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

Cada modelo pay-per-tokens tem um único endpoint, e os usuários podem interagir com esse endpoint usando solicitações HTTP POST. provisionamento O ponto de extremidade da taxa de transferência pode ser criado usando o site API ou a UI de serviço. Esses pontos de extremidade também 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.

As cargas de trabalho pay-per-tokens são compatíveis com determinados modelos. Consulte Modelos compatíveis para pay-per-tokens para conhecer esses modelos e os formatos aceitos em API.

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 llama-2-70b-chat, 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. Cada solicitação descreve a conversa até agora, na qual o campo messages deve alternar entre as funções user e assistant, terminando com uma mensagem user. 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 para { "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 probabilidade log de um token ser amostrado.
top_logprobs	null	Integer	Esse parâmetro controla o número de tokens candidatos 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	String	O conteúdo da mensagem. Necessário para tarefas de chat que não envolvam chamadas de ferramentas.
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.

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á ajustada 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 chaves.
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 estiver 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.

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. Um dos seguintes: "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 variedade 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)

Outros recursos

• APIs do Foundation Model do Databricks

• Consulte modelos básicos

• Modelos compatíveis com pagamento por token