xianggao31412-png/production-rag-system

# 企业知识助手 一个具备 reranking、可靠引用、namespace 隔离、API-key 认证、速率限制、结构化日志、健康/就绪探针以及内置**实时运营 dashboard** 的**最低生产级混合检索 RAG 平台**。 它**开箱即用，完全离线运行**（无需下载模型，无需 GPU，无需网络），使用确定性哈希 embedder、内存向量存储和抽取式回答生成器——然后只需切换几个环境变量，即可升级为**本地 Ollama**（`qwen3-coder:30b` + `nomic-embed-text`）、**ChromaDB** 和 **cross-encoder reranker**。API 或 dashboard 的任何内容都不会改变。 ## 为什么这不是玩具 大多数“RAG 演示”只是将单个向量搜索连接到 LLM。以下是将其转变为平台的三个升级： 1. **混合搜索** — 通过 Reciprocal Rank Fusion 将 BM25 词法检索与稠密向量检索融合。它能捕捉被 embedding 淡化的确切术语、ID 和缩写，*以及*关键词遗漏的语义匹配。 2. **Reranking** — 对融合后的候选结果进行第二阶段相关性筛选（默认为启发式，可选 cross-encoder），从而确保交给 LLM 的 chunk 是*最*相关的，而不仅仅是最容易被检索到的。 3. **运营 dashboard** — 一个真正的仪表盘，可逐阶段追踪实时检索 pipeline 并测量每个阶段的延迟，此外还提供目录、指标和最近的查询反馈。 除此之外，它还具备一个真正的服务所需的功能：摄入时的去重、与向量索引解耦的持久化目录 (SQLite)、每请求追踪、token-bucket 速率限制、一致的 JSON 错误封装、约 40 个测试套件，以及 Docker 打包。 ## 功能概览 | 领域 | 您将获得 | |------|--------------| | 检索 | 混合 BM25 + 向量，RRF 或加权融合，每个阶段可配置 top-k | | Reranking | 启发式（无需下载）或 cross-encoder（`sentence-transformers`） | | 生成 | 兼容 OpenAI 的聊天 (Ollama/llama.cpp)，带有**抽取式存根回退**，确保回答*始终*有理有据并附有引用 | | 引用 | 每个回答都带有映射到源 chunk 的 `[n]` 标记；`grounded` 标志 | | 隔离 | Namespace 划分文档、检索和分析数据 | | 安全性 | API-key 认证 (`X-API-Key`)，基于客户端的 token-bucket 速率限制 | | 可观测性 | 结构化 JSON 日志 + 请求 ID，`/health`、`/ready`、`/v1/admin/metrics`、实时 dashboard | | 存储 | SQLite 目录 + 分析数据；numpy 向量存储（pickle 持久化）或 ChromaDB | | 摄入 | TXT、Markdown、CSV/TSV、PDF；sha256 去重；边界感知分块 | | 运维 | Dockerfile + compose、Makefile、`run.sh` / `run.bat`、冒烟测试 + seed 脚本 | ## 快速开始 ### 最简单 — 在 Windows 上一键运行 1. **运行应用程序：** 双击 **`START_SOFTWARE.bat`**。它将创建虚拟环境、安装依赖项、生成 `.env`、创建 `data/ logs/ output/` 文件夹、启动服务器，并在 `http://127.0.0.1:8000/dashboard` 打开 dashboard。（无需管理员权限，包含空格的路径也可以正常运行，且绝不会删除您的文件。） 2. **查看所有功能：** 在 dashboard 中点击 **Run showcase demo** —— 它会加载捆绑的展示文档并运行一系列引导式问题，使整个 pipeline 亮起。或者双击 **`RUN_DEMO.bat`** 进行有旁白的命令行之旅（可离线工作，无需服务器）。 ### 选项 A — 离线演示（除 pip 外零依赖） ``` # 1. 安装 python -m pip install -r requirements.txt # 2. （可选）复制 demo env；默认已支持离线运行 cp .env.example .env # 3. 运行 uvicorn app.main:app --host 0.0.0.0 --port 8000 ``` 然后打开 **http://localhost:8000/dashboard**，在顶部栏粘贴 API key `dev-local-key`，即可摄入文件或运行查询。或者使用内置示例进行 seed： ``` python scripts/seed_examples.py --api-key dev-local-key ``` 在 Windows 上，您只需双击 **`run.bat`**（创建虚拟环境、安装、复制演示环境并启动服务器）。 ### 选项 B — 使用本地 Ollama 的生产配置 ``` ollama pull qwen3-coder:30b ollama pull nomic-embed-text ``` 在 `.env` 中，注释掉演示块并启用生产块（参见 [`docs/CONFIGURATION.md`](docs/CONFIGURATION.md)）。关键切换项： ``` EMBEDDING_PROVIDER=openai_compatible EMBEDDING_BASE_URL=http://127.0.0.1:11434/v1 EMBEDDING_MODEL=nomic-embed-text EMBEDDING_DIM=768 LLM_FORCE_STUB=false LLM_MODEL=qwen3-coder:30b # 可选的较重 backends： # VECTOR_BACKEND=chroma (pip install chromadb) # RERANK_PROVIDER=cross_encoder (pip install sentence-transformers) ``` 重启服务器。Dashboard 现在将显示实时的模型名称和真实的生成延迟。 ## 从命令行尝试 ``` KEY=dev-local-key # ingest curl -s -X POST "http://localhost:8000/v1/documents?namespace=demo" \ -H "X-API-Key: $KEY" -F "file=@demo/examples/company_policy.txt" # ask curl -s -X POST "http://localhost:8000/v1/query" \ -H "X-API-Key: $KEY" -H "Content-Type: application/json" \ -d '{"question":"How many vacation days do employees get?","namespace":"demo"}' ``` 请参阅 [`docs/API.md`](docs/API.md) 获取完整的 endpoint 参考。 ## 项目结构 ``` enterprise-knowledge-assistant/ ├── app/ │ ├── config.py # env-driven settings (pydantic-settings) │ ├── logging_config.py # JSON logs + request-id context │ ├── errors.py # typed errors + JSON envelope handlers │ ├── models/ # domain dataclasses + Pydantic wire schemas │ ├── core/ │ │ ├── extraction.py # TXT/MD/CSV/PDF text extraction │ │ ├── chunking.py # boundary-aware sliding-window chunker │ │ ├── embeddings/ # hash (default) | openai_compatible │ │ ├── vectorstore/ # memory (default) | chroma │ │ ├── keyword/ # BM25 index │ │ ├── fusion.py # RRF + weighted fusion │ │ ├── rerank/ # heuristic (default) | cross_encoder │ │ ├── retriever.py # the hybrid retrieval pipeline │ │ ├── llm.py # OpenAI-compatible client + extractive stub │ │ └── rag.py # context assembly + citation extraction │ ├── storage/ # SQLite catalogue + analytics │ ├── services/ # ingest / query / admin orchestration │ ├── middleware/ # request-id + rate-limit │ ├── api/ # FastAPI routers + auth deps │ ├── dashboard/ # single-page ops console (HTML/CSS/JS) │ ├── container.py # dependency wiring │ └── main.py # app factory + lifespan ├── tests/ # ~40 unit + integration tests ├── demo/ # all demonstration & example files (kept separate from app code) │ ├── showcase/ # AI_SOFTWARE_SHOWCASE_FILE.md (the guided-demo document) │ └── examples/ # sample corpus: policy (TXT), FAQ (MD), employees (CSV) ├── scripts/ # smoke_test.py, seed_examples.py ├── docs/ # USAGE, ARCHITECTURE, API, CONFIGURATION, DEPLOYMENT, DEVELOPMENT_LOOP ├── START_SOFTWARE.bat # Windows one-click: setup + run + open dashboard ├── RUN_DEMO.bat / run_demo.py # one-click / CLI guided feature demo ├── Dockerfile, docker-compose.yml, Makefile, run.sh, run.bat └── requirements.txt, requirements-optional.txt, .env.example ``` ## 文档 | 文档 | 内容 | |-----|----------| | [docs/USAGE.md](docs/USAGE.md) | 平台操作：摄入、查询、dashboard、切换后端（包含中文操作手册） | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 分层、检索 pipeline、设计决策和权衡 | | [docs/API.md](docs/API.md) | 每个 endpoint 的请求/响应示例 | | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | 每个环境变量，包含演示与生产环境的配置对比 | | [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | Docker、compose 以及生产环境强化清单 | | [docs/DEVELOPMENT_LOOP.md](docs/DEVELOPMENT_LOOP.md) | 迭代构建日志、验证表，以及发现并修复的三个真实 bug | ## 测试 ``` python -m pytest # ~40 unit + integration tests python scripts/smoke_test.py # end-to-end boot + ingest + query ``` ## 技术栈 FastAPI · Pydantic v2 · SQLite · NumPy · rank-bm25 · pypdf · httpx · 原生 HTML/CSS/JS dashboard。可选：ChromaDB、sentence-transformers。专为本地 Ollama runtime（`qwen3-coder:30b`、`nomic-embed-text`）设计。 ## 致审阅者 / 面试简介 ## License 按“原样”提供，用于作品集和评估目的。

标签：AI风险缓解, AV绕过, ChromaDB, DLL 劫持, FastAPI, RAG系统, 大语言模型, 检索增强生成, 请求拦截, 运维监控, 运行时操纵, 逆向工具