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
基于SpringAI开发的通用RAG脚手框架，适配各种场景
发布时间：2026/5/16 1:47:11
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
相关文章
快速上手Redis
一、认识Redis Redis 是一个内存数据库，常用于缓存和高性能数据存储。特点： 数据存储在内存，读写速度快（毫秒级甚至微秒级）支持多种数据结构：String、Hash、List、Set、Sorted Set（ZSet&#…
量子电路仿真加速器QEA的FPGA实现与优化
1. 量子电路仿真加速器的核心挑战与现状量子计算正在重塑我们对计算能力的认知边界。作为一名长期从事高性能计算与量子仿真研究的工程师，我见证了量子仿真技术从理论探索到工程实现的完整历程。量子电路仿真作为验证量子算法正确性的关键技术，其核心痛点…
大模型KV缓存量化技术：原理、优化与实践
1. KV缓存量化技术背景解析在Transformer架构的大语言模型(LLM)推理过程中，注意力机制的计算复杂度与序列长度呈平方关系增长。为优化这一过程，现代LLM服务系统普遍采用KV缓存(Key-Value Cache)技术，将注意力层计算过的键值对存储在内存中供后…
生成式 AI 的未来是具有代理性的：你需要了解的信息
原文：towardsdatascience.com/the-future-of-generative-ai-is-agentic-what-you-need-to-know-01b7e801fa69
Arm Neoverse CMN-650架构与缓存一致性协议解析
1. Arm Neoverse CMN-650架构概述在现代多核处理器设计中，缓存一致性互连网络是决定系统扩展性和性能的关键组件。Arm Neoverse CMN-650作为第二代Coherent Mesh Network解决方案，采用了创新的分布式目录协议和优化的传输机制，能够支持多达12…
基于LLM的自主智能体框架zorro-agent：从规划到执行的实战指南
1. 项目概述与核心价值最近在折腾AI智能体开发的朋友，估计都绕不开一个核心问题：如何让一个智能体真正具备“自主行动”的能力，而不仅仅是一个被动的问答机器。无论是想做一个能自动处理工单的客服助手，还是一个能帮你分析数据并生…
AirLLM：用张量切片与动态调度在有限显存上运行大模型
1. 项目概述：当大模型遇见有限内存最近在折腾大语言模型本地部署的朋友，估计都绕不开一个“甜蜜的烦恼”：模型能力越来越强，参数量动辄数十亿甚至上百亿，随之而来的就是对显存的惊人消耗。想在自己的消费级显卡上跑一个…
谷歌搜索留痕怎么做？ 配合蜘蛛池提升80%存活率方法
四月份谷歌打击垃圾外链算法更新中，三百万个带有查询参数的页面遭到清除。单日某大型医疗器械外贸站页面收录量从15万跌至8千。存留的查询页面里，大多数采用了定时定量引导搜索引擎爬虫抓取的操作。服务器日志表明，维持60天不掉落的链接&…
基于Alpine的LNMP Docker镜像构建：从设计到实战部署
1. 项目概述：一个Docker镜像的诞生与价值最近在整理自己的开发环境时，发现一个高频需求：快速部署一个轻量级的、开箱即用的Web应用开发环境。这个环境需要包含基础的Web服务器、数据库、以及一些常用的调试工具。虽然市面上有现成的集成环境&…
SD-PPP：在Photoshop中开启智能设计革命的终极AI插件
SD-PPP：在Photoshop中开启智能设计革命的终极AI插件 【免费下载链接】sd-ppp A Photoshop AI plugin 项目地址: https://gitcode.com/gh_mirrors/sd/sd-ppp 你是否厌倦了在Photoshop和AI工具之间频繁切换，打断了创意的流畅性？SD-PPP正…
NomNom存档编辑器：解放你的《无人深空》游戏体验终极指南
NomNom存档编辑器：解放你的《无人深空》游戏体验终极指南 【免费下载链接】NomNom NomNom is the most complete savegame editor for NMS but also shows additional information around the data youre about to change. You can also easily look up each item i…
5个专业策略：构建企业级本地漏洞情报分析平台
5个专业策略：构建企业级本地漏洞情报分析平台 【免费下载链接】cve-search cve-search - a tool to perform local searches for known vulnerabilities 项目地址: https://gitcode.com/gh_mirrors/cv/cve-search 在当今复杂的网络安全环境中，快速…
贾子理论与AI时代文明竞争：从暴力计算到本质贯通的范式重构
贾子理论与AI时代文明竞争：从暴力计算到本质贯通的范式重构摘要本文基于贾子理论的文明竞争视角，揭示中美AI战略差异的本质并非技术参数较量，而是“暴力计算”与“本质贯通”两种文明范式的根本对立。美国依赖算力堆叠与资本逻辑追求技术霸权…
2026年AI大模型API中转平台排名揭晓，诗云API(ShiyunApi)脱颖而出成省心之选
在AI开发领域，如何接入模型厂商的官方API是一个绕不开的现实问题。对于海外开发者来说，注册、绑卡、调用，三步即可轻松搞定。然而，国内开发者却面临着跨境网络波动、外币支付门槛、发票合规需求以及多厂商Key碎片化管理等诸多“非…
基于飞书与OpenAI构建企业级AI助手：架构、部署与深度优化指南
1. 项目概述：当飞书遇上AI，一个企业级智能助手的诞生 最近在折腾一个挺有意思的项目，叫“ConnectAI-E/feishu-openai”。简单来说，它就是一个桥梁，把飞书这个强大的企业协作平台，和以ChatGPT为代表的OpenA…
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案
MPC-BE：基于DirectShow架构的专业级开源媒体播放解决方案 【免费下载链接】MPC-BE MPC-BE – универсальный проигрыватель аудио и видеофайлов для операционной системы Windows. 项目地址:…
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南
如何快速计算3D模型体积和重量：STL-Volume-Model-Calculator终极指南 【免费下载链接】STL-Volume-Model-Calculator STL Volume Model Calculator Python 项目地址: https://gitcode.com/gh_mirrors/st/STL-Volume-Model-Calculator 你是否曾经为3D打印项目…
通过Taotoken CLI工具一键配置团队开发环境与模型密钥
通过Taotoken CLI工具一键配置团队开发环境与模型密钥 1. CLI工具安装与基本使用 Taotoken提供的CLI工具可通过npm全局安装或直接使用npx运行。对于需要频繁使用CLI的团队，推荐全局安装： npm install -g taotoken/taotoken对于临时使用或项目级配置&a…