Retrieval score differs between UI upload (.docx) and API upload (.txt) despite identical chunk content and embedding model

快速结论：该报错发生在 Dify 用户通过 UI 上传 .docx 文件与通过 API 上传 .txt 文件时，使用相同的分块规则和文本内容，但检索得分出现显著差异（UI → 0.99，API → 0.69）。优先排查 API 请求中的 hierarchical mode 是否被正确应用，以及两种文件格式的文本提取管道差异。

问题场景

用户在使用 Dify Cloud 版本时，通过 POST /v1/datasets/{dataset_id}/document/create-by-file API 上传 .txt 文件，与在 Dify UI 直接上传 .docx 文件对比。两边使用相同的 embedding 模型（text-embedding-3-large）和相同的 process_rule（hierarchical mode）。尽管在 Dify chunk viewer 中看到的 chunk 内容完全一致，但检索得分 API 上传结果为 0.69，UI 上传结果为 0.99。

报错原文

Method: Dify UI | Format: .docx | Score: 0.99
Method: API create-by-file | Format: .txt | Score: 0.69
Chunk content is confirmed identical in the Dify chunk viewer. Only the upload method differs.

原因分析

有两个主要贡献原因：

格式特定的文本提取管道差异（可能原因）： .docx 文件通过 WordExtractor 处理，保留段落、超链接、表格等结构信息；.txt 文件通过 TextExtractor 处理，以线性文本方式读取并涉及编码检测。两者最终都经过 CleanProcessor.clean() 和 remove_extra_spaces 逻辑，因此预处理规则本身没有区别。但提取阶段引入的细微差异（如空白字符处理、换行模式）可能导致送入 embedding 模型的文本存在差异，这些差异在 chunk viewer 中已被标准化，但实际存储的 embedding 向量不同。
Hierarchical Mode API 缺陷（最可能原因）： 存在已知 bug (#35858)，即通过 API 调用 hierarchical chunking 时可能静默失败或行为不一致。ParentChildIndexProcessor 缺少 ParagraphIndexProcessor 中存在的自动模式回退逻辑。如果 API 请求中的 hierarchical 规则匹配有偏差，父子块结构可能与 UI 生成的不同，直接影响检索评分。

环境排查

Dify 版本：Cloud (无法确认内部版本号，Issue 中标注 1.14.0 相关)
Embedding 模型：text-embedding-3-large（两边相同）
API 端点：POST /v1/datasets/{dataset_id}/document/create-by-file
分块模式：hierarchical，parent_mode 为 paragraph
是否通过 API 设置了 process_rule.mode 为 "hierarchical"（非 automatic 或 custom）

解决步骤

确认 API 请求中的 process_rule 设置完全匹配 UI 实际发送的参数。 检查 dataset 的最新 process rule，确保所有子字段（parent_mode，segmentation，subchunk_segmentation）与 UI 完全一致。可优先尝试明确设置 process_rule.mode 为 "hierarchical"，而不是 "automatic" 或 "custom"。
作为临时工作方法，尝试通过 API 上传 .docx 文件而非 .txt 文件，以消除提取管道差异带来的变量。
排查 Hierarchical Mode API 缺陷： 参考已知 bug #35858，确认是否有针对该问题的修复版本。在 API 调用中避免使用可能导致规则匹配不成功的配置，确保 process_rule 的所有层级与 UI 行为一致。

验证方法

使用相同的查询语句分别测试通过 UI 上传的 .docx 文件和通过 API 上传的 .txt 文件（或 .docx 文件）的检索得分。如果得分恢复一致（预期均接近 0.99），则问题解决。同时检查 chunk viewer 中显示的文本与实际 embedding 的文本是否完全相同（可通过导出 chunk 对比）。