内存管家 · Local Model Manager
让本地 AI 模型按资源余量排队运行，同时给日常办公留出空间。
当前开源版本：v1.2.0。面向 Windows + NVIDIA GPU，提供命令行和 MCP 接口，可接入 Codex 等支持 MCP 的客户端。它是后台资源协调工具，目前没有图形界面。
它能帮你做什么？
例如，你正在用 ComfyUI 生成视频，另一个聊天又想启动本地大语言模型。两边各自启动容易争抢内存和显存。内存管家让接入的任务先申请资源，条件不够时排队，每次推理前重新检查，完成后释放资源。任务始终保留原有分辨率、步数、模型精度和上下文要求。
| 能力 | 具体用途 |
|---|---|
| RAM、系统提交量、显存监测 | 分清哪一种容量不足，避免把物理内存回收当成显存扩容 |
| 跨聊天资源排队 | 多个客户端共享一个后台服务，通过凭证协调已登记的模型 |
| 推理前准入检查 | 根据实际任务规格、已有测量和桌面余量决定是否允许新提交 |
| 受控启停 | 核对进程身份和后端忙闲状态；忙碌或身份不明时拒绝停止 |
| 有界自适应 | 按模型与工作流分别积累峰值、耗时和质量反馈；遇到压力增加保护，可回退策略 |
| 闲置应用物理内存回收 | v1.2.0 新增；真实模型任务持续缺 RAM 时，对符合条件的最小化应用执行有限的工作集回收 |
| 状态、历史与健康报告 | 解释为什么等待、是否有观测缺失、哪些经验可以用于容量预测 |
适合在同一台 Windows 电脑上运行本地视频模型、ComfyUI 和 llama.cpp，同时还需要浏览器、编辑器、录制或办公的人。仅安装它不会自动接管其他软件；任务必须走 MCP、CLI 包装器或资源凭证接口。
能力边界
- 当前调度以 NVIDIA GPU 0 为准；没有多 GPU 调度、AMD/macOS/Linux 完整运行支持。缺少必要遥测时会阻止准入。
- 它不能增加硬件容量、硬隔离显存或抢占正在执行的推理，也不能阻止绕过管家的客户端抢资源。
- 不会为了放行任务而自动降低生成质量。预算超过硬件能力时会报告
policy_infeasible，而不是无限等待或偷偷缩减预算。 - 闲置回收调用 Windows
EmptyWorkingSet，不关闭、暂停或重启应用。它移出可分页的物理驻留页，不减少私有提交量，不释放显存；切回应用可能重新调页，不能保证提速。 - 状态采样、CPU 调度延迟和自动测试不等于人工确认桌面流畅，也不等于生成质量验收。
- 项目不包含模型权重、ComfyUI、llama.cpp 或个人安装环境；这些软件须自行安装并遵守各自许可证。
安装与首次运行
需要 Windows、Python 3.12（本次验证版本为 3.12.14）、Git，以及可运行 nvidia-smi 的 NVIDIA 驱动。普通用户权限即可。以下命令在 PowerShell 中执行：
git clone https://github.com/tt1145142222/local-model-manager.git
cd local-model-manager
py -3.12 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
Copy-Item config.example.json config.json
.\.venv\Scripts\python.exe manager.py status
status 会在需要时自动启动轻量后台管家，不会启动模型。首次配置的 models 为空，这是预期状态。请只运行一个管家实例；默认地址为 127.0.0.1:18765，若本机已有实例，应复用它，或先在没有活动任务时正常关闭旧实例。
运行时仅需要 psutil；MCP stdio 层由本项目的标准库实现提供，无需额外安装 MCP SDK。启动后，凭证、SQLite 状态和日志保存在仓库下的 work/，已加入忽略规则。
1. 登记你已安装的模型
先复制 examples/llamacpp.manifest.json 或 examples/comfyui.manifest.json 到自己的工作目录，修改：
root、exe和start_argv中的所有路径：必须指向真实文件。url与启动端口：保持一致，只允许127.0.0.1。- 启动参数：沿用你已验证可运行的模型、精度、采样及上下文配置。示例不代替模型安装说明。
startup_*_gib：按实际模型和硬件设置保守启动阈值；示例值不是通用最低配置。不要为强行放行而调低预算。
llama.cpp 需暴露 /health 和 /slots，使用单推理槽 -np 1，且 -c 与 context_capacity 一致。ComfyUI 需提供 /queue。示例中的 model.gguf 是占位名称。
New-Item -ItemType Directory -Path work -Force
Copy-Item examples/llamacpp.manifest.json work/my-llm.json
# 编辑 work/my-llm.json，填写实际路径、启动参数及预算后执行：
.\.venv\Scripts\python.exe manager.py register --model my-llm --manifest work/my-llm.json
登记只验证并保存配置，不启动模型。登记时不能有排队或活动任务。h3 和 muse 是原安装环境的保留 ID；新安装请使用自己的名称，例如 my-llm、my-video。
2. 接入 Codex / MCP 客户端
将以下条目合并到客户端的 MCP 配置，替换路径，不要覆盖已有服务器配置：
[mcp_servers.local_models]
command = "C:/Tools/local-model-manager/.venv/Scripts/python.exe"
args = ["C:/Tools/local-model-manager/mcp_server.py"]
其他 MCP 客户端使用相同的 stdio 命令和参数。重新加载连接后，让助手遵循以下资源协议：
对已登记模型，先 status，再 request；仅在 active 且 proceed=true 时继续。每次实际推理前 prepare；只有本次 prepare 返回 proceed=true 才提交。长任务定期 lease 续期；完成推理与原流程质量检查后 complete，整批结束 release。保留原质量参数，quality 未评估就填 unknown。外部服务停止需要针对具体对象的授权。
MCP 管家不会替你调用模型推理接口。 原有 ComfyUI/LLM 工作流继续执行生成，管家负责允许何时执行和记录结果。完整工具映射见 使用与集成说明。
3. 用一条命令包装现有脚本
复制并修改 examples/task-llm.json，填写本次实际 token/上下文规模，以及能标识模型、精度、采样配置的 workflow_signature：
Copy-Item examples/task-llm.json work/task.json
.\.venv\Scripts\python.exe manager.py run --model my-llm --owner demo --task-file work/task.json -- C:/YourPython/python.exe C:/YourProject/infer.py
包装器自动申请、等待、prepare、续期、记录完成并释放。脚本退出成功只表示执行完成，质量仍为 unknown。若原流程产生本次 QA 文件，可加 --qa-file work/qa.json；不要预造 passed。
一个脚本内部多次提交推理时，每次都需要单独 prepare/complete；外层 run 只检查命令启动，不能替代每次推理检查。
4. 查看状态、回收记录与停机
.\.venv\Scripts\python.exe manager.py status
.\.venv\Scripts\python.exe manager.py health-report
.\.venv\Scripts\python.exe manager.py app-memory
.\.venv\Scripts\python.exe manager.py history
.\.venv\Scripts\python.exe manager.py learning
# 没有排队或活动任务时正常关闭管家，保留模型服务：
.\.venv\Scripts\python.exe manager.py shutdown
v1.2.0 的闲置内存回收怎么工作？
公开示例配置中 app_memory_reclaim.enabled 为 false。需要此功能时，在无任务时正常关闭管家，将其改为 true 后重新启动。启用后，只有有效模型任务持续 15 秒 缺少 RAM，才考虑同一用户/桌面会话内：所有可见窗口都已最小化、连续 10 分钟 CPU/I/O 活动低、工作集至少 256 MiB 的应用。
前台程序及其进程族、模型和任务进程、Codex、常见办公/编辑/录制/媒体应用、脚本运行时受保护；无窗口服务、托盘程序、身份不明或权限不足的目标跳过。每次最多处理一个应用的 4 个进程，全局间隔至少 60 秒，同一应用冷却 30 分钟，一次持续压力最多 3 次。执行前还会重查身份、活动与 RAM 需求。
关闭方法：在无任务时执行 shutdown，将 config.json 中 app_memory_reclaim.enabled 改为 false，再执行 status 启动。不要直接修改正在运行的配置并假定已经生效。
最新快照还包含持久停用控制：若部署目录存在明确的用户停用标记，普通调用不会自动重启管家或接受新任务；已获准保留的任务可继续完成。停用控制与仅关闭应用回收不同，详见 使用说明。
测试与开发
.\.venv\Scripts\python.exe -m unittest discover -s . -p "test_*.py" -v
默认测试使用隔离的临时目录、模拟后端和公开测试配置，不启动真实模型。smoke_*.py 属于按需运行的本机集成检查，其中部分会申请资源或启停模型，不应当作默认测试批量执行。测试范围与本次结果见 验证记录。
许可证
本项目源码以 MIT License 开源，允许使用、修改、分发和商业使用，须保留许可证与版权声明。外部模型、软件及其素材的授权不由本许可证授予。