API de inferencia

Fastino ofrece dos interfaces síncronas para la inferencia GLiNER. Elige la interfaz que se ajuste a tu modelo y a los requisitos de tu carga útil:

Capacidad	`/v1/chat/completions`	`/v1/gliner-2`
Modelo	Selecciona un modelo base con capacidad de inferencia o el UUID de un trabajo de entrenamiento completado	Siempre usa `fastino/gliner2-base-v1`
Solicitud	`model` y `messages` compatibles con OpenAI, más el `schema` de nivel superior de Fastino	Campos nativos `text`, `schema`, `threshold`, `include_confidence` e `include_spans`
Respuesta	Envoltorio de chat-completion de OpenAI; analiza `choices[0].message.content` como JSON	Cuerpo nativo `{ "result": ..., "token_usage": ... }`
Entrada por lotes	Una conversación por solicitud	Acepta una cadena o una lista de cadenas
Procesamiento asíncrono	No disponible	Envía con `POST /v1/gliner-2/async` y luego consulta `GET /v1/gliner-2/jobs/{job_id}`
Ideal para	Integraciones estándar y modelos ajustados	Inferencia con el modelo base GLiNER2, resultados nativos, procesamiento por lotes o trabajos de larga duración

Empieza con /v1/chat/completions para disponer de una API coherente entre modelos base y ajustados. Usa /v1/gliner-2 cuando necesites específicamente el contrato nativo del modelo base fijo GLiNER2, la entrada por lotes o el procesamiento asíncrono.

Esta página documenta a continuación el contrato HTTP en crudo de /v1/chat/completions. Los esquemas nativos de /v1/gliner-2 se publican en el documento OpenAPI. El uso del SDK, el entrenamiento de modelos, la evaluación, el historial de inferencia y el feedback quedan fuera del alcance de esta página.

POST /inference se ha eliminado. No envíes sus campos heredados como model_id, text, task, format_results o is_warmup.

Endpoint

POST https://api.fastino.ai/v1/chat/completions

Autenticación

Envía una clave de API de Fastino como bearer token:

export FASTINO_API_KEY="fast_sk_..."

Authorization: Bearer $FASTINO_API_KEY
Content-Type: application/json

Solicitud

string

requerido

Un ID de modelo base con capacidad de inferencia o el UUID de un trabajo de entrenamiento de Fastino completado y desplegable.

object[]

requerido

Una lista de mensajes no vacía. Para la inferencia GLiNER, coloca el texto a analizar en el content de un mensaje de usuario.

object

Define tareas personalizadas del codificador. Proporciona un diccionario que contenga una o varias de las claves entities, classifications, structures o relations. Omítelo solo cuando el modelo seleccionado tenga una tarea predeterminada configurada.Una lista plana de etiquetas de entidad está obsoleta. Utiliza siempre la forma de diccionario.

number

predeterminado:"0.5"

Umbral de confianza de 0 a 1. Los valores más bajos favorecen la exhaustividad; los más altos favorecen la precisión.

boolean

predeterminado:"true"

Incluye los valores de confianza en los resultados extraídos.

boolean

predeterminado:"true"

Incluye los desplazamientos de caracteres semiabiertos (start, end) en los resultados de entidades.

boolean

predeterminado:"true"

Persiste la inferencia. Establécelo en false para no guardarla.

Esquema de entidades

Utiliza definiciones de entidades descriptivas cuando sea posible:

{
  "entities": [
    {
      "name": "organization",
      "description": "business or institution name"
    },
    {
      "name": "product",
      "description": "named commercial product"
    }
  ]
}

Esquema de clasificación

{
  "classifications": [
    {
      "task": "sentiment",
      "labels": ["positive", "negative", "neutral"],
      "multi_label": false,
      "top_k": 1
    }
  ]
}

Esquema de extracción estructurada

Los campos de estructura usan especificaciones field::type::description:

{
  "structures": {
    "product": [
      "name::str::product name",
      "price::str::listed price",
      "features::list::named features"
    ]
  }
}

Esquema de relaciones

El esquema de relaciones más simple es una lista plana de nombres de relación:

{
  "relations": ["works_for", "lives_in"]
}

También puedes usar un diccionario para añadir descripciones o configuración por relación:

{
  "relations": {
    "works_for": {
      "description": "employment relationship",
      "threshold": 0.6
    }
  }
}

No envíes objetos de relación que contengan definiciones de head y tail.

Esquema combinado

Ejecuta varias tareas sobre el mismo texto combinando claves:

{
  "entities": [
    {
      "name": "organization",
      "description": "business or institution name"
    },
    {
      "name": "product",
      "description": "named commercial product"
    }
  ],
  "classifications": [
    {
      "task": "sentiment",
      "labels": ["positive", "negative", "neutral"],
      "multi_label": false,
      "top_k": 1
    }
  ]
}

El esquema identifica la operación automáticamente. No envíes task ni task_type.

Ejemplo

curl -X POST "https://api.fastino.ai/v1/chat/completions" \
  -H "Authorization: Bearer $FASTINO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fastino/gliner2.5-multi-v1",
    "messages": [
      {
        "role": "user",
        "content": "Apple announced the MacBook Pro at WWDC in Cupertino."
      }
    ],
    "schema": {
      "entities": [
        {
          "name": "organization",
          "description": "business or institution name"
        },
        {
          "name": "product",
          "description": "named commercial product"
        },
        {
          "name": "event",
          "description": "named conference or event"
        },
        {
          "name": "location",
          "description": "city, region, or place"
        }
      ]
    },
    "threshold": 0.5
  }'

El valor de model debe soportar actualmente la inferencia alojada. Usa el catálogo de modelos en vivo en lugar de asumir que todos los checkpoints de Hugging Face están disponibles:

curl "https://api.fastino.ai/v1/base-models?supports_inference=true&task_type=encoder"

Respuesta

El endpoint devuelve un envoltorio de chat completion. El resultado GLiNER se serializa como una cadena JSON en choices[0].message.content:

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "created": 1790123456,
  "model": "fastino/gliner2.5-multi-v1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"entities\":[{\"organization\":[{\"text\":\"Apple\",\"confidence\":0.99,\"start\":0,\"end\":5}],\"product\":[{\"text\":\"MacBook Pro\",\"confidence\":0.98,\"start\":20,\"end\":31}],\"event\":[{\"text\":\"WWDC\",\"confidence\":0.97,\"start\":35,\"end\":39}],\"location\":[{\"text\":\"Cupertino\",\"confidence\":0.99,\"start\":43,\"end\":52}]}],\"classifications\":{},\"structures\":{},\"relations\":{}}"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 0,
    "completion_tokens": 0,
    "total_tokens": 0
  },
  "x_pioneer": {
    "inference_id": "..."
  }
}

Analiza choices[0].message.content como JSON antes de leer los resultados de la tarea. Cuando store=true, x_pioneer.inference_id identifica la inferencia persistida.

Entradas repetidas

El endpoint acepta una conversación por solicitud. No soporta la forma de lote text: string[] del endpoint nativo eliminado. Envía solicitudes separadas de forma concurrente cuando proceses varias entradas.

Arranques en frío y reintentos

Un modelo inactivo o recién desplegado puede tener un arranque en frío. Usa un tiempo de espera de lectura de al menos 300 segundos y reintenta las respuestas 425, 429 y 503. Respeta la cabecera de respuesta Retry-After cuando esté presente. Una solicitud que agota el tiempo aún puede calentar el despliegue, lo que permite que la siguiente solicitud tenga éxito. No reintentes errores de autenticación, facturación, validación, modelo desconocido ni de trabajo no desplegable sin corregir el problema subyacente.

curl --max-time 300 -X POST "https://api.fastino.ai/v1/chat/completions" \
  -H "Authorization: Bearer $FASTINO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json

Errores

Estado	Causa probable	Acción
`400`	Solicitud o esquema no válidos	Corrige los campos de la solicitud o el esquema
`401`	Clave de API ausente, mal formada o no válida	Exporta una clave `fast_sk_...` válida
`402`	Créditos insuficientes, se requiere financiación o límite de gasto diario/mensual fijado por el propietario	Añade créditos o ajusta el límite de gasto
`403`	Método de pago, verificación de tarjeta, techo de crédito o denegación por política de la cuenta	Resuelve el requisito de facturación o de la cuenta
`404`	Modelo desconocido o no soportado	Usa un ID del catálogo con capacidad de inferencia o el UUID de un trabajo desplegable
`409`	El modelo ajustado existe pero no está desplegado	Espera al despliegue o repáralo
`422`	Validación de la solicitud fallida	Lee y corrige los detalles de validación a nivel de campo
`425`	El despliegue ajustado se está calentando	Reintenta tras el retraso indicado
`429`	Límite de tasa o de capacidad	Respeta `Retry-After` y reintenta con retroceso
`503`	Arranque en frío o problema temporal de capacidad del proveedor	Reintenta antes de tratarlo como terminal

Migración de solicitudes heredadas

Campo eliminado de `/inference`	Campo actual
`model_id`	`model`
`text`	`messages: [{"role": "user", "content": "..."}]`
Lista plana de entidades en `schema`	Diccionario `schema`
`task` o `task_type`	Elimínalo; el esquema identifica la operación
`text: string[]`	Envía solicitudes separadas
`format_results` o `is_warmup`	Elimínalos
Cuerpo de resultado nativo	Analiza `choices[0].message.content`

Empezar

Conceptos básicos

API de entrenamiento

Cuenta

API de inferencia

Endpoint

Autenticación

Solicitud

Esquema de entidades

Esquema de clasificación

Esquema de extracción estructurada

Esquema de relaciones

Esquema combinado

Ejemplo

Respuesta

Entradas repetidas

Arranques en frío y reintentos

Errores

Migración de solicitudes heredadas

​Endpoint

​Autenticación

​Solicitud

​Esquema de entidades

​Esquema de clasificación

​Esquema de extracción estructurada

​Esquema de relaciones

​Esquema combinado

​Ejemplo

​Respuesta

​Entradas repetidas

​Arranques en frío y reintentos

​Errores

​Migración de solicitudes heredadas

Endpoint

Autenticación

Solicitud

Esquema de entidades

Esquema de clasificación

Esquema de extracción estructurada

Esquema de relaciones

Esquema combinado

Ejemplo

Respuesta

Entradas repetidas

Arranques en frío y reintentos

Errores

Migración de solicitudes heredadas