YoVinchen
f4ba5d5342
Some checks failed
verify / verify (push) Has been cancelled
The Stage 1 foundation now proves provider contracts with mocks and validates PostgreSQL/pgvector ingestion, approval binding, retrieval, reranking, and idempotency using only synthetic data. Live Bailian validation remains gated on rotating the exposed key. Constraint: The key shown in chat is compromised and cannot be used or committed Rejected: Mark Stage 1 complete from mock and offline results | real three-model smoke is still required Confidence: high Scope-risk: moderate Reversibility: clean Directive: Do not enable real-data ingestion until Stage 3 cloud approval and outbound manifest controls are enforced end to end Tested: make verify; 41 pytest tests; strict mypy; Ruff; Compose config; pinned image build; empty-volume migration; role denial; two idempotent 20-vector seeds; database restart persistence Not-tested: Live Bailian calls require a newly rotated key; React product UI is not implemented
61 lines
3.1 KiB
Markdown
61 lines
3.1 KiB
Markdown
# 基于 RAG 的地质找矿知识问答系统
|
||
|
||
本仓库用于“基于 RAG 的地质找矿知识问答系统构建与应用”毕业设计。系统计划采用 Python/FastAPI 后端、React/TypeScript 前端、PostgreSQL + pgvector 向量存储，以及阿里云百炼的 `text-embedding-v4`、`qwen3-rerank`、`deepseek-v4-flash`。
|
||
|
||
当前处于 Stage 1“模型与数据库 PoC”：设计基线与离线 pgvector/适配器/seed 子闭环可运行，真实百炼 smoke 仍待轮换后的新 Key，React 产品功能尚未开始。完整方案、状态和评测方法见 [docs/README.md](docs/README.md)，仓库不会把 PoC 伪装成已经完成的产品。
|
||
|
||
## 目录
|
||
|
||
```text
|
||
.
|
||
├── backend/ Python 后端代码与测试
|
||
├── frontend/ React 前端代码与测试
|
||
├── docs/ 全部需求、架构、数据、评测、部署和决策文档
|
||
├── data/ 只提交清单、格式说明和允许公开的小样例
|
||
├── ops/ Docker/PostgreSQL 初始化等运维资产（不含凭证）
|
||
├── scripts/ 安全检查、导入、验证、评测和运维脚本
|
||
├── .githooks/ 本地 Git 钩子
|
||
└── .gitea/workflows/ Gitea Actions 工作流
|
||
```
|
||
|
||
## 安全红线
|
||
|
||
- 百炼 API Key 只通过 Docker Secret、环境变量或云密钥管理服务注入。
|
||
- 真实 `.env`、`secrets/`、原始受限资料和私有评测数据一律禁止提交。
|
||
- 前端不得接触模型密钥；所有模型请求只能由后端发起。
|
||
- 每次提交前运行 `make verify`。当前设计阶段它执行文档、链接、diff 和密钥检查；代码落地后将扩展为后端/前端 lint、类型、测试和镜像检查。首次克隆后运行 `make setup-hooks` 启用提交前密钥检查。
|
||
- 若密钥曾出现在聊天、日志、终端历史或提交中，立即在百炼控制台重置；仅从 Git 历史删除文件并不能让密钥恢复安全。
|
||
|
||
## 阶段交付规则
|
||
|
||
每个阶段必须按以下顺序结束：
|
||
|
||
1. 完成该阶段可验证的最小闭环。
|
||
2. 运行格式、静态检查、测试和密钥扫描。
|
||
3. 更新 `docs/` 中的状态与设计决策。
|
||
4. 使用符合 Lore 协议的提交信息提交。
|
||
5. 推送到远端，确保过程产物可追踪。
|
||
|
||
## 文档入口
|
||
|
||
- [总体设计](docs/00-overall-design.md)
|
||
- [数据与评测设计](docs/01-data-and-evaluation.md)
|
||
- [部署与安全设计](docs/02-deployment-and-security.md)
|
||
- [实施计划与验收](docs/03-implementation-plan.md)
|
||
- [全生命周期 TODO 与进度](docs/04-project-todo.md)
|
||
- [Stage 1 PoC 运行手册](docs/05-stage1-runbook.md)
|
||
- [架构决策记录](docs/adr/README.md)
|
||
|
||
## 当前可运行入口
|
||
|
||
```bash
|
||
make setup-hooks
|
||
make backend-sync
|
||
bash scripts/init-local-secrets.sh
|
||
docker compose up -d --build db migrate
|
||
docker compose --profile tools run --rm seed-demo-offline
|
||
make verify
|
||
```
|
||
|
||
这组命令不需要百炼 Key，只使用 20 条虚构数据验证 pgvector 写入、检索、重排和幂等。真实模型运行必须先轮换聊天中已暴露的旧 Key，再按 [Stage 1 运行手册](docs/05-stage1-runbook.md) 操作。
|