Referência da API REST do modelo básico

API Este artigo fornece informações gerais sobre as APIs do Databricks Foundation Model e os modelos que elas suportam. 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 da taxa de transferência aceitam o mesmo formato de solicitação da API REST.

endpoint

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 a 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 de API. Por exemplo, ambos os modelos são modelos de bate-papo.

Solicitações e respostas usam JSON, a estrutura JSON exata depende do tipo de tarefa de um endpoint. O endpoint de bate-papo e conclusão oferece suporte a respostas de transmissão.

As cargas de trabalho pay-per-tokens suportam determinados modelos. Consulte Modelos suportados para pay-per-tokens para conhecer esses modelos e os formatos de API aceitos.

Uso

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

campo	Tipo	Descrição
completion_tokens	Inteiro	Número de tokens gerados. Não incluído na incorporação de respostas.
prompt_tokens	Inteiro	Número de tokens dos prompts de entrada.
total_tokens	Inteiro	Número total de tokens.

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

Tarefa de bate-papo

As tarefas de bate-papo são otimizadas para conversas múltiplas com um modelo. Cada solicitação descreve a conversa até o momento, onde o campo messages deve alternar entre os papéis user e assistant , terminando com uma mensagem user . A resposta do modelo fornece a próxima mensagem assistant na conversa.

Solicitação de bate-papo

campo	Padrão	Tipo	Descrição
messages		Lista de mensagens de bate-papo	Necessário. Uma lista de mensagens que representam a conversa atual.
max_tokens	nil	Inteiro maior que zero ou nil, que representa o infinito	O número máximo de tokens a serem gerados.
stream	true	Boolean	transmitir respostas de volta a um cliente para permitir resultados parciais para solicitações. Se este parâmetro estiver 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 amostragem nuclear.
top_k	nil	Inteiro maior que zero ou nil, que representa o infinito	Define o número de k tokens mais prováveis a serem usados para filtragem top-k. Defina esse valor como 1 para tornar as saídas determinísticas.
stop	[]	strings ou Lista[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	nil	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 o senhor está deixando que o modelo decida qual (se houver) ferramenta é relevante para ser usada. Com auto, se o modelo não acredita 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 um 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	nil	ToolObject	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.

ChatMessage

campo	Tipo	Descrição
role	String	Necessário. A função 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 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", a ID associada ao ToolCall ao qual a mensagem está respondendo. Deve estar vazio para outras opções role.

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

ToolCall

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

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

FunctionCallCompletion

campo	Tipo	Descrição
name	String	Necessário. O nome da função recomendada pelo modelo.
arguments	Objeto	Necessá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	Necessário. O tipo de ferramenta. Atualmente, apenas "function" é suportado.
function	Objeto	Necessário. Um objeto que define a ferramenta a ser chamada no formato {"type": "function", "function": {"name": "my_function"}} em que "my_function é o nome de um FunctionObject no campo tools.

ToolObject

Consulte Chamada de função em Databricks.

campo	Tipo	Descrição
type	String	Necessário. O tipo de ferramenta. Atualmente, apenas function é suportado.
function	FunctionObject	Necessário. A definição da função associada à ferramenta.

FunctionObject

campo	Tipo	Descrição
name	String	Necessário. O nome da função a ser chamada.
description	Objeto	Necessá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 de ferramenta com maior precisão.
parameters	Objeto	Os parâmetros que a função aceita, descritos como um objeto JSON Schema 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.

Resposta do bate-papo

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

campo	Tipo	Descrição
id	String	Identificador exclusivo para conclusão do chat.
choices	List[ChatCompletionChoice] ou List[ChatCompletionChunk] (transmissão)	Lista de textos de conclusão de bate-papo. As opções n sã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	Inteiro	O tempo em que a conclusão do chat foi gerada em segundos.
model	String	A versão do modelo usada para gerar a resposta.
usage	Uso	metadados de uso tokens . Pode não estar presente nas respostas de transmissão.

ChatCompletionChoice

campo	Tipo	Descrição
index	Inteiro	O índice da escolha na lista de opções geradas.
message	Mensagem de bate-papo	Uma mensagem de conclusão do chat retornada pelo modelo. A função será assistant.
finish_reason	String	O motivo pelo qual o modelo parou de gerar tokens.

ChatCompletionChunk

campo	Tipo	Descrição
index	Inteiro	O índice da escolha na lista de opções geradas.
delta	Mensagem de bate-papo	Uma mensagem de conclusão do chat faz parte das respostas de transmissão geradas do modelo. É garantido que apenas o primeiro bloco 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

As tarefas de preenchimento de texto servem para gerar respostas a um único prompt. Ao contrário do Chat, esta tarefa suporta entradas de lotes: vários prompts independentes podem ser enviados em uma solicitação.

Solicitação de conclusão

campo	Padrão	Tipo	Descrição
prompt		strings ou Lista[strings]	Necessário. O(s) prompt(s) do modelo.
max_tokens	nil	Inteiro maior que zero ou nil, que representa o infinito	O número máximo de tokens a serem gerados.
stream	true	Boolean	transmitir respostas de volta a um cliente para permitir resultados parciais para solicitações. Se este parâmetro estiver 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 amostragem nuclear.
top_k	nil	Inteiro maior que zero ou nil, que representa o infinito	Define o número de k tokens mais prováveis a serem usados para 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 de: "truncate" (retornar tantos tokens quanto possível) e "error" (retornar um erro). Este parâmetro só é aceito pelo endpoint de pagamento por 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 Lista[strings]	O modelo para de gerar mais tokens quando qualquer uma das sequências em stop é encontrada.
suffix	""	String	Uma strings anexada ao final de cada conclusão.
echo	false	Boolean	Retorna o prompt junto com a conclusão.
use_raw_prompt	false	Boolean	Se true, passe 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	Escolha de conclusão	Uma lista de complementos de texto. Para cada prompt passado, são geradas n escolhas se n for especificado. default n é 1.
object	String	O tipo de objeto. Igual a "text_completion"
created	Inteiro	O tempo em que a conclusão foi gerada em segundos.
usage	Uso	metadados de uso tokens .

CompletionChoice

campo	Tipo	Descrição
index	Inteiro	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.

Incorporando tarefa

Incorporação de strings de entrada do mapa de tarefas em vetores de incorporação. Muitas entradas podem ser agrupadas em cada solicitação.

Solicitação de incorporação

campo	Tipo	Descrição
input	strings ou Lista[strings]	Necessá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 BGE não recomendam nenhuma instrução ao indexar pedaços e recomendam o uso da instrução "Represent this sentence for searching relevant passages:" para query de recuperação. Outros modelos como o Instructor-XL suportam uma ampla variedade de strings de instruções.

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	Incorporação de Objeto	O objeto de incorporação.
usage	Uso	metadados de uso tokens .

EmbeddingObject

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

Recursos adicionais

• APIs do modelo do Databricks Foundation

• Consultar modelos básicos e modelos externos

• Modelos suportados para pay-per-tokens