PixelRAG 卡在渲染依赖，多数情况下不是“缺一个包”，而是分属两层的问题：一层是 Python 包在 import 阶段就加载不到系统共享库，另一层是包本身能导入、真正调用渲染时找不到命令行工具或后端二进制。判断顺序建议先固定报错发生在哪一阶段，再去核对系统库和 Python 包清单；直接卸载重装 Python 包，往往改不动系统层缺失这一半的原因。

遇到渲染报错，先用 python -c 触发导入、再看报错是 ImportError/OSError: cannot open shared object file 还是调用期的渲染异常，就能大致分清系统库与 Python 包。适用场景是安装或首次运行失败；动作是按报错栈分层、在隔离环境重装依赖、跑最小渲染脚本；验证方式是生成非零尺寸的图片文件；边界是最终仍需按本机发行版和 Python 环境确认。

保存完整报错栈，确认报错发生在导入阶段还是渲染调用阶段

先把现场固定下来，否则后面每换一次命令，报错都会变。建议一次记录这几项，写进一个临时文本里：

• 完整命令行与当时的工作目录；
• 从 Traceback (most recent call last) 起到底部最后一行的全部 stderr，不要只截最后一句；
• python -V、which python、pip list 的输出；
• 系统发行版与架构，例如 cat /etc/os-release 和 uname -m。

导入阶段和调用阶段的报错含义不同。导入阶段的典型形式是 ImportError: libGL.so.1: cannot open shared object file、OSError: cannot load library 'libpango-1.0-0'，说明 Python 包已经装上，但包在装载时找不到它依赖的系统共享库。调用阶段的典型形式是 PDFInfoNotInstalledError、FailedToExecuteCommand、Unable to get page count，说明共享库层面已经过关，是运行期去调用外部命令或后端时失败。

用下面这条命令做最小复现，把导入和调用分开：

# 只测导入，不触发渲染
python -c "import pdf2image; print(pdf2image.__file__)"
python -c "import fitz; print(fitz.__doc__)"

# 触发一次真实调用（把 sample.pdf 换成你自己的文件）
python -c "from pdf2image import convert_from_path; convert_from_path('sample.pdf', first_page=1, last_page=1)"

检查系统层渲染库是否可被命令行调用

这一步只关心“系统里有没有、路径可不可见”，不碰 Python 环境。先看二进制是否在 PATH 中：

which pdftoppm mutool gs
pdftoppm -v
mutool -v
gs `--version`

预期输出是打印出各自的路径和版本信息。如果 which 没有任何返回，就是系统层缺工具。再看共享库是否被动态链接器收录：

ldconfig -p | grep -Ei 'poppler|mupdf|pango|cairo|libGL|fontconfig|freetype'

这条命令应当能列出若干条带路径的记录。记录为空或只有少数几条，说明对应库在系统层面不可见于默认搜索路径。需要安装的库大致分几类：PDF 渲染工具集（Poppler 工具）、MuPDF 命令行工具、Ghostscript、图形与字体基础库（libGL、libSM、libXext、cairo、pango、fontconfig、freetype）。按发行版包管理器补齐，例如 Debian/Ubuntu 系用 apt-get install 装对应包，RHEL 系用 dnf install；具体包名以 apt-cache search 或 dnf search 的结果为准，不要凭记忆硬拼。

在隔离环境里重装 Python 依赖并导出清单

系统库补齐后，Python 侧的环境污染和版本冲突要单独排除，所以不要动全局 site-packages，另建虚拟环境：

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install -r requirements.txt
pip freeze > requirements.lock.txt
pip check

导出清单后重点核对三件事：一是渲染相关包是否只有一个来源，比如同时装了 pdf2image 和 pymupdf 时，确认 PixelRAG 实际走的是哪一条路径；二是同一功能是否有重复包（例如多个 PDF 解析库），重复安装容易让导入选中非预期实现；三是 pip check 是否报告依赖不满足。requirements.lock.txt 建议和报错记录放在一起，方便下次对照是否环境发生了变化。如果项目本身用 pyproject.toml，则改用 pip install -e .，导出方式不变。

写一段最小渲染脚本，把 PDF 第一页转成图片

最小脚本的作用是绕开 PixelRAG 的业务逻辑，只验证渲染链路。把下面骨架存成 render_check.py，和一份可正常打开的 sample.pdf 放在同一目录：

import sys
from pathlib import Path

src = Path(sys.argv[1] if len(sys.argv) > 1 else "sample.pdf")
out = Path("page1.png")

try:
    from pdf2image import convert_from_path
    pages = convert_from_path(str(src), first_page=1, last_page=1, dpi=100)
    pages[0].save(out)
except ImportError as e:
    print("IMPORT_FAIL:", repr(e))
    raise
except Exception as e:
    print("RENDER_FAIL:", type(e).__name__, repr(e))
    raise

print("OUT:", out.resolve(), "SIZE:", out.stat().st_size)

如果本机走的是 PyMuPDF，把中间三行换成 import fitz; doc = fitz.open(str(src)); doc[0].get_pixmap(dpi=100).save(out) 即可，其余判断逻辑不变。运行 python render_check.py sample.pdf，成功判据很明确：脚本正常退出，打印出 OUT: 和 SIZE:，且 page1.png 存在、字节数大于零。

失败时同样要留原始信息：把 IMPORT_FAIL 或 RENDER_FAIL 那一整行连同上面的 Traceback 一起保存下来，这比“渲染失败”四个字有用得多。要注意脚本输出的尺寸只证明“写出了文件”，不等于渲染内容正确，页面是否空白仍需人工打开图片确认；这部分属于人工核对，不要用脚本输出替代。

分别记录缺系统库与缺 Python 包时的报错特征，形成对照

把两类报错的特征做成对照，比记解决办法更省事：

判断顺序建议是：先看报错里有没有 .so 文件名或共享库加载字样，有就按系统库处理；再看是不是纯 ModuleNotFoundError，是就在虚拟环境里补 Python 包；两者都不像、却报 FailedToExecuteCommand 这类调用期错误，就回头用 which pdftoppm 确认命令行工具是否在 PATH 中，并检查服务进程或容器里的 PATH 与交互式 shell 是否一致。每次处理完只改动一层，然后重跑同一份最小脚本验证，避免同时改系统库和 Python 包后分不清是哪一步生效。