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

135 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Fuser Lab 参考调研:PLoop 的 UI 与 Python 架构边界
核查日期:2026-08-31。范围是对本机 [`~/workspace/project/fuser_lab`](/Users/pptg/workspace/project/fuser_lab/README.md) 源码的静态阅读;没有启动其前后端、没有连接其数据库或消息队列。因此下文明确区分“源码已观察到”与“PLoop 拟采用”。第一轮已决定直接建设平台,具体落地范围以 [V1 平台契约](../design/v1-platform-contract.md) 为准。
## 结论
Fuser Lab 是一个合适的**产品信息架构和 Python 分层参考**,特别适合 PLoop 后续从本地文件型 P0 演化出可查看 Run 与单条证据的界面。但它不是可以直接引入的依赖,也不是 PLoop 的目标架构:
```text
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`,形成三层对象:
```text
评测
├─ 评测集 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 前端架构](../design/frontend-architecture.md)。
### 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/`:
```text
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 或微服务拆分。
```text
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 与充血领域模型设计](../design/ddd-rich-domain-model.md)。
这比 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. 核查来源
- Fuser 根说明与技术入口:[`README.md`](/Users/pptg/workspace/project/fuser_lab/README.md)、[`CLAUDE.md`](/Users/pptg/workspace/project/fuser_lab/CLAUDE.md)。
- 前端路由、布局与评测页面:[`frontend/src/router/routes/evaluation.ts`](/Users/pptg/workspace/project/fuser_lab/frontend/src/router/routes/evaluation.ts)、[`frontend/src/layouts`](/Users/pptg/workspace/project/fuser_lab/frontend/src/layouts)、[`frontend/src/pages/evaluation`](/Users/pptg/workspace/project/fuser_lab/frontend/src/pages/evaluation)。
- Python API / 自动路由:[`backend/api/main.py`](/Users/pptg/workspace/project/fuser_lab/backend/api/main.py)、[`backend/api/endpoints/register.py`](/Users/pptg/workspace/project/fuser_lab/backend/api/endpoints/register.py)。
- 评测服务、Run worker 与数据模型:[`backend/module/lab`](/Users/pptg/workspace/project/fuser_lab/backend/module/lab)、[`backend/proto/lab`](/Users/pptg/workspace/project/fuser_lab/backend/proto/lab)。