毕昇Bisheng知识库与 RAG 管道深度解析三阶段处理架构、双路召回与异步任务实践【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng本文是毕昇开源 LLM 运维平台知识库模块src/backend/bisheng/knowledge/的技术指南。文章围绕文档上传、解析、向量化、检索的完整链路展开讲解 Load、Transform、Ingest 三阶段管道架构、Milvus 稠密向量 Elasticsearch 稀疏索引的双路召回策略以及 Celery Worker 驱动的异步任务机制。读完本文你将掌握毕昇知识库的领域模型与状态机、各类文档加载器与转换器的选型逻辑、混合检索组件的组合方式以及文件解析、重建、复制等异步任务的完整执行流程。1. 知识库模块定位知识库模块是毕昇平台的核心业务领域之一负责文档的上传、解析、向量化与检索。整个处理流程采用三阶段管道架构Load、Transform、Ingest文档内容同时写入 Milvus 稠密向量库和 Elasticsearch 稀疏索引实现语义检索与关键词检索的双路召回。异步文件处理由 Celery Worker 驱动通过knowledge_celery队列实现任务解耦。从目录结构看知识库模块遵循领域驱动设计DDD分层api/提供 REST 路由domain/承载实体、服务与仓储抽象rag/存放管道实现worker/knowledge/存放 Celery 异步任务。2. 领域模型2.1 Knowledge 实体Knowledge实体knowledge/domain/models/knowledge.py是知识库的核心聚合根基于SQLModelSerializable建模主要字段如下字段类型说明user_idint创建者用户 IDtenant_idint租户 ID默认 1用于多租户隔离namestr知识库名称1-200 字符typeint知识库类型取值见KnowledgeTypeEnumdescriptionstr描述modelstrEmbedding 模型 ID支持 int 自动转 strcollection_namestrMilvus Collection 名称index_namestrElasticsearch 索引名称stateint知识库状态取值见KnowledgeStateauth_typeAuthTypeEnum权限类型PUBLIC / PRIVATE / APPROVALmetadata_fieldsList[Dict]用户自定义元数据字段配置is_releasedbool是否发布到知识广场is_sharedbool是否作为 Root 资源共享给子租户F017镜像 FGA shared_with tuplesauto_tag_enabled/auto_tag_library_idbool / int是否启用自动标签及绑定的标签库值得注意的实现细节Knowledge.model字段在赋值前会经过convert_model校验器将 int 类型的模型 ID 统一转为字符串metadata_fields使用JsonType列存储KnowledgeDao提供了同步与异步async_/a前缀两套 DAO 方法并在aget_user_knowledge等接口中支持基于游标的 keyset 分页F027见_apply_keyset_where。2.2 知识库类型KnowledgeTypeEnum枚举值数值说明NORMAL0文档知识库QA1问答知识库PRIVATE2工作台个人知识库SPACE3知识空间2.3 知识库状态KnowledgeState枚举值数值说明UNPUBLISHED0未发布PUBLISHED1已发布正常状态也是默认值COPYING2复制中REBUILDING3重建中切换 Embedding 模型时触发FAILED4重建失败2.4 KnowledgeFile 实体KnowledgeFile实体knowledge/domain/models/knowledge_file.py记录知识库中每个文件的处理状态主要字段字段类型说明knowledge_idint所属知识库 IDfile_namestr文件名DB 列最大 500 字符file_typeint0 目录1 文件file_sourcestr来源upload / channel / space_upload / audio_transcript / video_transcript / web_linkmd5str文件 MD5用于去重parse_typestr解析方式local / etl4lm / un_etl4lm / mineru / paddle_ocr / unssplit_rulestr分块规则 JSONstatusint处理状态取值见KnowledgeFileStatusobject_namestrMinIO 中的源文件对象名preview_file_object_namestr预览文件对象名bbox_object_namestrbbox 文件对象名用于文档定位thumbnailsstr文件缩略图对象名abstractstrLLM 提取的文档摘要user_metadataDict用户自定义元数据值JsonType 列remarkstr错误信息或备注DB 列最大 4096 字符写入时自动截断simhash/similar_statusstr / int相似文件检测64 位 SimHash 与去重状态ParseType枚举比文档描述的更丰富local表示本地解析uns表示 UNS 服务统一转 PDF 解析etl4lm表示带版面分析的 ETL4LM 解析含 bboxun_etl4lm表示无 bbox 的解析此外还有mineru与paddle_ocr。文件来源FileSource也已扩展出音视频转写与网页链接等新来源。2.5 文件处理状态KnowledgeFileStatus枚举值数值说明PROCESSING1解析中SUCCESS2解析成功FAILED3解析失败REBUILDING4重建中WAITING5排队等待默认初始状态TIMEOUT6解析超时超过 24 小时VIOLATION7内容安全违规内容审核转换器可触发2.6 QAKnowledgeQAKnowledge实体QAKnowledgeBase同文件用于问答型知识库存储问答对questions问题列表JSON 数组带校验器强制为 listanswers答案文本list 自动序列化为 JSON 字符串source来源标识0未知1手动2审核3API4批量导入statusQA 状态0禁用1启用2处理中3插入失败默认 12.7 元数据字段MetadataFieldType知识库支持为文件定义自定义元数据字段字段类型包括STRING、NUMBER、TIME枚举定义于 knowledge.py且实现大小写不敏感匹配。元数据值存储在KnowledgeFile.user_metadata中同时同步到 Milvus 和 Elasticsearch 中支持基于元数据的过滤检索。在检索与列表场景中KnowledgeFileDao.filter_file_by_metadata_fields会针对 MySQL 生成基于 JSON 路径表达式的原生 SQL 过滤条件对达梦DaMeng等其他方言则在 Python 内存中完成过滤。3. DDD 分层结构知识库模块采用领域驱动设计DDD目录结构如下与实际源码对应knowledge/ api/ router.py # 路由导出knowledge_router, qa_router, knowledge_space_router endpoints/ knowledge.py # 文档知识库 API knowledge_space.py # 知识空间 API qa.py # 问答知识库 API domain/ models/ knowledge.py # Knowledge 实体 KnowledgeDao knowledge_file.py # KnowledgeFile / QAKnowledge 实体 DAO schemas/ # 请求/响应 Pydantic Schema services/ knowledge_service.py # 核心业务逻辑 knowledge_file_service.py # 文件级操作元数据修改等 knowledge_space_service.py # 知识空间业务逻辑 knowledge_permission_service.py # 权限校验 knowledge_audit_telemetry_service.py # 审计与遥测 knowledge_metadata_service.py # 元数据字段管理 repositories/ interfaces/ knowledge_repository.py # 知识库仓储接口 knowledge_file_repository.py # 文件仓储接口 knowledge_rag.py # KnowledgeRag向量存储初始化工具类 rag/ # RAG 管道实现 base_file_pipeline.py # 文件管道基类FileExtensionMap 映射表 knowledge_file_pipeline.py # 知识库文件管道 preview_file_pipeline.py # 预览文件管道 milvus_factory.py # Milvus 实例工厂 elasticsearch_factory.py # Elasticsearch 实例工厂 pipeline/ base.py # BasePipeline / NormalPipeline types.py # PipelineStage / PipelineConfig / PipelineResult loader/ # 文档加载器pdf/word/ppt/txt/html/excel/ofd/media 等 transformer/ # 文档转换器摘要/分块/缩略图/预览缓存等模型层还包含knowledge_document.py、knowledge_document_version.py文件版本管理、knowledge_space_file.py知识空间文件、knowledge_space_tag_library.py自动标签库等扩展实体。4. RAG 管道架构4.1 整体流程4.2 管道阶段定义管道通过PipelineStage枚举pipeline/types.py控制执行深度支持在任意阶段提前终止阶段枚举值说明LOAD1仅加载源文档不做任何转换TRANSFORMER2完成所有转换但不写入向量库INGEST10完整管道包括写入向量存储默认PipelineConfig通过stop_at字段指定停止阶段默认INGESTPipelineResult返回阶段标记、文档列表与耗时duration_seconds。4.3 管道执行流程NormalPipelinepipeline/base.py是标准执行器同时支持同步和异步模式run/arun异步模式通过asyncio.to_thread或原生aload/atransform_documents/aadd_documents实现调用loader.load()或aload()将源文件解析为List[Document]依次执行各transformer.transform_documents(docs)进行文档转换若stop_at TRANSFORMER则在此返回遍历所有vectorstore调用add_documents(docs)或aadd_documents写入向量存储返回PipelineResult包含阶段标记、文档列表和耗时BaseFilePipelinebase_file_pipeline.py封装了文件类型到加载器/转换器的映射关系。run()方法创建临时目录根据文件扩展名查找FileExtensionMap动态初始化对应的 Loader 和 Transformer 链然后交由NormalPipeline执行。若扩展名不在映射表中则抛出KnowledgeFileNotSupportedError。KnowledgeFilePipeline继承BaseFilePipeline绑定KnowledgeFile数据库记录负责从 MinIO 下载源文件并构造文件元数据文档 ID、知识库 ID、上传者、更新者、时间戳、用户自定义元数据等。另有PreviewFilePipeline用于临时解析场景不上传提取图片_get_image_object_dir返回 None。5. 文档加载器5.1 文件类型映射FileExtensionMap定义了每种文件扩展名对应的加载器和转换器初始化方法比文档所列更全含 OFD、WPS 及音视频文件扩展名加载器说明pdf_init_pdf_loader根据配置选择解析引擎见下文ofd_init_ofd_loaderOFD 文件先转 PDF 再委托 PDF 加载器doc, docx_init_word_loaderWord 文档加载BishengWordLoader/ 分层HierarchicalWordLoaderppt, pptx_init_ppt_loaderPowerPoint 加载BishengPptLoader支持按页分块txt, md_init_txt_loader纯文本 / MarkdownBishengTextLoader/HierarchicalMarkdownLoaderhtml, htm_init_html_loaderHTML 页面BishengHtmlLoaderxlsx, xls, csv, et_init_excel_loader/_init_xcreate_loader表格文件使用独立的 Excel 转换链wps, dps_init_xcreate_loader金山格式XinChuangFormatterLoaderpng, jpg, jpeg, bmp_init_image_loader图片复用 PDF 解析引擎做 OCRmp3, wav, m4a, aac, flac, ogg_init_audio_loader音频转写BishengMediaLoadermp4, mov, avi, mkv, webm_init_video_loader视频转写BishengMediaLoader所有加载器继承BaseBishengLoaderpipeline/loader/base.py统一接收file_path、file_metadata、file_extension、tmp_dir等参数输出 LangChainDocument列表。加载器还维护bbox_list文本区域坐标信息和local_image_dir提取的图片目录供后续转换器使用。BaseFilePipeline还内置了分块模式决策逻辑split_mode支持auto与hierarchical其中 hierarchical 模式仅对 md/doc/docx 生效hierarchical_file_extspptx 在 auto 模式下启用按页分块ppt_page_split_exts。get_splitter_kwargs()会依据split_rule构造分块参数其中 auto 模式下若未显式指定chunk_overlap则默认置为 0。5.2 PDF 解析引擎PDF 文件的加载器通过KnowledgeConf.loader_provider配置项动态选择选择逻辑位于BaseFilePipeline._build_pdf_loader()单一事实来源OFD 转 PDF 后也走此路径引擎配置值类说明ETL4LMetl4lmEtl4lmLoader默认引擎外部文档解析服务支持版面分析和公式识别超时 600 秒MineRUmineruMineruLoader替代解析服务超时 60 秒支持自定义 HeadersPaddleOCRpaddle_ocrPaddleOcrLoader基于 OCR 的解析适合扫描件支持认证 Token本地解析无配置LocalPdfLoader兜底方案使用本地 PDF 库直接解析解析引擎的选择逻辑按配置的loader_provider值匹配且要求对应引擎的 URL 非空否则回退到本地解析LocalPdfLoader。图片文件png/jpg/jpeg/bmp复用 PDF 解析引擎进行 OCR如果回退到本地解析器则抛出KnowledgeFileNotSupportedError异常。各引擎均透传filter_page_header_footer是否过滤页眉页脚等分块规则参数。KnowledgeConf还提供supports_image属性判断当前 provider 是否能解析图片。5.3 解析引擎配置配置位于 core/config/settings.pyKnowledgeConf、Etl4lmConf、MineruConf、PaddleOcrConf通过config.yaml的knowledge段加载knowledge: loader_provider: etl4lm # 可选: etl4lm, mineru, paddle_ocr etl4lm: url: http://... timeout: 600 # etl4lm 服务请求超时秒 ocr_sdk_url: http://... # etl4lm ocr sdk 服务地址 mineru: url: http://... timeout: 60 headers: {} request_kwargs: {} paddle_ocr: url: http://... timeout: 60 auth_token: 各配置模型均有默认值如Etl4lmConf.timeout默认 600、loader_provider默认etl4lm字段缺省时使用默认值。6. 文档转换器转换器位于knowledge/rag/pipeline/transformer/按顺序组成处理链每个转换器实现 LangChain 的BaseDocumentTransformer接口转换器类说明摘要提取AbstractTransformer利用 LLM 为文档生成摘要可通过no_summary参数跳过附件/图片处理ExtraFileTransformer处理文档中的内嵌图片上传到 MinIO可通过retain_images控制是否保留内容安全ContentSafetyTransformer内容安全审核命中违规时可将文件状态置为 VIOLATION缩略图生成ThumbnailTransformer为文档生成缩略图可通过need_thumbnail参数控制文本分块SplitterTransformer使用ElemCharacterTextSplitter进行文本切分预览缓存PreviewCacheTransformer将解析结果写入 Redis 缓存供前端预览使用分层分块HierarchicalSplitterTransformer基于文档结构的层级分块配合分层加载器编码检测 / SimHashFileEncodingTransformer/SimHashTransformer文件编码识别与相似文件去重6.1 摘要提取AbstractTransformertransformer/abstract.py通过 LLM 为文档生成摘要并写入document.metadata[abstract]与KnowledgeFile.abstract字段。其默认系统提示词内置文档摘要专家角色支持针对报告、制度、合同、会议纪要、产品说明等文档类型自适应摘要风格若知识库配置了自定义abstract_prompt则优先使用。摘要提取属于尽力而为的增强操作——LLM 调用失败超时、审核拒绝、模型配置异常只记录告警日志并置空摘要不会导致文件解析失败。实现上使用 LangChain 的SystemMessage/HumanMessage消息 API 直接调用 LLM并在落库前通过parse_document_title清理模型输出的 think 标签与代码块标记。6.2 文本分块SplitterTransformertransformer/splitter.py是管道中的关键转换步骤核心参数separator自定义分隔符列表separator_rule分隔符规则正则chunk_size分块大小默认 1000 字符chunk_overlap分块重叠默认 100 字符分块使用bisheng_langchain.text_splitter.ElemCharacterTextSplitteris_separator_regexTrue。分块完成后每个 chunk 会附带chunk_index序号、bbox区域坐标 JSON来自chunk_bboxes、page所在页码等元数据。单个 chunk 的文本长度上限为 10000 字符max_chunk_limit超出则抛出KnowledgeFileChunkMaxError异常。6.3 Excel 专用转换链Excel 类文件xlsx/xls/csv/et使用独立的转换链_init_excel_transformers跳过附件处理、缩略图和文本分块步骤仅执行摘要提取和预览缓存。这是因为表格数据的分块逻辑由ExcelLoader在加载阶段直接完成按行切片处理——ExcelLoader接收header_rows表头起始/结束行与data_rows每次切片行数参数来自split_rule.excel_rule。7. 向量存储策略知识库采用双向量存储架构文档同时写入 Milvus 和 Elasticsearch实现混合检索。底层连接配置见 docker/bisheng/config/config.yaml 的vector_stores段vector_stores: milvus: connection_args: !env ${BS_MILVUS_CONNECTION_ARGS} is_partition: !env ${BS_MILVUS_IS_PARTITION} partition_suffix: !env ${BS_MILVUS_PARTITION_SUFFIX} elasticsearch: url: !env ${BS_ELASTICSEARCH_URL} ssl_verify: !env ${BS_ELASTICSEARCH_SSL_VERIFY}7.1 Milvus稠密向量用途语义检索基于 Embedding 相似度搜索每个知识库对应一个 CollectionKnowledge.collection_name向量由知识库绑定的 Embedding 模型生成Knowledge.model字段指定模型 ID文档元数据字段包括document_id、knowledge_id、chunk_index、page、bbox、user_metadata等初始化入口KnowledgeRag.init_knowledge_milvus_vectorstore()/MilvusFactory基于 langchain_milvus7.2 Elasticsearch稀疏索引用途关键词检索 / BM25 检索每个知识库对应一个 IndexKnowledge.index_name存储文本原文和元数据不含向量通过全文索引实现关键词匹配初始化入口KnowledgeRag.init_knowledge_es_vectorstore()/ElasticsearchFactory基于 langchain_elasticsearch区分AsyncElasticsearchStore与同步ElasticsearchStore7.3 KnowledgeRag 工具类KnowledgeRagdomain/knowledge_rag.py封装了向量存储的初始化逻辑提供以下核心方法方法说明init_knowledge_milvus_vectorstore初始化单个知识库的 Milvus 向量存储异步Embedding 缺省时经LLMService.get_bisheng_knowledge_embedding动态加载init_knowledge_es_vectorstore初始化单个知识库的 ES 存储异步get_multi_knowledge_vectorstore/get_multi_knowledge_vectorstore_sync批量初始化多个知识库的向量存储用于跨知识库检索返回{knowledge_id: {knowledge, milvus, es}}结构支持include_es/include_milvus开关与check_auth权限校验aexpand_with_root_shared多租户场景下将 Root 租户共享is_shared1的知识库 ID 并入子租户可检索集合F017以上方法均支持同步_sync后缀和异步两种调用方式。Embedding 模型通过LLMService根据Knowledge.model字段动态加载。批量检索入口get_multi_knowledge_vectorstore_sync在check_authTrue时通过KnowledgeDao.judge_knowledge_permission做读权限过滤委托PermissionService.list_accessible_ids对象类型knowledge_library关系can_read。8. 检索组件8.1 bisheng_langchain 检索器bisheng_langchain扩展包src/backend/bisheng_langchain/rag/提供了多种检索器实现用于 RAG 管道的检索阶段检索器类说明关键词检索KeywordRetriever基于 Elasticsearch 的关键词匹配检索基线向量检索BaselineVectorRetriever基于 Milvus 的标准向量相似度检索混合检索MixRetriever结合向量检索和关键词检索小块检索SmallerChunksVectorRetriever使用更小的分块进行精细检索返回时映射回原始大块集成检索EnsembleRetriever将多个检索器的结果进行融合排序8.2 BishengRagPipelineBishengRagPipelinebisheng_langchain/rag/bisheng_rag_pipeline.py是完整的 RAG 管道编排类通过 YAML 配置文件bisheng_langchain/rag/config/驱动整合以下组件Embedding 模型初始化LLM 模型初始化Milvus 向量存储连接Elasticsearch 关键词存储连接多检索器组合通过EnsembleRetriever融合QA Chain 问答生成8.3 评分与评估bisheng_langchain/rag/scoring/提供了 RAG 质量评估工具RagScoreragas_score.py基于 RAGAS 框架的自动化评估llama_index_score.py基于 LlamaIndex 的评估方法8.4 Rerankbisheng_langchain/rag/rerank/提供检索结果重排序功能在初步召回后对候选文档进行精排提升检索精度。9. 异步任务处理知识库的文件处理全部由 Celery Worker 异步执行任务定义位于 worker/knowledge/。9.1 Worker 队列与任务路由知识库任务使用knowledge_celery队列。config.yaml的celery_task.task_routers将bisheng.worker.knowledge.*全部路由到knowledge_celery队列knowledge_file_worker段还支持独立的 OCR 解析队列ocr_celery与公平调度fair_scheduler含分布式锁、队列并发上限、用户权重与在飞任务 TTL 等配置。启动命令celery -A bisheng.worker.main worker -l info -c 20 -P threads -Q knowledge_celery -n knowledge%h若启用了独立 OCR 队列需额外启动监听-Q ocr_celery的 worker否则 OCR 相关任务会一直积压。9.2 Celery 任务任务函数文件说明parse_knowledge_file_celeryfile_worker.py解析上传的文件构建向量索引retry_knowledge_file_celeryfile_worker.py重试失败的文件解析先删除旧向量再重新解析delete_knowledge_file_celeryfile_worker.py删除文件及其向量数据file_copy_celeryfile_worker.py复制知识库含文件、向量、ES 索引的完整复制rebuild_knowledge_celeryrebuild_knowledge_worker.py重建知识库索引切换 Embedding 模型时使用QA 相关任务qa.py问答对的处理和向量化9.3 文件解析流程parse_knowledge_file_celery的执行流程从数据库查询KnowledgeFile记录校验状态为 WAITING 或 PROCESSING将状态更新为 PROCESSING解析分块规则FileProcessBase调用process_file_task()执行完整的 Load - Transform - Ingest 管道任务完成后检查文件记录是否仍存在可能在解析期间被用户删除若不存在则清理向量数据9.4 知识库重建rebuild_knowledge_celery用于在切换 Embedding 模型后重建向量索引查询所有 SUCCESS 和 REBUILDING 状态的文件删除 Milvus 中的旧向量数据保留 ES 数据将文件状态更新为 REBUILDING从 ES 中读取已有的 chunk 文本使用新模型重新生成 Embedding 并写入 Milvus更新文件状态为 SUCCESS 或 FAILED更新知识库状态9.5 知识库复制file_copy_celery实现知识库的完整复制分页遍历源知识库的所有文件通过 MD5 跳过已存在的文件复制 MinIO 中的源文件、PDF 预览文件、bbox 文件复制 Milvus 向量数据按批次 1000 条插入复制 ES 索引数据更新知识库状态为 PUBLISHED10. 权限模型10.1 知识库权限类型AuthTypeEnum类型说明PUBLIC公开所有用户可访问默认PRIVATE私有仅创建者和被授权者可访问APPROVAL审批需申请后由管理者审批10.2 权限校验KnowledgePermissionServicedomain/services/knowledge_permission_service.py提供集中式权限校验ensure_knowledge_read_async校验知识库读权限ensure_knowledge_write_async校验知识库写权限底层通过UserPayload.async_access_check()实现基于 RBAC 模型用户 - 角色 - 资源访问控制RoleAccessDao。管理员角色role_id1拥有所有知识库的完整权限。从KnowledgeDao.judge_knowledge_permission的实现看当前读写判定已委托给 ReBAC 权限服务PermissionService.list_accessible_ids管理员仍返回全量集合。10.3 审计与遥测KnowledgeAuditTelemetryServicedomain/services/knowledge_audit_telemetry_service.py负责记录知识库操作的审计日志和遥测事件创建 / 删除知识库时记录审计日志通过遥测服务上报知识库创建、删除等关键事件11. 相关文档docs/architecture/01-architecture-overview.md — 系统整体架构概述src/backend/bisheng/core/config/settings.py — KnowledgeConf 配置定义src/backend/bisheng/knowledge/ — 知识库模块完整源码src/backend/bisheng_langchain/rag/ — RAG 检索器与评估工具src/backend/bisheng/worker/knowledge/ — Celery 异步任务定义docker/bisheng/config/config.yaml — 向量存储、对象存储与知识库任务调度配置【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
毕昇（Bisheng）知识库与 RAG 管道深度解析：三阶段处理架构、双路召回与异步任务实践
毕昇Bisheng知识库与 RAG 管道深度解析三阶段处理架构、双路召回与异步任务实践【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng本文是毕昇开源 LLM 运维平台知识库模块src/backend/bisheng/knowledge/的技术指南。文章围绕文档上传、解析、向量化、检索的完整链路展开讲解 Load、Transform、Ingest 三阶段管道架构、Milvus 稠密向量 Elasticsearch 稀疏索引的双路召回策略以及 Celery Worker 驱动的异步任务机制。读完本文你将掌握毕昇知识库的领域模型与状态机、各类文档加载器与转换器的选型逻辑、混合检索组件的组合方式以及文件解析、重建、复制等异步任务的完整执行流程。1. 知识库模块定位知识库模块是毕昇平台的核心业务领域之一负责文档的上传、解析、向量化与检索。整个处理流程采用三阶段管道架构Load、Transform、Ingest文档内容同时写入 Milvus 稠密向量库和 Elasticsearch 稀疏索引实现语义检索与关键词检索的双路召回。异步文件处理由 Celery Worker 驱动通过knowledge_celery队列实现任务解耦。从目录结构看知识库模块遵循领域驱动设计DDD分层api/提供 REST 路由domain/承载实体、服务与仓储抽象rag/存放管道实现worker/knowledge/存放 Celery 异步任务。2. 领域模型2.1 Knowledge 实体Knowledge实体knowledge/domain/models/knowledge.py是知识库的核心聚合根基于SQLModelSerializable建模主要字段如下字段类型说明user_idint创建者用户 IDtenant_idint租户 ID默认 1用于多租户隔离namestr知识库名称1-200 字符typeint知识库类型取值见KnowledgeTypeEnumdescriptionstr描述modelstrEmbedding 模型 ID支持 int 自动转 strcollection_namestrMilvus Collection 名称index_namestrElasticsearch 索引名称stateint知识库状态取值见KnowledgeStateauth_typeAuthTypeEnum权限类型PUBLIC / PRIVATE / APPROVALmetadata_fieldsList[Dict]用户自定义元数据字段配置is_releasedbool是否发布到知识广场is_sharedbool是否作为 Root 资源共享给子租户F017镜像 FGA shared_with tuplesauto_tag_enabled/auto_tag_library_idbool / int是否启用自动标签及绑定的标签库值得注意的实现细节Knowledge.model字段在赋值前会经过convert_model校验器将 int 类型的模型 ID 统一转为字符串metadata_fields使用JsonType列存储KnowledgeDao提供了同步与异步async_/a前缀两套 DAO 方法并在aget_user_knowledge等接口中支持基于游标的 keyset 分页F027见_apply_keyset_where。2.2 知识库类型KnowledgeTypeEnum枚举值数值说明NORMAL0文档知识库QA1问答知识库PRIVATE2工作台个人知识库SPACE3知识空间2.3 知识库状态KnowledgeState枚举值数值说明UNPUBLISHED0未发布PUBLISHED1已发布正常状态也是默认值COPYING2复制中REBUILDING3重建中切换 Embedding 模型时触发FAILED4重建失败2.4 KnowledgeFile 实体KnowledgeFile实体knowledge/domain/models/knowledge_file.py记录知识库中每个文件的处理状态主要字段字段类型说明knowledge_idint所属知识库 IDfile_namestr文件名DB 列最大 500 字符file_typeint0 目录1 文件file_sourcestr来源upload / channel / space_upload / audio_transcript / video_transcript / web_linkmd5str文件 MD5用于去重parse_typestr解析方式local / etl4lm / un_etl4lm / mineru / paddle_ocr / unssplit_rulestr分块规则 JSONstatusint处理状态取值见KnowledgeFileStatusobject_namestrMinIO 中的源文件对象名preview_file_object_namestr预览文件对象名bbox_object_namestrbbox 文件对象名用于文档定位thumbnailsstr文件缩略图对象名abstractstrLLM 提取的文档摘要user_metadataDict用户自定义元数据值JsonType 列remarkstr错误信息或备注DB 列最大 4096 字符写入时自动截断simhash/similar_statusstr / int相似文件检测64 位 SimHash 与去重状态ParseType枚举比文档描述的更丰富local表示本地解析uns表示 UNS 服务统一转 PDF 解析etl4lm表示带版面分析的 ETL4LM 解析含 bboxun_etl4lm表示无 bbox 的解析此外还有mineru与paddle_ocr。文件来源FileSource也已扩展出音视频转写与网页链接等新来源。2.5 文件处理状态KnowledgeFileStatus枚举值数值说明PROCESSING1解析中SUCCESS2解析成功FAILED3解析失败REBUILDING4重建中WAITING5排队等待默认初始状态TIMEOUT6解析超时超过 24 小时VIOLATION7内容安全违规内容审核转换器可触发2.6 QAKnowledgeQAKnowledge实体QAKnowledgeBase同文件用于问答型知识库存储问答对questions问题列表JSON 数组带校验器强制为 listanswers答案文本list 自动序列化为 JSON 字符串source来源标识0未知1手动2审核3API4批量导入statusQA 状态0禁用1启用2处理中3插入失败默认 12.7 元数据字段MetadataFieldType知识库支持为文件定义自定义元数据字段字段类型包括STRING、NUMBER、TIME枚举定义于 knowledge.py且实现大小写不敏感匹配。元数据值存储在KnowledgeFile.user_metadata中同时同步到 Milvus 和 Elasticsearch 中支持基于元数据的过滤检索。在检索与列表场景中KnowledgeFileDao.filter_file_by_metadata_fields会针对 MySQL 生成基于 JSON 路径表达式的原生 SQL 过滤条件对达梦DaMeng等其他方言则在 Python 内存中完成过滤。3. DDD 分层结构知识库模块采用领域驱动设计DDD目录结构如下与实际源码对应knowledge/ api/ router.py # 路由导出knowledge_router, qa_router, knowledge_space_router endpoints/ knowledge.py # 文档知识库 API knowledge_space.py # 知识空间 API qa.py # 问答知识库 API domain/ models/ knowledge.py # Knowledge 实体 KnowledgeDao knowledge_file.py # KnowledgeFile / QAKnowledge 实体 DAO schemas/ # 请求/响应 Pydantic Schema services/ knowledge_service.py # 核心业务逻辑 knowledge_file_service.py # 文件级操作元数据修改等 knowledge_space_service.py # 知识空间业务逻辑 knowledge_permission_service.py # 权限校验 knowledge_audit_telemetry_service.py # 审计与遥测 knowledge_metadata_service.py # 元数据字段管理 repositories/ interfaces/ knowledge_repository.py # 知识库仓储接口 knowledge_file_repository.py # 文件仓储接口 knowledge_rag.py # KnowledgeRag向量存储初始化工具类 rag/ # RAG 管道实现 base_file_pipeline.py # 文件管道基类FileExtensionMap 映射表 knowledge_file_pipeline.py # 知识库文件管道 preview_file_pipeline.py # 预览文件管道 milvus_factory.py # Milvus 实例工厂 elasticsearch_factory.py # Elasticsearch 实例工厂 pipeline/ base.py # BasePipeline / NormalPipeline types.py # PipelineStage / PipelineConfig / PipelineResult loader/ # 文档加载器pdf/word/ppt/txt/html/excel/ofd/media 等 transformer/ # 文档转换器摘要/分块/缩略图/预览缓存等模型层还包含knowledge_document.py、knowledge_document_version.py文件版本管理、knowledge_space_file.py知识空间文件、knowledge_space_tag_library.py自动标签库等扩展实体。4. RAG 管道架构4.1 整体流程4.2 管道阶段定义管道通过PipelineStage枚举pipeline/types.py控制执行深度支持在任意阶段提前终止阶段枚举值说明LOAD1仅加载源文档不做任何转换TRANSFORMER2完成所有转换但不写入向量库INGEST10完整管道包括写入向量存储默认PipelineConfig通过stop_at字段指定停止阶段默认INGESTPipelineResult返回阶段标记、文档列表与耗时duration_seconds。4.3 管道执行流程NormalPipelinepipeline/base.py是标准执行器同时支持同步和异步模式run/arun异步模式通过asyncio.to_thread或原生aload/atransform_documents/aadd_documents实现调用loader.load()或aload()将源文件解析为List[Document]依次执行各transformer.transform_documents(docs)进行文档转换若stop_at TRANSFORMER则在此返回遍历所有vectorstore调用add_documents(docs)或aadd_documents写入向量存储返回PipelineResult包含阶段标记、文档列表和耗时BaseFilePipelinebase_file_pipeline.py封装了文件类型到加载器/转换器的映射关系。run()方法创建临时目录根据文件扩展名查找FileExtensionMap动态初始化对应的 Loader 和 Transformer 链然后交由NormalPipeline执行。若扩展名不在映射表中则抛出KnowledgeFileNotSupportedError。KnowledgeFilePipeline继承BaseFilePipeline绑定KnowledgeFile数据库记录负责从 MinIO 下载源文件并构造文件元数据文档 ID、知识库 ID、上传者、更新者、时间戳、用户自定义元数据等。另有PreviewFilePipeline用于临时解析场景不上传提取图片_get_image_object_dir返回 None。5. 文档加载器5.1 文件类型映射FileExtensionMap定义了每种文件扩展名对应的加载器和转换器初始化方法比文档所列更全含 OFD、WPS 及音视频文件扩展名加载器说明pdf_init_pdf_loader根据配置选择解析引擎见下文ofd_init_ofd_loaderOFD 文件先转 PDF 再委托 PDF 加载器doc, docx_init_word_loaderWord 文档加载BishengWordLoader/ 分层HierarchicalWordLoaderppt, pptx_init_ppt_loaderPowerPoint 加载BishengPptLoader支持按页分块txt, md_init_txt_loader纯文本 / MarkdownBishengTextLoader/HierarchicalMarkdownLoaderhtml, htm_init_html_loaderHTML 页面BishengHtmlLoaderxlsx, xls, csv, et_init_excel_loader/_init_xcreate_loader表格文件使用独立的 Excel 转换链wps, dps_init_xcreate_loader金山格式XinChuangFormatterLoaderpng, jpg, jpeg, bmp_init_image_loader图片复用 PDF 解析引擎做 OCRmp3, wav, m4a, aac, flac, ogg_init_audio_loader音频转写BishengMediaLoadermp4, mov, avi, mkv, webm_init_video_loader视频转写BishengMediaLoader所有加载器继承BaseBishengLoaderpipeline/loader/base.py统一接收file_path、file_metadata、file_extension、tmp_dir等参数输出 LangChainDocument列表。加载器还维护bbox_list文本区域坐标信息和local_image_dir提取的图片目录供后续转换器使用。BaseFilePipeline还内置了分块模式决策逻辑split_mode支持auto与hierarchical其中 hierarchical 模式仅对 md/doc/docx 生效hierarchical_file_extspptx 在 auto 模式下启用按页分块ppt_page_split_exts。get_splitter_kwargs()会依据split_rule构造分块参数其中 auto 模式下若未显式指定chunk_overlap则默认置为 0。5.2 PDF 解析引擎PDF 文件的加载器通过KnowledgeConf.loader_provider配置项动态选择选择逻辑位于BaseFilePipeline._build_pdf_loader()单一事实来源OFD 转 PDF 后也走此路径引擎配置值类说明ETL4LMetl4lmEtl4lmLoader默认引擎外部文档解析服务支持版面分析和公式识别超时 600 秒MineRUmineruMineruLoader替代解析服务超时 60 秒支持自定义 HeadersPaddleOCRpaddle_ocrPaddleOcrLoader基于 OCR 的解析适合扫描件支持认证 Token本地解析无配置LocalPdfLoader兜底方案使用本地 PDF 库直接解析解析引擎的选择逻辑按配置的loader_provider值匹配且要求对应引擎的 URL 非空否则回退到本地解析LocalPdfLoader。图片文件png/jpg/jpeg/bmp复用 PDF 解析引擎进行 OCR如果回退到本地解析器则抛出KnowledgeFileNotSupportedError异常。各引擎均透传filter_page_header_footer是否过滤页眉页脚等分块规则参数。KnowledgeConf还提供supports_image属性判断当前 provider 是否能解析图片。5.3 解析引擎配置配置位于 core/config/settings.pyKnowledgeConf、Etl4lmConf、MineruConf、PaddleOcrConf通过config.yaml的knowledge段加载knowledge: loader_provider: etl4lm # 可选: etl4lm, mineru, paddle_ocr etl4lm: url: http://... timeout: 600 # etl4lm 服务请求超时秒 ocr_sdk_url: http://... # etl4lm ocr sdk 服务地址 mineru: url: http://... timeout: 60 headers: {} request_kwargs: {} paddle_ocr: url: http://... timeout: 60 auth_token: 各配置模型均有默认值如Etl4lmConf.timeout默认 600、loader_provider默认etl4lm字段缺省时使用默认值。6. 文档转换器转换器位于knowledge/rag/pipeline/transformer/按顺序组成处理链每个转换器实现 LangChain 的BaseDocumentTransformer接口转换器类说明摘要提取AbstractTransformer利用 LLM 为文档生成摘要可通过no_summary参数跳过附件/图片处理ExtraFileTransformer处理文档中的内嵌图片上传到 MinIO可通过retain_images控制是否保留内容安全ContentSafetyTransformer内容安全审核命中违规时可将文件状态置为 VIOLATION缩略图生成ThumbnailTransformer为文档生成缩略图可通过need_thumbnail参数控制文本分块SplitterTransformer使用ElemCharacterTextSplitter进行文本切分预览缓存PreviewCacheTransformer将解析结果写入 Redis 缓存供前端预览使用分层分块HierarchicalSplitterTransformer基于文档结构的层级分块配合分层加载器编码检测 / SimHashFileEncodingTransformer/SimHashTransformer文件编码识别与相似文件去重6.1 摘要提取AbstractTransformertransformer/abstract.py通过 LLM 为文档生成摘要并写入document.metadata[abstract]与KnowledgeFile.abstract字段。其默认系统提示词内置文档摘要专家角色支持针对报告、制度、合同、会议纪要、产品说明等文档类型自适应摘要风格若知识库配置了自定义abstract_prompt则优先使用。摘要提取属于尽力而为的增强操作——LLM 调用失败超时、审核拒绝、模型配置异常只记录告警日志并置空摘要不会导致文件解析失败。实现上使用 LangChain 的SystemMessage/HumanMessage消息 API 直接调用 LLM并在落库前通过parse_document_title清理模型输出的 think 标签与代码块标记。6.2 文本分块SplitterTransformertransformer/splitter.py是管道中的关键转换步骤核心参数separator自定义分隔符列表separator_rule分隔符规则正则chunk_size分块大小默认 1000 字符chunk_overlap分块重叠默认 100 字符分块使用bisheng_langchain.text_splitter.ElemCharacterTextSplitteris_separator_regexTrue。分块完成后每个 chunk 会附带chunk_index序号、bbox区域坐标 JSON来自chunk_bboxes、page所在页码等元数据。单个 chunk 的文本长度上限为 10000 字符max_chunk_limit超出则抛出KnowledgeFileChunkMaxError异常。6.3 Excel 专用转换链Excel 类文件xlsx/xls/csv/et使用独立的转换链_init_excel_transformers跳过附件处理、缩略图和文本分块步骤仅执行摘要提取和预览缓存。这是因为表格数据的分块逻辑由ExcelLoader在加载阶段直接完成按行切片处理——ExcelLoader接收header_rows表头起始/结束行与data_rows每次切片行数参数来自split_rule.excel_rule。7. 向量存储策略知识库采用双向量存储架构文档同时写入 Milvus 和 Elasticsearch实现混合检索。底层连接配置见 docker/bisheng/config/config.yaml 的vector_stores段vector_stores: milvus: connection_args: !env ${BS_MILVUS_CONNECTION_ARGS} is_partition: !env ${BS_MILVUS_IS_PARTITION} partition_suffix: !env ${BS_MILVUS_PARTITION_SUFFIX} elasticsearch: url: !env ${BS_ELASTICSEARCH_URL} ssl_verify: !env ${BS_ELASTICSEARCH_SSL_VERIFY}7.1 Milvus稠密向量用途语义检索基于 Embedding 相似度搜索每个知识库对应一个 CollectionKnowledge.collection_name向量由知识库绑定的 Embedding 模型生成Knowledge.model字段指定模型 ID文档元数据字段包括document_id、knowledge_id、chunk_index、page、bbox、user_metadata等初始化入口KnowledgeRag.init_knowledge_milvus_vectorstore()/MilvusFactory基于 langchain_milvus7.2 Elasticsearch稀疏索引用途关键词检索 / BM25 检索每个知识库对应一个 IndexKnowledge.index_name存储文本原文和元数据不含向量通过全文索引实现关键词匹配初始化入口KnowledgeRag.init_knowledge_es_vectorstore()/ElasticsearchFactory基于 langchain_elasticsearch区分AsyncElasticsearchStore与同步ElasticsearchStore7.3 KnowledgeRag 工具类KnowledgeRagdomain/knowledge_rag.py封装了向量存储的初始化逻辑提供以下核心方法方法说明init_knowledge_milvus_vectorstore初始化单个知识库的 Milvus 向量存储异步Embedding 缺省时经LLMService.get_bisheng_knowledge_embedding动态加载init_knowledge_es_vectorstore初始化单个知识库的 ES 存储异步get_multi_knowledge_vectorstore/get_multi_knowledge_vectorstore_sync批量初始化多个知识库的向量存储用于跨知识库检索返回{knowledge_id: {knowledge, milvus, es}}结构支持include_es/include_milvus开关与check_auth权限校验aexpand_with_root_shared多租户场景下将 Root 租户共享is_shared1的知识库 ID 并入子租户可检索集合F017以上方法均支持同步_sync后缀和异步两种调用方式。Embedding 模型通过LLMService根据Knowledge.model字段动态加载。批量检索入口get_multi_knowledge_vectorstore_sync在check_authTrue时通过KnowledgeDao.judge_knowledge_permission做读权限过滤委托PermissionService.list_accessible_ids对象类型knowledge_library关系can_read。8. 检索组件8.1 bisheng_langchain 检索器bisheng_langchain扩展包src/backend/bisheng_langchain/rag/提供了多种检索器实现用于 RAG 管道的检索阶段检索器类说明关键词检索KeywordRetriever基于 Elasticsearch 的关键词匹配检索基线向量检索BaselineVectorRetriever基于 Milvus 的标准向量相似度检索混合检索MixRetriever结合向量检索和关键词检索小块检索SmallerChunksVectorRetriever使用更小的分块进行精细检索返回时映射回原始大块集成检索EnsembleRetriever将多个检索器的结果进行融合排序8.2 BishengRagPipelineBishengRagPipelinebisheng_langchain/rag/bisheng_rag_pipeline.py是完整的 RAG 管道编排类通过 YAML 配置文件bisheng_langchain/rag/config/驱动整合以下组件Embedding 模型初始化LLM 模型初始化Milvus 向量存储连接Elasticsearch 关键词存储连接多检索器组合通过EnsembleRetriever融合QA Chain 问答生成8.3 评分与评估bisheng_langchain/rag/scoring/提供了 RAG 质量评估工具RagScoreragas_score.py基于 RAGAS 框架的自动化评估llama_index_score.py基于 LlamaIndex 的评估方法8.4 Rerankbisheng_langchain/rag/rerank/提供检索结果重排序功能在初步召回后对候选文档进行精排提升检索精度。9. 异步任务处理知识库的文件处理全部由 Celery Worker 异步执行任务定义位于 worker/knowledge/。9.1 Worker 队列与任务路由知识库任务使用knowledge_celery队列。config.yaml的celery_task.task_routers将bisheng.worker.knowledge.*全部路由到knowledge_celery队列knowledge_file_worker段还支持独立的 OCR 解析队列ocr_celery与公平调度fair_scheduler含分布式锁、队列并发上限、用户权重与在飞任务 TTL 等配置。启动命令celery -A bisheng.worker.main worker -l info -c 20 -P threads -Q knowledge_celery -n knowledge%h若启用了独立 OCR 队列需额外启动监听-Q ocr_celery的 worker否则 OCR 相关任务会一直积压。9.2 Celery 任务任务函数文件说明parse_knowledge_file_celeryfile_worker.py解析上传的文件构建向量索引retry_knowledge_file_celeryfile_worker.py重试失败的文件解析先删除旧向量再重新解析delete_knowledge_file_celeryfile_worker.py删除文件及其向量数据file_copy_celeryfile_worker.py复制知识库含文件、向量、ES 索引的完整复制rebuild_knowledge_celeryrebuild_knowledge_worker.py重建知识库索引切换 Embedding 模型时使用QA 相关任务qa.py问答对的处理和向量化9.3 文件解析流程parse_knowledge_file_celery的执行流程从数据库查询KnowledgeFile记录校验状态为 WAITING 或 PROCESSING将状态更新为 PROCESSING解析分块规则FileProcessBase调用process_file_task()执行完整的 Load - Transform - Ingest 管道任务完成后检查文件记录是否仍存在可能在解析期间被用户删除若不存在则清理向量数据9.4 知识库重建rebuild_knowledge_celery用于在切换 Embedding 模型后重建向量索引查询所有 SUCCESS 和 REBUILDING 状态的文件删除 Milvus 中的旧向量数据保留 ES 数据将文件状态更新为 REBUILDING从 ES 中读取已有的 chunk 文本使用新模型重新生成 Embedding 并写入 Milvus更新文件状态为 SUCCESS 或 FAILED更新知识库状态9.5 知识库复制file_copy_celery实现知识库的完整复制分页遍历源知识库的所有文件通过 MD5 跳过已存在的文件复制 MinIO 中的源文件、PDF 预览文件、bbox 文件复制 Milvus 向量数据按批次 1000 条插入复制 ES 索引数据更新知识库状态为 PUBLISHED10. 权限模型10.1 知识库权限类型AuthTypeEnum类型说明PUBLIC公开所有用户可访问默认PRIVATE私有仅创建者和被授权者可访问APPROVAL审批需申请后由管理者审批10.2 权限校验KnowledgePermissionServicedomain/services/knowledge_permission_service.py提供集中式权限校验ensure_knowledge_read_async校验知识库读权限ensure_knowledge_write_async校验知识库写权限底层通过UserPayload.async_access_check()实现基于 RBAC 模型用户 - 角色 - 资源访问控制RoleAccessDao。管理员角色role_id1拥有所有知识库的完整权限。从KnowledgeDao.judge_knowledge_permission的实现看当前读写判定已委托给 ReBAC 权限服务PermissionService.list_accessible_ids管理员仍返回全量集合。10.3 审计与遥测KnowledgeAuditTelemetryServicedomain/services/knowledge_audit_telemetry_service.py负责记录知识库操作的审计日志和遥测事件创建 / 删除知识库时记录审计日志通过遥测服务上报知识库创建、删除等关键事件11. 相关文档docs/architecture/01-architecture-overview.md — 系统整体架构概述src/backend/bisheng/core/config/settings.py — KnowledgeConf 配置定义src/backend/bisheng/knowledge/ — 知识库模块完整源码src/backend/bisheng_langchain/rag/ — RAG 检索器与评估工具src/backend/bisheng/worker/knowledge/ — Celery 异步任务定义docker/bisheng/config/config.yaml — 向量存储、对象存储与知识库任务调度配置【免费下载链接】bishengBISHENG is an open LLM devops platform for next generation Enterprise AI applications. Powerful and comprehensive features include: GenAI workflow, RAG, Agent, Unified model management, Evaluation, SFT, Dataset Management, Enterprise-level System Management, Observability and more.项目地址: https://gitcode.com/GitHub_Trending/bi/bisheng创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考