Inicio Rápido

Esta guía te ayudará a comenzar rápidamente con CapibaraGPT-v2, el modelo de lenguaje con JAX nativo, Vector Quantization (VQ), y optimizaciones TPU v4-32 completamente funcionales.

🏆 Estado del Proyecto: 100% FUNCIONAL - SISTEMA COMPLETAMENTE OPERATIVO

Instalación Rápida

# Clonar el repositorio
git clone https://github.com/user/CapibaraGPT-v2.git
cd CapibaraGPT-v2

# Instalar dependencias
pip install -r requirements.txt

# Instalación en modo desarrollo
pip install -e .

Verificación de la Instalación

# Test de importación principal - debe funcionar sin errores
import capibara
print("✅ CapibaraGPT-v2 importado correctamente")

# Verificar módulos principales
from capibara.core import ModularCapibaraModel
from capibara.config import ModularModelConfig
from capibara.vq.vqbit import VQbitLayer
print("✅ Módulos principales funcionales")

Configuración Inicial

CapibaraGPT-v2 utiliza configuración TOML optimizada:

from capibara.config import ModularModelConfig

# Configuración desde archivo TOML (recomendado)
config = ModularModelConfig.from_toml(
    "capibara/config/configs_toml/production/tpu_v4.toml"
)

# Configuración programática personalizada
config = ModularModelConfig(
    model_name="capibara_lite_300m",
    hidden_size=768,
    num_layers=12,
    num_heads=12,
    vocab_size=32000,

    # JAX nativo y optimizaciones
    use_jax_native=True,
    use_tpu_v4_optimizations=True,

    # Vector Quantization
    use_vq=True,
    vq_codes=64,  # 64 para TPU v4, 128 para TPU v6

    # Sparsity y optimizaciones
    use_sparse=True,
    sparsity_ratio=0.65,
    mixed_precision=True
)

Carga del Modelo Principal

from capibara.core import ModularCapibaraModel

# Crear modelo con JAX nativo y optimizaciones TPU
model = ModularCapibaraModel(config)

# Inicializar modelo (configuración automática de hardware)
model.initialize()

print(f"✅ Modelo cargado: {model.config.model_name}")
print(f"🔧 JAX nativo: {model.config.use_jax_native}")
print(f"🎯 VQ codes: {model.config.vq_codes}")
print(f"⚡ TPU v4 optimizations: {model.config.use_tpu_v4_optimizations}")

Generación de Texto Básica

# Generación básica con optimizaciones automáticas
prompt = "Explica Vector Quantization en machine learning:"

response = model.generate(
    prompt,
    max_length=150,
    temperature=0.7,
    use_vq=True,           # Usar Vector Quantization
    use_sparse=True,       # Activar sparsity automática
    tpu_optimized=True     # Usar optimizaciones TPU
)

print("🤖 Respuesta:", response)

Generación Avanzada con VQ

from capibara.vq.vqbit import VQbitLayer

# VQbit Layer para quantización avanzada
vqbit = VQbitLayer(
    codebook_size=64,      # 64 códigos para TPU v4
    embedding_dim=768,
    use_tpu_optimizations=True
)

# Generación con VQ personalizado
vq_response = model.generate_with_vq(
    prompt,
    vqbit_layer=vqbit,
    quantization_strength=0.8,
    adaptive_threshold=0.5
)

print("🎯 Respuesta VQ:", vq_response)

Entrenamiento y Fine-tuning

from capibara.training.unified_trainer import UnifiedTrainer
from capibara.data import CapibaraDataset

# Preparar datos
dataset = CapibaraDataset.from_text_file("datos_entrenamiento.txt")

# Configurar trainer con optimizaciones TPU
trainer = UnifiedTrainer(
    model=model,
    dataset=dataset,
    batch_size=32,
    learning_rate=1e-4,
    use_tpu_v4=True,
    mixed_precision=True
)

# Entrenamiento con consensus distilling automático
trainer.train(
    epochs=3,
    save_checkpoints=True,
    checkpoint_dir="./checkpoints"
)

Agentes Inteligentes

from capibara.agents import CapibaraAgentFactory

# Crear agente especializado
agent = CapibaraAgentFactory.create_agent(
    agent_type="research_assistant",
    model=model,
    personality="analytical",
    specialized_knowledge=["machine learning", "vector quantization"]
)

# Interacción con el agente
response = agent.process_query(
    "¿Cómo funciona la quantización vectorial en transformers?"
)

print("🤖 Agente:", response)

Monitoreo en Tiempo Real

from capibara.monitoring import SystemMonitor

# Monitor de sistema con métricas TPU
monitor = SystemMonitor(model)

# Obtener métricas en tiempo real
metrics = monitor.get_real_time_metrics()

print("📊 Métricas del sistema:")
print(f"   💾 Memoria TPU: {metrics['tpu_memory_usage']:.1f}%")
print(f"   🔥 Temperatura: {metrics['temperature']:.1f}°C")
print(f"   ⚡ TFLOPS: {metrics['tflops']:.1f}")
print(f"   🎯 VQ efficiency: {metrics['vq_efficiency']:.1f}%")
print(f"   💰 Cost/hour: ${metrics['cost_per_hour']:.4f}")

Configuración Multi-Plataforma

TPU v4-32 (Recomendado)

config = ModularModelConfig.from_toml(
    "capibara/config/configs_toml/production/tpu_v4.toml"
)
# 64 códigos VQ, 275 TFLOPS, optimizaciones nativas

ARM Axion (Cost-Effective)

config = ModularModelConfig.from_toml(
    "capibara/config/configs_toml/specialized/arm_axion_inference.toml"
)
# 64 códigos VQ, SVE vectorization, UMA memory

GPU/CPU (Fallback)

config = ModularModelConfig.from_toml(
    "capibara/config/configs_toml/development/development.toml"
)
# Fallback automático, optimizaciones disponibles

Debugging y Troubleshooting

# Verificar estado del sistema
from capibara.utils import SystemDiagnostics

diagnostics = SystemDiagnostics()

# Check completo del sistema
status = diagnostics.run_full_check()

print("🔍 Diagnóstico del sistema:")
for component, status in status.items():
    icon = "✅" if status["healthy"] else "❌"
    print(f"   {icon} {component}: {status['message']}")

# Check específico de imports
import_status = diagnostics.check_imports()
print(f"📦 Imports: {len(import_status['successful'])} OK, {len(import_status['failed'])} errores")

Ejemplos de Uso Avanzado

Generación con Control de Estilo

response = model.generate_with_style(
    prompt="Describe la cuantización vectorial",
    style="academic",           # 'academic', 'casual', 'technical'
    complexity_level=0.8,       # 0.0-1.0
    use_vq=True,
    temperature=0.6
)

Procesamiento por Lotes

prompts = [
    "Explica VQ en términos simples",
    "Ventajas de TPU v4 vs GPU",
    "Diferencias entre sparsity y quantization"
]

responses = model.generate_batch(
    prompts,
    max_length=100,
    use_vq=True,
    batch_size=8
)

Integración con Meta Loop (Elixir/OTP)

from capibara.meta_loop import CapibaraBridge

# Bridge Python-Elixir para capacidades avanzadas
bridge = CapibaraBridge(model)

# RAG con control ético
rag_response = bridge.query_with_rag(
    prompt,
    ethics_check=True,
    knowledge_base="ml_papers",
    confidence_threshold=0.8
)

Guardar y Cargar Modelos

# Guardar modelo con configuración
model.save_pretrained(
    "./mi_modelo_vq",
    save_config=True,
    save_vq_codebooks=True,
    compress=True
)

# Cargar modelo guardado
loaded_model = ModularCapibaraModel.from_pretrained(
    "./mi_modelo_vq",
    config_path="./mi_modelo_vq/config.toml"
)

Optimizaciones de Rendimiento

# Compilación JIT para máximo rendimiento
model.compile_for_inference(
    input_shapes=[(1, 512)],   # Shapes típicos
    optimization_level="aggressive",
    cache_compiled=True
)

# Warmup para TPU
model.warmup_tpu(num_steps=10)

# Configurar cache optimizado
model.setup_optimized_cache(
    cache_size_gb=4.0,
    use_tpu_memory=True
)

Siguientes Pasos

Explora la configuración avanzada
Revisa los ejemplos específicos
Consulta la referencia de API
Únete a nuestra comunidad para soporte técnico
Contribuye al desarrollo en GitHub

Recursos Adicionales

Documentación TPU v4: tpu_v4/optimizations
Sistema VQ: layers/vq_layers
JAX Nativo: jax/native_implementation
Testing: testing/comprehensive_testing