文档上传后卡在“处理中”需按顺序排查：先查status是否真为processing超15分钟；再验文件格式（PDF需可选中文、Office需另存为新格式、大小≤512MB）；接着核对标签名拼写、元数据非空且无非法字符、解析模板匹配文件类型；最后强制删任务重传，并清缓存用隐身窗操作。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
火山引擎知识库文档上传后长期卡在“处理中”，无法进入可检索状态，需立即定位是文件解析失败、向量索引阻塞，还是元数据标签缺失导致任务挂起。
确认任务是否真实卡住
打开知识库管理页 → 点击对应知识库 → 进入「导入任务」列表 → 找到目标文件任务，查看其 【status 字段值】 是否为 processing 且持续超过15分钟。若 status 已变为 failed 或 completed，则非卡住，而是前端未刷新或状态同步延迟。
直接调用接口 /profile_platform/api/v2/rag/chunk/import/task/list?kb_id=YOUR_KB_ID 获取最新任务快照，比页面更实时。注意：页面每30秒轮询一次，而接口可手动触发。
检查文件内容与格式合规性
方法一：PDF类文档必须能被OCR准确识别文字。扫描版PDF（纯图无文本层）会导致解析超时或静默失败。用Mac预览打开该PDF → 按 Cmd+A 全选 → 若无法高亮文字，则属于扫描件，需先转文字版再上传。
方法二：Word/PPT/Excel 文件内不能含加密、损坏对象或嵌入不可读OLE控件。将文件另存为 .docx（非 .doc）、.pptx（非 .ppt）、.xlsx（非 .xls），再重试上传。
方法三：单文件大小不能超过512MB。超限文件会被截断处理，任务状态停留在 processing 且无报错提示。用终端执行 ls -lh your_file.pdf 验证实际体积。
验证标签与元数据配置
第一步：进入该知识库的「标签管理」页，确认你为该文档设置的标签名（如 account_id、product_name）已真实创建，且拼写完全一致——大小写、下划线、空格均敏感。
第二步：点击文档右侧「编辑元数据」，检查字段值是否为空或含非法字符（如中文冒号、全角括号、控制符）。【空值或非法字符会中断向量化流程，但不返回错误】。
第三步：若使用了 chunk_settings_type=local，必须确保所选解析模板支持该文件类型。例如：选择「合同解析模板」上传会议纪要，会导致 chunk 切分失败，任务停滞。
强制终止并重试任务
调用接口 DELETE /profile_platform/api/v2/rag/chunk/import/task/{task_id} 删除当前挂起任务。task_id 从上一步接口响应的 data.list[0].id 中获取。
删除后，立即重新上传同一份文件，但务必在上传前完成：① 清除浏览器缓存；② 关闭所有知识库相关Tab页；③ 使用隐身窗口操作。这能避免前端残留旧任务ID干扰新任务注册。
上传完成后，等待3分钟，再次调用 GET /profile_platform/api/v2/rag/chunk/import/task/list 查看新任务 status 是否变为 queued → processing → completed。若仍卡在 processing 超过8分钟，说明后端服务异常，需提工单并附上 task_id 和 kb_id。
