故障处理
Codex 读不到 PDF?先确认读取方式,再抽查漏读与错读
Codex PDF 读不到、CLI 说无法读取,或摘要漏掉扫描页和表格?先核执行端与实际读取工具,再对照原页检查文字、图片、数字单位和行列归属,明确局部抽查不代表全文读全。
把 PDF 路径交给 Codex,它说无法读取;或者已经生成摘要,却漏掉扫描页、图片里的金额,甚至把表格数字归到了错误的行。先确认这次究竟走了什么读取方式,再核对指定页的实际内容。 文件存在、附件出现、工具退出成功和模型理解正确,是不同的证据。
本文处理 Codex PDF 读不到、codex read pdf cli 和 PDF 表格内容漏读。目标是得到一份有页码、有实际工具记录、有原页对照的结果,并说明失败和未验证的范围。若只是路径不存在或文件列表没有目标,先看文件位置与实际读取验证,不在这里重复整套路径排查。
先按现象找下一步
| 现象 | 先做什么 | 不能直接认定 |
|---|---|---|
| 模型说“不能直接读 PDF” | 第 1 步:看执行位置、可用工具及本轮调用 | 当前所有 Codex 都不支持 PDF |
| 文件有预览,回答却像没看 | 第 1 步:核对本次输入和读取范围 | 预览过就已经送达并理解全文 |
| 提取命令成功,但没有文本 | 第 2 步:打开对应原页并检查所用路线 | PDF 是空的,或一定缺 OCR |
| 摘要只包含部分文字 | 第 2、3 步:检查图片区域、页码与截断 | 有文字输出就已经读全 |
| 表格数字都有,结论却不对 | 第 3 步:核对表头、行列、单位和脚注 | 数字都出现就证明单元格归属正确 |
1. 确认客户端、执行位置和实际读取方式
适用条件: 还没有取得可复核的读取输出,或仅有一句“我读不了”。先记录客户端及版本、本地/远程/云端、目标文件和本次需要的页码。路径或引用只能帮助定位,不能代替读取证据。
当前 OpenAI 文件工作说明区分了各端的文件查看方式;环境说明还区分本机与云端工作文件:
| 使用位置 | 应核对的入口和环境 | 验证边界 |
|---|---|---|
| 桌面应用中的 Codex | 本次消息实际使用的附件或任务可访问的文件;查看对应工具记录 | 桌面可预览 PDF,不等于预览内容已全部进入本轮分析 |
| Codex CLI | CLI 运行主机上的明确路径,以及已有的解析、渲染或查看工具 | 官方说明 CLI 没有同样的视觉文件预览/批注界面;这不等于任务不能调用读取工具 |
| IDE 扩展 | 当前工作区、扩展实际执行位置,以及本次所用的文件入口 | 在兼容阅读器中打开 PDF,与 Codex 实际读取它分开核验 |
| Codex Cloud | 当前任务独立工作区中是否有文件及所需工具 | 本机文件和进程不会自动转移过去;不能只给本机路径就认定云端可读 |
| ChatGPT Work 网页 | 本次消息的附件状态、工具输出与页面可核对结果 | 官方列有 PDF 附件流程,不能直接套成所有 Codex Cloud 入口的承诺 |
WSL、SSH、容器和不同 worktree 也要确认实际执行位置。本机装有库,不代表远端任务也有。本文不设各客户端统一大小上限,也不把 API 或其他产品的文件限制套到 CLI;遇到明确限制时,以该入口当前官方说明和原始错误为准。
先检查当前环境已有的工具或技能,优先使用可用路线,不必先安装新软件。若技能存在却未调用,按Skills 加载与显式调用核对;不能靠往 AGENTS.md 写“会读 PDF”就证明能力已经启用。
可先给当前任务一个限定请求;其中路径和页码要替换成实际值。这是正常 Codex 请求,会使用账号额度:
这次只核对我已授权读取的小型非敏感 PDF,不修改原件或项目配置。
目标:<实际文件或本次附件>;范围:PDF 物理页第 3 页。
先确认当前执行位置和已有的读取方式,再实际读取指定页。
报告所用工具、页码范围、实际输出或原始错误,不根据文件名猜内容。
如需新依赖、额外权限或外部服务,先说明缺什么,不自行上传文件或改权限。
未读取、提取为空、输出被截断、只取得文字但没检查图片,请分别写明。
预期结果: 活动记录里能对应到本轮的读取、提取或渲染及其结果。只看模型自述、工具列表或附件预览,还不能确认完整送达机制或理解质量。答不出文件名也只能记为待核,不能据此定位上传失败。
出现路径/权限错误时回到文件指南;缺依赖则记录实际环境和缺失工具,在获准的环境中选择下一步,不默认全局安装或扩大权限。工具已经调用但正文为空、乱码或不完整时,进入下面的内容核对。
2. 用一页提取与原页画面对照,区分文字和图像内容
适用条件: 已有可读取的小型非敏感 PDF,需要验证文本提取结果。先在阅读器打开对应页,确认 PDF 物理页序号;封面、罗马数字和印刷页码可能使“书上第 3 页”与文件第 3 页不同。
以下是已有 Python 3 与 pypdf 环境的一条可选路线,不是 Codex 必需组件。先在任务实际执行端确认该解释器能导入库:
python3 -c "import pypdf; print(pypdf.__version__)"
命令或模块不存在时,先按任务环境与 PATH检查,不把依赖缺失当作 PDF 不可读。Windows 使用已核对的 Python 启动方式;不直接照搬另一台主机的安装路径。
把下面保存为独立的 pdf_page_probe.py。它只读一个指定页,把结果输出到终端;可选的 --tables 需要同一环境已有 pdfplumber。只用于允许回显内容的小样本,不对大型、未知或含敏感数据的文件直接运行并公开输出。
import argparse
import json
from pathlib import Path
from pypdf import PdfReader
parser = argparse.ArgumentParser()
parser.add_argument("pdf", type=Path)
parser.add_argument("page", type=int, help="PDF physical page, starting at 1")
parser.add_argument("--tables", action="store_true")
args = parser.parse_args()
if not args.pdf.is_file():
parser.error("Target is not an accessible regular file")
with args.pdf.open("rb") as stream:
reader = PdfReader(stream)
if reader.is_encrypted:
parser.error("Encrypted PDF: use an authorized unlocked sample")
if not 1 <= args.page <= len(reader.pages):
parser.error("Page is outside the PDF physical page range")
text = reader.pages[args.page - 1].extract_text() or ""
print(f"page={args.page}/{len(reader.pages)}, text_chars={len(text)}")
print(text)
if args.tables:
import pdfplumber
with pdfplumber.open(args.pdf) as pdf:
tables = pdf.pages[args.page - 1].extract_tables()
print(json.dumps(tables, ensure_ascii=False, indent=2))
将占位路径替换为同一执行端上的实际文件。下面读取物理第 3 页;只有文件至少三页时才使用这个页号:
python3 pdf_page_probe.py "/actual/path/probe.pdf" 3
预期结果: 输出实际页序号、该页提取字符数及文本。text_chars 不是 token 数、覆盖率或质量评分。pypdf 官方文档说明它不是 OCR,不提取图片内部文字;提取为空也可能涉及字体、文件结构或解析问题,不能仅凭空输出确诊纯扫描件。
对照阅读器中的同一页:若画面有内容而文本为空,核所用工具是否只处理文字;若文本非空,但图片里的注释、印章或金额没有出现,记录为该路线遗漏图像区域。混合页、带旧 OCR 文字层的扫描页都不能仅按“能复制文字”判定完整或准确。
可选:单页渲染,不覆盖原 PDF
已有 Poppler 的 pdftoppm 时,可以把指定页渲染成 PNG,再用图像查看器逐项核对。先在仓库外创建一个全新的空输出目录;以下两处路径都是占位,输出前缀必须指向这个新目录,避免覆盖已有图片:
pdftoppm -f 3 -l 3 -r 144 -png "/actual/path/probe.pdf" "/new/empty/pdf-check/page"
-f、-l 在这里都设为 3,只渲染这一页。预期结果: 新目录出现对应页的 PNG,打开后与原页相符。PNG 存在只证明生成了画面,不证明它已经提供给模型或模型看懂了;需要让 Codex 查看时,继续按图片输入与识别验证确认实际查看记录及内容。
渲染失败时保留实际错误;不要因为提取失败就先改权限或转码整份文件。加密或受限文件先确认处理授权;上面的脚本主动停止,不提供绕过或解密办法。
何时考虑 OCR
在需要文字提取、对应页没有可用文字结果而画面确实有文字时,可评估已有的本地 OCR。它只是所选路线之一,不要求所有 PDF 都先转图再 OCR。
已有 Tesseract 时,先用 tesseract --list-langs 确认语言包。下面仅用于英文测试页,将路径改为刚核对的 PNG;stdout 将识别结果写到终端,不改原件:
tesseract "/actual/path/page-3.png" stdout -l eng
Tesseract 官方用法区分语言选择;缺语言包、命令失败或页面不清晰时先处理对应原因,不拿英文示例承诺中文识别效果。OCR 得到文字后仍须核否定词、数字、单位和表格;它不能自动恢复正确结构,也不能因为退出码为 0 就宣称无错。
3. 表格与混合页:抽查具体字段,保留页码和遗漏
适用条件: 已取得文字或页面画面,需要判断能否用于本次任务。不要先让模型自由总结,再只核对一句看起来合理的结论。
在同一 PDF 的目标范围内,分别选择文字、扫描、混合和表格页;有哪类就核哪类,不能用首页文本成功代表其他页。记录“物理页号+印刷页码(若有)+具体位置+原页事实+工具/回答结果”。
| 核对对象 | 具体检查 | 不通过时的下一步 |
|---|---|---|
| 文字页 | 否定词、编号、数字、小数点及单位是否完整 | 对照原页与实际提取输出,区分解析错误和回答错读 |
| 扫描页 | 是否取得正确页的清晰画面;OCR 或视觉结果是否对应 | 核选页、渲染、方向、清晰度与实际调用,再决定是否换路线 |
| 混合页 | 文本区和图片区是否都被检查,有无只读到一半 | 分别核两个区域,保留原页关系,不只提交缺图的纯文本 |
| 表格页 | 数字属于哪行、哪列、哪个表头;合并单元格、空值、脚注如何解释 | 使用适合该表的结构化提取或原页逐格核对,不把空值补成 0 |
| 跨页内容 | 下一页续表、脚注、单位及页序映射是否保留 | 带相邻页重新核对,并标出仍未覆盖的范围 |
表格需要结构信息时,上述脚本可在已有 pdfplumber 的环境中增加 --tables。例如读取物理第 4 页:
python3 pdf_page_probe.py "/actual/path/probe.pdf" 4 --tables
预期结果: 除文字外,还得到找到的表格行列列表。[] 不证明原页没有表格;工具可能未识别当前边框或布局。pdfplumber 官方说明给出表格提取及调试方法;这条路线不做 OCR,扫描表格也不能保证直接提取。成功得到列表后仍要与原页核对,防止漏表、行列错位或脚注脱离。
若要验证模型是否使用了输入内容,用没有预先透露答案的非敏感样本,在无旧答案的新测试会话里询问指定页的具体字段,再人工逐项对照。模型说“已读取”、答对文件名或章节名,不是全文读取证明。工具输出被截断时先限定所需页段、保留页号和续页关系,不反复把整份文件塞进上下文。
局部抽查不代表全文读全。 即使四类页面的样本都通过,也只说明那些页、字段和当前工具路线的表现。任务要求检查全部条款或整份表格时,应另外列出完整目标页范围、每段处理状态和未覆盖项;没有覆盖证据就不能把“抽查通过”交付成“全文无遗漏”。
隔离样例的实际结果与验收边界
2026 年 10 月 22 日,用一份自制四页英文虚构 PDF 做了本地验证,原件哈希在提取、渲染和 OCR 前后不变。所有页都实际渲染并查看,不使用用户 PDF、账号凭据或外部转换服务。
- 文字页:
pypdf提取到了Do NOT approve、编号和37.5 mg。文件第一页另标印刷页码i,不能用印刷标签替代物理页序号。 - 纯扫描页: 提取调用成功但文本为空;渲染可见内容,Tesseract 英文 OCR 的所核编号、否定词和
12.75 mL对应原页。这不是所有扫描件均可准确识别的保证。 - 混合页: 文字提取非空,却没有图片内的订单号和
6.25 USD;渲染后能见到缺失区域,英文 OCR 的所核字段对应原页。非空输出确实不能证明读全。 - 表格页: 普通提取包含所有目标数字,但不由此证明行列。用
pdfplumber得到的两条数据行、三列及表头与原页核对一致,并查看了从第 3 页续到第 4 页的脚注;不外推为其他布局或跨页表格都能成功。
实际环境为 macOS、Python 3.12.14、pypdf 6.10.0、pdfplumber 0.11.9、Poppler 26.05.0、Tesseract 5.5.1。本文不要求读者固定到这些版本;应记录自己实际使用的工具。公开样例答案用于解释结果,不能再把这些已知答案当作模型盲测。
本次未调用真实 Codex 模型,未实测各原生客户端的附件传输、Windows/远程/云端运行或中文 OCR。客户端差异依据当前官方资料核对;提取、渲染、OCR 和表格对照的本地结果,不冒充模型识别或服务端送达证明。
完成标准: 能说清文件与执行位置、实际读取方式、已核页段及字段、错读/漏读和未验证项。仍失败时,提供脱敏的客户端/工具版本、入口、物理页码、原始错误和非敏感最小样本;不公开整份私人 PDF、密码或原始会话。涉及资料上传和本机记录的顾虑,可继续核对代码发送、训练与留存边界。