# Ollama

La forma más fácil de ejecutar LLMs localmente en GPUs de CLORE.AI.

{% hint style="info" %}
**Versión actual: v0.6+** — Esta guía cubre Ollama v0.6 y posteriores. Las nuevas funciones clave incluyen salidas estructuradas (aplicación de esquemas JSON), endpoint de embeddings compatible con OpenAI (`/api/embed`), y carga concurrente de modelos (ejecuta múltiples modelos simultáneamente sin intercambio). Ver [Novedades en v0.6+](#new-in-v06) para más detalles.
{% endhint %}

{% hint style="success" %}
Todos los ejemplos se pueden ejecutar en servidores GPU alquilados a través de [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Requisitos del servidor

| Parámetro        | Mínimo        | Recomendado |
| ---------------- | ------------- | ----------- |
| RAM              | 8GB           | 16GB+       |
| VRAM             | 6GB           | 8GB+        |
| Red              | 100Mbps       | 500Mbps+    |
| Tiempo de inicio | \~30 segundos | -           |

{% hint style="info" %}
Ollama es liviano y funciona en la mayoría de servidores con GPU. Para modelos más grandes (13B+), elija servidores con 16GB+ de RAM y 12GB+ de VRAM.
{% endhint %}

## ¿Por qué Ollama?

* **Instalación con un comando** - Sin Python, sin dependencias
* **Biblioteca de modelos** - Descarga modelos con `ollama pull`
* **API compatible con OpenAI** - Reemplazo directo
* **Aceleración por GPU** - Detección automática de CUDA
* **Multi-modelo** - Ejecuta múltiples modelos simultáneamente (v0.6+)

## Despliegue rápido en CLORE.AI

**Imagen Docker:**

```
ollama/ollama
```

**Puertos:**

```
22/tcp
11434/http
```

**Comando:**

```bash
ollama serve
```

### Verificar que funciona

Después del despliegue, encuentra tu `http_pub` URL en **Mis Pedidos** y probar:

```bash
# Reemplaza con tu URL http_pub real
curl https://your-http-pub.clorecloud.net/

# Respuesta esperada: "Ollama is running"
```

{% hint style="warning" %}
Si obtienes HTTP 502, espera 30-60 segundos: el servicio aún se está iniciando.
{% endhint %}

## Accediendo a tu servicio

Cuando se implementa en CLORE.AI, accede a tu instancia de Ollama vía `http_pub` URL:

```bash
# Encuentra tu http_pub en My Orders, luego:
curl https://your-http-pub.clorecloud.net/api/tags

# Para llamadas a la API, usa tu URL http_pub:
curl https://your-http-pub.clorecloud.net/api/chat -d '{
  "model": "llama3.2",
  "messages": [{"role": "user", "content": "Hello!"}],
  "stream": false
}'
```

{% hint style="info" %}
Todo `localhost:11434` los ejemplos a continuación funcionan cuando está conectado vía SSH. Para acceso externo, reemplace con su `https://your-http-pub.clorecloud.net/` URL.
{% endhint %}

## Instalación

### Usando Docker (Recomendado)

```bash
docker run -d --gpus all -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama
```

### Instalación manual

```bash
curl -fsSL https://ollama.com/install.sh | sh
```

Este único comando instala la última versión de Ollama, configura el servicio systemd y configura la detección de GPU automáticamente. Funciona en Ubuntu, Debian, Fedora y la mayoría de distribuciones Linux modernas.

## Ejecución de modelos

### Descargar y Ejecutar

```bash
# Descargar modelo
ollama pull llama3.2

# Ejecutar chat interactivo
ollama run llama3.2

# Ejecutar con prompt
ollama run llama3.2 "Explain quantum computing"
```

### Modelos populares

| Modelo              | Tamaño  | Caso de uso                  |
| ------------------- | ------- | ---------------------------- |
| `llama3.2`          | 3B      | Rápido, de propósito general |
| `llama3.1`          | 8B      | Mejor calidad                |
| `llama3.1:70b`      | 70B     | Mejor calidad                |
| `mistral`           | 7B      | Rápido, buena calidad        |
| `mixtral`           | 47B     | MoE, alta calidad            |
| `codellama`         | 7-34B   | Generación de código         |
| `deepseek-coder-v2` | 16B     | Mejor para código            |
| `deepseek-r1`       | 7B-671B | Modelo de razonamiento       |
| `deepseek-r1:32b`   | 32B     | Razonamiento equilibrado     |
| `qwen2.5`           | 7B      | Multilingüe                  |
| `qwen2.5:72b`       | 72B     | Mejor calidad de Qwen        |
| `phi4`              | 14B     | Lo último de Microsoft       |
| `gemma2`            | 9B      | Modelo de Google             |

### Variantes de modelo

```bash
# Variantes de cuantización
ollama pull llama3.1:8b-instruct-q4_K_M   # 4 bits (más pequeño, más rápido)
ollama pull llama3.1:8b-instruct-q8_0     # 8 bits (mejor calidad)
ollama pull llama3.1:8b-instruct-fp16     # Precisión completa

# Variantes de tamaño
ollama pull llama3.1:8b    # 8 mil millones de parámetros
ollama pull llama3.1:70b   # 70 mil millones de parámetros

# Nuevos modelos (era v0.6+)
ollama pull deepseek-r1:7b      # Razonamiento, económico
ollama pull deepseek-r1:14b     # Razonamiento, eficiente
ollama pull deepseek-r1:32b     # Razonamiento, equilibrado
ollama pull deepseek-r1:70b     # Razonamiento, alta calidad
ollama pull qwen2.5:72b         # Qwen más grande, máxima calidad
ollama pull phi4                # Microsoft Phi-4 14B
```

## Novedades en v0.6+

Ollama v0.6 introdujo varias características importantes para cargas de trabajo en producción:

### Salidas estructuradas (Esquema JSON)

Forzar que las respuestas del modelo coincidan con un esquema JSON específico. Útil para construir aplicaciones que necesiten salidas fiables y parseables:

```bash
curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [{"role": "user", "content": "Tell me about Canada."}],
  "format": {
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "capital": {"type": "string"},
      "population": {"type": "integer"},
      "languages": {
        "type": "array",
        "items": {"type": "string"}
      }
    },
    "required": ["name", "capital", "population", "languages"]
  },
  "stream": false
}'
```

Ejemplo en Python con salidas estructuradas:

```python
from openai import OpenAI
import json

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

response = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "List 3 programming languages with their main use cases"}],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "languages",
            "schema": {
                "type": "object",
                "properties": {
                    "languages": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {"type": "string"},
                                "use_case": {"type": "string"},
                                "popularity_rank": {"type": "integer"}
                            }
                        }
                    }
                }
            }
        }
    }
)

data = json.loads(response.choices[0].message.content)
print(data)
```

### Endpoint de embeddings compatible con OpenAI (`/api/embed`)

Novedad en v0.6+: el `/api/embed` endpoint es totalmente compatible con OpenAI y soporta entradas por lotes:

```bash
# Embedding de texto único
curl http://localhost:11434/api/embed -d '{
  "model": "nomic-embed-text",
  "input": "Hello world"
}'

# Embeddings por lotes (nuevo en v0.6)
curl http://localhost:11434/api/embed -d '{
  "model": "nomic-embed-text",
  "input": ["First document", "Second document", "Third document"]
}'
```

El cliente de OpenAI funciona directamente con `/v1/embeddings`:

```python
from openai import OpenAI
import numpy as np

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# Primero descarga el modelo de embedding: ollama pull nomic-embed-text
response = client.embeddings.create(
    model="nomic-embed-text",
    input=["Hello world", "Goodbye world"]
)

emb1 = np.array(response.data[0].embedding)
emb2 = np.array(response.data[1].embedding)

# Similitud coseno
similarity = np.dot(emb1, emb2) / (np.linalg.norm(emb1) * np.linalg.norm(emb2))
print(f"Similarity: {similarity:.4f}")
```

Modelos de embedding populares:

```bash
ollama pull nomic-embed-text      # 137M, rápido, buena calidad
ollama pull mxbai-embed-large     # 335M, mayor calidad
ollama pull all-minilm            # 23M, el más rápido
```

### Carga concurrente de modelos

Antes de v0.6, Ollama descargaba un modelo para cargar otro. V0.6+ soporta ejecutar múltiples modelos simultáneamente, limitado solo por la VRAM disponible:

```bash
# Cargar dos modelos al mismo tiempo
ollama run llama3.2 &
ollama run deepseek-r1:7b &

# Comprueba qué se está ejecutando
curl http://localhost:11434/api/ps
```

Configurar concurrencia:

```bash
# Permitir hasta 4 modelos cargados simultáneamente
OLLAMA_MAX_LOADED_MODELS=4 ollama serve

# Cada runner en un proceso separado (mejor aislamiento)
OLLAMA_NUM_PARALLEL=2 ollama serve
```

Esto es especialmente útil para:

* Pruebas A/B con diferentes modelos
* Modelos especializados para distintas tareas (codificación + chat)
* Mantener modelos de uso frecuente calientes en VRAM

## Uso de la API

### Chat Completion

```bash
# Vía http_pub (acceso externo):
curl https://your-http-pub.clorecloud.net/api/chat -d '{
  "model": "llama3.2",
  "messages": [{"role": "user", "content": "Hello!"}],
  "stream": false
}'

# Vía túnel SSH (localhost):
curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [{"role": "user", "content": "Hello!"}],
  "stream": false
}'
```

{% hint style="info" %}
Agregar `"stream": false` para obtener la respuesta completa de una vez en lugar de transmitirla.
{% endhint %}

### Endpoint compatible con OpenAI

```python
from openai import OpenAI

# Para acceso externo, use su URL http_pub:
client = OpenAI(
    base_url="https://your-http-pub.clorecloud.net/v1",
    api_key="ollama"  # cualquier cadena sirve
)

# O vía túnel SSH:
# client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

response = client.chat.completions.create(
    model="llama3.2",
    messages=[
        {"role": "user", "content": "What is machine learning?"}
    ]
)

print(response.choices[0].message.content)
```

### Streaming

```python
stream = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Write a poem"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

### Embeddings

```bash
# Endpoint legado (todavía funciona)
curl http://localhost:11434/api/embeddings -d '{
  "model": "nomic-embed-text",
  "prompt": "Hello world"
}'

# Nuevo endpoint v0.6+ (soporte por lotes, compatible con OpenAI)
curl http://localhost:11434/api/embed -d '{
  "model": "nomic-embed-text",
  "input": ["Hello world", "Another text"]
}'
```

### Generación de texto (No-Chat)

```bash
curl https://your-http-pub.clorecloud.net/api/generate -d '{
  "model": "llama3.2",
  "prompt": "The meaning of life is",
  "stream": false
}'
```

## Referencia completa de la API

Todos los endpoints funcionan tanto con `http://localhost:11434` (vía SSH) y `https://your-http-pub.clorecloud.net` (externo).

### Gestión de modelos

| Endpoint       | Método | Descripción                             |
| -------------- | ------ | --------------------------------------- |
| `/api/tags`    | GET    | Lista todos los modelos descargados     |
| `/api/show`    | POST   | Obtener detalles del modelo             |
| `/api/pull`    | POST   | Descargar un modelo                     |
| `/api/delete`  | DELETE | Eliminar un modelo                      |
| `/api/ps`      | GET    | Listar modelos actualmente en ejecución |
| `/api/version` | GET    | Obtener la versión de Ollama            |

#### Listar modelos

```bash
curl https://your-http-pub.clorecloud.net/api/tags
```

Respuesta:

```json
{
  "models": [
    {"name": "llama3.2:latest", "size": 2019393189, "digest": "...", "modified_at": "..."}
  ]
}
```

#### Mostrar detalles del modelo

```bash
curl https://your-http-pub.clorecloud.net/api/show -d '{"name": "llama3.2"}'
```

#### Descargar modelo vía API

```bash
curl https://your-http-pub.clorecloud.net/api/pull -d '{
  "name": "mistral:7b",
  "stream": false
}'
```

Respuesta:

```json
{"status": "success"}
```

{% hint style="warning" %}
Los modelos grandes pueden tardar varios minutos en descargarse. Para modelos muy grandes (30GB+), considera usar SSH y la CLI: `ollama pull model-name`
{% endhint %}

#### Eliminar modelo

```bash
curl -X DELETE https://your-http-pub.clorecloud.net/api/delete -d '{"name": "mistral:7b"}'
```

#### Listar modelos en ejecución

```bash
curl https://your-http-pub.clorecloud.net/api/ps
```

Respuesta:

```json
{
  "models": [
    {"name": "llama3.2:latest", "size": 2019393189, "expires_at": "2025-01-25T12:00:00Z"}
  ]
}
```

#### Obtener versión

```bash
curl https://your-http-pub.clorecloud.net/api/version
```

Respuesta:

```json
{"version": "0.6.8"}
```

### Endpoints de inferencia

| Endpoint               | Método | Descripción                                                 |
| ---------------------- | ------ | ----------------------------------------------------------- |
| `/api/generate`        | POST   | Completación de texto                                       |
| `/api/chat`            | POST   | Completación de chat                                        |
| `/api/embeddings`      | POST   | Generar embeddings (legado)                                 |
| `/api/embed`           | POST   | Generar embeddings v0.6+ (por lotes, compatible con OpenAI) |
| `/v1/chat/completions` | POST   | Chat compatible con OpenAI                                  |
| `/v1/embeddings`       | POST   | Embeddings compatibles con OpenAI                           |

### Creación de modelos personalizados

Crea modelos personalizados con prompts de sistema específicos vía API:

```bash
curl https://your-http-pub.clorecloud.net/api/create -d '{
  "name": "my-assistant",
  "modelfile": "FROM llama3.2\nSYSTEM You are a helpful coding assistant."
}'
```

## Configuración de GPU

### Comprobar uso de GPU

```bash
# En contenedor o servidor
nvidia-smi

# Ollama muestra la GPU en los logs
ollama run llama3.2 --verbose
```

### Multi-GPU

Ollama usa automáticamente las GPUs disponibles. Para una GPU específica:

```bash
CUDA_VISIBLE_DEVICES=0 ollama serve
```

### Gestión de memoria

```bash
# Establecer límite de memoria de GPU
OLLAMA_GPU_MEMORY=8GiB ollama serve

# Mantener el modelo cargado
OLLAMA_KEEP_ALIVE=24h ollama serve

# Permitir modelos concurrentes (v0.6+)
OLLAMA_MAX_LOADED_MODELS=3 ollama serve
```

## Modelos personalizados (Modelfile)

Crear modelos personalizados con prompts de sistema:

```dockerfile
# Modelfile
FROM llama3.2

SYSTEM You are a helpful coding assistant. Always provide code examples.

PARAMETER temperature 0.7
PARAMETER top_p 0.9
```

```bash
ollama create coding-assistant -f Modelfile
ollama run coding-assistant
```

## Ejecución como servicio

### Systemd

```ini
# /etc/systemd/system/ollama.service
[Unit]
Description=Ollama Service
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/ollama serve
Restart=always
Environment="OLLAMA_HOST=0.0.0.0"

[Install]
WantedBy=multi-user.target
```

```bash
systemctl enable ollama
systemctl start ollama
```

## Consejos de rendimiento

1. **Usa la cuantización apropiada**
   * Q4\_K\_M para velocidad
   * Q8\_0 para calidad
   * fp16 para máxima calidad
2. **Ajusta el modelo a la VRAM**
   * 8GB: modelos 7B (Q4)
   * 16GB: modelos 13B o 7B (Q8)
   * 24GB: modelos 34B (Q4)
   * 48GB+: modelos 70B
3. **Mantener el modelo cargado**

   ```bash
   OLLAMA_KEEP_ALIVE=1h ollama serve
   ```
4. **Un SSD rápido mejora el rendimiento**
   * La carga de modelos y la caché KV se benefician de un almacenamiento rápido
   * Los servidores con SSD NVMe pueden lograr 2-3x mejor rendimiento

## Benchmarks

### Velocidad de generación (tokens/seg)

| Modelo               | RTX 3060 | RTX 3090 | RTX 4090 | A100 40GB |
| -------------------- | -------- | -------- | -------- | --------- |
| Llama 3.2 3B (Q4)    | 120      | 160      | 200      | 220       |
| Llama 3.1 8B (Q4)    | 60       | 100      | 130      | 150       |
| Llama 3.1 8B (Q8)    | 45       | 80       | 110      | 130       |
| Mistral 7B (Q4)      | 70       | 110      | 140      | 160       |
| Mixtral 8x7B (Q4)    | -        | 35       | 55       | 75        |
| Llama 3.1 70B (Q4)   | -        | -        | 18       | 35        |
| DeepSeek-R1 7B (Q4)  | 65       | 105      | 135      | 155       |
| DeepSeek-R1 32B (Q4) | -        | -        | 22       | 42        |
| Qwen2.5 72B (Q4)     | -        | -        | 15       | 30        |
| Phi-4 14B (Q4)       | -        | 50       | 75       | 90        |

*Benchmarks actualizados en enero de 2026. Las velocidades reales pueden variar según la configuración del servidor.*

### Tiempo hasta el primer token (ms)

| Modelo | RTX 3090 | RTX 4090 | A100 |
| ------ | -------- | -------- | ---- |
| 3B     | 50       | 35       | 25   |
| 7-8B   | 120      | 80       | 60   |
| 13B    | 250      | 150      | 100  |
| 34B    | 600      | 350      | 200  |
| 70B    | -        | 1200     | 500  |

### Longitud de contexto vs VRAM (Q4)

| Modelo | 2K ctx | 4K ctx | 8K ctx | 16K ctx |
| ------ | ------ | ------ | ------ | ------- |
| 7B     | 5GB    | 6GB    | 8GB    | 12GB    |
| 13B    | 8GB    | 10GB   | 14GB   | 22GB    |
| 34B    | 20GB   | 24GB   | 32GB   | 48GB    |
| 70B    | 40GB   | 48GB   | 64GB   | 96GB    |

## Requisitos de GPU

| Modelo | VRAM Q4 | VRAM Q8 |
| ------ | ------- | ------- |
| 3B     | 3GB     | 5GB     |
| 7-8B   | 5GB     | 9GB     |
| 13B    | 8GB     | 15GB    |
| 34B    | 20GB    | 38GB    |
| 70B    | 40GB    | 75GB    |

## Estimación de costos

Tarifas típicas del mercado de CLORE.AI:

| GPU      | VRAM | Precio/día | Bueno para           |
| -------- | ---- | ---------- | -------------------- |
| RTX 3060 | 12GB | $0.15–0.30 | Modelos 7B           |
| RTX 3090 | 24GB | $0.30–1.00 | Modelos 13B-34B      |
| RTX 4090 | 24GB | $0.50–2.00 | Modelos 34B, rápidos |
| A100     | 40GB | $1.50–3.00 | Modelos 70B          |

*Precios en USD/día. Las tarifas varían según el proveedor: consulte* [*CLORE.AI Marketplace*](https://clore.ai/marketplace) *para las tarifas actuales.*

## Solución de problemas

### El modelo no se carga

```bash
# Comprobar memoria disponible
nvidia-smi

# Prueba una cuantización más pequeña
ollama pull llama3.1:8b-q4_0
```

### Generación lenta

```bash
# Comprobar si se usa la GPU
ollama run llama3.2 --verbose

# Asegurarse de que CUDA esté disponible
nvidia-smi
```

### Conexión rehusada

```bash
# Asegúrate de que el servidor esté en funcionamiento
ollama serve

# Comprueba si está enlazando a todas las interfaces
OLLAMA_HOST=0.0.0.0 ollama serve
```

### HTTP 502 en la URL http\_pub

Esto significa que el servicio aún se está iniciando. Espera 30-60 segundos y vuelve a intentarlo:

```bash
# Comprobar si el servicio está listo
curl https://your-http-pub.clorecloud.net/

# Esperado: "Ollama is running"
# Si 502: espera y vuelve a intentar
```

## Próximos pasos

* [Abrir WebUI](https://docs.clore.ai/guides/guides_v2-es/modelos-de-lenguaje/open-webui) - Hermosa interfaz de chat para Ollama
* [vLLM](https://docs.clore.ai/guides/guides_v2-es/modelos-de-lenguaje/vllm) - Servicio de producción de alto rendimiento
* [DeepSeek-R1](https://docs.clore.ai/guides/guides_v2-es/modelos-de-lenguaje/deepseek-r1) - Modelo de razonamiento
* [DeepSeek-V3](https://docs.clore.ai/guides/guides_v2-es/modelos-de-lenguaje/deepseek-v3) - Mejor modelo general
* [Qwen2.5](https://docs.clore.ai/guides/guides_v2-es/modelos-de-lenguaje/qwen25) - Alternativa multilingüe
* [Text Generation WebUI](https://docs.clore.ai/guides/guides_v2-es/modelos-de-lenguaje/text-generation-webui) - Funciones avanzadas