← Volver al listado de tecnologías ← Índice de OpenCode

Capitulo 10: Ollama y Modelos Locales

4 de abril de 2026 Por: Artiko

opencodeaiollamamodelos-localesprivacidad

Capitulo 10: Ollama y Modelos Locales

Ejecutar modelos localmente te da privacidad total, sin costo por token, funcionamiento offline y libertad para experimentar sin límites. Este capítulo cubre en profundidad cómo configurar Ollama, llama.cpp y LM Studio como proveedores de OpenCode, incluyendo la configuración correcta en opencode.json, optimización de rendimiento y solución de problemas comunes.

Por qué Modelos Locales

Las razones para ejecutar modelos en tu propia máquina van más allá del ahorro económico:

Privacidad: tu código nunca sale de tu máquina. Ningún proveedor externo procesa, almacena ni entrena con tus datos.
Sin costo por token: una vez descargado el modelo, el uso es completamente gratuito. Puedes ejecutar miles de peticiones sin preocuparte por la factura.
Offline: funciona sin conexión a internet. Ideal para aviones, zonas rurales o redes corporativas restrictivas.
Experimentación: prueba diferentes modelos, parámetros y configuraciones sin preocuparte por costos. Puedes iterar cientos de veces sobre un prompt.
Cumplimiento normativo: algunas empresas y sectores (finanzas, salud, defensa) requieren que los datos no salgan de su infraestructura bajo ningún concepto.
Latencia predecible: sin depender de la red ni de la carga de servidores remotos. La velocidad depende únicamente de tu hardware.

flowchart LR
    A[Tu código] --> B[Ollama local]
    B --> C[Modelo en tu GPU/CPU]
    C --> D[Respuesta]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e9
    style D fill:#e1f5fe

La desventaja principal es que los modelos locales son menos capaces que los modelos cloud de frontera (Claude Opus, GPT-4o). Sin embargo, para muchas tareas de desarrollo — generar tests, escribir funciones pequeñas, refactorizar código simple — los modelos locales son más que suficientes.

Ollama (Recomendado)

Ollama es la forma más sencilla de ejecutar modelos locales. Gestiona la descarga, cuantización, configuración y ejecución de modelos con un solo comando. Además, expone una API compatible con OpenAI, lo que facilita la integración con OpenCode.

Instalación

# Linux y macOS
curl -fsSL https://ollama.ai/install.sh | sh

# Verificar instalación
ollama --version

# Iniciar el servicio (si no se inició automáticamente)
ollama serve

En macOS, Ollama también está disponible como aplicación de escritorio con icono en la barra de menús. En Windows, hay un instalador nativo.

Modelos Recomendados para Coding

# Descargar modelos
ollama pull llama3.3:latest
ollama pull qwen2.5-coder:32b
ollama pull deepseek-coder-v2
ollama pull codellama:34b
ollama pull gemma3:27b
ollama pull phi4:latest

Modelo	Tamaño	RAM/VRAM	Uso recomendado
`llama3.3:latest`	~4GB	8GB	Uso general rápido
`qwen2.5-coder:32b`	~20GB	24GB+	Mejor balance calidad/velocidad para código
`deepseek-coder-v2`	~8GB	16GB	Buena relación calidad/tamaño
`codellama:34b`	~19GB	24GB+	Optimizado específicamente para código
`gemma3:27b`	~17GB	24GB+	Buen rendimiento multilingüe
`phi4:latest`	~8GB	16GB	Compacto y eficiente

La elección del modelo depende de tu hardware. Si tienes una GPU con 24GB+ de VRAM (RTX 3090, RTX 4090, A5000), los modelos de 32B-34B ofrecen la mejor experiencia. Con 16GB de VRAM (RTX 4080, A4000), los modelos de 7B-14B son la mejor opción.

Configurar en OpenCode

La configuración correcta en opencode.json usa el adaptador @ai-sdk/openai-compatible apuntando al servidor local de Ollama:

{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (local)",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "llama3.3:latest": { "name": "Llama 3.3" },
        "qwen2.5-coder:32b": { "name": "Qwen 2.5 Coder 32B" },
        "deepseek-coder-v2": { "name": "DeepSeek Coder V2" },
        "codellama:34b": { "name": "Code Llama 34B" },
        "gemma3:27b": { "name": "Gemma 3 27B" },
        "phi4:latest": { "name": "Phi-4" }
      }
    }
  }
}

Observa la estructura:

npm: indica qué paquete del AI SDK usar para la comunicación.
name: nombre que aparece en la interfaz de OpenCode al seleccionar proveedor.
options.baseURL: apunta al endpoint v1 de Ollama. El /v1 es importante porque Ollama expone una API compatible con OpenAI en esa ruta.
models: mapa de modelos disponibles. La clave debe coincidir exactamente con el nombre del modelo en Ollama (lo que devuelve ollama list).

Después de guardar la configuración, abre OpenCode y usa /models para seleccionar uno de los modelos listados.

Aumentar Ventana de Contexto (num_ctx)

Si las llamadas de herramientas no funcionan, intenta aumentar num_ctx en Ollama. Comienza alrededor de 16k - 32k.

Este es el consejo más importante de este capítulo. Por defecto, Ollama usa una ventana de contexto de 2048 tokens, lo cual es insuficiente para OpenCode. Las herramientas (file read, bash, grep, etc.) necesitan espacio en el contexto para enviar las definiciones y recibir resultados. Si la ventana es muy pequeña, las llamadas a herramientas simplemente no funcionarán.

Opción 1: Variable de entorno

export OLLAMA_NUM_CTX=32768
ollama serve

Opción 2: Configuración systemd (persistente en Linux)

sudo mkdir -p /etc/systemd/system/ollama.service.d/
sudo tee /etc/systemd/system/ollama.service.d/override.conf << 'EOF'
[Service]
Environment="OLLAMA_NUM_CTX=32768"
EOF

sudo systemctl daemon-reload
sudo systemctl restart ollama

Opción 3: Modelfile personalizado

# Crear archivo Modelfile
cat > Modelfile << 'EOF'
FROM qwen2.5-coder:32b
PARAMETER num_ctx 32768
EOF

ollama create qwen-32k -f Modelfile

Esta opción crea un modelo derivado con la ventana de contexto ya configurada. La ventaja es que no necesitas recordar la variable de entorno cada vez.

Valores recomendados según el modelo:

Modelo	num_ctx recomendado	Nota
Modelos 7B	16384	Suficiente para herramientas básicas
Modelos 13-14B	16384-32768	Buen balance
Modelos 32-34B	32768	Ideal para OpenCode
Modelos 70B	16384	Más consume RAM, ajustar según hardware

Ten en cuenta que aumentar num_ctx incrementa el consumo de VRAM/RAM proporcionalmente. Un modelo de 32B con num_ctx=32768 puede necesitar 4-8GB adicionales de VRAM respecto a la configuración por defecto.

Listar y Gestionar Modelos

# Ver modelos descargados
ollama list

# Información detallada de un modelo
ollama show qwen2.5-coder:32b

# Eliminar un modelo
ollama rm codellama:34b

# Ejecutar un modelo directamente (para probar)
ollama run qwen2.5-coder:32b

# Copiar un modelo con otro nombre
ollama cp qwen2.5-coder:32b qwen-coding

Solución de Problemas Comunes con Ollama

Las herramientas no funcionan (tool calling): Aumenta num_ctx a 16384 o 32768. Este es el problema más frecuente.

El modelo responde muy lento: Verifica que el modelo esté corriendo en GPU. Ejecuta ollama ps para ver si el modelo está cargado y en qué dispositivo. Si dice cpu, necesitas instalar los drivers de GPU correctos.

Error “out of memory”: El modelo es demasiado grande para tu VRAM. Prueba con un modelo más pequeño o con una cuantización más agresiva (Q4 en lugar de Q8).

Error “connection refused”: Ollama no está corriendo. Ejecuta ollama serve o verifica el servicio con systemctl status ollama.

Respuestas cortadas o incompletas: Puede ser un problema de num_ctx insuficiente. También verifica que no estés usando un modelo demasiado pequeño para la tarea.

llama.cpp

Para control total sobre la inferencia. llama.cpp es el motor que Ollama usa internamente, pero acceder a él directamente te da máxima flexibilidad sobre parámetros de generación, cuantización y uso de hardware.

Instalación

git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp

# Compilar con soporte CUDA (NVIDIA)
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# Compilar con soporte Metal (macOS Apple Silicon)
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release

# Compilar sin GPU (solo CPU)
cmake -B build
cmake --build build --config Release

Ejecutar servidor compatible con OpenAI

./build/bin/llama-server \
  -m ./models/mi-modelo.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  -c 32768 \
  -ngl 99

Parámetros clave:

-m: ruta al archivo del modelo en formato GGUF.
-c: tamaño de la ventana de contexto (equivalente a num_ctx de Ollama).
-ngl: número de capas a cargar en GPU. Usa 99 para cargar todo el modelo en GPU.
—host: interfaz de red. Usa 0.0.0.0 para acceso desde otros equipos.

Configurar en OpenCode

{
  "provider": {
    "llamacpp": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://127.0.0.1:8080/v1"
      },
      "models": {
        "mi-modelo": { "name": "Mi Modelo Local" }
      }
    }
  }
}

La configuración sigue el mismo patrón que Ollama: npm con @ai-sdk/openai-compatible, baseURL apuntando al servidor local y un mapa de modelos disponibles.

LM Studio

GUI para gestionar y ejecutar modelos locales. Ideal si prefieres una interfaz gráfica para descargar, configurar y probar modelos antes de usarlos con OpenCode.

Descargar desde lmstudio.ai
Buscar y descargar el modelo deseado desde la interfaz
Ir a la pestaña “Local Server” y activar el servidor
El servidor expone una API compatible con OpenAI en http://localhost:1234/v1

Configurar en OpenCode

{
  "provider": {
    "lmstudio": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://127.0.0.1:1234/v1"
      },
      "models": {
        "nombre-del-modelo": { "name": "Nombre para mostrar" }
      }
    }
  }
}

LM Studio tiene la ventaja de ofrecer una interfaz visual para monitorear el rendimiento del modelo en tiempo real: tokens por segundo, uso de VRAM, temperatura y otros parámetros.

Ollama Remoto

Si tienes Ollama corriendo en otra máquina (por ejemplo, un servidor con GPU potente en tu red local o un servidor cloud):

{
  "provider": {
    "ollama-remoto": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (servidor)",
      "options": {
        "baseURL": "http://192.168.1.100:11434/v1"
      },
      "models": {
        "qwen2.5-coder:32b": { "name": "Qwen 2.5 Coder 32B (remoto)" }
      }
    }
  }
}

Asegúrate de que el puerto 11434 esté accesible y que Ollama escuche en todas las interfaces:

export OLLAMA_HOST=0.0.0.0
ollama serve

Esta configuración es poderosa para equipos: un servidor central con GPUs potentes puede servir modelos a todos los desarrolladores del equipo sin que cada uno necesite hardware especializado.

Consideraciones de seguridad para Ollama remoto

No expongas Ollama a internet sin autenticación. El servidor no tiene autenticación nativa.
Usa una VPN o red privada para el acceso remoto.
Considera un proxy reverso (nginx, caddy) con autenticación básica si necesitas acceso desde fuera de la red local.

Docker con GPU

NVIDIA

# docker-compose.yml
services:
  ollama:
    image: ollama/ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    environment:
      - OLLAMA_NUM_CTX=32768
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  ollama_data:

# Alternativa con docker run
docker run -d \
  --gpus all \
  -e OLLAMA_NUM_CTX=32768 \
  -v ollama:/root/.ollama \
  -p 11434:11434 \
  --name ollama \
  ollama/ollama

Después de iniciar el contenedor, descarga los modelos:

docker exec ollama ollama pull qwen2.5-coder:32b

Nota que incluimos OLLAMA_NUM_CTX=32768 directamente en la configuración de Docker para que la ventana de contexto esté correcta desde el inicio.

Tabla Comparativa

Herramienta	Facilidad	Rendimiento	GPU Support	Ideal para
Ollama	Alta	Bueno	NVIDIA, AMD, Metal	Empezar rápido, uso diario
llama.cpp	Baja	Máximo	NVIDIA, AMD, Metal	Control total, optimización
LM Studio	Alta	Bueno	NVIDIA, AMD, Metal	Interfaz gráfica, explorar modelos

Requerimientos de Hardware

graph LR
    A[Modelos 7B] -->|8GB VRAM| B[GTX 1080, RTX 3060]
    C[Modelos 13-14B] -->|16GB VRAM| D[RTX 4080, A4000]
    E[Modelos 32-34B] -->|24GB+ VRAM| F[RTX 3090, RTX 4090]
    G[Modelos 70B] -->|48GB+ VRAM| H[A6000, 2x RTX 3090]

Modelos 7B: 8GB RAM/VRAM mínimo
Modelos 13-14B: 16GB RAM/VRAM recomendado
Modelos 32-34B: 24GB+ VRAM (o 64GB RAM en CPU)
Modelos 70B: 48GB+ VRAM (o 128GB RAM en CPU)

La ejecución en CPU es posible pero significativamente más lenta que en GPU. Para un modelo de 7B en CPU, espera ~5-10 tokens por segundo. En GPU, el mismo modelo genera 40-80 tokens por segundo.

Apple Silicon

Los Mac con Apple Silicon (M1, M2, M3, M4) ofrecen una experiencia sorprendentemente buena para modelos locales gracias a la memoria unificada. Un Mac con 32GB de RAM unificada puede ejecutar modelos de 32B cómodamente. Los chips M3 Max y M4 Max con 64-128GB son capaces de ejecutar modelos de 70B.

Configuración Recomendada para Empezar

Si estás empezando con modelos locales y OpenCode, esta es la configuración mínima recomendada:

Instala Ollama
Descarga qwen2.5-coder:32b si tienes 24GB+ VRAM, o deepseek-coder-v2 si tienes 16GB
Configura OLLAMA_NUM_CTX=32768
Añade la configuración a opencode.json
Prueba con una tarea simple: “lee este archivo y explica qué hace”

Si las herramientas no responden, lo primero es verificar num_ctx. En la gran mayoría de casos, ese es el problema.

Siguiente: Capitulo 11: OpenCode Zen —>