# 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):
```bash
pip install -e .[cpu]
```

### Instalaci�n con soporte CUDA (recomendado para GPU):
```bash
pip install -e .[cuda]
```

### Instalaci�n manual con CUDA:
```bash
# 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:
```bash
nvidia-smi  # Verificar que CUDA est� disponible
python -c "import llama_cpp; print('llama-cpp-python instalado correctamente')"
```

2. Descargar un modelo GGUF (ejemplo):
```bash
# Ejemplo con un modelo peque�o
wget https://huggingface.co/microsoft/DialoGPT-medium/resolve/main/pytorch_model.bin
```

## Uso

### Iniciar el servidor

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

### Opciones disponibles

```bash
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

```bash
# 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:
```bash
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):
```python
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

```json
{
  "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:
  ```bash
  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