Arquitectura de Ollama: servidor, modelos, CLI y API

Visión general de la arquitectura

Ollama sigue una arquitectura cliente-servidor: un servidor (proceso en segundo plano) es el que realmente carga los modelos, ejecuta la inferencia y responde a las peticiones. Las aplicaciones y el usuario no hablan directamente con el modelo, sino con ese servidor a través de dos interfaces principales: la CLI (ollama en terminal) y la API REST.

Tanto si usas modelos locales como si usas Ollama Cloud, la idea es la misma: hay un "backend" que gestiona los modelos y un "cliente" (CLI, aplicación, script) que envía peticiones y recibe respuestas. Entender esta separación te ayuda a ver por qué la misma herramienta sirve para uso interactivo en terminal y para integraciones desde código o desde otras aplicaciones.

El servidor: local y en la nube

El servidor es el componente que:

• Carga los modelos (desde disco en local o desde la infraestructura de Ollama en la nube).
• Ejecuta la inferencia (generación de texto, chat, embeddings, etc.).
• Escucha peticiones en un puerto (en local, por defecto el 11434) o recibe peticiones hacia los endpoints de Ollama Cloud.

En una instalación local, el servidor suele arrancar automáticamente cuando usas la aplicación de escritorio o el comando ollama por primera vez. Se ejecuta en tu máquina y solo atiende peticiones desde el mismo equipo (o desde la red si se configura así). Los modelos se descargan y se guardan en tu disco.

En Ollama Cloud, el servidor está en los centros de datos de Ollama. Tú no lo instalas ni lo mantienes, solo te autenticas (cuenta, API key) y envías peticiones a sus endpoints. Los modelos están en su infraestructura y la inferencia se hace allí.

En ambos casos, la lógica es la misma: un servidor que recibe peticiones, elige el modelo adecuado (local o :cloud) y devuelve la respuesta. La diferencia está en dónde corre ese servidor y dónde están almacenados los modelos.

Registro de modelos

Ollama mantiene un registro (lista) de modelos disponibles para esa instalación. En local, ese registro refleja los modelos que has descargado en tu máquina (con ollama pull u otras vías). Cada modelo tiene un nombre y, opcionalmente, una etiqueta o tag (por ejemplo, versión o variante). Cuando pides usar un modelo por nombre, el servidor local busca en ese registro y carga el modelo desde disco si está disponible.

Cuando usas el sufijo :cloud, en la práctica estás indicando que el modelo no debe buscarse en el registro local, sino que la petición debe enviarse al servicio en la nube. El registro de modelos en la nube lo gestiona Ollama, y tú solo eliges el nombre del modelo (por ejemplo, llama3.2:cloud) y el servidor remoto se encarga del resto.

Así, el registro es el mecanismo que permite al servidor saber qué modelos tiene disponibles (locales o remotos) y cuál cargar o invocar para cada petición.

La CLI como cliente

La CLI (ollama en la terminal) es un cliente del servidor. Comandos como ollama run, ollama list o ollama pull no ejecutan el modelo por sí mismos: envían peticiones al servidor (local o, en su caso, a la nube) y muestran la respuesta en la terminal.

La CLI sirve para:

• Gestionar modelos (listar, descargar, eliminar).
• Ejecutar modelos de forma interactiva (chat en terminal).
• Lanzar el servidor o comprobar su estado cuando corresponde.

Todo lo que hace la CLI podría hacerse, en principio, llamando directamente a la API: la CLI es una forma cómoda de usar esa API desde la línea de comandos. Los comandos concretos y sus opciones permiten listar, descargar y ejecutar modelos desde la terminal.

La API como interfaz para aplicaciones

La API REST es la interfaz que usan aplicaciones, scripts e integraciones (por ejemplo, un plugin del editor, un backend en Python o una app web). En lugar de teclear comandos, el cliente envía peticiones HTTP (por ejemplo, POST a un endpoint de generación o de chat) y recibe la respuesta en JSON (o en streaming).

Ventajas de basar las integraciones en la API:

• Cualquier lenguaje o herramienta que pueda hacer HTTP puede usar Ollama.
• Se puede implementar streaming (respuestas que van llegando por fragmentos).
• Es la misma API que usan clientes compatibles con OpenAI: configurando la URL base y, en su caso, la API key de Ollama Cloud, muchas librerías funcionan sin cambios.

En local, la API suele estar en localhost en un puerto por defecto (11434). En la nube, la base URL y la autenticación cambian, pero el esquema de peticiones y respuestas es coherente. Los endpoints, parámetros y formato de la API permiten integrar Ollama desde cualquier aplicación que pueda enviar peticiones HTTP.

Cómo encajan los componentes

flowchart LR
  subgraph Cliente
    CLI[CLI ollama]
    APP[App / Script]
  end
  subgraph Servidor
    S[Servidor Ollama]
    R[(Registro modelos)]
  end
  CLI -->|Comandos| S
  APP -->|HTTP / API| S
  S --> R
  R --> Modelo[Modelo local o cloud]
  S --> Modelo

El cliente (CLI o aplicación) envía peticiones al servidor. El servidor consulta el registro de modelos para saber qué modelo usar (local o :cloud), lo carga o lo invoca y devuelve la respuesta al cliente. Tanto la CLI como las aplicaciones que usan la API se apoyan en el mismo servidor y en el mismo registro conceptual, y la única diferencia es el canal (comandos frente a HTTP).

Con esta visión general tienes la base para entender la instalación del servidor, los comandos de la CLI y el uso de la API en detalle.