README.md

metadata

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

pip install requests

Uso Básico

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

# 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

# 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:

{
    "data": [
        "system_prompt",
        "message", 
        [["user", "assistant"], ...],
        512,
        0.7
    ]
}

Respuesta:

{
    "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:

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

Manejo de Errores

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

# 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
• Meta Llama 3.2 3B Instruct
• Gradio Documentation
• Transformers Library

---

¡Disfruta chateando con Llama! 🦙