Establish a safe foundation before implementing the geology RAG system
Some checks failed
secret-scan / scan (push) Has been cancelled
Some checks failed
secret-scan / scan (push) Has been cancelled
The project begins with architecture, data governance, reproducible evaluation, deployment boundaries, and secret-handling contracts so later code has measurable acceptance criteria. Constraint: Real provider credentials, workspace identities, and restricted geological data must never enter Git Rejected: Add placeholder runnable services in the design commit | would imply unverified implementation readiness Confidence: high Scope-risk: narrow Reversibility: clean Directive: Run make verify before every commit and update ADRs when architecture boundaries change Tested: Secret scan, Markdown links, YAML parse, shell syntax, and staged diff validation Not-tested: Application runtime is intentionally deferred to the implementation stage
This commit is contained in:
440
docs/03-implementation-plan.md
Normal file
440
docs/03-implementation-plan.md
Normal file
@@ -0,0 +1,440 @@
|
||||
# 实施计划、代码规范与验收标准
|
||||
|
||||
| 项目 | 内容 |
|
||||
|---|---|
|
||||
| 计划周期 | 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. 阶段计划
|
||||
|
||||
每个阶段都必须形成“功能 + 测试 + 文档 + 提交 + 推送”的闭环。
|
||||
|
||||
### 阶段 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. 进度判断
|
||||
|
||||
进度报告必须区分：
|
||||
|
||||
- 当前提交/阶段完成度；
|
||||
- 整个系统完成度；
|
||||
- 已验证能力；
|
||||
- 仅完成设计、尚未验证的能力；
|
||||
- 剩余风险和预计时间。
|
||||
|
||||
不能因设计文档完整就声称系统已经实现，也不能因页面可演示就声称评测和安全已经完成。
|
||||
Reference in New Issue
Block a user