SuperMew 模型控制面完整指南:Answer、Fast、Grader、Evaluator 四角色分工与 Model Snapshot 冻结机制
SuperMew 模型控制面完整指南:Answer、Fast、Grader、Evaluator 四角色分工与 Model Snapshot 冻结机制
SuperMew 是一个基于 LangChain & LangGraph 构建、以知识库优先的 Agentic RAG 平台,其模型控制面将模型配置与运行时 Secret 彻底分离:管理员可为 Answer、Fast、Grader、Evaluator 四个角色分配模型,每个 Run 创建时冻结一份不可变的 Model Snapshot,保证对话、HITL 恢复与重试全程始终使用同一组模型。
模型控制面在 SuperMew 中的位置
从总体架构看,模型控制面是 FastAPI API + PostgreSQL 的核心平面之一:管理员在模型中心页面维护 Model Profile 与角色 Assignment;Run 引擎在创建 Run 的同一事务中预留并冻结 Model Snapshot;RAG 流水线、Agent 记忆、评估 Worker 都从该快照读取模型,不再从环境变量或全局单例动态选择。完整架构决策见 ADR 文档:docs/adr/0024-model-control-and-rag-evaluation-runtime.md。
四角色分工:为什么"一个大模型"不够用
一次 RAG 流水线里藏着多种性质完全不同的"模型工作":有的要快速、结构化的判断,有的要稳定低温的评分,有的要流式生成最终答案。SuperMew 将其拆分为四个角色,并在 backend/model_control/contracts.py 中硬编码了每个角色的能力要求:
| 角色 | 必备能力 | 默认温度 | 流水线中的典型职责 |
|---|---|---|---|
| Answer | Stream 流式输出 | 0.3 | Agent 对话与 RAG Synthesis 主模型,流式生成回答 |
| Fast | Structured Output | 0.2 | 复杂度规划、2~4 个子问题拆解、Step-back/HyDE 单选重写、记忆摘要 |
| Grader | Structured Output | 0.0 | 对证据做一次性结构化判断:相关性、可回答性、歧义与 route |
| Evaluator | Structured Output | 0.0 | RAG 自动评估 Judge:correctness、groundedness、relevance、completeness 等维度 |
📌 以 RAG 流水线为例:证据评判节点由 Grader 模型对召回证据做一次结构化判断并决定下一步 route;证据不足时,Fast 模型只在 Step-back 与 HyDE 中单选一种,且只执行一次重写检索与复评。这种分工让你可以给 Answer 配大模型、给 Fast/Grader/Evaluator 配小而快的模型,兼顾体验与成本。Grader 的调用逻辑见 backend/rag/pipeline.py。
模型中心如何分配模型:Profile、Assignment 与 fail-closed
控制面管理两类对象:
- Model Profile:持久化的模型配置——模型名、Base URL、timeout、Stream / Structured Output 能力标记、启用状态,以及每次修改单调递增的 version。注意其中不存任何 Secret:
ARK_API_KEY只由服务端读取,永不进入数据库、HTTP 响应、Snapshot 或前端。 - Assignment:角色 → Profile 的映射。分配时会校验该角色的能力要求(如 Answer 必须支持 Stream),已分配的 Profile 不可被删除或停用。
环境变量(MODEL、FAST_MODEL 等)只在首次启动且角色尚未分配时用于种子化控制面默认值,之后不再是运行时事实来源,见 backend/model_control/service.py。
⚠️ fail-closed 原则:当必需角色缺失、Profile 已停用、能力不满足或 API Key 未配置时,新 Run 直接返回 503 MODEL_UNAVAILABLE,绝不会静默回退到"另一个环境里碰巧存在的模型"。
所有接口仅对 admin 开放:/v1/models 负责 Profile CRUD,PUT /v1/models/assignments/{role} 负责角色分配,路由实现见 backend/api/routes/models.py。
Model Snapshot 冻结机制:从头到尾同一组模型
这是模型控制面最核心的设计:每个新 Run 在预留事务中冻结一份完整的、不可变的 Model Snapshot,并落库到 runs 表——
model_catalog_hash:角色 → 模型映射的 SHA-256 摘要(64 位、非空、带长度校验约束)model_snapshot_json:快照本体,包含每个角色的profile_id与profile_version
关键设计点:
- 全链路只读快照:Agent、RAG、Memory、并行子问题、HITL resume 与 Tool 调用,都从 Request Context 读取同一份快照(backend/runs/request_context.py),任何模块都不再碰环境变量。
- 幂等性随快照而变:幂等请求哈希包含 catalog hash——管理员一旦变更模型分配,相同问题会创建"新" Run,而不是污染旧请求。
- 只影响未来:Assignment 变化不会改变正在运行或等待 HITL 的任务;重试、恢复、worker 重领后仍使用原快照。
- 版本号是锚点:快照保存 profile identity + version,而不是可变显示名,模型配置升级后依然可审计。
Schema 演进见迁移 migrations/versions/0015_run_model_snapshot.py,Run 创建时的快照冻结见 backend/runs/service.py。
💡 在 RAG 自动评估场景中,Evaluation Job 创建时同样冻结四角色 Model Snapshot:Worker 逐 Case 用 Answer 角色生成回答,再由 Evaluator 角色输出结构化 Judge。baseline 比较与 Gate 判断都基于同一组冻结模型完成,评估结果才可复现、可比较。
前端模型中心:一页看懂控制面状态
管理员可以在模型中心页面完成"新建 Profile → 能力校验 → 角色分配",页面直接展示当前 Catalog Hash、已分配角色数与 API Key 配置状态,并明确标注:"目录发生变化后仅影响后续新 Run"——把快照冻结的语义做成了用户可见的说明。
前端实现见 frontend/src/components/Models/ModelCenter.vue。
相关文件速查
- 角色定义与能力要求:backend/model_control/contracts.py
- Profile 生命周期、Assignment 与快照构建:backend/model_control/service.py
- Run 预留与快照冻结:backend/runs/service.py
- 模型注册表与运行时能力校验:backend/agent/models.py
- Grader 证据评判节点:backend/rag/pipeline.py
- 模型中心前端页面:frontend/src/components/Models/ModelCenter.vue
- 架构决策 ADR-0024:docs/adr/0024-model-control-and-rag-evaluation-runtime.md
总结
SuperMew 的模型控制面把两件事做到了极致:角色分工——Answer、Fast、Grader、Evaluator 各司其职,能力与温度预先约束;快照冻结——Run 与 Evaluation Job 的整个生命周期(含 HITL 恢复、重试、并行子问题)都被锁定在同一份 Model Snapshot 上。对运维者而言,这意味着换模型不需要重启服务,而"当时到底用的哪个模型"永远可追溯、可审计。

