1. 大文件PDF处理的真实困境与破局思路
1.1 为什么300页PDF成了AI的"消化不良"
做过文档处理的人都有一个共同体会：几十页的PDF丢给大模型，回答质量还不错；一旦页数上到两三百页，情况就完全变了。要么是接口直接报超出上下文长度的错误，要么是模型读到后面忘了前面，问它第15页讲了什么，它给你编一段第80页的内容。这不是模型不行，而是上下文窗口这个物理瓶颈在起作用。
大语言模型的上下文窗口就像一张工作台。你给它300页PDF，相当于把300页纸全部摊在这一张桌子上，桌子放不下，它就只能扔掉一部分。目前主流模型的上下文窗口从几万到几十万token不等，而一页中文PDF转成文本后，通常在500到1500个token之间。300页就是15万到45万token，再加上你提问的内容和模型回复的预留空间，很容易就顶到上限。更麻烦的是，即使勉强塞进去了，模型对中间部分的注意力也会明显衰减，业内管这叫"lost in the middle"现象——开头和结尾记得清楚，中间一大段基本是模糊的。
所以问题的本质不是"换个更大的模型"就能解决，而是处理策略的问题。把整本书一次性塞进去，本身就是一种偷懒的做法。真正靠谱的思路是：把大文档拆成小块，一块一块地读，读完一块记录一块的要点，最后再汇总。这就像人读一本厚书，你不会指望一眼扫完记住所有内容，而是逐章阅读、做笔记、最后回顾。
1.2 分页读取脚本到底解决了什么问题
这个开源脚本的核心价值，就是把"逐页读取、逐页处理、结果落盘"这套流程自动化了。它做的事情说起来不复杂：用Python打开PDF，按页提取文本，每一页单独送给AI处理，把AI的输出按页保存成JSON，最后可以选择合并成一份完整的结果文件。
听起来简单，但里面有几个关键设计决定了它好不好用。第一是逐页隔离，每一页都是独立的请求，不会互相干扰，也就不存在上下文溢出。第二是结果持久化，每处理完一页就立刻写入JSON文件，哪怕中途程序崩了、网络断了，已经处理完的页不会丢，重新跑的时候可以跳过。第三是可恢复性，脚本会记录处理进度，300页分三次跑完也没问题。
这套方案特别适合几类人：需要把长篇报告、论文、合同、说明书转成结构化摘要的办公场景；做文档问答系统、需要预先建立页面级索引的开发者；以及手头有大量PDF资料、想批量提取关键信息做知识库的团队。哪怕你Python刚入门，只要照着步骤配好环境，也能跑起来。
1.3 整体方案的技术选型逻辑
为什么用Python而不是别的语言？因为PDF解析和AI接口调用这两个领域，Python的生态最成熟。解析PDF有pypdf、pdfplumber、PyMuPDF这些库，调用AI接口有各家官方SDK，JSON处理是Python内置能力，整个链路不需要引入额外依赖。
为什么输出用JSON而不是直接写文本？JSON的结构化特性在这里非常关键。每一页的记录包含页码、原始文本、AI处理结果、处理时间戳、状态标记等字段，用JSON存下来，后续无论是做检索、做统计、还是做二次加工，都能直接按字段读取。如果存成纯文本，页码和内容的对应关系就得靠解析文本去猜，很容易出错。
为什么强调"一页一页读"而不是"按固定字数切块"？因为PDF的页是天然的逻辑单元。一页通常对应一个完整的段落、一张表格或一个小节，按页切分能最大程度保留语义完整性。按字数硬切，很可能把一句话、一个表格从中间劈开，AI读到的就是残缺信息，输出质量自然下降。当然，如果某一页内容特别长，脚本里也可以加一个二次切分逻辑，但默认按页处理是最稳妥的起点。
2. 环境搭建与核心依赖的实操配置
2.1 Python环境准备：从零开始的安装路径
如果你机器上还没装Python，第一步就是去Python官网下载安装包。这里有个细节很多人踩坑：Windows安装时一定要勾选"Add Python to PATH"这个选项，否则装完之后在命令行敲python会提示找不到命令。Mac用户如果用Homebrew，直接brew install python更省事。版本选择上，建议用3.9到3.11之间的版本，太老的版本部分库不支持，太新的版本偶尔会遇到依赖兼容问题。
装完之后验证一下，打开终端或命令行，输入：
python --version能正常输出版本号就说明装好了。如果提示找不到命令，Windows用户检查一下环境变量，Mac和Linux用户试试python3 --version。这一步看着基础，但我见过太多人卡在这里，后面所有步骤都进行不下去。
2.2 必装依赖库清单与安装命令
这个脚本涉及的核心库不多，但每一个都有明确用途。我整理成一张表，方便你对照安装：
| 库名称 | 用途 | 安装命令 |
|---|---|---|
| pypdf | 读取PDF、按页提取文本 | pip install pypdf |
| pdfplumber | 处理复杂版式、提取表格 | pip install pdfplumber |
| requests | 调用AI接口（如果用HTTP方式） | pip install requests |
| tqdm | 显示处理进度条 | pip install tqdm |
一次性安装可以这样写：
pip install pypdf pdfplumber requests tqdm如果你用的是国内网络环境，pip下载可能比较慢，可以加一个镜像源参数：
pip install pypdf pdfplumber requests tqdm -i https://pypi.tuna.tsinghua.edu.cn/simple提示：不要盲目用
pip install装一堆用不到的库。依赖越少，出问题的概率越低。上面这四个库已经能覆盖绝大多数场景，表格提取用pdfplumber，纯文本提取用pypdf就够了。
2.3 目录结构与配置文件设计
脚本跑起来之前，先把目录结构规划好，后面维护起来会轻松很多。我习惯用这样的结构：
pdf_reader/ ├── input/ # 放待处理的PDF ├── output/ # 存放处理结果 │ ├── pages/ # 每页单独的JSON │ └── merged.json # 合并后的总结果 ├── progress.json # 处理进度记录 ├── config.py # 配置参数 └── main.py # 主脚本config.py里放几个关键配置项：PDF文件路径、输出目录、AI接口的地址和密钥、每页处理的超时时间、失败重试次数。把这些抽出来单独放，好处是换一个PDF处理时，不用去改主脚本的代码，只改配置就行。
# config.py PDF_PATH = "input/report.pdf" OUTPUT_DIR = "output" API_URL = "你的AI接口地址" API_KEY = "你的密钥" TIMEOUT = 60 MAX_RETRY = 3注意：API密钥千万不要硬编码在会提交到代码仓库的文件里。本地测试可以放config.py，但如果要分享代码，记得把密钥换成环境变量读取的方式，比如
os.getenv("API_KEY")。
3. 逐页读取与AI处理的核心实现
3.1 PDF按页提取文本的两种方案对比
提取PDF文本这件事，不同库的表现差异很大。pypdf胜在轻量和稳定，对标准生成的PDF支持很好，提取速度快。pdfplumber胜在版式解析能力强，能识别表格、能处理多栏排版，但速度慢一些，内存占用也高一些。
我的建议是：先用pypdf试，如果提取出来的文本乱成一团或者大量缺失，再换pdfplumber。判断标准很简单，随便打开一页提取结果看看，如果段落是连贯的、标点正常，就继续用；如果出现大量乱码、文字顺序错乱、表格内容挤成一坨，就换库。
用pypdf按页提取的核心代码大概是这样：
from pypdf import PdfReader reader = PdfReader("input/report.pdf") total_pages = len(reader.pages) for i, page in enumerate(reader.pages): text = page.extract_text() print(f"第{i+1}页，提取到{len(text)}个字符")这里有个细节值得说：extract_text()返回的文本，段落之间可能没有换行，全挤在一起。如果后续要给AI处理，最好做一次简单的清洗，把连续空格压缩、把明显的段落分隔补上换行。清洗逻辑不用太复杂，几行正则就能搞定。
3.2 单页文本送给AI的请求构造
每一页提取出来的文本，要单独构造一个请求发给AI。请求里包含两部分：系统提示词和用户内容。系统提示词决定了AI怎么处理这一页，比如"请提取这一页的核心要点，用三到五句话概括，如果有数据或结论请单独列出"。用户内容就是这一页的文本。
这里有个经验：提示词要针对文档类型调整。处理学术论文，提示词侧重"研究方法、实验结论、关键数据"；处理合同，侧重"甲乙方、金额、期限、违约责任"；处理产品说明书，侧重"功能点、操作步骤、注意事项"。用一套通用提示词处理所有文档，效果会打折扣。
def build_prompt(page_text, page_num): system = "你是一个文档分析助手。请阅读用户提供的PDF单页内容，提取核心信息。" user = f"这是第{page_num}页的内容：\n\n{page_text}\n\n请用简洁的语言概括这一页的要点。" return system, user请求发送时要注意超时设置。单页文本通常不会太长，60秒超时足够。但如果遇到图片型PDF，提取出来的文本很少甚至为空，这时候要么跳过，要么走OCR流程，不要傻等。
3.3 结果落盘：JSON结构设计与断点续跑
每处理完一页，立刻把结果写进JSON文件。单页JSON的结构建议包含这些字段：
{ "page": 15, "status": "success", "raw_text_length": 842, "summary": "本页主要讨论了……", "timestamp": "2025-01-15T10:23:45", "retry_count": 0 }status字段用来标记这一页是成功、失败还是跳过。retry_count记录重试了几次。有了这些字段，后面排查问题的时候一目了然。
断点续跑的逻辑是：程序启动时先读progress.json，看看哪些页已经处理过了，处理过的直接跳过，从第一个未处理的页继续。这样即使300页跑到第200页时断电了，重新跑也只需要处理剩下的100页。
import json, os def load_progress(): if os.path.exists("progress.json"): with open("progress.json", "r", encoding="utf-8") as f: return json.load(f) return {"last_page": 0} def save_progress(page_num): with open("progress.json", "w", encoding="utf-8") as f: json.dump({"last_page": page_num}, f)实操心得：写JSON文件时一定要指定
encoding="utf-8"，否则在Windows上默认用GBK编码，中文内容会乱码。这个坑我踩过不止一次，排查半天才发现是编码问题。
3.4 处理进度可视化与日志记录
300页跑起来可能要几十分钟甚至更久，没有进度提示会让人心里没底。用tqdm包一层，终端里就能看到进度条、已用时间、预计剩余时间。
from tqdm import tqdm for i in tqdm(range(total_pages), desc="处理PDF"): # 处理逻辑 pass除了进度条，建议再写一份日志文件，记录每一页的处理状态、耗时、是否重试。日志用追加模式写，不要覆盖。出问题的时候，翻日志比翻代码快得多。
import logging logging.basicConfig( filename="output/process.log", level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s" )日志里重点记录三类信息：开始处理第几页、这一页处理成功还是失败、失败的原因是什么。有了这些，排查问题时能快速定位到具体是哪一页、哪一步出了岔子。
4. 常见问题排查与性能优化技巧
4.1 提取文本为空或乱码怎么办
这是PDF处理里最高频的问题。原因通常有三种：PDF是扫描件（本质是图片）、PDF用了特殊字体编码、PDF有加密保护。
判断方法很简单，用pypdf提取第一页，看看返回的文本长度。如果长度接近0，基本就是扫描件。扫描件必须走OCR，Python里可以用pytesseract配合pdf2image，先把PDF页转成图片，再对图片做文字识别。这条路速度慢，但没办法，扫描件没有文本层，任何库都直接读不出文字。
如果是字体编码问题，表现为提取出来一堆问号或奇怪符号。这种情况换pdfplumber试试，它对编码的处理更宽容。如果还是不行，可能得用PyMuPDF（导入名是fitz），它的底层解析能力更强。
加密PDF的话，如果知道密码，pypdf支持传入密码参数解密。不知道密码就只能放弃，或者用专门工具先解密再处理。
4.2 AI接口调用失败的排查路径
接口调用失败的原因五花八门，我按出现频率排个序，做成速查表：
| 现象 | 可能原因 | 排查方法 |
|---|---|---|
| 返回401 | 密钥错误或过期 | 检查API_KEY配置 |
| 返回429 | 请求频率超限 | 降低并发、加延时 |
| 返回500 | 服务端临时故障 | 等待后重试 |
| 连接超时 | 网络问题或文本过长 | 检查网络、缩短单次请求 |
| 返回内容为空 | 提示词问题或文本异常 | 打印请求内容检查 |
重试逻辑一定要有，但不能无脑重试。我的做法是：失败后等3秒重试，最多重试3次，3次都失败就把这一页标记为failed，继续处理下一页，最后统一处理失败页。不要因为一页卡住，让整个300页的任务停摆。
import time def call_ai_with_retry(system, user, max_retry=3): for attempt in range(max_retry): try: # 调用接口 return result except Exception as e: if attempt < max_retry - 1: time.sleep(3) else: return {"status": "failed", "error": str(e)}4.3 大批量处理的性能调优
300页串行处理，如果每页耗时5秒，总共就是25分钟。想提速有几个方向。
第一是并发处理。用concurrent.futures的线程池，同时处理5到10页。但要注意，并发数不是越高越好，接口通常有频率限制，开太高反而触发限流。我一般从5开始试，稳定的话加到10。
from concurrent.futures import ThreadPoolExecutor with ThreadPoolExecutor(max_workers=5) as executor: results = list(executor.map(process_page, pages))第二是减少不必要的请求。有些页是目录、封面、空白页，内容很少甚至没有，可以加一个判断：文本长度低于50个字符的页，直接标记为跳过，不调接口。300页里这类页可能有二三十页，省下来的时间很可观。
第三是本地缓存。同一页如果处理过了，结果直接读缓存，不要重复调接口。这在调试阶段特别有用，改提示词的时候不用每次都重新跑全部页面。
注意：并发处理时，写JSON文件要加锁，否则多个线程同时写同一个文件会冲突。简单做法是每个线程写自己的临时文件，最后统一合并。
4.4 合并结果与后续利用
所有页处理完之后，把pages/目录下的单页JSON合并成一份总文件。合并逻辑就是按页码排序，把每页的summary拼起来，同时保留页码索引。
import json, glob all_pages = [] for filepath in sorted(glob.glob("output/pages/*.json")): with open(filepath, "r", encoding="utf-8") as f: all_pages.append(json.load(f)) with open("output/merged.json", "w", encoding="utf-8") as f: json.dump(all_pages, f, ensure_ascii=False, indent=2)合并后的JSON可以直接拿来做很多事：导入知识库做检索、生成全书摘要、按关键词定位到具体页码。因为每一页都保留了页码，用户问"第几页讲了什么"，你能精确回答，而不是给一个模糊的范围。
如果要做全文问答，可以在合并结果基础上再建一个向量索引，把每页的summary转成向量存起来，查询时先检索相关页，再把那几页的原文送给AI做精细回答。这套组合拳打下来，300页PDF的处理就从一个难题变成了一个可复用的流程。
5. 几个容易被忽略的实操细节
5.1 页码从0还是从1开始
pypdf的reader.pages是0索引的，但用户理解的页码是1索引的。写JSON的时候，page字段一定要用1索引，否则后面做页码定位时会差一位，用户问第15页，你给的是第16页的内容。这个错误很隐蔽，因为程序不会报错，只是结果对不上。
5.2 大文件的内存占用
pypdf读取PDF时，整个文件会加载到内存。300页的PDF如果图片多，文件可能上百MB，内存占用会比较明显。如果机器内存紧张，可以用PdfReader的流式读取，或者分批处理：先读前100页，处理完释放，再读下一批。不过大多数情况下，300页纯文本PDF也就几MB到几十MB，不用太担心。
5.3 提示词的迭代节奏
不要指望第一版提示词就完美。我的做法是：先拿5页做小样本测试，看看AI输出的质量，调整提示词，再拿20页测试，稳定之后再跑全量。直接上300页，提示词有问题的话，300页的结果全得重来，浪费时间和接口额度。
5.4 结果的人工抽检
AI处理完的结果，一定要抽检。随机抽10页，对照原文看看摘要是否准确、有没有遗漏关键信息、有没有编造内容。抽检发现问题，说明提示词或处理逻辑需要调整。全部信任AI输出，风险很大，尤其是处理合同、报告这类对准确性要求高的文档。
我自己跑这套流程处理过技术白皮书、产品手册、学术论文，最深的体会是：分页处理这个思路本身不复杂，难的是把异常情况处理干净。扫描件、加密文件、超长页、接口抖动，这些边角情况才是真正消耗时间的地方。把重试、跳过、日志、断点续跑这几样做扎实，脚本的可靠性会上一个台阶。至于提示词，没有万能模板，针对你的文档类型多试几轮，找到最贴合的那一版，效果比套用任何"最佳实践"都好。
