Rookery是一款Rust编写的本地LLM推理管理工具，通过单一守护进程统一管理llama.cpp和vLLM后端，支持模型热切换、GPU实时监控、智能休眠唤醒、Agent生命周期管理等功能，并配备Leptos WASM实时仪表板。

Rookery：本地大模型推理的统一指挥中心，支持热切换与多后端管理\n\n随着开源大语言模型（LLM）的蓬勃发展，越来越多的开发者和团队选择在本地部署模型以获得更好的隐私保护和成本控制。然而，本地推理生态面临着后端碎片化、模型切换繁琐、资源管理困难等挑战。llama.cpp、vLLM、TensorRT-LLM等后端各有优劣，却缺乏统一的管控界面。\n\nRookery项目应运而生，它是一款用Rust编写的本地推理指挥中心，通过单一守护进程整合llama-server（GGUF格式）和vLLM（Safetensors/AWQ/GPTQ/NVFP4格式）两大主流后端，提供CLI控制、REST API和实时Web仪表板三位一体的管理体验。本文将深入介绍其核心功能、架构设计和使用场景。\n\n## 核心功能全景\n\nRookery的设计理念是"一个守护进程管理所有本地推理需求"。其核心功能可归纳为以下几个维度：\n\n多后端统一管理。Rookery同时支持llama.cpp（通过llama-server）和vLLM两大推理后端，用户可以在同一配置文件中定义不同格式的模型，并根据需求灵活切换。这种统一抽象层消除了后端差异带来的管理复杂度。\n\n模型热切换。这是Rookery最具特色的功能之一。用户可以在不重启守护进程的情况下，通过rookery swap <profile>命令切换到另一个模型配置。热切换过程会优雅地停止当前后端、加载新模型并恢复服务状态，整个过程在秒级完成。对于需要频繁对比不同模型表现的场景（如基准测试、A/B测试），这一功能极大地提升了工作效率。\n\n实时GPU监控。通过NVIDIA NVML库，Rookery提供实时的GPU状态监控，包括显存使用、温度、利用率、功耗以及各进程的显存占用详情。这些数据通过REST API暴露，并在Web仪表板中以可视化仪表盘形式呈现。\n\n智能休眠与唤醒。Rookery支持配置空闲超时（默认30分钟），当推理服务在指定时间内无请求时，自动卸载模型释放显存。下一次请求到达时，系统透明地重新加载模型并处理请求。这一机制对于需要7x24小时运行但请求不频繁的场景（如个人开发环境、低频API服务）可以显著降低能耗和硬件损耗。\n\nAgent生命周期管理。除了模型推理，Rookery还提供了外部Agent进程的管理能力。用户可以定义Agent配置（如Telegram机器人、编码助手），Rookery负责启动、监控、崩溃自动重启和日志收集。这为构建复杂的AI应用系统提供了基础设施支持。\n\n模型发现与下载。内置的HuggingFace集成允许用户直接从CLI搜索模型、浏览量化版本、查看显存适配建议，并一键下载最佳匹配的量化文件。这简化了模型获取流程，避免了手动浏览网页和wget下载的繁琐。\n\n推理健康检查。Rookery实现了"推理金丝雀"机制，定期发送测试请求验证后端健康状态。一旦检测到CUDA僵死或其他故障，系统会自动重启后端服务，保证服务可用性。\n\n## 技术架构与实现\n\nRookery采用Rust语言开发，充分利用了Rust的内存安全、零成本抽象和高性能特性。项目采用多crate工作空间结构：\n\n- rookery-core：配置管理、状态机和共享类型定义\n- rookery-engine：进程管理、GPU监控、健康检查和Agent管理器的核心实现\n- rookery-daemon：基于axum的REST API服务、SSE事件流、认证中间件和嵌入式仪表板\n- rookery-dashboard：使用Leptos框架开发的WASM前端，编译后嵌入到守护进程二进制中\n- rookery-cli：基于clap的命令行客户端\n\n这种分层架构清晰分离了关注点，core提供领域模型，engine处理业务逻辑，daemon暴露网络接口，dashboard提供用户界面，cli则是轻量级的HTTP客户端。\n\n守护进程启动时会协调持久化状态、收养孤儿进程、自动启动配置的Agent，并清理残留的llama-server进程。InferenceBackend trait抽象了llama-server和vLLM的差异，使得上层逻辑可以统一处理不同后端。\n\n## 配置系统详解\n\nRookery使用TOML格式的配置文件，默认位于~/.config/rookery/config.toml。配置分为模型定义和运行配置两个层次：\n\ntoml\nllama_server = \"/path/to/llama-server\"\ndefault_profile = \"qwen_fast\"\nauto_start = true\nidle_timeout = 1800\n\n[models.qwen35]\nsource = \"hf\"\nrepo = \"unsloth/Qwen3.5-35B-A3B-GGUF\"\nfile = \"UD-Q4_K_XL\"\nestimated_vram_mb = 25800\n\n[profiles.qwen_fast]\nmodel = \"qwen35\"\naliases = [\"fast\", \"moe\"]\nport = 8081\n\n[profiles.qwen_fast.llama_server]\nctx_size = 262144\nflash_attention = true\nreasoning_budget = 0\ntemp = 0.7\ntop_p = 0.8\n\n\n模型定义指定了模型来源（目前支持HuggingFace）、仓库地址、具体文件名和预估显存占用。运行配置（profile）则定义了如何运行模型，包括绑定的模型、端口别名、后端特定参数（如上下文长度、采样参数、FlashAttention开关等）。\n\n这种分离设计允许同一模型定义被多个profile复用，例如可以为同一模型创建"快速模式"（较小上下文、较高温度）和"精确模式"（完整上下文、零温度）两个profile。\n\n## Web仪表板功能\n\nRookery的Web仪表板基于Leptos（Rust的响应式Web框架）和WASM技术构建，编译后嵌入到守护进程二进制中，无需额外部署前端服务。仪表板包含七个功能标签页：\n\n概览（Overview）：GPU仪表盘、服务状态、模型信息、Agent摘要\n\n设置（Settings）：profile切换器、采样参数编辑器\n\nAgent（Agents）：Agent卡片、控制按钮、看门狗状态、过滤日志\n\n聊天（Chat）：支持流式输出的交互式聊天测试界面\n\n基准（Bench）：prompt processing和token生成速度基准测试\n\n日志（Logs）：实时日志查看器，支持跟随模式\n\n模型（Models）：HuggingFace搜索、量化版本浏览、下载管理\n\n仪表板支持键盘快捷键：1-7切换标签页，s启动服务，x停止服务，t切换主题。这种设计使得在浏览器中就能完成大部分日常操作，无需记忆CLI命令。\n\n## REST API设计\n\nRookery暴露了完整的REST API，当配置了api_key时，所有/api/*数据路由和SSE事件流都需要Bearer Token认证。例外的是健康检查端点（/api/health）、Prometheus指标（/metrics）和仪表板HTML外壳（数据获取需要认证）。\n\n主要API端点包括：\n\n- 服务控制：/api/start、/api/stop、/api/sleep、/api/wake、/api/swap\n- 状态查询：/api/status、/api/gpu、/api/profiles\n- 基准测试：/api/bench\n- 日志与事件：/api/logs、/api/events（SSE流）\n- 聊天代理：/api/chat（自动唤醒休眠后端）\n- Agent管理：/api/agents、/api/agents/start、/api/agents/stop等\n- 模型管理：/api/models/search、/api/models/pull等\n- 配置管理：/api/config、/api/config/profile/{name}\n\n/metrics端点暴露Prometheus格式的指标，包括GPU状态、服务状态、Agent状态和金丝雀检查结果，便于集成到现有的监控体系中。\n\n## 与同类工具对比\n\nRookery在功能矩阵上与llama-swap、GPUStack、LocalAI等工具形成差异化竞争：\n\n| 功能 | Rookery | llama-swap | GPUStack | LocalAI |\n|------|---------|------------|----------|---------|\n| 热切换profile | 支持 | 支持 | 不支持 | 不支持 |\n| 多后端（llama.cpp+vLLM） | 支持 | 不支持 | 部分支持 | 支持 |\n| 实时仪表板 | 支持（WASM） | 不支持 | 支持 | 不支持 |\n| Agent生命周期管理 | 支持 | 不支持 | 不支持 | 不支持 |\n| 模型浏览器+下载 | 支持 | 不支持 | 支持 | 支持 |\n| 显存感知推荐 | 支持 | 不支持 | 支持 | 不支持 |\n| 自动休眠/唤醒 | 支持 | 支持 | 不支持 | 不支持 |\n| 推理金丝雀+自动重启 | 支持 | 不支持 | 支持 | 不支持 |\n| Prometheus指标 | 支持 | 不支持 | 支持 | 支持 |\n| 单二进制+嵌入式仪表板 | 支持 | 支持 | 不支持 | 不支持 |\n\n可以看出，Rookery在功能完整性上具有明显优势，特别是Agent管理和推理金丝雀功能是竞品所不具备的。\n\n## 典型使用场景\n\n场景一：开发测试环境。开发者需要频繁切换不同模型对比效果。使用Rookery可以在不重启服务的情况下热切换模型，配合rookery bench快速获取性能数据，大幅提升迭代效率。\n\n场景二：7x24小时低功耗服务。个人项目或小型团队的API服务请求频率不高，但需要保持可用。配置auto_start = true和idle_timeout = 1800，系统会在空闲30分钟后自动卸载模型，下次请求时透明唤醒，既保证可用性又降低能耗。\n\n场景三：Agent托管。部署Telegram机器人、Discord机器人或其他AI Agent时，Rookery的Agent管理功能提供进程监控、崩溃自动重启、日志聚合等运维能力，简化了服务管理。\n\n场景四：多模型A/B测试。生产环境中需要对比不同模型表现时，可以为每个模型创建profile，通过rookery swap快速切换，配合基准测试和日志分析评估效果。\n\n## 安装与部署\n\nRookery提供多种安装方式：\n\n一键安装脚本（推荐）：\nbash\ncurl -fsSL https://raw.githubusercontent.com/lance0/rookery/main/install.sh | sh\n\n\nGitHub Releases下载：提供Linux x86_64和ARM64预编译二进制包。\n\n源码编译（需要Rust 1.85+和NVIDIA CUDA驱动）：\nbash\ngit clone https://github.com/lance0/rookery.git\ncd rookery\nsudo make install\n\n\n编译安装支持自定义前缀、服务用户和模型缓存目录：\nbash\nsudo make install PREFIX=/opt/rookery SERVICE_USER=myuser HF_HOME=/mnt/models\n\n\n安装完成后，使用rookeryd启动守护进程，rookery作为CLI客户端与守护进程通信。systemd集成提供OOM保护、journal日志记录和优雅关机支持。\n\n## 平台支持与限制\n\n当前支持平台：\n- Linux x86_64 + NVIDIA GPU：完全支持\n- Linux ARM64 + NVIDIA GPU：支持（包括Jetson等嵌入式平台）\n- AMD GPU（ROCm）：未测试\n- macOS（Metal）：不支持（依赖NVML进行GPU监控）\n\n由于核心功能依赖NVIDIA NVML库进行GPU监控，macOS和纯CPU环境无法使用GPU监控功能，但理论上可以修改源码支持纯CPU推理模式。\n\n## 总结\n\nRookery为本地LLM推理管理提供了一个功能完备、设计精良的解决方案。其多后端支持、热切换能力、智能休眠、Agent管理和实时仪表板等功能，填补了现有工具在统一性和易用性方面的空白。Rust语言的高性能和内存安全特性保证了系统的稳定性和资源效率。\n\n对于需要在本地部署和管理多个LLM的个人开发者、研究团队或小型企业，Rookery提供了一个值得考虑的"一站式"解决方案。随着项目的持续迭代，期待未来能够支持更多后端（如TensorRT-LLM、AMD ROCm）和平台（如macOS Metal、纯CPU模式），进一步扩大适用范围。

Rookery：本地大模型推理的统一指挥中心，支持热切换与多后端管理\n\n随着开源大语言模型（LLM）的蓬勃发展，越来越多的开发者和团队选择在本地部署模型以获得更好的隐私保护和成本控制。然而，本地推理生态面临着后端碎片化、模型切换繁琐、资源管理困难等挑战。llama.cpp、vLLM、TensorRT-LLM等后端各有优劣，却缺乏统一的管控界面。\n\nRookery项目应运而生，它是一款用Rust编写的本地推理指挥中心，通过单一守护进程整合llama-server（GGUF格式）和vLLM（Safetensors/AWQ/GPTQ/NVFP4格式）两大主流后端，提供CLI控制、REST API和实时Web仪表板三位一体的管理体验。本文将深入介绍其核心功能、架构设计和使用场景。\n\n核心功能全景\n\nRookery的设计理念是"一个守护进程管理所有本地推理需求"。其核心功能可归纳为以下几个维度：\n\n多后端统一管理。Rookery同时支持llama.cpp（通过llama-server）和vLLM两大推理后端，用户可以在同一配置文件中定义不同格式的模型，并根据需求灵活切换。这种统一抽象层消除了后端差异带来的管理复杂度。\n\n模型热切换。这是Rookery最具特色的功能之一。用户可以在不重启守护进程的情况下，通过rookery swap <profile>命令切换到另一个模型配置。热切换过程会优雅地停止当前后端、加载新模型并恢复服务状态，整个过程在秒级完成。对于需要频繁对比不同模型表现的场景（如基准测试、A/B测试），这一功能极大地提升了工作效率。\n\n实时GPU监控。通过NVIDIA NVML库，Rookery提供实时的GPU状态监控，包括显存使用、温度、利用率、功耗以及各进程的显存占用详情。这些数据通过REST API暴露，并在Web仪表板中以可视化仪表盘形式呈现。\n\n智能休眠与唤醒。Rookery支持配置空闲超时（默认30分钟），当推理服务在指定时间内无请求时，自动卸载模型释放显存。下一次请求到达时，系统透明地重新加载模型并处理请求。这一机制对于需要7x24小时运行但请求不频繁的场景（如个人开发环境、低频API服务）可以显著降低能耗和硬件损耗。\n\nAgent生命周期管理。除了模型推理，Rookery还提供了外部Agent进程的管理能力。用户可以定义Agent配置（如Telegram机器人、编码助手），Rookery负责启动、监控、崩溃自动重启和日志收集。这为构建复杂的AI应用系统提供了基础设施支持。\n\n模型发现与下载。内置的HuggingFace集成允许用户直接从CLI搜索模型、浏览量化版本、查看显存适配建议，并一键下载最佳匹配的量化文件。这简化了模型获取流程，避免了手动浏览网页和wget下载的繁琐。\n\n推理健康检查。Rookery实现了"推理金丝雀"机制，定期发送测试请求验证后端健康状态。一旦检测到CUDA僵死或其他故障，系统会自动重启后端服务，保证服务可用性。\n\n技术架构与实现\n\nRookery采用Rust语言开发，充分利用了Rust的内存安全、零成本抽象和高性能特性。项目采用多crate工作空间结构：\n\n- rookery-core：配置管理、状态机和共享类型定义\n- rookery-engine：进程管理、GPU监控、健康检查和Agent管理器的核心实现\n- rookery-daemon：基于axum的REST API服务、SSE事件流、认证中间件和嵌入式仪表板\n- rookery-dashboard：使用Leptos框架开发的WASM前端，编译后嵌入到守护进程二进制中\n- rookery-cli：基于clap的命令行客户端\n\n这种分层架构清晰分离了关注点，core提供领域模型，engine处理业务逻辑，daemon暴露网络接口，dashboard提供用户界面，cli则是轻量级的HTTP客户端。\n\n守护进程启动时会协调持久化状态、收养孤儿进程、自动启动配置的Agent，并清理残留的llama-server进程。InferenceBackend trait抽象了llama-server和vLLM的差异，使得上层逻辑可以统一处理不同后端。\n\n配置系统详解\n\nRookery使用TOML格式的配置文件，默认位于~/.config/rookery/config.toml。配置分为模型定义和运行配置两个层次：\n\ntoml\nllama_server = \"/path/to/llama-server\"\ndefault_profile = \"qwen_fast\"\nauto_start = true\nidle_timeout = 1800\n\n[models.qwen35]\nsource = \"hf\"\nrepo = \"unsloth/Qwen3.5-35B-A3B-GGUF\"\nfile = \"UD-Q4_K_XL\"\nestimated_vram_mb = 25800\n\n[profiles.qwen_fast]\nmodel = \"qwen35\"\naliases = [\"fast\", \"moe\"]\nport = 8081\n\n[profiles.qwen_fast.llama_server]\nctx_size = 262144\nflash_attention = true\nreasoning_budget = 0\ntemp = 0.7\ntop_p = 0.8\n\n\n模型定义指定了模型来源（目前支持HuggingFace）、仓库地址、具体文件名和预估显存占用。运行配置（profile）则定义了如何运行模型，包括绑定的模型、端口别名、后端特定参数（如上下文长度、采样参数、FlashAttention开关等）。\n\n这种分离设计允许同一模型定义被多个profile复用，例如可以为同一模型创建"快速模式"（较小上下文、较高温度）和"精确模式"（完整上下文、零温度）两个profile。\n\nWeb仪表板功能\n\nRookery的Web仪表板基于Leptos（Rust的响应式Web框架）和WASM技术构建，编译后嵌入到守护进程二进制中，无需额外部署前端服务。仪表板包含七个功能标签页：\n\n概览（Overview）：GPU仪表盘、服务状态、模型信息、Agent摘要\n\n设置（Settings）：profile切换器、采样参数编辑器\n\nAgent（Agents）：Agent卡片、控制按钮、看门狗状态、过滤日志\n\n聊天（Chat）：支持流式输出的交互式聊天测试界面\n\n基准（Bench）：prompt processing和token生成速度基准测试\n\n日志（Logs）：实时日志查看器，支持跟随模式\n\n模型（Models）：HuggingFace搜索、量化版本浏览、下载管理\n\n仪表板支持键盘快捷键：1-7切换标签页，s启动服务，x停止服务，t切换主题。这种设计使得在浏览器中就能完成大部分日常操作，无需记忆CLI命令。\n\nREST API设计\n\nRookery暴露了完整的REST API，当配置了api_key时，所有/api/*数据路由和SSE事件流都需要Bearer Token认证。例外的是健康检查端点（/api/health）、Prometheus指标（/metrics）和仪表板HTML外壳（数据获取需要认证）。\n\n主要API端点包括：\n\n- 服务控制：/api/start、/api/stop、/api/sleep、/api/wake、/api/swap\n- 状态查询：/api/status、/api/gpu、/api/profiles\n- 基准测试：/api/bench\n- 日志与事件：/api/logs、/api/events（SSE流）\n- 聊天代理：/api/chat（自动唤醒休眠后端）\n- Agent管理：/api/agents、/api/agents/start、/api/agents/stop等\n- 模型管理：/api/models/search、/api/models/pull等\n- 配置管理：/api/config、/api/config/profile/{name}\n\n/metrics端点暴露Prometheus格式的指标，包括GPU状态、服务状态、Agent状态和金丝雀检查结果，便于集成到现有的监控体系中。\n\n与同类工具对比\n\nRookery在功能矩阵上与llama-swap、GPUStack、LocalAI等工具形成差异化竞争：\n\n| 功能 | Rookery | llama-swap | GPUStack | LocalAI |\n|------|---------|------------|----------|---------|\n| 热切换profile | 支持 | 支持 | 不支持 | 不支持 |\n| 多后端（llama.cpp+vLLM） | 支持 | 不支持 | 部分支持 | 支持 |\n| 实时仪表板 | 支持（WASM） | 不支持 | 支持 | 不支持 |\n| Agent生命周期管理 | 支持 | 不支持 | 不支持 | 不支持 |\n| 模型浏览器+下载 | 支持 | 不支持 | 支持 | 支持 |\n| 显存感知推荐 | 支持 | 不支持 | 支持 | 不支持 |\n| 自动休眠/唤醒 | 支持 | 支持 | 不支持 | 不支持 |\n| 推理金丝雀+自动重启 | 支持 | 不支持 | 支持 | 不支持 |\n| Prometheus指标 | 支持 | 不支持 | 支持 | 支持 |\n| 单二进制+嵌入式仪表板 | 支持 | 支持 | 不支持 | 不支持 |\n\n可以看出，Rookery在功能完整性上具有明显优势，特别是Agent管理和推理金丝雀功能是竞品所不具备的。\n\n典型使用场景\n\n场景一：开发测试环境。开发者需要频繁切换不同模型对比效果。使用Rookery可以在不重启服务的情况下热切换模型，配合rookery bench快速获取性能数据，大幅提升迭代效率。\n\n场景二：7x24小时低功耗服务。个人项目或小型团队的API服务请求频率不高，但需要保持可用。配置auto_start = true和idle_timeout = 1800，系统会在空闲30分钟后自动卸载模型，下次请求时透明唤醒，既保证可用性又降低能耗。\n\n场景三：Agent托管。部署Telegram机器人、Discord机器人或其他AI Agent时，Rookery的Agent管理功能提供进程监控、崩溃自动重启、日志聚合等运维能力，简化了服务管理。\n\n场景四：多模型A/B测试。生产环境中需要对比不同模型表现时，可以为每个模型创建profile，通过rookery swap快速切换，配合基准测试和日志分析评估效果。\n\n安装与部署\n\nRookery提供多种安装方式：\n\n一键安装脚本（推荐）：\nbash\ncurl -fsSL https://raw.githubusercontent.com/lance0/rookery/main/install.sh | sh\n\n\nGitHub Releases下载：提供Linux x86_64和ARM64预编译二进制包。\n\n源码编译（需要Rust 1.85+和NVIDIA CUDA驱动）：\nbash\ngit clone https://github.com/lance0/rookery.git\ncd rookery\nsudo make install\n\n\n编译安装支持自定义前缀、服务用户和模型缓存目录：\nbash\nsudo make install PREFIX=/opt/rookery SERVICE_USER=myuser HF_HOME=/mnt/models\n\n\n安装完成后，使用rookeryd启动守护进程，rookery作为CLI客户端与守护进程通信。systemd集成提供OOM保护、journal日志记录和优雅关机支持。\n\n平台支持与限制\n\n当前支持平台：\n- Linux x86_64 + NVIDIA GPU：完全支持\n- Linux ARM64 + NVIDIA GPU：支持（包括Jetson等嵌入式平台）\n- AMD GPU（ROCm）：未测试\n- macOS（Metal）：不支持（依赖NVML进行GPU监控）\n\n由于核心功能依赖NVIDIA NVML库进行GPU监控，macOS和纯CPU环境无法使用GPU监控功能，但理论上可以修改源码支持纯CPU推理模式。\n\n总结\n\nRookery为本地LLM推理管理提供了一个功能完备、设计精良的解决方案。其多后端支持、热切换能力、智能休眠、Agent管理和实时仪表板等功能，填补了现有工具在统一性和易用性方面的空白。Rust语言的高性能和内存安全特性保证了系统的稳定性和资源效率。\n\n对于需要在本地部署和管理多个LLM的个人开发者、研究团队或小型企业，Rookery提供了一个值得考虑的"一站式"解决方案。随着项目的持续迭代，期待未来能够支持更多后端（如TensorRT-LLM、AMD ROCm）和平台（如macOS Metal、纯CPU模式），进一步扩大适用范围。