hack/tools/scripts/llm-key-hunter/results/_cache/content/amy-ma-hh_gopher-vdp-rag.json

{"repo": "amy-ma-hh/gopher-vdp-rag", "files": {"README.md": {"7b48e28cf62087446e5caf1ee0790769f4e09c65": {"t": 1786068583.1848967, "n": 5686, "h": "eb68b80690cab20b", "c": "# Gopher VDP (Vector Data Platform) 🚀\n\n**Gopher VDP** 是一款基于 Go 语言的高性能 RAG（检索增强生成）知识库系统。本项目专为企业级私有知识库场景设计，通过 **双阶段检索架构** 与 **多级缓存机制**，解决了传统 AI 对话中常见的“幻觉”问题及高延迟瓶颈。\n\n---\n\n## 🛠️ 核心技术栈\n\n- **后端**: Go 1.25+ (Gin, GORM, pgvector) —— 采用典型的 Clean Architecture 思想。\n- **前端**: Vue 3, Vite, Tailwind CSS —— 响应式管理后台与流式对话界面。\n- **存储 + 监控**: \n  - **PostgreSQL (pgvector)**: 启用向量扩展，支持 HNSW/IVFFlat 等索引实现高维相似度检索。\n  - **Redis**: 缓存 Embedding 向量，减少 60% 以上的重复计算成本。\n  - **Prometheus + Grafana**: 采集 embedding/rerank hit ratio、candidate histogram、服务 QPS/p95/goroutines/memory，Grafana provisioning 目录提供预配置的 dashboard。\n- **模型层**: DeepSeek-V3 (LLM), BGE-M3 (Embedding), BGE-Reranker-v2 (Rerank)。\n\n---\n\n## 🔥 技术深度与亮点\n\n### 1. 双阶段检索流 (Recall & Rerank)\n为了解决向量检索由于语义偏移带来的“不相关”问题，本项目实现了标准的工业级检索链路：\n- **粗排 (Recall)**: 利用计算欧式距离/余弦相似度从千万级分片中快速召回前 10 条候选片段。\n- **精排 (Rerank)**: 引入交叉编码器 (Cross-Encoder) 模型对候选片段进行深度语义重评分，仅保留高置信度片段喂给 LLM，大幅提升回答准确率。\n\n### 2. 向量计算优化与 Redis 缓存策略\n- **哈希去重**: 对文本分片进行 **MD5 哈希采样**，在调用昂贵的 Embedding API 前先查询 Redis 缓存。\n- **性能提升**: 针对高频重复问题，响应速度从秒级提升至毫秒级，同时显著降低了 token 消耗。\n- **缓存稳态**: 精排前对候选片段 ID 做数值排序再生成缓存 Key，避免排序抖动导致缓存 miss。\n\n### 3. 分片上传与并发控制\n- **Chunk-by-Chunk 协议**: 实现了一套健壮的管理员分片上传逻辑，支持长文档的断点续传思维。\n- **原子性保证**: 在知识库更新时，通过数据库事务与预检接口确保了向量索引与原始文档的一致性。\n\n### 4. 实时流式溯源 (Source Citations)\n- **SSE 全双工通信**: 利用 Server-Sent Events 实现对话流与引用来源（Source JSON）的分离传输。\n- **精确锚点**: 前端动态解析 Markdown 中的 `[n]` 角标，并支持点击侧边栏实时预览对应分片的数据库原文。\n\n---\n\n## 📂 项目模块说明\n\n```text\n├── main.go                # 程序入口：负责 Gin 路由调度、RAG 全链路控制\n├── internal/\n│   ├── ai/                # AI 核心：封装 Embedding 缓存、Rerank 打分、SSE 流式接口\n│   ├── storage/           # 数据持久层：PostgreSQL 向量存储、Redis 客户端、Grafana/Prometheus 配置\n│   └── grafana/           # Grafana provisioning：数据源与仪表盘自动加载\n├── src/                   # 前端源码\n│   ├── components/Admin.vue    # 管理后台：分片上传、知识库管理与清理\n│   └── components/Chat.vue     # 用户端：流式交互、角标渲染、原文预览抽屉和历史列表\n└── .env                   # 环境变量：API Keys 与 数据库连接配置\n```\n## 🌟 2026-01-27 更新概要\n\n1. **对话卡片升级**：后端强制 `### 结论 / ### 依据 / ### 建议` 的 Markdown output，前端用 Markdown-it 渲染，展示 inline citations、状态提示与 fallback 标签，阅读体验更贴近 Review 文章。\n2. **引用粒度提升**：每段结尾自动出现 `[#N]` 引用，同时底部引用行会列出 chunk index & similarity badge，可点击查看原文；知识库未命中时会触发 fallback SSE 事件，并提醒回答基于通用知识。\n3. **历史对话栏**：新增左侧历史列表（localStorage 持久化、最多 30 条），支持清空、收起/hover 自动展开、collapsed 图标 + tooltip，单击即可恢复当次问答。\n4. **观测链路扩展**：Prometheus 添加 embedding/rerank cache hit ratio、候选段数直方图，Grafana 面板展示 QPS/p95/goroutines/memory/cache 命中率；`node:20 npm run build` 已通过验证。\n5. **治理能力强化**：新增 request limiter、RBAC 中间件与 audit log 打点，管理接口仅允许 `X-Role: admin` 调用，同时记录操作审计，提高安全治理。\n\n## 🌟 2026-01-28 更新概要\n\n1. **统一登录/身份体验**：前端新增 `Login.vue` + `stores/auth.js`，集中管理 API Key 与 `X-Role`，统一填充请求头；未登录自动跳转 `/login`，管理员角色才可进入 `/admin`，普通用户可直接访问 `/` 对话。  \n2. **鉴权校验与验证接口**：后端新增 `/v1/verify`（公共路由），`role=admin` 时校验 API Key，`role=user` 时直接返回 ok，方便前端与 curl 快速验证；所有管理接口继续受 API Key + RBAC + 审计 + 限流保护。  \n3. **验证指引补充**：在 README 下方新增本地快速验证与监控启动命令，包含健康检查、鉴权验证、metrics 访问说明。\n4. **前端引用与预览体验**：行内引用/底部 chips 可点击溯源，预览支持关键词高亮（无匹配时高亮开头内容），过滤空段落、优化间距和 fallback 提示，让展示更整洁。\n\n## 🚀 项目核心架构优化 (2026-01-22)\n\n本项目针对 RAG（检索增强生成）系统在长文本处理、检索精度及交互性能上的痛点，实施了以下深度优化方案：\n\n### 1. 🧠 语义分块策略 (Semantic Chunking) \n* **痛点**：传统的固定长度分块（Fixed-size Chunking）容易切断上下文（如一句话被切成两半），导致向量检索时语义碎片化。\n* **方案**：引入了基于语义关联的分块算法。系统不再生硬地按字符数切割，而是通过 NLP 启发式规则（如句号、段落边界、语义相似度阈值）动态识别语义单元，确保每个 Chunk 包含完整的逻辑意图。\n* **收益**：\n    * **检索质量**：检索召回率（Recall）显著提升，AI 获取的上下文更加连贯。\n    * **减少幻觉**：由于避免了信息截断，AI 生成答案的准确度提升了约 40%。\n\n### 2. 🔗 物理回溯与语义检索双路径架构\n* **痛点**：向量检索在处理“上一句/下一句是什么”这类指令时，因语义向量极度接近而无法精准区分物理相邻片段。\n* **方案**：构建了基于 `ChunkIndex` 的物理回溯机制。系统解析上下文锚点（如 `[#1024]`），当检测到用户有物理位移需求时，直接通过 `SourceID` + `Index` 偏移量精确定位。\n* **收益**：\n    * **绝对精度**：将“邻居定位”准确率从模糊匹配提升至 **100% 物理精准匹配**。\n    * **响应提速**：物理路径绕过 Embedding 和向量库检索，实现毫秒级响应。\n\n### 3. 🛡️ 检索流边界异常保护与提示拦截\n* **痛点**：物理回溯到文档边界（Index < 0）时，系统往往会盲目切换到语义检索，导致 AI 引用无关资料。\n* **方案**：增加了物理边界拦截器。检测到 `targetIndex < 0` 时，手动注入“系统提示分片”并触发短路（Short-circuiting），阻止无效的向量检索。\n* **收益**：彻底解决了长文本翻页到底时的“幻觉引用”问题，增强了系统的逻辑可解释性。\n\n### 4. ⚡ Rerank 缓存稳定性与命中率加固\n* **痛点**：候选片段顺序的微调会导致 Rerank 缓存 Key 频繁抖动。\n* **方案**：在生成缓存 Key 前，对所有候选片段 ID 执行 **数值型强制排序 (Numerical Sort)**，确保 Key 只受内容集合影响，不受检索排序干扰。\n* **收益**：精排阶段的 Redis 缓存命中率显著提高，大幅度降低了 SiliconFlow 等精排 API 的调用成本。\n\n### 5. 🔄 双向关联异步预热 (Prefetching Engine)\n* **痛点**：用户连续追问时的 Embedding 请求会导致交互卡顿。\n* **方案**：利用 Goroutine 开发异步预热引擎。在返回当前答案的同时，后台静默预测并预加载物理邻居向量。\n* **收益**：将连续对话场景下的延迟感降至接近 0，极大提升了用户体验。\n\n## ⚙️ 部署 Grafana / Prometheus\n\n1. 设置 `.env` 中必需变量（例如 `API_KEY=change-me`、`DEEPSEEK_API_KEY=xxxxx`）。  \n2. 启动依赖：`docker compose up -d db redis`。  \n3. 启动应用 + 监控：`docker compose up -d app prometheus grafana`。  \n4. Grafana 自动注册 `Prometheus` 数据源并加载 `grafana/dashboards/gopher-vdp.json`。可通过 `http://localhost:3000` 。  \n5. Prometheus 可在 `http://localhost:9090/targets` 查看上市链接，指标页 `http://localhost:9090/graph` 查询 `http_requests_total` 或 `embedding_cache_hits_total`。\n\n## 🔐 快速验证（健康 / 鉴权 / Metrics）\n\n- 健康检查：`curl http://localhost:8080/health`，就绪检查：`curl http://localhost:8080/ready`。  \n- 鉴权验证：  \n  - 管理员：`curl -H \"X-API-Key: $API_KEY\" -H \"X-Role: admin\" http://localhost:8080/v1/verify`  \n  - 普通用户：`curl -H \"X-Role: user\" http://localhost:8080/v1/verify`  \n- 管理接口示例：`curl -H \"X-API-Key: $API_KEY\" -H \"X-Role: admin\" http://localhost:8080/v1/sources`  \n- 指标：`curl -H \"X-API-Key: $API_KEY\" http://localhost:8080/metrics`（若设置了 METRICS_ALLOWLIST 需满足来源 IP）。\n\n## 🧪 测试\n\n- 后端（容器内）：`docker compose exec app go test ./cmd/server`\n- 前端（本机）：  \n  1) `cd frontend && npm install`（首次需要）  \n  2) `npm run test`（Vitest + jsdom，覆盖 auth store 登录/登出/头部生成）  \n\n## 🔑 登录与角色说明\n\n- 管理员：在登录页输入 `.env` 中的 `API_KEY`，选择 “管理员”，通过 `/v1/verify` 后可访问 `/admin`。  \n- 普通用户：可不填 API Key，选择 “普通用户” 直接进入对话页（公共接口）。  \n- 所有请求头由前端 auth store 自动注入（`X-API-Key` / `Authorization` / `X-Role`），便于统一维护。"}}}}