Compartilhar via

Referência da API REST de foundation model

  • Artigo

Este artigo fornece informações gerais de API para APIs de modelo de base e os modelos aos quais elas dão suporte. As APIs do Modelo de Fundação foram projetadas de modo semelhante à API REST da 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

Cada modelo de pagamento por token tem apenas um ponto de extremidade. 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 dão suporte para vários modelos por ponto de extremidade para testes A/B, desde que ambos os modelos fornecidos exponham o mesmo formato de API. Por exemplo, ambos os modelos são modelos de chat.

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

Cargas de trabalho pagas por token dão suporte a determinados modelos. Consulte Modelos com suporte para pagamento por token para conhecer esses modelos e os formatos de API aceitos.

Uso

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

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

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 ponto de extremidades de pagamento por token, um prompt do sistema também pode ser adicionado. prompt_tokens inclui todo o texto adicionado pelo nosso servidor.

Tarefa de chats

As tarefas de chats são otimizadas para conversas com várias rodadas com um modelo. Cada solicitação descreve a conversa até o momento, em que o campo messages deve alternar entre as funções user e assistant, terminando com uma mensagem user. A resposta do modelo fornece a próxima mensagem assistant na conversa.

Solicitação de chats

Campo Padrão Digite Descrição
messages Lista ChatMessage Obrigatório. Uma lista de mensagens que representam a conversa atual.
max_tokens null null, o que significa nenhum limite ou um número inteiro maior que zero O número máximo de tokens a serem gerados.
stream true Booliano Transmite 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 Eventos Enviados pelo Servidor.
temperature 1.0 Float em [0,2] A temperatura de amostragem. 0 é determinístico e valores mais altos apresentam 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 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 mais tokens quando qualquer uma das sequências em 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ários preenchimentos 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 apenas em conjunto com o campo tools. tool_choice suporta uma variedade de strings de palavras-chave, como auto, required e 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 acreditar 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 será padronizado como 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 no 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": {...} } habilitar saídas estruturadas, o que garante 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 Booliano Esse parâmetro indica se a probabilidade logarítmica de uma amostragem de token ocorrer.
top_logprobs null Inteiro Esse parâmetro controla o número de candidatos a token mais prováveis para retornar probabilidades logarítmicas em cada etapa de amostragem. Ele pode estar entre 0 a 20. logprobs deve ser true se estiver usando este campo.

ChatMessage

Campo Type Descrição
role Cadeia de caracteres 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 de conteúdo 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. Consulte Chamada de função no Azure Databricks.

Campo Type Descrição
id Cadeia de caracteres Obrigatório. Um identificador exclusivo para essa sugestão de chamada de ferramenta.
type String Obrigatório. Apenas "function" tem suporte.
function FunctionCallCompletion Obrigatório. Uma chamada de função sugerida pelo modelo.

FunctionCallCompletion

Campo Type Descrição
name Cadeia de caracteres Obrigatória. O nome da função que o modelo recomendou.
arguments Objeto Obrigatória. Argumentos para a função como um dicionário JSON serializado.

ToolChoiceObject

Consulte Chamada de função no Azure Databricks.

Campo Type Descrição
type Cadeia de caracteres 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

Consulte Chamada de função no Azure Databricks.

Campo Type Descrição
type Cadeia de caracteres 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 Type Descrição
name Cadeia de caracteres Obrigatório. O nome da função que será chamada.
description Objeto Obrigatório. A descrição detalhada da função. O modelo usa essa descrição para reconhecer 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á ajustada ao esquema JSON fornecido. A omissão de parâmetros define uma função sem parâmetros. O número de properties é limitado a 15 teclas.
strict Booliano 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 do esquema JSON quando strict é true

ResponseFormatObject

Confira Saídas estruturadas no Azure Databricks.

Campo Type Descrição
type Cadeia de caracteres Obrigató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 que aderem a um esquema específico.
json_schema JsonSchemaObject Obrigatório. O esquema JSON a ser seguido por if type está definido como json_schema

JsonSchemaObject

Confira Saídas estruturadas no Azure Databricks.

Campo Type Descrição
name Cadeia de caracteres Obrigató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 Objeto Obrigatório. O esquema para o formato de resposta, descrito como um objeto de esquema JSON.
strict Booliano 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 do esquema JSON 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 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 Type Descrição
id Cadeia de caracteres Identificador exclusivo para conclusão de chat.
choices List[ChatCompletionChoice] ou List[ChatCompletionChunk] (streaming) Uma lista de textos de preenchimento de 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 streaming ou "chat.completion.chunk" para streaming.
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 de token. Pode não estar presente em respostas de streaming.

ChatCompletionChoice

Campo Type Descrição
index Inteiro O índice de 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 Type Descrição
index Inteiro O índice de escolha na lista de opções geradas.
delta ChatMessage 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á esse campo preenchido.

Tarefa de conclusão

As tarefas de conclusão de texto servem para gerar respostas a um único prompt. Ao contrário do Chat, essa tarefa tem suporte para entradas em lote: vários prompts independentes podem ser enviados em uma única solicitação.

Solicitação de conclusão

Campo Padrão Digite Descrição
prompt Cadeia de caracteres ou List[String] Obrigatório. O(s) prompt(s) do modelo.
max_tokens null null, o que significa nenhum limite ou um número inteiro maior que zero O número máximo de tokens a serem gerados.
stream true Booliano Transmite 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 Eventos Enviados pelo Servidor.
temperature 1.0 Float em [0,2] A temperatura de amostragem. 0 é determinístico e valores mais altos apresentam 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 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.
error_behavior "error" "truncate" ou "error" Para tempos limite e erros de tamanho de contexto excedidos. Uma das opções: "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 preenchimentos de chat independentes quando n é especificado. Recomendado para cargas de trabalho que geram vários preenchimentos 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 mais tokens quando qualquer uma das sequências em 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 o prompt diretamente para o modelo sem nenhuma transformação.

Resposta de conclusão

Campo Type Descrição
id Cadeia de caracteres 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 Inteiro O tempo em que a conclusão foi gerada, em segundos.
usage Uso Metadados de uso de token.

CompletionChoice

Campo Type 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.

Tarefa de inserção

As tarefas de inserção mapeiam as cadeias de caracteres de entrada nos vetores de inserção. Muitas entradas podem ser colocadas em lote em cada solicitação.

Solicitação de inserção

Campo Type 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 a ser passada para o modelo de inserção.

As instruções são opcionais e altamente específicas para cada modelo. Por exemplo, os criadores do BGE não recomendam nenhuma instrução ao indexar divisões em partes 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, dão suporte para um amplo intervalo de cadeias de caracteres de instrução.

Resposta de inserções

Campo Type Descrição
id Cadeia de caracteres 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 Type Descrição
object Cadeia de caracteres O tipo de objeto. Igual a "embedding".
index Inteiro O índice da inserção na lista de inserções geradas pelo modelo.
embedding List[Float] O vetor de inserção. Cada modelo retornará um vetor de tamanho fixo (1024 para BGE-Large)

Recursos adicionais