图_2文档入库模块 · 详细实现
对应 [[2_代码实现_文档入库]]。按图 1 模板粒度，只写主要实现步骤。
读图方式
- 蓝底是文件，紫底是类，灰底是函数；标题与主要步骤分开，框宽随文字收紧。简单函数一句，复杂函数按主要处理阶段分步。
- 实线箭头表示调用（含 LangGraph 的节点调度），虚线箭头表示数据或对象传递。远距离用
〔调用 F07〕/〔传递 F07:2〕引用，避免拉长线。 - F / C / P 分别表示函数、类、文件；冒号后的数字指目标步骤。编号只用于定位，不表示执行次序。
- 省略普通返回、逐字段转换和重复异常处理；保留会影响业务走向的降级、HITL、终止等分支。
文件与函数索引
P01 · backend/indexing/document_loader.py
文档解析、清洗与三级分块。
- F01
sanitize_text()（源码 16 行）：清洗文档文本。 - F02
DocumentLoader.__init__()（源码 54 行）：初始化三级分块器。 - F03
DocumentLoader._build_chunk_id()（源码 82 行）：生成分块 ID。 - F04
DocumentLoader._split_page_to_three_levels()（源码 85 行）：按父子关系切出三级 Chunk。 - F05
DocumentLoader._load_from_langchain_docs()（源码 162 行）：将解析结果转换为三级分块。 - F06
DocumentLoader.load_document()（源码 195 行）：按文件类型解析并分块。 - F07
DocumentLoader.load_documents_from_folder()（源码 222 行）：批量读取文件夹中的文档。 - C01
DocumentLoader：文档加载与三级分块服务。
P02 · backend/indexing/html_processor.py
把 HTML 正文转换为章节 Document。
- F08
_read_html_text()（源码 21 行）：按网页编码读取 HTML。 - F09
_strip_noise()（源码 41 行）：去除网页噪声。 - F10
_pick_root()（源码 48 行）：选择正文区域。 - F11
_br_to_newlines()（源码 52 行）：保留网页换行。 - F12
_linearize_blocks()（源码 57 行）：按原顺序提取正文。 - F13
_doc_title()（源码 108 行）：提取网页标题。 - F14
_split_into_sections()（源码 115 行）：按二级标题切分章节。 - F15
parse_html_file_to_sections()（源码 139 行）：完成 HTML 正文与章节解析。 - F16
load_html_for_document_loader()（源码 152 行）：适配 DocumentLoader 的输入。
P03 · backend/indexing/embedding.py
共享文本向量化服务。
- F17
_create_dense_embedder()（源码 6 行）：加载本地 Dense 模型。 - F18
EmbeddingService.__init__()（源码 19 行）：初始化向量编码器。 - F19
EmbeddingService.get_embeddings()（源码 22 行）：批量文本编码。 - C02
EmbeddingService：文本向量化服务。
P04 · backend/indexing/milvus_writer.py
批量编码并写入 Milvus。
- F20
MilvusWriter.__init__()（源码 11 行）：绑定编码和存储服务。 - F21
MilvusWriter.write_documents()（源码 15 行）：按批次写入文档分块。 - C03
MilvusWriter：文档向量化与写入服务。
调用与对象传递对照
| 出发位置 | 目标 | 类型 | 关系 |
|---|---|---|---|
| F07 · 第 1 步 | F06 DocumentLoader.load_document |
实线 · 调用 | 调用 |
| F06 · 第 3 步 | F05 DocumentLoader._load_from_langchain_docs |
实线 · 调用 | 调用 |
| F05 · 第 2 步 | F01 sanitize_text |
实线 · 调用 | 调用 |
| F05 · 第 3 步 | F04 DocumentLoader._split_page_to_three_levels |
实线 · 调用 | 调用 |
| F04 · 第 1 步 | F03 DocumentLoader._build_chunk_id |
实线 · 调用 | 调用 |
| F02 · 第 2 步 | F04:1 DocumentLoader._split_page_to_three_levels |
虚线 · 传递 | 三级分块器 |
| F06 · 第 2 步 | F16 load_html_for_document_loader |
实线 · 调用 | HTML 解析调用 |
| F16 · 第 1 步 | F15 parse_html_file_to_sections |
实线 · 调用 | 调用 |
| F15 · 第 1 步 | F08 _read_html_text |
实线 · 调用 | 调用 |
| F15 · 第 1 步 | F09 _strip_noise |
实线 · 调用 | 调用 |
| F15 · 第 2 步 | F10 _pick_root |
实线 · 调用 | 调用 |
| F15 · 第 2 步 | F13 _doc_title |
实线 · 调用 | 调用 |
| F15 · 第 2 步 | F12 _linearize_blocks |
实线 · 调用 | 调用 |
| F15 · 第 3 步 | F14 _split_into_sections |
实线 · 调用 | 调用 |
| F12 · 第 1 步 | F11 _br_to_newlines |
实线 · 调用 | 调用 |
| F12 · 第 3 步 | F14:1 _split_into_sections |
虚线 · 传递 | 网页正文 |
| P03 · 第 1 步 | F18 EmbeddingService.__init__ |
实线 · 调用 | 创建共享编码服务 |
| F18 · 第 1 步 | F17 _create_dense_embedder |
实线 · 调用 | 调用 |
| F18 · 第 1 步 | F19:1 EmbeddingService.get_embeddings |
虚线 · 传递 | _embedder 编码模型 |
| P03 · 第 1 步 | F20:1 MilvusWriter.__init__ |
虚线 · 传递 | 共享 embedding_service |
| F21 · 第 2 步 | F19 EmbeddingService.get_embeddings |
实线 · 调用 | 批量编码调用 |
| F19 · 第 1 步 | F21:3 MilvusWriter.write_documents |
虚线 · 传递 | Dense 向量 |
[[source/_posts/LLM/2_RAG/project/img/详细实现/项目实现|查看项目实现总图]]。概要图仍保留在“实现”文件夹。
Excalidraw Data
Text Elements
backend/：本模块的后端实现 ^7c1228f4
indexing/：解析、编码及存取知识库数据 文档入库模块提供三个功能：文档解析与分块，向量化，L3块写入数据库 ^a320a655
[[2_代码实现_文档入库|P01 document_loader.py：文档解析、清洗与三级分块]] ^69dd485b
F01 sanitize_text()：清洗文档文本 ^94606cf0
- Unicode NFC 标准化
- 去除不可见字符、控制字符与私有区乱码
- 清除不完整的 UTF-8 代理项 ^cee41104
C01 DocumentLoader：文档加载与三级分块服务（pdf, docx, xlsx, html） ^b2ab78cb
-
属性：L1、L2、L3 三个递归分块器。 ^261013c8
-
功能： 文件夹批量解析 单文件解析 三级分块 ^0efc2c82
F02 init()：初始化三级分块器 ^f6d7b9ca
-
设置 L1 / L2 / L3 的块大小与重叠长度。 ^3352e2ab
-
创建三个递归文本分块器。 〔传递 F04:1〕 ^8eb23e04
F07 load_documents_from_folder()：批量读取文件夹中的文档 ^7f75718e
-
遍历支持的文件，逐个调用 load_document()。 〔调用 F06〕 ^53bfb254
-
汇总分块 ^4b4d288c
F06 load_document()：按文件类型解析成langchain数据结构 ^c59cec97
-
根据后缀选择 PDF / Word / Excel / HTML 解析器。 ^1de66adc
-
读取为 LangChain Document；HTML 走章节解析。 〔调用 F16〕 ^0c2dd8f9
-
统一清洗、分块，得到三级 Chunk。 〔调用 F05〕 ^643f3dc1
F05 _load_from_langchain_docs()：将解析结果转换为三级分块 ^edaaf4eb
-
逐页提取正文与文件、页码等来源信息。 ^649c1209
-
清洗正文及来源字段。 〔调用 F01〕 ^46692425
-
调用三级分块，汇总全部 Chunk。 〔调用 F04〕 ^f2350a05
F04 _split_page_to_three_levels()：将一页切出三级 Chunk ^a95232bd
-
整页切成 L1，记录 root_chunk_id。 〔调用 F03〕 ^b95b91f3
-
每个 L1 再切 L2，记录 parent / root ID。 ^f7b628a2
-
每个 L2 再切 L3，补齐关联 ID 与块序号。 ^744c4416
F03 _build_chunk_id()：生成分块 ID ^c28e1bf1
- 按 文件名::页码::层级::序号 拼接 chunk_id。 ^ffc81f0a
[[2_代码实现_文档入库|P04 milvus_writer.py：批量编码并写入 Milvus]] ^aa31e43c
- 组合 EmbeddingService 与 MilvusStore。 ^d8e62e4a
C03 MilvusWriter：文档向量化与写入服务 ^cfa452ca
-
属性：embedding_service、milvus_manager。 ^4d3b3e51
-
功能：文档批量编码、记录组装、写入和进度回调。 ^6d4bed78
F20 init()：绑定编码和存储服务 ^8bc0e994
- 保存传入或默认的 EmbeddingService、MilvusStore。 ^95c7e343
F21 write_documents()：按批次写入文档分块 ^4eb8f8c4
-
获取向量维度，初始化 Milvus 表。 ^661a2a17
-
分批提取文本，调用 EmbeddingService 编码。 〔调用 F19〕 ^749b8747
-
组合向量、正文、来源与 Chunk 关联字段。 ^e3bc1d28
-
批量插入 Milvus，更新处理进度。 ^4957f757
[[2_代码实现_文档入库|P02 html_processor.py：把 HTML 分页转换为章节 Document]] ^026cc2bb
- HTML 读取 → 去噪 → 正文提取 → 章节切分。 ^3a72d061
F16 load_html_for_document_loader()：适配 DocumentLoader 的输入 ^ca597f65
-
调用 HTML 章节解析。 〔调用 F15〕 ^d2b30bb5
-
将章节包装为 Document，附章节页码和来源。 ^0bb11f74
F15 parse_html_file_to_sections()：完成 HTML 正文与章节解析 ^a6fc0b0c
-
读取并解析 HTML，清理script、style、iframe 等网页噪声。 〔调用 F08 / F09〕 ^cc3eb994
-
选择正文区域，提取标题并线性化正文。 〔调用 F10 / F13 / F12〕 ^a298145a
-
按章节切分。 〔调用 F14〕 ^b0eedeb8
F08 _read_html_text()：按网页编码读取 HTML ^9a7282f9
- 识别 BOM / charset，选择编码解码文件。 ^0973b040
F09 _strip_noise()：去除网页噪声 ^5d3ebaeb
- 删除脚本、样式、嵌入标签与注释。 ^11517c77
F10 _pick_root()：选择正文区域 ^1bba7aa9
- 按 main → article → body 的顺序选正文。 ^6d3e2ecc
F13 _doc_title()：提取网页标题 ^1911281d
- 读取 title 标签文本。 ^202118bc
F12 _linearize_blocks()：按原顺序提取正文 ^b711cd31
-
先把 br 转为换行。 〔调用 F11〕 ^906a4668
-
依次提取标题、段落、列表等，保留标题层级。 ^8f6c1ec2
-
结构化文本过少时改用纯文本正文。 〔传递 F14:1〕 ^230fcbbc
F11 _br_to_newlines()：保留网页换行 ^0fcb7be3
- 将 br 标签替换为换行符。 ^2e9c284b
F14 _split_into_sections()：按二级标题切分章节 ^1783dc82
-
按二级标题拆分正文。 ^ce482e1c
-
为各章节添加标题与页码；无章节则作为一页。 ^8b0ba77e
[[2_代码实现_文档入库|P03 embedding.py：共享文本向量化服务]] ^e11919d7
- 创建全进程共享的 embedding_service。 〔调用 F18〕 〔传递 F20:1〕 ^7ea22f88
F17 _create_dense_embedder()：加载本地 Dense 模型 ^6809dee6
-
读取模型与设备配置，默认 bge-m3。 ^ca9686df
-
创建启用向量归一化的 HuggingFaceEmbeddings。 ^3c9b26c7
C02 EmbeddingService：文本向量化服务 ^6d5d9b8a
-
属性：共享的 embedding 模型。 ^d5002235
-
功能：文本编码 ^652e8e38
F18 init()：初始化向量编码器 ^3b333911
- 加载并保存 _embedder。 〔调用 F17〕 〔传递 F19:1〕 ^523b21f0
F19 get_embeddings()：批量文本编码 ^de5aa6f9
-
调用模型，将文本列表编码为 Dense 向量。 〔传递 F21:3〕 ^65b54933
-
编译文本清洗正则去除指定字符 ^1q2LpgxK
-
封装文档的加载和切分服务 ^ff0LzTs2
-
beautifulsoup解析 ^uAXIRZWB
文档入库一共三步： 1. 文档解析（html自定义解析） 2. 文本向量化 3. 解析的文本，向量，元数据入库 ^YKgiz7UK
Element Links
69dd485b: [[2_代码实现_文档入库]]
aa31e43c: [[2_代码实现_文档入库]]
026cc2bb: [[2_代码实现_文档入库]]
e11919d7: [[2_代码实现_文档入库]]
%%
Drawing
1 | N4KAkARALgngDgUwgLgAQQQDwMYEMA2AlgCYBOuA7hADTgQBuCpAzoQPYB2KqATLZMzYBXUtiRoIACyhQ4zZAHoFAc0JRJQgEYA6bGwC2CgF7N6hbEcK4OCtptbErHALRY8RMpWdx8Q1TdIEfARcZgRmBShcZQUebR4ATm0ARho6IIR9BA4oZm4AbXAwUDBSiBJuCGJNAHZNBITNHjTSyFhESsDsKI5lYJayzG4AFgAGfjKYbmSANgBWCcgKEnVu |
%%
