在 RAGFlow 中丢失中文文档内容,先不要急着换向量模型或调 chunk 大小。更直接的方向是检查从文档解析到文本切分的整条链路,尤其是解析器输出文本的编码,以及分词器读取该文本时使用的编码参数。两者不一致时,中文往往以乱码或空字符形式被丢弃。
先判断:丢失发生在解析阶段还是切分阶段
丢字现象出现在不同位置,对应的处理方式也不一样。可以按下面几个特征快速区分。
- 解析后预览文本就缺字:问题在文档解析器,看解析器的编码参数或依赖库是否识别中文编码。
- 解析后文本完整,但入库检索时中文命中不全:问题可能在分词器,检查分词器初始化参数是否强制了非 UTF-8 编码。
- 日志里出现 UnicodeDecodeError,或在页面看到成片乱码:这是编码不匹配的典型信号。
检查分词器编码参数
分词器负责把解析出的文本切成词或字符。如果读入的文本是 bytes 类型,必须显式指定解码编码;如果已经是 str,则默认按 Unicode 处理,但仍要确认环境 locale 不是 C 或 POSIX,以免 Python 在控制台回显时误判。
# 在调用分词器前,确保文本是 str 且为 UTF-8
if isinstance(raw_text, bytes):
text = raw_text.decode('utf-8')
else:
text = raw_text
# jieba 示例,cut 返回生成器
seg_list = jieba.cut(text, cut_all=False)如果你在容器内运行 RAGFlow,建议同时设置环境变量 LANG=zh_CN.UTF-8 和 LC_ALL=zh_CN.UTF-8,并在启动前确认 locale 生效。
检查文档解析器的编码设置
文档解析器把 PDF、DOCX、TXT 等原始文件提取成纯文本。TXT 文件若源编码非 UTF-8,解析器读入时容易丢字;PDF 若为扫描件,则要关注 OCR 引擎输出的编码;DOCX 内部是 XML 结构,通常由库自动处理,不需要额外设置。以下以 PyMuPDF 提取 PDF 为例:
import fitz
doc = fitz.open('中文文档.pdf')
for page in doc:
text = page.get_text('text')
# 若 text 中中文缺失,先检查 PDF 字体映射,而不是继续调编码参数如果自定义了解析器,需要注意读取文件时显式指定编码,例如 text = f.read(encoding='utf-8'),不要依赖系统默认编码。
验证清单
- 准备一份 UTF-8 编码的纯中文 TXT 文件,上传到知识库,解析完成后查看页面预览文本,确认是否完整。
- 将同一文件另存为 GBK 编码再上传,对比解析结果。若 GBK 版出现乱码或丢失,说明链路默认按 UTF-8 处理,需要把源文件统一转为 UTF-8,或调整解析器参数匹配源编码。
- 查看服务日志,搜索 encoding、codec、Unicode 等关键词,确认是否有警告或报错。
- 通过 API 或数据库查询已入库的文本片段,直接搜索一个较长的中文关键词,验证分词器是否完整保存了中文内容。
以上步骤只能定位到环节,具体配置项名称需要结合你部署的 RAGFlow 版本和代码确认。如果检查后仍丢失,优先怀疑不是编码问题,而是文件本身损坏、OCR 模型不支持中文或切分策略删除了空字符串。