Chimeraforge

Un planificador de despliegue de LLM local-first y agnóstico al modelo. Convierte "qué modelo, cuantización, GPU y backend -- cuántos, cabrá, cumplirá mi SLO, cuánto costará" en una respuesta rápida, honesta y medida, desde tu shell, tu Python o tu asistente de IA.

uvx chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB"

El principio de confianza

Cada número está etiquetado como medido, estimado o desconocido, y la herramienta se niega a falsificar los que no puede respaldar. La VRAM y la caché de KV se calculan a partir de la arquitectura real de un modelo (exacto). El rendimiento es una búsqueda medida cuando está disponible; de lo contrario, una estimación explícita de límite de ancho de banda -- nunca presentada como datos que no son. La calidad por debajo del corpus incluido informa desconocido, no una puntuación inventada. Un plan con 0 resultados nombra la puerta exacta que rechazó a cada candidato en lugar de un genérico "no se encontró nada". Sin telemetría, sin llamadas a casa, funciona aislado.

Dale un modelo -- una clase de tamaño, un repositorio de Hugging Face, una etiqueta de Ollama o anulaciones manuales para un modelo no publicado -- y busca el espacio (modelo x cuantización x backend x número de GPUs x paralelismo de tensor/pipeline) contra VRAM, calidad, latencia, coste, energía y una puerta de seguridad opcional, y luego devuelve la configuración más barata que cumple tu SLO.

12 comandos, una herramienta: plan - suggest - measure - validate - catalog - safety - bench - eval - compare - refit - report - mcp.

El corpus empírico se remonta a los Informes Técnicos TR108-TR137 (~204.000 mediciones reales en GPUs de consumo). Consulta el CHANGELOG para el historial completo de funciones.

Related MCP server: infra-advisor-mcp

Instalación

Pruébalo sin instalar:

uvx chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB"
pipx run chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB"

Instala de verdad:

pip install chimeraforge            # planner + model resolution (HF/Ollama) + suggest/measure/safety/bench
pip install chimeraforge[bench]     # + GPU environment metadata for benchmarks (pynvml)
pip install chimeraforge[mcp]       # + MCP server so Claude/GPT/Cursor can call the planner
pip install chimeraforge[eval]      # + quality evaluation (BERTScore, ROUGE-L)
pip install chimeraforge[refit]     # + coefficient refitting (numpy, scipy)
pip install chimeraforge[all]       # everything

Python 3.10+. La instalación principal cubre el planificador y los comandos orientados a red (httpx es una dependencia principal). plan / suggest / catalog funcionan completamente sin conexión; bench / measure / safety necesitan un backend en ejecución (Ollama, vLLM o TGI). Windows / macOS / Linux.

Inicio rápido

# Plan a registry size class on your GPU
chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB" --request-rate 2.0

# Plan ANY model -- a Hugging Face repo or an Ollama tag
chimeraforge plan --model Qwen/Qwen2.5-7B-Instruct --hardware "RTX 4090 24GB"
chimeraforge plan --model ollama:qwen3:14b --ollama-url http://localhost:11434

# Split a model too big for one GPU across several (tensor parallelism)
chimeraforge plan --model meta-llama/Llama-3.3-70B-Instruct --hardware "H100 80GB" --tp 4

# Shrink the KV-cache, print the cost/latency/quality trade-off menu
chimeraforge plan --model-size 8b --hardware "RTX 4080 12GB" --kv-quant q8 --pareto

# Benchmark a live model and plan on the MEASURED numbers
chimeraforge plan --model qwen3:14b --measure

# Discover + rank what fits your GPU and budget
chimeraforge suggest --source ollama --hardware "RTX 4090 24GB" --budget 500

Servidor MCP -- dale a Claude / GPT / Cursor los mismos números

El dimensionado de GPU es exactamente donde fallan los asistentes: precios y especificaciones de hardware con fecha de corte de entrenamiento, además de aritmética de caché de KV/lote propensa a errores hecha de memoria. chimeraforge mcp ejecuta un servidor MCP stdio para que un asistente llame al planificador real contra datos medidos en lugar de adivinar.

pip install "chimeraforge[mcp]"

Claude Code:

claude mcp add --transport stdio chimeraforge -- uvx --from "chimeraforge[mcp]" chimeraforge mcp

Claude Desktop / Cursor (añade a tu archivo de configuración MCP):

{
  "mcpServers": {
    "chimeraforge": {
      "command": "uvx",
      "args": ["--from", "chimeraforge[mcp]", "chimeraforge", "mcp"]
    }
  }
}

El --from "chimeraforge[mcp]" incluye el SDK de MCP; uvx ejecuta el servidor en un entorno autocontenido. Si ya has hecho pip install "chimeraforge[mcp]" en el entorno que tu cliente lanza, puedes usar en su lugar "command": "chimeraforge", "args": ["mcp"].

Expone tres herramientas: chimeraforge_plan (la búsqueda completa de puertas), chimeraforge_resolve_model (fundamenta un id de modelo en sus parámetros/arquitectura reales) y chimeraforge_list_hardware. Cada resultado lleva la misma procedencia medido / estimado / desconocido que el CLI, y las descripciones de las herramientas le dicen al modelo que las prefiera sobre su propio conocimiento. chimeraforge_plan también devuelve un campo launch -- el comando de servicio para la configuración recomendada -- para que el asistente pueda responder "y cómo lo ejecuto" sin inventar banderas.

Comandos

plan -- planificador de capacidad predictivo

chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB" --request-rate 2.0
chimeraforge plan --model Qwen/Qwen2.5-7B-Instruct --hardware "RTX 4090 24GB"   # any HF repo
chimeraforge plan --model ollama:qwen3:14b --ollama-url http://localhost:11434  # any Ollama tag
chimeraforge plan --model meta-llama/Llama-3.3-70B-Instruct --hardware "H100 80GB" --tp 4   # multi-GPU
chimeraforge plan --model-size 3b --kv-quant q4 --pareto                       # smaller KV cache, trade-off menu
chimeraforge plan --model-size 8b --hardware "RTX 4090 24GB" --launch          # + the serve command to actually run it
chimeraforge plan --model-size 3b --workload agent --safety-target 0.85 --json

• Planifica cualquier modelo: clase de tamaño de registro, repositorio HF (org/name), etiqueta de Ollama o anulaciones manuales (--params-b/--n-layers/...).

• Busca (modelo x cuantización x backend x N-réplicas x lote/GPU) a través de un pipeline de 5 puertas: VRAM -> calidad -> seguridad (opcional) -> latencia -> presupuesto.

• Modela la física real de servicio: batching continuo (vLLM/TGI), división prefill/decode (TTFT + TPOT), concurrencia limitada por caché de KV y cola consciente de varianza (--workload).

• Ajusta modelos demasiado grandes para una GPU: --tensor-parallel/--tp {N|auto} fragmenta pesos + KV entre N GPUs (estilo Megatron, con comunicaciones modeladas); --pipeline-parallel/--pp {N|auto} divide capas entre N etapas en su lugar (más barato en interconexiones lentas, necesita batching para llenar el pipeline). Aún no combinables.

• Sirve lo que el backend sirve: los cuantos GGUF se ofrecen en Ollama; vLLM/TGI reciben FP16 y FP8 (solo en GPUs con núcleos de tensor FP8 -- Ada/Hopper/Blackwell/CDNA3). El planificador ya no sugiere un checkpoint GGUF en vLLM con un aumento de velocidad de llama.cpp.

• Cuantización de caché de KV (--kv-quant {fp16,q8,q4}) reduce la caché y aumenta la concurrencia máxima -- la mayor ganancia en contexto largo.

• Realismo de costes (--duty-cycle, --gpu-price-multiplier): el precio principal de $/1M-tok valora una flota saturada. También pagas por el margen aprovisionado y por cada hora inactiva, así que la cifra efectiva en un 8B a 2 req/s es $2.71/1M a pleno ciclo y $9.04/1M al 30%, frente a $0.92 a capacidad. El precio spot/reservado es tu entrada, no una suposición incluida.

• Punto de equilibrio entre autoalojamiento y API (--compare-api): valora tu carga de trabajo contra APIs alojadas y reporta el volumen mensual donde el autoalojamiento empieza a ganar. Los precios son una instantánea con fecha y una URL de fuente por proveedor, marcada como obsoleta pasados 90 días -- nunca presentada como una cotización en vivo -- y una API de frontera se etiqueta como un nivel de calidad diferente en lugar de pasarse como equivalente.

• Caché de prefijo (--prefix-cache-hit-rate): el tráfico de chatbot y agente reutiliza un prompt de sistema largo, así que la mayor parte del prefill ya está en caché. Con un prompt de 4k y un 90% de acierto, un 8B pasa de 166ms a 17ms de TTFT. Por defecto es 0 y nunca se infiere, y el KV que un prefijo compartido ahorra no se deduce deliberadamente -- subdimensionar el KV es lo que convierte "cabe" en un OOM.

• Modelos de razonamiento (--reasoning-tokens N): los tokens de pensamiento ocultos son decodificados por la GPU y se mantienen en KV aunque el llamador nunca los vea. Contar solo la salida visible subestima la decodificación por la proporción de razonamiento -- 1000 tokens ocultos llevaron un plan de 8B de 363ms a 6128ms p95 en nuestra propia comprobación. Por defecto es 0 y nunca se infiere: la proporción es una propiedad de tu carga de trabajo, no de los pesos.

• KV consciente de la forma de atención: MLA (DeepSeek-V2/V3) cachea un latente comprimido en lugar de K/V por cabeza -- dimensionarlo como GQA sobreestima la caché de DeepSeek-V3 en 57x -- y los modelos de ventana deslizante dejan de crecer la caché más allá de la ventana. Una ventana cuyo patrón de capas no está declarado no se aplica, porque subdimensionar el KV es lo que convierte "cabe" en un OOM.

• Consciente de Mixture-of-Experts: la VRAM se dimensiona sobre los parámetros totales (cada experto permanece residente) mientras que el rendimiento y el TTFT usan los parámetros activos (un token solo lee los expertos a los que se enruta). Tratar un modelo MoE como denso subestima su rendimiento en 3.6x en Mixtral-8x7B y ~18x en DeepSeek-V3. Los recuentos activos se derivan de la geometría real de expertos del modelo y coinciden con las cifras publicadas.

• Energía (--electricity-rate): coste mensual de kWh, $/1M-tok (+energía) y tok/s por vatio, reportados junto al (no incluidos en) la puerta de presupuesto.

• Exportación de comando de lanzamiento (--launch): emite el comando vllm serve / ollama run / TGI docker run para la configuración ganadora, con la longitud de contexto del propio plan, el grado de TP/PP, el tamaño de lote y el dtype de KV rellenados -- las banderas que son propensas a error de calcular a mano. No fabrica lo que no puede derivar: un nivel de cuantización GGUF se convierte en una nota para servir el checkpoint equivalente nativo, no una bandera --quantization inventada.

• Procedencia por predicción (medido / estimado / desconocido); explica la puerta vinculante cuando nada cabe.

• Validado en datos de registro: VRAM R^2=0.968, rendimiento R^2=0.859, RMSE de calidad=0.062, MAPE de latencia=1.05% (supera el M/D/1 analítico en 20.4x, TR133). Sin ML -- tablas de búsqueda empíricas con interpolación de primeros principios (límite de ancho de banda para modelos fuera de registro).

suggest -- descubre y clasifica modelos

chimeraforge suggest --source ollama --hardware "RTX 4090 24GB" --budget 500
chimeraforge suggest --source hf --hf-limit 8 --hardware "RTX 4080 12GB"
chimeraforge suggest --source catalog --hardware "RTX 4080 12GB"   # offline, after `catalog --build`

Tira candidatos de un Ollama en vivo (/api/tags), el HF Hub (generación de texto superior) y/o el catálogo local; resuelve cada uno a parámetros/arquitectura reales, ejecuta la misma búsqueda de puertas y muestra la mejor configuración por modelo.

measure -- benchmark en vivo, planifica con números reales

chimeraforge measure --model qwen3:14b --ollama-url http://localhost:11434
chimeraforge plan --model qwen3:14b --measure   # measure then plan in one step

Benchmarkea el modelo en vivo (rendimiento real N=1, tiempo de servicio, escalado de concurrencia) y lo incorpora a un corpus local. plan / suggest prefieren entonces los números medidos automáticamente (la procedencia cambia a medido).

catalog -- catálogo de modelos local

chimeraforge catalog --build         # resolve a curated seed (+ --with-ollama) and cache specs
chimeraforge catalog                 # list the cached catalog

Persiste las especificaciones resueltas para que suggest --source catalog clasifique un conjunto conocido y bueno completamente sin conexión.

safety -- pantalla de rechazo en vivo

chimeraforge safety --model llama3.2-3b --prompts harmful.txt --quant Q4_K_M --safety-target 0.85

Donde plan --safety-target decide a partir de datos TR134/TR142 incluidos, safety mide: ejecuta tus prompts de prueba contra un modelo en vivo, clasifica los rechazos (basado en reglas -- la línea base de regex TR134), reporta la tasa de rechazo medida frente a los datos de puerta incluidos (esperado, deriva, nivel de riesgo RTSI) y sale 1 por debajo de --safety-target. Tú proporcionas los prompts (--prompts, uno por línea) -- no se incluye ningún corpus de ataque con el paquete; apúntalo a HarmBench / AdvBench / tu propio conjunto. Necesita un Ollama en ejecución.

bench -- benchmark de inferencia en vivo

chimeraforge bench --model llama3.2-3b --runs 5
chimeraforge bench --model llama3.2-3b --all-quants --context 512,1024,2048,4096 --json
chimeraforge bench --model llama3.2-3b --backend vllm --base-url http://localhost:8000

Tres perfiles de carga de trabajo (single / batch / servidor-Poisson); mide rendimiento, TTFT y latencia con p50/p90/p95/p99; advertencias de estabilidad basadas en CV; salida JSON.

eval -- evaluación de calidad

chimeraforge eval --task general_knowledge --json
chimeraforge eval --predictions preds.txt --references refs.txt --model llama3.2-3b

Métricas: coincidencia exacta, ROUGE-L (respaldo LCS), BERTScore, coherencia -> compuesta (0.2*EM + 0.3*ROUGE + 0.3*BERT + 0.2*coherencia). Niveles de calidad de TR125; 3 tareas integradas (general_knowledge, summarization, code). Pasa --fp16-baseline para clasificar el nivel de caída.

compare -- comparar ejecuciones de benchmark

chimeraforge compare --baseline run1.json --candidate run2.json,run3.json --json

Empareja configuraciones por (modelo, backend, quant, carga de trabajo, context_length); calcula deltas de rendimiento/TTFT/duración con un resumen agregado de mejora/regresión.

refit -- actualizar coeficientes del planificador

chimeraforge refit --bench-dir ./results/ --output fitted_models.json --validate

Mezcla bayesiana (ponderación de confianza por clave), offsets de hardware, reajuste de ley de potencia y una suite de validación de 10 comprobaciones que bloquea la escritura (--validate).

report -- generar informes

chimeraforge report --results-dir ./results/ --format markdown --output report.md

Markdown (compatible con GitHub) y HTML autocontenido y seguro contra XSS; análisis estadístico (RMSE, MAE, MAPE, R^2) con tablas de percentiles por configuración.

mcp -- servir el planificador a asistentes de IA

chimeraforge mcp

Ejecuta el servidor MCP stdio descrito arriba. Requiere pip install "chimeraforge[mcp]".

Qué se modela

Hardware: 22 GPUs -- Ada + Blackwell de consumo (series RTX 30/40/50), centro de datos (A100 40/80GB, H100, H200, B200, L4, T4) y AMD MI300X -- cada una con VRAM, ancho de banda, FP16 TFLOPS, TDP e interconexión (NVLink/Infinity Fabric/PCIe).

Limitaciones conocidas (honestas): La decodificación especulativa aún no está modelada. El caché de prefijos modela el ahorro de prefill pero no el ahorro de KV (deliberadamente conservador). Los tokens de razonamiento están modelados, pero la proporción es tu entrada (--reasoning-tokens), nunca inferida. Para MoE, los parámetros activos-vs-totales sí están modelados, pero el paralelismo de expertos y el desequilibrio de carga de enrutamiento no lo están. La cobertura de cuantización para vLLM/TGI es FP16 + FP8 (AWQ/GPTQ aún no); la calidad FP8 se estima, no se mide. El rendimiento de TP y PP son estimaciones modeladas por comunicaciones, no medidas, y no pueden combinarse en un mismo plan. El encolado es analítico (consciente de la varianza), no un simulador de eventos discretos. El corpus incluido se ajusta principalmente en un solo equipo (RTX 4080 12GB); otras GPUs escalan desde ancho de banda/cómputo hasta que measure en la tuya. El servidor MCP es solo stdio (Claude Code/Desktop, Cursor local) -- aún no hay transporte remoto alojado.

Lo que decidió la investigación

La Fase 2 (TR123-TR133, ~106,000 mediciones) se destiló en un marco de despliegue respaldado por artefactos -- las mismas reglas que aplica el planificador:

Hallazgos principales (datos completos en los TR): Rust supera a Python en agente único (+15.2% de rendimiento, -58% TTFT, -67% de memoria -- TR112); Ollama dual alcanza un paralelismo multiagente casi perfecto (~99%) frente al 82.2% en una sola instancia (TR110/TR113/TR114); el continuous batching de vLLM ofrece una ventaja de 2.25x en N=8, limitado por el ancho de banda de la memoria de la GPU, no por la pila (TR130-TR132).

Investigación completa: docs/archive/technical_reports.md indexa los 32 informes; el archivo completo con metodología y referencias de datos brutos vive en outputs/publish_ready/reports/.

Cómo se generan los números

• ~204,000 mediciones primarias en 32 informes técnicos (TR108-TR137 + la procedencia de seguridad TR142/TR146), en un RTX 4080 Laptop (12 GB). De-duplicadas: TR137/TR142 son síntesis de datos ya contados.

• Rigor: aislamiento de proceso limpio por ejecución (sin sesgo de caché caliente), arranques en frío forzados, 3-5 ejecuciones por configuración para confianza estadística, registro estructurado JSON/CSV con procedencia completa. Cada afirmación se remonta a datos brutos que puedes re-ejecutar.

• Contexto del programa: ChimeraForge es el empalme CLI accionable del programa padre Banterhearts (~1,337,000 mediciones primarias + de juez en 54 TRs); la investigación de superficie de ataque de seguridad y pila de servicio vive en repositorios hermanos.

• 549 pruebas automatizadas (pytest tests/) cubren los modelos del planificador, búsqueda de puertas, resolvedor, descubrimiento, seguridad, backends de bench y el servidor MCP -- desacopladas de GPU, sin backend en vivo requerido para la suite principal.

Reproduce cualquier número: encuentra la afirmación en un informe bajo outputs/publish_ready/reports/, sigue su referencia a la carpeta de datos, inspecciona el CSV/JSON y re-ejecuta los scripts o notebooks proporcionados. Consulta docs/archive/methodology.md.

Estructura del repositorio

Documentación

• docs/README.md -- índice de documentación y navegación

• docs/quick_start.md -- primera ejecución de benchmark (Python + Rust)

• docs/API.md -- referencia de API de Python para el paquete

• docs/archive/technical_reports.md -- índice de los 32 informes técnicos

• docs/archive/dual_ollama_setup.md -- requerido para reproducir resultados multiagente

• docs/archive/methodology.md / docs/archive/rust_vs_python.md -- metodología y la comparación completa de lenguajes

Contribuciones

Contribuciones bienvenidas -- consulta CONTRIBUTING.md. Buenas áreas: configuraciones de benchmark adicionales, nuevas estrategias de optimización, más modelos/hardware, documentación y herramientas de análisis.

Licencia

MIT -- consulta LICENSE.

Agradecimientos

Realizado como parte del Programa de Investigación de Rendimiento LLM de Banterhearts: la Fase 1 (TR108-TR122) estableció la metodología de medición y la comparación entre lenguajes, la Fase 2 (TR123-TR133) produjo el marco de despliegue y el planificador de capacidad, y la Fase 3 (TR134-TR137) midió el coste de seguridad de la optimización de inferencia -- ahora la puerta de seguridad opcional del planificador.

Repositorio: https://github.com/Sahil170595/Chimeraforge - PyPI: https://pypi.org/project/chimeraforge/ - Estado: Beta, en desarrollo activo