028、图片与文档处理图像分析、PDF 章节阅读与 Jupyter Notebook 编辑实战上周五凌晨两点我盯着终端里Claude Code吐出的错误日志发呆。一个客户发来的PDF合同里面嵌着三张扫描件——公章、签名、手写备注。Claude Code读完了文字部分但图像区域直接跳过了。客户追问“公章上的编号你们识别了吗”我翻了下输出没有。这不是Claude Code的锅是我没告诉它怎么处理非文本内容。这个场景在工程化落地中太常见了。很多人把Claude Code当成纯文本工具遇到图片、PDF、Notebook就抓瞎。今天这篇笔记我把踩过的坑和摸出来的套路一次性说清楚。图像分析别让Claude Code“看”不到图Claude Code默认不会主动读取图片文件。你扔一个image.png进去它只会看到文件名。要让模型真正“看见”图片内容得用--vision模式。claude--visionanalyze_image.py这里踩过坑--vision会显著增加token消耗一张中等分辨率的截图大约吃掉2000-3000 tokens。别在调试阶段每张图都开vision先确认文本逻辑跑通最后再开视觉分析。实战中我常用这个模式做两件事1. UI截图对比测试自动化测试跑完Claude Code拿到截图后直接让它描述页面元素位置和颜色变化。比如请分析screenshot_after_update.png告诉我 - 按钮“提交”是否可见 - 错误提示区域是否有红色边框 - 页面加载状态是否消失别这样写“请分析这张图片”。Claude Code需要明确的任务指令否则它会给你一段“这是一张包含蓝色按钮和白色背景的图片”这种废话。2. 手写笔记转结构化数据客户发来一张手写会议记录的照片。我让Claude Code先做OCR识别再按Markdown表格整理。关键步骤是分两步走第一步让模型描述图片中的文字内容。第二步基于描述结果做结构化转换。不要指望一步到位图片质量差的时候模型会编造内容。有个血泪教训图片分辨率低于300dpi时识别准确率断崖式下跌。我后来在预处理阶段加了--resize参数用ImageMagick先放大两倍再喂给Claude Code。PDF章节阅读分段投喂的艺术PDF是Claude Code的天然敌人。不是模型不行是PDF格式太脏。一个10页的PDF可能包含5种不同的编码方式、嵌入字体、矢量图、注释层。直接扔进去Claude Code大概率会吐出乱码或者只读前两页。我的标准流程是三步第一步PDF转文本pdftotext-layoutinput.pdf output.txt-layout参数保留原始排版对多栏文档尤其重要。别用默认参数否则表格数据会变成一坨。第二步按章节切割写一个简单的Python脚本根据“第X章”或“Chapter X”做分割。Claude Code对单次输入的长度有限制超过2万token会开始丢细节。我一般把每个章节控制在5000 token以内。# 这里踩过坑直接用split(\n\n)会切碎表格# 改用正则匹配章节标题importre chaptersre.split(r(?第[一二三四五六七八九十]章),text)第三步逐章投喂并汇总每次只给Claude Code一个章节的内容让它提取关键信息。最后把所有章节的摘要合并再让模型做一次全局总结。别这样写“请阅读整个PDF并总结”。Claude Code会尝试一次性处理然后告诉你“抱歉内容过长”。分段投喂虽然慢但结果可靠。遇到扫描版PDF怎么办先转图片再用vision模式。我写了个自动化脚本# 先转图片pdftoppm-png-r300input.pdf output_page# 再逐页分析forfinoutput_page*.png;doclaude--vision分析$f中的文字内容page_content.txtdone这个流程跑一次大概5分钟但能处理任何格式的PDF包括那些加密的、带水印的、甚至手写的。Jupyter Notebook编辑实战别让Claude Code碰.ipynbJupyter Notebook的.ipynb文件本质是JSON。Claude Code能读但编辑起来极其痛苦。它经常把代码块和Markdown块搞混或者把输出结果当成代码写进去。我的解决方案是永远不要直接编辑.ipynb文件。工作流.ipynb → .py → 编辑 → 转回.ipynb# 提取代码和Markdownjupyter nbconvert--toscript notebook.ipynb# 这会生成notebook.py包含所有代码和注释然后让Claude Code编辑这个.py文件。它处理纯Python文件得心应手不会搞混格式。编辑完成后再转回Notebook# 这里踩过坑直接转回去会丢失Markdown格式# 改用这个工具jupytext--tonotebook notebook.py-onotebook_updated.ipynbjupytext比nbconvert更智能能保留Markdown和代码的分隔。我试过用nbconvert转回来结果所有Markdown都变成了代码注释气得我重写了一遍。进阶技巧让Claude Code生成Notebook有时候需要从零创建一个Notebook。我让Claude Code先生成一个.py文件里面用特殊注释标记Markdown和代码块# %% [markdown]# # 数据分析报告# 这是标题# %% [code]importpandasaspd dfpd.read_csv(data.csv)然后运行jupytext--tonotebook generated.py-oreport.ipynb这个流程比直接让Claude Code写JSON靠谱十倍。它不会把引号搞乱也不会忘记闭合括号。实战案例处理一份混合文档上周处理了一个真实案例客户发来一个压缩包里面包含一个PDF合同、三张盖章照片、一个Jupyter Notebook分析报告。我的处理流程解压后PDF用pdftotext转文本照片用--vision逐张分析文本和图片分析结果合并成一个Markdown文件让Claude Code基于合并内容生成合同摘要和风险点Notebook用jupytext转成.py让Claude Code检查代码逻辑并添加注释最后把修改后的.py转回.ipynb整个过程大约20分钟Claude Code处理了约1.5万token的输入。如果直接扔原始文件估计要翻车三次。个人经验性建议图片预处理比模型能力更重要。分辨率、对比度、去噪这些做好Claude Code的视觉能力能提升50%。我写了个预处理脚本自动做灰度化、对比度增强、锐化效果立竿见影。PDF永远不要直接喂。先转文本再分段。这是铁律。我见过有人直接把100页PDF扔进去Claude Code卡了15分钟最后输出“无法处理”。浪费时间。Notebook编辑用中转格式。.ipynb是给Jupyter看的不是给LLM看的。.py才是Claude Code的舒适区。多一步转换少十次debug。token预算要提前算。一张图片vision模式吃掉2000-3000 tokens一个PDF章节5000 tokens一个Notebook可能1万。我每次开工前先估算总token超过3万就分两次对话。Claude Code的上下文窗口虽然大但超过2万后质量明显下降。保留原始文件。Claude Code编辑完别急着覆盖原文件。我习惯在文件名加_claude_edited后缀对比着看。有一次它把PDF里的表格数据全改成了Markdown格式数值没变但结构乱了幸好有原文件对比才发现。最后说一句Claude Code处理图片和文档的能力在快速迭代但工程化的核心不是依赖模型有多强而是你有多了解它的边界。知道什么时候该用vision什么时候该用文本什么时候该手动预处理——这些经验比任何模型更新都值钱。
028 图片与文档处理：图像分析、PDF 章节阅读与 Jupyter Notebook 编辑实战
028、图片与文档处理图像分析、PDF 章节阅读与 Jupyter Notebook 编辑实战上周五凌晨两点我盯着终端里Claude Code吐出的错误日志发呆。一个客户发来的PDF合同里面嵌着三张扫描件——公章、签名、手写备注。Claude Code读完了文字部分但图像区域直接跳过了。客户追问“公章上的编号你们识别了吗”我翻了下输出没有。这不是Claude Code的锅是我没告诉它怎么处理非文本内容。这个场景在工程化落地中太常见了。很多人把Claude Code当成纯文本工具遇到图片、PDF、Notebook就抓瞎。今天这篇笔记我把踩过的坑和摸出来的套路一次性说清楚。图像分析别让Claude Code“看”不到图Claude Code默认不会主动读取图片文件。你扔一个image.png进去它只会看到文件名。要让模型真正“看见”图片内容得用--vision模式。claude--visionanalyze_image.py这里踩过坑--vision会显著增加token消耗一张中等分辨率的截图大约吃掉2000-3000 tokens。别在调试阶段每张图都开vision先确认文本逻辑跑通最后再开视觉分析。实战中我常用这个模式做两件事1. UI截图对比测试自动化测试跑完Claude Code拿到截图后直接让它描述页面元素位置和颜色变化。比如请分析screenshot_after_update.png告诉我 - 按钮“提交”是否可见 - 错误提示区域是否有红色边框 - 页面加载状态是否消失别这样写“请分析这张图片”。Claude Code需要明确的任务指令否则它会给你一段“这是一张包含蓝色按钮和白色背景的图片”这种废话。2. 手写笔记转结构化数据客户发来一张手写会议记录的照片。我让Claude Code先做OCR识别再按Markdown表格整理。关键步骤是分两步走第一步让模型描述图片中的文字内容。第二步基于描述结果做结构化转换。不要指望一步到位图片质量差的时候模型会编造内容。有个血泪教训图片分辨率低于300dpi时识别准确率断崖式下跌。我后来在预处理阶段加了--resize参数用ImageMagick先放大两倍再喂给Claude Code。PDF章节阅读分段投喂的艺术PDF是Claude Code的天然敌人。不是模型不行是PDF格式太脏。一个10页的PDF可能包含5种不同的编码方式、嵌入字体、矢量图、注释层。直接扔进去Claude Code大概率会吐出乱码或者只读前两页。我的标准流程是三步第一步PDF转文本pdftotext-layoutinput.pdf output.txt-layout参数保留原始排版对多栏文档尤其重要。别用默认参数否则表格数据会变成一坨。第二步按章节切割写一个简单的Python脚本根据“第X章”或“Chapter X”做分割。Claude Code对单次输入的长度有限制超过2万token会开始丢细节。我一般把每个章节控制在5000 token以内。# 这里踩过坑直接用split(\n\n)会切碎表格# 改用正则匹配章节标题importre chaptersre.split(r(?第[一二三四五六七八九十]章),text)第三步逐章投喂并汇总每次只给Claude Code一个章节的内容让它提取关键信息。最后把所有章节的摘要合并再让模型做一次全局总结。别这样写“请阅读整个PDF并总结”。Claude Code会尝试一次性处理然后告诉你“抱歉内容过长”。分段投喂虽然慢但结果可靠。遇到扫描版PDF怎么办先转图片再用vision模式。我写了个自动化脚本# 先转图片pdftoppm-png-r300input.pdf output_page# 再逐页分析forfinoutput_page*.png;doclaude--vision分析$f中的文字内容page_content.txtdone这个流程跑一次大概5分钟但能处理任何格式的PDF包括那些加密的、带水印的、甚至手写的。Jupyter Notebook编辑实战别让Claude Code碰.ipynbJupyter Notebook的.ipynb文件本质是JSON。Claude Code能读但编辑起来极其痛苦。它经常把代码块和Markdown块搞混或者把输出结果当成代码写进去。我的解决方案是永远不要直接编辑.ipynb文件。工作流.ipynb → .py → 编辑 → 转回.ipynb# 提取代码和Markdownjupyter nbconvert--toscript notebook.ipynb# 这会生成notebook.py包含所有代码和注释然后让Claude Code编辑这个.py文件。它处理纯Python文件得心应手不会搞混格式。编辑完成后再转回Notebook# 这里踩过坑直接转回去会丢失Markdown格式# 改用这个工具jupytext--tonotebook notebook.py-onotebook_updated.ipynbjupytext比nbconvert更智能能保留Markdown和代码的分隔。我试过用nbconvert转回来结果所有Markdown都变成了代码注释气得我重写了一遍。进阶技巧让Claude Code生成Notebook有时候需要从零创建一个Notebook。我让Claude Code先生成一个.py文件里面用特殊注释标记Markdown和代码块# %% [markdown]# # 数据分析报告# 这是标题# %% [code]importpandasaspd dfpd.read_csv(data.csv)然后运行jupytext--tonotebook generated.py-oreport.ipynb这个流程比直接让Claude Code写JSON靠谱十倍。它不会把引号搞乱也不会忘记闭合括号。实战案例处理一份混合文档上周处理了一个真实案例客户发来一个压缩包里面包含一个PDF合同、三张盖章照片、一个Jupyter Notebook分析报告。我的处理流程解压后PDF用pdftotext转文本照片用--vision逐张分析文本和图片分析结果合并成一个Markdown文件让Claude Code基于合并内容生成合同摘要和风险点Notebook用jupytext转成.py让Claude Code检查代码逻辑并添加注释最后把修改后的.py转回.ipynb整个过程大约20分钟Claude Code处理了约1.5万token的输入。如果直接扔原始文件估计要翻车三次。个人经验性建议图片预处理比模型能力更重要。分辨率、对比度、去噪这些做好Claude Code的视觉能力能提升50%。我写了个预处理脚本自动做灰度化、对比度增强、锐化效果立竿见影。PDF永远不要直接喂。先转文本再分段。这是铁律。我见过有人直接把100页PDF扔进去Claude Code卡了15分钟最后输出“无法处理”。浪费时间。Notebook编辑用中转格式。.ipynb是给Jupyter看的不是给LLM看的。.py才是Claude Code的舒适区。多一步转换少十次debug。token预算要提前算。一张图片vision模式吃掉2000-3000 tokens一个PDF章节5000 tokens一个Notebook可能1万。我每次开工前先估算总token超过3万就分两次对话。Claude Code的上下文窗口虽然大但超过2万后质量明显下降。保留原始文件。Claude Code编辑完别急着覆盖原文件。我习惯在文件名加_claude_edited后缀对比着看。有一次它把PDF里的表格数据全改成了Markdown格式数值没变但结构乱了幸好有原文件对比才发现。最后说一句Claude Code处理图片和文档的能力在快速迭代但工程化的核心不是依赖模型有多强而是你有多了解它的边界。知道什么时候该用vision什么时候该用文本什么时候该手动预处理——这些经验比任何模型更新都值钱。
