# YunRAGLib **Repository Path**: imagescience/yun-raglib ## Basic Information - **Project Name**: YunRAGLib - **Description**: No description available - **Primary Language**: Java - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-09 - **Last Updated**: 2026-10-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # YunRAGLib — 企业级 RAG 最小 MVP 基于 **Spring Boot 3 + Spring AI Alibaba (DashScope) + Tika + PgVector + Redis + MySQL** 的后端 RAG(检索增强生成)+ Function Calling Agent 服务,纯后端接口,无前端。 ## 功能模块 | 模块 | 说明 | 核心类 | |------|------|--------| | 文档上传解析 | multipart 上传,Tika 抽取 PDF/Word/PPT/Excel/TXT/MD 纯文本;支持单文档删除与清空知识库(`DELETE /api/documents`,高危) | `DocumentParseService` | | 文本分块 | 固定窗口+重叠、Markdown/PDF 标题感知、句子边界对齐、尾块合并(调参理由见 docs/CHUNKING.md) | `TextChunkService` | | Embedding 入库 | DashScope text-embedding-v2 批量向量化,PgVector 存储 | `EmbeddingService` / `ChunkVectorRepository` | | 检索召回 | 余弦相似度 Top-K 原始召回 + 质量评估(阈值/地板) | `RetrievalService` | | 检索质量评估与拒答 | 相关性过低(无候选/低于地板/未达阈值)时拒答而非强行生成,问答与诊断共用同一判定 | `RetrievalQualityEvaluator` | | 问答生成 | 会话记忆(Redis) + 编号参考资料拼 Prompt + qwen-plus 生成 | `RagChatService` | | 引用溯源 | 答案 [n] 编号 ↔ 召回块映射,返回文档名/块号/得分/原文片段 | `RagChatService#buildCitations` | | 召回诊断工具 | 输入问题输出 TopN 片段+分数+来源文档+质量判定,不调 LLM,用于调参排查 | `RetrievalDiagnosticsService` | | Function Calling Agent | 模型自主决定是否调用「知识库检索/订单查询/当前时间」三工具;Redis 多轮记忆+上下文隔离;详见 docs/AGENT.md | `AgentChatService` / `AgentConfig` | | Agent 护栏与兜底 | 输入敏感/注入拦截、工具参数校验、ToolContext 越权防护、工具异常兜底 | `SensitiveTopicGuard` / `agent.tool.*` / `AgentToolExceptionProcessor` | | Agentic RAG 多路检索 | 意图判断→Query改写→双路召回(向量+BM25)→RRF融合→Rerank重排→质量闸门→生成→Self-Reflection自检;全阶段可配置 + Trace 可观测 + 逐级降级;独立端点,受 `rag.agentic.enabled` 控制;详见 docs/AGENTIC_RAG.md | `AgenticRagService` / `RrfFusion` / `RerankService` / `SelfReflectionService` | | 向量存储抽象 | 支持PgVector/Milvus切换,通过配置 `rag.vector-store.type` 选择实现;详见 docs/VECTOR_DB_COMPARISON.md | `VectorStore` / `PgVectorStore` / `MilvusVectorStore` | ## 本地环境依赖清单 | 依赖 | 版本要求 | 用途 | 备注 | |------|---------|------|------| | JDK | **17+** | 运行环境 | Spring Boot 3 强制要求,JDK 8 无法编译 | | Maven | 3.6.3+ | 构建 | Boot 3 插件要求 | | PostgreSQL | 15+ | 业务库 | 需带 pgvector 扩展 | | pgvector 扩展 | 0.5+ | 向量存储/检索 | 推荐直接用官方镜像 | | Redis | 6+ | 会话记忆 | 单机即可 | | MySQL | 8.0+ | Agent 订单库 | 仅订单查询工具需要;不启动不影响应用启动(HikariCP 懒加载) | | DashScope API Key | - | 通义千问 + Embedding | [百炼控制台](https://bailian.console.aliyun.com/)申请 | ### 一键拉起中间件(Docker) ```bash # PostgreSQL + pgvector(官方镜像自带扩展) docker run -d --name rag-pg -p 5432:5432 \ -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=rag_db \ pgvector/pgvector:pg16 # Redis docker run -d --name rag-redis -p 6379:6379 redis:7-alpine # MySQL(Agent 订单库,可选) docker run -d --name rag-mysql -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=root -e MYSQL_DATABASE=order_db \ mysql:8.0 # Milvus(可选,替代PgVector,适合大规模向量检索) # 详细部署方案见 docs/VECTOR_DB_COMPARISON.md docker run -d --name rag-milvus -p 19530:19530 milvusdb/milvus:v2.3.0 ``` ## 启动步骤 1. **初始化数据库表** ```bash psql -h localhost -U postgres -d rag_db -f sql/schema.sql ``` ```bash # 存量库升级 Agentic RAG 关键词(BM25)索引:加列+生成列+GIN索引(幂等),随后调用回填端点 psql -h localhost -U postgres -d rag_db -f sql/migration/V2__agentic_keyword_index.sql ``` ```bash # Agent 订单库(MySQL,可选,仅订单查询工具需要) mysql -h localhost -uroot -p < sql/order_mysql.sql ``` 2. **配置 API Key**(不要写入代码库) ```bash # Windows CMD set DASHSCOPE_API_KEY=sk-你的key # PowerShell $env:DASHSCOPE_API_KEY="sk-你的key" ``` 数据库/Redis 非默认配置时,同样通过环境变量覆盖:`PG_HOST`、`PG_PORT`、`PG_DB`、`PG_USER`、`PG_PASSWORD`、`REDIS_HOST`、`REDIS_PORT`、`REDIS_PASSWORD`。 **切换向量存储**(可选,默认使用PgVector): ```bash # 使用Milvus作为向量存储 set RAG_VECTOR_STORE_TYPE=milvus set MILVUS_HOST=localhost set MILVUS_PORT=19530 set MILVUS_DIMENSION=1536 # 需与Embedding模型维度一致 ``` 向量存储选型指南与性能对比见 [docs/VECTOR_DB_COMPARISON.md](docs/VECTOR_DB_COMPARISON.md)。 3. **编译并启动** ```bash mvn clean package -DskipTests java -jar target/yun-rag-lib-1.0.0.jar # 或开发模式 mvn spring-boot:run ``` 4. **冒烟验证** ```bash # 上传文档 curl -X POST http://localhost:8080/api/documents/upload -F "file=@./docs/产品手册.pdf" # 问答 curl -X POST http://localhost:8080/api/chat -H "Content-Type: application/json" \ -d '{"sessionId":"demo-001","question":"产品的退货政策是什么?"}' # 召回诊断(查看 TopN 分数/来源/是否应作答,不触发 LLM) curl -X POST http://localhost:8080/api/diagnostics/retrieval -H "Content-Type: application/json" \ -d '{"query":"产品的退货政策是什么?","topK":5}' # Agent 对话(模型自主决定是否调用工具;越权/敏感拦截见 docs/AGENT.md) curl -X POST http://localhost:8080/api/agent/chat -H "Content-Type: application/json" \ -d '{"sessionId":"agent-001","message":"帮我查下订单 ORD20240101001 的状态","userId":"user_1001"}' # Agentic RAG 多路检索问答(返回答案+引用+全链路 Trace;详见 docs/AGENTIC_RAG.md) curl -X POST http://localhost:8080/api/rag/agentic/chat -H "Content-Type: application/json" \ -d '{"sessionId":"agentic-001","question":"SKU-1024 对应的商品退货政策是什么?"}' # 关键词索引存量回填(BM25 迁移后执行一次,幂等,可重复调用直到返回 0) curl -X POST http://localhost:8080/api/rag/agentic/admin/reindex ``` 评估对比(简单RAG vs Agentic RAG,仅用 Python3 标准库,无需 pip;先按真实知识库校准 golden_set.json): ```bash python3 scripts/eval_agentic_rag.py --golden scripts/golden_set.json --base-url http://localhost:8080 ``` 接口详情见 [docs/API.md](docs/API.md),架构与面试要点见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md),分块策略与调参见 [docs/CHUNKING.md](docs/CHUNKING.md),防幻觉 Prompt 模板见 [docs/prompt-template.md](docs/prompt-template.md),Function Calling Agent 设计与面试话术见 [docs/AGENT.md](docs/AGENT.md),Agentic RAG 多路检索链路(双路召回/RRF/Rerank/自检)设计、优缺点、场景、瓶颈与面试话术见 [docs/AGENTIC_RAG.md](docs/AGENTIC_RAG.md)。 OpenAPI 3.0 规范见 [docs/openapi.json](docs/openapi.json)(可导入 Swagger UI / Apifox);Postman 测试集合见 [docs/postman_collection.json](docs/postman_collection.json) + 环境 [docs/postman_environment.json](docs/postman_environment.json)(含断言脚本、docId/sessionId 自动提取、清空知识库二次确认拦截)。 运行分块与检索质量单元测试: ```bash mvn test -Dtest=TextChunkServiceTest mvn test -Dtest=RetrievalQualityEvaluatorTest,RetrievalDiagnosticsServiceTest # Agent(护栏/三工具/编排兜底) mvn test -Dtest=SensitiveTopicGuardTest,DateTimeToolTest,KnowledgeBaseToolTest,OrderQueryToolTest,AgentChatServiceTest # Agentic RAG(分词/融合/改写/重排/自检/编排,全部离线 mock) mvn test -Dtest=BigramTokenizerTest,RrfFusionTest,QueryRewriteServiceTest,RerankServiceTest,SelfReflectionServiceTest,AgenticRagServiceTest ``` ## 目录结构 ``` YunRAGLib ├── pom.xml ├── sql/schema.sql # PG 建表 + pgvector 索引 + BM25 关键词生成列/GIN ├── sql/order_mysql.sql # MySQL 订单库建表 + 样例数据 ├── sql/migration/V2__agentic_keyword_index.sql # 存量库升级:关键词(BM25)索引迁移 ├── scripts/ │ ├── golden_set.json # Agentic RAG 评估金标准集(带标注) │ └── eval_agentic_rag.py # 简单RAG vs Agentic RAG 对比评估(Python3 标准库) ├── docs/ │ ├── API.md # 接口文档 │ ├── openapi.json # OpenAPI 3.0 规范(全接口) │ ├── postman_collection.json # Postman 测试集合(v2.1,含断言) │ ├── postman_environment.json # Postman 环境变量 │ ├── ARCHITECTURE.md # 架构图 + 面试亮点/难点/踩坑 │ ├── AGENT.md # Function Calling Agent 设计 + 面试话术 │ ├── AGENTIC_RAG.md # Agentic RAG 多路检索链路设计 + 优缺点/场景/瓶颈 + 面试话术 │ └── VECTOR_DB_COMPARISON.md # 向量数据库选型对比(PgVector vs Milvus) + 面试笔记 └── src/main/ ├── java/com/yun/rag/ │ ├── YunRagApplication.java # 启动类 │ ├── common/ # 统一返回 Result / ResultCode │ │ └── exception/ # BizException + 全局异常捕获 │ ├── agent/ # AgentChatService 编排 + SensitiveTopicGuard 护栏 + 兜底处理器 │ │ └── tool/ # KnowledgeBaseTool / OrderQueryTool / DateTimeTool │ ├── config/ # AiConfig + AgentConfig + DataSourceConfig(双数据源) + RagProperties/AgentProperties/AgenticRagProperties │ ├── controller/ # DocumentController / ChatController / DiagnosticController / AgentController / AgenticChatController │ ├── memory/ # RedisChatMemoryRepository(实现 Spring AI SPI) │ ├── model/ │ │ ├── dto/ # ChatRequest / AgenticChatRequest(带校验注解) │ │ ├── entity/ # DocumentRecord / ChunkRecord / RetrievedChunk │ │ └── vo/ # ChatResponse / CitationVO / AgenticChatResponse / AgenticTraceVO ... │ ├── repository/ # DocumentRepository / ChunkKeywordRepository / ChatLogRepository / OrderRepository │ │ └── vector/ # VectorStore接口 / PgVectorStore / MilvusVectorStore(向量存储抽象) │ └── service/ # 解析/分块/向量化/检索/文档编排/RAG问答 │ └── agentic/ # BigramTokenizer / RrfFusion / IntentGate / QueryRewriteService / RerankService / SelfReflectionService / AgenticRagService └── resources/application.yml ``` ## 分层规范 - **Controller**:只做参数接收 + 校验(`@Valid`/`@Validated`)+ 调 Service + `Result` 包装; - **Service**:业务编排,异常统一抛 `BizException`,由 `GlobalExceptionHandler` 转 `Result`; - **Repository**:`JdbcTemplate` 数据访问,不含业务逻辑; - **参数校验**:DTO 用 record + jakarta.validation 注解;分页参数 `@Min/@Max`; - **敏感信息**:API Key、数据库密码全部走环境变量占位符。