Inference AIops

Inference AIops

免责声明：由社区维护的开源项目。**与 vLLM 或 Ray 项目及任何推理服务供应商均无关联，也未获得其认可或赞助。**产品名称和商标归其所有者所有。采用 MIT 许可。

面向 GPU 推理集群 的受治理 AI 运维——支持 vLLM（OpenAI API + Prometheus /metrics）和 Ray Serve / Ray Jobs（Ray 仪表板），以及单进程 服务引擎 SGLang 和 TGI (Text Generation Inference)——并内置 治理机制：统一审计日志、策略引擎、令牌／失控预算保护、撤销令牌记录，以及每条审计记录上的描述性风险等级标签。它会直接解析每种引擎的 Prometheus /metrics（无需 Prometheus 服务），并独立探测 Ray 仪表板。承载令牌为可选项（许多技术栈以开放方式运行）。

服务引擎。 vLLM 是旗舰引擎（完整的 Ray Serve 控制平面：扩缩容、 排空、自动扩缩容、LoRA、热切换）。SGLang 和 TGI 支持与引擎无关的可观测性——健康状况、运行模型身份、请求延迟 指标、队列深度和延迟根因分析——数据从各引擎自身的端点和指标名称中读取。由于是单进程服务，这些引擎没有 Ray 风格的扩缩容／排空 API：此类写入操作会返回教学提示错误，建议使用真正的水平扩缩容 层（Ray Serve / Kubernetes / 负载均衡器）。

功能

核心价值是根因分析，并由受保护的读取和写入操作提供支持：

• diagnose_latency_spike（旗舰根因分析）——当 TTFT/TPOT/e2e 延迟 上升时，它会关联队列深度（运行中与等待中）、KV 缓存 压力／抢占和前缀缓存局部性，给出排序后的原因 以及具体的调整项（增加副本、提高 max-num-seqs、修复 路由、扩大 KV 缓存）。每个标记都是一个数字，而非黑盒结论。
• diagnose_low_utilization——反向诊断：GPU 闲置、副本过度 配置，或路由导致缓存预热的副本无法发挥作用 → 应缩减什么。
• Prometheus 原生——直接读取 vLLM 的 /metrics 端点；无需部署 Prometheus/Grafana。
• 治理级别——这是这一细分领域中首个治理级别的项目： 审计 + 预算 + 风险等级审批 + 撤销令牌 + 提示词注入清理； 对脆弱的生产操作（缩容、缩至零、排空、重新部署、热切换）实施试运行 + 双重确认，这些操作被社区报告为危险操作。
• 笔记本电脑自测——约 80% 的工具可免费自测：在单个 GPU 上运行 vLLM，或使用 CPU 模拟 + 在一个本地容器中运行 Ray（ray start --head）。

此工具的决策范围与非决策范围

它能准确、高效地执行推理集群操作——读取和写入——并记录每一次操作。它不会决定是否允许执行写入。这由 Agent 自行判断，或由你连接的环境授权：限制网络路径，使其只能访问读取／指标端点；或者运行不带作业提交 API 的 Ray 面板。这样，写入就会在服务器端失败——因为服务器才是真正掌握权限的一方。

因此，无需配置只读开关、策略文件或审批关卡。此工具唯一能保证的是，所有操作都不会悄无声息：无论通过 MCP 还是 CLI 发起，每次调用都会在 ~/.inference-aiops/audit.db 中生成一条审计记录；对于破坏性写入，还会捕获操作前的状态，并在存在逆操作时记录该操作。

每个工具都会声明一个 risk_level，并通过测试确保它与 [READ]／[WRITE] 文档标签一致；同时，该值会作为描述性等级写入审计记录，因此审查者可以一眼看出某条记录对应的是高风险缩容至零操作。它只是一个标签，不是关卡。

使用较小型／本地模型？请参阅 agent-guardrails.md——其中列出了此工具为你强制执行的护栏（这样你就不必在提示词预算中重复说明），并为剩余事项提供了一份可直接使用的系统提示词。

功能矩阵（39 个 MCP 工具）

分组	工具	数量	读／写（风险）
指标与根因分析（vLLM）	request_metrics、queue_depth、kv_cache_stats、diagnose_latency_spike、diagnose_low_utilization	5	读取
引擎无关（vLLM／SGLang／TGI）	engine_health、engine_inventory、engine_request_metrics、engine_queue_depth、diagnose_engine_latency	5	读取
Ray Serve（读取）	serve_deployment_list、deployment_status、replica_list、autoscale_config_get	4	读取
Ray Serve（写入）	scale_replicas_up、scale_replicas_down、scale_to_zero、autoscale_config_update、drain_replica	5	写入（中／高）
模型／vLLM	model_list、model_info、model_is_sleeping、lora_load、lora_unload	5	读取 + 写入（中）
休眠模式／vLLM（需要 VLLM_SERVER_DEV_MODE=1）	model_sleep、model_wake	2	写入（高／中）
Ray 集群／作业／GPU	ray_cluster_resources、ray_dashboard_status、ray_job_list、gpu_utilization、ray_job_cancel、replica_restart	6	读取 + 写入（中／高）
部署生命周期	model_deploy、model_undeploy、deployment_redeploy、routing_policy_update	4	写入（中／高）
成本	cost_per_token	1	读取

引擎无关分组适用于任何受支持的引擎（包括 vLLM）；对于 SGLang/TGI 目标或需要统一查看混合机群的情况，请使用此分组。Ray Serve／集群／部署写入分组仅适用于 vLLM（Ray 控制平面）——面对 SGLang/TGI 目标时，它们会说明原因并拒绝操作。

23 个读取工具，16 个写入工具。 高风险写入（scale_replicas_down、 scale_to_zero、drain_replica、lora_unload、model_sleep、 replica_restart、model_undeploy、deployment_redeploy）均支持 dry_run + 二次确认；可逆写入会记录撤销描述符。

休眠模式需要开发模式服务器。 只有在启动时设置 VLLM_SERVER_DEV_MODE=1，vLLM 才会注册 /sleep、 /wake_up 和 /is_sleeping。只有在这种情况下，这三个工具才可用。对于任何其他服务器，这三个工具都会说明路由不存在及其原因，而不是含糊地报错。 休眠模式会暂停同一个模型，不会切换基础模型—— 如需提供不同的基础模型，必须使用不同的 --model 重启 vLLM。

安装

uv tool install inference-aiops          # or: pipx install inference-aiops

快速开始

作为 Claude Code 插件

安装一次，即可让 Agent 同时获得技能和 MCP 服务：

/plugin marketplace add AIops-tools/marketplace
/plugin install inference-aiops@aiops-tools

MCP 服务通过 uv 获取，并固定为此插件声明的软件包版本，因此可以追溯每条审计记录对应的写入代码。凭据仍通过 inference-aiops init 配置——见下文。

作为 OpenClaw 插件

同一套插件也发布在 ClawHub 上，安装一次即可同时获得技能和 MCP 服务：

openclaw plugins install clawhub:@zw008/inference-aiops
openclaw skills info inference-aiops          # expect: Visible to model: yes

之后请重启 OpenClaw 网关，以便加载插件。MCP 服务通过 uv 获取，并固定为此确切版本，因此 uvx 必须位于 PATH 中——没有它，技能仍会安装，但会报告 Visible to model: no。凭据的配置方式如下所示。

作为 CLI 或独立 MCP 服务

inference-aiops init                     # wizard: engine (vllm/sglang/tgi) + host + port + scheme
inference-aiops doctor                   # vLLM: probes Ray + vLLM; SGLang/TGI: engine health + inventory
inference-aiops overview                 # deployments + total replicas + queue backpressure
inference-aiops metrics diagnose         # why is inference slow? ranked RCA + the knob to turn
inference-aiops serve list               # Ray Serve deployments + replica counts

作为 MCP 服务（stdio）运行，以使用完整的 39 个工具：

export INFERENCE_AIOPS_MASTER_PASSWORD=...   # only if a bearer token is stored
inference-aiops mcp

密码之后会存在哪里：导出的变量可被此 shell 启动的所有进程读取，也会被记录在 shell 历史记录中。在共享主机或长期运行的主机上，建议使用交互式提示，或在需要该密码的单条命令运行期间通过密钥管理器注入密码。

CLI 提供一组便捷的子集命令（init、overview、serve …、metrics …、secret …、doctor、mcp）；完整的 39 个工具通过 MCP 服务提供。

治理

每个 MCP 工具都会经过内置的 @governed_tool 工具链。它不会决定是否允许写入——请参阅上文的 此工具决定什么，以及不决定什么——但会记录每次调用：

• 审计——将每次调用（参数、结果、状态、耗时、风险级别，以及任何审批者／理由说明）记录到 ~/.inference-aiops/audit.db（可通过 INFERENCE_AIOPS_HOME 更改位置）。
• 预算／失控防护——这是一道安全后备措施，而非授权机制：令牌和调用预算会在紧密的轮询／重试循环中触发断路器。
• 风险级别——每条审计记录都带有根据工具的 risk_level 得出的描述性级别；它只是标签，不是门禁。INFERENCE_AUDIT_APPROVED_BY / INFERENCE_AUDIT_RATIONALE 是可选说明，设置后会被记录，但从不强制要求。
• 撤销记录——可逆写入（扩缩容、自动扩缩配置、路由、热切换、LoRA 加载）会记录反向操作描述。

支持范围与限制

测试套件通过模拟的 vLLM /metrics、vLLM OpenAI API 和 Ray 仪表板响应来验证行为。在笔记本电脑上，约 80% 的工具自测可通过——使用单 GPU 上的 vLLM，或 CPU 模拟环境，以及本地单节点 Ray 主节点。目前尚未在实时生产集群上运行；实时验证清单请参阅 docs/VERIFICATION.md。

尚未在真实硬件／拓扑上验证：

• 多 GPU 张量并行／流水线并行部署；
• 真实 GPU 温度／降频遥测（利用率数据尽力取自 Ray 仪表板的 /api/nodes）；
• 多节点排空和节点重启编排。

最快的实时检查方式是运行 inference-aiops doctor；完整清单请参阅 docs/VERIFICATION.md。

缺少所需功能？

这是 AIops-tools 系列中面向 GPU 推理的成员（包含审计、预算、撤销和风险级别的受治理 AI 运维工具）。如果你需要的 vLLM 或 Ray 功能尚未提供，或者你的技术栈使用了这些工具尚不支持的方言，请提交 issue 或 PR。欢迎贡献。