LobeChat es una aplicación de chat con IA de código abierto; el proyecto y sus imágenes están adoptando poco a poco el nombre LobeHub. No ofrece modelos por sí misma: la calidad de las respuestas depende del proveedor de API que conectes. Para los equipos que usan un gateway unificado, la ventaja de integrar una API personalizada es directa: una Base URL y una clave bastan para cambiar entre varios modelos, y el consumo se consulta en un solo lugar.

Este artículo sigue las versiones habituales de 2026 y recorre el despliegue, la configuración del proveedor, la verificación de conectividad y los ajustes de asistentes, plugins, base de conocimiento y despliegue en equipo. La interfaz y los nombres de las variables cambian según la versión; antes de empezar, contrasta la documentación de la versión que uses.

Nota: LobeChat y LobeHub son productos y marcas de sus respectivos titulares; OpenAI es una marca de OpenAI, Inc. Este artículo solo describe una integración técnica y no implica subordinación ni relación de colaboración con esas empresas. El catálogo de modelos y los precios se rigen por la página de precios de modelos del sitio.

1. Elige primero la forma de despliegue

LobeChat puede ejecutarse solo en una computadora local o desplegarse en un servidor para todo el equipo. Cada escenario tiene dependencias distintas:

Forma Escenario adecuado Dependencias principales Notas
Contenedor único para pruebas Prueba personal, validación de funciones Docker, PostgreSQL Es la vía más rápida; para uso prolongado hay que añadir almacenamiento y copias de seguridad
Docker Compose Uso prolongado en equipo PostgreSQL, almacenamiento compatible con S3, Redis opcional Recomendado por el proyecto, con funciones completas
Hosting tipo Vercel Prueba ligera, poca operación PostgreSQL externo, S3 Serverless tiene límites de tiempo de ejecución y no admite WebSocket

La versión de servidor de 2026 considera PostgreSQL un componente obligatorio; la base de conocimiento necesita además pgvector y extensiones de búsqueda de texto completo, y la carga de archivos requiere almacenamiento compatible con S3. Las versiones antiguas tenían un modo solo de navegador; las nuevas se centran en el despliegue de servidor, así que confirma las dependencias de la versión actual antes de empezar. Si ya sabes que será para un equipo, prepara directamente el esquema Compose y evitarás retrabajos.

2. Prepara tres parámetros

Cualquiera sea la forma de despliegue, integrar una API personalizada requiere solo tres datos:

  • Base URL: https://ai.zhongshangqihang.com/v1, la entrada compatible con OpenAI.
  • API Key: se crea en la consola tras registrarte en ZSQH AI Gateway; ponle un nombre por proyecto o entorno.
  • ID del modelo: cópialo de la página de precios de modelos; es el identificador de API, no el nombre visible en la web.

Los dos últimos son los que más se equivocan: al pegar la clave se cuelan espacios, o el ID del modelo lleva un sufijo de versión de más o le falta una mayúscula. Guarda la clave en un gestor de contraseñas antes de configurar.

3. Arranca el servicio y escribe las variables de entorno

En un despliegue de equipo conviene poner la configuración en un archivo de variables de entorno, no dentro de la imagen ni del repositorio. Este es un ejemplo mínimo; sustituye los valores de base de datos, almacenamiento y secretos por los tuyos:

# Ejemplo de lobehub.env; genera tus propias claves y guárdalas bien
APP_URL=https://chat.example.com
DATABASE_URL=postgres://postgres:change-me@postgres:5432/postgres
AUTH_SECRET=genera con openssl rand -base64 32
KEY_VAULTS_SECRET=genera otro por separado con el mismo método
OPENAI_API_KEY=sk-tu-clave-del-gateway
OPENAI_PROXY_URL=https://ai.zhongshangqihang.com/v1
OPENAI_MODEL_LIST=-all,+tu-ID-de-modelo

Al arrancar el contenedor, monta ese archivo:

docker run -d --name lobehub -p 3210:3210 \
  --env-file lobehub.env lobehub/lobehub

Cuando el registro de arranque muestre la migración de base de datos completada y Ready, abre http://dirección-del-servidor:3210. Si el registro se detiene en un fallo de conexión a la base de datos, revisa primero el host, el puerto y la contraseña de DATABASE_URL; localhost dentro del contenedor no es el mismo que en el servidor anfitrión. Antes de actualizar la imagen, fija una etiqueta de versión; no uses latest durante largos periodos.

4. Añade un proveedor compatible con OpenAI en la interfaz

Las variables de entorno sirven para una configuración uniforme; la interfaz, para pruebas personales o ajustes temporales. Con las versiones habituales actuales:

  1. Inicia sesión, abre los ajustes y entra en «AI Providers».
  2. Elige OpenAI o añade un proveedor personalizado con un nombre que aclare su uso, por ejemplo «gateway del equipo».
  3. En la dirección de API escribe https://ai.zhongshangqihang.com/v1, solo hasta /v1.
  4. Introduce la clave del gateway y confirma que no haya espacios sobrantes.
  5. Añade el ID del modelo a la lista y marca visión, llamadas a herramientas, archivos u otras capacidades según lo que el modelo admita de verdad.
  6. Guarda y define ese proveedor como predeterminado, o vuelve al chat y elige el modelo manualmente.

Los proveedores personalizados permiten configurar etiquetas de capacidades, un punto que suele pasarse por alto. Una etiqueta mal marcada no da error al guardar, pero hace que plugins, comprensión de imágenes o carga de archivos fallen a mitad de la tarea. Si dudas, marca menos y valida con una tarea real antes de añadir el resto.

5. Verificación: primero curl, después la conversación

No empieces a trabajar justo después de configurar. Confirma primero la cadena con una solicitud mínima:

export ZSQH_API_KEY="sk-tu-clave"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tu-modelo-id","messages":[{"role":"user","content":"Responde solo OK"}]}'

Si la respuesta incluye choices, la dirección, la clave y el modelo al menos se comunican. Vuelve a LobeChat, crea una conversación, elige el mismo modelo y envía «Responde solo OK». Cuando ambos pasos funcionen, configura asistentes y base de conocimiento.

Los códigos de estado habituales apuntan a causas claras: 401, revisa la clave y los espacios; 404, revisa la ruta /v1; model not found, comprueba que el ID coincida con la página de precios; 429, revisa consumo y concurrencia en el gateway. Cambia una sola variable a la vez; de lo contrario no sabrás cuál surtió efecto.

6. Asistentes: asigna cada modelo a una tarea concreta

Los asistentes (en versiones nuevas también llamados agentes) guardan el prompt del sistema, el modelo y los parámetros. Lo práctico es repartir por tareas en lugar de amontonar todos los modelos en la lista predeterminada:

  • Preguntas cotidianas: un modelo general con buena velocidad y costo controlado.
  • Resúmenes largos y revisión de contratos: un asistente aparte con modelo de contexto largo y una estructura de salida escrita en el prompt.
  • Tareas de código: un modelo estable en programación, con la instrucción de explicar los cambios antes de ejecutarlos.
  • Traducción y corrección de estilo: un asistente para cada una, con glosario y tono fijados.

Cada asistente debería resolver un solo tipo de problema; cuanto más corto el prompt, más fácil de mantener. El equipo puede distribuir los prompts de los asistentes habituales como plantillas, pero nunca debe incluir claves en ellas.

7. Plugins y base de conocimiento: confirma las dependencias

Los plugins dependen de la capacidad de llamada a funciones del modelo. Si el modelo no admite herramientas, el botón del plugin puede seguir activo, pero la llamada fallará. Si alojas tu propio mercado de plugins, configura también la dirección del índice y las claves que necesiten; instala solo plugins de fuentes confiables y revisa qué contenido leen.

La base de conocimiento tiene más dependencias; la combinación habitual es PostgreSQL, pgvector, almacenamiento compatible con S3 y un modelo de embeddings. La versión actual usa por defecto un modelo de embeddings de OpenAI, aunque puede indicarse otro compatible mediante variables de entorno. Si conectas un gateway, confirma primero que ofrece la interfaz de embeddings y el modelo correspondiente; sin eso, la búsqueda semántica no funcionará.

Conviene importar primero uno o dos archivos con respuestas claras, probar la recuperación con preguntas concretas y después subir en lote. El tamaño de los fragmentos, el formato y la calidad del escaneo influyen en el resultado; no cambies varias opciones a la vez.

8. Despliegue en equipo: configuración central, claves separadas

Para uso en equipo, conviene respetar algunos límites:

  • Las variables de entorno del servidor solo llevan configuración compartida y modelos predeterminados; las claves van a un gestor de secretos y nunca a Git.
  • Cada miembro usa su propia clave del gateway, con su nombre, para poder revocarla si sale del equipo o hay una filtración.
  • La base de datos y S3 entran en el plan de copias de seguridad, y los archivos de respaldo se tratan como datos sensibles.
  • Todo despliegue público debe usar HTTPS y control de acceso en el proxy inverso.
  • En respuestas en streaming hay que desactivar el buffering del proxy; de lo contrario la respuesta aparece de golpe o se atasca a mitad.
  • Configura presupuesto y límites de concurrencia en el gateway, y revisa periódicamente los informes de consumo.

Si se trata de un equipo interno pequeño, puedes separar claves por proyecto en el gateway y usar las cuentas de LobeChat para distinguir usuarios. Conservar registros en ambas capas facilita mucho el diagnóstico y la facturación.

Preguntas frecuentes

¿Qué relación hay entre LobeChat y LobeHub?

LobeChat es el nombre temprano del proyecto; en 2026 la documentación y las imágenes nuevas usan la marca LobeHub. Las funciones continúan, pero las variables de entorno y los accesos de la interfaz han cambiado; al desplegar, guíate por la documentación actual del proyecto.

¿La Base URL debe incluir /v1?

Sí. Escribe https://ai.zhongshangqihang.com/v1 y no la ruta completa /chat/completions, porque el cliente la añade por su cuenta. Algunos proxies reenvían /v1 por ti; en ese caso manda el resultado de la prueba real.

¿La lista de modelos sigue vacía después de configurar las variables?

Revisa primero el nombre y la sintaxis de OPENAI_MODEL_LIST: -all,+ID-de-modelo se separa con comas inglesas y sin espacios. Después de cambiar variables de entorno hay que reconstruir el contenedor; un simple reinicio no siempre carga los valores nuevos.

¿La base de conocimiento sube archivos pero no encuentra contenido?

Comprueba en orden de dependencia: si la base de datos tiene la extensión vectorial, si S3 permite escritura y si el modelo de embeddings responde. Si falla cualquiera de las tres, el archivo puede aparecer como subido pero no se indexa.

¿Puede el equipo compartir una sola clave?

No es recomendable. Con una clave compartida no se distingue el consumo y una filtración afecta a todos. Emite claves por persona, proyecto o entorno y apóyate en los límites y registros del gateway.

Siguiente paso

La integración de LobeChat se puede dividir en tres pasos: elegir bien la forma de despliegue, alinear Base URL, clave e ID de modelo, y verificar con curl y una conversación real. Cuando funcione, añade asistentes, plugins y base de conocimiento poco a poco; los problemas serán muchos menos. Si necesitas un punto de acceso unificado a modelos y gestión de consumo, puedes registrarte en ZSQH AI Gateway; los modelos disponibles y sus precios se rigen por la página de precios de modelos.

Lecturas relacionadas: