YoVinchen
63279cf213
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
基于 RAG 的地质找矿知识问答系统
本仓库用于“基于 RAG 的地质找矿知识问答系统构建与应用”毕业设计。系统计划采用 Python/FastAPI 后端、React/TypeScript 前端、PostgreSQL + pgvector 向量存储，以及阿里云百炼的 text-embedding-v4、qwen3-rerank、deepseek-v4-flash。
核心 synthetic 产品链现已在 Docker 中多次端到端通过：文档上传、本地解析、manifest 人工审核、向量写库、原子激活、正式检索和带引用问答均可运行，React 已提供 /documents、/retrieval 和 /chat 页面。固定 fixture 的两次入库使用相同身份，version/chunk/assignment/jobs/invocations 计数稳定为 1/1/1/2/1；最新 fresh + replay smoke 还证明当前 Worker 执行与幂等重放均有效。当前质量门禁记录为 296 项后端测试、53 项前端测试。真实百炼的 text-embedding-v4、qwen3-rerank、deepseek-v4-flash 仍全部返回 401，PDF/OCR、正式认证与多租户、300 题盲测、备份恢复/压测、论文和答辩仍未完成，因此本仓库不会把 synthetic 闭环描述为毕业验收完成。
目录
.
├── 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、密钥、后端与前端格式、类型、测试、构建和 Compose 配置检查。首次克隆后运行make setup-hooks启用提交前密钥检查。 - 若密钥曾出现在聊天、日志、终端历史或提交中，立即在百炼控制台重置；仅从 Git 历史删除文件并不能让密钥恢复安全。
阶段交付规则
每个阶段必须按以下顺序结束：
- 完成该阶段可验证的最小闭环。
- 运行格式、静态检查、测试和密钥扫描。
- 更新
docs/中的状态与设计决策。 - 使用符合 Lore 协议的提交信息提交。
- 推送到远端，确保过程产物可追踪。
文档入口
- 总体设计
- 数据与评测设计
- 部署与安全设计
- 实施计划与验收
- 全生命周期 TODO 与进度
- Stage 1 PoC 运行手册
- React 离线检索演示运行手册
- 正式检索、Worker 与评测运行手册
- Grounded Chat 运行与引用验证手册
- 文档上传、审核、向量化与检索运行手册
- 架构决策记录
当前可运行入口
make setup-hooks
bash scripts/init-local-secrets.sh
make up
make seed-offline
make smoke-document
curl http://127.0.0.1:8000/health/ready
make verify
这组命令不需要有效百炼 Key，只使用公开虚构数据验证上传、解析、审批、向量化、pgvector 写入和正式检索/重排；Chat 引用与同源 Web 交互由测试套件及对应页面单独验证。migrate 与 upload-init 是成功后正常显示 Exited (0) 的一次性任务，不是服务暂停。启动后访问 http://127.0.0.1:8000/documents 完成文档入库与审核，访问 http://127.0.0.1:8000/retrieval 查看正式检索页，访问 http://127.0.0.1:8000/chat 查看 Grounded Chat，或访问 http://127.0.0.1:8000/docs 查看 Swagger。详细操作见 文档入库运行手册。真实模型运行必须先轮换聊天中已暴露的旧 Key，再按 Stage 1 运行手册 操作；真实 Key 永远不得提交到 Git。