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 o pagamento por token quanto os pontos de extremidade de taxa de transferência provisionados aceitam o mesmo formato de solicitação de API REST.

Parâmetros de avaliação

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 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 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 para obter os parâmetros de configuração do ponto final .

Solicitações e respostas usam JSON, a estrutura JSON exata depende do tipo de tarefa de um ponto de extremidade. Os endpoints de bate-papo e conclusão suportam respostas de streaming.

As cargas de trabalho de pagamento por token suportam determinados modelos, consulte Modelos suportados para pagamento por token para esses modelos e formatos de API aceitos.

Utilização

As respostas incluem uma usage submensagem 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 Description
completion_tokens Número inteiro Número de tokens gerados. Não incluído nas respostas incorporadas.
prompt_tokens Número inteiro Número de tokens do(s) prompt(s) de entrada.
total_tokens Número 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 pontos de extremidade pay-per-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. Cada solicitação descreve a conversa até agora, onde o messages campo deve alternar entre user e assistant funções, terminando com uma user mensagem. A resposta do modelo fornece a próxima assistant mensagem na conversa. Consulte POST /serving-endpoints/{name}/invocations para consultar os parâmetros do endpoint.

Pedido de chat

Campo Predefinido Tipo Description
messages Lista de ChatMessage Necessá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 superior a 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 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 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 superior a 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 é stop encontrada.
n 1 Inteiro maior que zero A API retorna n conclusões de bate-papo independentes quando n é especificada. 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 tools campo. tool_choice suporta uma variedade de cadeias de palavras-chave, como auto, requirede none. auto significa que você está deixando o modelo decidir qual (se houver) ferramenta é relevante usar. Se auto o modelo não acredita que nenhuma das ferramentas em tools são relevantes, 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 e tools 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 a chamada de uma ferramenta específica definida em tools, utilize um ToolChoiceObject. Por padrão, se o campo estiver preenchido toolstool_choice = "auto". Caso contrário, o tools campo assume como padrão tool_choice = "none"
tools null ObjetoFerramenta Uma lista do tools que o modelo pode chamar. Atualmente, function é o único tipo suportado tool e um máximo de 32 funções são suportadas.
response_format null ResponseFormatObject Um objeto que especifica o formato que o modelo deve produzir. Os tipos aceites são text, json_schema ou json_object

Configuração para { "type": "json_schema", "json_schema": {...} } permitir saídas estruturadas que garantem que o modelo siga o esquema JSON fornecido.

A configuração para { "type": "json_object" } garantir 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 Este parâmetro indica se deve fornecer a probabilidade de log de um token ser amostrado.
top_logprobs null Número inteiro Este parâmetro controla o número de candidatos de token mais prováveis para retornar probabilidades de log para cada etapa de amostragem. Pode ser 0-20. logprobs deve ser true se usar este campo.

ChatMessage

Campo Tipo Description
role String Necessá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 envolvem chamadas de ferramentas.
tool_calls Lista ToolCall A lista do tool_calls que o modelo gerou. Deve ter role como "assistant" e nenhuma especificação para o content campo.
tool_call_id String Quando role é "tool", o ID associado ao ToolCall qual a mensagem está respondendo. Deve estar vazio para outras role opções.

A system função 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 de chamada de ferramenta pelo modelo. Consulte Chamada de função no Azure Databricks.

Campo Tipo Description
id String Necessário. Um identificador exclusivo para esta sugestão de chamada de ferramenta.
type String Necessário. Só o "function" é suportado.
function FunctionCallCompletion Necessário. Uma chamada de função sugerida pelo modelo.

FunctionCallCompletion

Campo Tipo Description
name String Obrigatório. O nome da função recomendada pelo modelo.
arguments Object Obrigatório. Argumentos para a função como um dicionário JSON serializado.

ToolChoiceObject

Consulte Chamada de função no Azure Databricks.

Campo Tipo Description
type String Necessário. O tipo da ferramenta. Atualmente, apenas "function" é suportado.
function Object Necessá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 tools campo.

ToolObject

Consulte Chamada de função no Azure Databricks.

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

FunctionObject

Campo Tipo Description
name String Necessário. O nome da função a ser chamada.
description Object 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 da ferramenta com maior precisão.
parameters Object 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á 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 Boolean 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 Description
type String Necessário. O tipo de formato de resposta que está sendo definido. Para text 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 Necessário. O esquema JSON ao qual aderir se type está definido como json_schema

JsonSchemaObject

Consulte Saídas estruturadas no Azure Databricks.

Campo Tipo Description
name String Necessário. O nome do formato de resposta.
description String Uma descrição do formato de resposta, usado pelo modelo para determinar como responder no formato.
schema Object Necessário. O esquema para o formato de resposta, descrito como um objeto de esquema JSON.
strict Boolean 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 é uma 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: só choices tem um tipo diferente.

Campo Tipo Description
id String Identificador exclusivo para a conclusão do chat.
choices List[ChatCompletionChoice] ou List[ChatCompletionChunk] (streaming) Lista de textos de conclusão de chat. n As opções são retornadas se o n parâmetro for especificado.
object String O tipo de objeto. Igual a não "chat.completions" streaming ou "chat.completion.chunk" para streaming.
created Número inteiro O tempo de conclusão do chat foi gerado em segundos.
model String 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 Description
index Número inteiro O índice da escolha na lista de opções geradas.
message ChatMensagem 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 Description
index Número inteiro O índice da escolha na lista de opções geradas.
delta ChatMensagem Uma mensagem de conclusão de bate-papo faz parte das respostas transmitidas geradas pelo modelo. Apenas o primeiro pedaço é garantido ter role preenchido.
finish_reason String A razão pela qual o modelo parou de gerar tokens. Apenas o último pedaço terá isso preenchido.

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 verificar os parâmetros do ponto de extremidade.

Pedido de conclusão

Campo Predefinido Tipo Description
prompt String ou List[String] Necessário. As sugestões para o modelo.
max_tokens null null, o que significa ausência de limite, ou um número inteiro superior a 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 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 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 superior a 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 limite e erros de comprimento de contexto excedido. Um dos: "truncate" (retorna o maior número possível de tokens) e "error" (retorna 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 conclusões de bate-papo independentes quando n é especificada. 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 é stop encontrada.
suffix "" String Uma cadeia de caracteres que é 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 o prompt diretamente para o modelo sem qualquer transformação.

Resposta de conclusão

Campo Tipo Description
id String Identificador exclusivo para a conclusão do texto.
choices ConclusãoEscolha Uma lista de finalizações de texto. Para cada prompt passado, n as opções são geradas se n for especificado. O padrão n é 1.
object String O tipo de objeto. Igual a "text_completion"
created Número inteiro O tempo em que a conclusão foi gerada em segundos.
usage Utilização Metadados de uso de token.

CompletionChoice

Campo Tipo Description
index Número inteiro O índice do prompt na solicitação.
text String A conclusão gerada.
finish_reason String 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 parâmetros de ponto de extremidade.

Pedido de incorporação

Campo Tipo Description
input String ou List[String] Necessário. O texto de entrada a ser incorporado. 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 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 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 gama de cadeias de instruções.

Incorpora resposta

Campo Tipo Description
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 EmbeddingObject O objeto de incorporação.
usage Utilização Metadados de uso de token.

EmbeddingObject

Campo Tipo Description
object String O tipo de objeto. Igual a "embedding".
index Número 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