Cómo conectar Onyx y otras interfaces con Ollama

Conectar Onyx con Ollama permite utilizar modelos de lenguaje ejecutados en tu propio ordenador o servidor como motor para los chats y agentes de la plataforma. De esta forma, puedes trabajar con modelos abiertos sin enviar cada conversación a proveedores externos ni pagar por cada token generado.

Las dos aplicaciones cumplen funciones diferentes. Ollama descarga, carga y ejecuta los modelos, mientras que Onyx proporciona la interfaz de chat, el historial, los agentes, los controles de acceso y, en su despliegue Standard, la búsqueda sobre documentos y fuentes empresariales.

Onyx dispone actualmente de una integración específica para Ollama dentro de su Panel de Administración. La configuración es sencilla, pero debes utilizar una dirección diferente dependiendo de si Onyx y Ollama se ejecutan directamente en el sistema, dentro de Docker o en equipos separados.

Qué necesitas para conectar Onyx con Ollama

Antes de comenzar, necesitas tener ambos servicios en funcionamiento:

• Una instalación de Onyx Lite o Standard.
• Ollama ejecutándose en el mismo equipo o en un servidor accesible.
• Al menos un modelo descargado en Ollama.
• Acceso de administrador a Onyx.
• Memoria RAM o VRAM suficiente para el modelo elegido.

Onyx Lite es suficiente si solo quieres chatear, utilizar archivos adjuntos, crear proyectos o probar agentes con un modelo local. Si necesitas conectar Google Drive, Slack, SharePoint u otras fuentes, indexar documentos y utilizar búsqueda RAG, tendrás que instalar Onyx Standard.

Cómo instalar Ollama y descargar un modelo

Descarga Ollama desde su sitio oficial e instálalo en Windows, macOS o Linux. Después abre una terminal y descarga un modelo adecuado para tu hardware.

Por ejemplo:

ollama pull qwen3:8b

El nombre es solamente un ejemplo. Puedes elegir otro modelo compatible según la memoria disponible y las funciones que necesites.

Comprueba los modelos instalados mediante:

ollama list

También puedes ejecutar una prueba directa:

ollama run qwen3:8b

Si el modelo responde en la terminal, Ollama está funcionando. Escribe /bye para cerrar la conversación.

Cómo comprobar que la API de Ollama funciona

Ollama inicia de forma predeterminada un servidor HTTP en el puerto 11434. Para consultar la lista de modelos disponibles, ejecuta:

curl http://localhost:11434/api/tags

En PowerShell también puedes abrir directamente esta dirección mediante:

Invoke-RestMethod http://localhost:11434/api/tags

Si recibes una respuesta con los modelos instalados, la API está disponible. Si aparece un error de conexión, comprueba que Ollama se esté ejecutando y que ningún cortafuegos esté bloqueando el puerto.

Qué dirección de Ollama debes introducir en Onyx

La dirección correcta depende de dónde se ejecuta cada aplicación. Este es el punto que provoca más errores durante la integración.

Configuración	Dirección habitual
Onyx y Ollama ejecutados directamente en el mismo sistema	http://localhost:11434
Onyx en Docker y Ollama instalado en el anfitrión	http://host.docker.internal:11434
Onyx y Ollama en contenedores de la misma red	http://ollama:11434
Ollama en otro equipo de la red local	http://IP_DEL_SERVIDOR:11434

Cuando Onyx se ejecuta en Docker, localhost hace referencia al propio contenedor, no al ordenador anfitrión. Por eso una dirección que funciona desde el navegador puede fallar al introducirla en Onyx.

En Docker Desktop para Windows y macOS suele estar disponible el nombre host.docker.internal. En Linux puede ser necesario añadir una asignación al gateway del anfitrión o utilizar la dirección IP accesible desde la red de Docker.

Cómo permitir que Onyx acceda a Ollama desde Docker

Ollama escucha de forma predeterminada en 127.0.0.1:11434. Esto limita el acceso a procesos ejecutados en el mismo sistema. Si Onyx está dentro de un contenedor y no consigue conectarse, puede ser necesario hacer que Ollama escuche en una interfaz accesible.

En Linux con systemd, crea una modificación del servicio:

sudo systemctl edit ollama

Añade:

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

Después aplica la configuración:

sudo systemctl daemon-reload
sudo systemctl restart ollama

Comprueba desde el equipo anfitrión que la API continúa respondiendo:

curl http://localhost:11434/api/tags

Antes de continuar, limita el puerto mediante el cortafuegos. La API local de Ollama no exige autenticación, por lo que cualquier equipo capaz de alcanzar el puerto podría enviar peticiones y consumir los recursos del servidor.

Cómo conectar Onyx con Ollama desde el Panel de Administración

Cuando la API sea accesible, completa la integración desde Onyx:

1. Inicia sesión con una cuenta administradora.
2. Abre el menú del perfil.
3. Entra en el Panel de Administración.
4. Accede a Configuration > Language Models.
5. Pulsa la opción para añadir un proveedor.
6. Selecciona Ollama.
7. Introduce un nombre descriptivo para identificar el proveedor.
8. Indica la dirección de la instancia de Ollama.
9. Pulsa Fetch Available Models.

Onyx consultará la instancia y mostrará los modelos disponibles. Si la lista permanece vacía, revisa la dirección utilizada y ejecuta ollama list para confirmar que existen modelos descargados.

La clave de API no es necesaria para una instancia local de Ollama. Si utilizas el servicio administrado de Ollama Cloud, tendrás que introducir la clave correspondiente.

Cómo elegir los modelos visibles en Onyx

Después de recuperar la lista, abre las opciones avanzadas y selecciona los modelos que quieres mostrar a los usuarios. No es recomendable publicar automáticamente todos los modelos instalados.

Una lista reducida facilita la elección y evita que alguien seleccione accidentalmente un modelo experimental, demasiado lento o incompatible con determinadas funciones.

Al escoger un modelo, revisa especialmente:

• Seguimiento de instrucciones: determina si respeta correctamente las indicaciones del sistema y del usuario.
• Uso de herramientas: necesario para determinados agentes y acciones.
• Ventana de contexto: condiciona la cantidad de conversación y documentación que puede procesar.
• Memoria necesaria: un modelo que no cabe en la VRAM puede repartir el trabajo entre GPU y CPU y responder mucho más despacio.
• Idioma: algunos modelos responden mejor en español que otros.
• Visión: necesaria si quieres analizar imágenes mediante un modelo multimodal compatible.

En equipos modestos suele ser preferible comenzar con un modelo cuantizado de entre 4B y 8B parámetros. Para equipos profesionales pueden utilizarse modelos mayores, siempre que exista memoria suficiente.

Cómo establecer el modelo predeterminado y controlar el acceso

Onyx permite definir qué modelo utilizará la organización de forma predeterminada y qué proveedores estarán disponibles para cada usuario.

Al guardar la configuración de Ollama, puedes marcar el proveedor como:

• Público: todos los usuarios de la instancia pueden utilizar sus modelos.
• Privado: solamente los administradores y los grupos autorizados pueden acceder al proveedor.

La configuración privada resulta útil cuando el servidor tiene recursos limitados o cuando determinados modelos están reservados para un equipo concreto.

También conviene establecer un modelo principal para los chats generales y, si Onyx ofrece la opción en tu versión, un modelo rápido para tareas auxiliares. De esta forma, las operaciones sencillas no necesitan recurrir siempre al modelo más pesado.

Cómo probar Ollama desde el chat de Onyx

Después de guardar el proveedor:

1. Abre un chat nuevo.
2. Despliega el selector de modelos.
3. Elige uno de los modelos procedentes de Ollama.
4. Envía una pregunta sencilla.
5. Comprueba que la respuesta comienza a transmitirse progresivamente.

Mientras se genera la respuesta, puedes comprobar qué modelo está cargado y si utiliza la GPU mediante:

ollama ps

La columna correspondiente al procesador indica si el modelo se está ejecutando completamente en la GPU, en la CPU o mediante una combinación de ambas.

Cómo utilizar Ollama con documentos y RAG en Onyx

Conectar Ollama configura el modelo generativo utilizado para redactar respuestas, interpretar instrucciones y ejecutar determinados agentes. Esto no significa que Ollama sustituya automáticamente a todos los componentes empleados por Onyx para la búsqueda documental.

En Onyx Standard, los documentos se convierten en vectores mediante un modelo de embeddings y se almacenan en el índice de búsqueda. Los servidores de modelos de Onyx también pueden encargarse del reranking y de otras operaciones relacionadas con la recuperación.

Los modelos de embeddings se configuran desde los ajustes de búsqueda, no desde la pantalla de proveedores de lenguaje. Si quieres que todo el procesamiento permanezca dentro de tu infraestructura, selecciona un modelo de embeddings autogestionado y asigna recursos suficientes al servidor de indexación.

Onyx recomienda disponer de GPU para procesar grandes cantidades de documentos mediante embeddings locales. Ejecutar al mismo tiempo el modelo de chat, los embeddings y el reranking en una única GPU con poca VRAM puede provocar esperas y errores de memoria.

Cómo mejorar el rendimiento de Ollama con Onyx

Elegir un modelo que quepa en la memoria

Si el modelo supera la VRAM disponible, Ollama puede descargar parte de sus capas en la memoria del sistema. Esto reduce notablemente la velocidad. Utiliza ollama ps para comprobar dónde se ha cargado.

Ajustar el tiempo que permanece cargado

Ollama mantiene los modelos en memoria durante unos minutos después de utilizarlos. Puedes modificar este comportamiento mediante OLLAMA_KEEP_ALIVE.

Por ejemplo, para conservarlos durante 30 minutos:

OLLAMA_KEEP_ALIVE=30m

Un valor negativo mantiene el modelo cargado indefinidamente, pero no siempre es recomendable. Si varios modelos permanecen residentes, pueden consumir toda la VRAM e impedir que se carguen otros.

Precalentar el modelo

Para evitar el retraso de la primera respuesta, puedes cargar previamente el modelo mediante una petición vacía:

curl http://localhost:11434/api/generate \
  -d '{"model":"qwen3:8b","keep_alive":"30m"}'

Evitar una concurrencia excesiva

Las peticiones simultáneas aumentan el consumo de memoria. Si Ollama no dispone de recursos suficientes, las solicitudes quedan en cola y eventualmente puede devolver un error 503.

Las variables OLLAMA_NUM_PARALLEL, OLLAMA_MAX_LOADED_MODELS y OLLAMA_MAX_QUEUE permiten ajustar este comportamiento, pero no conviene aumentarlas sin comprobar primero la RAM y la VRAM disponibles.

Por qué no deberías utilizar OLLAMA_ORIGINS=»*»

OLLAMA_ORIGINS controla los orígenes web adicionales autorizados para realizar peticiones mediante el navegador. La conexión habitual entre Onyx y Ollama se realiza desde el backend de Onyx, por lo que normalmente no requiere modificar CORS.

Configurar un comodín no soluciona los errores de red entre contenedores y amplía innecesariamente los orígenes admitidos. Si una integración basada en navegador necesita CORS, añade únicamente el dominio concreto que utilizará la aplicación.

Cómo proteger una instancia de Ollama accesible por red

La API local de Ollama no incluye autenticación. Nunca publiques directamente el puerto 11434 en Internet.

Si Onyx y Ollama se ejecutan en equipos diferentes:

• Utiliza una red privada, una VPN o una VLAN interna.
• Limita mediante el cortafuegos qué direcciones pueden acceder al puerto.
• No configures una redirección pública del puerto 11434 en el router.
• Si necesitas acceso remoto, coloca un proxy con autenticación y TLS delante de Ollama.
• Supervisa el consumo de CPU, RAM, GPU y las peticiones recibidas.

Ejecutar el modelo localmente mejora el control sobre las solicitudes, pero la privacidad final también depende de los conectores, herramientas, modelos de embeddings y servicios externos habilitados dentro de Onyx.

Errores frecuentes al conectar Onyx con Ollama

Onyx no encuentra ningún modelo

Comprueba primero la instalación:

ollama list
curl http://localhost:11434/api/tags

Si la lista de Ollama está vacía, descarga un modelo antes de utilizar la opción Fetch Available Models en Onyx.

Connection refused o error 111

Este error indica que el contenedor o servidor de Onyx no puede alcanzar la dirección especificada. Si Onyx está en Docker y Ollama en el anfitrión, prueba:

http://host.docker.internal:11434

No utilices localhost desde el contenedor para referirte al anfitrión.

host.docker.internal no funciona en Linux

En determinadas instalaciones de Docker Engine para Linux, este nombre no se resuelve automáticamente. Añade una asignación al gateway del anfitrión en la configuración de Compose o utiliza una dirección IP accesible desde la red de Docker.

Onyx muestra el modelo, pero el chat no responde

Ejecuta el modelo directamente con ollama run y revisa los registros de ambos servicios. El modelo puede no caber en la memoria, haberse detenido o no ser compatible correctamente con el tipo de petición enviada.

La primera respuesta tarda demasiado

El modelo necesita cargarse desde el almacenamiento hasta la memoria. Puedes precalentarlo o aumentar moderadamente OLLAMA_KEEP_ALIVE. Si todas las respuestas son lentas, utiliza un modelo más pequeño y comprueba su distribución con ollama ps.

Ollama devuelve un error 503

El servidor está sobrecargado o su cola ha alcanzado el límite. Reduce la cantidad de solicitudes simultáneas, limita los modelos cargados y revisa los valores de concurrencia antes de ampliar la cola.

El modelo responde, pero los agentes fallan al utilizar herramientas

No todos los modelos siguen correctamente los esquemas de las herramientas. Selecciona un modelo con buen seguimiento de instrucciones y soporte para tool calling. Comprueba también que la ventana de contexto sea suficiente para las instrucciones del agente.

Onyx no encuentra información de los documentos

La conexión con Ollama solamente proporciona el modelo generativo. Revisa que estés utilizando Onyx Standard, que los conectores hayan terminado de indexar, que los permisos permitan acceder a los documentos y que la búsqueda interna esté habilitada.

Conectar Onyx con Ollama permite combinar una interfaz de trabajo completa con modelos ejecutados dentro de tu propia infraestructura. El procedimiento consiste en preparar un modelo en Ollama, comprobar su API, introducir en Onyx una dirección accesible desde su entorno y seleccionar los modelos que estarán disponibles para los usuarios.

La parte crítica es la red. Si Onyx se ejecuta en Docker, localhost no apunta al ordenador anfitrión. Una vez resuelto este detalle, podrás utilizar Ollama en chats y agentes, mientras Onyx se encarga de la interfaz, los permisos y, en su despliegue Standard, la recuperación de información empresarial.