内容
# 小模型防护框架
**用于生产环境智能工作流中运行1B–12B参数模型的防御性防护框架。**
五层架构：路由 → 验证 → 约束 → 熔断 → 上下文管理。以Hermes插件（确定性强制执行）+ MCP服务器（分析工具）的形式提供。
## 问题
小模型（1B–12B）已显著缩小了与前沿模型的质量差距，但**可靠性差距仍然存在**：
| 失败模式 | 影响 | 来源 |
|---|---|---|
| **死循环** —贪婪采样下的重复死亡螺旋 | Qwen3.5-4B：**22.9%循环率** | Antidoom (FTPO) |
| **上下文腐烂** —输入长度而非位置的退化 | 有效窗口 = ~1/3 声明窗口 | Chroma/NVIDIA |
| **格式漂移** —长链上工具调用的脆弱性 | 87% 准确率 vs GPT-4o 的 92% | Qwen3-32B 评估 |
## 架构
```
┌─────────────────────────────────────────┐
│ 入口 / 任务调度 │
└────────────────┬────────────────────────┘
│
┌────────────────▼────────────────────────┐
第一层 │ 任务分类器 │
路由 │ 复杂度分类，路由到模型 │
│ T1 (<4B) → T2 (4-8B) → T3 (9-12B) → │
│ T4 (云) 级联，带有置信度 │
└────────────────┬────────────────────────┘
│
┌────────────────▼────────────────────────┐
第二层 │ 调用前验证 │
防护栏 │ 模式检查，循环检测，预算 │
│ 在执行前阻止坏调用 │
└────────────────┬────────────────────────┘
│
┌────────────────▼────────────────────────┐
第三层 │ 约束解码引擎 │
输出 │ XGrammar token 掩码 (40μs) │
强制执行 │ 保证有效的 JSON/工具调用输出 │
│ （尚未实施） │
└────────────────┬────────────────────────┘
│
┌────────────────▼────────────────────────┐
第四层 │ 熔断器 │
循环 │ 3 状态：关闭 → 打开 → 半打开 │
检测 │ 检测循环，断开电路，升级 │
└────────────────┬────────────────────────┘
│
┌────────────────▼────────────────────────┐
第五层 │ 上下文预算 │
上下文 │ 滑动窗口压缩 │
│ 1/3 有效窗口规则 │
└─────────────────────────────────────────┘
```
## 组件
| 组件 | 功能 | 状态 |
|---|---|---|
| **Hermes 插件** | `pre_tool_calls` 钩子 — 模式验证，循环检测，熔断器，上下文预算，路由感知 | ✅ 第一阶段 |
| **MCP 服务器** | 5 种工具：上下文状态，压缩，任务分类，路由，重置 | ✅ 第二阶段+第三阶段 |
| **任务分类器** | 基于规则的复杂度评分和模型层分配 | ✅ 第三阶段 |
| **上下文路由器** | 层级级联（T1→T2→T3→T4），带有基于失败的升级 | ✅ 第三阶段 |
| **输出强制执行** | 约束解码（XGrammar/Outlines），保证有效输出 | ⏳ 计划中 |
| **输出验证器** | 工具调用正确性的后生成验证 | 📋 计划中 |
## 安装
### 作为 Hermes 插件
```bash
# 将插件复制到 Hermes 插件目录
cp -r hermes-plugin ~/.hermes/profiles/dev/plugins/small-model-harness
# 启用它
hermes plugins enable small-model-harness
```
### 作为 MCP 服务器
添加到 `~/.hermes/config.yaml` 或 `~/.hermes/profiles/dev/config.yaml`：
```yaml
mcp_servers:
small-model-harness:
command: python3
args: ["/path/to/mcp-server/server.py"]
enabled: true
```
## MCP 服务器工具
| 工具 | 描述 |
|---|---|
| `harness_context_status` | 查询会话的上下文预算利用率 |
| `harness_compact` | 紧凑会话上下文（滑动窗口总结） |
| `harness_classify_task` | 分类任务复杂度和建议模型层级 |
| `harness_route` | 将任务路由到具有级联逻辑的模型层级 |
| `harness_reset` | 重置会话的所有防护状态 |
## 层级参考
| 层级 | 模型大小 | 示例模型 | 用例 |
|---|---|---|---|
| T1 | <4B | SmolLM3, phi-4-mini | 简单提取，分类 |
| T2 | 4-8B | Qwen3-8B, Llama 3.2-8B | 单个工具调用，基本路由 |
| T3 | 9-12B | Ornith-1.0-9B, Qwen3-30B-A3B | 多步骤，推理，规划 |
| T4 | 云 | DeepSeek V4, GPT-4o | 复杂链条，安全关键 |
## 开发
```bash
# 设置
uv sync --group dev
# 运行测试
uv run pytest tests/ -v
# 测试 MCP 服务器
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | python3 mcp-server/server.py
```
## 许可证
MIT
