## Plan de investigación y documentación

### 1. Objetivo de la documentación
Proporcionar una guía comparativa y de selección sobre las mejores bibliotecas y herramientas para cargar modelos de lenguaje locales (LLMs) en Python, con un enfoque en **eliminar la dependencia de una API externa** (como la de Ollama) y permitir una integración directa en el propio código del proyecto. Se busca identificar alternativas que igualen o superen a Ollama en eficiencia, facilidad de uso y compatibilidad con modelos de Hugging Face, detallando ventajas, limitaciones y configuraciones óptimas.

### 2. Audiencia y nivel técnico
- **Perfil:** Desarrolladores de Python con experiencia intermedia, que construyen aplicaciones que requieren inferencia local de LLMs (chatbots, asistentes, analizadores de texto) y desean integrar el modelo como parte del mismo proceso, sin desplegar servicios separados.
- **Prerrequisitos:** Conocimiento básico de Python, familiaridad con Hugging Face `transformers`/`hub`, conceptos de cuantización (GGUF, GPTQ, AWQ) y experiencia con entornos virtuales. Se asume acceso a hardware con al menos 8 GB de RAM y, opcionalmente, GPU NVIDIA.

### 3. Alcance y versiones
- **Qué cubre:**
  - Comparación exhaustiva de bibliotecas que permiten cargar modelos locales **sin necesidad de un servidor API** (modelos en proceso).
  - Evaluación de eficiencia (latencia, uso de memoria, throughput) y facilidad de integración en proyectos Python.
  - Compatibilidad con formatos de modelo populares (safetensors, GGUF, GPTQ/AWQ) y repositorios Hugging Face.
  - Alternativas específicas mencionadas por el usuario: Ollama (como referencia), llamafile, exllamav2. Además, se investigarán y documentarán otras opciones como `llama-cpp-python`, `transformers` + `accelerate`, `ctranslate2`, y `vLLM` (in-process o en modo API local).
- **Qué NO cubre:**
  - Servicios en la nube ni APIs propietarias.
  - Entrenamiento ni fine‑tuning de modelos.
  - Despliegue en producción a gran escala (orquestación, balanceo), aunque se mencionarán consideraciones básicas.
- **Contexto de versiones:** Se documentarán las versiones estables más recientes al momento de la investigación (fechas aproximadas: mayo‑junio 2025). Se indicará cómo verificar versiones y compatibilidad.

### 4. Estructura del documento

| Sección | Propósito |
|--------|-----------|
| **Introducción** | Presentar el problema (necesidad de modelos locales sin API externa) y el alcance de la comparación. |
| **Criterios de evaluación** | Definir los parámetros con los que se juzgará cada biblioteca: facilidad de instalación, integración en Python (sin servidor), rendimiento (CPU/GPU), soporte de cuantización, variedad de modelos compatibles, madurez, licencia y comunidad. |
| **Ollama: referencia y limitación** | Describir brevemente cómo funciona Ollama (servidor local + API REST) y por qué se busca una alternativa sin esa capa, destacando su fortaleza para modelos muy pequeños pero la obligación de administrar un endpoint HTTP. |
| **Panorama de alternativas** | Bloque principal con secciones dedicadas a cada herramienta. |
| – **llamafile (Mozilla)** | Características, instalación, integración en Python (como subproceso o embebido), rendimiento prometido en ARM SBC, madurez, formatos soportados. |
| – **exllamav2** | Enfoque en GPTQ/AWQ, ligado a tarjetas NVIDIA, uso desde Python mediante `torch`, condiciones para cargar modelos Hugging Face cuantizados. Comparación de velocidad frente a Ollama. |
| – **llama-cpp-python (binding de llama.cpp)** | Alternativa más directa para modelos GGUF. Instalación con pip, API Python nativa, soporte de GPU (CUDA/Metal), streaming y restricción de servidor si se desea. Gran compatibilidad con Hugging Face. |
| – **transformers + accelerate (Hugging Face)** | Carga estándar de modelos en safetensors o PyTorch. Técnicas para reducir huella (device_map, offloading). Cuándo es competitivo con Ollama. |
| – **CTranslate2** | Motor de inferencia optimizado para modelos seq2seq y decoders. Soporte para modelos con pesos en float16/int8. Conversión de modelos Hugging Face. |
| – **vLLM (modo in‑process)** | Aunque su diseño es de servidor, explicar la posibilidad de usar `LLM` directamente en código Python sin levantar un endpoint, sus ventajas en throughput con PagedAttention, y sus requisitos de hardware. |
| – **Otras librerías a considerar** | Mencionar opciones como `mlc-llm`, `text-generation-webui` como frontend pero no librería, `OpenVINO` para Intel, o `MNN-LLM`. |
| **Matriz comparativa** | Tabla resumen con características: tipo de integración, formatos soportados, aceleración hardware, dependencias, curva de aprendizaje, rendimiento relativo. |
| **Recomendaciones por caso de uso** | Escenarios típicos (modelos <7B en CPU, modelos >13B en GPU, necesidad de streaming, entorno sin GPU, etc.) y la mejor alternativa para cada uno. |
| **Guía rápida de implementación** | Ejemplo de código mínimo para cada una de las 3‑4 opciones más recomendadas, mostrando carga de un modelo de Hugging Face sin servidor. |
| **Conclusiones** | Resumen de hallazgos y decisión final sobre si existe una alternativa superior a Ollama que elimine la API. |
| **Referencias y enlaces** | Documentación oficial de cada herramienta, artículos de benchmarks, issues relevantes. |

### 5. Aspectos técnicos a investigar
- **Rendimiento comparativo**: Realizar (o recolectar benchmarks existentes) mediciones de latencia de primera inferencia y tokens/segundo para un modelo estándar (p.ej., Mistral‑7B, Llama‑3‑8B) en CPU y GPU, comparando Ollama, llama‑cpp‑python, exllamav2 y CTranslate2.
- **Integración en Python sin servidor**: Verificar para cada librería si se puede instanciar el modelo directamente en el mismo script (`model = Llama(...)`) sin levantar sockets ni procesos externos, o si requiere un wrapper.
- **Compatibilidad con Hugging Face**: Probar la carga de modelos en formatos comunes (safetensors, GGUF subidos al Hub) y documentar cualquier paso de conversión necesario.
- **Madurez y riesgos**: Investigar la frecuencia de actualizaciones, número de estrellas, reportes de bugs, especialmente en llamafile y exllamav2, para evaluar si son opciones “production‑ready”.
- **Licenciamiento**: Identificar restricciones (licencias MIT, Apache 2.0, uso comercial permitido) que puedan influir en la elección.
- **Soporte para cuantización**: Detallar qué métodos de cuantización acepta cada herramienta y si influye en la velocidad.
- **Requisitos de sistema**: Dependencias nativas (cmake, compilador C++, CUDA Toolkit) y su impacto en la facilidad de instalación.
- **Comportamiento con streaming**: Verificar si las librerías permiten token‑por‑token de manera natural en Python.
- **Errores comunes y solución**: Recopilar problemas frecuentes al usar cada herramienta (fallos de compilación, incompatibilidades de versión, modelos no soportados) y cómo resolverlos.

### 6. Convenciones
- **Formato de código**: Todo ejemplo estará en bloques de código Python con resaltado de sintaxis (`python`). Los comandos de terminal se indicarán con `shell`.
- **Notas y advertencias**:
  - ℹ️ Nota: información complementaria no crítica.
  - ⚠️ Advertencia: posibles puntos de fallo o configuraciones que deben manejarse con cuidado.
  - ❗ Importante: limitaciones o decisiones que afectan significativamente el resultado.
- **Diagramas**: Se usarán diagramas Mermaid para ilustrar arquitecturas de integración (in‑process vs. API) y flujos de carga de modelo.
- **Tablas**: Las comparativas usarán tablas markdown con columnas bien definidas.
- **Versiones y comandos**: Se indicará la fecha de la última verificación y los comandos de instalación exactos, por ejemplo: `pip install llama-cpp-python==0.3.2`.

### 7. Entregable esperado
Documentación técnica final en un único archivo Markdown, estructurada según las secciones definidas, que incluya:
- Introducción y criterios claros.
- Análisis detallado de al menos 6 alternativas (incluyendo Ollama como referencia).
- Ejemplos de código funcionales, probados en la investigación.
- Matriz comparativa y recomendaciones finales.
- Apéndice con instrucciones de instalación rápida para cada herramienta.
- Redacción en español, objetiva, con lenguaje adecuado para desarrolladores (sin juicios personales).
Investigación anterior o parte 1: https://admin-herandro-services-api.herandro.com.mx/reports/public?src=https:%2F%2Fcdn.herandro.com.mx%2Fbuckets%2Fpublic%2Finvestigations%2Fc5c6b310-4270-4159-9517-a396d2033b5d%2Fstep_3_final_report%2Ffinal-report-20260527T200106Z.md&title=Investigaci%C3%B3n%20de%20la%20mejor%20forma%20de%20implementar%20modelos%20locales