llama_cpp_local/README.md

Llama.cpp OpenAI Compatible API

API compatible con OpenAI para servir modelos GGUF usando llama.cpp.

Caracter�sticas

• =� API compatible con OpenAI Chat Completions

•  Soporte para modelos GGUF

• � Construido con FastAPI y llama-cpp-python
• =� Documentaci�n autom�tica con Swagger
• =' Configuraci�n flexible de par�metros

Instalaci�n

Instalaci�n b�sica (solo CPU):

pip install -e .[cpu]

Instalaci�n con soporte CUDA (recomendado para GPU):

pip install -e .[cuda]

Instalaci�n manual con CUDA:

# Opci�n 1: Usando CMAKE
CMAKE_ARGS="-DLLAMA_CUBLAS=on" pip install llama-cpp-python[cublas] --force-reinstall --no-cache-dir

# Opci�n 2: Usando variables de entorno
export CMAKE_ARGS="-DLLAMA_CUBLAS=on"
pip install llama-cpp-python[cublas] --force-reinstall --no-cache-dir

# Luego instalar el resto de dependencias
pip install -e .

Verificar instalaci�n de CUDA:

nvidia-smi  # Verificar que CUDA est� disponible
python -c "import llama_cpp; print('llama-cpp-python instalado correctamente')"

2. Descargar un modelo GGUF (ejemplo):

# Ejemplo con un modelo peque�o
wget https://huggingface.co/microsoft/DialoGPT-medium/resolve/main/pytorch_model.bin

Uso

Iniciar el servidor

python main.py --model-path /ruta/a/tu/modelo.gguf

Opciones disponibles

python main.py --help

• --model-path / -m: Ruta al archivo del modelo GGUF (requerido)
• --host: Host del servidor (default: 0.0.0.0)
• --port: Puerto del servidor (default: 8000)
• --n-ctx: Tama�o del contexto (default: 4096)
• --n-batch: Tama�o del batch (default: 512)
• --n-threads: N�mero de threads (default: auto)
• --n-gpu-layers: N�mero de capas a cargar en GPU (-1 = todas, 0 = ninguna, default: -1)
• --main-gpu: GPU principal a usar (default: 0)
• --split-mode: Modo de divisi�n entre GPUs (default: 1)

Ejemplo de uso

# Ejemplo recomendado con GPU (CUDA) - M�ximo rendimiento
uv run python main.py --model-path ./models/Qwen3-4B-Instruct-2507-Q4_K_M.gguf --port 8000 --n-ctx 4096 --n-gpu-layers -1

# Ejemplo b�sico con CPU solamente
uv run python main.py --model-path ./models/Qwen3-4B-Instruct-2507-Q4_K_M.gguf --port 8000 --n-ctx 4096 --n-gpu-layers 0

# Ejemplo con GPU - Solo algunas capas en GPU (para modelos grandes o GPUs con poca memoria)
uv run python main.py --model-path ./models/Qwen3-4B-Instruct-2507-Q4_K_M.gguf --port 8000 --n-ctx 4096 --n-gpu-layers 20

# Ejemplo con configuraci�n personalizada para GPU m�ltiples
uv run python main.py --model-path ./models/Qwen3-4B-Instruct-2507-Q4_K_M.gguf --port 8000 --n-ctx 4096 --n-gpu-layers -1 --main-gpu 0 --split-mode 1

API Endpoints

GET /v1/models

Lista los modelos disponibles

POST /v1/chat/completions

Crea una completion de chat

Ejemplo con curl:

curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama",
    "messages": [
      {"role": "user", "content": "Hola, �c�mo est�s?"}
    ],
    "max_tokens": 100,
    "temperature": 0.7
  }'

Ejemplo con Python (usando openai):

import openai

# Configurar el cliente para usar tu servidor local
openai.api_base = "http://localhost:8000/v1"
openai.api_key = "no-key-needed"  # No se requiere clave real

response = openai.ChatCompletion.create(
    model="llama",
    messages=[
        {"role": "user", "content": "Expl�came qu� es la inteligencia artificial"}
    ],
    max_tokens=200,
    temperature=0.7
)

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

Documentaci�n de la API

Una vez que el servidor est� ejecut�ndose, puedes acceder a la documentaci�n interactiva en:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Par�metros de la API

ChatCompletionRequest

• model: Nombre del modelo (string)
• messages: Lista de mensajes del chat
• max_tokens: M�ximo n�mero de tokens a generar (default: 2048)
• temperature: Temperatura para el muestreo (default: 0.7)
• top_p: Top-p para el muestreo (default: 0.9)
• stream: Respuesta en streaming (no implementado a�n)

Formato de mensajes

{
  "role": "user|assistant|system",
  "content": "Contenido del mensaje"
}

Notas importantes

• La API estima el conteo de tokens dividiendo la longitud del texto por 4
• Los modelos GGUF deben ser compatibles con llama.cpp
• El formateo de prompts puede variar seg�n el modelo usado
• Para mejor rendimiento, ajusta n_ctx, n_batch y n_threads seg�n tu hardware

Troubleshooting

Error: "El archivo del modelo no existe"

• Verifica que la ruta al modelo GGUF sea correcta
• Aseg�rate de que el archivo tenga extensi�n .gguf

Error de memoria

• Reduce n_ctx para modelos grandes
• Usa un modelo m�s peque�o
• Aumenta la memoria disponible

Respuestas lentas

• Aumenta n_threads si tienes m�s CPU cores disponibles
• Ajusta n_batch para tu hardware
• Considera usar un modelo m�s peque�o
• Para GPU: Usa --n-gpu-layers -1 para cargar todas las capas en GPU
• Para GPU: Verifica que CUDA est� instalado correctamente con nvidia-smi

Problemas con GPU/CUDA

• Error "CUDA not found": Reinstala llama-cpp-python con soporte CUDA:

  CMAKE_ARGS="-DLLAMA_CUBLAS=on" pip install llama-cpp-python[cublas] --force-reinstall --no-cache-dir
  

• Memoria GPU insuficiente: Reduce --n-gpu-layers a un n�mero menor (ej: 20, 10)
• GPU no detectada: Verifica que nvidia-smi funcione y muestre tu GPU
• Rendimiento lento con GPU: Aseg�rate de usar --n-gpu-layers -1 para cargar todas las capas
• Error de compatibilidad: Verifica que tu GPU tenga compute capability >= 3.5