Partilhar 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

Cada modelo de pagamento por token tem um único ponto de extremidade, e os usuários podem interagir com esses pontos de extremidade usando solicitações HTTP POST. 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 pontos de extremidade também oferecem 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 sobre a configuração do endpoint parameters.

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.

As cargas de trabalho de pagamento por token suportam certos modelos. Consulte Modelos suportados para pagamento por token para obter informações sobre os modelos e os formatos de API aceites.

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 llama-2-70b-chat 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 consulta ao endpoint parameters.

Pedido de chat

Campo Padrão Tipo Descrição
messages list ChatMessage Obrigatório. Um conjunto list de mensagens que representam a conversa atual.
max_tokens null null, o que significa ausência de limit, ou um número inteiro maior que zero O número máximo de tokens até generate.
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 maior values introduz 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 limit, 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. Set esse valor para 1 para tornar os resultados determinísticos.
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 generate 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 generate efetuar uma chamada de ferramenta. none significa que o modelo não generate nenhuma chamada de ferramenta e, em vez disso, deve generate 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 Um list 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, o que garante que o modelo siga o JSON fornecido schema.

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 schemaespecí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 String O conteúdo da mensagem. Obrigatório para tarefas de chat que não envolvam chamadas de ferramentas.
tool_calls ToolCalllist A list 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 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 String Obrigatório. Uma identifier única para esta sugestão de chamada de ferramenta.
type String 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 Corda 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 Corda 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"}}where"my_function é o nome de um FunctionObject no campo tools.

ToolObject

Consulte Chamada de função no Azure Databricks.

Campo Tipo Descrição
type String 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 Corda / 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 generate as chamadas da ferramenta com maior precisão.
parameters Objeto A função aceita o parameters, descrito como um objeto JSON schema válido. Se a ferramenta for chamada, a chamada de ferramenta será adequada ao JSON schema fornecido. O facto de omitir parameters define uma função sem qualquer parameters. O número de properties é limitado a 15 chaves.
strict Booleano Se a adesão estrita ao schema deve ser ativada ao gerar a chamada de função. Se set a true, o modelo segue exatamente o schema definido no campo schema. Somente um subconjunto de JSON schema é suportado quando strict é true

ResponseFormatObject

Consulte Saídas estruturadas no Azure Databricks.

Campo Tipo Descrição
type Corda 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 schemaespecífico.
json_schema JsonSchemaObject Obrigatório. O JSON schema a seguir se type for set até json_schema

JsonSchemaObject

Consulte 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 do propósito do formato de resposta, utilizada pelo modelo para determinar como responder nesse formato.
schema Objeto Obrigatório. O schema para o formato de resposta, descrito como um objeto JSON schema.
strict Booleano Deve-se habilitar a adesão estrita schema ao gerar a saída? Se set a true, o modelo segue exatamente o schema definido no campo schema. Somente um subconjunto do JSON schema é 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 é uma text/event-streamwhere, e 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 String Único identifier para a conclusão do chat.
choices List[ChatCompletionChoice] ou List[ChatCompletionChunk] (transmissão) List de textos de conclusão de chat. n opções 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 de conclusão do chat foi gerado em segundos.
model String A versão do modelo usada para generate 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 no list de escolhas geradas.
message ChatMessage Uma mensagem de conclusão de chat retornada pelo modelo. O papel será assistant.
finish_reason String A razão pela qual o modelo parou de gerar tokens.

ChatCompletionChunk

Campo Tipo Descrição
index Inteiro O índice da escolha no list de escolhas 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 String 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. Veja POST /serving-endpoints/{name}/invocations para consultar o endpoint parameters.

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 limit, ou um número inteiro maior que zero O número máximo de tokens para generate.
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 Flutuar em [0,2] A temperatura de amostragem. 0 é determinístico e maior values introduz 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 limit, ou um número inteiro maior que zero Define o número de tokens k mais prováveis usados na filtragem top-k. Set esse valor para 1 para tornar os resultados determinísticos.
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 generate várias finalizações na mesma entrada para eficiência de inferência adicional e economia de custos. Apenas disponível para pontos de extremidade de taxa de transferência provisionada.
stop [] String ou List[String] O modelo para de gerar mais tokens quando qualquer uma das sequências em stop é encontrada.
suffix "" String 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 Exclusivo identifier para a conclusão do texto.
choices Escolha de Conclusão Uma list de finalizações de texto. Para cada prompt fornecido, n escolhas são geradas se n estiver especificado. O n padrão é 1.
object Corda 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 String A conclusão gerada.
finish_reason Corda 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 fazer a consulta do endpoint parameters.

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 um list de cadeias de caracteres.
instruction String 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 String Identificador único identifier para a integração.
object Cadeia O tipo de objeto. Igual a "list".
model String 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 String O tipo de objeto. Igual a "embedding".
index Inteiro O índice da incorporação na list de incorporações geradas pelo modelo.
embedding List[Flutuar] O vetor de incorporação. Cada modelo retornará um vetor de tamanho fixo (1024 para BGE-Large)

Recursos adicionais