1. 从一份扫描版合同说起大模型调用与 PDF 解析的真实痛点我手头经常要处理几十页的 PDF 合同、技术白皮书、论文最烦的不是读而是「先解析再喂给模型」这条链路总在某个环节断掉。你可能也遇到过PDF 里是扫描图直接丢给模型它读不出字或者用某个库抽出来的文本全是乱码、表格错位再或者模型 API 的地址在国内访问不稳定请求发出去半天没响应。这几个问题叠在一起一条本来十分钟能跑完的流程能拖你一整个下午。这篇要解决的就是这条完整链路用统一 Key 和统一 Base URL 调用大模型同时完成 PDF 的文本抽取最后让模型对抽取结果做总结。核心检索词就是「中转API」「大模型调用」「PDF解析」。适合谁看适合已经会一点 Python、想快速把「PDF → 文本 → 模型总结」跑通的后端、算法、数据同学也适合做 RAG 知识库前期文档预处理的人。我试过把解析和调用拆成两个服务分别配 Key结果调试时两边报错信息对不上排查成本翻倍。后来改成统一通道Base URL 和 Key 只维护一份问题定位快很多。下面按「先讲通道怎么配 → 再讲 PDF 怎么抽 → 再讲模型怎么调 → 最后验证和排错」的顺序来每一步都给可复制的代码和配置。先说清楚整体架构避免你后面迷路。整条链路分三层第一层是接入层也就是统一的中转 API 通道负责把请求转发到具体模型第二层是解析层把 PDF 文件转成纯文本或结构化 JSON第三层是调用层把解析出来的文本拼成 prompt 发给模型拿回总结。三层之间用同一个 Key 串起来这样你只需要管一个凭证。为什么强调「统一」因为很多人的做法是 PDF 解析用一个本地库不花钱模型调用用另一个平台的 Key两套凭证、两套限流、两套错误码。一旦出问题你根本不知道是解析挂了还是调用挂了。统一通道之后至少调用层的问题能收敛到一个地方。还有一个容易被忽略的点PDF 解析出来的文本质量直接决定模型总结的质量。如果解析阶段把表格拍扁成一行、把页眉页脚混进正文模型再强也总结不准。所以这篇不会只给你一句loader.load()就完事会把解析后的清洗也讲清楚。2. TaoToken 统一 Key 接入Base URL 与凭证准备这一节讲接入层。TaoToken 的作用是提供一个统一的 API 入口你用一份 Key 就能调用多种大模型Base URL 固定不用为每个模型单独配地址。官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 根地址是 https://taotoken.net/api 注意这个不带 UTM 参数代码里填这个。先明确三个必须配对的要素缺一不可Base URL、API Key、Model ID。很多人报 401 或者 model not found就是因为这三个里有一个填错。Base URL 用https://taotoken.net/apiKey 在控制台的 API Keys 页面生成Model ID 用你实际要调用的模型名。生成 Key 的路径进入控制台后找到 API Keys 管理页新建一个 Key复制出来保存好。这个 Key 只显示一次丢了只能重建。建议按项目建不同的 Key方便后面按 Key 统计用量和排查。拿到 Key 之后先别急着写业务代码用一条最简单的 curl 验证通道是否通。这一步能帮你把「通道问题」和「业务问题」分开。curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: gpt-4o-mini, messages: [{role: user, content: 只回复两个字通了}] }把$TAOTOKEN_API_KEY换成你刚生成的 Key。如果返回里有choices字段且内容是「通了」说明通道没问题。如果返回 401检查 Key 有没有复制全、有没有多余空格如果返回 model 相关错误检查 Model ID 拼写。环境变量建议这样管理别把 Key 硬编码进代码export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_BASE_URLhttps://taotoken.net/apiPython 里读取import os API_KEY os.environ[TAOTOKEN_API_KEY] BASE_URL os.environ.get(TAOTOKEN_BASE_URL, https://taotoken.net/api)如果你用的是 OpenAI 官方 SDK可以直接把base_url指过来这样你原来的代码几乎不用改from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlhttps://taotoken.net/api/v1, )注意这里base_url后面带了/v1因为 OpenAI SDK 会自己拼/chat/completions。而前面 curl 里我写的是完整路径https://taotoken.net/api/v1/chat/completions。两种写法对应两种调用方式别混。用 SDK 就填到/v1手写 requests 就填完整路径。关于模型选择如果你只是做 PDF 总结这种文本任务选一个上下文窗口够大、价格适中的模型就行。上下文窗口很关键因为一份 30 页 PDF 抽出来的文本可能有两三万 token窗口太小会被截断。选模型时先确认它的最大上下文再决定要不要分段。Key 的权限和额度也要留意。控制台里一般能看到每个 Key 的用量建议给解析和总结这类批量任务单独建 Key避免和线上对话业务抢额度。如果发现请求突然变慢先看是不是额度或限流触发了。3. 可复制配置PDF 解析 模型调用的完整代码这一节是核心给你一份能直接跑的代码。分两部分PDF 解析和模型调用。解析用pypdf做基础抽取复杂版式再上pdfplumber调用用 OpenAI SDK 指向 TaoToken 的 Base URL。先装依赖pip install openai pypdf pdfplumber先写一个配置文件config.json把三件套集中管理避免散落在代码里{ base_url: https://taotoken.net/api/v1, api_key_env: TAOTOKEN_API_KEY, model_id: gpt-4o-mini, max_context_tokens: 120000, chunk_size: 3000, chunk_overlap: 200 }这个 JSON 里base_url填到/v1api_key_env是环境变量名而不是 Key 本身model_id换成你要用的模型chunk_size是分段大小后面讲长文档时会用到。PDF 解析部分先给基础版from pypdf import PdfReader def extract_text_basic(pdf_path: str) - str: reader PdfReader(pdf_path) pages [] for i, page in enumerate(reader.pages): text page.extract_text() or pages.append(f[第{i1}页]\n{text}) return \n\n.join(pages)pypdf对纯文本 PDF 效果好但对扫描件无能为力——扫描件里没有文字层抽出来是空的。判断方法很简单如果抽取结果长度接近 0基本就是扫描件需要走 OCR这篇不展开 OCR但你要知道这个边界。对表格多的 PDF换pdfplumberimport pdfplumber def extract_text_with_tables(pdf_path: str) - str: chunks [] with pdfplumber.open(pdf_path) as pdf: for i, page in enumerate(pdf.pages): text page.extract_text() or tables page.extract_tables() table_str for t in tables: for row in t: table_str | .join([c or for c in row]) \n chunks.append(f[第{i1}页]\n{text}\n[表格]\n{table_str}) return \n\n.join(chunks)表格用|分隔模型读起来比纯文本更清楚。实测下来表格类文档用这个版本总结准确率明显高。接下来是调用层。先写一个通用的 chat 函数import os from openai import OpenAI client OpenAI( api_keyos.environ[TAOTOKEN_API_KEY], base_urlhttps://taotoken.net/api/v1, ) def chat(prompt: str, model: str gpt-4o-mini) - str: resp client.chat.completions.create( modelmodel, messages[{role: user, content: prompt}], temperature0.3, ) return resp.choices[0].message.content长文档要分段否则超上下文。分段函数def split_text(text: str, size: int 3000, overlap: int 200): chunks [] start 0 while start len(text): end start size chunks.append(text[start:end]) start end - overlap return chunks分段总结再合并def summarize_pdf(pdf_path: str, model: str gpt-4o-mini) - str: text extract_text_with_tables(pdf_path) chunks split_text(text) partial [] for i, c in enumerate(chunks): p f这是文档第{i1}段请用中文提炼要点\n{c} partial.append(chat(p, model)) merged \n.join(partial) final chat(f以下是分段要点请合并成一份完整总结\n{merged}, model) return final跑起来if __name__ __main__: print(summarize_pdf(example.pdf))这份代码覆盖了「解析 → 分段 → 调用 → 合并」全链路。你可以先把chunk_size调小一点测试确认通了再放大。4. 用样例 PDF 验证从请求到成功结果这一节带你实际验证一遍确保解析和调用都成功。准备一份样例 PDF最好 5 到 10 页包含正文和至少一个表格这样能同时验证两种解析路径。第一步单独验证解析。写个小脚本只跑解析不调模型text extract_text_with_tables(example.pdf) print(字符数:, len(text)) print(text[:500])看输出字符数应该和 PDF 页数成正比一般每页几百到几千字符。如果字符数是 0 或个位数说明是扫描件或加密 PDF。如果前 500 字里出现大量乱码符号说明字体编码有问题换pdfplumber或先做预处理。第二步单独验证模型调用。用固定 prompt 测print(chat(用一句话解释什么是向量数据库。))返回一句通顺的中文说明通道和 Key 都正常。如果这里就报错先回到第 2 节排查别往下走。第三步跑完整链路result summarize_pdf(example.pdf) print(result)成功的结果应该是一份结构化的中文总结包含文档主题、关键结论、可能的表格数据。如果总结里出现「无法读取」「内容为空」之类的话多半是解析阶段没抽到文本回到第一步检查。第四步验证长文档分段是否生效。找一份 30 页以上的 PDF在split_text里加一行打印chunks split_text(text) print(分段数:, len(chunks))分段数应该大于 1。如果只有 1 段但文档很长说明chunk_size设太大了调小到 2000 再试。第五步检查 token 消耗。控制台里能看到每次请求的用量。一份 10 页 PDF 分段总结通常消耗几千到一万多 token具体看文档密度。如果消耗异常高检查是不是分段重叠设太大或者把整份文档重复发了多次。验证通过的标准很简单解析有文本、调用有返回、总结内容对得上原文。三个都满足链路就通了。5. 常见报错排查401、local proxy failed、reading choices这一节按真实报错来。你跑上面代码时最可能撞上这几类错误逐个说清楚原因和解法。401 Unauthorized。原因通常是 Key 没读到或格式不对。检查三处环境变量有没有export成功echo $TAOTOKEN_API_KEY看有没有值Key 前面有没有多余空格请求头是不是Authorization: Bearer sk-xxx。用 SDK 的话确认api_key参数传对了。还有一种情况是 Key 被删了或过期去控制台重新生成一个。local proxy failed / connection error。这类错误说明请求根本没发出去或者发出去被本地网络环境拦了。先确认base_url拼写正确是https://taotoken.net/api/v1别多写斜杠或少写/v1。再确认本机没有奇怪的全局代理设置干扰。如果公司网络有出口限制换一个网络环境测试。注意这里说的是排查本地网络配置不是让你去搞什么特殊通道。reading choices / KeyError: choices。这个错误说明请求返回了但返回体里没有choices字段。常见原因是返回的其实是错误信息比如{error: {message: ...}}。解决办法是把原始返回打出来resp client.chat.completions.create(...) print(resp)看error.message里写了什么。常见的有 model 不存在、参数格式错、额度不足。model 不存在就核对 Model ID额度不足就去控制台看用量。OAuth / authentication 相关错误。如果你用的是某些 CLI 工具比如 Claude Code 类它可能走的是 OAuth 流程而不是 API Key。这种情况要确认工具支持自定义 Base URL 和 Key把三件套填全Base URL 填https://taotoken.net/apiKey 填你的 API KeyModel ID 填对应模型。三者缺一工具就会回退到默认认证方式然后失败。PDF 解析返回空。不是报错但结果不对。先判断是不是扫描件再看是不是加密 PDF。加密的用PdfReader(pdf_path, passwordxxx)解密。版式复杂的换pdfplumber再不行就上 OCR。分段总结结果重复或断裂。多半是chunk_overlap设太大导致内容重复或者设太小导致句子被切断。200 左右是个比较稳的值句子边界处可以再加一层按句号切分的逻辑。排查顺序建议固定先 curl 测通道 → 再单独测解析 → 再单独测调用 → 最后跑全链路。这样每步只验证一个变量定位快。6. 把这条链路用起来接入文档与后续扩展链路跑通之后你可以按自己的场景扩展。如果要做 RAG 知识库解析出来的文本可以直接切块入向量库模型调用部分换成 embedding 接口即可。如果要批量处理把summarize_pdf包一层循环加上失败重试和日志。几个实用建议。第一解析结果先落盘再调用模型这样模型调用失败时不用重新解析省时间也省 token。第二给每个 PDF 记录解析字符数和分段数方便回溯哪份文档出了问题。第三模型总结的 prompt 里明确要求「只基于给定文本不要编造」能减少幻觉。关于凭证和文档接入相关的说明在接入文档里Key 的生成和管理在 API Keys 页面。如果你要验证不同模型对同一份 PDF 的总结效果可以用模型对话页面直接对比不用改代码。长期跑批量编码或 Agent 类任务Coding Plan 会更合适额度和并发都更稳。最后留一个我踩过的坑一开始我把chunk_size设成 8000觉得分段少、调用次数少、省钱。结果模型对超长单段文本的总结质量明显下降关键信息被淹没。后来改成 2500 到 3000虽然调用次数多了但总结准确率上来了。分段大小不是越大越好要按模型的实际表现调。你可以从 3000 起步根据总结质量上下微调。