YoVinchen
63279cf213
Some checks failed
verify / verify (push) Has been cancelled
Document the runnable Docker workflow, expected one-shot container exits, server-controlled Bailian namespace switch, current earned progress, and the security and evaluation work that still blocks private-data or graduation release claims. Constraint: Current local Bailian credentials are rejected by the configured workspace Rejected: Mark the project complete from synthetic metrics | would overstate provider, OCR, authorization, and blind-evaluation readiness Confidence: high Scope-risk: narrow Directive: Keep progress evidence task-based and distinguish synthetic engineering validation from real geological efficacy Tested: make verify-design; Markdown links; secret scan; diff checks Not-tested: Final thesis review and live provider authorization
446 lines
15 KiB
Markdown
446 lines
15 KiB
Markdown
# 实施计划、代码规范与验收标准
|
||
|
||
| 项目 | 内容 |
|
||
|---|---|
|
||
| 计划周期 | 10–14 周（含 300 题正式标注与盲测） |
|
||
| 开发方式 | 小步可验证、每阶段提交并推送 |
|
||
| 主分支 | `main` |
|
||
| 质量门禁 | 格式、lint、类型、测试、密钥扫描、文档同步 |
|
||
|
||
## 1. 仓库结构规范
|
||
|
||
```text
|
||
RAG/
|
||
├── README.md
|
||
├── SECURITY.md
|
||
├── CONTRIBUTING.md
|
||
├── AGENTS.md
|
||
├── Makefile
|
||
├── compose.yaml # 实现阶段创建
|
||
├── .env.example # 只能有占位符
|
||
├── .githooks/
|
||
├── .gitea/workflows/
|
||
├── backend/
|
||
│ ├── Dockerfile
|
||
│ ├── pyproject.toml
|
||
│ ├── alembic.ini
|
||
│ ├── migrations/
|
||
│ ├── app/
|
||
│ │ ├── main.py
|
||
│ │ ├── api/v1/
|
||
│ │ ├── core/
|
||
│ │ ├── domain/
|
||
│ │ ├── ports/
|
||
│ │ ├── services/
|
||
│ │ ├── adapters/
|
||
│ │ │ ├── bailian/
|
||
│ │ │ └── parsers/
|
||
│ │ ├── persistence/
|
||
│ │ ├── workers/
|
||
│ │ ├── tools/
|
||
│ │ │ ├── provider_smoke.py
|
||
│ │ │ ├── seed_demo.py
|
||
│ │ │ ├── verify_index.py
|
||
│ │ │ └── run_evaluation.py
|
||
│ │ └── prompts/
|
||
│ └── tests/
|
||
│ ├── unit/
|
||
│ ├── integration/
|
||
│ └── contract/
|
||
├── frontend/
|
||
│ ├── Dockerfile
|
||
│ ├── nginx.conf
|
||
│ ├── package.json
|
||
│ ├── src/
|
||
│ │ ├── api/
|
||
│ │ ├── components/
|
||
│ │ ├── features/
|
||
│ │ ├── hooks/
|
||
│ │ ├── pages/
|
||
│ │ ├── routes/
|
||
│ │ ├── styles/
|
||
│ │ └── types/
|
||
│ └── tests/
|
||
│ ├── unit/
|
||
│ └── e2e/
|
||
├── docs/
|
||
│ ├── 00-overall-design.md
|
||
│ ├── 01-data-and-evaluation.md
|
||
│ ├── 02-deployment-and-security.md
|
||
│ ├── 03-implementation-plan.md
|
||
│ └── adr/
|
||
├── data/
|
||
│ └── README.md
|
||
├── ops/
|
||
│ └── postgres/init/ # 数据库扩展与分权角色初始化
|
||
└── scripts/
|
||
├── check-secrets.sh
|
||
└── check_markdown_links.py
|
||
```
|
||
|
||
空目录只作为当前结构承诺；开始实现某模块时删除对应 `.gitkeep` 并增加真实代码和测试。
|
||
|
||
## 2. 后端代码边界
|
||
|
||
### 2.1 依赖方向
|
||
|
||
```text
|
||
api / workers
|
||
-> services
|
||
-> domain
|
||
-> ports (protocols)
|
||
adapters / persistence
|
||
-> implement ports
|
||
```
|
||
|
||
规则：
|
||
|
||
- `domain/` 不 import FastAPI、SQLAlchemy、OpenAI SDK 或具体解析库；
|
||
- `ports/` 定义外部模型、解析、存储和仓储协议；
|
||
- `services/` 编排用例，通过接口调用外部能力；
|
||
- `adapters/` 封装百炼、PDF/OCR、文件存储；
|
||
- `persistence/` 负责 ORM、仓储和事务；
|
||
- `api/` 只处理鉴权、DTO、状态码和调用用例；
|
||
- `workers/` 只领取任务、调用用例和更新租约；
|
||
- Prompt 文件独立版本化并计算哈希，不散落在控制器字符串中。
|
||
|
||
### 2.2 关键接口
|
||
|
||
```python
|
||
class EmbeddingProvider(Protocol):
|
||
async def embed_documents(self, texts: list[str]) -> list[list[float]]: ...
|
||
async def embed_query(self, text: str) -> list[float]: ...
|
||
|
||
class Reranker(Protocol):
|
||
async def rerank(self, query: str, documents: list[str], top_n: int) -> list[RankedItem]: ...
|
||
|
||
class Generator(Protocol):
|
||
async def stream_answer(self, request: GroundedAnswerRequest) -> AsyncIterator[GenerationEvent]: ...
|
||
|
||
class DocumentParser(Protocol):
|
||
def parse(self, source: StoredDocument) -> ParsedDocument: ...
|
||
```
|
||
|
||
适配器契约要保留 request ID、usage 和耗时，但领域层不依赖供应商响应对象。
|
||
|
||
### 2.3 Python 质量
|
||
|
||
- Ruff 统一格式和 lint；
|
||
- mypy 或 pyright 做严格类型检查；
|
||
- pytest + coverage；
|
||
- 时间使用带时区 UTC，展示层转 Asia/Shanghai；
|
||
- UUID 作为外部资源 ID；
|
||
- 金额和精确数值不用二进制浮点做业务比较；
|
||
- 异常转成稳定错误码，不把内部堆栈返回前端；
|
||
- 所有外部调用显式 timeout、并发上限和取消传播。
|
||
|
||
## 3. 前端代码边界
|
||
|
||
### 3.1 Feature 结构
|
||
|
||
```text
|
||
features/chat/
|
||
api.ts
|
||
types.ts
|
||
hooks.ts
|
||
components/
|
||
pages/
|
||
tests/
|
||
```
|
||
|
||
`documents`、`retrieval`、`evaluation` 使用同样结构。通用按钮、来源卡片基础组件放 `components/`，业务组合留在各 feature。禁止把所有请求、状态和页面堆在单个 `App.tsx`。
|
||
|
||
### 3.2 TypeScript 质量
|
||
|
||
- TypeScript strict；
|
||
- ESLint + Prettier；
|
||
- API 类型从后端 OpenAPI 生成或由共享 schema 校验；
|
||
- TanStack Query 管理服务端状态，局部 UI 状态才用组件状态；
|
||
- Vitest/Testing Library 做单元与组件测试；
|
||
- Playwright 做上传、问答、引用和失败重试 E2E；
|
||
- SSE 重连、取消和错误状态必须测试；
|
||
- Markdown 渲染必须清理 HTML。
|
||
|
||
## 4. 阶段计划
|
||
|
||
每个阶段都必须形成“功能 + 测试 + 文档 + 提交 + 推送”的闭环。
|
||
|
||
截至 2026-07-13，核心 synthetic 上传→解析→审核→向量化→检索链已在 Docker 中连续两次
|
||
通过，当前门禁记录为 296 项后端测试和 53 项前端测试。以下阶段描述仍是最终 Definition of
|
||
Done，不因部分能力提前落地而降低验收标准；实时完成度和剩余项以
|
||
[04-project-todo.md](04-project-todo.md) 为准。
|
||
|
||
### 阶段 0：仓库、安全和设计基线
|
||
|
||
交付：
|
||
|
||
- 规范目录、README、贡献和安全规则；
|
||
- `.gitignore`、Secret 扫描钩子和 Gitea 工作流；
|
||
- 总体、数据评测、部署安全、实施计划和 ADR；
|
||
- 初始化远端仓库并推送。
|
||
|
||
验收：
|
||
|
||
- `make verify-design` 通过；当前阶段只验证文档、相对链接、diff 和密钥，尚不声称存在应用 lint/类型/测试结果；
|
||
- 工作树没有真实 Key、真实工作空间地址或受限数据；
|
||
- 所有 Markdown 链接和目录入口可定位；
|
||
- 第一笔提交推送到 `main`；Gitea Actions 仅在远端 runner 首次成功后才可称为已验证。
|
||
|
||
### 阶段 1：模型与数据库 PoC（1–2 天）
|
||
|
||
交付：
|
||
|
||
- 轮换后 Secret 注入；
|
||
- 最小后端 Python 包、`backend/Dockerfile` 和依赖锁定；
|
||
- 最小 Compose `db + migrate + provider-smoke`，以及数据库角色初始化脚本；
|
||
- 确定文档族 split 规则、盲测保管人/受控凭据和“盲测用于调参即退役”规则；
|
||
- Embedding/Rerank/Chat 三个独立适配器；
|
||
- `provider_smoke.py`；
|
||
- pgvector 1024 维表与迁移；
|
||
- 20 条虚构文本的写入/检索/重排测试。
|
||
|
||
验收：
|
||
|
||
- `docker compose up db migrate` 可在空 volume 上建立扩展、分权角色和表；
|
||
- `docker compose run --rm provider-smoke` 可独立执行三模型探测；
|
||
- `docker compose run --rm seed-demo` 可完成 20 条虚构数据写入、检索和重排；
|
||
- Key 不出现在日志、异常、镜像历史和 Git；
|
||
- Embedding 返回 1024 维，批次下标正确；
|
||
- Rerank URL 与响应下标正确；
|
||
- Chat 关闭思考可流式返回；
|
||
- 重复运行 seed 不增加数据。
|
||
|
||
建议提交意图：`Prove the selected model chain before building product workflows`。
|
||
|
||
### 阶段 2：扩展为完整工程骨架（3–4 天）
|
||
|
||
交付：
|
||
|
||
- 在阶段 1 的最小后端/数据库 Compose 上增加 FastAPI、React、Nginx 和 worker；
|
||
- `/health/live`、`/health/ready`；
|
||
- 数据库任务租约；
|
||
- Worker maintenance loop、advisory-lock reaper 与 fencing 恢复测试；
|
||
- OpenAPI 客户端生成；
|
||
- 一键 Compose。
|
||
|
||
验收：
|
||
|
||
- 空白机器按文档启动；
|
||
- migration 只执行一次且失败会阻止 API；
|
||
- 只有 Web 端口暴露；
|
||
- Docker 重启数据保留；
|
||
- 强杀任务 Worker 后，有剩余次数的任务可恢复、耗尽任务进入 FAILED、旧租约不能提交；
|
||
- API/前端 lint、类型和测试通过。
|
||
|
||
### 阶段 3：数字文档入库（1 周）
|
||
|
||
交付：
|
||
|
||
- PDF/DOCX/TXT/Markdown 上传；
|
||
- 权利元数据门禁；
|
||
- 冻结 corpus manifest 与文档族 60/20/20 划分，正式盲测标签继续由保管人隔离；
|
||
- 数字 PDF 页码/章节解析；
|
||
- 结构化切分；
|
||
- 批量向量化、检查点和版本激活；
|
||
- 文档状态 UI。
|
||
|
||
验收：
|
||
|
||
- 重复文件/任务幂等；
|
||
- 中途终止后恢复；
|
||
- 100% searchable 切片可追溯当前文档版本和页码；
|
||
- 预期切片数等于非空向量数；
|
||
- 删除后立即不能检索。
|
||
|
||
### 阶段 4：检索与重排（1 周）
|
||
|
||
交付：
|
||
|
||
- pgvector 精确和 HNSW 检索；
|
||
- 权限/知识库元数据过滤；
|
||
- qwen3-rerank；
|
||
- 邻接补全、去重和上下文预算；
|
||
- 检索实验室。
|
||
|
||
验收：
|
||
|
||
- 100 组语义三元组门槛达标或有错误报告；
|
||
- 初召回、重排结果和耗时可解释；
|
||
- ANN Recall@10 与精确基线对比；
|
||
- 未授权文档在候选生成阶段被排除。
|
||
|
||
### 阶段 5：生成、引用和问答 UI（1 周）
|
||
|
||
交付：
|
||
|
||
- `deepseek-v4-flash` SSE；
|
||
- 证据 Prompt；
|
||
- 引用编号验证；
|
||
- 会话、来源卡片、页码定位、反馈；
|
||
- 无答案与模型失败降级。
|
||
|
||
验收：
|
||
|
||
- 用户取消会终止下游请求；
|
||
- 模型自造引用被拦截；
|
||
- 证据不足题可以拒答；
|
||
- LLM 失败仍能显示检索结果；
|
||
- Prompt Injection 回归样例不改变系统行为。
|
||
|
||
### 阶段 6：OCR、表格与数据质量（1–2 周）
|
||
|
||
交付：
|
||
|
||
- 扫描页检测和可选 OCR profile；
|
||
- OCR 置信度复核队列；
|
||
- 表格 JSON/Markdown/语义行；
|
||
- 数值、单位、地质术语校验；
|
||
- 图件挑战集边界提示。
|
||
|
||
验收：
|
||
|
||
- 金标准页 CER、术语和数值指标可计算；
|
||
- 跨页表/合并单元格有失败而非静默错位；
|
||
- OCR 原文和修订文本都保留；
|
||
- 图件问题不会被当作已可靠支持。
|
||
|
||
### 阶段 7：验证集与消融实验（3–4 周）
|
||
|
||
交付：
|
||
|
||
- 至少 300 题（构建/开发/盲测各 100）的源证据锚点及 run-specific qrels；500 题仅在人力充分时扩展；
|
||
- 双人审核和一致性统计；
|
||
- union pooling、未判定候选补标、Hit/CompleteHit/MRR/nDCG、忠实度、引用和拒答指标；
|
||
- 维度、切片、Rerank、上下文等消融；
|
||
- 运行配置、预测、指标和错误分类。
|
||
|
||
验收：
|
||
|
||
- 测试集哈希冻结；
|
||
- Gold 问答未进入知识库；
|
||
- 正式盲测只用于最终结论；一旦结果用于调参，该集合立即退役为开发集并更换新的未见盲测集；
|
||
- 所有论文图表可由脚本重建；
|
||
- 指标带分层结果和置信区间。
|
||
|
||
### 阶段 8：安全、备份、性能和论文（1 周）
|
||
|
||
交付：
|
||
|
||
- RBAC、上传限制、限流、审计；
|
||
- 数据库/文件备份与恢复演练；
|
||
- p50/p95、并发、费用报告；
|
||
- 演示脚本、失败案例、局限性；
|
||
- 最终部署和答辩文档。
|
||
|
||
验收：
|
||
|
||
- 恢复到空白环境并通过固定 20 题冒烟；
|
||
- Secret 扫描和镜像检查通过；
|
||
- 端到端 p95 和错误率有实测；
|
||
- 论文不夸大图件、预测和专业结论能力。
|
||
|
||
## 5. 测试矩阵
|
||
|
||
| 层级 | 内容 |
|
||
|---|---|
|
||
| 单元 | 规范化、切分、哈希、下标映射、分数排序、引用校验、任务状态机 |
|
||
| 集成 | PostgreSQL/pgvector、迁移、任务租约、文件卷、备份恢复 |
|
||
| 契约 | 百炼 Embedding/Rerank/Chat 请求响应、错误码、超时和限流 |
|
||
| 端到端 | 上传 -> READY -> 检索 -> 重排 -> SSE -> 引用 -> 反馈 |
|
||
| 安全 | Secret、越权检索、路径穿越、恶意文件、XSS、Prompt Injection |
|
||
| 数据质量 | OCR CER、表格数值、页码追溯、重复和版本冲突 |
|
||
| 性能 | 入库吞吐、查询 p50/p95、ANN Recall、并发和成本 |
|
||
| 评测 | 检索、生成、引用、拒答、分层和消融 |
|
||
|
||
外部百炼契约测试分为：默认 CI 使用 fake server，不花费 Token；受控的手动/定时环境使用真实 Key。真实调用测试不得在外部贡献者 PR 自动执行。
|
||
|
||
## 6. Definition of Done
|
||
|
||
任何功能阶段标记完成前必须满足：
|
||
|
||
1. 范围内功能工作，失败路径可见。
|
||
2. 新行为有回归测试。
|
||
3. Ruff/类型/pytest、ESLint/TypeScript/Vitest 等适用门禁通过。
|
||
4. `make verify` 密钥和 diff 检查通过。
|
||
5. 迁移可向前应用，必要时有回滚/恢复说明。
|
||
6. API、配置和数据格式文档已更新。
|
||
7. 不新增未说明的依赖、服务或权限。
|
||
8. 运行证据和剩余风险写入阶段记录。
|
||
9. 使用 Lore 提交信息提交。
|
||
10. 推送远端并确认提交可见。
|
||
|
||
## 7. 提交和推送协议
|
||
|
||
### 7.1 频率
|
||
|
||
- 每个阶段至少一个可独立回滚的提交；
|
||
- 大阶段按数据库、后端、前端、测试拆成少量有意义提交；
|
||
- 不为每个微小文件保存制造无意义提交；
|
||
- 在“验证通过的过程点”提交，而不是未测试半成品；
|
||
- 当前阶段结束后立即推送；后续每个阶段同样执行。
|
||
|
||
### 7.2 Lore 示例
|
||
|
||
```text
|
||
Establish a safe and reproducible foundation for the RAG project
|
||
|
||
The repository begins with the architecture, data governance, evaluation,
|
||
and secret-handling contracts required before model calls or corpus ingestion.
|
||
|
||
Constraint: Real provider credentials and restricted geological data must never enter Git
|
||
Rejected: Add runnable placeholder services | would imply unverified implementation
|
||
Confidence: high
|
||
Scope-risk: narrow
|
||
Directive: Run make verify before every commit and update ADRs for architecture changes
|
||
Tested: Documentation checks, secret scan, git diff validation
|
||
Not-tested: Application runtime has not been implemented in the design stage
|
||
```
|
||
|
||
### 7.3 推送失败
|
||
|
||
网络或远端认证失败时：
|
||
|
||
- 本地提交仍保留，记录失败原因；
|
||
- 不把 Token 写进 remote URL；
|
||
- 使用系统 Git Credential Manager/SSH agent；
|
||
- 恢复连接后只推送已验证提交；
|
||
- 不用关闭 TLS 验证或把凭证明文写入脚本绕过问题。
|
||
|
||
## 8. 最终答辩演示脚本
|
||
|
||
1. 展示仓库 Secret 防护和无密钥配置。
|
||
2. `docker compose up -d --build` 启动并展示健康状态。
|
||
3. 上传一份合法数字报告，展示页码解析、分块和向量数量。
|
||
4. 用同一问题展示 Top 50 初召回、重排 Top 10 和最终上下文 Top 8 的变化。
|
||
5. 展示带页码来源的流式答案。
|
||
6. 提问一个语料无答案问题，展示拒答。
|
||
7. 展示一个旧/新资料冲突问题，分别引用。
|
||
8. 展示表格数值问题及单位来源。
|
||
9. 打开评测面板，比较无 RAG、无 Rerank、完整 RAG。
|
||
10. 展示错误分类、局限性和恢复演练证据。
|
||
|
||
## 9. 论文结构映射
|
||
|
||
| 论文章节 | 工程证据 |
|
||
|---|---|
|
||
| 绪论 | 课题背景、目标、国内外工作和边界 |
|
||
| 相关技术 | RAG、Embedding、Rerank、LLM、pgvector |
|
||
| 需求与总体设计 | [00-overall-design.md](00-overall-design.md) |
|
||
| 知识库构建 | 解析、OCR、表格、切分、版本与入库测试 |
|
||
| 检索生成实现 | 两阶段检索、Prompt、SSE 和引用 |
|
||
| 实验与评测 | 验证集、指标、消融、置信区间和成本 |
|
||
| 系统实现 | 前后端页面、API、Docker 和安全 |
|
||
| 总结与展望 | 失败案例、图件限制、多模态和扩展路径 |
|
||
|
||
## 10. 进度判断
|
||
|
||
进度报告必须区分：
|
||
|
||
- 当前提交/阶段完成度；
|
||
- 整个系统完成度；
|
||
- 已验证能力；
|
||
- 仅完成设计、尚未验证的能力；
|
||
- 剩余风险和预计时间。
|
||
|
||
不能因设计文档完整就声称系统已经实现，也不能因页面可演示就声称评测和安全已经完成。
|