ploop/README.md
2026-08-31 15:27:34 +08:00

6.3 KiB
Raw Blame History

PLoop:知识库评测

PLoop 用于沉淀和实现可复现、可解释的知识库评测。它关注的不只是答案是否“像对的”,还要验证系统检索到了什么、引用是否真实、不同知识边界是否隔离,以及一次结论能否由完整运行证据复核。

当前状态

  • 阶段:第一轮直接交付前后端平台。平台保留 执行 → Trace 标准化 → 评测 的语义与不可变产物,并将其组织成异步 Run、持久化状态和 React 管理台。
  • 首轮数据:冻结的英文 MultiHop-RAG 与中文派生集 MultiHop-RAG-zh;两套语料、索引、运行和报告独立。
  • 首轮后端:FastAPI + Python application/domain/repository 分层,PostgreSQL 保存元数据与状态,Redis 驱动独立 worker;不使用 gRPC / proto / stub。
  • 首轮 UI:React + TypeScript,实现 Dataset、被测 RAG、Run、Case 明细四个工作区;证据与评分可下钻,gold 默认不展示。
  • 待确认:第一个真实被测 RAG 的受控接入方式和运行环境。第一轮只允许平台注册的 adapter/命令模板,不接受网页自由输入的 shell 命令。

Monorepo 边界

backend/       Python 包:P0 执行内核,后续 FastAPI、DDD、worker、迁移和后端测试
frontend/      React + TypeScript 包:后续 Vite 应用、页面和浏览器测试
docs/          设计、计划、基准、参考和操作文档
scripts/       仅由根 Makefile 调用的跨包质量门(M0a 建立)
deploy/        Compose、镜像和反向代理配置(M0a 建立)

根目录只承担 monorepo 编排、文档和跨包配置;不放 Python 的 src/、pyproject.toml、测试目录或 Node 的 package.json。当前 P0 原型已位于 backend/,前端包边界见 frontend/。

设计原则

  1. 先证据,后总分:保留摄取配置、检索候选、重排、送入模型的上下文、回答和引用;总分不能替代证据链。
  2. Case 可复现:语料、金标、索引配置、模型和提示词均须版本化。
  3. 执行与评分解耦:系统运行完成后,可更换或修复评分器并独立 regrade,不必重新执行被测系统。
  4. 同口径比较:比较系统时固定数据、模型、检索预算、评分器和重复次数。
  5. 安全和治理是一等指标:跨知识空间泄漏、删除后仍可检索、冲突事实被静默断言,都不是普通 QA 错误。

参考项目:Fuser Lab 与 Fuser Mate

~/workspace/project/fuser_lab 是 PLoop 本轮平台建设的参考项目,不是运行时依赖,也不复制其代码:

  • 前端 UI:借鉴其“评测集 → 实验 → Run → 单条明细”的信息架构、左侧导航、列表/详情/抽屉下钻与状态展示;PLoop 必须用 React + TypeScript 重新实现,不迁移 Vue、Element Plus 或其组件代码。
  • Python 后端:借鉴 FastAPI、Pydantic、应用层/领域服务/仓储/基础设施的分层,以及实验快照、Run 状态与可重评的思路;首版不使用 gRPC / proto / stub,未来 API 直接调用 Python application service。
  • 平台实现边界:第一轮引入 React、FastAPI、PostgreSQL、Redis worker 和本地 artifact volume;不引入 gRPC、Kafka、ClickHouse、RBAC、多租户或在线自由编辑评测数据。

已核查的实际结构、可复用边界和 PLoop 映射见 Fuser Lab 参考调研。

~/workspace/project/fuser_mate 是 PLoop 的 React 工程实现参考,同样不是运行时依赖,也不复制其代码:

  • 借鉴按业务收拢代码、共享 API client / layout / UI 层、路由懒加载与错误边界、React Query 的服务端状态管理,以及 Vitest + Playwright 的质量门;PLoop 采用“页面优先、按需提升”:页面专属 API/query/组件放在对应 pages/ 子目录,只有真实跨页的 API/工具才进入 shared/,以控制 AI 改动的影响范围。
  • 可参考其 Tailwind + Radix 原子组件与设计 token 的组织方式;具体视觉和组件只围绕 PLoop 的 Dataset、SUT、Run、Case 重新实现,仍以 Fuser Lab 的评测信息架构为产品参考。
  • 不带入聊天、编辑器、Electron、WebSocket runtime、帖子/通知等业务代码;PLoop API 合同也不因其现有的响应 envelope 而被强行绑定。

详细的源码观察、采用边界与第一轮前端映射见 Fuser Mate React 参考调研。

文档导航

下一个人工决策

确定第一个真实 RAG 的受控接入方式(平台注册的 CLI adapter 或 SDK adapter)。它必须接收仅含 request 的 JSONL,返回原始结果 JSONL;gold 永远不进入其工作目录或请求。