---
title: Llama 3.2 3B Chat
emoji: 🦙
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: "4.44.0"
app_file: app.py
pinned: false
license: mit
---

# 🦙 Llama 3.2 3B Chat - Hugging Face Space

Un Space de Hugging Face para chatear con Meta Llama 3.2 3B Instruct con sistema de colas, streaming y API para cliente Python.

## ✨ Características

- 🔄 **Sistema de colas**: Solo procesa una petición a la vez para evitar sobrecargar el modelo
- 📡 **Streaming en tiempo real**: Ve la respuesta generándose en tiempo real
- 🐍 **Cliente Python**: API completa para integración con aplicaciones Python
- 💬 **Interfaz web**: Chat interactivo con sistema de prompts y configuración
- 📊 **Monitoreo**: Estado de cola en tiempo real
- 🔐 **Autenticación**: Soporte para modelos restringidos con HF token

## 🚀 Configuración del Space

### 1. Crear el Space

1. Ve a [Hugging Face Spaces](https://huggingface.co/new-space)
2. Elige **Gradio** como SDK
3. Selecciona **T4 small** o superior como hardware
4. Nombra tu Space (ej: `tu-usuario/llama-chat`)

### 2. Configurar el token HF

1. Ve a **Settings** de tu Space
2. En **Repository secrets**, agrega:
   - **Name**: `HF_TOKEN`
   - **Value**: Tu token de Hugging Face (con acceso a Llama)

### 3. Subir archivos

Sube estos archivos a tu Space:
- `app.py` (aplicación principal)
- `requirements.txt` (dependencias)

### 4. Verificar el despliegue

Una vez que el Space esté corriendo, deberías ver:
- Una interfaz de chat en la pestaña principal
- Un endpoint API en la segunda pestaña
- Estado de cola actualizado automáticamente

## 📱 Uso de la interfaz web

### Chat Principal
- **System Prompt**: Define el comportamiento del asistente
- **Mensaje**: Tu pregunta o mensaje
- **Max Tokens**: Longitud máxima de la respuesta (50-1024)
- **Temperature**: Creatividad de la respuesta (0.1-2.0)

### Estado de Cola
- **queue_size**: Número de peticiones en espera
- **is_processing**: Si está procesando actualmente
- **timestamp**: Última actualización

## 🐍 Cliente Python

### Instalación

```bash
pip install requests
```

### Uso Básico

```python
from client import LlamaClient

# Inicializar cliente con la URL de tu Space
client = LlamaClient("https://tu-usuario-llama-chat.hf.space")

# Chat simple
response = client.chat(
    message="¿Qué es la inteligencia artificial?",
    system_prompt="Eres un profesor experto."
)

print(response["response"])
```

### Chat con Streaming

```python
# Ver respuesta generándose en tiempo real
for chunk in client.chat_stream(
    message="Explica la física cuántica",
    system_prompt="Eres un divulgador científico.",
    max_tokens=300
):
    print(f"\r{chunk['response']}", end="", flush=True)

    if chunk.get("is_complete", False):
        print("\n[Completo]")
        break
```

### Chat con Historial

```python
# Mantener conversación
history = [
    ["Hola", "¡Hola! ¿En qué puedo ayudarte?"],
    ["Explica el machine learning", "El machine learning es..."]
]

response = client.chat(
    message="¿Puedes dar un ejemplo práctico?",
    history=history
)
```

## 🔧 API Endpoints

### POST /call/api_chat
Respuesta completa sin streaming.

**Payload:**
```json
{
    "data": [
        "system_prompt",
        "message", 
        [["user", "assistant"], ...],
        512,
        0.7
    ]
}
```

**Respuesta:**
```json
{
    "data": [{
        "response": "Respuesta del modelo",
        "queue_status": {
            "queue_size": 0,
            "is_processing": false,
            "timestamp": "2025-10-16T17:30:00"
        }
    }]
}
```

### POST /call/api_chat_stream
Respuesta con streaming.

Misma estructura de payload, pero responde con eventos SSE.

## 📊 Monitoreo y Debugging

### Logs del Space
Revisa los logs en la interfaz de HF Spaces para debugging.

### Estado de Cola
Usa `client.get_queue_status()` para monitorear la cola:

```python
status = client.get_queue_status()
print(f"Cola: {status['queue_size']} peticiones")
print(f"Procesando: {status['is_processing']}")
```

### Manejo de Errores

```python
response = client.chat("Hola")

if "error" in response:
    print(f"Error: {response['error']}")
else:
    print(f"Respuesta: {response['response']}")
```

## ⚙️ Configuración Avanzada

### Parámetros del Modelo

- **max_tokens**: 50-1024 (recomendado: 512)
- **temperature**: 0.1-2.0 (recomendado: 0.7)
- **repetition_penalty**: Automático (1.1)

### Optimización de Performance

1. **Hardware**: Usa GPU T4 small mínimo
2. **Batch size**: Sistema de colas evita problemas de memoria
3. **Context length**: Máximo 2048 tokens de entrada

### System Prompts Útiles

```python
# Para tareas académicas
system_prompt = "Eres un tutor experto que explica conceptos complejos de forma clara y pedagógica."

# Para programación
system_prompt = "Eres un desarrollador senior que ayuda con código Python, explicando paso a paso."

# Para creatividad
system_prompt = "Eres un escritor creativo que ayuda a generar ideas originales y contenido engagente."
```

## 🐛 Troubleshooting

### Error: HF_TOKEN no encontrado
- Verifica que agregaste el token en Repository secrets
- Asegúrate que el nombre sea exactamente `HF_TOKEN`

### Error: Modelo no disponible
- Tu token debe tener acceso a Llama 3.2 3B
- Solicita acceso en la página del modelo si es necesario

### Timeouts en cliente Python
- Aumenta el timeout: `requests.post(..., timeout=600)`
- El modelo puede tardar en cargar la primera vez

### Cola muy larga
- El sistema procesa una petición a la vez
- Considera usar hardware más potente

## 🤝 Contribuciones

¿Mejoras sugeridas?
1. Fork el código
2. Implementa mejoras
3. Prueba con tu propio Space
4. Comparte tu versión

## 📝 Licencia

Este código es de uso libre. Respeta los términos de uso de:
- Hugging Face Spaces
- Meta Llama 3.2 License
- Gradio License

## 🔗 Enlaces Útiles

- [Hugging Face Spaces](https://huggingface.co/spaces)
- [Meta Llama 3.2 3B Instruct](https://huggingface.co/meta-llama/Llama-3.2-3B-Instruct)
- [Gradio Documentation](https://gradio.app/docs/)
- [Transformers Library](https://huggingface.co/docs/transformers)

---

**¡Disfruta chateando con Llama! 🦙**