# LocalAI

Ejecute una API compatible con OpenAI autohospedada con LocalAI.

{% 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              | 200Mbps          | 500Mbps+    |
| Tiempo de inicio | **5-10 minutos** | -           |

{% hint style="warning" %}
**Importante:** LocalAI tarda 5-10 minutos en inicializarse completamente en el primer arranque. HTTP 502 durante este tiempo es normal: el servicio está descargando y cargando modelos.
{% endhint %}

{% hint style="info" %}
LocalAI es ligero. Para ejecutar LLMs (modelos 7B+), elija servidores con 16GB+ de RAM y 8GB+ de VRAM.
{% endhint %}

## ¿Qué es LocalAI?

LocalAI proporciona:

* Reemplazo directo de la API de OpenAI
* Soporte para múltiples formatos de modelos
* Generación de texto, imagen, audio y embeddings
* No se requiere GPU (pero es más rápido con GPU)

## Modelos compatibles

| Tipo       | Formatos    | Ejemplos            |
| ---------- | ----------- | ------------------- |
| LLM        | GGUF, GGML  | Llama, Mistral, Phi |
| Embeddings | GGUF        | all-MiniLM, BGE     |
| Imágenes   | Diffusers   | SD 1.5, SDXL        |
| Audio      | Whisper     | De voz a texto      |
| TTS        | Piper, Bark | Texto a voz         |

## Despliegue rápido

**Imagen Docker:**

```
localai/localai:master-aio-gpu-nvidia-cuda-12
```

**Puertos:**

```
22/tcp
8080/http
```

**No se necesita comando** - el servidor se inicia automáticamente.

### Verificar que funciona

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

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

# Listar modelos disponibles
curl https://your-http-pub.clorecloud.net/v1/models

# Obtener versión
curl https://your-http-pub.clorecloud.net/version
```

{% hint style="warning" %}
Si obtiene HTTP 502, espere 5-10 minutos: LocalAI tarda más en inicializarse que otros servicios.
{% endhint %}

## Modelos preinstalados

LocalAI viene con varios modelos disponibles listos para usar:

| Nombre del modelo          | Tipo           | Descripción                  |
| -------------------------- | -------------- | ---------------------------- |
| `gpt-4`                    | Chat           | LLM de propósito general     |
| `gpt-4o`                   | Chat           | LLM de propósito general     |
| `gpt-4o-mini`              | Chat           | LLM más pequeño y rápido     |
| `whisper-1`                | STT            | De voz a texto               |
| `tts-1`                    | TTS            | Texto a voz                  |
| `text-embedding-ada-002`   | Embeddings     | Vectores de 384 dimensiones  |
| `jina-reranker-v1-base-en` | Reordenamiento | Reordenamiento de documentos |

{% hint style="info" %}
Estos modelos funcionan inmediatamente después del arranque sin configuración adicional.
{% endhint %}

## Accediendo a tu servicio

Cuando se despliega en CLORE.AI, acceda a LocalAI a través de la `http_pub` URL:

```bash
# Completado de chat
curl https://your-http-pub.clorecloud.net/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "gpt-4",
        "messages": [{"role": "user", "content": "¡Hola!"}]
    }'
```

{% hint style="info" %}
Todo `localhost:8080` 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 %}

## Despliegue con Docker (alternativa)

```bash
docker run -d \
    --gpus all \
    -p 8080:8080 \
    -v /workspace/models:/models \
    -e THREADS=4 \
    -e CONTEXT_SIZE=4096 \
    localai/localai:master-aio-gpu-nvidia-cuda-12
```

## Descargar modelos

### Desde la galería de modelos

LocalAI tiene una galería de modelos incorporada:

```bash
# Listar modelos disponibles
curl http://localhost:8080/models/available

# Instalar desde la galería
curl http://localhost:8080/models/apply -d '{"id": "mistral-7b-instruct"}'
```

### Desde Hugging Face

```bash
mkdir -p /workspace/models

# Llama 3.1 8B GGUF
wget https://huggingface.co/bartowski/Meta-Llama-3.1-8B-Instruct-GGUF/resolve/main/Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf \
    -O /workspace/models/llama-3.1-8b.gguf

# Mistral 7B GGUF
wget https://huggingface.co/bartowski/Mistral-7B-Instruct-v0.3-GGUF/resolve/main/Mistral-7B-Instruct-v0.3-Q4_K_M.gguf \
    -O /workspace/models/mistral-7b.gguf
```

## Configuración del modelo

Cree un archivo YAML de configuración para cada modelo:

**models/llama-3.1-8b.yaml:**

```yaml
name: llama-3.1-8b
backend: llama-cpp
parameters:
  model: llama-3.1-8b.gguf
  context_size: 4096
  threads: 8
  gpu_layers: 35
template:
  chat: |
    {{.Input}}
    ### Respuesta:
  completion: |
    {{.Input}}
```

## Uso de la API

### Chat Completions (compatible con OpenAI)

```python
import openai

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

# O vía túnel SSH:
# client = openai.OpenAI(base_url="http://localhost:8080/v1", api_key="not-needed")

response = client.chat.completions.create(
    model="mistral-7b",
    messages=[
        {"role": "system", "content": "Eres un asistente útil."},
        {"role": "user", "content": "Explique la computación cuántica en términos simples."}
    ],
    temperature=0.7,
    max_tokens=500
)

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

### Streaming

```python
stream = client.chat.completions.create(
    model="mistral-7b",
    messages=[{"role": "user", "content": "Escribe un poema sobre la IA"}],
    stream=True
)

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

### Embeddings

```python
response = client.embeddings.create(
    model="all-minilm",
    input="The quick brown fox jumps over the lazy dog"
)

embedding = response.data[0].embedding
print(f"Dimensión del embedding: {len(embedding)}")
```

### Generación de imágenes

```python
response = client.images.generate(
    model="stablediffusion",
    prompt="un hermoso atardecer sobre montañas",
    size="512x512",
    n=1
)

image_url = response.data[0].url
```

## Ejemplos con cURL

### Chat

```bash
curl https://your-http-pub.clorecloud.net/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "mistral-7b",
        "messages": [{"role": "user", "content": "¡Hola!"}]
    }'
```

### Embeddings

```bash
curl https://your-http-pub.clorecloud.net/v1/embeddings \
    -H "Content-Type: application/json" \
    -d '{
        "model": "text-embedding-ada-002",
        "input": "Su texto aquí"
    }'
```

Respuesta:

```json
{
  "data": [{"embedding": [0.1, -0.2, ...], "index": 0}],
  "model": "text-embedding-ada-002",
  "usage": {"prompt_tokens": 4, "total_tokens": 4}
}
```

### Texto a voz (TTS)

```bash
curl https://your-http-pub.clorecloud.net/v1/audio/speech \
    -H "Content-Type: application/json" \
    -d '{
        "model": "tts-1",
        "input": "¡Hola, bienvenido a LocalAI!",
        "voice": "alloy"
    }' \
    --output speech.wav
```

Voces disponibles: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`

### Voz a texto (STT)

```bash
curl https://your-http-pub.clorecloud.net/v1/audio/transcriptions \
    -F "file=@audio.mp3" \
    -F "model=whisper-1"
```

Respuesta:

```json
{"text": "Texto transcrito aquí..."}
```

### Reordenamiento

Reordenar documentos por relevancia a una consulta:

```bash
curl https://your-http-pub.clorecloud.net/v1/rerank \
    -H "Content-Type: application/json" \
    -d '{
        "model": "jina-reranker-v1-base-en",
        "query": "¿Qué es el aprendizaje automático?",
        "documents": [
            "El aprendizaje automático es un subconjunto de la IA",
            "El clima está agradable hoy",
            "El aprendizaje profundo utiliza redes neuronales"
        ],
        "top_n": 2
    }'
```

Respuesta:

```json
{
  "results": [
    {"index": 0, "relevance_score": 0.95},
    {"index": 2, "relevance_score": 0.82}
  ]
}
```

## Referencia completa de la API

### Endpoints estándar (compatibles con OpenAI)

| Endpoint                   | Método | Descripción                |
| -------------------------- | ------ | -------------------------- |
| `/v1/models`               | GET    | Listar modelos disponibles |
| `/v1/chat/completions`     | POST   | Completación de chat       |
| `/v1/completions`          | POST   | Completación de texto      |
| `/v1/embeddings`           | POST   | Generar embeddings         |
| `/v1/audio/speech`         | POST   | Texto a voz                |
| `/v1/audio/transcriptions` | POST   | De voz a texto             |
| `/v1/images/generations`   | POST   | Generación de imágenes     |

### Endpoints adicionales

| Endpoint            | Método | Descripción                      |
| ------------------- | ------ | -------------------------------- |
| `/readyz`           | GET    | Comprobación de disponibilidad   |
| `/healthz`          | GET    | Comprobación de salud            |
| `/version`          | GET    | Obtener la versión de LocalAI    |
| `/v1/rerank`        | POST   | Reordenamiento de documentos     |
| `/models/available` | GET    | Listar modelos de la galería     |
| `/models/apply`     | POST   | Instalar modelo desde la galería |
| `/swagger/`         | GET    | Documentación Swagger UI         |
| `/metrics`          | GET    | Métricas de Prometheus           |

#### Obtener versión

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

Respuesta:

```json
{"version": "v2.26.0"}
```

#### Documentación Swagger

Ábralo en el navegador para documentación interactiva de la API:

```
https://your-http-pub.clorecloud.net/swagger/
```

## Aceleración por GPU

### Backend CUDA

```yaml
# En la configuración del modelo
parameters:
  gpu_layers: 35  # Número de capas en la GPU
  f16: true       # Usar FP16
```

### Descarga completa a GPU

```yaml
parameters:
  gpu_layers: 99  # Todas las capas en la GPU
  main_gpu: 0     # ID de GPU primaria
```

## Múltiples modelos

LocalAI puede servir múltiples modelos simultáneamente:

```
models/
├── llama-3.1-8b.yaml
├── llama-3.1-8b.gguf
├── mistral-7b.yaml
├── mistral-7b.gguf
├── whisper.yaml
└── whisper-base.bin
```

Acceda a cada uno mediante el nombre del modelo en las llamadas a la API.

## Ajuste de rendimiento

### Para velocidad

```yaml
parameters:
  threads: 8
  gpu_layers: 99
  batch_size: 512
  use_mmap: true
  use_mlock: true
```

### Para memoria

```yaml
parameters:
  gpu_layers: 20  # Descarga parcial
  context_size: 2048  # Contexto más pequeño
  batch_size: 256
```

## Benchmarks

| Modelo          | GPU      | Tokens/seg |
| --------------- | -------- | ---------- |
| Llama 3.1 8B Q4 | RTX 3090 | \~100      |
| Mistral 7B Q4   | RTX 3090 | \~110      |
| Llama 3.1 8B Q4 | RTX 4090 | \~140      |
| Mixtral 8x7B Q4 | A100     | \~60       |

*Benchmarks actualizados en enero de 2026.*

## Solución de problemas

### HTTP 502 en la URL http\_pub

LocalAI tarda más en iniciarse que otros servicios. Espere **5-10 minutos** y vuelva a intentar:

```bash
# Comprobar disponibilidad
curl https://your-http-pub.clorecloud.net/readyz

# Comprobar salud
curl https://your-http-pub.clorecloud.net/healthz
```

### El modelo no carga

* Compruebe la ruta del archivo en el YAML
* Verifique la compatibilidad del formato GGUF
* Compruebe la VRAM disponible

### Respuestas lentas

* Aumente `gpu_layers`
* Habilite `use_mmap`
* Reducir `context_size`

### Memoria insuficiente

* Reducir `gpu_layers`
* Use cuantización más pequeña (Q4 en lugar de Q8)
* Reducir el tamaño del lote

### Problemas con la generación de imágenes

{% hint style="warning" %}
Stable Diffusion puede tener problemas de compatibilidad con CUDA en algunas configuraciones de GPU. Si encuentra errores de CUDA con la generación de imágenes, considere usar una imagen dedicada de Stable Diffusion en su lugar.
{% endhint %}

## 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       |
| RTX 4090 | 24GB | $0.50–2.00 | Inferencia rápida |
| A100     | 40GB | $1.50–3.00 | Modelos grandes   |

*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.*

## Próximos pasos

* [Inferencia vLLM](https://docs.clore.ai/guides/guides_v2-es/modelos-de-lenguaje/vllm) - Mayor rendimiento
* [Guía de Ollama](https://docs.clore.ai/guides/guides_v2-es/modelos-de-lenguaje/ollama) - Configuración más simple
* [RAG con LangChain](https://docs.clore.ai/guides/guides_v2-es/avanzado/api-integration) - Construir aplicaciones