🤖
CULTIVA IA · IA-Ingeniería-MLOps

Despliegue LLM Local con llama.cpp

Guía técnica de selección, cuantización y despliegue · Endpoint compatible OpenAI · Air-gapped
HuggingFace Hub Apple Metal GGUF / GGML OpenAI-compatible API RGPD-compliant
NovaTech Analytics SL
Valencia · B2B Industrial
Preparado: junio 2026
● Sin datos a APIs externas
Contexto del despliegue
🏭
Caso de uso
Análisis de informes industriales
Texto libre → resúmenes + Q&A técnico
🔒
Restricción crítica
Air-gapped en producción
RGPD + NDA clientes · Sin APIs cloud
🔌
Integración existente
API compatible OpenAI
App Python con cliente openai-sdk
llama-server expone un endpoint http://localhost:8080/v1/ 100% compatible con la API de OpenAI. El código Python existente de NovaTech solo necesita cambiar base_url y api_key="no-key" — sin refactorizar.
Selección de modelo · Comparativa
Modelo (Hub) Parámetros Cuantización Tamaño GGUF RAM mín. Contexto Español Veredicto
Qwen2.5-14B-Instruct 14B Q4_K_M
8.5 GB
12 GB 32k tokens ⭐⭐⭐⭐⭐ ★ PRIMARIO
DeepSeek-R1-Distill-Qwen-14B 14B Q5_K_M
10.2 GB
14 GB 32k tokens ⭐⭐⭐⭐ Razonamiento
Mistral-7B-Instruct-v0.3 7B Q4_K_M
4.1 GB
7 GB 8k tokens ⭐⭐⭐ Laptops / fallback
Guía de cuantización GGUF para Qwen2.5-14B
Q3_K_M
3-bit · Mixed precision
6.2 GB
Tamaño GGUF
+6%
Perplexity vs FP16
Solo si RAM < 10 GB
Q5_K_M
5-bit · Mixed precision
10.2 GB
Tamaño GGUF
+0.4%
Perplexity vs FP16
Análisis técnico · código
Q6_K
6-bit · Best quality
13.0 GB
Tamaño GGUF
+0.13%
Perplexity vs FP16
Máxima calidad · 192 GB RAM
Perfiles de hardware disponibles en NovaTech
🖥️
Mac Studio M2 Ultra
Servidor principal · Producción
Apple Metal GPU
RAM unificada192 GB
GPU cores24-core
AceleraciónGGML_METAL=1
Flag llama-ngl 99
Modelo recomendadoQwen2.5-14B Q4_K_M
Velocidad est.~45 tok/s
💻
MacBook Pro M3 Max
Laptops ingenieros · Desarrollo
Apple Metal GPU
RAM unificada64 GB
GPU cores40-core
AceleraciónGGML_METAL=1
Flag llama-ngl 99
Modelo recomendadoQwen2.5-14B Q4_K_M
Velocidad est.~35 tok/s
🐧
Ubuntu 22.04 · Ryzen 9
Servidor secundario · Fallback
CPU-only
RAM64 GB
CPU cores16c / 32t
AceleraciónLLAMA_OPENBLAS=1
Flag llama-t 16
Modelo recomendadoMistral-7B Q4_K_M
Velocidad est.~8 tok/s
Comandos de despliegue paso a paso
1
Instalar llama.cpp
macOS con Homebrew (recomendado) · Compila automáticamente con Metal
macOS (Homebrew) Linux (build) $ bash
# macOS — instala con Metal habilitado por defecto
brew install llama.cpp

# Linux Ubuntu — compilar con OpenBLAS para CPU-only
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
make LLAMA_OPENBLAS=1

# Verificar instalación
llama-server --version
2
Buscar y confirmar el modelo en HuggingFace Hub
Verificar GGUF disponible + filenames exactos antes de descargar
Hub search Tree API $ bash
# 1. Buscar repos GGUF para Qwen2.5-14B en el Hub
#    URL: https://huggingface.co/models?search=Qwen2.5-14B&apps=llama.cpp&sort=trending
#    Resultado: bartowski/Qwen2.5-14B-Instruct-GGUF (repo con GGUF nativos)

# 2. Ver página local-app para recomendación de cuantización
#    https://huggingface.co/bartowski/Qwen2.5-14B-Instruct-GGUF?local-app=llama.cpp

# 3. Confirmar filenames exactos con la Tree API
curl -s "https://huggingface.co/api/models/bartowski/Qwen2.5-14B-Instruct-GGUF/tree/main?recursive=true" \
  | python3 -c "import json,sys; [print(f['path']) for f in json.load(sys.stdin) if f['path'].endswith('.gguf')]"

# Resultado esperado:
# Qwen2.5-14B-Instruct-Q3_K_M.gguf
# Qwen2.5-14B-Instruct-Q4_K_M.gguf  ← elegido
# Qwen2.5-14B-Instruct-Q5_K_M.gguf
# Qwen2.5-14B-Instruct-Q6_K.gguf
# Qwen2.5-14B-Instruct-Q8_0.gguf
3
Lanzar llama-server (Mac Studio M2 Ultra — producción)
Descarga automática desde Hub + arranque con Metal · contexto 16k para informes largos
Mac Studio · Producción MacBook Pro · Desarrollo Linux · Fallback $ bash
# ── Mac Studio M2 Ultra (servidor producción NovaTech) ──────────────────────
# Primera vez: descarga GGUF (~8.5 GB) y arranca
llama-server \
  --hf-repo bartowski/Qwen2.5-14B-Instruct-GGUF \
  --hf-file Qwen2.5-14B-Instruct-Q4_K_M.gguf \
  -c 16384 \
  -ngl 99 \
  --host 0.0.0.0 \
  --port 8080

# Con shorthand Hub (alternativa equivalente)
llama-server -hf bartowski/Qwen2.5-14B-Instruct-GGUF:Q4_K_M -c 16384 -ngl 99 --host 0.0.0.0

# Air-gapped producción: modelo ya descargado en disco local
llama-server \
  -m /opt/models/Qwen2.5-14B-Instruct-Q4_K_M.gguf \
  -c 16384 \
  -ngl 99 \
  --host 0.0.0.0 \
  --port 8080
4
Smoke test y validación del endpoint OpenAI-compatible
Verificar que la app Python de NovaTech puede conectar sin modificar código de negocio
cURL test Python (SDK openai) $ bash / python
# ── Test con cURL ──────────────────────────────────────────────────────────
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer no-key" \
  -d '{
    "model": "local",
    "messages": [
      {"role": "system", "content": "Eres un analista industrial experto en fabricación."},
      {"role": "user",   "content": "Resume los 3 KPIs más importantes de un informe de planta: OEE 87%, tiempo de ciclo 4.2s, tasa de rechazo 0.3%."}
    ],
    "max_tokens": 512,
    "temperature": 0.3
  }'

# ── Integración Python con SDK openai (sin cambios en lógica de negocio) ───
from openai import OpenAI

client = OpenAI(
    base_url="http://192.168.1.100:8080/v1",  # IP Mac Studio en LAN NovaTech
    api_key="no-key"
)

response = client.chat.completions.create(
    model="local",
    messages=[
        {"role": "system", "content": "Eres analista de operaciones industriales."},
        {"role": "user",   "content": informe_texto}
    ],
    temperature=0.2,
    max_tokens=1024
)
Benchmark de rendimiento estimado
Tokens por segundo · Qwen2.5-14B Q4_K_M
Mac Studio M2 Ultra (ngl 99)
~45 tok/s
MacBook Pro M3 Max (ngl 99)
~35 tok/s
Ubuntu Ryzen 9 CPU (t 16)
~8 tok/s
Tiempo respuesta · Informe 3.000 palabras → Resumen
Entrada: ~4.500 tokens
~6 seg
Salida estimada: ~400 tokens
~9 seg
Total end-to-end Mac Studio: ~15 seg · Aceptable para batch
Uso de memoria · Mac Studio 192 GB
Modelo Q4_K_M en RAM GPU
8.5 GB
Contexto 16k (KV cache)
~3.8 GB
174 GB libres para otras apps ✓
Checklist de validación post-despliegue
Servidor activo y respondiendo PASS
GET /health devuelve {"status":"ok"}
GET /v1/models lista el modelo local
Latencia primer token < 3s (Mac Studio)
Compatibilidad OpenAI SDK PASS
Chat completions con messages[] funciona
Streaming (stream=True) operativo
Parámetros temperature, max_tokens respetados
Calidad en español industrial PASS
Resumen de informe OEE coherente y en español
Terminología técnica correcta (tasa de rechazo, tiempo de ciclo)
No alucina datos que no están en el informe
Seguridad · Air-gapped PASS
Servidor escucha solo en LAN interna (--host 0.0.0.0 con firewall)
GGUF en /opt/models/ con permisos 640
Cero peticiones salientes a APIs externas
⚠️
Próximo paso recomendado para NovaTech: Una vez validado el servidor base, integrar una capa RAG con LlamaIndex o Chroma apuntando a http://localhost:8080/v1 para el Q&A sobre manuales técnicos internos. Los embeddings también pueden generarse localmente con llama-embedding.