文档解析失败必须立即定位原因：先用file命令检查PDF是否损坏或加密，再验证页数（≤400）、大小（≤1GB）及格式规范；调用import_task_list接口查失败详情；清理pending/processing文档、清除chunk_cache缓存，并确认kb_type为rag。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
火山引擎知识库文档解析失败时，无法进入后续向量化与检索流程，必须立即定位是文件本身问题、接口调用异常还是任务状态卡滞。
确认PDF文件是否符合解析规范
打开终端执行：file your_doc.pdf，检查输出是否含“PDF document”字样。若显示“data”或“cannot open”，说明文件已损坏或被加密——【加密PDF无法被豆包PDF解析算子处理，且不会返回明确错误码，任务会静默失败】。
用浏览器直接打开该PDF，验证能否正常渲染。若出现“需要密码”“禁止复制”弹窗，或文字全部乱码，则必须先解密或转为无保护副本。
单文件页数超过400页时，解析任务必然超时中断。此时需手动切分：用pdfseparate -f 1 -l 400 input.pdf output_%d.pdf拆成多份再逐个提交。
检查导入任务状态与失败原因
调用import_task_list_chunk_import_task_list_get接口，传入kb_id和status=failed参数，获取最近3条失败任务记录。
重点查看响应中data.items[0].message字段内容：
- 若含
"invalid pdf format"：文件非标准PDF，可能是Word另存为PDF时未勾选“文档结构”选项； - 若含
"file size exceeds limit"：文件总大小＞1GB，需压缩图片或拆分文档； - 若含
"timeout"：页面含大量矢量图或嵌入字体，应切换至detail模式重试。
注意：【status参数为空时默认只返回total统计，不返回具体任务列表，必须显式传入status=failed才能查到失败详情】。
重试前必须清理的三个隐藏状态
第一步：在火山引擎控制台→知识库→对应知识库→「文档管理」页，手动删除所有状态为pending或processing的文档条目。这些条目会锁住KB写入通道，导致新任务始终排队不执行。
第二步：登录RAGFlow服务所在服务器，执行docker exec -it ragflow-server bash -c "rm -rf /app/storage/chunk_cache/*"清除本地缓存碎片。缓存残留会导致新上传文件被识别为重复而跳过解析。
第三步：确认当前知识库kb_type为rag而非qa。若误设为qa类型，即使上传PDF，系统也会忽略解析步骤直接报“no chunk generated”。
