SuperMew 模型控制面完整指南:Answer、Fast、Grader、Evaluator 四角色分工与 Model Snapshot 冻结机制

原创2026-10-23 20:25:551,842 阅读

SuperMew 模型控制面完整指南:Answer、Fast、Grader、Evaluator 四角色分工与 Model Snapshot 冻结机制

SuperMew 是一个基于 LangChain & LangGraph 构建、以知识库优先的 Agentic RAG 平台,其模型控制面将模型配置与运行时 Secret 彻底分离:管理员可为 Answer、Fast、Grader、Evaluator 四个角色分配模型,每个 Run 创建时冻结一份不可变的 Model Snapshot,保证对话、HITL 恢复与重试全程始终使用同一组模型。

模型控制面在 SuperMew 中的位置

SuperMew 总体架构图(包含模型控制面、持久 Run 引擎、RAG 流水线与 Evaluation Worker)

从总体架构看,模型控制面是 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

关键设计点:

  1. 全链路只读快照:Agent、RAG、Memory、并行子问题、HITL resume 与 Tool 调用,都从 Request Context 读取同一份快照(backend/runs/request_context.py),任何模块都不再碰环境变量。
  2. 幂等性随快照而变:幂等请求哈希包含 catalog hash——管理员一旦变更模型分配,相同问题会创建"新" Run,而不是污染旧请求。
  3. 只影响未来:Assignment 变化不会改变正在运行或等待 HITL 的任务;重试、恢复、worker 重领后仍使用原快照。
  4. 版本号是锚点:快照保存 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"——把快照冻结的语义做成了用户可见的说明。

SuperMew 前端模型控制面与知识库空状态插画

前端实现见 frontend/src/components/Models/ModelCenter.vue。

相关文件速查

总结

SuperMew 的模型控制面把两件事做到了极致:角色分工——Answer、Fast、Grader、Evaluator 各司其职,能力与温度预先约束;快照冻结——Run 与 Evaluation Job 的整个生命周期(含 HITL 恢复、重试、并行子问题)都被锁定在同一份 Model Snapshot 上。对运维者而言,这意味着换模型不需要重启服务,而"当时到底用的哪个模型"永远可追溯、可审计。

登录后查看全文
SuperMew