问题排查方案.md

问题排查方案

程序运行部分

1. 该程序尚处在开发过程中，逻辑漏洞不可避免。如果运行出错，请按照项目主页末尾的更多内容-获取更新来更新程序，然后再试一次。如果依旧出错，请请继续进行后续步骤。
2. 如果运行时产生报错，请按照下表中“执行成功的最后一步”列找到对应解决方案；如果运行正常但处理结果损坏，请打开根目录下的data文件夹，并找到出错的任务对应的缓存文件夹（例如20250306124605_d56W1A，每个缓存文件夹中的input_pdf中存储了该流程的原始 PDF 文件），然后按照下表中“输入输出数据情况”列找到对应解决方案。如果表中未列出你的问题，请跳转至第5条。下表中所列出的解决方案覆盖了 90% 以上的情况，因此请务必先试试它们。

输入输出数据情况	执行成功的最后一步	解决方案
mark/input_image非空，automark_raw_data为空	PDF 转换为图像	跳转至3
automark_raw_data非空，automarker_colour为空	OCR 识别与投影	跳转至4
raw_content非空，llm_processed_content为空	内容预处理	跳转至5

3. 如果选择使用阿里云的服务，程序提供了本步骤常见问题的快速排除测试脚本。请运行tools文件夹下的windows_aliyun_ocr_test.bat或macos_aliyun_ocr_test.command，运行完成后，观察该目录下是否出现error_[yyyymmddhhmmss].txt文件。如果有相应文件，请根据文件的报错内容进行故障排除。
   1. ocrServiceNotOpen：参照申请云服务账户教程的1.2 通用文字识别 API的第1条。注意应选择通用文字识别而不是 OCR 统一识别。
   2. noPermission：参照申请云服务账户教程的1.2 通用文字识别 API的第4条。
   3. Aliyun credentials not found in environment variables或Incorrect API key provided：参见主页Step 2 配置环境，确保 API-KEY 正确申请和配置。
4. 此问题难以复现，目前并未找到任何有价值的报错信息，建议换一个系统后再试一次。目前能给出的100%成功的解决方案是：租一个阿里云Ubuntu服务器，把这个程序部署在服务器上。
5. 如果选择使用阿里云的服务，程序提供了本步骤常见问题的快速排除测试脚本。请运行tools文件夹下的windows_qwen_test.bat或macos_aliyun_ocr_test.command，运行完成后，观察该目录下是否出现error_[yyyymmddhhmmss].txt文件。如果有相应文件，请根据文件的报错内容进行故障排除。如果是其他环境，也请先手动检查问题是否出现在下方所提及的内容中。
   1. AccessDenied.Unpurchased：前往通义大模型官网，点击右上角的用户，然后点击费用与成本，进行小额充值，然后再试一次。
   2. InvalidAccessKeyId.NotFound或Aliyun credentials not found in environment variables：参见主页Step 2 配置环境，确保 API-KEY 正确申请和配置。
   3. 若该脚本测试正常但输出的是损坏的文件，请检查目录中是否存在可能导致模型截断响应的敏感信息。
   4. 更多错误，请参考 DashScope 错误信息。
6. 若上述所有步骤均已完成但依旧无法运行，或表格中没有列出你的问题，请将data文件夹中出错的任务对应的缓存文件夹打包发送至[email protected]中。为过滤无效咨询，收取费用 20 RMB / 次，付款码位于static文件夹下。如果发送邮件未得到回复，可提出 Issue。

环境配置部分

如果自动环境配置脚本windows_install.bat或macos_install.sh运行时出现问题，请手动配置运行环境：

1. Python 版本 == 3.11（其他版本未测试）
2. poppler 版本 == 24（choco 包管理器貌似最高支持到 22，建议 Windows 用户前往 poppler 官方网站下载）
3. requirements.txt 中的全部依赖

环境配置完毕后，请回到项目主页，从 API-KEY 配置部分（2.2.1 的第 2 条或 2.2.2 的第 4 条）继续。

由于环境配置并非项目核心内容，如需咨询，收取费用 50 RMB / 次，付款码位于static文件夹下。请先向[email protected]发送邮件，得到回复后再支付。