vLLM Beta

4 min de lectura

La conexión vLLM sirve para vLLM y para cualquier motor que hable la API de OpenAI: LM Studio, llama.cpp (llama-server) o SGLang. El modelo se ejecuta en una máquina que controlas, en lugar de usar un proveedor cloud. A cambio, te encargas de los recursos, la disponibilidad y la seguridad de esa máquina.

Experimental

La integración con vLLM está en pruebas y puede cambiar. Úsala primero en un entorno controlado.

Antes de conectarlo

Necesitas el motor en marcha con el modelo cargado y una dirección alcanzable desde el contenedor del agente. Comprueba que contesta con:

curl http://<dirección>:8000/v1/models

Debe devolver el modelo con el nombre exacto que usarás en Kujira. Si el motor solo escucha en localhost, haz que escuche en una interfaz de red (en vLLM, --host 0.0.0.0) y protege el acceso con tu red privada, una VPN o un cortafuegos.

Kujira habla con el motor por /v1/messages, así que necesita una versión de vLLM que lo incluya. Si lo arrancas con --api-key, pon esa misma clave en la conexión; si no, déjala vacía.

No expongas el motor sin protección

Sin --api-key, quien conozca la dirección puede usar tu GPU y ver tus modelos. No publiques el puerto directamente en internet: utiliza una VPN o un proxy con autenticación y HTTPS.

Crear una conexión

En Ajustes > Modelos > vLLM, pulsa Añadir conexión. Una conexión representa una combinación concreta de máquina y modelo, no una cuenta de proveedor: si tienes tres equipos, son tres conexiones.

Nombra la conexión

El nombre es obligatorio y es lo único que distingue una máquina de otra en la lista y en la ficha de cada agente. Usa algo que permita reconocerla, por ejemplo, “vLLM del servidor”.

Indica la dirección

Introduce la URL desde la que el agente puede alcanzar el motor, sin /v1 al final: por ejemplo, http://192.168.1.85:8000. Para un motor en el mismo servidor que el agente, suele utilizarse http://host.docker.internal:8000.

Declara dónde está el servidor

En Ubicación del servidor, elige Red privada si está en la misma máquina, en tu red local o en una VPN, o Acceso público si llegas a él por un túnel, un dominio propio o DNS dinámico. El acceso público exige HTTPS.

Elige el modelo y su contexto

En Modelo, elige uno de la lista: Kujira le pregunta al motor —desde tu servidor— qué modelos sirve, y enseña de cada uno su ventana de contexto. Al elegirlo se rellena la ventana. Los que admiten 64k tokens o menos aparecen atenuados y no se pueden elegir. Si la lista no sale, escribe el nombre exacto que devuelve /v1/models e indica su ventana, que tiene que ser de más de 64k.

Asigna la conexión al agente

En Configuración > Modelo del agente, elige esa conexión en el desplegable Conexión. Como la conexión trae su propio modelo, es el que correrá.

Otros servicios compatibles

La conexión no está atada a un motor concreto: sirve para cualquier dirección que responda a lo que Kujira necesita, sea un motor, un servidor de modelos o una pasarela propia (por ejemplo, LiteLLM).

Debe cumplir tres cosas:

• Servir /v1/messages en formato Anthropic, con streaming y herramientas.
• Listar sus modelos en /v1/models, que es lo que usa Probar.
• Aceptar la clave como Authorization: Bearer, si la pide.

Si el servicio no publica la ventana de sus modelos, escríbela tú en la conexión: tiene que ser de más de 64k tokens.

Kujira no comprueba ni da soporte a lo que haya detrás de esa dirección: sus condiciones de uso, su coste y su disponibilidad son cosa de quien lo monta. Como no interviene un proveedor cloud, el consumo de esta conexión aparece a cero en Kujira aunque el servicio de detrás cobre por token.

Contexto y rendimiento

Un agente envía en cada mensaje unos 30.000 tokens de instrucciones y herramientas antes de lo que le escribes, así que Kujira solo acepta modelos con más de 64k tokens de ventana. Pulsa Probar en la conexión: comprueba que el motor contesta, que sirve el modelo de la conexión y que su ventana alcanza. vLLM publica la ventana de cada modelo (max_model_len); otros motores pueden no hacerlo, y entonces la que declares en la conexión es la que cuenta.

El coste por token no aparece en Kujira porque no interviene un proveedor cloud. Aun así, el consumo existe: depende de la GPU, CPU, memoria y electricidad de tu infraestructura.

Errores frecuentes

Probar dice que el modelo no está

El nombre de la conexión tiene que coincidir exactamente con el id que devuelve /v1/models en la máquina. Elígelo de la lista en vez de escribirlo.

El agente no puede conectar

Revisa la dirección, el puerto, el cortafuegos y que el motor esté escuchando fuera de localhost cuando el agente se ejecute en otro contenedor o servidor.

Error de credencial

El motor se arrancó con --api-key y la conexión no lleva esa clave, o lleva otra. Escríbela en Clave (opcional).

Funciona en un agente y no en otro

Los agentes pueden ejecutarse en servidores distintos. Con host.docker.internal, cada agente habla con el motor de su propio servidor: todos deben tener el mismo modelo, o debes crear una conexión para cada máquina.

Consulta Modelos para las demás opciones y para cómo se comprueba una conexión.