🤖 @joelrd01/llama-cpp-qwen2.5-0.5b

📖 Descripción

Este paquete npm proporciona una integración sencilla y directa con el modelo Qwen2.5-0.5B-Instruct en formato GGUF, permitiendo ejecutar inferencias de inteligencia artificial directamente desde Node.js utilizando la librería node-llama-cpp.

✨ Características Principales

• ⬇️ Descarga Automática: El modelo se descarga automáticamente al instalar el paquete
• 🚀 Fácil de Usar: API minimalista y intuitiva
• 💻 Multiplataforma: Soporta CPU y GPU (CUDA, Vulkan, Metal)
• 📦 GGUF: Formato optimizado para eficiencia en memoria

🛠️ Instalación

Requisitos Previos

| Requisito | Versión Mínima | |-----------|----------------| | Node.js | 16.0.0+ | | npm | 7.0.0+ |

Instalación del Paquete

npm install @joelrd01/llama-cpp-qwen2.5-0.5b

Nota: El script postinstall se ejecutará automáticamente para descargar el modelo GGUF desde Hugging Face.

📚 Estructura del Proyecto

llama-cpp-qwen2.5:0.5b/
├── 📄 index.js              # Punto de entrada principal
├── 📂 scripts/
│   ├── 📥 postinstall.js   # Script de descarga del modelo
│   └── ✅ verify.js         # Script de verificación
├── 📂 node_modules/
│   └── @joelrd01/
│       └── llama-cpp-qwen2.5-0.5b/
│           └── model/
│               └── model.gguf  # Modelo descargado
└── 📦 package.json

🎯 Uso Rápido

Ejemplo Básico

import { initModelLocal, getModelPath, getModelInfo } from '@joelrd01/llama-cpp-qwen2.5-0.5b';

// Crear instancia del modelo
const model = new initModelLocal();

// Inicializar el modelo
await model.init();

// Ejecutar una consulta
const response = await model.runModel(
  'Eres un asistente útil.',
  '¿Cuál es la capital de Francia?'
);

console.log(response);
// Output: "La capital de Francia es París."

Ejemplo con Configuración Personalizada

import { initModelLocal } from '@joelrd01/llama-cpp-qwen2.5-0.5b';

// Crear instancia con configuración personalizada
const model = new initModelLocal({
  gpu: { vulkan: true },      // Habilitar Vulkan
  gpuLayers: 16,              // 16 capas en GPU
  contextSize: 8192,          // Contexto de 8192 tokens
  batchSize: 1024,            // Batch size aumentado
  ignoreMemorySafetyChecks: false
});

// Inicializar y ejecutar
await model.init();

const response = await model.runModel(
  'Eres un experto en programación.',
  'Explica qué es un closure en JavaScript.'
);

📖 Referencia de API

Clase initModelLocal

Constructor que crea una nueva instancia del modelo con configuración opcional.

new initModelLocal(options?)

Parámetros del Constructor

| Parámetro | Tipo | Valor por Defecto | Descripción | |-----------|------|-------------------|-------------| | gpu | Object | { vulkan: false, cuda: false, metal: false } | Configuración de GPU | | gpuLayers | number | 2 | Número de capas en GPU | | contextSize | number | 4096 | Tamaño del contexto en tokens | | batchSize | number | 512 | Tamaño del batch | | ignoreMemorySafetyChecks | boolean | false | Ignorar verificaciones de memoria |

Opciones de GPU

// Modo CPU únicamente (por defecto)
gpu: {}

// Solo Vulkan
gpu: { vulkan: true }

// Solo CUDA
gpu: { cuda: true }

// Metal (macOS)
gpu: { metal: true }

Método initModelLocal.init()

Inicializa el runtime de llama, carga el modelo y crea el contexto de inferencia.

Retorno

// Promise<void> - Resuelve cuando el modelo está listo
const model = new initModelLocal();
await model.init();

Método initModelLocal.runModel(systemPrompt?, userPrompt)

Ejecuta una inferencia contra el modelo cargado.

Parámetros

| Parámetro | Tipo | Requerido | Descripción | |-----------|------|-----------|-------------| | systemPrompt | string | No | Prompt de sistema para definir el comportamiento del modelo | | userPrompt | string | Sí | Mensaje del usuario a enviar al modelo |

Retorno

// Promise<string> - Respuesta del modelo (sin espacios en blanco al inicio/final)
const respuesta = await model.runModel('Eres un asistente.', 'Hola, ¿cómo estás?');

Ejemplo Completo

import { initModelLocal } from '@joelrd01/llama-cpp-qwen2.5-0.5b';

const model = new initModelLocal();
await model.init();

// Consulta simple
const r1 = await model.runModel('', '¿Cuánto es 2 + 2?');
console.log(r1);

// Consulta con contexto
const r2 = await model.runModel(
  'Responde siempre en español y de forma concisa.',
  'Explícame qué es una API REST.'
);
console.log(r2);

Función getModelPath()

Retorna la ruta absoluta al directorio del modelo.

Retorno

// string - Ruta absoluta al directorio del modelo
const ruta = getModelPath();
// => /home/usuario/proyecto/node_modules/@joelrd01/llama-cpp-qwen2.5-0.5b/model

4. getModelInfo()

Retorna metadatos sobre los archivos del modelo descargado.

Retorno

// Object - Metadatos del modelo
{
  path: string,           // Ruta absoluta del directorio
  files: string[],        // Nombres de archivos GGUF
  fileCount: number,      // Cantidad de archivos
  totalSizeBytes: number, // Tamaño total en bytes
  totalSizeMB: string,    // Tamaño en MB (2 decimales)
  totalSizeGB: string     // Tamaño en GB (2 decimales)
}

Ejemplo

import { getModelInfo } from '@joelrd01/llama-cpp-qwen2.5-0.5b';

const info = getModelInfo();
console.log(`
📦 Modelo: Qwen2.5-0.5B-Instruct GGUF
📁 Archivos: ${info.fileCount}
💾 Tamaño: ${info.totalSizeMB} MB
📂 Ubicación: ${info.path}
`);

🔧 Configuración Avanzada

Configuración de Memoria

// Para sistemas con memoria limitada
const model = new initModelLocal({
  gpuLayers: 0,                         // Solo CPU
  contextSize: 2048,                     // Contexto reducido
  batchSize: 256,                       // Batch pequeño
  ignoreMemorySafetyChecks: false       // Mantener verificaciones
});
await model.init();

Optimización para GPU

// Configuración para GPU dedicada
const model = new initModelLocal({
  gpu: { cuda: true },      // NVIDIA GPU
  gpuLayers: 32,            // Todas las capas en GPU
  contextSize: 8192,        // Contexto amplio
  batchSize: 2048,          // Batch grande
});
await model.init();

🎨 Múltiples Instancias

Cada instancia de initModelLocal mantiene su propio estado:

// Crear múltiples instancias independientes
const model1 = new initModelLocal({ gpuLayers: 4 });
const model2 = new initModelLocal({ gpuLayers: 0 }); // CPU-only

await model1.init();
await model2.init();

// Cada modelo puede tener diferente configuración
const r1 = await model1.runModel('', 'Pregunta 1');
const r2 = await model2.runModel('', 'Pregunta 2');

⚠️ Manejo de Errores

Modelo No Encontrado

// Error: Model directory not found
// Solución: Ejecutar npm run postinstall
npm run postinstall

Memoria Insuficiente

// Reducir uso de memoria
const model = new initModelLocal({
  gpuLayers: 0,
  contextSize: 2048,
  batchSize: 256
});
await model.init();

📊 Benchmark Rápido

| Configuración | Velocidad Aproximada | |--------------|---------------------| | CPU (1 hilo) | ~30 tokens/segundo | | CPU (4 hilos) | ~80 tokens/segundo | | GPU (CUDA) | ~200 tokens/segundo | | GPU (Vulkan) | ~150 tokens/segundo |

Valores aproximados, varían según hardware

📝 Scripts Disponibles

| Script | Descripción | |--------|-------------| | npm run postinstall | Descarga el modelo GGUF | | npm run test | Verifica la instalación del modelo |

🔗 Recursos Externos

| Recurso | Enlace | |---------|--------| | Repositorio GitHub | HuggingFace | | Modelo en HuggingFace | Qwen2.5-0.5B-Instruct-GGUF | | Librería node-llama-cpp | npm |

📄 Licencia

MIT License - Ver archivo LICENSE

👨‍💻 Autor

joelrd01