# 026 Agent 的文件处理：PDF、Excel、图片、音频的解析与生成

一、从一次线上事故说起

去年冬天凌晨两点，我被值班电话吵醒。客户那边一个自动化报表Agent跑崩了，日志里只有一行：MemoryError: cannot fit 'int' into an index-sized integer。查了半天，发现是Agent在处理一个300MB的Excel文件时，用pandas.read_excel()直接全量加载，把32GB的服务器内存吃光了。更坑的是，这个Excel里还混着图片嵌入的批注——openpyxl解析时直接抛了InvalidFileException。

从那以后，我给自己定了个规矩：Agent处理文件，第一原则不是“能解析”，而是“怎么优雅地崩”。今天这篇笔记，就把我这两年踩过的坑、试过的方案，从PDF到音频，从解析到生成，全盘托出。

二、PDF：别信“一行代码搞定”

网上很多教程教你用PyPDF2或pdfplumber，说“三行代码提取文本”。但真实场景里，PDF是个大坑集合体。

2.1 文本提取的“三座大山”

第一座：扫描件PDF
你拿到的PDF可能根本不是文本，而是一张张图片。PyPDF2提取出来全是空字符串。这时候得祭出OCR：pytesseract+pdf2image。但注意，pdf2image依赖poppler，Windows用户装起来能劝退一半人。我一般这样写：

frompdf2imageimportconvert_from_pathimportpytesseract# 这里踩过坑：DPI设太低，中文识别率暴跌；设太高，内存爆炸images=convert_from_path('report.pdf',dpi=300,fmt='jpeg')text=''forimginimages:# 别这样写：直接传原图，背景噪点会让OCR结果惨不忍睹# 先做预处理：灰度化 + 二值化gray=img.convert('L')bw=gray.point(lambdax:0ifx<128else255)text+=pytesseract.image_to_string(bw,lang='chi_sim+eng')

第二座：表格PDF
pdfplumber提取表格还行，但遇到合并单元格、跨页表格，结果就乱成一锅粥。我的经验是：别指望一次提取完美。先提取原始表格数据，再用规则修正：

importpdfplumberwithpdfplumber.open('invoice.pdf')aspdf:forpageinpdf.pages:tables=page.extract_tables()fortableintables:# 这里踩过坑：空单元格返回None，直接拼接会报错row_data=[]forcellintable:# 别这样写：cell.strip() 如果cell是None会AttributeErrorrow_data.append(cell.strip()ifcellelse'')

第三座：加密PDF
很多财务PDF有打开密码或权限密码。PyPDF2可以解密，但只支持40位和128位RC4加密。遇到256位AES加密？换pikepdf：

importpikepdf# 别这样写：硬编码密码在代码里，被审计查到就凉了# 应该从环境变量或密钥管理服务读取password=os.environ.get('PDF_PASSWORD')withpikepdf.open('encrypted.pdf',password=password)aspdf:# 保存为无密码版本，注意覆盖原文件有风险pdf.save('decrypted.pdf')

2.2 PDF生成：别用reportlab手写

reportlab功能强大，但API设计反人类。生成一个带中文的PDF，字体配置能折腾半天。我现在只用fpdf2，轻量且中文支持好：

fromfpdfimportFPDFclassPDF(FPDF):defheader(self):# 这里踩过坑：set_font必须在add_page之后调用self.set_font('NotoSansSC','',12)self.cell(0,10,'报告标题',align='C')pdf=PDF()pdf.add_font('NotoSansSC','','NotoSansSC-Regular.ttf',uni=True)pdf.add_page()pdf.set_font('NotoSansSC','',10)# 别这样写：直接写长文本，超出页面不会自动换行# 用multi_cell代替cellpdf.multi_cell(0,10,'这是一段很长的中文文本，会自动换行...')pdf.output('output.pdf')

三、Excel：从“读爆内存”到“流式处理”

回到开头的故事。300MB的Excel，用pandas.read_excel()直接读，相当于把整个文件解压到内存。Excel本质是ZIP压缩包，里面是XML文件。openpyxl的read_only模式可以流式读取：

fromopenpyxlimportload_workbook# 这里踩过坑：不指定read_only=True，大文件直接OOMwb=load_workbook('huge.xlsx',read_only=True,data_only=True)ws=wb.activeforrowinws.iter_rows(min_row=1,max_row=10000):# 别这样写：row[0].value 如果单元格是公式且data_only=True，可能返回None# 应该先判断类型values=[]forcellinrow:ifcell.valueisNone:values.append('')elifisinstance(cell.value,datetime):values.append(cell.value.strftime('%Y-%m-%d'))else:values.append(str(cell.value))# 处理这一行数据，比如写入数据库process_row(values)wb.close()# 别忘了关闭，否则文件句柄泄漏

3.1 写入Excel：别用pandas.to_excel

pandas.to_excel方便，但遇到大数据量写入，速度慢得令人发指。而且它依赖openpyxl或xlsxwriter，但默认配置下，写入100万行数据，内存占用会飙升。我改用xlsxwriter直接操作：

importxlsxwriter workbook=xlsxwriter.Workbook('output.xlsx',{'constant_memory':True})worksheet=workbook.add_worksheet()# 这里踩过坑：不设置列宽，中文可能显示不全worksheet.set_column('A:A',20)worksheet.set_column('B:B',30)# 写入表头header_format=workbook.add_format({'bold':True,'bg_color':'#D9E1F2'})worksheet.write('A1','姓名',header_format)worksheet.write('B1','邮箱',header_format)# 流式写入，内存恒定fori,rowinenumerate(data,start=2):worksheet.write(i,0,row['name'])worksheet.write(i,1,row['email'])workbook.close()

3.2 处理嵌入对象

Excel里可能嵌着图片、PDF甚至视频。openpyxl可以读取图片，但注意图片是作为PIL.Image对象存在的：

fromopenpyxlimportload_workbookfromopenpyxl.drawing.imageimportImageasXLImage wb=load_workbook('with_images.xlsx')ws=wb.activeforimageinws._images:# 这里踩过坑：image.ref 可能不存在，需要先判断ifhasattr(image,'ref'):img_data=image.ref# 这是BytesIO对象# 保存到文件withopen('extracted.png','wb')asf:f.write(img_data.getvalue())

四、图片：Agent的“眼睛”不能瞎

Agent处理图片，最常见的是OCR和分类。但图片格式、分辨率、色彩空间，每个细节都能坑你。

4.1 图片解析：统一格式是第一步

用户上传的图片可能是PNG、JPG、WebP甚至BMP。我习惯先统一转成RGB模式的PNG：

fromPILimportImageimportiodefnormalize_image(image_bytes):# 这里踩过坑：直接Image.open(BytesIO)可能遇到截断的图片try:img=Image.open(io.BytesIO(image_bytes))exceptExceptionase:# 别这样写：直接抛异常，应该返回错误信息给AgentreturnNone,f"图片损坏:{str(e)}"# 转换色彩模式ifimg.mode!='RGB':img=img.convert('RGB')# 限制最大尺寸，防止OCR时内存溢出max_size=(2048,2048)img.thumbnail(max_size,Image.LANCZOS)# 保存为PNG字节流output=io.BytesIO()img.save(output,format='PNG')returnoutput.getvalue(),None

4.2 OCR增强：不是所有图片都适合直接识别

对于扫描件、票据，直接OCR效果很差。我总结了一套预处理流程：

importcv2importnumpyasnpdefpreprocess_for_ocr(image_path):img=cv2.imread(image_path)# 1. 灰度化gray=cv2.cvtColor(img,cv2.COLOR_BGR2GRAY)# 2. 去噪：高斯模糊，核大小根据图片分辨率调整blurred=cv2.GaussianBlur(gray,(5,5),0)# 3. 二值化：OTSU自动阈值_,binary=cv2.threshold(blurred,0,255,cv2.THRESH_BINARY+cv2.THRESH_OTSU)# 4. 去边框：很多票据有表格线，干扰OCR# 这里踩过坑：直接腐蚀膨胀会丢失文字细节kernel=np.ones((2,2),np.uint8)cleaned=cv2.morphologyEx(binary,cv2.MORPH_CLOSE,kernel)returncleaned

4.3 图片生成：别用PIL画复杂图表

Agent需要生成图表时，matplotlib是首选，但注意中文字体问题：

importmatplotlib.pyplotaspltimportmatplotlibfrommatplotlib.font_managerimportFontProperties# 这里踩过坑：不指定字体，中文显示为方框font=FontProperties(fname='/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc')matplotlib.rcParams['font.family']=font.get_name()fig,ax=plt.subplots()ax.plot(x,y)ax.set_title('销售趋势图',fontproperties=font)# 别这样写：直接plt.savefig，背景默认白色，但透明背景在某些场景更好plt.savefig('chart.png',dpi=150,bbox_inches='tight',transparent=False)plt.close()

五、音频：从语音到文本的“最后一公里”

音频处理在Agent场景里越来越常见，比如语音助手、会议记录。但音频格式、采样率、噪声，每个环节都可能翻车。

5.1 音频解析：格式转换是必修课

用户上传的音频可能是MP3、WAV、FLAC甚至AMR。pydub可以处理大部分格式，但依赖ffmpeg：

frompydubimportAudioSegment# 这里踩过坑：不指定采样率，语音识别模型可能报错audio=AudioSegment.from_file('input.mp3')audio=audio.set_frame_rate(16000)# 大多数ASR模型要求16kHzaudio=audio.set_channels(1)# 单声道audio=audio.set_sample_width(2)# 16位PCM# 导出为WAV，方便后续处理audio.export('output.wav',format='wav')

5.2 语音识别：别用免费API做生产环境

很多教程推荐speech_recognition库，但它底层调的是Google、IBM的免费API，有调用次数限制，而且延迟不稳定。生产环境我推荐两种方案：

方案一：本地模型（Vosk）
适合离线场景，但模型文件较大（~50MB），中文识别率一般：

fromvoskimportModel,KaldiRecognizerimportwave model=Model('vosk-model-cn-0.22')wf=wave.open('output.wav','rb')rec=KaldiRecognizer(model,wf.getframerate())whileTrue:data=wf.readframes(4000)iflen(data)==0:breakifrec.AcceptWaveform(data):result=rec.Result()# 解析JSON，提取文本text=json.loads(result)['text']

方案二：云端API（阿里云/腾讯云）
延迟低，准确率高，但注意并发限制和费用。我一般封装成异步调用：

importasyncioimportaiohttpasyncdefrecognize_audio(audio_bytes):# 这里踩过坑：不设置超时，网络波动时请求会挂起timeout=aiohttp.ClientTimeout(total=30)asyncwithaiohttp.ClientSession(timeout=timeout)assession:# 假设是阿里云语音识别APIurl='https://nls-gateway.cn-shanghai.aliyuncs.com/stream/v1/asr'headers={'Authorization':'Bearer '+get_token()}asyncwithsession.post(url,data=audio_bytes,headers=headers)asresp:ifresp.status==200:result=awaitresp.json()returnresult['result']else:# 别这样写：直接返回空字符串，应该记录错误并重试returnNone

5.3 音频生成：TTS的坑

Agent需要语音回复时，pyttsx3是离线方案，但声音机械感强。在线TTS（如Azure、百度）效果好，但注意流式播放：

importazure.cognitiveservices.speechasspeechsdk speech_config=speechsdk.SpeechConfig(subscription=os.environ['AZURE_KEY'],region='eastasia')speech_config.speech_synthesis_voice_name='zh-CN-XiaoxiaoNeural'synthesizer=speechsdk.SpeechSynthesizer(speech_config=speech_config)# 这里踩过坑：不设置SSML，语速、音调无法控制ssml=f""" <speak version='1.0' xmlns='http://www.w3.org/2001/10/synthesis' xml:lang='zh-CN'> <voice name='zh-CN-XiaoxiaoNeural'> <prosody rate='+10%' pitch='+5%'>{text}</prosody> </voice> </speak> """result=synthesizer.speak_ssml_async(ssml).get()ifresult.reason==speechsdk.ResultReason.SynthesizingAudioCompleted:audio_data=result.audio_data# 保存或播放

六、个人经验性建议

1. 文件处理一定要有超时和大小限制。Agent面对的是不可控的用户输入，一个100MB的PDF、10小时的音频，如果不加限制，能把整个系统拖垮。我一般在入口处就做校验：文件大小超过50MB直接拒绝，处理时间超过30秒就中断。

2. 临时文件管理是隐形炸弹。解析PDF、转换音频都会产生临时文件，如果不清理，磁盘很快会被占满。我习惯用tempfile.NamedTemporaryFile，并设置delete=True，或者用with语句确保释放。

3. 错误处理要分层。文件损坏、格式不支持、API超时，每种错误都应该有对应的降级策略。比如PDF解析失败，可以尝试用OCR兜底；语音识别超时，可以返回“暂时无法识别，请稍后重试”。

4. 日志要记录文件指纹。出问题时，光看“文件解析失败”根本没法排查。我每次处理文件都会记录MD5、文件大小、处理耗时，方便事后回溯。

5. 别迷信“万能解析库”。没有哪个库能处理所有文件变体。PDF有扫描件、加密、表单、注释；Excel有宏、嵌入对象、数据验证。我的做法是：先尝试主流库，失败后用备用方案，再失败就返回明确的错误信息，而不是让Agent卡死。

文件处理是Agent连接物理世界的桥梁，也是最容易出幺蛾子的环节。记住：能优雅地失败，比勉强地成功更重要。