前言¶

在 DSH 里做模型相关能力时，常见做法是本机直接 vllm serve 或手写脚本起容器。演示够用，但一旦要幂等部署、失败降级、回滚清理和可核对审计，这些零散步骤很难和智能体工具链对齐。维护者 xiciyang 的 inference-serving（分类：模型推理）面向「把模型 checkpoint 部署成可访问的推理端点」，并把失败当作一等公民：探测环境、选后端、健康检查、注册、自动降级与回滚，全程写入哈希链审计日志。包内零运行时依赖（仅 Node 内建模块），README 写明测试套件含 154 项用例。

这是什么¶

inference-serving 是 DSH 插件与独立 CLI（npm 包 @xiciyang/inference-serving，当前资料版本 0.1.7，MIT）。它不是托管云端点，也不是 vLLM 的替代品；文档明确说明其定位是围绕 vLLM 等后端的运维层（降级、回滚、审计、对账），不适合「只要一条 vllm serve 做 demo」的场景。

主流程可概括为：

输入 → 环境探测 → 后端选择 →（迁移适配）→ 部署 → 健康检查三关
     → 注册端点 → 写共享状态
     → 失败自动降级（内存配额 → 并行度 → 精度 → 端口）→ 仍失败则回滚中止
     → 全程哈希链审计

• 一条命令：inference-serving deploy /path/to/models/<model>
• 幂等：同一模型与同一配置重复调用返回同一端点
• 可回退：rollback 回到上一个已验证版本
• 可清理：teardown 后验证无残留进程、显存与端口
• 可审计：调用写入 ~/.ai-infra/logs/audit/，哈希链可校验删改

GitHub 仓库：https://github.com/xiciyang/inference-serving；社区目录页：https://www.skillhub.cn/plugins/xiciyang/inference-serving。

核心功能¶

命令与工具面¶

CLI 与 DSH 原生工具注册共用 src/tools.mjs 规格与 src/api.mjs 实现。常用命令如下。

退出码：0 成功，1 业务失败，2 用法错误，3 需要确认。

健康检查三关¶

仅 HTTP 200 不足以认定模型可用；三关全部通过才注册端点。

失败时的降级链¶

次序为：内存配额 → 并行度 → 精度 → 端口 → 中止。精度降级为有损，部署报告会标注 degrade.lossy = true；端口冲突单独换端口。文档区分 E_INSUFFICIENT_MEMORY（下调配额）与 E_MEMORY_CONFIG_INFEASIBLE（应降并发、上下文或精度）。不可降级的失败（无 GPU、无 nvidia runtime、模型无法解析、License 待确认等）会立即中止。

MCP 与 DSH 分工¶

包内提供 MCP server（stdio 或 streamable-http），对外暴露与 DSH 原生工具相同的 5 个核心工具及若干运维工具。DSH 在 MCP 上为 client，插件侧通过 ctx.tools.register 注册原生工具；MCP 主要服务第三方客户端，两条通道不行为分叉。

node mcp/server.mjs
node mcp/server.mjs --http --port 8790

权限、沙箱与状态¶

manifest.yaml 以能力白名单约束 deploy、status、rollback 等操作及资源访问。部署路径对应风险档 R2，要求容器级沙箱；沙箱不可用会拒绝（E_SANDBOX_UNAVAILABLE），不静默去掉沙箱。仅操作带 inference-serving.managed=true 标签的自建载体；审计目录只追加，模块内无删除或改写审计的 API。

共享状态默认在 ~/.ai-infra/（注册表、确认授权、指标、审计与策略配置等），不写在 npm 包目录内。

安装与启用¶

运行时要求：Node ≥ 20.11，Linux 或 macOS，x64 或 arm64；package.json 中 dsh 引擎为 >=0.2.0 <0.3.0。

全局 CLI：

npm install -g @xiciyang/inference-serving

作为 DSH 插件（bundle，安装后需重启生效）：

dsh plugin --profile <name> add @xiciyang/inference-serving

无 GPU 时仍可跑测试与环境探测：

npm test
inference-serving doctor

真实 deploy 需要 GPU 与确认 token（风险类 R2）；无 GPU 时可阅读 deploy --help 中的计划说明。

典型用法¶

inference-serving doctor
inference-serving deploy /path/to/models/<model>
inference-serving status
inference-serving list
inference-serving teardown <endpoint-id> --confirm <token>

部署成功后会打印端点 URL、耗时、降级步数、自动补全的假设与审计 id。首次涉及写操作可能返回 E_CONFIRMATION_REQUIRED 与 details.confirmToken，需带回 confirm 再执行。

DSH 行内插件配置示例（未知键或类型错误会在加载期失败）：

- insert:
    - id: inference-serving
      name: 'inference-serving'
      inject: [tools]
      config:
        root: '~/.ai-infra'
        portPoolStart: 8100
        portPoolEnd: 8199
        modelRoots: ['/path/to/models']
        maxDegradeSteps: 4
        headless: false

也可用环境变量 DSH_MODEL_ROOTS（冒号分隔）指定模型根目录。策略文件在首次运行后生成于 ~/.ai-infra/config/（如 risk-classification.yaml、network-policy.yaml、headless-policy.yaml）。

适用场景与注意¶

适合：在 DSH 或本机运维流程中，需要把 checkpoint 变成可核对、可回滚、可审计的推理端点；希望在 OOM、端口冲突等失败时按证据自动降级而非反复手工改参数。

不适合：需要全托管云端推理，或仅需临时 vllm serve 的场景。

安全与权限：插件以当前 DSH 进程权限运行；deploy / teardown 等会动 GPU、端口与本地状态。安装前请阅读仓库源码与 MIT 许可证，并理解确认 token、风险档与网络白名单策略。无 TTY 或 CI 下默认 headless，未获确认的高风险操作会中止（E_HEADLESS_NEEDS_CONFIRMATION）。

社区插件目录站点 skillhub.cn 与 DeepSeek、幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本包是社区维护的模型推理类插件之一。

结尾¶

inference-serving 把「探测 → 部署 → 三关健康检查 → 注册」与「降级 → 回滚 → 清理 → 哈希链审计」收进同一套 CLI 与 DSH 工具，并强调注册表与实机状态的一致性核对。进一步了解可从目录页与 GitHub README 入手。

• 目录页：https://www.skillhub.cn/plugins/xiciyang/inference-serving
• GitHub：https://github.com/xiciyang/inference-serving