图_15文档索引模块设计
原生 Excalidraw 可编辑画布，基于 SuperMew-0.1.0。
视图类型： M7 文档索引模块主图。上级为 [[图_1项目设计|系统总图]]。
模块边界
- 输入是 M6 已保存的 file_path 与 filename；鉴权、文件保存、同名清理和 job 属于 M6。
- M7 提供解析、三级分块、父块存取、叶子向量化与写入组件；原版没有独立 IndexingService。
真实调用
- DocumentLoader 按格式读取，再清洗文本、补充来源 metadata 并三级分块。
- M6 在 documents.py 中拆出 parent_docs / leaf_docs，先调用父块存储，再调用向量写入。
- MilvusWriter 初始化集合，按批调用 EmbeddingService，再组装字段并 insert。
存储与约束
- L1/L2 写入 PG，逐项缓存 Redis；L3 写入 Milvus。
- 本地模型只生成 dense；BM25 sparse 由 Milvus 的服务端函数生成。
- 父块 commit 后才开始叶子写入；中途失败没有统一跨库回滚。
关联视图
- 图 03 是上传任务的完整业务流程；图 08 是三级分块与跨库关联的数据契约。
关联视图
- [[图_3文档入库流程|图3：上传入库业务流程]]
- [[图_8三级分块与跨库关联|图8：分块与跨库数据契约]]
源码对应
backend/api/routes/documents.py：upload_document / _process_upload_job：真实调用方与先父后叶顺序backend/api/resources.py：loader / parent_chunk_store / milvus_writer：组件实例装配backend/indexing/document_loader.py：DocumentLoader.load_document / sanitize_text / _split_page_to_three_levelsbackend/indexing/html_processor.py：load_html_for_document_loader：HTML 解析与章节页backend/indexing/parent_chunk_store.py：ParentChunkStore.upsert_documents：父块 PG 与 Redisbackend/indexing/milvus_writer.py：MilvusWriter.write_documents：叶子批处理、字段组装、进度backend/indexing/embedding.py：EmbeddingService.get_embeddings：本地 densebackend/indexing/milvus_client.py：MilvusStore.ensure_collection / init_collection / insert：Schema、BM25 与写入
Excalidraw Data
Text Elements
15 文档索引模块：组件与调用关系 ^90c53b15
从已保存的文件到可检索的文档块；展示 M7 的真实组件、调用接口与外部存储边界。 ^fd3f3183
M7 文档索引 · 返回 [[图_1项目设计|图1]] ^3dc311c1
调用方 M6 · documents.py 已完成文件保存与同名清理；同步 upload_document / 异步 _process_upload_job 传入 file_path + filename；由调用方控制“父块先入库，再处理叶子” ^57925fea
M7 · 解析、清洗与三级分块 / backend/indexing/document_loader.py ^30ed4496
DocumentLoader.load_document() PDF / Word / Excel → 对应 Loader HTML → html_processor.py 语义线性化 ^94dfd7e6
_load_from_langchain_docs() sanitize_text() 清洗正文与来源 统一 filename / type / path / page ^0ab1de02
_split_page_to_three_levels() L1 → L2 → L3 递归分块 _build_chunk_id() 建立父子 / 根关联 ^e40c4cf2
默认 chunk_size / overlap：L1 2400 / 400；L2 1600 / 200；L3 800 / 100。HTML 按章节组织成可复用的“页”。 ^16d5ae89
返回 new_docs: list[dict] · 包含 L1/L2/L3 全部块 text + 来源 metadata + chunk_id / parent_chunk_id / root_chunk_id + chunk_level / chunk_idx ^da00070a
M7 · 可复用存储组件 / M6 在 documents.py 中选出 parent_docs 与 leaf_docs，并按 ① → ② 调用 ^1fe251b8
① ParentChunkStore.upsert_documents(parent_docs) parent_chunk_store.py 处理 L1/L2；更新或插入父块，写 Redis 缓存 结束前 PG commit ^7204b45f
② MilvusWriter.write_documents(leaf_docs) milvus_writer.py 初始化集合；默认每批 50 个叶子块 生成 dense → 组装字段 → insert → 进度回调 ^9f9799fc
EmbeddingService.get_embeddings(texts) embedding.py HuggingFaceEmbeddings / BGE-M3 默认 CPU、1024 维、归一化 dense ^842372f5
① 成功后再执行 ② 并列画法表示组件分工 BM25 在 Milvus 服务端生成 ^4ac80adc
外部存储 · M8 管理的数据设施，供 M7 写入、M5 读取 ^2e07df4e
PostgreSQL parent_chunks + Redis L1/L2 全文、来源与关联 ID 逐项写缓存，最后 commit；无跨库回滚 ^99978508
Milvus · L3 可检索叶子 text + dense_embedding + 关联 ID；服务端从 text 生成 BM25 sparse 成功后原调用方更新 job；同步接口返回叶子块数量 ^16628bc4
关联视图 上传任务完整流程：[[图_3文档入库流程|图3]] · 分块与跨库关联：[[图_8三级分块与跨库关联|图8]] 返回系统总图：[[图_1项目设计|图1]] ^af6773f7
本图说明组件如何协作；原版编排仍位于 M6 的路由函数中，不虚构新的 IndexingService 或独立事务。 ^df4f59d3
读图说明 · M7 文档索引 ^035ebf40
模块边界 ^bc0e2757
• 输入是 M6 已保存的 file_path 与 filename； 鉴权、文件保存、同名清理和 job 属于 M6。 ^38958b19
• M7 提供解析、三级分块、父块存取、叶子向量 化与写入组件；原版没有独立 IndexingService。 ^0bd7113e
真实调用 ^3911e71d
• DocumentLoader 按格式读取，再清洗文本、补 充来源 metadata 并三级分块。 ^202b9669
• M6 在 documents.py 中拆出 parent_docs / leaf_docs，先调用父块存储，再调用向量写入。 ^b5a76db3
• MilvusWriter 初始化集合，按批调用 EmbeddingService，再组装字段并 insert。 ^e645399b
存储与约束 ^f3535e39
• L1/L2 写入 PG，逐项缓存 Redis；L3 写入 Milvus。 ^cd78c39d
• 本地模型只生成 dense；BM25 sparse 由 Milvus 的服务端函数生成。 ^8f455902
• 父块 commit 后才开始叶子写入；中途失败没有 统一跨库回滚。 ^3cea14a3
关联视图 ^0619838a
• 图 03 是上传任务的完整业务流程；图 08 是三 级分块与跨库关联的数据契约。 ^c700d0d5
Element Links
3dc311c1: [[图_1项目设计]]
%%
Drawing
1 | N4KAkARALgngDgUwgLgAQQQDwMYEMA2AlgCYBOuA7hADTgQBuCpAzoQPYB2KqATLZMzYBXUtiRoIACyhQ4zZAHoFAc0JRJQgEYA6bGwC2CgF7N6hbEcK4OCtptbErHALRY8RMpWdx8Q1TdIEfARcZgRmBShcZQUebR4ATm0ARho6IIR9BA4oZm4AbXAwUDBSiBJuCAB2YmwADgAGZIBmADM00shYRErA7CiOZWCOssxuKob+MphuZoA2AFYpyAoS |
%%
