ploop/docs/reference/fuser-lab-reference.md
2026-08-31 15:27:34 +08:00

12 KiB
Raw Permalink Blame History

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. 明确不照搬的点

  1. 不引入 gRPC:Fuser 的 API → gRPC stub → application 层来自微服务边界;PLoop 现阶段没有这个边界,直接调用更简单、可调试。
  2. 不引入 Kafka worker:Fuser 已有按 item 分发、Kafka 消费、barrier 推进的实现;PLoop 首先依赖已有 Batch / manifest / Raw Result 语义,队列的选择另行决策。
  3. 不默认总分取平均:Fuser Run 会保存 final_score;PLoop 必须继续按 dataset × language × slice × metric 报告。英文/中文、检索/回答/引用均不可简单平均。
  4. 不让 reference payload 泄漏:Fuser 的运行条目包含 input_payload、reference_payload、output_payload 以支持评测。PLoop 的 gold evidence/answer 在任何 target RAG 可读路径中都必须不可见;UI 也要分权显示。
  5. 不复制全栈基础设施:第一轮有意采用 PostgreSQL 与 Redis 来支撑持久 Run 和异步 worker;但不复制 Fuser 的 Kafka、ClickHouse、gRPC、RBAC、微服务部署或云基础设施。采用的只是满足本轮状态机与 artifact 语义的最小集合。

6. 核查来源