{"id":50701542,"url":"https://github.com/mcp-tool-shop-org/gpu-container","last_synced_at":"2026-06-09T09:30:41.986Z","repository":{"id":362555332,"uuid":"1258999335","full_name":"mcp-tool-shop-org/gpu-container","owner":"mcp-tool-shop-org","description":"Model-aware inference memory-placement planner for single-GPU rigs: profile hardware + model, generate explicit VRAM/RAM/NVMe placement plans across runtimes (llama.cpp/vLLM/...), and prove them with a measured receipt. Not VRAM overflow - declared placement.","archived":false,"fork":false,"pushed_at":"2026-06-04T20:29:52.000Z","size":1458,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T21:36:25.776Z","etag":null,"topics":["cuda","gpu","inference","llama-cpp","llm","moe","offload","vram","wsl2"],"latest_commit_sha":null,"homepage":"https://mcp-tool-shop-org.github.io/gpu-container/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mcp-tool-shop-org.png","metadata":{"files":{"readme":"README.es.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["mcp-tool-shop"]}},"created_at":"2026-06-04T05:30:35.000Z","updated_at":"2026-06-04T20:29:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mcp-tool-shop-org/gpu-container","commit_stats":null,"previous_names":["mcp-tool-shop-org/gpu-container"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/mcp-tool-shop-org/gpu-container","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-tool-shop-org%2Fgpu-container","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-tool-shop-org%2Fgpu-container/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-tool-shop-org%2Fgpu-container/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-tool-shop-org%2Fgpu-container/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcp-tool-shop-org","download_url":"https://codeload.github.com/mcp-tool-shop-org/gpu-container/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcp-tool-shop-org%2Fgpu-container/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34101064,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cuda","gpu","inference","llama-cpp","llm","moe","offload","vram","wsl2"],"created_at":"2026-06-09T09:30:41.718Z","updated_at":"2026-06-09T09:30:41.974Z","avatar_url":"https://github.com/mcp-tool-shop-org.png","language":"Python","funding_links":["https://github.com/sponsors/mcp-tool-shop"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.ja.md\"\u003e日本語\u003c/a\u003e | \u003ca href=\"README.zh.md\"\u003e中文\u003c/a\u003e | \u003ca href=\"README.md\"\u003eEnglish\u003c/a\u003e | \u003ca href=\"README.fr.md\"\u003eFrançais\u003c/a\u003e | \u003ca href=\"README.hi.md\"\u003eहिन्दी\u003c/a\u003e | \u003ca href=\"README.it.md\"\u003eItaliano\u003c/a\u003e | \u003ca href=\"README.pt-BR.md\"\u003ePortuguês (BR)\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"https://raw.githubusercontent.com/mcp-tool-shop-org/gpu-container/main/assets/logo.png\" width=\"400\" alt=\"gpu-container\" /\u003e\n\n[![CI](https://github.com/mcp-tool-shop-org/gpu-container/actions/workflows/ci.yml/badge.svg)](https://github.com/mcp-tool-shop-org/gpu-container/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/gpu-container)](https://pypi.org/project/gpu-container/)\n[![npm](https://img.shields.io/npm/v/gpu-container)](https://www.npmjs.com/package/gpu-container)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Handbook](https://img.shields.io/badge/handbook-docs-blue)](https://mcp-tool-shop-org.github.io/gpu-container/)\n\n**Un contenedor habilitado para GPU expone el dispositivo. Un entorno de ejecución consciente del modelo decide qué se almacena en la VRAM, la RAM asignada y la NVMe.**\n\n\u003c/div\u003e\n\nEjecute el modelo local más grande y útil que su máquina pueda soportar de manera realista, con planes de ubicación explícitos, informes de pruebas de rendimiento y rechazo cuando el plan cause problemas.\n\n## Arquitectura\n\n```\nWindows / WSL2 / Linux host\n  └─ GPU-enabled Docker container\n      └─ Inference runtime\n          ├─ VRAM: hot weights, active layers, activations, KV working set\n          ├─ pinned RAM: CPU-offloaded weights, MoE experts, KV spill/reuse\n          └─ NVMe: mmap shards, disk offload, cold experts, cold KV\n```\n\n## Límite del producto\n\n```\nDocker         = packaging + GPU exposure\nCUDA/runtime   = compute backend\nPlanner        = memory law\nInference engine = execution\n```\n\n## Características principales\n\n1. **Perfilador de hardware:** Detecta la VRAM, la RAM, el tipo de GPU, WSL/Linux nativo, la velocidad de NVMe y la disponibilidad de CUDA.\n2. **Perfilador de modelo:** Detecta si es denso o MoE, la capa más grande, el número total de parámetros, la cuantificación y el crecimiento de KV según la longitud del contexto.\n3. **Planificador de entorno de ejecución:** Genera planes de inicio para llama.cpp, vLLM, Accelerate, TensorRT-LLM o la descarga al estilo DeepSpeed.\n4. **Informe de ubicación:** Muestra qué hay en la VRAM, qué hay en la RAM, qué hay en el disco, el cuello de botella esperado y los tokens/segundo medidos.\n5. **Ruta especializada para MoE:** Mantiene las capas siempre activas en la GPU, dirige los expertos a la CPU/RAM y a la NVMe para la recuperación en caso de inactividad.\n6. **Reducción de riesgos en el enrutamiento:** Mide si el enrutamiento MoE de un modelo está lo suficientemente sesgado como para que una caché por experto sea útil, antes de construirlo (`gpu-container-concentration`).\n7. **Vigilante de seguridad del sistema:** Supervisa la potencia/temperatura/VRAM de la GPU y la memoria del host en comparación con los umbrales configurables; un agente de IA o un bucle autónomo aborta una ejecución antes de que ponga en peligro la máquina (`gpu-container-watchdog`).\n\n## Restricción clave\n\nEn Windows/WSL, la sobreasignación de memoria unificada de CUDA **no es la solución**. CUDA trata Windows/WSL como un soporte limitado para la memoria unificada: no hay migración de páginas de GPU de grano fino, ni sobreasignación de memoria de GPU más allá de la VRAM física. Este producto es la **ubicación explícita de la memoria de inferencia**, no el \"desbordamiento de VRAM de Docker\".\n\n## Estado\n\nConstruido y funcionando hoy: `gpu-container-profile`, `gpu-container-plan`, `gpu-container-receipt` (con el bucle de recalibración), `gpu-container-concentration` (reducción de riesgos en el enrutamiento) y `gpu-container-watchdog` (supervisión segura de un trabajo de GPU). llama.cpp es el backend integrado; las matemáticas de ubicación son independientes del backend. Comience con el [inicio rápido](docs/quickstart.md).\n\n## Privacidad y seguridad\n\n`gpu-container` es una **herramienta local y sin conexión**: no realiza llamadas de red y no recopila **ninguna telemetría**, ni por defecto ni de otra manera. Lee las métricas de la GPU (`nvidia-smi` / NVML) y la memoria del host (`psutil`), el archivo `config.json` del modelo que proporciona y los archivos JSON a los que lo apunta; solo escribe en las rutas de salida que especifica. **No** lee ni transmite los parámetros del modelo, las credenciales ni los tokens. Las acciones a nivel de host (`wsl --shutdown`, `docker stop`, `kill`) solo se ejecutan cuando usted acepta explícitamente a través del parámetro `--on-breach` del vigilante; los valores predeterminados nunca tocan su máquina más allá del trabajo que supervisan. Política completa: [SECURITY.md](SECURITY.md).\n\n## Documentación\n\n- [`docs/quickstart.md`](docs/quickstart.md): recorrido completo: perfil → plan → inicio bajo el vigilante → informe → recalibración\n- [`docs/cli.md`](docs/cli.md): los cinco comandos: resumen, opciones, códigos de salida, ejemplos prácticos\n- [`docs/architecture.md`](docs/architecture.md): modelo de niveles de memoria, flujo de datos, enrutamiento de expertos MoE, el bucle de recalibración\n- [`docs/features.md`](docs/features.md): las siete características principales en detalle\n- [`docs/moe-lane-architecture.md`](docs/moe-lane-architecture.md): la ruta MoE insignia en detalle\n- [`docs/derisk-concentration.md`](docs/derisk-concentration.md): la puerta de reducción de riesgos de la caché por experto (concentración del enrutamiento)\n- [`docs/decisions/0001-per-expert-cache-build-vs-upstream.md`](docs/decisions/0001-per-expert-cache-build-vs-upstream.md): ADR-0001: consumir el mecanismo de caché, contribuir a la política\n- [`docs/constraints.md`](docs/constraints.md): objetivos no cumplidos + la corrección de la memoria unificada de CUDA en Windows/WSL\n- [`docs/prior-art.md`](docs/prior-art.md): entornos de ejecución que orquestamos y la brecha que llena este producto\n- [`docs/feasibility.md`](docs/feasibility.md): evaluación de viabilidad, base de investigación y lo que se ha confirmado que funciona\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\nCreado por \u003ca href=\"https://mcp-tool-shop.github.io/\"\u003eMCP Tool Shop\u003c/a\u003e · Licencia MIT\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcp-tool-shop-org%2Fgpu-container","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcp-tool-shop-org%2Fgpu-container","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcp-tool-shop-org%2Fgpu-container/lists"}