YoVinchen
c3bad0f186
Some checks failed
verify / verify (push) Has been cancelled
Expose the verified synthetic retrieval path through a typed React client and a non-root Nginx edge while keeping database credentials and data-network reachability out of the browser tier. A fixed-origin gateway preserves request boundaries and now closes upstream streams even when downstream disconnects before body iteration. The deployment ADR and runbooks record the four-network topology and its accepted Web edge-egress risk. Constraint: The previously exposed Bailian key must be revoked and no live provider credential may enter Git, images, logs, or the browser. Rejected: Connect Web directly to the data network | expands lateral reach to PostgreSQL. Rejected: Publish the database-aware API on the edge network | gives a credential-bearing process a public default route. Rejected: Buffer streaming responses in either proxy | prevents incremental chat delivery in the future. Confidence: high Scope-risk: moderate Reversibility: clean Directive: Do not mark Stage 1 or Stage 2 complete until the rotated-key live smoke and remaining stage gates pass. Tested: make verify; 65 backend tests; 14 frontend tests; Docker image build; container health and isolation probes; real HTTP demo/status/search/docs/OpenAPI checks. Not-tested: Live Bailian models, real document ingestion, business chat SSE generation, and final browser screenshot automation because the browser skill runtime was unavailable.
63 lines
3.5 KiB
Markdown
63 lines
3.5 KiB
Markdown
# 基于 RAG 的地质找矿知识问答系统
|
||
|
||
本仓库用于“基于 RAG 的地质找矿知识问答系统构建与应用”毕业设计。系统计划采用 Python/FastAPI 后端、React/TypeScript 前端、PostgreSQL + pgvector 向量存储，以及阿里云百炼的 `text-embedding-v4`、`qwen3-rerank`、`deepseek-v4-flash`。
|
||
|
||
当前处于 Stage 1“模型与数据库 PoC”：设计基线、离线 pgvector/适配器/seed、FastAPI 和 React/Nginx 可视化检索演示均可运行；真实百炼 smoke 仍待轮换后的新 Key，正式知识库、文档入库和生成问答尚未实现。完整方案、状态和评测方法见 [docs/README.md](docs/README.md)，仓库不会把离线演示伪装成已经完成的产品。
|
||
|
||
## 目录
|
||
|
||
```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、密钥、后端与前端格式、类型、测试、构建和 Compose 配置检查。首次克隆后运行 `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)
|
||
- [React 离线检索演示运行手册](docs/06-frontend-demo-runbook.md)
|
||
- [架构决策记录](docs/adr/README.md)
|
||
|
||
## 当前可运行入口
|
||
|
||
```bash
|
||
make setup-hooks
|
||
bash scripts/init-local-secrets.sh
|
||
docker compose up -d --build web
|
||
docker compose --profile tools run --rm seed-demo-offline
|
||
curl http://127.0.0.1:8000/health/ready
|
||
curl http://127.0.0.1:8000/api/v1/demo/status
|
||
make verify
|
||
```
|
||
|
||
这组命令不需要百炼 Key，只使用 20 条虚构数据验证 pgvector 写入、检索、重排、引用编号和同源 Web 交互。`web` 会依次启动数据库、迁移、内部 API 和 gateway；启动后访问 <http://127.0.0.1:8000/> 使用 React 演示，或访问 <http://127.0.0.1:8000/docs> 查看 FastAPI Swagger。真实模型运行必须先轮换聊天中已暴露的旧 Key，再按 [Stage 1 运行手册](docs/05-stage1-runbook.md) 操作。
|