Compartilhar via

Referência da API REST do modelo de base

  • Artigo

Este artigo fornece informações gerais de API para APIs do Databricks Foundation Model e os modelos suportados. As APIs do Foundation Model são projetadas para serem semelhantes à API REST da OpenAI para facilitar a migração de projetos existentes. Tanto a cobrança por token quanto os pontos de extremidade provisionados aceitam o mesmo formato de solicitação de API REST.

Pontos de extremidade

As APIs do Modelo de Base suportam interfaces de pagamento por uso de token e interfaces de largura de banda provisionada.

Um ponto de extremidade pré-configurado está disponível em seu espaço de trabalho para cada modelo suportado de pagamento por token, e os usuários podem interagir com esses pontos de extremidade usando solicitações HTTP POST. Consulte a secção Pagamento por token para obter os modelos suportados.

Os pontos de extremidade para taxa de transferência provisionada podem ser criados usando a API ou a interface de utilização do serviço. Esses endpoints suportam múltiplos modelos por endereço para testes A/B, desde que os dois 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 obter os parâmetros de configuração do ponto final.

Solicitações e respostas utilizam JSON, e a estrutura exata do JSON depende do tipo de tarefa do endpoint. Os endpoints de bate-papo e conclusão suportam respostas em fluxo contínuo.

Utilização

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 tarefas.

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

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 endpoints cobrados por token, 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 em vários turnos com um modelo. A resposta do modelo fornece a próxima mensagem assistant na conversa. Consulte POST /serving-endpoints/{name}/invocations para consultar os parâmetros do ponto de extremidade.

Pedido de chat

Campo Padrão Tipo Descrição
messages ChatMessage lista Obrigatório. Uma lista de mensagens que representam a conversa atual.
max_tokens null null, o que significa ausência de limite, ou um número inteiro maior que zero O número máximo de tokens a serem gerados.
stream true Booleano Transmita 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 eventos enviados pelo servidor padrão.
temperature 1.0 Valor flutuante 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 limiar de probabilidade utilizado para a amostragem do núcleo.
top_k null null, o que significa ausência de limite, ou um número inteiro maior que zero 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 [] String ou List[String] O modelo para de gerar mais tokens quando qualquer uma das sequências em stop é encontrada.
n 1 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 finalizaçõ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 provisionados.
tool_choice none String ou ToolChoiceObject Usado apenas em conjunto com o campo tools. tool_choice suporta uma variedade de cadeias de caracteres de palavras-chave, como auto, requirede none. auto significa que você está deixando o modelo decidir qual (se houver) ferramenta é relevante usar. 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. Por padrão, se o campo tools estiver preenchido tool_choice = "auto". Caso contrário, o campo tools assume como padrão tool_choice = "none"
tools null ObjetoDeFerramenta Uma lista de tools que o modelo pode chamar. Atualmente, function é o único tipo de tool suportado e um máximo de 32 funções são suportadas.
response_format null ObjetoDeFormatoDeResposta Um objeto que especifica o formato que o modelo deve produzir. Os tipos aceites 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.

A configuração 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 Booleano Este parâmetro indica se deve fornecer a probabilidade em log de um token ser selecionado.
top_logprobs null Inteiro Este parâmetro controla o número de candidatos a token mais prováveis para os quais se devem retornar as probabilidades logarítmicas em cada etapa de amostragem. Pode ser 0-20. logprobs deve ser true se utilizar este campo.

ChatMessage

Campo Tipo Descrição
role Cadeia Obrigatório. O papel do autor da mensagem. Pode ser "system", "user", "assistant" ou "tool".
content Cadeia O conteúdo da mensagem. Obrigató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 Cadeia Quando role é "tool", o ID associado ao ToolCall a que a mensagem responde. 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 de sistema padrão do modelo.

ToolCall

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

Campo Tipo Descrição
id Cadeia Obrigatório. Um identificador exclusivo para esta sugestão de chamada de ferramenta.
type Cadeia Obrigatório. Apenas "function" é suportado.
function ConclusãoDeChamadaDeFunção Obrigatório. Uma invocação de função sugerida pelo modelo.

FunctionCallCompletion

Campo Tipo Descrição
name Cadeia 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 no Azure Databricks.

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

ToolObject

Consulte Chamada de função no Azure Databricks.

Campo Tipo Descrição
type Cadeia Obrigatório. O tipo da ferramenta. Atualmente, apenas function é suportado.
function FunctionObject Obrigatório. A definição de função associada à ferramenta.

FunctionObject

Campo Tipo Descrição
name Cadeia 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 esquema JSON válido objeto. Se a ferramenta for chamada, a chamada de ferramenta será ajustada ao esquema JSON fornecido. Omitir parâmetros define uma função sem quaisquer parâmetros. O número de properties é limitado a 15 chaves.
strict Booleano Se a adesão estrita ao esquema deve ser ativada ao gerar a chamada de função. Se definido como true, o modelo segue o esquema exato definido no campo de esquema. Somente um subconjunto do esquema JSON é suportado quando strict é true

ResponseFormatObject

Consulte Saídas estruturadas no Azure Databricks.

Campo Tipo Descrição
type Cadeia 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 aderentes a um esquema específico.
json_schema JsonSchemaObject Obrigatório. O esquema JSON a ser aderido se type estiver definido como json_schema

JsonSchemaObject

Consulte Saídas estruturadas no Azure Databricks.

Campo Tipo Descrição
name Cadeia Obrigatório. O nome do formato de resposta.
description Cadeia Uma descrição do propósito do formato de resposta, utilizada pelo modelo para determinar como responder nesse formato.
schema Objeto Obrigatório. O esquema para o formato de resposta, descrito como um objeto de esquema JSON.
strict Booleano Se a adesão estrita ao esquema deve ser habilitada ao gerar a saída. Se definido como true, o modelo segue o esquema exato definido no campo de esquema. Somente um subconjunto do esquema JSON é suportado quando strict é true

Resposta do 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 bloco de conclusão. A estrutura de nível superior de conclusão e fragmentação de objetos é quase idêntica: apenas choices tem um tipo diferente.

Campo Tipo Descrição
id Cadeia Identificador exclusivo para a conclusão do chat.
choices List[ChatCompletionChoice] ou List[ChatCompletionChunk] (streaming) Lista de textos de conclusão de chat. n opções são retornadas se o parâmetro n for especificado.
object Cadeia O tipo de objeto. Igual a "chat.completions" para não-transmissão ou "chat.completion.chunk" para transmissão.
created Inteiro O tempo de conclusão do chat foi gerado em segundos.
model Cadeia A versão do modelo usada para gerar a resposta.
usage Utilização Metadados de uso de token. Pode não estar presente nas respostas de streaming.

ChatCompletionChoice

Campo Tipo Descrição
index Inteiro O índice da escolha na lista de opções geradas.
message ChatMessage Uma mensagem de conclusão de chat retornada pelo modelo. O papel será assistant.
finish_reason Cadeia A razão pela 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 ChatMessage Uma mensagem de conclusão de bate-papo faz parte das respostas transmitidas geradas pelo modelo. Apenas o primeiro pedaço tem a garantia de ter role preenchido.
finish_reason Cadeia A razão pela qual o modelo parou de gerar tokens. Apenas o último bloco terá estes dados preenchidos.

Tarefa de conclusão

As tarefas de conclusão de texto são para gerar respostas a um único prompt. Ao contrário do Chat, esta tarefa suporta 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 ponto de extremidade.

Pedido de conclusão

Campo Padrão Tipo Descrição
prompt String ou List[String] Obrigatório. As sugestões para o modelo.
max_tokens null null, o que significa ausência de limite, ou um número inteiro maior que zero O número máximo de tokens a serem gerados.
stream true Booleano Transmita 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 eventos enviados pelo servidor padrão.
temperature 1.0 Valor flutuante 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 limiar de probabilidade utilizado para a amostragem do núcleo.
top_k null null, o que significa ausência de limite, ou um número inteiro maior que zero 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 de espera e erros de comprimento de contexto excedido. Um de: "truncate" (retornar o maior número possível de tokens) e "error" (retornar um erro). Esse parâmetro só é aceite por endpoints de pagamento por token.
n 1 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 finalizaçõ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 provisionados.
stop [] String ou List[String] O modelo para de gerar mais tokens quando qualquer uma das sequências em stop é encontrada.
suffix "" Cadeia Uma cadeia de caracteres que é acrescentada ao final de cada conclusão.
echo false Booleano Retorna o comando juntamente com a conclusão.
use_raw_prompt false Booleano Se true, passe o prompt diretamente para o modelo, sem qualquer transformação.

Resposta de conclusão

Campo Tipo Descrição
id Cadeia Identificador exclusivo para completar o texto.
choices Escolha de Conclusão Uma lista de finalizações de texto. Para cada prompt fornecido, n escolhas são geradas se n estiver especificado. O n padrão é 1.
object Cadeia O tipo de objeto. Igual a "text_completion"
created Inteiro O tempo em que a conclusão foi gerada em segundos.
usage Utilização Metadados de uso de token.

CompletionChoice

Campo Tipo Descrição
index Inteiro O índice do prompt na solicitação.
text Cadeia A conclusão gerada.
finish_reason Cadeia A razão pela qual o modelo parou de gerar tokens.

Tarefa de incorporação

As tarefas de incorporação mapeiam cadeias de caracteres de entrada em vetores de incorporação. Muitas entradas podem ser agrupadas em lote em cada solicitação. Consulte POST /serving-endpoints/{name}/invocations para consultar os parâmetros do ponto de extremidade.

Pedido de incorporação

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

As instruções são opcionais e altamente específicas do modelo. Por exemplo, os autores do BGE recomendam não dar 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 Instructor-XL suportam uma ampla gama de cadeias de instruções.

Incorpora resposta

Campo Tipo Descrição
id Cadeia Identificador único para a incorporação.
object Cadeia O tipo de objeto. Igual a "list".
model Cadeia O nome do modelo de incorporação usado para criar a incorporação.
data EmbeddingObject O objeto de incorporação.
usage Utilização Metadados de uso de token.

EmbeddingObject

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

Recursos adicionais