Variables de entorno y configuración del servicio de Ollama

Ollama no tiene un archivo de configuración tradicional; el comportamiento del servicio está controlado casi por completo por variables de entorno: dirección de escucha, ruta de modelos, contexto, concurrencia, proxy y depuración.

Este capítulo primero explica los métodos de configuración en las tres plataformas y luego aclara cada variable central en tres niveles: entrada de red, programación de solicitudes y ejecución de modelos.

Ubicación de las variables de configuración en el servicio

Primero establezcamos un mapa: la docena de variables de entorno no están al mismo nivel; cada una actúa en una etapa distinta del proceso del servicio.

Para ver la lista completa de variables compatibles con la versión actual, ejecuta ollama serve --help.

Métodos para establecer variables de entorno en las tres plataformas

La misma variable se configura en entradas completamente diferentes según la plataforma; es donde los principiantes suelen atascarse.

macOS：launchctl

Cuando Ollama se ejecuta como aplicación, las variables de entorno deben inyectarse mediante launchctl; tras configurarlas, reinicia la aplicación para que surtan efecto:

Linux: anulación del servicio systemd

Windows: Variables de entorno del sistema

En el menú Inicio, busca "variables de entorno", selecciona "Editar las variables de entorno de su cuenta", crea o edita la variable y guarda.

Paso clave: primero sal de Ollama en la bandeja; después de guardar, reinícialo desde el menú Inicio para que las nuevas variables surtan efecto en el nuevo proceso.

Además, hay un archivo de configuración JSON server.json (ubicado en ~/.ollama/) para algunas configuraciones de tipo conmutador; por ejemplo, para desactivar las funciones en la nube escribe {"disable_ollama_cloud": true}. La gran mayoría de la configuración sigue rigiéndose por las variables de entorno.

Entrada de red: HOST, ORIGINS y proxy

OLLAMA_HOST: permite que la red local acceda a tus modelos

Por defecto solo escucha en 127.0.0.1, por lo que solo está disponible localmente; si quieres que otros dispositivos de la red local lo usen, cambia para que escuche en todas las interfaces de red:

Exponer el servicio a la red local equivale a dejarlo accesible sin autenticación para todos los dispositivos de la misma subred; en una red doméstica puede ser aceptable, pero en una red corporativa es imprescindible combinarlo con reglas de firewall o un proxy inverso (se trata en detalle en el capítulo de despliegue privado).

OLLAMA_ORIGINS: permitir solicitudes entre dominios (CORS)

Ollama, por defecto, solo acepta solicitudes de origen cruzado desde 127.0.0.1 y 0.0.0.0; cuando una página web o una extensión del navegador se conecta directamente a la API local, debes permitirlo explícitamente:

Proxy: solo HTTPS_PROXY

La descarga de modelos se realiza mediante HTTPS saliente; en entornos con restricciones de red, basta con usar HTTPS_PROXY para apuntar al proxy.

Configura únicamente HTTPS_PROXY, no HTTP_PROXY: Ollama no descarga modelos mediante HTTP; añadir un proxy HTTP podría incluso interrumpir la conexión entre cliente y servidor. En Docker, pasa -e HTTPS_PROXY=... al iniciar el contenedor; si el proxy usa un certificado autofirmado, también debes instalar el certificado CA en el sistema (o incluirlo en la imagen).

Ejecución de modelos: ruta, contexto y persistencia

OLLAMA_MODELS: guardar los modelos en otra unidad

Los modelos se almacenan por defecto en el directorio del usuario; las rutas en las tres plataformas son las siguientes:

Basta con apuntar OLLAMA_MODELS al nuevo directorio para migrarlo por completo; una vez movidos los archivos de modelos descargados, pueden usarse directamente.

OLLAMA_CONTEXT_LENGTH: contexto global

Establece la longitud de contexto predeterminada para todos los modelos; se aplica cuando no se especifica una distinta a nivel de modelo o de solicitud:

La prioridad, de mayor a menor, es: options.num_ctx de la solicitud API, PARAMETER num_ctx en el Modelfile, esta variable de entorno y el valor predeterminado de nivel automático según la memoria de video (VRAM).

OLLAMA_KEEP_ALIVE: duración de persistencia global

Ajusta de forma uniforme el tiempo que el modelo permanece cargado; el formato de valores es el mismo que el parámetro keep_alive de la API:

El keep_alive pasado individualmente en las solicitudes API tiene prioridad sobre este valor global, lo que permite una estrategia por niveles como "10 minutos global, modelos importantes siempre cargados".

Programación de solicitudes: el trío de concurrencia

Ollama admite dos niveles de concurrencia: varios modelos cargados simultáneamente y un solo modelo procesando varias solicitudes en paralelo; cada nivel está controlado por una variable.

Merece la pena entender la lógica de programación: cuando hay suficiente memoria de video, el modelo procesa las solicitudes en paralelo; cuando no hay suficiente, las nuevas solicitudes hacen cola y esperan a que los modelos ociosos se descarguen para liberar espacio.

NUM_PARALLEL es la variable con la que es más fácil cometer errores: establecerla en 4 significa que la caché de contexto se multiplica por 4, la memoria de video se cuadruplica de inmediato y el modelo podría ser expulsado de la GPU. El método de planificación para instancias compartidas por múltiples usuarios se desarrolla en el capítulo de despliegue privado.

Depuración y registros: OLLAMA_DEBUG

El primer paso para solucionar problemas siempre es activar la depuración y revisar los registros.

Para activar la depuración en la aplicación gráfica de Windows: primero sal de la aplicación desde la bandeja y luego ejecuta en PowerShell:

Resumen de las ubicaciones de registros en los cuatro entornos:

Referencia rápida de otras variables útiles

Las demás variables suelen estar ligadas a escenarios específicos; la explicación completa por capítulos se desarrolla en los temas correspondientes. Aquí solo establecemos un índice.