FastGPT 知识库出现乱码：从文件编码到解析的排查顺序
文档传进知识库，一看内容全是问号、方块字，或者莫名其妙的符号。
这类问题九成不在 FastGPT 里，在文件本身或者上传之前的处理环节。 这篇按链路排查，从最可能的开始。
具体的配置项和支持格式以 FastGPT 官方文档为准。这篇讲的是排查方法，跟版本关系不大。
第一步：确认是哪种「乱码」
不同的乱像对应完全不同的原因，先分清能省很多时间。
整段变成问号或方块字（如 ??? 或 □□□） → 典型的编码问题，看第二步。
部分字符正常、部分是奇怪符号 → 也是编码问题，但可能是混合编码，看第二步。
文字能看懂但顺序乱了、段落错位 → 不是编码问题，是解析问题，看第三步。
内容是空的或者只有零星几个字 → 大概率是扫描件，看第四步。
只有表格部分乱 → 结构丢失，看第五步。
第二步：文件编码（最常见）
中文文本文件的编码是老问题了。同一份文件，在 Windows 上用某个编辑器存的，和标准 UTF-8 可能不一样。系统按 UTF-8 去读一个非 UTF-8 的文件，就会出现问号和方块字。
判断方法：用支持查看编码的文本编辑器打开源文件，看它识别成什么编码。
处理办法：把文件另存为 UTF-8 再上传。
批量处理时要注意：如果你有几百份文件，编码可能不统一——有的是这个有的是那个。写脚本转换时不能假设都是同一种，要逐个检测。这一步在文档摸底阶段就该做，别等传完发现一半是乱的。
一个容易忽略的点：从老系统导出的数据、多年前的文档、不同人在不同电脑上写的文件，编码混乱的概率最高。
第三步：解析顺序错乱
如果文字本身没问题，但读起来前言不搭后语，那是解析环节的问题。
常见原因：
分栏排版。 双栏或多栏的 PDF，解析时可能按整行读——把左栏第一行和右栏第一行连成一句，读起来完全不通。
页眉页脚混入。 每页的页眉页脚被当成正文插进内容中间，打断了原本的段落。
图文混排。 文字框、批注、水印的文字被混进正文。
判断方法：在知识库里直接看解析后的分段内容——这一步很关键，不要只看原文件觉得没问题就以为传进去也没问题。 你看到的和系统读到的可能完全是两回事。
处理办法：这类文档最好先转成纯文本，人工过一遍再上传。如果量大，考虑换个来源——很多时候同一份内容有 Word 原件，用原件比解析 PDF 干净得多。
第四步：扫描件
扫描版 PDF 本质是图片，没有文字层。 传进去系统读到的是空的或者零星几个识别错的字。
判断方法：用 PDF 阅读器打开，试着用鼠标选中一段文字。选不中就是扫描件。
处理办法：先做 OCR。但要注意 OCR 的错误是隐蔽的——它不会报错，只会把「8」认成「B」、把「0」认成「O」。这类错误在知识库里查不出来，只会在用户拿到错误答案时暴露。
所以扫描件转换之后必须人工抽查，尤其是含数字、编号、金额的部分。
第五步：表格结构丢失
表格是单独一类问题。二维表被拉平成文字后，行列的对应关系就没了。
一张「姓名 / 部门 / 分机号」的表，拉平之后可能变成一串没有分隔的文字。问「张三的分机号」，系统找不到答案——不是检索的问题，是信息在解析阶段就丢了。
处理办法：
- 量不大：手工转成问答形式或者「姓名：张三，部门：技术部，分机号：xxx」这样的句子。最可靠。
- 量大：考虑用专门的表格解析方案，但效果要实测，不能想当然。
排查顺序小结
按这个顺序走，每一步都有明确的判断方法：
- 看乱码的形态 → 定位是编码问题还是解析问题
- 查文件编码 → 非 UTF-8 就转换
- 看知识库里解析后的实际内容 → 不要只看原文件
- 确认是不是扫描件 → 选不中文字就是
- 单独检查表格部分 → 结构有没有保住
第三步是最容易被跳过的一步，也是最有价值的一步。很多人反复调参数、换模型，却从没看过系统实际读到了什么内容。
打个比方：这就像抱怨一个人复述得不准，却从没确认过你递给他的那张纸上到底写了什么。纸上如果是花的，他复述得再流利也没用。
还有两类容易被误认成乱码的情况
一、特殊符号和公式。 数学公式、化学式、带上下标的内容，解析后经常变成一串看不懂的字符。这不是编码错误，是这类内容本来就难以用纯文本表达。
处理办法：如果这类内容是核心（比如技术标准、实验规程），要么改写成文字描述，要么接受它检索不到——别指望调参数能解决，信息在解析阶段就已经变形了。
二、繁简混排和异体字。 从港台资料或老文档来的内容，可能混着繁体字、异体字。它们能正常显示，看起来没问题，但检索时会出问题——用户用简体提问，匹配不上繁体的文档内容。
判断方法：用简体和繁体分别搜同一个词，看结果是否一致。
处理办法：上传前统一转成简体。这一步在处理历史资料时很值得做。
这两类的共同特点是：内容看起来是好的，但检索不到。 比明显的乱码更隐蔽，往往要等用户反馈才发现。
预防比排查划算
如果是做项目，这些工作应该在报价之前完成：
文档摸底要看真实文件，不是听甲方描述。甲方普遍会低估自己文档的混乱程度——不是不诚实，是他们太熟悉自己的资料，意识不到外人（和机器）看不懂。
把文档预处理的工作量单独算进报价。 这部分经常占到整个项目的一半以上，却经常被算成零。
在合同里写清楚文档治理的责任归属。 是甲方负责整理出干净的有效版本，还是你来做？含糊过去的结果通常是你在做，而且没收到钱。
完整的文档摸底方法见知识库项目七成工作量在文档。
如果文档处理干净了检索还是不准，那是另一类问题，见 Dify 知识库检索不准怎么排查——排查方法对各平台通用。
文档预处理量大、需要定制处理流程的，也可以找我们聊聊。