MaxKB 深度剖析：一套 RAG 智能问答平台的完整技术拆解

MaxKB 深度剖析一套 RAG 智能问答平台的完整技术拆解【免费下载链接】MaxKB MaxKB is an open-source platform for building enterprise-grade agents. 强大易用的开源企业级智能体平台。项目地址: https://gitcode.com/GitHub_Trending/ma/MaxKB把几十份产品手册丢进一个知识库然后直接问退货申请需要满足什么条件几秒后得到的不是搜索结果列表而是一段带出处的答案——这就是 MaxKB 的日常用法。它定位为企业级智能体平台核心价值是 RAG检索增强生成即先查资料再让大模型照着答问答、可视化工作流编排以及对接数十家大模型厂商的模型管理。下面不聊宣传语直接拆开看它用什么技术组合解决了什么问题一次提问的数据在内部是怎么流动的。技术选型每个组件都在解决一个具体问题MaxKB 的选型不是堆新而是每个问题都有对应解法全部可以从 pyproject.toml 和 ui/package.json 核对向量检索不想引入独立向量数据库→ PostgreSQL pgvector 扩展installer/init.sql 里只有一句CREATE EXTENSION vector业务数据和向量同库免去跨库一致性问题对话链路是多步骤串联问题改写→检索→生成→ Django 5.2.16 DRF 3.17.2 承载 API流程本身用 chat_pipeline 的步骤器实现每步一个抽象接口加一个默认实现文档解析、向量化耗时且可能中断→ Celery 5.5.3 Redis配合celery-once防重复任务模型厂商 API 差异巨大→ 统一走 LangChain 1.3.10 / LangGraph 1.2.6 的抽象外加自己一层 Provider 封装详见下文工作流画布需要拖拽式节点编辑→ 前端 Vue 3.5.13 LogicFlow 1.2.27流程图引擎 Element Plus 2.13.5构建用 Vite 6.2.4。一次提问的完整数据流跟着一句话从前端走到答案回来。用户在应用页提问后请求命中 chat_api.py 中的ChatAPI随后进入 pipeline_manage.py 定义的流水线四个步骤依次执行代码都在 chat_pipeline/stepreset_problem_step清理问题上下文generate_human_message_step调用 LLM 把用户口语化的问题补全成检索友好的文本比如把这个咋弄补成如何配置知识库相似度阈值search_dataset_step拿补全后的文本去 pg_vector.py 的query()做混合检索返回段落列表paragraph_listchat_step把问题 检索段落组装成提示词通过 LangChain 流式调用 LLM逐 token 经 SSE 推回前端。检索这一步最值得注意它不是简单的向量近邻。以混合检索为例blend_search.sql 先用余弦距离取出候选再叠加 PostgreSQL 全文检索的ts_rank_cd关键词分数-- 综合得分 向量相似度 关键词命中排名(归一化标志位32) (1 - vc.distance COALESCE(ts_rank_cd(e.search_vector, plainto_tsquery(simple, %s), 32), 0)) AS comprehensive_score候选规模被LEAST(top_n * 10, 500)硬性封顶防止 top_n 调大时全表扫描。写入侧同样埋了细节ts_vecto_util.py 会把知识库级术语表Termbase的自定义词注入 tsvector 分词解决内部黑话检索不到的问题。三个有辨识度的关键设计混合检索 按知识库切分的 HNSW 索引pg_vector.py里有一段很实战的注释当查询命中单个知识库时用knowledge_id xxx而不是knowledge_id__in条件因为后者用不上 PostgreSQL 的部分 HNSW 索引per-KB partial HNSW indexes。换言之索引是每个知识库一个查询必须精确到单个库才能走索引——多库场景就逐库查询再合并排序all_results.sort(...)那段。这是用查询路径上的几次额外循环换索引体积和构建速度的工程取舍。检索模式做成策略数组search_handle_list [EmbeddingSearch, KeywordsSearch, BlendSearch]前端传search_mode即切换新增模式只需实现ISearch两个方法。多模型抽象层20 厂商收敛成一个接口base_model_provider.py 定义了骨架IModelProvider厂商→ModelInfoManage模型清单→ModelInfo模型名 鉴权凭证类 模型实现类。impl/ 目录下有 20 多个厂商实现OpenAI、Anthropic、DeepSeek、智谱、Ollama、火山引擎等而ModelTypeConst把能力切成 9 种LLM、EMBEDDING、STT、TTS、IMAGE、TTI文生图、RERANKER重排、TTV/ITV视频。业务代码只调get_model(model_type, model_name, credential)具体是哪家厂商、哪个 SDK 完全被屏蔽。凭证敏感字段由BaseModelCredential.encryption_dict加密入库返回前端时脱敏为123******890样式。工作流引擎节点定义即 JSON应用不只是固定流水线还能变成图。默认工作流见 default_workflow.json——每个节点带type如search-dataset-node和properties.config.fields输入输出声明step_node/ 下有 146 个节点实现覆盖 LLM、条件分支、代码执行、知识库检索等。外部工具则通过 MCPModel Context Protocol让模型调用外部工具的标准协议依赖mcp1.28.1langchain-mcp-adapters0.3.0接入且工具执行被放进独立沙箱common/mcp/sandbox.py 与 installer/sandbox.c 配合代码类工具在隔离进程里跑避免一个恶意工具打穿整个服务。工程化部署、权限与异步流水线部署侧提供两套入口start-maxkb.sh 本地脚本或 Dockerfile 容器化Web 进程由 gunicorn 23.0.0 拉起django-db-connection-pool1.2.6解决 gunicorn 多 worker 下连接泄漏django-redis6.0.0承担会话与模型实例缓存MaxKBBaseModel.is_cache_model()允许模型对象跨请求复用。文档处理是典型的异步流水线上传后由 knowledge/task 下的 Celery 任务接手——pypdf 6.16.1 解 PDF、python-docx 解 Word、beautifulsoup4jieba 0.42.1 清洗切词分块结果批量bulk_create写入 Embedding 表_batch_save每轮调用is_the_task_interrupted()检查任务是否被用户取消取消即停不浪费算力。权限上走工作空间 资源映射模型system_manage/sql/ 里的get_user_resource_permission.sql等查询决定用户能看到哪些知识库/应用/模型外部调用则靠 application_api_key.py 的 API Key支持过期时间见迁移0007做入口鉴权。带得走的三点向量库不一定要专业pgvector 余弦距离 封顶候选数LEAST(top_n*10, 500) 按库切分 HNSW在单库规模内完全够用还省掉一套独立组件——代价是查询条件必须精确到分区键这个取舍值得在自己的索引设计里权衡。混合检索的融合公式可以直接抄1 - 余弦距离 ts_rank_cd(归一化)的线性叠加比向量/关键词二选一鲁棒得多尤其适合术语密集的内部文档。模型层用厂商→清单→实例三级抽象把 SDK 差异关在impl/目录里新增厂商不动业务代码再配 MCP 沙箱执行外部工具是让模型安全地动手的实用范式。若你基于 MaxKB 二次开发扩展方向也很清晰自定义ISearch接入重排模型、在 step_node 加领域节点、或把 Celery 换成本地任务队列做单机化部署。【免费下载链接】MaxKB MaxKB is an open-source platform for building enterprise-grade agents. 强大易用的开源企业级智能体平台。项目地址: https://gitcode.com/GitHub_Trending/ma/MaxKB创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考