--- title: "11-统计打分收口打包同步落库" created: 2026-05-19 aliases: - 统计打分收口打包同步落库 tags: - 项目 --- # 统计打分收口打包同步落库我们接着上一篇“结构节点提取的四阶段流水线”往后学。上一篇的终点是: ```text extract() 返回 DocumentStructureNodeCandidate 列表 parse() 方法继续往下执行 ``` 这一篇要做的事情是:**把 parse() 后半段的统计分析跑完,然后回到 handleParseRoute,完成异步解析链路的收尾工作。** 学完之后,你就完整打通了"上传 → Kafka → Tika 解析 → 结构提取 → 解析收尾"这条主线。下一篇才会进入策略推荐。 --- ### **一、先建立整体认知:这一节在做什么?** 可以用一句话概括: > 在拿到结构节点之后,parse() 方法继续做标题计数、段落切分、token 估算、结构等级和内容质量评估,最后打包成 DocumentAnalysisResult。然后 handleParseRoute 接着把解析文本上传 MinIO、结构节点落库、同步导航索引和图谱投影、生成文档画像、记录任务日志,最后把任务推进到策略推荐阶段。整体可以画成两段流程: ```mermaid flowchart TD A[已经拿到 structureNodes] --> B[countHeadings 标题计数] B --> C[extractParagraphs 段落切分] C --> D[estimateTokenCount token 估算] D --> E[evaluateStructureLevel 结构等级] E --> F[evaluateContentQuality 内容质量] F --> G[打包 DocumentAnalysisResult] G --> H[上传 parsed-text txt 到 MinIO] H --> I[replaceDocumentNodes 结构节点落库] I --> J[syncNavigationArtifacts 同步导航和图谱] J --> K[generateProfile 生成文档画像] K --> L[记录任务完成日志] L --> M[推进到 STRATEGY_ROUTE 阶段] ``` 可以看出,这一节虽然不像结构提取那么复杂,但它是“收口”阶段,把解析结果落到各个存储里,为后面的策略推荐和索引构建准备数据。 --- ### **二、回到 parse():还剩五个统计步骤** 上一篇结束时,我们停在 `structureNodeExtractor.extract()` 返回结构节点。接下来的代码很短,但每一步都在为后续策略推荐准备“判断依据”。 ```java List structureNodes = structureNodeExtractor.extract(originalFileName, cleanedText); int headingCount = countHeadings(cleanedText, structureNodes); List paragraphList = extractParagraphs(cleanedText); int maxParagraphLength = paragraphList.stream() .mapToInt(String::length) .max() .orElse(0); int charCount = cleanedText.length(); int tokenCount = estimateTokenCount(cleanedText); int structureLevel = evaluateStructureLevel(headingCount, paragraphList.size()); int contentQualityLevel = evaluateContentQuality(cleanedText, charCount); return new DocumentAnalysisResult(...); ``` 我们一步一步看。 --- ### **三、countHeadings:标题计数为什么要双路径?** 代码的核心是这样: ```java if (structureNodes != null && !structureNodes.isEmpty()) { long structuredHeadingCount = structureNodes.stream() .filter(node -> node != null && DocumentStructureNodeTypeEnum.SECTION.getCode().equals(node.getNodeType()) && node.getDepth() != null && node.getDepth() > 0) .count(); if (structuredHeadingCount > 0) { return (int) structuredHeadingCount; } } // 否则退化成逐行扫描 int count = 0; for (String line : text.split(" ")) { if (documentLineClassifier.classify(line).isHeading()) { count++; } } return count; ``` 这里的设计有两个关键点。 #### **1. 优先使用结构节点提取的结果** 为什么? 因为上一阶段的四阶段流水线已经做了非常严谨的结构识别: ```text 信号提取歧义消解层级构建树校验 ``` 它得到的 SECTION 节点(depth > 0)质量比单纯逐行扫描高得多。所以这里直接 stream 过滤: ```text 节点类型 = SECTION depth > 0(排除根节点) ``` 得到的就是真正的“章节级标题数量”。 #### **2. 没识别出 SECTION 才退化成逐行扫描** 如果文档结构非常乱,四阶段流水线可能没有抽到任何 SECTION。这时候不能直接说“没标题”,而是要退化成 `DocumentLineClassifier` 的轻量识别。这是一种**降级策略**: ```text 高质量路径:用结构节点高质量失败:用单行启发式都失败:返回 0 ``` #### **3. 为什么标题数量这么重要?** 因为它直接影响后面 `evaluateStructureLevel`: ```text 标题数 >= 5 → 结构等级 HIGH 标题数 >= 2 → 结构等级 MEDIUM 没标题但有段落 → LOW 什么都没有 → UNKNOWN ``` 而结构等级又是策略推荐的核心输入: ```text HIGH → 优先结构化切块 MEDIUM → 结构化 + 递归 LOW → 递归 + 语义 UNKNOWN → LLM 智能切块或最简单的递归 ``` 所以标题计数看似一个简单的 `count++`,实际是后面切块策略选择的关键信号。 --- ### **四、extractParagraphs:段落切分** 代码很短: ```java for (String paragraph : text.split(" \\s* ")) { String trimmed = paragraph.trim(); if (StrUtil.isNotBlank(trimmed)) { paragraphList.add(trimmed); } } ``` 核心逻辑: ```text 按"连续空行"切分 trim 每段过滤空段 ``` 为什么用“连续空行”而不是单一换行? 因为单换行通常只是行内换行(比如 PDF 转换出来的硬换行),并不代表段落边界。只有“两个换行之间没有内容”才是段落分隔符。这也是为什么上一篇文本清洗时: ```text .replaceAll(" {3,}", " ") ``` 只把超过 3 个换行的地方压缩成 2 个,保留段落边界。 #### **段落统计的几个用途** ```text 1. 段落数 → 结构等级判断 2. 段落数 → 是否适合语义切块 3. 最长段落长度 → 切块策略选择 4. 段落数 → 文档画像、目录辅助判断 ``` 例如最长段落很长(几千字符),说明文档里可能有大段连续文本,递归切块需要严格控制块大小,否则单块超过预算。 --- ### **五、estimateTokenCount:为什么是估算?** 代码: ```java int englishWordCount = 0; int chineseCharCount = 0; for (String word : text.split("\\s+")) { if (word.matches(".*[A-Za-z].*")) { englishWordCount++; } } for (char current : text.toCharArray()) { if (String.valueOf(current).matches("[\\u4e00-\\u9fa5]")) { chineseCharCount++; } } return englishWordCount + chineseCharCount + Math.max(1, (text.length() - chineseCharCount) / 4); ``` 公式可以简化为: ```text 中文字符数 + 英文单词数 + 剩余字符数 / 4 ``` #### **1. 为什么不用真实 tokenizer?** 理论上你可以用 OpenAI tiktoken、HuggingFace tokenizer 之类来精确算。但这里做了一个非常工程化的取舍: ```text 当前阶段只是粗粒度判断不需要精确到每一 token 不想引入额外依赖不想增加调用开销 ``` 因为这里 token 数的用途是: ```text 判断文档大致体量策略推荐里的粗略阈值判断日志统计前端展示 ``` 不是真正调用模型时的 token 控制。 #### **2. 公式背后的近似逻辑** ```text 中文一个字 ≈ 一个 token 英文一个单词 ≈ 一个 token 其他字符按 4 个字符 ≈ 1 个 token ``` 这个估算和主流 tokenizer 在中英文文本上的统计结果差异通常在 ±10~20% 之间,对“做策略判断”来说完全够用。 #### **3. 这就是工程权衡的一个典型案例** 如果未来某个阶段确实需要精确 token 数,例如调用模型前要严格控制 prompt 大小,可以单独引入精确 tokenizer。但解析阶段没必要,“好用、稳定、便宜”就行。面试时可以这样讲: > 解析阶段的 token 估算只用于策略判断和粗粒度统计,采用“中文字符数 + 英文单词数 + 其他字符 / 4”的近似公式,在保证稳定性和零外部依赖的前提下,提供了足够的精度。如果未来需要精确 token,会在调用模型前单独引入 tokenizer,而不是在解析层。 --- ### **六、evaluateStructureLevel:结构等级** 代码: ```java if (headingCount >= 5) { return DocumentStructureLevelEnum.HIGH.getCode(); } if (headingCount >= 2) { return DocumentStructureLevelEnum.MEDIUM.getCode(); } if (paragraphCount >= 3) { return DocumentStructureLevelEnum.LOW.getCode(); } return DocumentStructureLevelEnum.UNKNOWN.getCode(); ``` 这是一个非常简洁但意义重大的分类。 #### **1. HIGH:有清晰章节结构** ```text 标题 >= 5 ``` 适合走结构化切块,沿章节切,块边界自然,语义独立。 #### **2. MEDIUM:有部分结构** ```text 标题 >= 2 ``` 可能是一些有几级目录但不完整的文档。适合“结构化 + 递归”混合切块。 #### **3. LOW:几乎没结构,只是连续段落** ```text 没什么标题但有 >= 3 段 ``` 适合递归切块或语义切块。 #### **4. UNKNOWN:啥结构都没有** ```text 没标题段落也很少 ``` 可能是非常短的文档、解析失败、扫描版 PDF 等。需要走 LLM 智能切块或最简单的整文档作为一个块。 #### **5. 这种粗粒度分类的工程意义** 不是越细越好。如果这里分得太细,后面策略推荐的逻辑就会爆炸。四档分类(HIGH / MEDIUM / LOW / UNKNOWN)既能覆盖绝大多数情况,又能让策略推荐保持简单。 --- ### **七、evaluateContentQuality:内容质量等级** 代码: ```java if (StrUtil.isBlank(text) || charCount < 20) { return LOW; } long brokenCharCount = text.chars().filter(value -> value == '�').count(); double brokenRatio = charCount == 0 ? 1D : (double) brokenCharCount / charCount; if (brokenRatio > 0.02D || charCount < 100) { return LOW; } if (brokenRatio > 0.005D || charCount < 500) { return MEDIUM; } return HIGH; ``` 它判断的是“解析得到的文本质量好不好”。 #### **1. 极短文本直接判 LOW** ```text charCount < 20 ``` 这种文档基本无法用于问答,需要提示用户或人工处理。 #### **2. 乱码率检测** ```text brokenCharCount = 替换字符 �(U+FFFD)的数量 ``` 这个字符是 UTF-8 解码失败时的占位符。如果一份文档解析出来 � 占比很高,说明: ```text 原始文件编码有问题 PDF 嵌入字体不规范解析器无法识别某些字符 ``` 这种情况要降级处理,例如: ```text 不推荐自动切块提示用户重新上传切到 LLM 智能切块兜底 ``` 3. 阈值设计 ```text 乱码 > 2% 或字符数 < 100 → LOW 乱码 > 0.5% 或字符数 < 500 → MEDIUM 否则 → HIGH ``` 这种多维阈值是工程经验积累下来的。它的核心思想是: ```text 不能只看一个维度要把"长度"和"乱码"组合起来判断 ``` 例如一份 1000 字符的文档,乱码占 1%,虽然乱码不多但比例不低,仍然只算 MEDIUM。 #### **4. 这两个等级如何影响后续?** ```text structureLevel:决定切块策略 contentQualityLevel:决定是否能自动处理 ``` 例如: ```text 质量 HIGH + 结构 HIGH → 自动结构化切块质量 MEDIUM + 结构 LOW → 推荐递归 + 语义质量 LOW → 提示用户、可能拒绝继续处理 ``` ### **八、打包返回 DocumentAnalysisResult** 最后一步: ```text return new DocumentAnalysisResult( cleanedText, charCount, tokenCount, structureLevel, contentQualityLevel, headingCount, paragraphList.size(), maxParagraphLength, structureNodes ); ``` 这个对象是“解析阶段的标准输出”。可以理解为一份**文档解析报告**: ```text 原文(清洗后) 长度统计结构指标质量指标结构节点 ``` 后续模块只对接这个对象,不再关心: ```text 文档是 PDF 还是 DOCX Tika 怎么解析怎么换行清洗怎么识别标题怎么算 token ``` 这就是抽象的力量:**通过中间 DTO 把上下游解耦。** 到这里 parse() 全部执行完成,控制流回到 `handleParseRoute`。 --- ### **九、回到 handleParseRoute:解析后的收尾工作** handleParseRoute 拿到 DocumentAnalysisResult 后,要做四件大事: ```text 1. 上传清洗后纯文本到 MinIO 2. 把结构节点落库 3. 同步导航索引和图谱投影 4. 生成文档画像 5. 记录解析完成日志 6. 推进到策略推荐阶段 ``` 我们逐一展开。 --- ### **十、上传解析文本 txt:为什么要再存一份?** 代码: ```java String parseTextPath = storageService.uploadParsedText( documentId, analysisResult.getParsedText() ); ``` 这一步把清洗后的纯文本以 .txt 形式上传到 MinIO,路径例如: ```text parsed-text/123456.txt ``` #### **1. 为什么不直接每次重新解析原始文件?** 因为后续阶段会多次用到这个文本: ```text 切块阶段:把文本切成父子块向量化阶段:把每个块送进 embedding 模型索引阶段:写入 ES、向量库图谱阶段:节点 contentText 已经写过,但全文也可能补充摘要阶段:基于全文生成摘要 RAG 阶段:可能需要回查全文证据 ``` 每次都重新跑一次 Tika 是非常昂贵的: ```text PDF 解析慢 Word 解析慢内存开销大还要重新做清洗 ``` 而 .txt 文件: ```text 读取很快不需要解析所有阶段都能直接用 ``` #### **2. 为什么不直接放数据库?** 因为文本可能很大,几十万字符甚至几百万。数据库适合存结构化字段,不适合存大块文本: ```text 影响行存储影响查询性能备份成本高 ``` 对象存储 + 数据库存路径,是更典型的设计。 #### **3. 为什么是 .txt 而不是 JSON?** 因为这一步只关心“纯文本”。结构化信息已经分别保存: ```text 统计指标 → 数据库 document 字段结构节点 → document_structure_node 表画像 → document_profile 表 ``` 所以 .txt 只承担“最干净的全文”的职责,简单清晰。 --- ### **十一、replaceDocumentNodes:结构节点整体替换** 这是这一节最有“工程感”的一段代码,值得好好讲。 ```java List structureNodes = structureNodeService.replaceDocumentNodes( documentId, taskId, analysisResult.getStructureNodes() ); ``` #### **1. 为什么是“替换”而不是“增量”?** 因为每次重新解析都意味着: ```text 文档可能被重新上传切块策略可能被调整结构识别算法可能升级 ``` 如果做增量更新,会非常麻烦: ```text 要识别哪些节点是同一个要处理父子关系迁移要保留旧 ID 还是分配新 ID ``` 而“整树替换”非常清晰: ```text 旧节点全删新节点全建 ``` 代价是同一文档的旧节点 ID 不再保留,但这一般不是问题,因为: ```text 节点 ID 主要用于内部关系对外暴露的是 canonicalPath 和 sectionPath ``` #### **2. 两轮遍历的设计** 代码做了一个非常重要的设计: ```text 第一轮:为每个 candidate 预生成数据库 ID 第二轮:把逻辑编号 nodeNo 翻译成数据库 ID,再插入 ``` 为什么要两轮? 因为节点之间存在前后引用关系: ```text parentNodeId 指向父节点的真实 ID prevSiblingNodeId 指向前兄弟 nextSiblingNodeId 指向后兄弟 ``` 如果一边遍历一边插入: ```text 插到节点 A 时,可能它的兄弟 B 还没插入 B 还没拿到真实 ID A 的 nextSiblingNodeId 就只能留空或要后续修正 ``` 而如果先把所有 nodeNo → 真实 ID 的映射建好: ```text 插入 A 时,直接根据 nextSiblingNodeNo 查映射表拿到 B 的真实 ID 一次性完成所有引用关系 ``` 这是处理“有向图持久化”的经典做法: ```text 先分配 ID 再 resolve 引用 ``` #### **3. 为什么不直接用 nodeNo 当主键?** 因为 nodeNo 只是“当前这一次解析里”的逻辑编号: ```text 只在当前文档解析任务中唯一不同文档之间会重复重新解析时也可能重新编号 ``` 数据库主键需要全局唯一,所以用 uidGenerator 生成。而 candidate 里只保留 nodeNo,是为了让结构提取阶段不依赖具体存储实现。这种“逻辑层用 nodeNo,持久层用真实 ID”的分层设计很常见。 #### **4. 为什么先删旧数据?** ```java deleteByDocumentId(documentId); ``` 因为这个方法的语义就是“整树替换”。先删旧,再插新,保证数据库里只有“当前最新的一棵结构树”。如果不先删,可能会出现: ```text 旧节点和新节点共存父子关系混乱导航索引和图谱投影查到错节点 ``` #### **5. 这部分可以怎么讲给面试官** 可以这样表达: > 结构节点采用整树替换策略,避免增量更新引发的关系迁移复杂度。落库时使用两轮遍历:第一轮基于候选节点的 nodeNo 预分配数据库主键,第二轮再把候选节点中的 parentNodeNo、prevSiblingNodeNo、nextSiblingNodeNo 翻译成真实主键 ID,保证父子关系和兄弟关系在一次插入中即可闭合。逻辑层使用 nodeNo,持久层使用全局唯一 ID,通过映射表完成解耦。 --- ### **十二、syncNavigationArtifacts:导航索引和图谱投影** 代码: ```java DocumentNavigationIndexService navigationIndexService = navigationIndexServiceProvider.getIfAvailable(); if (navigationIndexService != null) { navigationIndexService.reindexDocumentNodes(documentId, parseTaskId, structureNodes); } DocumentStructureGraphProjectionService graphProjectionService = graphProjectionServiceProvider.getIfAvailable(); if (graphProjectionService != null && graphProjectionService.enabled()) { graphProjectionService.projectToGraph(documentId, parseTaskId); } ``` 这一步做两件事: ```text 1. 把结构节点写入 ES,用于导航搜索 2. 把结构节点写入 Neo4j,用于图谱导航 ``` #### **1. ObjectProvider 模式的妙用** 代码用了 Spring 的 `ObjectProvider`: ```java navigationIndexServiceProvider.getIfAvailable(); graphProjectionServiceProvider.getIfAvailable(); ``` 它的作用是: ```text 如果项目里没有这个 Bean,返回 null 如果有,就拿到实例 ``` 为什么要这么写? 因为这两个能力是**可选组件**: ```text 有些部署环境可能不启用 Neo4j 有些环境只用向量检索,不做结构导航开发环境可能完全跳过这两块 ``` 如果直接 `@Autowired`,Bean 不存在就启动失败。 `ObjectProvider` 的好处是: ```text 不存在不抛异常存在就用不存在就跳过 ``` 这是非常优雅的“可选依赖”设计。 #### **2. 导航索引:reindexDocumentNodes** 它把结构节点写入 ES,例如: ```text 索引名:document_structure_index 文档:每个 SECTION / LIST_ITEM 一条字段:title、anchorText、sectionPath、contentText、documentId、nodeId ``` 后续用户可以做: ```text 按章节标题搜索按章节路径定位全文搜索章节内容 ``` 这就是项目里“章节级导航与上下文扩展”的基础。 #### **3. 图投影:projectToGraph** 它把结构节点写入 Neo4j,形成三层图谱: ```text Document 节点 └── Section 节点 └── Item 节点 ``` 通过四种关系连接: ```text HAS_SECTION HAS_CHILD HAS_ITEM NEXT_SIBLING ``` 这就是项目亮点里的“基于 Neo4j 图数据库构建文档层级结构图谱”。支持五种查询能力: ```text 章节编号定位标题路径查找邻接遍历(前后兄弟) 子节点展开语义最佳匹配 ``` #### **4. 为什么要在解析阶段就同步,而不是等切块完?** 因为图谱和导航索引依赖的是**结构信息**,而不是切块信息。切块的产物是“父子文本块”,用于 RAG 检索; 图谱和导航索引用的是“章节标题、路径、层级”,和切块无关。所以: ```text 结构节点一旦落库,就立刻同步图谱和导航索引不必等切块或向量化完成用户上传后短时间内就能看到目录导航 ``` 这是一种把“快产物”和“慢产物”分开释放的设计。 --- ### **十三、generateProfile:文档画像生成** 文档画像是这一节最有意思的部分之一。它的目标是: ```text 不解析正文不做切块而是把解析结果再压缩成一份"画像快照" ``` 可以理解为给文档做一张“身份证”,告诉系统: ```text 这份文档大致讲什么属于哪种类型适不适合图谱导航适不适合条目定位属于哪个知识范围属于哪个业务分类有哪些标签有哪些核心主题有哪些示例问题 ``` #### **1. 画像 vs 文档主表** 很多人会问:为什么不直接把这些字段放到 document 表? 因为画像和文档主表的职责不同: ```text document:文档的基础属性 + 状态字段 profile:文档的"能力摘要" + 自动推断结果 ``` 而且画像是“可重新生成”的: ```text 重新解析时画像版本递增不会覆盖用户手填字段 ``` document 表里的字段则是“正式资产数据”,不能轻易自动覆盖。这是一种典型的“正式数据 vs 派生数据”分表设计。 #### **2. 画像版本号** 代码里有一段: ```java boolean creating = profile == null; if (creating) { profile.setProfileVersion(1); } else { profile.setProfileVersion( Optional.ofNullable(profile.getProfileVersion()).orElse(0) + 1 ); } ``` 每次重新生成画像,版本号 +1。这有什么用? ```text 后台运营可以看出文档画像被重建过几次调试时可以看哪一次画像出问题新旧画像对比有依据 ``` 如果未来要做画像质量监控、画像 A/B 测试,版本号是基础。 #### **3. buildDraft:画像推断中心** `buildDraft()` 是画像生成的核心,它有非常清晰的依赖链: ```mermaid flowchart TD A[structureNodes] --> B[sectionTitles] A --> C[supportsItemLookup] B --> D[supportsGraphOutline] C --> E[graphFriendly] D --> E A --> F[documentType] B --> F F --> G[coreTopics] G --> H[exampleQuestions] G --> I[summary] G --> J[knowledgeScopeCode] F --> K[businessCategory] J --> L[documentTags] ``` 这种链式推断有一个核心思想: > 所有画像字段使用同一批输入快照,避免“摘要按旧数据生成、标签按新数据生成”的不一致问题。这是设计上的一个细节,也是工程师的成熟标志。 #### **4. inferDocumentType:启发式关键词推断** 代码里没用 LLM 来判断文档类型,而是用关键词规则: ```java if (combined.contains("faq") || combined.contains("常见问题")) { return "faq"; } if (combined.contains("故障") || combined.contains("排查") ...) { return "troubleshooting"; } if (combined.contains("规则") || combined.contains("制度")) { return "rule"; } if (combined.contains("规格") || combined.contains("参数")) { return "spec"; } if (supportsItemLookup || combined.contains("手册") ...) { return "manual"; } return "intro"; ``` 为什么这里没用 LLM? 因为画像生成是一个高频操作: ```text 每次上传都要做每次重新解析都要做不能让 LLM 成本和延迟拖累主链 ``` 而文档类型只是粗粒度归类,关键词规则: ```text 稳定、可解释、零成本出错也容易排查随时可以加新关键词 ``` 这是和上一节歧义消解里 LLM 介入的鲜明对比: ```text 歧义消解:边界场景,数量很少,适合 LLM 文档类型:高频粗分类,适合规则 ``` 工程系统中,“什么时候用 LLM,什么时候用规则”是非常重要的判断。 #### **5. 文档类型的下游作用** documentType 会影响: ```text exampleQuestions 的生成模板 businessCategory 的归类后续策略推荐里的判断逻辑 ``` 例如： ```text faq 类型 → 适合短块切分,问题导向召回 troubleshooting → 适合条目级精准定位 manual → 适合结构化切块 + 章节导航 rule → 适合段落级切块,严格证据匹配 spec → 适合表格识别,关键词匹配 intro → 适合短文档摘要召回 ``` 所以画像不是“为了画像而画像”,它是后续策略推荐和路由的输入。 #### **6. backfillDocumentMetadata:补空不覆盖** 这一步把画像推断的字段补到 document 主表: ```text if (StrUtil.isBlank(document.getKnowledgeScopeCode()) && StrUtil.isNotBlank(draft.knowledgeScopeCode())) { document.setKnowledgeScopeCode(draft.knowledgeScopeCode()); changed = true; } ``` 注意这里有一条非常重要的原则: ```text 只在 document 主表为空时才补用户已经填的值绝对不动这就是“尊重用户输入”的设计原则。 ``` 举个例子: ```text 用户上传文档时手动填了知识范围:"人力资源" 画像自动推断出"行政管理" ``` 如果直接覆盖: ```text 用户会非常困惑甚至会觉得系统乱改数据 ``` 而“补空不覆盖”可以做到: ```text 用户填了 → 用用户的用户没填 → 用画像推断 ``` 这种细节非常体现产品意识。 --- ### **十四、记录解析完成日志** 代码: ```text taskLogService.saveLog( taskId, documentId, DocumentTaskStageEnum.CONTENT_PARSE.getCode(), DocumentTaskEventTypeEnum.COMPLETE.getCode(), DocumentLogLevelEnum.INFO.getCode(), DocumentOperatorTypeEnum.SYSTEM.getCode(), null, "文档解析完成。", Map.of( "charCount", analysisResult.getCharCount(), "tokenCount", analysisResult.getTokenCount(), "structureLevel", analysisResult.getStructureLevel(), "contentQualityLevel", analysisResult.getContentQualityLevel(), "structureNodeCount", structureNodeCount ) ); ``` 为什么要把这些数据塞到日志里? #### **1. 全链路可观测的数据基础** 你的项目亮点里有“全链路可观测”。任务日志不是简单的 info 文本,而是结构化的事件: ```text 任务 ID 文档 ID 阶段事件类型日志级别操作人类型操作人描述 metadata ``` 后台可以基于 metadata 做: ```text 不同结构等级的文档分布平均字符数和 token 数解析成功率画像版本号失败模式分类 ``` #### **2. 事后排查问题的关键信息** 如果用户说: ```text 我上传的文档为什么切块策略选错了? ``` 后台可以查日志: ```text charCount = 12000 tokenCount = 8000 structureLevel = LOW contentQualityLevel = MEDIUM structureNodeCount = 3 ``` 立刻就能知道: ```text 文档结构识别少质量一般所以策略推荐选了递归 + 语义,而不是结构化 ``` 整个排查链路非常清晰。 --- ### **十五、推进任务阶段:CONTENT\_PARSE → STRATEGY\_ROUTE** 最后一步: ```java task.setCurrentStage(DocumentTaskStageEnum.STRATEGY_ROUTE.getCode()); taskMapper.updateById(task); ``` 这一步只更新一个字段,但意义重大。它表示: ```text 内容解析阶段完成任务进入策略推荐阶段 ``` 整个文档生命周期可以画成: ```mermaid stateDiagram-v2 [*] --> FILE_UPLOAD FILE_UPLOAD --> CONTENT_PARSE CONTENT_PARSE --> STRATEGY_ROUTE STRATEGY_ROUTE --> WAIT_USER_CONFIRM WAIT_USER_CONFIRM --> CHUNK_BUILD CHUNK_BUILD --> EMBEDDING EMBEDDING --> INDEX_BUILD INDEX_BUILD --> [*] ``` 每一次状态切换都会落库,任务表里始终能反映最新进度。 #### **为什么不直接进入切块阶段,而要中间过策略推荐?** 因为切块策略是“可由用户调整”的: ```text 系统先推荐用户确认或修改再触发切块 ``` 这就是项目里设计五种切块策略的原因: ```text 结构化、递归、语义、LLM、自动选择 ``` 每一种都有适用场景,系统给推荐,但用户可以决定。 --- ### **十六、把 parse() 后半段和 handleParseRoute 收尾完整串起来** 可以总结成一段话: > 在结构节点提取完成后,parse() 方法继续做标题计数、段落切分、token 估算、结构等级评估和内容质量评估,把所有结果打包成 DocumentAnalysisResult。控制流回到 handleParseRoute 后,系统先把清洗后的纯文本以 .txt 形式上传到 MinIO,供后续切块和索引复用;再调用 DocumentStructureNodeService.replaceDocumentNodes 用最新候选节点整体替换文档结构树,通过两轮遍历实现 nodeNo 到真实主键的引用闭合;接着通过 ObjectProvider 模式可选地同步导航 ES 索引和 Neo4j 图谱投影;然后调用 DocumentProfileService.generateProfile 生成或递增更新文档画像,并将画像推断出的元数据"补空不覆盖"地回填到文档主表;最后记录解析完成日志,把任务阶段从 CONTENT\_PARSE 推进到 STRATEGY\_ROUTE,等待策略推荐流程接管。 --- ### **十七、这一节的核心技术点** #### **1. 双路径标题计数** 优先用结构节点,降级用单行启发式,保证标题计数始终有结果。 #### **2. token 估算的工程权衡** 策略判断阶段不需要精确 token,公式估算更便宜更稳定。 #### **3. 多维阈值评估** 结构等级和内容质量都用“数量阈值 + 比例阈值”组合判断,鲁棒性更好。 #### **4. DTO 抽象 DocumentAnalysisResult** 把多格式文档的解析结果统一成一个对象,下游模块只对接 DTO,不关心源格式。 #### **5. 解析文本独立存储** 避免重复解析原始文件,以 .txt 形式存到 MinIO,索引和切块阶段直接复用。 #### **6. 结构节点整树替换** 避免增量更新的复杂度,用先删后插的方式保证一致性。 #### **7. 两轮遍历闭合引用** 先分配 ID,再翻译引用,解决节点之间的前后向引用问题。 #### **8. ObjectProvider 处理可选依赖** 导航索引和图投影都做成可插拔组件,缺失不报错。 #### **9. 画像与主表分离** 画像是派生数据,主表是正式资产数据,职责清晰,互不干扰。 #### **10. 画像版本号** 每次重新生成画像递增版本,便于审计、对比和质量监控。 #### **11. 启发式关键词分类** 文档类型用规则推断,避免高频 LLM 调用。LLM 只用在歧义边界场景。 #### **12. 补空不覆盖原则** 自动推断不能覆盖用户显式输入,尊重用户意图。 #### **13. 结构化任务日志** 不是文本日志,而是带 metadata 的事件日志,支撑全链路可观测。 #### **14. 阶段状态机** 任务在 FILE\_UPLOAD → CONTENT\_PARSE → STRATEGY\_ROUTE 之间显式流转,每一步都更新数据库。 --- ### **十八、面试官可能会问的问题** #### **问题 1:为什么 token 数用估算公式,不用精确 tokenizer?** 可以回答: > 解析阶段的 token 数主要用于策略判断和粗粒度统计,不直接参与模型 prompt 控制。所以采用“中文字符数 + 英文单词数 + 其他字符 / 4”的近似公式,在保证精度足够的前提下,避免引入额外依赖和开销。如果未来需要精确 token 数,会在调用模型前单独引入 tokenizer,而不是在解析层。 #### **问题 2:为什么结构节点要整树替换,不做增量更新?** 可以回答: > 增量更新需要识别同一节点、迁移父子关系、保留历史 ID,对树形结构来说复杂度很高。而文档每次重新解析后结构可能完全变化,与其追求最小变更,不如直接整树替换。先删旧节点再插入新节点,保证数据库始终只有“当前最新结构”。代价是节点 ID 变更,但对外暴露的是 canonicalPath 和 sectionPath,这两者保持一致即可。 #### **问题 3:为什么用两轮遍历来插入结构节点?** 可以回答: > 因为节点之间存在 parent、prevSibling、nextSibling 等前后向引用,如果一边遍历一边插入,可能在插入当前节点时其引用对象还没拿到真实主键。所以先做一轮遍历预生成 nodeNo → 真实 ID 的映射表,再做第二轮遍历,把候选节点中的逻辑编号翻译成真实主键 ID,最后插入。这样可以一次性闭合所有引用关系,不需要后续修补。 #### **问题 4:为什么导航索引和图投影用 ObjectProvider?** 可以回答: > 因为这两个能力是可选组件。有些部署环境只用向量检索不启用 Neo4j,有些开发环境为了简化部署连 ES 都不启用。如果直接 @Autowired,Bean 不存在会启动失败。ObjectProvider 的 getIfAvailable() 模式可以做到“存在就用,不存在就跳过”,实现真正的可插拔。 #### **问题 5:画像为什么要单独建一张表,而不放到 document 主表?** 可以回答: > 因为它们的职责不同。document 主表存的是文档基础属性和正式状态字段,这些字段一般由用户显式维护或系统状态机推进。画像是派生数据,通过解析结果自动推断而来,可以重新生成、可以版本递增。两者分离可以避免“自动推断覆盖用户输入”的风险,同时方便画像质量监控、版本审计和迭代升级。 #### **问题 6:画像里为什么不用 LLM 来推断文档类型?** 可以回答: > 画像生成是高频操作,每次上传或重新解析都会执行一次。如果用 LLM 推断文档类型,会带来明显的成本和延迟。而文档类型只是粗粒度归类(faq、manual、rule、spec、troubleshooting、intro),用启发式关键词规则就能稳定覆盖大多数场景。规则的好处是稳定、可解释、零成本、出错好排查、随时可扩展。LLM 的能力会留给真正“规则解决不了”的边界场景,例如歧义消解。 #### **问题 7:为什么画像回填只补空不覆盖?** 可以回答: > 因为用户在知识管理界面手动填写的元数据优先级应该高于系统自动推断结果。如果直接覆盖,用户可能困惑甚至觉得系统乱改数据。所以策略是:用户填了就保留用户值,用户没填才用画像推断作为默认值补上。这种“尊重用户输入”的设计在产品上非常重要。 #### **问题 8:任务日志为什么要带 metadata?** 可以回答: > 因为日志不只是记录“发生了什么”,还要记录“当时的关键状态”。每个阶段把 charCount、tokenCount、structureLevel、contentQualityLevel、structureNodeCount 等关键指标作为 metadata 写入日志,后续排查问题、做质量分析、生成统计报表时都能直接基于结构化字段查询,而不用回去重新算。这是全链路可观测的基础。 --- ### **十九、这块可以怎么写进简历** 可以这样表达: > 负责文档解析阶段的统计分析与异步收尾流程。在结构节点提取完成后,完成标题计数、段落切分、token 估算、结构等级和内容质量评估,统一打包为 DocumentAnalysisResult,作为后续策略推荐的标准输入。解析收尾环节,将清洗后的纯文本以 .txt 上传至 MinIO 供索引和切块复用;通过两轮遍历的"先分配 ID,再 resolve 引用"模式,将结构节点整树替换写入数据库;基于 ObjectProvider 模式可选同步 Elasticsearch 导航索引和 Neo4j 图谱投影;并调用画像服务生成文档摘要、文档类型、核心主题、示例问题、知识范围、业务分类和标签等画像信息,以"补空不覆盖"策略回填文档主表元数据。最后记录结构化任务日志并推进任务阶段至 STRATEGY\_ROUTE,为后续切块策略推荐提供完整上下文。如果要再强调架构性,可以加一句: > 通过"统一 DTO 抽象 + 整树替换 + 可插拔派生产物 + 画像版本化"的设计,实现了多格式文档解析结果到 RAG 知识资产的标准化转换,是文档处理流水线中承上启下的关键阶段。 --- **企业级项目导航**：⬅️ [[10-策略推荐与方案持久化|10-策略推荐与方案持久化]] | 11-统计打分收口打包同步落库 | ➡️ [[12-解析结果统计与异步收尾|12-解析结果统计与异步收尾]]