12 KiB
Fuser Lab 参考调研:PLoop 的 UI 与 Python 架构边界
核查日期:2026-08-31。范围是对本机 ~/workspace/project/fuser_lab 源码的静态阅读;没有启动其前后端、没有连接其数据库或消息队列。因此下文明确区分“源码已观察到”与“PLoop 拟采用”。第一轮已决定直接建设平台,具体落地范围以 V1 平台契约 为准。
结论
Fuser Lab 是一个合适的产品信息架构和 Python 分层参考,特别适合 PLoop 后续从本地文件型 P0 演化出可查看 Run 与单条证据的界面。但它不是可以直接引入的依赖,也不是 PLoop 的目标架构:
Fuser UI 的产品路径 → 借鉴并用 React 重构
Fuser Python 的职责分层 → 借鉴,但 API 直接调用 application service
Fuser 的 gRPC/proto/stub → PLoop 当前明确不采用
Fuser Kafka/ClickHouse/RBAC → PLoop 当前明确不采用
PLoop P0 的 CLI/manifest → 保持不变,先作为未来服务化的事实来源
1. 已观察到的 Fuser Lab 结构
1.1 前端:以评测工作流组织界面
源码入口是 frontend/:Vue 3 + TypeScript + Vite + Pinia + Element Plus,而不是 React。评测路由位于 frontend/src/router/routes/evaluation.ts,形成三层对象:
评测
├─ 评测集 Dataset
│ └─ 详情:版本切换、条目、导入/导出、单条历史
├─ 评估器 Evaluator
│ └─ 详情:版本、Judge 配置、Prompt 版本/发布
└─ 实验 Experiment
└─ 详情:绑定的评估器、Run 列表、进度刷新、重新评估
└─ Run 条目:输入 / 输出 / reference、执行状态、评分、评估明细 drawer
这不是只展示一个最终分数:在 experiment/run-items.vue 中,每个条目显示执行状态、评估状态、最终分和加权分、输出预览、执行错误;再通过侧边 drawer 展示各评估器的记录、原因和 judge 请求/响应。这个“从总览逐层下钻到可解释原始记录”的信息结构与 PLoop 的 Trace 目标高度一致。
目录组织上还观察到另一条可借鉴规则:pages/observe/trace/ 自己拥有 apis/index.ts、apis/type.ts、detail components 和页面状态;pages/context/dataset/ 自己拥有 apis/、components/ 与页面代码。全局层则保留 http/axios.ts、common/utils/、common/components/、layouts 等真正通用的能力。PLoop 不复制其 Vue 文件,但采用同一条“页面专属代码就近放,跨页能力再提升”的作用域原则,详见 V1 前端架构。
1.2 UI 语言与可复用交互模式
源码中的 layouts/、ListPage 和 _common.scss 已体现一套统一后台界面语言:
| Fuser 已观察到的模式 | 源码证据 | PLoop 参考方式 |
|---|---|---|
| 左侧固定导航 + 顶部面包屑/标签页 + 内容区 | layouts/modes/LeftMode.vue、Sidebar、NavigationBar |
PLoop 未来管理台采用同类空间划分;菜单按 Dataset、目标 RAG、Run、Artifacts 组织。 |
| 轻灰页面底色、白色卡片、8px 圆角、12px 内容边距 | _common.scss |
借鉴视觉节奏,不复制 SCSS 或 Element Plus token。 |
蓝紫主色 #5b5fc7、浅色 active state、状态 Tag |
variables.css、StatusBadge |
可作为早期视觉参考;React 实现用自身 token,不承诺完全像素复刻。 |
| 列表页 = 标题 + 即时搜索 + 刷新 + 列管理 + 创建动作 + 分页表格 | ListPage、DebouncedSearch、ColumnManagerPopover |
PLoop 先做只读 Run 列表;列管理、创建弹窗在真实需要出现时引入。 |
| 详情页 = 返回、标题/ID copy、描述卡、版本/Run 表、刷新进度 | DetailPageHeader、experiment/detail |
PLoop 重点借鉴:Run 状态、耗时、artifact hash、失败数和可重评入口必须同屏可见。 |
| 单条抽屉下钻 | experiment/run-items.vue |
PLoop drawer 应展示 request、Raw Result、Canonical Trace、gold(仅授权角色)、评分明细和 artifact 链接。 |
Fuser 当前 sidebar 会从路由与权限决定可见菜单,列表页还可按权限显示创建/删除操作。PLoop 初期不需要抄 RBAC;但应保留“读 Run”和“看到私有 gold”是不同权限的概念,防止产品页面反过来把金标泄漏给被测系统或普通使用者。
1.3 后端:评测对象与运行状态机
源码入口为 backend/,核心技术是 FastAPI、Pydantic、SQLModel、Alembic;完整部署还包含 gRPC、Kafka、Redis、PostgreSQL/pgvector 与 ClickHouse。实际评测域代码位于 module/lab/:
HTTP API endpoint
→ gRPC stub # Fuser 特有,PLoop 不采用
→ application app # proto/DO 转换、调用 domain service
→ domain service # 规则、快照、状态推进、计算
→ repository / infra model # 持久化
→ worker(Kafka) # 单条 execute / evaluate
以 Experiment 为例,Fuser 的 ExperimentService.start_experiment_run() 会读取评测集的当前版本,创建 Run 和每个 item 的执行记录,再发布逐条执行任务。完成执行后,通过 barrier 将 Run 从 executing 推进到 evaluating;全部评估结束才推进到 done。它还支持从已有输出发起 re_evaluate,不再执行目标应用。
这一机制中值得借鉴的是快照、阶段与重评语义,而不是 Kafka 或 gRPC 本身。
2. Fuser 概念到 PLoop 概念的映射
| Fuser | PLoop 对应物 | 采用方式 | 关键差异 |
|---|---|---|---|
| Evalset + EvalsetVersion + item | Dataset snapshot:英文/中文 MultiHop-RAG、私有 gold、corpus、translation manifest | 采用版本不可变、运行绑定具体版本 | PLoop Dataset 必须把 request 与私有 gold 物理/逻辑隔离。 |
| Evaluator + EvaluatorVersion | 官方 evaluator、PLoop evaluator、答案规范化器、可选 judge 配置 | 采用评分器版本与配置冻结 | P0 不用 LLM judge 取代证据评分;一个 Run 可有多维结果,不能默认汇成单一加权分。 |
| Experiment + binding | Evaluation definition:被测 RAG 配置 + dataset variant + retrieval budget + evaluator set | 采用明确配置与可读绑定 | PLoop 要保存 SUT 命令/版本和 language/scope,不绑定 Fuser 的 app_id。 |
| ExptRunLog | Run manifest / 将来的 Run record | 采用 phase、状态、计数、开始结束时间、parent run | P0 已用文件 manifest;平台化时应引用该 manifest,不能创造第二套不一致事实。 |
| ExptItemResult | Case execution / canonical trace 的索引 | 采用 per-case 状态、错误、重试、结果入口 | 原始 Raw Result 与大 Trace 应保留为 artifact 文件/对象引用,避免只将摘要 JSON 塞进数据库。 |
| EvaluatorRecord | 每个指标/评分器的 evidence | 采用每条评分解释、版本、错误与产物链接 | 证据映射/引用判断须保留结构化证据,而非只有一个 judge score。 |
| Worker task | 未来 async job | 只采用稳定 run_id + case_id + phase 的幂等任务语义 |
P0 不引入 Kafka;先以本地 batch、状态文件和超时产物验证。 |
3. PLoop 未来服务化的目标分层
第一轮直接采用下面的 Python 分层;这是平台实现目标,但不会照搬 Fuser 的 gRPC 或微服务拆分。
React + TypeScript 管理台
↓ HTTP/JSON
FastAPI router + Pydantic schema
↓ 直接 Python 调用(无 gRPC)
Application service
↓
Domain service
├─ Dataset / translation lineage
├─ Evaluation definition
├─ Run state machine: queued → executing → normalizing → evaluating → done/failed
└─ Re-evaluate:只读已有 canonical trace
↓
Repository / artifact store adapter
├─ metadata:Dataset、SUT、Run、Case 状态、指标索引
└─ immutable artifacts:request、raw result、trace、score、manifest
API router 只完成认证(若有)、输入验证、调用 application service 与返回 schema;不得在 route 内直接拼命令、做评分或直接访问数据库。Application service 负责事务边界与 DTO 转换;PLoop 的充血 aggregate/domain policy 负责不可变快照、状态机、重试/重评规则;repository/infra 负责文件、数据库或对象存储。该 DDD 细化比 Fuser 的 service-centric 参考更严格,见 DDD 与充血领域模型设计。
这比 Fuser 少了一层 RPC conversion:没有 proto、pb2、stub 或 module 间 gRPC。若以后拆服务,先证明进程边界和吞吐需求;再把 application service 的稳定接口提取成 RPC,而不是现在为可能的拆分预埋 proto。
4. React 重构的 UI 范围
不移植 .vue、Pinia store、Element Plus 或 Fuser 的通用组件。React 实现应该根据 PLoop 的实体和 Trace 契约重新设计下面四个工作区:
| 工作区 | 首要内容 | Fuser 启发 | PLoop 特有内容 |
|---|---|---|---|
| 数据集 | 英文/中文变体、SHA、语言、corpus 规模、翻译审查/例外 | Dataset list/detail/version switch | lineage_case_id、翻译模型/prompt hash、gold 访问边界。 |
| 被测 RAG | 命令/SDK adapter、版本、索引配置、scope、top-k | Fuser Experiment 中的 app 选择 | PLoop 的 SUT 是外部命令或 adapter,不是假定的平台内应用。 |
| Run | 状态、阶段进度、成功/失败、耗时、成本、关联数据/配置/评分器版本 | Experiment detail + run table + refresh | execute → normalize → evaluate 三段与 artifact manifest。 |
| Case 明细 | 问题、retrievals、citations、answer、指标、错误与 artifact 链接 | Run items + evaluator drawer | 分栏显示 Raw Result 与 Canonical Trace;gold 默认遮蔽并与请求严格隔离。 |
第一轮实现受控的 Run 创建与只读 artifact 下钻;Dataset 在线编辑、通用评估器编辑和任意数据上传仍延后。这样 UI 不会反向决定还没有稳定的评测语义。
5. 明确不照搬的点
- 不引入 gRPC:Fuser 的 API → gRPC stub → application 层来自微服务边界;PLoop 现阶段没有这个边界,直接调用更简单、可调试。
- 不引入 Kafka worker:Fuser 已有按 item 分发、Kafka 消费、barrier 推进的实现;PLoop 首先依赖已有 Batch / manifest / Raw Result 语义,队列的选择另行决策。
- 不默认总分取平均:Fuser Run 会保存
final_score;PLoop 必须继续按 dataset × language × slice × metric 报告。英文/中文、检索/回答/引用均不可简单平均。 - 不让 reference payload 泄漏:Fuser 的运行条目包含
input_payload、reference_payload、output_payload以支持评测。PLoop 的 gold evidence/answer 在任何 target RAG 可读路径中都必须不可见;UI 也要分权显示。 - 不复制全栈基础设施:第一轮有意采用 PostgreSQL 与 Redis 来支撑持久 Run 和异步 worker;但不复制 Fuser 的 Kafka、ClickHouse、gRPC、RBAC、微服务部署或云基础设施。采用的只是满足本轮状态机与 artifact 语义的最小集合。
6. 核查来源
- Fuser 根说明与技术入口:
README.md、CLAUDE.md。 - 前端路由、布局与评测页面:
frontend/src/router/routes/evaluation.ts、frontend/src/layouts、frontend/src/pages/evaluation。 - Python API / 自动路由:
backend/api/main.py、backend/api/endpoints/register.py。 - 评测服务、Run worker 与数据模型:
backend/module/lab、backend/proto/lab。