Referencia de las API REST de Foundation Model

  • Artículo

En este artículo se proporciona información general de API para las API de Databricks Foundation Model y los modelos que admiten. Las API de Foundation Model están diseñadas para ser similares a la API REST de OpenAI para facilitar la migración de proyectos existentes. Los puntos de conexión de rendimiento de pago por token y aprovisionados aceptan el mismo formato de solicitud de API de REST.

Extremos

Cada modelo de pago por token tiene un único punto de conexión y los usuarios pueden interactuar con estos puntos de conexión mediante solicitudes HTTP POST. Los puntos de conexión de rendimiento aprovisionados se pueden crear mediante la API o la interfaz de usuario de servicio. Estos puntos de conexión también admiten varios modelos por punto de conexión para las pruebas A/B, siempre y cuando ambos modelos servidos expongan el mismo formato de API. Por ejemplo, ambos modelos son modelos de chat.

Las solicitudes y respuestas usan JSON, la estructura JSON exacta depende del tipo de tarea de un punto de conexión. Los puntos de conexión de chat y finalización admiten respuestas de streaming.

Las cargas de trabajo de pago por token admiten determinados modelos; consulte Modelos admitidos para el pago por token para obtener información sobre esos modelos y los formatos de API aceptados.

Uso

Las respuestas incluyen un usage sub-mensaje que informa del número de tokens en la solicitud y la respuesta. El formato de este submensaje es el mismo en todos los tipos de tareas.

Campo Tipo Descripción
completion_tokens Entero Número de tokens generados. No se incluye en las respuestas de inserción.
prompt_tokens Entero Número de tokens del símbolo del sistema de entrada.
total_tokens Entero Número de tokens totales.

Para los modelos como llama-2-70b-chat una solicitud de usuario se transforma mediante una plantilla de aviso antes de pasarse al modelo. En el caso de los puntos de conexión de pago por token, también se puede agregar un símbolo del sistema. prompt_tokens incluye todo el texto agregado por nuestro servidor.

Tarea chat

Las tareas de chat están optimizadas para conversaciones multiturno con un modelo. Cada solicitud describe la conversación hasta ahora, donde el campo messages debe alternar entre los roles user y assistant, finalizando con un mensaje user. La respuesta del modelo proporciona el siguiente assistant mensaje en la conversación.

Solicitud de chat

Campo Valor predeterminado Tipo Descripción
messages Lista ChatMessage Necesario. Lista de mensajes que representan la conversación actual.
max_tokens null null, lo que significa que no hay límite o un entero mayor que cero. Número máximo de tokens que se van a generar.
stream true Booleano Transmita las respuestas a un cliente para permitir resultados parciales para las solicitudes. Si este parámetro se incluye en la solicitud, las respuestas se envían mediante el estándar de eventos enviados por el servidor.
temperature 1.0 Flotar en [0,2] Temperatura de muestreo. 0 es determinista y los valores superiores introducen más aleatoriedad.
top_p 1.0 Flotar en (0,1] Umbral de probabilidad utilizado para el muestreo de núcleos.
top_k null null, lo que significa que no hay límite o un entero mayor que cero. Define el número de tokens más probables que se usen para el filtrado top-k. Establezca este valor en 1 para que las salidas sean deterministas.
stop [] Cadena o Lista[String] El modelo deja de generar más tokens cuando se encuentra cualquiera de las secuencias de stop.
n 1 Entero mayor que 0 La API devuelve n finalizaciones de chat independientes cuando se especifica n. Se recomienda para cargas de trabajo que generen varias finalizaciones en la misma entrada para obtener una eficiencia de inferencia adicional y un ahorro de costes. Solo está disponible para los puntos de conexión de rendimiento aprovisionados.
tool_choice none Cadena o ToolChoiceObject Solo se usa junto con el campo tools. tool_choice admite una variedad de cadenas de palabras clave, como auto, required y none. auto significa que va a permitir que el modelo decida qué herramienta (si la hubiera) es relevante para su uso. Con auto si el modelo no cree que ninguna de las herramientas de tools son relevantes, el modelo genera un mensaje de asistente estándar en lugar de una llamada a una herramienta. required significa que el modelo elige la herramienta más relevante en tools y debe generar una llamada a una herramienta. none significa que el modelo no genera ninguna llamada a una herramienta y, en su lugar, debe generar un mensaje de asistente estándar. Para forzar una llamada a una herramienta con una herramienta específica definida en tools, use un ToolChoiceObject. De manera predeterminada, si el campo tools se rellena tool_choice = "auto". En caso contrario, el campo tools tiene como valor predeterminado tool_choice = "none"
tools null ToolObject Lista de tools que el modelo puede llamar. Actualmente, function es el único tipo tool admitido y se admite un máximo de 32 funciones.
response_format null ResponseFormatObject Objeto que especifica el formato que debe generar el modelo. Los tipos aceptados son text, json_schema o json_object

Al establecer en { "type": "json_schema", "json_schema": {...} } se habilitan salidas estructuradas que garantizan que el modelo sigue el esquema JSON proporcionado.

Establecer en { "type": "json_object" } garantiza que las respuestas que genera el modelo son JSON válidas, pero no garantiza que las respuestas sigan un esquema específico.
logprobs false Booleano Este parámetro indica si se debe proporcionar la probabilidad de registro de un token que se muestrea.
top_logprobs null Entero Este parámetro controla el número de candidatos de token más probables para devolver probabilidades de registro en cada paso de muestreo. Puede ser de 0 a 20. logprobs debe ser true si se usa este campo.

ChatMessage

Campo Tipo Description
role String Necesario. Rol del autor del mensaje. Puede ser "system", "user", "assistant" o "tool".
content Cadena Contenido del mensaje. Necesario para las tareas de chat que no implican llamadas a una herramienta.
tool_calls Lista de ToolCall Lista de tool_calls que generó el modelo. Debe tener role como "assistant" y ninguna especificación para el campo content.
tool_call_id Cadena Cuando role es "tool", el identificador asociado al ToolCall al que responde el mensaje. Debe estar vacío para otras opciones role.

El system rol solo se puede usar una vez, como primer mensaje de una conversación. Invalida el símbolo del sistema predeterminado del modelo.

ToolCall

Sugerencia de acción de llamada a una herramienta por el modelo. Consulte Llamada a funciones en Azure Databricks.

Campo Tipo Description
id String Necesario. Identificador único para esta sugerencia de llamada a una herramienta.
type Cadena Necesario. Solo se admite "function".
function FunctionCallCompletion Necesario. Una llamada a una función sugerida por el modelo.

FunctionCallCompletion

Campo Tipo Description
name String Necesario. Nombre de la función recomendada por el modelo.
arguments Object Necesario. Argumentos para la función como un diccionario JSON serializado.

ToolChoiceObject

Consulte Llamada a funciones en Azure Databricks.

Campo Tipo Description
type String Necesario. El tipo de la herramienta. Actualmente, solo se admite "function".
function Object Necesario. Objeto que define qué herramienta llamar del formulario {"type": "function", "function": {"name": "my_function"}} donde "my_function es el nombre de un FunctionObject en el campo tools.

ToolObject

Consulte Llamada a funciones en Azure Databricks.

Campo Tipo Description
type String Necesario. El tipo de la herramienta. Actualmente, solo se admite function.
function FunctionObject Necesario. Definición de función asociada a la herramienta.

FunctionObject

Campo Tipo Description
name String Necesario. El nombre de la función que se llamará.
description Object Necesario. Descripción detallada de la función. El modelo usa esta descripción para comprender la relevancia de la función en el símbolo del sistema y generar las llamadas a la herramienta con mayor precisión.
parameters Object Los parámetros que acepta la función, que se describen como un objeto de esquema JSON válido. Si se llama a la herramienta, la llamada a la herramienta se ajusta al esquema JSON proporcionado. La omisión de parámetros define una función sin parámetros. El número de properties está limitado a 15 claves.
strict Booleano Indica si se debe habilitar el cumplimiento estricto del esquema al generar la llamada a la función. Si se establece trueen , el modelo sigue el esquema exacto definido en el campo de esquema. Solo se admite un subconjunto del esquema JSON cuando es estricto true

ResponseFormatObject

Consulte Salidas estructuradas en Azure Databricks.

Campo Tipo Description
type String Necesario. Tipo de formato de respuesta que se va a definir. Ya sea text para texto no estructurado, json_object para objetos JSON no estructurados o json_schema para objetos JSON que se adhieren a un esquema específico.
json_schema JsonSchemaObject Necesario. Esquema JSON al que se va a cumplir si type está establecido en json_schema

JsonSchemaObject

Consulte Salidas estructuradas en Azure Databricks.

Campo Tipo Description
name String Necesario. Nombre del formato de respuesta.
description Cadena Descripción del formato de respuesta que usa el modelo para determinar cómo responder en el formato.
schema Object Necesario. Esquema para el formato de respuesta, descrito como un objeto de esquema JSON.
strict Booleano Indica si se debe habilitar el cumplimiento estricto del esquema al generar la respuesta. Si se establece trueen , el modelo sigue el esquema exacto definido en el campo de esquema. Solo se admite un subconjunto del esquema JSON cuando es estricto true

Respuesta de chat

En el caso de las solicitudes que no son de streaming, la respuesta es un único objeto de finalización de chat. En el caso de las solicitudes de streaming, la respuesta es un text/event-stream objeto donde cada evento es un objeto de fragmento de finalización. La estructura de nivel superior de los objetos de finalización y fragmento es casi idéntica: solo choices tiene un tipo diferente.

Campo Tipo Description
id String Identificador único para la finalización del chat.
choices List[ChatCompletionChoice] o List[ChatCompletionChunk] (streaming) Lista de mensajes de textos de finalización de chat. Se devuelven opciones n si se especifica el parámetro n.
object Cadena El tipo de objeto. Igual a "chat.completions" para no streaming o "chat.completion.chunk" para streaming.
created Entero Hora UTC en la que se generó la finalización del chat en segundos.
model String Versión del modelo utilizada para generar la respuesta.
usage Uso Metadatos de uso de tokens. Puede que no esté presente en las respuestas de streaming.

ChatCompletionChoice

Campo Tipo Descripción
index Entero Índice de la elección en la lista de opciones generadas.
message ChatMessage Mensaje de finalización del chat devuelto por el modelo. El rol será assistant.
finish_reason String Motivo por el que el modelo dejó de generar tokens.

ChatCompletionChunk

Campo Tipo Descripción
index Entero Índice de la elección en la lista de opciones generadas.
delta ChatMessage Una parte del mensaje de finalización del chat de las respuestas generadas transmitidos desde el modelo. Solo se garantiza que el primer fragmento se haya role rellenado.
finish_reason String Motivo por el que el modelo dejó de generar tokens. Solo el último fragmento se rellenará.

Tarea de finalización

Las tareas de finalización de texto son para generar respuestas a un único mensaje. A diferencia de Chat, esta tarea admite entradas por lotes: se pueden enviar varias solicitudes independientes en una solicitud.

Solicitud de finalización

Campo Valor predeterminado Tipo Descripción
prompt Cadena o Lista[String] Necesario. Los avisos del modelo.
max_tokens null null, lo que significa que no hay límite o un entero mayor que cero. Número máximo de tokens que se van a generar.
stream true Booleano Transmita las respuestas a un cliente para permitir resultados parciales para las solicitudes. Si este parámetro se incluye en la solicitud, las respuestas se envían mediante el estándar de eventos enviados por el servidor.
temperature 1.0 Flotar en [0,2] Temperatura de muestreo. 0 es determinista y los valores superiores introducen más aleatoriedad.
top_p 1.0 Flotar en (0,1] Umbral de probabilidad utilizado para el muestreo de núcleos.
top_k null null, lo que significa que no hay límite o un entero mayor que cero. Define el número de tokens más probables que se usen para el filtrado top-k. Establezca este valor en 1 para que las salidas sean deterministas.
error_behavior "error" "truncate" o "error" En el caso de los tiempos de espera y los errores superados por la longitud del contexto. Uno de: "truncate" (devuelve tantos tokens como sea posible) y "error" (devuelve un error). Este parámetro solo lo aceptan los puntos de conexión de pago por token.
n 1 Entero mayor que 0 La API devuelve n finalizaciones de chat independientes cuando se especifica n. Se recomienda para cargas de trabajo que generen varias finalizaciones en la misma entrada para obtener una eficiencia de inferencia adicional y un ahorro de costes. Solo está disponible para los puntos de conexión de rendimiento aprovisionados.
stop [] Cadena o Lista[String] El modelo deja de generar más tokens cuando se encuentra cualquiera de las secuencias de stop.
suffix "" String Cadena que se anexa al final de cada finalización.
echo false Booleano Devuelve el símbolo del sistema junto con la finalización.
use_raw_prompt false Booleano Si es true, pase directamente prompt al modelo sin ninguna transformación.

Respuesta de finalización de texto

Campo Tipo Description
id String Identificador único para la finalización del texto.
choices CompletionChoice Lista de finalizaciones de mensajes de texto. Para cada mensaje pasado, se generan opciones n si se especifica n. El n predeterminado es 1.
object Cadena El tipo de objeto. Igual a "text_completion"
created Entero Hora UTC en la que se generó la finalización en segundos.
usage Uso Metadatos de uso de tokens.

CompletionChoice

Campo Tipo Descripción
index Entero Índice del símbolo del sistema en la solicitud.
text String Finalización generada.
finish_reason String Motivo por el que el modelo dejó de generar tokens.

Tarea de inserción

Insertar tareas asignan cadenas de entrada en vectores de inserción. Muchas entradas se pueden procesar por lotes en cada solicitud.

Inserción de la solicitud

Campo Tipo Descripción
input Cadena o Lista[String] Necesario. Texto de entrada que se va a insertar. Puede ser una cadena o una lista de cadenas.
instruction Cadena Una instrucción opcional para pasar al modelo de inserción.

Las instrucciones son opcionales y muy específicas del modelo. Por ejemplo, los autores de BGE no recomiendan ninguna instrucción al indexar fragmentos y recomendar el uso de la instrucción "Represent this sentence for searching relevant passages:" para las consultas de recuperación. Otros modelos como Instructor-XL admiten una amplia gama de cadenas de instrucción.

Respuesta de inserción

Campo Tipo Description
id String Identificador único para la inserción.
object String El tipo de objeto. Igual a "list".
model String Nombre del modelo de inserción que se usa para crear la inserción.
data EmbeddingObject Objeto de inserción.
usage Uso Metadatos de uso de tokens.

EmbeddingObject

Campo Tipo Description
object String El tipo de objeto. Igual a "embedding".
index Entero Índice de la inserción en la lista de incrustaciones generadas por el modelo.
embedding List[Float] El vector de inserción. Cada modelo devolverá un vector de tamaño fijo (1024 para BGE-Large)

Recursos adicionales