简介本资源是一套基于Python调用百度OCR API实现批量图片文字识别的实战工具包面向IT从业者、自动化办公需求者及Python初学者解决纸质文档数字化、多图信息快速提取等实际问题。压缩包共4个文件149KB含2张测试PNG样本图用于效果验证、1个核心脚本shiyan-docx.py封装图像预处理、API鉴权、批量请求、JSON解析与结果写入Word全流程、1份生成的shiyan.docx示例文档结构精简、开箱即用。已有1419人学习下载读者可直接复用代码逻辑快速部署本地批量识别任务脚本已预留APP_ID/APP_SECRET占位符与预处理扩展接口便于适配不同图像质量与业务字段配套示例文档直观呈现输出格式降低调试门槛显著提升文档处理效率。1. 批量图片文字识别不是“点一下就出结果”而是图像预处理、API调用、响应解析、文档组装四步闭环在实际办公场景中你可能刚收到200张扫描件截图——会议纪要、合同页、手写签到表、发票照片全堆在“新建文件夹”里。此时打开百度OCR网页版一张张上传、复制、粘贴3小时后眼睛酸胀还漏了3张。而本方案用Python驱动百度OCR API把1.PNG、2.PNG等批量喂进去自动完成图像质量校验、token刷新、并发请求控制、错误重试、段落分隔与Word结构化排版最终生成带标题层级的shiyan.docx。它不依赖GUI操作可嵌入定时任务或CI流程不硬编码路径支持通配符匹配和子目录递归不裸奔式发请求内置400/401/500状态码分级处理逻辑。适合IT运维、行政数字化、法务文档归档等需稳定处理50图片/日的中小规模场景新手按步骤能跑通熟手可直接切入参数调优与异常流覆盖。2. 百度OCR API接入与access_token生命周期管理2.1 为什么必须用access_token而非永久密钥百度OCR API采用OAuth 2.0鉴权机制app_id与app_secret仅用于换取短期有效的access_token有效期30天而非直接作为请求凭证。这是安全设计的强制要求若密钥泄露攻击者最多利用30天若直接暴露密钥系统将面临无限期风险。官方文档明确禁止在前端代码或公开仓库中硬编码app_id/app_secret生产环境应通过环境变量或配置中心注入。提示access_token过期后API返回{error:invalid_access_token,error_description:The access token is invalid.}此时必须重新调用token接口不可重试原OCR请求。2.2 token获取与缓存策略实现以下代码封装了token获取、本地文件缓存及自动刷新逻辑避免每次识别都发起认证请求import json import time import requests from pathlib import Path def get_access_token(app_id: str, app_secret: str, cache_file: str baidu_token.json) - str: cache_path Path(cache_file) # 优先读取缓存 if cache_path.exists(): try: with open(cache_path, r, encodingutf-8) as f: cache json.load(f) if cache.get(expires_at, 0) time.time(): return cache[access_token] except (json.JSONDecodeError, KeyError, OSError): pass # 调用token接口 token_url https://aip.baidubce.com/oauth/2.0/token params { grant_type: client_credentials, client_id: app_id, client_secret: app_secret } response requests.post(token_url, paramsparams, timeout10) response.raise_for_status() data response.json() # 缓存token含过期时间戳 cache_data { access_token: data[access_token], expires_at: time.time() data[expires_in] - 300 # 提前5分钟过期 } with open(cache_path, w, encodingutf-8) as f: json.dump(cache_data, f, ensure_asciiFalse, indent2) return cache_data[access_token]参数说明app_id/app_secret从百度AI开放平台控制台「应用列表」中获取需创建OCR专用应用cache_file本地缓存路径默认为当前目录下baidu_token.json内容含access_token与expires_at时间戳expires_inAPI返回的秒数通常2592000秒30天减去300秒是为预留网络延迟与时钟误差缓冲response.raise_for_status()自动抛出HTTP错误异常如401密钥错误便于上层捕获处理。2.3 API选型basic vs accurate vs general百度OCR提供多档接口需根据图片质量与精度需求选择接口类型URL后缀适用场景识别速度费用千次关键限制basic/ocr/v1/basic普通印刷体、清晰截图快免费额度内可用不支持表格、公式、手写体accurate/ocr/v1/accurate含复杂版式、小字号、轻微倾斜中¥15单图最大4MB支持PDF转图general/ocr/v1/general多语言混合、低对比度、模糊文本慢¥30支持竖排、繁体、生僻字本项目默认使用basic因其满足1.PNG/2.PNG类标准截图需求且免费额度充足每日500次。若需处理扫描件或合同页应切换至accurate并调整图像预处理逻辑。3. 图像预处理与批量请求调度3.1 预处理为何不可跳过三类典型失败案例未预处理的原始图片常导致API返回空结果或乱码根本原因在于OCR引擎对输入有隐式要求分辨率不足手机拍摄的1.PNG若宽高320px文字像素点过少引擎无法提取特征对比度失衡扫描件背景泛灰非纯白文字边缘模糊words_result字段为空格式兼容性PNG透明通道、WebP压缩伪影、JPEG色度抽样偏差均可能触发error_code:17图片解码失败。因此预处理不是“锦上添花”而是保障成功率的必要环节。3.2 PIL预处理流水线缩放→灰度→二值化→格式标准化以下函数对单图执行标准化处理输出符合API要求的JPEG字节流from PIL import Image, ImageEnhance, ImageFilter import io def preprocess_image(image_path: str, target_width: int 1200) - bytes: 对图像进行标准化预处理返回JPEG格式字节流 :param image_path: 原始图片路径 :param target_width: 目标宽度保持宽高比缩放 :return: JPEG格式的bytes对象 try: img Image.open(image_path) # 1. 统一分辨率等比缩放至target_width避免过大超4MB或过小320px if img.width target_width: ratio target_width / img.width new_size (int(img.width * ratio), int(img.height * ratio)) img img.resize(new_size, Image.Resampling.LANCZOS) # 2. 转灰度去除色彩干扰提升文字对比度 if img.mode ! L: img img.convert(L) # 3. 增强对比度针对泛灰背景 enhancer ImageEnhance.Contrast(img) img enhancer.enhance(1.5) # 4. 二值化Otsu算法自动阈值 img img.point(lambda x: 0 if x 128 else 255, mode1) # 5. 转JPEG并压缩API明确要求JPEG/PNG/BMPPNG可能因透明通道报错 buffer io.BytesIO() img.save(buffer, formatJPEG, quality95) return buffer.getvalue() except Exception as e: raise ValueError(f预处理失败 {image_path}: {str(e)})关键参数说明target_width1200平衡清晰度与文件大小1200px宽度对应约1.5MB JPEG远低于4MB上限Image.Resampling.LANCZOS高质量缩放算法避免文字锯齿enhance(1.5)对比度增强系数实测1.3~1.8区间对扫描件效果最佳point(... mode1)强制二值化消除灰阶噪声显著提升印刷体识别率quality95JPEG压缩质量兼顾体积与文字锐度避免quality80导致笔画断裂。3.3 批量请求调度并发控制与错误重试直接for循环发送200个请求会触发百度限流error_code:18需引入并发控制与指数退避重试import asyncio import aiohttp from typing import List, Tuple, Optional async def ocr_single_image(session, image_bytes: bytes, access_token: str, api_url: str) - Tuple[str, Optional[str]]: 异步调用单张图片OCR try: async with session.post( api_url, params{access_token: access_token}, data{image: image_bytes}, timeoutaiohttp.ClientTimeout(total30) ) as resp: if resp.status 200: result await resp.json() if words_result in result: return success, \n.join([item[words] for item in result[words_result]]) elif error_msg in result: return api_error, result[error_msg] else: return unknown, str(result) else: return http_error, fHTTP {resp.status} except asyncio.TimeoutError: return timeout, 请求超时 except Exception as e: return exception, str(e) async def batch_ocr(image_paths: List[str], app_id: str, app_secret: str, concurrency: int 5) - List[Tuple[str, str, str]]: 批量OCR主函数返回(文件名, 状态, 结果/错误)元组列表 access_token get_access_token(app_id, app_secret) api_url https://aip.baidubce.com/rest/2.0/ocr/v1/basic # 预处理所有图片同步因I/O密集 preprocessed [] for path in image_paths: try: bytes_data preprocess_image(path) preprocessed.append((path, bytes_data)) except Exception as e: preprocessed.append((path, None)) # 异步并发请求 connector aiohttp.TCPConnector(limitconcurrency, limit_per_hostconcurrency) timeout aiohttp.ClientTimeout(total60) async with aiohttp.ClientSession(connectorconnector, timeouttimeout) as session: tasks [] for path, data in preprocessed: if data is not None: task ocr_single_image(session, data, access_token, api_url) tasks.append(task) else: tasks.append(asyncio.create_task(asyncio.sleep(0))) results await asyncio.gather(*tasks, return_exceptionsTrue) # 组装结果 output [] for i, (path, _) in enumerate(preprocessed): if i len(results) and not isinstance(results[i], Exception): status, content results[i] output.append((path, status, content)) else: output.append((path, preprocess_failed, 预处理异常)) return output调度逻辑说明concurrency5默认5路并发避免被限流百度未公开具体QPS实测5~10为安全阈值TCPConnector(limit5)限制总连接数防止端口耗尽ClientTimeout(total60)单请求最长60秒覆盖网络抖动preprocess_image同步执行因图像处理为CPU密集型异步无收益且需保证顺序results[i]索引对齐确保结果与image_paths顺序严格一致便于后续Word排版。4. Word文档结构化生成与结果验证4.1 为什么不能简单add_paragraph——文档层级与语义标记shiyan-docx.py生成的shiyan.docx需支持后续人工编辑与机器解析因此必须超越“纯文本拼接”。例如每张图片识别结果应作为独立章节添加标题如“图1会议签到表”若某图含多段文字应保留原文段落结构而非合并为单段错误识别项需显式标注而非静默丢弃。python-docx库通过Document.add_heading()和Paragraph样式控制实现此目标。4.2 结构化Word生成代码from docx import Document from docx.shared import Pt from docx.enum.text import WD_PARAGRAPH_ALIGNMENT def generate_word_report(results: List[Tuple[str, str, str]], output_path: str): 生成结构化Word报告 :param results: batch_ocr返回的结果列表 :param output_path: 输出docx路径 doc Document() # 添加封面标题 title doc.add_heading(批量文字识别报告, level0) title.alignment WD_PARAGRAPH_ALIGNMENT.CENTER # 逐条写入结果 for i, (path, status, content) in enumerate(results, 1): filename Path(path).name # 添加章节标题 heading doc.add_heading(f图{i}{filename}, level1) heading.runs[0].font.size Pt(14) # 写入识别结果或错误信息 if status success: # 分行处理content每行一个段落保留原文段落 for line in content.split(\n): if line.strip(): p doc.add_paragraph(line.strip()) p.style Normal else: # 错误项用红色字体标注 p doc.add_paragraph(f[识别失败] {status}{content}) p.runs[0].font.color.rgb RGBColor(255, 0, 0) # 插入分页符可选避免长图挤在一起 if i len(results): doc.add_page_break() doc.save(output_path) print(f✅ 报告已生成{output_path}) # 使用示例 if __name__ __main__: # 从当前目录读取所有PNG文件支持子目录 from pathlib import Path image_files [str(p) for p in Path(.).rglob(*.PNG)] # 执行批量OCR需替换为你的app_id/app_secret results asyncio.run(batch_ocr( image_files, app_idyour_app_id, app_secretyour_app_secret )) # 生成Word generate_word_report(results, shiyan.docx)样式控制要点level1标题生成Word中的“标题1”样式支持自动生成目录Pt(14)设置标题字号避免默认过小RGBColor(255,0,0)错误信息标红视觉上立即区分成功/失败项add_page_break()每图独立一页符合纸质文档阅读习惯content.split(\n)尊重API返回的换行符还原原始段落结构。4.3 结果验证三类必查指标与快速诊断表生成shiyan.docx后需验证是否真正可用而非仅“文件存在”。以下是工程师现场检查清单验证维度检查方法合格标准常见问题定位完整性打开Word统计页数与image_files数量页数 图片总数某图预处理失败未写入检查preprocess_failed日志准确性随机抽3页对照原图1.PNG/2.PNG关键字段人名、数字、日期100%正确API选错接口如用basic识别手写体改用accurate结构化在Word中点击「视图→导航窗格」左侧显示“图1xxx”等标题层级add_heading(level1)未调用或样式被模板覆盖注意若发现大量“识别失败”优先检查baidu_token.json是否过期其次验证preprocess_image是否对特定图片抛异常如PNG透明通道最后确认百度控制台中该APP的OCR服务是否已开通并启用。5. 生产环境加固环境变量注入与失败日志追踪5.1 拆离密钥用环境变量替代硬编码将app_id与app_secret从代码中移出改由系统环境变量注入杜绝密钥泄露风险# Linux/macOS export BAIDU_APP_IDyour_real_app_id export BAIDU_APP_SECRETyour_real_app_secret # Windows PowerShell $env:BAIDU_APP_IDyour_real_app_id $env:BAIDU_APP_SECRETyour_real_app_secret修改get_access_token调用方式import os app_id os.getenv(BAIDU_APP_ID) app_secret os.getenv(BAIDU_APP_SECRET) if not app_id or not app_secret: raise EnvironmentError(请设置环境变量 BAIDU_APP_ID 和 BAIDU_APP_SECRET)5.2 失败日志记录每张图的完整上下文当某张图识别失败时仅打印错误信息不足以定位问题。需记录原始图、预处理图、API请求体与响应体import logging from datetime import datetime # 配置日志 logging.basicConfig( levellogging.INFO, format%(asctime)s - %(levelname)s - %(message)s, handlers[ logging.FileHandler(ocr_debug.log, encodingutf-8), logging.StreamHandler() ] ) def log_failure(image_path: str, error_type: str, detail: str, original_size: tuple None, processed_bytes: bytes None): 记录详细失败日志 timestamp datetime.now().strftime(%Y%m%d_%H%M%S) log_entry f[{timestamp}] {image_path} | {error_type} | {detail} logging.error(log_entry) # 保存原始图与预处理图仅失败时 if original_size: with open(fdebug/{timestamp}_{Path(image_path).stem}_orig.png, wb) as f: with open(image_path, rb) as src: f.write(src.read()) if processed_bytes: with open(fdebug/{timestamp}_{Path(image_path).stem}_proc.jpg, wb) as f: f.write(processed_bytes)调用位置插入至batch_ocr的异常分支中确保每次失败都生成可复现的调试包。5.3 一键诊断脚本快速验证本地环境创建check_env.py运行即输出环境健康度#!/usr/bin/env python3 import sys import subprocess def check_dependency(cmd, name): try: subprocess.run(cmd, capture_outputTrue, checkTrue) print(f✅ {name} 可用) except (subprocess.CalledProcessError, FileNotFoundError): print(f❌ {name} 缺失请安装) def main(): print( 批量OCR环境诊断报告) print(- * 30) # 检查Python版本 print(fPython版本: {sys.version.split()[0]}) # 检查依赖包 check_dependency([sys.executable, -m, pip, show, requests], requests) check_dependency([sys.executable, -m, pip, show, Pillow], Pillow) check_dependency([sys.executable, -m, pip, show, python-docx], python-docx) check_dependency([sys.executable, -m, pip, show, aiohttp], aiohttp) # 检查环境变量 import os if os.getenv(BAIDU_APP_ID) and os.getenv(BAIDU_APP_SECRET): print(✅ BAIDU_APP_ID/APP_SECRET 已设置) else: print(❌ BAIDU_APP_ID/APP_SECRET 未设置) if __name__ __main__: main()运行python check_env.py5秒内确认所有依赖与配置是否就绪避免“代码写完却卡在环境”这种低级阻塞。提示将check_env.py加入Git仓库新成员克隆后首条命令即python check_env.py大幅降低协作门槛。本文还有配套的精品资源点击获取