API compatible con OpenAI de VergeOS

Documentación del endpoint de API compatible con OpenAI de VergeOS, que permite a las aplicaciones interactuar con LLM alojados localmente utilizando el formato estándar de la API de OpenAI con Python, JavaScript y cURL.

Descripción general

VergeOS proporciona un endpoint de API compatible con OpenAI que permite a las aplicaciones interactuar con modelos de lenguaje grandes (LLM) alojados localmente usando el formato estándar de la API de OpenAI. Esto le permite usar herramientas y bibliotecas conocidas mientras ejecuta modelos completamente dentro de su entorno VergeOS.

La API enruta automáticamente las solicitudes a sus asistentes configurados y a sus modelos subyacentes, proporcionando una interfaz unificada para las interacciones de IA.

Requisitos previos

Antes de usar la API compatible con OpenAI, asegúrese de que los siguientes componentes estén en ejecución:

1. AI-Helper Worker: Este worker gestiona las solicitudes de la API y debe estar en ejecución. Se inicia automáticamente cuando el servicio de IA está habilitado.
2. Al menos un asistente con un modelo en línea: Se debe configurar un asistente y su modelo subyacente debe estar en estado "Online".

Para verificar estos requisitos previos:

1. Vaya a AI → Ver workers para confirmar que AI-Helper Worker está en ejecución
2. Vaya a AI → Asistentes para confirmar que al menos un asistente muestra el estado "Online"

Puntos finales de la API

La API compatible con OpenAI está disponible en:

https://<your-vergeos-url>/v1

Puntos finales compatibles

Punto final	Descripción
/v1/models	Lista los modelos disponibles (devuelve los asistentes configurados)
/v1/chat/completions	Generar completaciones de chat

Autenticación

Las solicitudes de la API requieren autenticación mediante un token Bearer:

Authorization: Bearer <your-api-key>

Creación de una clave API

1. Vaya a Sistema → Usuarios
2. Seleccione el usuario que será propietario de la clave API (o cree un usuario nuevo)
3. Haga clic en Nueva clave API en el menú de la izquierda
4. Configure los ajustes de la clave:

   • Nombre: Un nombre descriptivo para la clave (p. ej., my-app-key)
   • Descripción (opcional): Detalles adicionales sobre el propósito de la clave
   • Tipo de vencimiento: Elija "Establecer fecha" o "Nunca"
   • Vence: Si usa Establecer fecha, seleccione la fecha/hora de vencimiento
5. Guarde la clave y copie el token generado

Seguridad

La clave API solo se muestra una vez al crearse. Guárdela de forma segura, ya que no podrá recuperarse más tarde.

Las claves API heredan los permisos del usuario asociado. Para uso en producción, considere crear un usuario de API dedicado con los permisos adecuados.

Uso básico

Ejemplo en Python

from openai import OpenAI

client = OpenAI(
    base_url="https://your-vergeos-instance.com/v1",
    api_key="your-api-key"
)

response = client.chat.completions.create(
    model="qwen3-coder-14B",  # Usa el nombre del asistente
    messages=[
        {"role": "user", "content": "Escribe una función de hola mundo en Python"}
    ],
    max_tokens=1024,
    temperature=0.7
)

print(response.choices[0].message.content)

Ejemplo de cURL

curl https://your-vergeos-instance.com/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-coder-14B",
    "messages": [{"role": "user", "content": "¡Hola!"}],
    "max_tokens": 100
  }'

Listar modelos disponibles

curl https://your-vergeos-instance.com/v1/models \
  -H "Authorization: Bearer your-api-key"

Nombres de modelos

En las solicitudes de la API, use el nombre del asistente (p. ej., qwen3-coder-14B) como el modelo parámetro, no el nombre del modelo subyacente (p. ej., Qwen3-14B-Q6_K).

Formato de respuesta

Las respuestas siguen el formato estándar de OpenAI con información adicional de temporización:

{
  "id": "unique-completion-id",
  "object": "chat.completion",
  "created": 1768822431,
  "model": "assistant-name",
  "system_fingerprint": "assistant-name",
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Contenido de la respuesta aquí"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 100,
    "total_tokens": 132
  },
  "timings": {
    "prompt_n": 12,
    "prompt_ms": 365.388,
    "prompt_per_token_ms": 30.449,
    "prompt_per_second": 32.84,
    "predicted_n": 100,
    "predicted_ms": 1620.788,
    "predicted_per_token_ms": 16.21,
    "predicted_per_second": 61.70
  }
}

La timings el campo proporciona métricas de rendimiento no disponibles en la API estándar de OpenAI.

Configuración de asistentes

Los asistentes definen cómo interactúa la API con los modelos subyacentes. El asistente Nombre se usa como el modelo parámetro en las solicitudes de la API.

Para obtener instrucciones detalladas sobre cómo crear y configurar asistentes, consulte la Guía de configuración de IA.

Ajustes clave para el uso de la API

• Nombre: Esto se convierte en el modelo parámetro en las llamadas a la API
• Desactivar el razonamiento: Habilítelo para que los modelos con capacidad de razonamiento devuelvan contenido mediante la API
• Prompt del sistema: Se aplica automáticamente a cada solicitud de la API

Workers

El sistema de IA usa dos tipos de workers:

• AI-Helper Worker: Procesa las solicitudes de la API y las enruta a los modelos. Se inicia automáticamente y es necesario para que la API funcione.
• Workers de modelos: Gestionan la inferencia de cada modelo en ejecución. Se crean automáticamente cuando un modelo se inicia.

Ver el estado del worker en AI → Ver workers.

Conversaciones de varios turnos

La API admite conversaciones de varios turnos al incluir el historial de mensajes:

response = client.chat.completions.create(
    model="qwen3-coder-14B",
    messages=[
        {"role": "user", "content": "¿Qué es Python?"},
        {"role": "assistant", "content": "Python es un lenguaje de programación..."},
        {"role": "user", "content": "Muéstrame un ejemplo sencillo"}
    ]
)

Cuando Historial de chat está habilitado en el asistente, el sistema también puede mantener el contexto entre llamadas separadas a la API dentro de una sesión.

Trabajar con modelos de razonamiento

Algunos modelos (como Qwen3) tienen capacidades de "razonamiento" en las que resuelven problemas internamente antes de responder.

Si está usando un modelo así mediante la API y recibe respuestas vacías, es posible que el modelo esté generando tokens de razonamiento que se filtran de la respuesta. Para obtener el contenido real de la respuesta:

1. Vaya a AI → Asistentes
2. Haga clic en su asistente
3. Haga clic en Editar asistente
4. Habilite el Desactivar el razonamiento interruptor
5. Haga clic en Enviar

Esto suprime el proceso de razonamiento y devuelve solo la respuesta final.

Ejemplos de integración

Integración en el IDE

Muchos IDE admiten endpoints personalizados compatibles con OpenAI. Configure su IDE con:

• URL base de la API: https://your-vergeos-instance.com/v1
• Clave API: Su clave API de VergeOS
• Modelo: El nombre de su asistente (p. ej., qwen3-coder-14B)

Integración de aplicaciones

Use cualquier biblioteca cliente de OpenAI:

Python

from openai import OpenAI
client = OpenAI(base_url="https://your-vergeos-instance.com/v1", api_key="your-key")

JavaScript

import OpenAI from 'openai';
const client = new OpenAI({
  baseURL: 'https://your-vergeos-instance.com/v1',
  apiKey: 'your-key'
});

cURL

curl https://your-vergeos-instance.com/v1/chat/completions \
  -H "Authorization: Bearer your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "assistant-name", "messages": [...]}'

Solución de problemas

Error de inicio de sesión requerido

{"err":"Se requiere inicio de sesión"}

Causa: Falta la clave API o no es válida.

Solución: Incluya una clave API válida en el encabezado Authorization.

Contenido de respuesta vacío

Causa: El modelo está usando tokens de razonamiento que se filtran de la salida.

Solución: Habilite "Desactivar el razonamiento" en la configuración del asistente.

Modelo no encontrado

Causa: El nombre de modelo especificado no coincide con ningún asistente.

Solución:

• Use el nombre exacto del asistente (sensible a mayúsculas y minúsculas)
• Verifique que el asistente exista en AI → Asistentes
• Asegúrese de que el modelo del asistente esté en línea

Conexión rechazada

Causa: AI-Helper Worker no está en ejecución.

Solución:

• Compruebe AI → Ver workers para verificar el estado de AI-Helper Worker
• Reinicie el servicio de IA si es necesario

Respuestas lentas

Causa: El modelo se está cargando o está muy cargado.

Solución:

• Compruebe el uso de recursos del worker en AI → Ver workers
• Considere asignar más núcleos de CPU o RAM al modelo
• Use un modelo más pequeño para obtener respuestas más rápidas

---

Compatibilidad de versiones: Esta funcionalidad está disponible en VergeOS 26.0 y versiones posteriores.