基于SpringAI开发的通用RAG脚手框架，适配各种场景

RAG 业务落地开发指导本文面向后续把这套 RAG 能力接入业务系统的开发者重点回答三件事上游业务请求怎么进入 RAG。RAG 内部各组件怎么串起来。数据分别存到 MySQL、文件存储、向量库和搜索引擎的哪里。1. 总体边界独立工程保留的是一套完整 RAG 子系统不是简单 demo。业务系统 - RAG HTTP/API 层 - 模型/存储/知识库配置 - 文档入库 pipeline - 检索 pipeline - QA prompt 模型调用代码入口src/main/java/com/aizuda/snail/ai/ragforge/controller/RagForgeController.java这个 controller 只负责暴露接口和参数转换。真正可复用的业务边界在这些类RagDocumentService 接收文件/URL做去重、资源存储、文档元数据入库 DocumentPipeline 解析、切片、写 chunk、写向量库、写搜索引擎 RagSearchService 检索总入口 RagSearchPipeline 检索流水线编排 RagQAService 检索后拼 Prompt 并调用 Chat 模型 KnowledgeService 知识库配置管理 ModelFactory Chat / Embedding / Rerank 模型工厂 VectorStoreFactory 向量库工厂 SearchEngineFactory 搜索引擎工厂 ResourceService 原始文件存储2. 配置链路业务落地前要先准备四类配置。模型提供商 - 模型配置 - 存储实例 - 知识库2.1 模型提供商表snail_ai_model_provider作用记录提供商如 OpenAI、Ollama、Gemini 或内部兼容 OpenAI 协议的服务。关键字段id 提供商 ID provider_name 展示名称 provider_key 代码识别用 key如 openai is_enabled 是否启用2.2 模型配置表snail_ai_model_config作用记录具体模型实例。RAG 至少需要EMBEDDING 文档入库写向量、向量检索时使用 CHAT QA 阶段生成答案时使用 RERANKER 可选检索后重排时使用关键字段id 模型配置 ID业务配置里引用它 provider_id 所属提供商 model_key 真实模型名如 text-embedding-3-small model_type CHAT / EMBEDDING / RERANKER api_key 加密后的 key api_endpoint 模型服务地址 config_json 模型扩展参数如 dimensions、temperature、timeoutMs代码读取路径ModelFactory.getModel(modelConfigId) - ModelConfigHandler.getConfigInfo - snail_ai_model_config - 具体模型实现2.3 存储实例表snail_ai_store_instance作用把外部向量库和搜索引擎的连接信息配置化不写死在代码里。关键字段id 存储实例 ID category 1向量库2搜索引擎 type 1PG_VECTOR2MILVUS3ELASTICSEARCH4PG_FULLTEXT config 连接参数 JSON status 是否启用 is_default 是否默认向量库由VectorStoreFactory读取snail_ai_rag.vector_store_instance_id - snail_ai_store_instance.config - PGVector / Milvus / Elasticsearch 向量适配器搜索引擎由SearchEngineFactory读取snail_ai_rag.search_engine_instance_id - snail_ai_store_instance.config - Elasticsearch BM25 适配器2.4 知识库配置表snail_ai_rag作用这是 RAG 的主配置表后续所有入库和检索都以ragId为主线。关键字段id 知识库 ID也就是接口里的 ragId name 知识库名称 embedding_model_id 入库和向量检索使用的 Embedding 模型 rerank_model_id 默认 Rerank 模型 vector_store_instance_id 向量库存储实例 search_engine_enable 是否启用 BM25 搜索引擎 search_engine_instance_id 搜索引擎实例 config 切片、检索、问答参数 JSON dedup_strategy 文档去重策略 dedup_action 命中去重后的动作 upload_confirm 上传前是否二次确认config对应代码src/main/java/com/aizuda/snail/ai/persistence/rag/dataobject/RagConfigDO.java结构chunkParams 切片参数mode、maxChunkTokens、chunkOverlap、regex、smart 模型等 searchParams 检索参数resultCount、rerankEnabled、denseWeight、rrfK、threshold 等 modelParams QA 参数modelId、nearbySliceCount、prompt3. 文档入库上下游串联入口POST /demo/rag/document/upload-and-process POST /demo/rag/document/import-url-and-process业务上游只需要提供ragId 写入哪个知识库 file/url 文档来源 可选去重参数 dedupStrategy / dedupAction完整调用链RagForgeController - RagDocumentService.upload / importFromUrl - DocumentImportFactory - ResourceService - snail_ai_resource - snail_ai_rag_document(PENDING) - DocumentPipeline.processDocument - ResourceService.load(resourceId) - DocumentParserFactory - DocumentChunkingService - snail_ai_rag_chunk - VectorStoreFactory - 外部向量库 index: rag_{ragId} - SearchEngineFactory - 外部搜索引擎 index: rag_{ragId} - snail_ai_rag_document.status SUCCESS / FAILED3.1 原始文件怎么存原始文件不直接塞到snail_ai_rag_document.content。存储路径ResourceService.upload - LOCAL 或 MINIO - snail_ai_resource - snail_ai_rag_document.resource_id核心表snail_ai_resourceid 资源 ID storage_key 本地相对路径或对象存储 key original_name 原始文件名 file_size 文件大小 mime_type MIME 类型 storage_type LOCAL / MINIO access_url 预览或访问 URL biz_type DOCUMENT biz_id ragId creator_id 上传人可为空3.2 文档元数据怎么存表snail_ai_rag_document一份上传文档对应一行。关键字段id documentId rag_id 所属知识库 name 文件名 file_type pdf/docx/xlsx/txt/md/html 等 source_type UPLOAD / URL status 0PENDING 1PARSING 2PROCESSING 3SUCCESS 4FAILED error_msg 失败原因 chunk_count 切片数量 content_hash 原始内容 SHA-256用于文档级去重 resource_id 指向 snail_ai_resource.id推荐业务用法上传后返回 documentId 业务系统保存 documentId 与自身业务单据的关系 前端或后台轮询 document.status 判断是否处理完成 失败时展示 error_msg 并允许重试 processDocument3.3 切片怎么存表snail_ai_rag_chunk一份文档会拆成多行 chunk。关键字段id chunkId rag_id 所属知识库 document_id 所属文档 paragraph_index 段落序号 chunk_index 文档内切片序号 content 切片文本 token_count 估算 token 数 vector_id 外部向量库里的向量 ID content_hash chunk 文本 SHA-256用于 chunk 级向量复用为什么 MySQL 还要存content向量库和搜索引擎负责召回不负责业务主数据。 最终展示、拼 Prompt、权限过滤、来源展示都应回到 MySQL chunk/document 做补全。3.4 向量怎么存向量不存 MySQL存外部向量库。索引命名rag_{ragId}代码IndexNameBuilder.KNOWLEDGE.build(Map.of(ragId, ragId))写入内容id vectorId对应 snail_ai_rag_chunk.vector_id content chunk 文本 metadata ragId、documentId、chunkId vector embedding 后的向量关系snail_ai_rag_chunk.id - metadata.chunkId snail_ai_rag_chunk.vector_id - 向量库 document/vector id3.5 搜索引擎怎么存搜索引擎用于 BM25/关键词召回。当前实现使用 Elasticsearch。索引命名同样是rag_{ragId}写入内容id chunkId content chunk 文本 metadata ragId、documentId、chunkId注意search_engine_enablefalse 时不会写搜索引擎也不会走 BM25。 业务对编号、术语、错误码召回敏感时建议开启 BM25。4. 检索上下游串联入口POST /demo/rag/search请求{ragId:1,query:设备报警 E32 怎么处理,debug:true}完整调用链RagForgeController.search - RagSearchService.search - RagSearchPipeline - ConfigResolveHandler - QueryRewriteHandler - VectorSearchHandler - Bm25SearchHandler - HybridFusionHandler - RerankHandler - FinalizeHandler4.1 ConfigResolveHandler输入ragId读取snail_ai_rag snail_ai_rag.config输出到上下文knowledge searchParams modelParams query4.2 VectorSearchHandler读取knowledge.vector_store_instance_id knowledge.embedding_model_id searchParams.resultCount下游VectorStoreFactory - 外部向量库 rag_{ragId}输出vectorResults: ListSearchResult其中SearchResult.chunkId来自向量 metadata后面用于回查 MySQL。4.3 Bm25SearchHandler前提snail_ai_rag.search_engine_enable true读取knowledge.search_engine_instance_id searchParams.resultCount下游SearchEngineFactory - Elasticsearch rag_{ragId}输出bm25Results: ListSearchResult4.4 HybridFusionHandler作用融合向量召回和 BM25 召回。支持策略RRF 默认推荐按排名倒数融合比较稳定 WEIGHTED_SUM 按 denseWeight 做加权适合调参后固定业务场景配置来源snail_ai_rag.config.searchParams.fusionStrategy snail_ai_rag.config.searchParams.denseWeight snail_ai_rag.config.searchParams.rrfK4.5 RerankHandler作用用 Reranker 模型对融合后的候选重新排序。配置来源rerankEnabled rerankModelId enterRerankCount resultCount成本控制点只有前 enterRerankCount 个候选会送入 rerank。 最终只保留 resultCount 个结果。4.6 FinalizeHandler作用把召回结果变成可展示、可拼 Prompt 的最终结果。处理按 chunkId 回查 snail_ai_rag_chunk 按 documentId 回查 snail_ai_rag_document 补齐 content、documentName、documentId 按 nearbySliceCount 合并相邻切片 重排结果缓解 lost-in-the-middle5. 问答上下游串联入口POST /demo/rag/qa/stream完整调用链RagForgeController.qaStream - RagQAService.qaStream - snail_ai_rag.config.modelParams - RagSearchService.search - buildDocumentsText - buildSystemPrompt - ModelFactory.getModel(modelParams.modelId) - ChatModel.chatStreamModel - ResponseBodyEmitterPrompt 拼装规则modelParams.prompt 中必须保留 Documents RagQAService 会把检索结果拼成 documentsText然后替换 Documents示例请只根据以下参考资料回答用户问题。资料不足时明确说明不足不要编造。 Documents如果没有配置 prompt则默认使用请根据以下参考资料回答用户的问题 {documentsText}6. 最小落地表集docs/sql/snail_ai_schema.sql是从原项目带出的全量建表脚本里面包含 agent、memory、skill、openapi 等外围表。如果只落地 RAG最小核心表是snail_ai_model_provider snail_ai_model_config snail_ai_store_instance snail_ai_rag snail_ai_resource snail_ai_rag_document snail_ai_rag_chunk建议保留但不是 RAG 主链路强依赖snail_ai_user snail_ai_model_usage_stat可以裁剪的外围表snail_ai_agent* snail_ai_mcp_server snail_ai_skill* snail_ai_app snail_ai_client_node snail_ai_openapi_user memory 相关表如果裁剪表也要同步删除对应 mapper/PO 或限制 Spring 扫描范围否则 MyBatis/Spring 仍可能加载不需要的组件。7. 核心表关系snail_ai_model_provider 1 ---- N snail_ai_model_config snail_ai_store_instance 1 ---- N snail_ai_rag.vector_store_instance_id snail_ai_store_instance 1 ---- N snail_ai_rag.search_engine_instance_id snail_ai_model_config 1 ---- N snail_ai_rag.embedding_model_id snail_ai_model_config 1 ---- N snail_ai_rag.rerank_model_id snail_ai_model_config 1 ---- N snail_ai_rag.config.modelParams.modelId snail_ai_rag 1 ---- N snail_ai_rag_document snail_ai_rag_document 1 ---- N snail_ai_rag_chunk snail_ai_resource 1 ---- 1 snail_ai_rag_document.resource_id snail_ai_rag_chunk.vector_id ---- 外部向量库 rag_{ragId} snail_ai_rag_chunk.id ---- 外部搜索引擎 rag_{ragId} 文档 ID 或 metadata.chunkId当前 SQL 没有强制声明所有外键主要靠代码维护关系。这样便于迁移和清理外部索引但业务落地时要自己保证删除顺序。8. 写入一致性和失败处理文档状态0 PENDING 已创建文档行等待处理 1 PARSING 预留状态 2 PROCESSING 解析/切片/写外部索引中 3 SUCCESS 入库完成 4 FAILED 入库失败error_msg 保存原因写入顺序1. 原始文件写 Resource 2. 文档行写 RagDocumentPENDING 3. 解析文件 4. 切片 5. 写 RagChunk 6. 写向量库并回填 vector_id 7. 写搜索引擎 8. 更新 RagDocument 状态注意向量库写入失败会导致文档处理失败。 搜索引擎写入当前是非致命失败失败时向量检索仍可用但 BM25 召回会缺数据。 重跑同一 documentId 前会清理旧 chunk 和不再被引用的向量。业务落地建议上传接口只返回 documentId不要立即假设可检索。 前端轮询 document.status或后端加异步任务/消息通知。 失败时展示 error_msg并提供重新处理入口。9. 去重策略文档级去重字段snail_ai_rag_document.rag_id snail_ai_rag_document.name snail_ai_rag_document.content_hash策略0 NONE 不去重 1 BY_NAME 同库同名重复 2 BY_CONTENT 同库同内容重复 3 BY_NAME_OR_CONTENT 同名或同内容重复冲突动作0 REJECT 拒收并报错 1 SKIP 跳过本次上传返回旧文档 2 OVERWRITE 删除旧文档、chunk、向量和资源后重新入库Chunk 级去重snail_ai_rag_chunk.content_hash如果同一知识库里已有相同 chunk 且已有vector_id新 chunk 会复用旧vector_id避免重复 embedding。10. 业务系统接入建议10.1 上游业务对象和 ragId 的关系推荐业务侧建自己的关联表例如business_id rag_id document_id owner_id permission_scope created_atRAG 子系统只关心ragId/documentId/chunkId业务权限、租户、栏目、产品线建议放在业务侧或扩展 metadata。10.2 权限过滤放哪里可选位置上传前限制谁能写某个 ragId 检索前限制谁能查某个 ragId FinalizeHandler按 documentId/chunkId 做结果过滤 向量/搜索 metadata写入 tenantId、deptId、bizId 后在检索时过滤如果权限是强要求建议不要只在前端控制至少在 search/qa 入口和 FinalizeHandler 做后端校验。10.3 同步和异步当前 demo 的upload-and-process是同步处理方便学习完整链路。生产建议上传接口只写资源和文档行返回 documentId 后台任务异步调用 DocumentPipeline.processDocument(documentId) 查询接口根据 document.status 展示处理进度这样可以避免大文件解析、embedding、外部索引写入导致 HTTP 超时。10.4 业务可扩展点新增文件解析器 实现 DocumentParser并注册到 DocumentParserFactory 新增切片策略 实现 ChunkStrategy并接入 DocumentChunkingService 新增向量库 实现 SnailAiVectorStore并注册 VectorStoreFactory.REGISTER 新增搜索引擎 实现 SearchEngine并注册 SearchEngineFactory.REGISTER 新增模型提供商 实现 Chat/Embedding/Rerank 对应构建逻辑 检索后权限过滤 扩展 FinalizeHandler 答案引用格式 扩展 RagQAService.buildDocumentsText 或 buildSystemPrompt11. 落地检查清单上线前逐项确认MySQL 已执行核心表 SQL snail_ai_model_provider 已有提供商 snail_ai_model_config 已有 EMBEDDING/CHAT/RERANKER snail_ai_store_instance 已有向量库实例 需要 BM25 时已有搜索引擎实例 snail_ai_rag 已绑定 embeddingModelId/vectorStoreInstanceId/searchEngineInstanceId snail_ai_rag.config 已配置 searchParams/modelParams/chunkParams 原始文件存储 LOCAL/MINIO 可读写 向量库 rag_{ragId} 可写可查 搜索引擎 rag_{ragId} 可写可查 Prompt 模板保留 Documents 业务权限已在入口或 FinalizeHandler 处理本项目完整源码已上传至 Gitee需要的朋友可自行下载学习 源码地址https://gitee.com/ww_qq_22/ragforge