Compartilhar via

Referência da API REST do modelo de fundação

  • Artigo

Este artigo fornece informações gerais sobre as APIs de Modelos do Databricks Foundation e os modelos que elas suportam. As APIs do Modelo de Fundação foram projetadas para serem semelhantes à API REST do OpenAI para facilitar a migração de projetos existentes. Os pontos de extremidade de pagamento por token e de taxa de transferência provisionada aceitam o mesmo formato de solicitação da API REST.

Pontos de extremidade

As APIs dos Modelos Fundamentais dão suporte a pontos de extremidade de pagamento por token e pontos de extremidade com taxa de transferência provisionada.

Um ponto de extremidade pré-configurado está disponível em seu workspace para cada modelo com suporte de pagamento por token e os usuários podem interagir com esses pontos de extremidade usando solicitações HTTP POST. Confira Pagamento por token para modelos com suporte.

Os pontos de extremidade de taxa de transferência provisionados podem ser criados usando a API ou a interface do usuário de serviço. Esses pontos de extremidade dão suporte a vários modelos por ponto de extremidade para testes A/B, desde que ambos os modelos servidos exponham o mesmo formato de API. Por exemplo, ambos os modelos são modelos de chat. Consulte POST /api/2.0/serving-endpoints para os parâmetros de configuração do endpoint.

Requisições e respostas usam JSON, a estrutura JSON exata depende do tipo de tarefa de um endpoint. Os pontos de extremidade de chats e de conclusão dão suporte para respostas de streaming.

Uso

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

Campo Tipo Descrição
completion_tokens Integer Número de tokens gerados. Não incluído nas respostas de inserção.
prompt_tokens Número Inteiro Número de tokens do(s) prompt(s) de entrada.
total_tokens Integer Número de tokens totais.

Para modelos como Meta-Llama-3.3-70B-Instruct, um prompt do usuário é transformado usando um modelo de prompt antes de ser passado para o modelo. Para ponto de extremidades de pagamento por token, um prompt do sistema também pode ser adicionado. prompt_tokens inclui todo o texto adicionado pelo servidor.

Tarefa de chat

As tarefas de chats são otimizadas para conversas com várias rodadas com um modelo. A resposta do modelo fornece a próxima mensagem assistant na conversa. Confira POST /serving-endpoints/{name}/invocações para consultar parâmetros de ponto de extremidade.

Solicitação de chat

Campo Padrão Tipo Descrição
messages Lista ChatMessage Obrigatório. Uma lista de mensagens que representam a conversa atual.
max_tokens null null, o que significa sem limite, ou seja, um inteiro maior que zero O número máximo de tokens a serem gerados.
stream true Boolean Transmita respostas de volta para um cliente para permitir resultados parciais para solicitações. Se esse parâmetro estiver incluído na solicitação, as respostas serão enviadas usando os eventos enviados pelo servidor padrão.
temperature 1.0 Float em [0,2] A temperatura de amostragem. 0 é determinístico e valores mais altos introduzem mais aleatoriedade.
top_p 1.0 Float em (0,1] O limite de probabilidade usado para amostragem de núcleo.
top_k null null, que significa sem limite ou um número inteiro maior que zero Define o número de tokens k mais prováveis a serem usados para filtragem top-k. Defina esse valor como 1 para tornar as saídas determinísticas.
stop [] Cadeia de caracteres ou List[String] O modelo para de gerar tokens adicionais quando qualquer uma das sequências no stop é encontrada.
n 1 Inteiro maior que zero A API retorna n preenchimentos de chat independentes quando n é especificado. Recomendado para cargas de trabalho que geram várias conclusões na mesma entrada para eficiência de inferência adicional e economia de custos. Disponível apenas para pontos de extremidade de taxa de transferência provisionada.
tool_choice none Cadeia de caracteres ou ToolChoiceObject Usado somente em conjunto com o campo tools. tool_choice dá suporte a uma variedade de cadeias de caracteres de palavra-chave, como auto, requirede none. auto significa que você está permitindo que o modelo decida qual ferramenta (se houver) é relevante para usar. Com auto se o modelo não acredita que nenhuma das ferramentas no tools seja relevante, o modelo gerará uma mensagem de assistente padrão em vez de uma chamada de ferramenta. required significa que o modelo escolhe a ferramenta mais relevante no 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. Por padrão, se o campo tools estiver preenchido tool_choice = "auto". Caso contrário, o campo tools usa como padrão tool_choice = "none"
tools null ToolObject Uma lista de tools que o modelo pode chamar. Atualmente, function é o único tipo de tool com suporte e há suporte para um máximo de 32 funções.
response_format null ResponseFormatObject Um objeto que especifica 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": {...} } habilita saídas estruturadas, o que garante que o modelo siga o esquema JSON fornecido.

A configuração para { "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 Boolean Esse parâmetro indica se é necessário fornecer a probabilidade de log de um token sendo amostrado.
top_logprobs null Integer Esse parâmetro controla o número de candidatos de tokens mais possíveis para os quais retornar probabilidades logarítmicas em cada etapa de amostragem. Pode ser 0-20. logprobs deve ser true se estiver usando esse campo.

ChatMessage

Campo Tipo Descrição
role String Obrigatório. A função do autor da mensagem. Pode ser "system", "user", "assistant" ou "tool".
content String O conteúdo da mensagem. Obrigatório para tarefas de chat que não envolvem 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 a 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 de sistema padrão do modelo.

ToolCall

Uma sugestão de ação de chamada de ferramenta pelo modelo. Confira Chamada de função no Azure Databricks.

Campo Tipo Descrição
id String Obrigatório. Um identificador exclusivo para essa sugestão de chamada de ferramenta.
type String Obrigatório. Há suporte apenas para "function".
function FunctionCallCompletion 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

Confira Chamada de função no Azure Databricks.

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

ToolObject

Confira Chamada de função no Azure Databricks.

Campo Tipo Descrição
type String Obrigatório. O tipo da ferramenta. Atualmente, há suporte apenas para function.
function FunctionObject Obrigatório. A definição de 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 de 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 de ferramenta será adequada ao esquema JSON fornecido. Omitir parâmetros define uma função sem parâmetros. O número de properties é limitado a 15 chaves.
strict Boolean Se deseja habilitar a adesão estrita do esquema ao gerar a chamada de função. Se definido como true, o modelo segue o esquema exato definido no campo de esquema. Há suporte apenas para um subconjunto de esquema JSON quando estrito é true

ResponseFormatObject

Confira Saídas estruturadas no Azure 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 estão aderindo a um esquema específico.
json_schema JsonSchemaObject Obrigatório. O esquema JSON a ser seguido se type estiver definido como json_schema

JsonSchemaObject

Confira Saídas estruturadas no Azure Databricks.

Campo Tipo Descrição
name String Obrigatório. O nome do formato de resposta.
description String Uma descrição de para que serve o formato de resposta, usada pelo modelo para determinar a forma de responder no formato.
schema Objeto Obrigatório. O esquema para o formato de resposta, descrito como um objeto de esquema JSON.
strict Boolean Se deseja habilitar a adesão estrita do esquema ao gerar a saída. Se definido como true, o modelo segue o esquema exato definido no campo de esquema. Há suporte apenas para um subconjunto de esquema JSON quando estrito é true

Resposta de chat

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

Campo Tipo Descrição
id String Identificador exclusivo para a conclusão do chat.
choices List[ChatCompletionChoice] ou List[ChatCompletionChunk] (streaming) Lista de textos de conclusão do chat. n opções 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 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 de token. Talvez não esteja presente em respostas de streaming.

ChatCompletionChoice

Campo Tipo Descrição
index Integer O índice da escolha na lista de opções geradas.
message ChatMessage Uma mensagem de conclusão de 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 Integer O índice de escolha na lista de opções geradas.
delta Mensagem de Chat Uma parte da mensagem de conclusão de chat das respostas transmitidas geradas do modelo. Somente a primeira parte tem a garantia de ter role preenchido.
finish_reason String O motivo pelo qual o modelo parou de gerar tokens. Somente a última parte terá essa população.

Tarefa de conclusão

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

Solicitação de conclusão

Campo Padrão Tipo Descrição
prompt Cadeia de caracteres ou List[String] Obrigatório. As instruções para o modelo.
max_tokens null null, o que significa sem limite, ou um inteiro maior que zero O número máximo de tokens a serem gerados.
stream true Boolean Transmita respostas de volta para um cliente para permitir resultados parciais para solicitações. Se esse parâmetro estiver incluído na solicitação, as respostas serão enviadas usando os eventos enviados pelo servidor padrão.
temperature 1.0 Float em [0,2] A temperatura de amostragem. 0 é determinístico e valores mais altos introduzem mais aleatoriedade.
top_p 1.0 Float em (0,1] O limite de probabilidade usado para amostragem de núcleo.
top_k null null, o que significa nenhum limite ou um inteiro maior que zero. Define o número de tokens k 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 tamanho de contexto excedidos. Um deles: "truncate" (retornar o maior número possível de tokens) e "error" (retornar um erro). Esse parâmetro só é aceito por pontos de extremidade de pagamento por token.
n 1 Inteiro maior que zero A API retorna n preenchimentos de chat independentes quando n é especificado. Recomendado para cargas de trabalho que geram várias conclusões na mesma entrada para eficiência de inferência adicional e economia de custos. Disponível apenas para pontos de extremidade de taxa de transferência provisionada.
stop [] Cadeia de caracteres ou List[String] O modelo para de gerar tokens adicionais quando qualquer uma das sequências no stop é encontrada.
suffix "" String Uma cadeia de caracteres acrescentada 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 a prompt diretamente para o modelo sem nenhuma transformação.

Resposta de conclusão

Campo Tipo Descrição
id String Identificador exclusivo para conclusão de texto.
choices CompletionChoice Lista de preenchimentos de texto. Para cada prompt passado, n opções serão geradas se n for especificado. O n padrão é 1.
object String O tipo de objeto. Igual a "text_completion"
created Integer O tempo em que a conclusão foi gerada, em segundos.
usage Uso Metadados de uso de token.

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.

Integração de tarefa

As tarefas de inserção mapeiam as cadeias de caracteres de entrada nos vetores de inserção. Muitas entradas podem ser agrupadas em lote em cada solicitação. Confira POST /serving-endpoints/{name}/invocações para consultar parâmetros de ponto de extremidade.

Solicitação de incorporação

Campo Tipo Descrição
input Cadeia de caracteres ou List[String] Obrigatório. O texto de entrada a ser inserido. Pode ser uma cadeia de caracteres ou uma lista de cadeias de caracteres.
instruction String Uma instrução opcional para passar para o modelo de inserçã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 partes e recomendam usar a instrução "Represent this sentence for searching relevant passages:" para consultas de recuperação. Outros modelos como Instructor-XL dão suporte a uma ampla gama de cadeias de caracteres de instrução.

Resposta de inserções

Campo Tipo Descrição
id String Identificador exclusivo da inserção.
object String O tipo de objeto. Igual a "list".
model String O nome do modelo de inserção usado para criar a inserção.
data EmbeddingObject O objeto de inserção.
usage Uso Metadados de uso de token.

EmbeddingObject

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

Recursos adicionais