简介这是一套面向C#开发者的百度OCR图片文字识别示例工程覆盖本地图片与网络图片两种识别场景可应用于文档扫描、表单录入、截图提取等自动化文本处理。压缩包共57个文件约2.07MB其中15个cs为C#源码、9个dll为所引用的类库、3个exe为可直接运行的程序另有config配置文件、resx界面资源、xml说明和示例jpg/png图片整体为可编译的完整工程目录结构清晰便于按模块研读。目前已有657人学习参考适合刚接触OCR API或想快速上手C#调用百度接口的开发者。工程完整演示了获取访问令牌、读取或下载图片、构造请求、解析返回JSON及异常处理等关键流程并包含身份证识别与通用文字识别的窗体实现付费版在调用额度和识别能力上更完整能帮助读者直接借鉴并搭建自己的图片文字提取工具。1. 用C#调百度OCR付费版本地图片和网络图片识别文字差在哪本地图片和网络图片调用同一个百度OCR接口返回的却往往不是同一份结果网络图多出下载、格式判断和访问时效三个变量付费版又叠加了配额、QPS和费用的约束。C#生态里最常见的做法是把百度OCR封装成一个HttpClient客户端用access_token做鉴权本地图走base64字段网络图先拉字节流再统一识别最后解析JSON把文字块带进业务逻辑。这里按这条主线把本地路径、远程URL、图片压缩、并发控制拆开讲并补上付费版应有的验证手段。适合处理截图、票据、面单和远程抓图的C#开发者或上位机工程师做服务端的同行可以直接看限流和压缩那两段压测时最容易在那里翻车。2. 百度OCR付费版接入准备接口选型、密钥配置和连通性检查2.1 为什么“付费版”通常对应高精度文字识别接口百度智能云开放的OCR接口不止一个C#代码要先对准目标。标题里的“付费版”一般落在通用文字识别高精度版接口路径是rest/2.0/ocr/v1/accurate_basic按量计费控制台能看到免费调用量、资源包和欠费状态。标准版路径是rest/2.0/ocr/v1/general_basic免费额度更大但斜体、艺术字、复杂背景文字的容错会弱一些。实际项目里票据、证书、屏幕截图最容易出现的问题是浅色背景和低对比度文字。我一般默认先接高精度版把流程跑通再根据失败样本统计决定要不要降级如果业务限定为白底黑字印刷体就切到标准版压成本。“付费版”不是独立产品而是你选择了高精度接口并开启按量计费后的使用状态。代码层面两个接口只差URL和价格参数结构几乎一样这给后期调接口留了余地不至于重写封装。2.2 创建应用、拿API Key并用配置项承接密钥接入前要做三步注册并完成实名认证创建应用拿到 API Key 和 Secret Key在文字识别产品下开通高精度版并完成按量后付费或资源包设置。第三步最容易漏漏掉后调用会收到17 Open api daily request limit reached常常被误判成代码问题。密钥到手不要直接写进 class 里。控制台程序习惯放appsettings.json老式 WinForm 用App.config也可以只是读取层会多一点。最小配置如下{ BaiduOcr: { ApiKey: 你的API Key, SecretKey: 你的Secret Key, TokenUrl: https://aip.baidubce.com/oauth/2.0/token, AccurateUrl: https://aip.baidubce.com/rest/2.0/ocr/v1/accurate_basic, MaxImageBytes: 4194304, MaxConcurrent: 2 } }各项在 C# 里的作用与配错后的现象整理成表方便排查配置节点作用配错后的特征ApiKey / SecretKey换取 access_token报110或提示 token 无效AccurateUrl高精度版识别地址URL 拼错通常返回非 200 状态码MaxImageBytes上传前的体积门槛超限后在本地被拦截不消耗 QPSMaxConcurrent客户端并发上限超过账号 QPS 会收到18错误密钥能不进工程文件就不要进。交付.rar源码包时真实 Key 应放到部署机器的环境变量里代码读Environment.GetEnvironmentVariable(BAIDU_OCR_API_KEY)更安全。API Key 和 Secret Key 合在一起才能换 access_tokenSecret Key 一旦进过 Git 历史就算泄漏优先动作是换 Key 而不是删文件。提示appsettings.json 里的密钥只服务于本地调试发布和交付前要替换成环境变量或密钥管理服务别让源码包直接带着真实值流转。2.3 用最短的C#请求确认密钥、TLS和网络链路写 OCR 业务之前先用一段不带图片逻辑的代码把 Token 请求打一遍能一次性隔离三类故障密钥错误、TLS 版本不匹配、代理拦截。老式 .NET Framework 上位机工程最常见的是 TLS 1.0/1.1 握手失败先把协议抬到 1.2using System.Net; using System.Text.Json; ServicePointManager.SecurityProtocol | SecurityProtocolType.Tls12; using var http new HttpClient { Timeout TimeSpan.FromSeconds(15) }; string tokenUrl https://aip.baidubce.com/oauth/2.0/token ?grant_typeclient_credentials client_id Environment.GetEnvironmentVariable(BAIDU_OCR_API_KEY) client_secret Environment.GetEnvironmentVariable(BAIDU_OCR_SECRET_KEY); using var doc JsonDocument.Parse(await http.GetStringAsync(tokenUrl)); Console.WriteLine(doc.RootElement.GetProperty(access_token));这里|是在原有协议集合上追加不是覆盖.NET 6 默认已协商到 TLS 1.2/1.3不写也能跑。请求如果超时先确认目标机器可以访问aip.baidubce.com再看系统代理。企业内网有时只放行了 HTTPHTTPS 请求被静默丢弃用HttpClientHandler.Proxy显式指定代理地址能解决一部分。打印出access_token后再进入真正的识别代码问题定位会轻松很多。3. C#实现本地图片文字识别Token缓存、Base64传图、JSON字段解析3.1 为什么access_token要缓存而不是每次现取百度OCR的鉴权分两步走先用 API Key 和 Secret Key 换 access_token再拿 token 请求 OCR 接口。token 有效期通常是 30 天每次识别都重新申请不只是浪费一次 HTTP 请求还会在批量扫描时触发限流。正确做法是在进程内缓存 token并设置一个提前过期时间。public class BaiduOcrService { private readonly HttpClient _http; private readonly BaiduOcrOptions _options; private string? _accessToken; private DateTime _expiresAt DateTime.MinValue; public BaiduOcrService(HttpClient http, BaiduOcrOptions options) { _http http; _options options; } public async Taskstring GetTokenAsync() { if (_accessToken ! null _expiresAt DateTime.UtcNow.AddMinutes(5)) { return _accessToken; } var url ${_options.TokenUrl}?grant_typeclient_credentials $client_id{_options.ApiKey}client_secret{_options.SecretKey}; using var json JsonDocument.Parse(await _http.GetStringAsync(url)); _accessToken json.RootElement.GetProperty(access_token).GetString(); var expiresIn json.RootElement.GetProperty(expires_in).GetInt32(); _expiresAt DateTime.UtcNow.AddSeconds(expiresIn); return _accessToken!; } }这里用DateTime.UtcNow而不是DateTime.Now避免机器时区影响过期判断。AddMinutes(5)是提前量即使百度侧认为 token 还剩 5 分钟有效客户端也不再复用防止某一次请求正巧撞上过期。多线程场景里首次并发会同时进入GetTokenAsync这取决于服务是不是单例。若是单例可以在类里加SemaphoreSlim锁住 Token 获取段若是容器多实例要控制实例数量否则几十个实例同一秒打 Token 接口也会很难看。3.2 本地图片读字节流、转Base64、设置识别参数识别本地图片的请求体是一个表单image字段放图片 Base64可选参数有language_type、detect_direction、paragraph等。高精度版对图片体积有上限限制客户端在上传前做一次体积检查比等百度返回错误更划算。public async Taskstring RecognizeLocalFileAsync(string filePath) { var bytes await File.ReadAllBytesAsync(filePath); if (bytes.Length _options.MaxImageBytes) { throw new InvalidDataException($图片大小 {bytes.Length} 超过限额 {_options.MaxImageBytes}); } var token await GetTokenAsync(); var form new Dictionarystring, string { [image] Convert.ToBase64String(bytes), [language_type] CHN_ENG, [detect_direction] true, [paragraph] true, [probability] true }; using var content new FormUrlEncodedContent(form); var url ${_options.AccurateUrl}?access_token{token}; using var response await _http.PostAsync(url, content); return await response.Content.ReadAsStringAsync(); }FormUrlEncodedContent会处理 URL 编码Base64 字符串里的和/不会被误读。有人喜欢把data:image/png;base64,前缀一起塞进去这会导致图片解析失败记得只传纯 Base64。detect_directiontrue会返回图片方向扫描件建议一直开paragraphtrue对连续文本段落有效但会增加响应体大小probabilitytrue给每个文字块附加置信度生产环境建议开启第 5 章会用它做人工复核分流。3.3 高频字段表和C# DTO设计先看一遍原始 JSON再落 DTO 更稳妥。核心字段并不复杂JSON字段C#类型含义log_idlong百度侧单次调用日志 IDwords_result_numint识别出的文本块数量words_resultarray文本块列表words_result[].wordsstring单块文字内容words_result[].locationobject左上角坐标、宽高words_result[].probabilityobject字符及平均置信度directionint0、1、2、3 对应 0°、90°、180°、270°一个够用的 DTO 类可以写成public class BaiduOcrResult { public long log_id { get; set; } public int words_result_num { get; set; } public ListOcrWordResult words_result { get; set; } new(); public int? direction { get; set; } } public class OcrWordResult { public string words { get; set; } ; public OcrLocation? location { get; set; } public OcrProbability? probability { get; set; } }words_result_num和words_result.Count绝大多数场景相等但不要用它替代列表长度。界面展示时把每个words拼接起来再根据direction决定是否旋转原图。location的左上角和宽高是像素值做框选标注时可直接映射到System.Drawing.Rectangle。高精度版对表格、数学公式、手写体的返回仍是纯文本后续结构化还得靠模板和正则这一步不要指望 OCR 一次到位。4. C#识别网络图片文字直接传URL还是先下载再识别4.1 直接传url和下载后传image怎么选百度OCR部分接口同时支持image和url两个字段网络图片可以把地址直接放进url省掉下载步骤。但“能传”不等于“合适”。C#生产环境里直接传 URL 有三个边界图片源是否允许百度服务器访问URL 是否带时效签名图片站点是否做防盗链。签名 URL 通常在十分钟到一小时之间失效失效后百度侧拿到的是 403 页面内网图片更不要试百度服务器访问不到路由器后面的地址。反向看先下载再识别多一次网络往返和内存占用请求却完全可控。两种方式的取舍用一张表落清楚维度直接传url下载后传image实现成本低一个字段解决中多出下载和校验私网/内网图片不支持支持带签名 URL有失效窗口失效前完成下载即可站点防盗链大概率失败可用请求头配合大图处理百度侧按原图识别本地可先压缩还需要注意网络图片地址若带中文参数直接把url字段交给FormUrlEncodedContent编码就好不要提前对整个地址UrlEncode双重编码会让百度侧拿到错误资源。4.2 用HttpClient把网络图片安全地下载成字节数组实际开发里我更多走下载路径给图片下载单独做方法。方法返回字节数组而不是临时文件临时文件一旦没有及时清理长期跑批量任务容易把系统盘占满。下面这个方法做三件事确认状态码、校验 Content-Type、限制响应体大小。public async Taskbyte[] DownloadImageAsync(string imageUrl, int maxBytes 4 * 1024 * 1024) { using var request new HttpRequestMessage(HttpMethod.Get, imageUrl); request.Headers.TryAddWithoutValidation(User-Agent, Mozilla/5.0 (Windows NT 10.0; Win64; x64)); request.Headers.TryAddWithoutValidation(Accept, image/*); using var response await _http.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, CancellationToken.None); if (!response.IsSuccessStatusCode) { throw new InvalidDataException($下载图片失败HTTP {(int)response.StatusCode}); } string? contentType response.Content.Headers.ContentType?.MediaType; if (string.IsNullOrEmpty(contentType) || !contentType.StartsWith(image/)) { throw new InvalidDataException($目标返回类型不是图片{contentType}); } await using var stream await response.Content.ReadAsStreamAsync(); using var buffer new MemoryStream(); await stream.CopyToAsync(buffer); if (buffer.Length maxBytes) { throw new InvalidDataException($图片超过 {maxBytes} 字节); } return buffer.ToArray(); }HttpCompletionOption.ResponseHeadersRead在响应头到达后就让异步方法返回再通过CopyToAsync流式写入内存如果直接ReadAsByteArrayAsync大图会先整段进入缓冲内存峰值翻倍。加User-Agent和源站要求的Referer属于常规客户端配置不是绕过鉴权的手段源站明确要求私有签名头时应在授权范围内用同一组HttpRequestMessage.Headers设置。个别图源会把图片当application/octet-stream返回此时 Content-Type 校验会拦下需要再用文件头判断是不是 PNG/JPEG后一种场景可以放宽到“能解码就算图片”。4.3 网络大图的本地压缩处理网络图片经常出现高清大图单边超过 4000 像素很常见。百度OCR高精度版对体积和边长有限制不能等返回错误再处理识别前先压缩。跨平台服务建议用SkiaSharpWinForm 里用System.Drawing也可以下面这个函数按最长边等比缩放public static byte[] EnsureMaxSide(byte[] source, int maxSide 2048, int quality 88) { using var input SKBitmap.Decode(source); if (input null) { throw new InvalidDataException(无法解码图片可能不是真实图片文件); } int longSide Math.Max(input.Width, input.Height); if (longSide maxSide) { return source; } float scale (float)maxSide / longSide; int width Math.Max(1, (int)(input.Width * scale)); int height Math.Max(1, (int)(input.Height * scale)); using var resized input.Resize(new SKImageInfo(width, height), SKFilterQuality.Medium); using var image SKImage.FromBitmap(resized); using var data image.Encode(SKEncodedImageFormat.Jpeg, quality); return data.ToArray(); }等比例缩小不丢文字可读性反而能去掉一部分 JPEG 块状噪声SKFilterQuality.Medium对普通文档够用细线表格和印章场景用 High。压缩质量quality88是白底黑字比较稳的值低于 80 时细笔画边缘会出锯齿。注意SKBitmap.Decode遇到损坏文件会返回 null先抛异常不要等到百度返回一个费解的216200再去猜。压缩逻辑放在字节数组层不要先写临时图片再读批量识别时能少很多磁盘 IO。5. 百度OCR付费版验证手段并发限流、结果去重与置信度分流5.1 用SemaphoreSlim把并发压进QPS阈值百度后台对每个应用有 QPS 约束付费版会提高上限但不意味着没有上限。C# 批量任务常用Task.WhenAll并行识别一旦把账号 QPS 打穿百度会返回18 Open api qps request limit reached。常见做法是给识别动作套一个SemaphoreSlim让并发由客户端统一控制而不是交给调用方随意拉起private readonly SemaphoreSlim _gate new(2, 2); public async Taskstring RecognizeWithLimitAsync(string filePath) { await _gate.WaitAsync(); try { return await _service.RecognizeLocalFileAsync(filePath); } finally { _gate.Release(); } }new SemaphoreSlim(2, 2)表示初始容量和最大容量都是 2即同时最多两个识别请求在途。账号后台显示 QPS 是 5 时客户端压到 3 或 4 更稳因为请求到达不是均匀的打满阈值就容易触发限流。被限流后不要立即重试指数退避比固定间隔效果更好配合 CancellationToken 可以让批量任务在停止指令下来时快速退出。5.2 结果去重与置信度分流控制付费版成本接入百度OCR付费版后最怕重复计费。同一摄像头每隔几秒抓一帧跑十几个小时会积攒大量相同图片在识别入口前计算字节数组的 MD5把最近识别过的结果放进ConcurrentDictionary命中就直接返回缓存能省下不小的调用成本。这个缓存要设上限否则长时间运行后内存增长不可控。另一个技巧是开启probability参数后按置信度分流单块文字平均置信度低于 0.6 的进人工复核队列而不是直接入库避免一个字错穿透到后续自动化流程。验证动作放在上线前做一次用同一张测试图分别走本地路径和网络 URL 路径确认words_result_num和首行文本一致再把控制台的调用日志与本地记录的log_id对上。两边的log_id对不上说明代码里藏在 URL 编码、重定向或超时重试上的问题这时候再回头查配置不迟。本文还有配套的精品资源点击获取
