资料库问答 112GT/RAG-for-DSH

RAG for DSH

English · 使用指南 ·数据库结构 · DSH 接入

面向工程参考资料、开发文档和个人笔记的可追溯问答系统。Windows 本机负责资料解析和入库，Linux 云端负责权限、检索与重排，再按需调用 DeepSeek API 生成答案。
仓库附带 DSH MCP 接入组件，DeepSeek Harness 能直接查询同一套资料库。

公开版包含源代码和空数据库结构，不包含我们的数据库内容。 原文、OCR 文本、数据库记录、用户、密码、API Key、模型权重和真实部署身份均不提供，没有默认网页登录密码。

已包含的功能

- PDF 解析、保留页码的分块、CPU 向量化和按名称/路径识别资料。
- Windows 团队/个人投放目录，可选 OCR、DOCX 转 PDF 和稳定文件检测。
- PostgreSQL 保存权威正文及元数据，Qdrant 保存可重建的向量索引。
- 稠密/关键词召回、同义词扩展、RRF 融合、相邻页候选、重排与文件名/页码引用。
- 邀请制注册、网页登录会话、团队/个人范围、检索和原文取件权限检查。
- 原生网页、纯检索 API、SSE 流式问答，以及共用已验证证据的有界云端 agent 流程。
- PyTorch CPU 推理和可选 ONNX int8 重排导出/运行。
- 我们的 DSH MCP 桥接器、插件配置生成工具和 Windows 启动脚本。
- Python venv + systemd + Nginx 原生部署，可选 WireGuard，无需 Docker。

当前界面及默认生成提示词使用简体中文；英文文档不代表产品已完成英文界面适配。

架构与分工

flowchart LR
Input[本地 PDF / DOCX] --> Index[解析 / OCR / 分块 / 向量化]
Index --> PG[(PostgreSQL)]
Index --> Q[(Qdrant)]
PG --> Cloud[云端鉴权 / 召回 / 回查 / 重排]
Q --> Cloud
Files[本地 PDF 文件服务] --> Cloud
Cloud --> API[DeepSeek HTTPS API]
API --> Cloud
Cloud --> Web[网页 / SSE / 引用]
DSH[DeepSeek Harness] --> MCP[本项目 MCP 桥接器]
MCP --> Cloud

| 组件 | 位置 | 责任 |
| 解析、OCR、向量化、投放任务 | Windows 本机 | 资料整理与写入 |
| PostgreSQL 与 Qdrant | 数据节点 | 正文、元数据、ACL 与向量索引 |
| 文件服务 | 数据节点 | 鉴权后的原始 PDF 读取 |
| FastAPI 和检索模型 | Linux 云端 | 认证、召回、校验、重排、生成编排 |
| SQLite | Linux 云端 | 邀请码、账号、会话、审计元数据，与知识库分开 |
| DeepSeek API | 自选服务商 | 生成答案，不托管数据库 |
| DSH 与 MCP | 工作电脑 | agent 工具与登录后的 RAG 访问 |

两端通过加密私有链路连接，云端持有只读数据凭据。原始资料保留在数据节点，但生成时检索片段会送到模型 API；仅将允许向相应服务商披露的内容用于 API 生成。

仓库目录

rag_node/ 本地解析、入库、OCR、文件服务 scripts/ 启动、投放、备份、MCP、发布检查 sql/schema.sql PostgreSQL 空表定义 sql/qdrant_schema.json 向量集合、payload 索引与嵌入契约 cloud/app/ 云端网页、认证、检索、生成、agent cloud/sql/session_schema.sql SQLite 空账号/会话/审计表定义 cloud/deploy/ systemd、Nginx、WireGuard 模板 cloud/requirements/ 云端依赖锁与可选 ONNX 依赖 integrations/dsh/ 插件配置、初始化与启动工具 docs/ 中英文使用与数据库说明 examples/ 合成 PDF 生成器，不附真实资料 tests/、cloud/tests/ 合成数据和离线测试

准备条件

参考部署为 Windows x64 数据节点 + Linux x64 云端，Python 3.10，支持纯 CPU。
8 vCPU / 16 GiB 是设计参考，不是并发能力保证。模型占数 GB，要为加载峰值、ONNX 导出和资料留空间。自行准备云服务器、VPN 或 HTTPS 域名与证书、模型 API 账号和有权使用的资料。
DSH 可选，其 Node/pnpm 环境独立安装。

本机自动初始化、投放锁和便携 LibreOffice 路径针对 Windows。迁移 Linux 数据节点时要手工配置服务并调整这些部分，Python 文件服务与入库核心可复用。

1. 安装全新 Windows 数据节点

克隆/解压到空目录，下方以 C:\workspace\RAG-for-DSH 为例，在 PowerShell 执行。
已有 rag-oss 环境时直接激活，避免重复创建。

Set-Location 'C:\workspace\RAG-for-DSH'
conda create -n rag-oss python=3.10 -y
conda activate rag-oss
python -m pip install --index-url https://download.pytorch.org/whl/cpu torch==2.14.0+cpu
python -m pip install --index-url https://pypi.tuna.tsinghua.edu.cn/simple -e '.[embed,dev]'
python -m pip check
New-Item -ItemType Directory -Force runtime/downloads | Out-Null
curl.exe -fL 'https://get.enterprisedb.com/postgresql/postgresql-17.11-4-windows-x64-binaries.zip' -o runtime/downloads/postgresql-17.11-4-windows-x64-binaries.zip
curl.exe -fL 'https://github.com/qdrant/qdrant/releases/download/v1.19.1/qdrant-x86_64-pc-windows-msvc.zip' -o runtime/downloads/qdrant-v1.19.1-windows.zip
python scripts/prepare_binaries.py
python scripts/bootstrap_services.py
python -m rag_node.cli init-store

解压工具按预期压缩包名称取件并检查解压路径。上游不再提供某版本时，选择兼容替代包并更新文件名。清华 PyPI 不通可换 https://pypi.org/simple，数据库二进制使用上游地址。

首次自动初始化前，不要复制 .env.example。 脚本会生成独立随机凭据，保存到受限 runtime/secrets.json 并创建 .env，创建新 rag 数据库及回环服务。
已有不认识的数据或端口占用会拒绝继续。.env.example 仅用于手工部署方式。

2. 下载嵌入模型，试用合成文档

权重不上传到本 GitHub 仓库或 Release。使用项目附带脚本，从 Hugging Face 下载 BAAI/bge-m3 与 BAAI/bge-reranker-v2-m3，网络受限时显式选择镜像。每个原始权重文件约 2.27 GB（2.12 GiB），超过 GitHub Release 单文件 2 GiB 限制。
两个模型目录预留约 5 GB，推理及导出空间另计。

按模型名 BAAI/bge-m3 与分支名 main 下载，不固定提交编号。
输出为 1024 维归一化向量；本机和云端使用同一批下载的模型文件。

官方 Hugging Face 不可达时显式选择镜像： $env:HF_ENDPOINT = 'https://hf-mirror.com'
python scripts/download_embedding_model.py
python examples/create_demo_pdf.py
python -m rag_node.cli ingest
python -m rag_node.cli query 'What does the synthetic document contain?'

模型显式下载，推理时离线加载，按文件名与路径取件。清单只记录模型名、分支/标签名和文件名，不解析或记录提交编号；更换嵌入模型文件后主动重新入库。
测试 PDF 在本机生成并被 Git 忽略。query 是数据节点检索诊断，不生成大模型答案。

3. 连接数据节点与云端

使用 cloud/deploy/wireguard/ 模板自行生成密钥、选择地址，只路由必要对端地址，不接管默认路由，不向公网开放 TCP 5432/6333/8765。Windows 服务绑定回环，需要精确的 VPN 到回环端口转发和防火墙规则，详见使用指南。

初始化表结构后，生成独立云端读取凭据：

$nodeVpn = Read-Host '本机数据节点的私有 VPN IPv4'
python scripts/prepare_cloud_reader.py --data-host $nodeVpn

将受限 runtime/cloud_access.json 经已验证 SSH 连接传到云端，用其字段填写 .env。
PostgreSQL 只授予 CONNECT/USAGE/SELECT，Qdrant 使用独立只读 key。
不要传入库管理员凭据或本机 secrets.json。核对握手、路由和真实 TCP/HTTP 连接。

4. 部署 Linux 云端

将 cloud/ 的内容，包含 sql/ 放到 /opt/rag-cloud。全新 Ubuntu 主机可执行：

sudo apt-get update
sudo apt-get install -y python3-venv nginx ca-certificates
sudo useradd --system --home /opt/rag-cloud --shell /usr/sbin/nologin rag
cd /opt/rag-cloud
bash scripts/install_dependencies.sh
cp .env.example .env
chmod 600 .env
.venv/bin/python scripts/download_models.py --endpoint https://hf-mirror.com

已有合适用户时复用，不要盲目重复 useradd。安装工具仅处理本项目 venv，CPU Torch 走官方 CPU 源，其他依赖尝试清华源再回退官方源，不卸载其他服务。
下载工具不传 --endpoint 时使用官方 Hugging Face；两个模型均默认使用 main。
可用 --embedding-revision <分支或标签名>、--reranker-revision <分支或标签名> 选择来源，工具不解析或记录提交编号。

编辑 .env，填数据节点只读连接、自己的 DeepSeek Key、API 账号实际支持的模型 ID、随机生成的 JWT_SECRET。核对项目 ID、集合名和嵌入契约；保持 QA_STUB_MODE=off。

sudo install -d -o rag -g rag /opt/rag-cloud/data /opt/rag-cloud/home
sudo chown -R rag:rag /opt/rag-cloud
sudo cp deploy/rag.service /etc/systemd/system/rag.service
sudo systemctl daemon-reload
sudo systemctl enable --now rag.service

有域名证书时选 deploy/nginx-rag-https.conf.example，仅回环入口选 deploy/nginx-rag.conf.example。修改并安装站点，先 sudo nginx -t 再 reload。
HTTPS 配置 COOKIES_SECURE=true；VPN 内 HTTP 配置 false，并按指南追加受限隧道监听。
回环监听单独不能跨电脑访问；配置正确后两种方式均不需要 VS Code。

systemctl is-active rag.service
curl -i http://127.0.0.1:8000/health/ready
sudo -u rag .venv/bin/python scripts/manage_users.py invite --label first-user --uses 1 --days 1

打开可达入口 /login，用邀请码注册并自定密码，再进入 /app。公开版没有预置用户。
live 代表进程存活；必需依赖与模型检查通过后 ready 应为 200，但它本身不能证明完整模型生成、引用质量和并发能力。完整配置参见使用指南及云端部署指南。

5. 加入资料，接入 DSH

私人入库前把本机 .env 的 RAG_PERSONAL_OWNER 改成准确网页登录用户名，配置变更后重启文件服务。

New-Item -ItemType Directory -Force inbox/team, inbox/personal | Out-Null
放入已复制完成的 PDF/DOCX 后：
python scripts/process_inbox.py --now

团队使用 reference，个人使用 personal 并绑定账号 ACL。
资料按项目与相对文件名识别。同名投放更新用 python scripts/process_inbox.py --now --retry-failed --replace；直接入库更新用 --force，OCR 刷新步骤见使用指南。
OCR 需要 pip install -e '.[ocr]'，DOCX 需要指南路径下的 LibreOffice。
自动处理时计划运行不带 --now 的短任务，等待文件复制稳定。
本架构的“上传”是自动入库供云端远程查询，不会把整库复制到 ECS。

已安装 Harness 时，首次配置后启动：

python integrations/dsh/setup.py --base-url https://rag.example.com
.\integrations\dsh\start-dsh.ps1 -DSHRoot 'C:\workspace\deepseek-harness'

工具交互输入已有 RAG 网页账号，将凭据保存在仓库外。
DSH 中先调用 mcp__rag__rag_scopes，再优先用 mcp__rag__rag_search 获取文件名和 PDF 页码证据。
DSH 完整说明包含参数、编程流程、subagent 与连接行为。

测试与边界

python -m pytest tests -p no:cacheprovider
python scripts/check_release.py

云端安装测试依赖后，在 cloud/ 内运行 .venv/bin/python -m pytest tests -p no:cacheprovider。离线模拟测试不等于真实 API 或新部署验收；不要误将入库或压测指向生产。

不承诺固定 token 速度、六人延迟或全库召回正确率。CPU 重排、VPN/数据库往返和 API 限制影响并发。云端 agent 有调用数、token、超时约束，不是无限制代码执行 agent。
OCR 公式和图表要核对，引用是 PDF 页序而非纸质页码；源码与 PCB 格式需要另加解析器。
权限隔离依赖受保护的服务凭据及可信云端/文件服务链路，数据节点管理员可直接访问底层数据。

开放入口前阅读 SECURITY.md，发布前阅读检查清单。
结构导出的备注、角色名也可能暴露身份；不要加入 dump、snapshot、真实评测日志或个人文件。
扫描器同时检查暂存 Git 内容与工作文件，仍需人工检查。

代码使用 MIT；Harness、依赖和模型权重遵循各自许可，本仓库许可不授予资料再分发权。