简介：这是一份基于 C# 调用百度 OCR 接口的图像文字识别示例工程包，面向需要在 Windows 桌面应用中快速集成文字识别能力的开发者，尤其适合入门到中级 C# 程序员作为 AI 接口调用练手项目。资源重点演示了申请百度 AI 开放平台 API 密钥、构造含图片数据或图片地址的 HTTP 请求、设置识别语言与返回格式，并通过 Newtonsoft.Json 解析响应、提取识别文字与坐标信息的完整过程。包内共有 29 个文件、约 261KB，以 7 个 .cs 源代码文件为主，同时附有 .exe/.dll 运行依赖、.pdb 调试符号、.resx/.resources 窗体界面资源，以及 .sln/.csproj/.suo 等工程配置，目录结构接近标准 Visual Studio 解决方案，便于直接对照学习。当前已有 224 人学习下载。通过阅读 Ocr.cs、Form1.cs 和 Program.cs，可以看清从图像输入到文本输出的调用链条；若再结合自己的业务，可快速扩展出身份证识别、票据扫描、文档电子化等实用功能。
1. 一个 OCR.rar 压缩包背后的 C# 接入百度AI方案，到底能解决什么问题
一个后缀为 rar 的压缩包，名字里同时带着 OCR、C#、百度AI、百度图像识别这些关键词，多半不是商业安装包，而是某位开发者打包的百度OCR调用示例工程。百度AI开放平台提供文字识别 REST 接口，C# 客户端要自己完成 token 换取、图片转 base64、HttpClient 请求和 JSON 解析，才能把图片里的文字变成可用的文本数据。这套方案在 C# 上位机、桌面工具、信息采集场景里出现频率很高；不少老项目用 WinForm 或 WPF 写界面，机器上没装 Python 环境，OCR 只能靠云端接口。下面按「接口原理 → 工作代码 → 排查避坑 → 精度调优 → 可复用封装」的顺序，把链路完整走一遍，想接入的人可以直接当施工参考。
2. 百度OCR的C#接入前先理清四件事：接口选型、token 生命周期、图片边界与限流节奏
2.1 百度OCR的接口家族：通用文字识别和高精度版怎么选，和图像识别是什么关系
百度AI开放平台的 OCR 能力大致分两类：通用文字识别和高精度文字识别。通用版对应general_basic，适合截图、印刷体、屏幕拍摄这类对比度正常的图；高精度版对应accurate_basic，在手机随手拍、老照片、扫描件有倾斜或光照不均的情况下命中率明显更高，但代价是免费额度消耗更快。两个接口在 C# 代码里只是请求 URL 不同，参数几乎共用，切换成本很低。
标题里把“百度图像识别”和“百度OCR”并列，实际情况是：它们属于同一个百度AI控制台体系，共用同一套 API Key 和 Secret Key，只是 REST endpoint 不同。图像识别偏“看懂图片里是什么物体”，OCR 偏“读出图片里的文字”。C# 工程里建议把认证模块抽出来共用，因为所有百度AI接口都走同一条路：先用 AK/SK 换 access_token，再带 token 去调具体服务。顺便说一句，很多 Python 侧的识别脚本用 requests 写也就二十行，C# 端要做的逻辑完全一一对应，只是异步和类型处理多几步。
2.2 token 生命周期与缓存策略：不要每识别一张图就去换一次 token
百度AI开放平台的接口认证不是每个请求单独签名，而是先通过client_credentials模式换取 access_token。这个 token 默认有效期 30 天，换取接口是https://aip.baidubce.com/oauth/2.0/token。常见翻车姿势是把换取 token 的代码写在识别方法里，每次调用都发一次认证请求，结果识别还没跑多少，先撞上获取 token 的频率限制。
稳妥做法是在 C# 侧做内存缓存。静态字段存 token 字符串和过期时间，过期前直接复用；程序重启后缓存清空，第一次调用再换。注意不能只在“还剩 0 秒”时才刷新，要在剩余有效期小于 24 小时时就主动换——生产环境里服务器时钟漂移、调用密集都会让临界点前后的请求批量失败。并发方面用一个 SemaphoreSlim 保证同时只有一个线程去刷新 token，其余线程等在锁外，避免多线程同时打到认证接口造成重复换取。
2.3 图片大小和编码边界：base64 之后再判断，别只看文件属性
百度OCR 对图片有几条硬性限制：单张图片 base64 编码后大小不能超过 4M，长边像素不能超过 4096，短边不能小于 15。注意它的措辞是“base64 编码后”，不是原始文件大小。一个 3.5M 的 JPG 原图，转成 base64 之后轻松超过 4.7M，直接触发错误码 17（image size limit）。
C# 侧判断是否超限，统一按 base64 字符串长度来算。base64 的膨胀比是 4/3，原始字节数约等于base64.Length * 3 / 4。超出阈值就先压缩再上传，不要直接甩给接口。另外还有一类隐蔽问题：带 Alpha 透明通道的 PNG，某些情况下会被服务端判定为“图片格式不支持”。我一般在上传前把图片标准化转成 JPEG，Q 值 80 左右，既能解决透明通道问题，又能把体积压下来，识别效果和原图几乎无差别。
提示：base64 字符串的 Length 属性在 ASCII 模式下与字节数一致，直接用
.Length * 3 / 4估算原始大小即可。
3. 用 C# 把百度OCR跑通：从图片到文字的完整代码链路
3.1 工程配置：创建 .NET 8 类库，还是继续用老式 .NET Framework
我通常的做法是以 .NET 8 为目标框架建一个类库项目，专门承载 OCR 服务，上层 WinForm 或 WPF 直接引用。高版本框架对异步、JSON 反序列化和 HTTP/2 的支持更顺手，System.Text.Json 又是内置的，不用引第三方包。如果你手上的代码是老式 .NET Framework 4.x 工程，也不一定非要迁移，但至少确认三点：目标框架不低于 4.6.2，项目引用了 System.Net.Http，序列化用 Newtonsoft.Json 或 System.Text.Json 都行。System.Drawing.Common 在 Windows 上直接用没问题，跨平台发布时换成 ImageSharp 更稳。
3.2 认证与 Token 缓存：线程安全的 TokenManager 实现
下面这段代码可以直接抄进工程。它做成单例，缓存 token 和过期时间，并发下只允许一个线程去刷新，避免多线程同时撞认证接口。
using System.Text.Json; public class BaiduTokenManager { private static readonly Lazy<BaiduTokenManager> _instance = new Lazy<BaiduTokenManager>(() => new BaiduTokenManager()); public static BaiduTokenManager Instance => _instance.Value; private readonly HttpClient _http; private string? _token; private DateTime _expireAt = DateTime.MinValue; private readonly SemaphoreSlim _lock = new SemaphoreSlim(1, 1); private BaiduTokenManager() { _http = new HttpClient { Timeout = TimeSpan.FromSeconds(15) }; } public async Task<string> GetTokenAsync(string apiKey, string secretKey) { // 缓存有效且剩余时间大于一天，直接复用 if (_token != null && _expireAt > DateTime.Now.AddDays(1)) return _token; await _lock.WaitAsync(); try { // 双重检查，避免多个等待线程重复换取 if (_token != null && _expireAt > DateTime.Now.AddDays(1)) return _token; var form = new FormUrlEncodedContent(new Dictionary<string, string> { ["grant_type"] = "client_credentials", ["client_id"] = apiKey, ["client_secret"] = secretKey }); var resp = await _http.PostAsync( "https://aip.baidubce.com/oauth/2.0/token", form); var json = await resp.Content.ReadAsStringAsync(); using var doc = JsonDocument.Parse(json); var root = doc.RootElement; if (root.TryGetProperty("error", out var error)) throw new InvalidOperationException($"换取 token 失败: {error.GetString()}"); _token = root.GetProperty("access_token").GetString(); _expireAt = DateTime.Now.AddSeconds( root.GetProperty("expires_in").GetInt32()); return _token!; } finally { _lock.Release(); } } }逻辑说明：Lazy 单例保证全局只有一个 token 缓存；SemaphoreSlim 的WaitAsync会阻塞其他线程，直到刷新完成；双重检查避免所有等待线程都重新进去换 token。expires_in以秒为单位，默认 30 天，这里预留了 24 小时余量，宁可提前换一次，也不能让业务请求在临界点失败。
参数说明：apiKey和secretKey从百度AI控制台的应用列表里复制，对应创建应用时生成的 API Key 和 Secret Key，不是控制台登录密码。这两个值建议放进配置文件，不要硬编码在类里。
3.3 图片转 base64 前的预处理：等比缩放与 JPEG 标准化
百度OCR 对图片格式的支持比较玄学，同一个文件转成 PNG 能过，转成 BMP 可能就报错。所以我只保留 PNG 和 JPEG 两种输出，统一用 JPEG 质量 80 输出。
using System.Drawing; using System.Drawing.Imaging; public static class ImagePreprocessor { // 返回标准化后的字节数组和 base64 字符串 public static (byte[] bytes, string base64) NormalizeToJpeg( string imagePath, int maxSide = 4096) { // 用字节数组加载，避免文件句柄被 Bitmap 锁住 var rawBytes = File.ReadAllBytes(imagePath); using var ms = new MemoryStream(rawBytes); using var src = Image.FromStream(ms); double ratio = Math.Min(1.0, (double)maxSide / Math.Max(src.Width, src.Height)); int newW = Math.Max(1, (int)(src.Width * ratio)); int newH = Math.Max(1, (int)(src.Height * ratio)); using var bmp = new Bitmap(newW, newH); using var g = Graphics.FromImage(bmp); g.Clear(Color.White); g.InterpolationMode = System.Drawing.Drawing2D.InterpolationMode.HighQualityBicubic; g.DrawImage(src, 0, 0, newW, newH); using var outMs = new MemoryStream(); bmp.Save(outMs, ImageFormat.Jpeg); var bytes = outMs.ToArray(); return (bytes, Convert.ToBase64String(bytes)); } }逻辑说明：File.ReadAllBytes把文件内容一次性读进内存，然后用Image.FromStream加载，这样 Bitmap 不直接持有文件句柄，识别完不会出现“文件被占用”的经典报错。缩放比例ratio用Math.Min(1.0, ...)封顶，图片本来就小于边界时不会无谓放大。白色背景填充解决了透明通道问题。
参数说明：maxSide默认 4096，对应百度OCR 长边限制；JPEG 质量 80 是一个平衡点，文件体积比质量 90 小约三成，识别效果肉眼不可见差别。若图片宽度超过 4096 但高度很小，也可以设置minSide之类的下限参数，但实际操作中 4096 边界就够用了。
3.4 调用通用接口并解析结果：网络请求与 C# 响应处理
识别调用本身不复杂，难在把错误码和异常网络情况都兜住。这里给出完整封装。
public enum BaiduOcrLevel { General, // POST /rest/2.0/ocr/v1/general_basic Accurate // POST /rest/2.0/ocr/v1/accurate_basic } public class BaiduOcrClient { private readonly string _apiKey; private readonly string _secretKey; private readonly HttpClient _http; public BaiduOcrClient(string apiKey, string secretKey) { (_apiKey, _secretKey) = (apiKey, secretKey); _http = new HttpClient { Timeout = TimeSpan.FromSeconds(30) }; } public async Task<List<string>> RecognizeAsync( string base64Image, BaiduOcrLevel level = BaiduOcrLevel.General) { var token = await BaiduTokenManager.Instance.GetTokenAsync(_apiKey, _secretKey); var url = level == BaiduOcrLevel.General ? "https://aip.baidubce.com/rest/2.0/ocr/v1/general_basic" : "https://aip.baidubce.com/rest/2.0/ocr/v1/accurate_basic"; var content = new FormUrlEncodedContent(new Dictionary<string, string> { ["image"] = base64Image, ["detect_direction"] = "true", ["detect_language"] = "true", ["paragraph"] = "true" }); using var req = new HttpRequestMessage(HttpMethod.Post, $"{url}?access_token={token}"); req.Content = content; using var resp = await _http.SendAsync(req); if (!resp.IsSuccessStatusCode) { var errBody = await resp.Content.ReadAsStringAsync(); throw new HttpRequestException($"OCR 接口 HTTP {(int)resp.StatusCode}: {errBody}"); } var json = await resp.Content.ReadAsStringAsync(); return ParseWordsResult(json); } private static List<string> ParseWordsResult(string json) { using var doc = JsonDocument.Parse(json); var root = doc.RootElement; // 百度错误码放在 error_code 字段，HTTP 状态码仍然是 200 if (root.TryGetProperty("error_code", out var code)) { var msg = root.TryGetProperty("error_msg", out var m) ? m.GetString() : "未知错误"; throw new InvalidOperationException($"百度OCR错误码 {code.GetInt32()}: {msg}"); } var list = new List<string>(); if (root.TryGetProperty("words_result", out var words)) { foreach (var item in words.EnumerateArray()) { if (item.TryGetProperty("words", out var w)) list.Add(w.GetString()!); } } return list; } }逻辑说明：access_token放在 URL 的 query 参数里，image放在表单体里，这是百度 REST 接口唯一正确的姿势。FormUrlEncodedContent会自动处理 base64 里的+号转义，不会出现自己拼字符串时把+变空格的问题。解析响应时注意：百度的业务错误码是放在error_code字段里返回的，HTTP 状态码可能仍是 200，所以必须先检查error_code，再取words_result。
参数说明：detect_direction=true让接口自动判断 0/90/180/270 方向；detect_language=true自动识别中英文混合内容；paragraph=true在返回结果里增加段落标示，方便后续按段落排版。需要每个词的具体坐标时，改用general或accurate（不带_basic后缀），响应里会额外带location字段，不过单位是像素，需要和原图尺寸对应换算。
4. C#接入百度OCR的排查与避坑：五个高频报错的现象、原因和解决
4.1 报“Open api image size limit”但图片看起来并不大
现象：用户传了一张 3.8M 的 JPG，程序抛异常，提示图片大小超限。查看文件属性，明明小于 4M。
原因：百度OCR 的限制对象是 base64 编码后的字符串大小，不是原始文件字节数。JPG 文件 3.8M，转 base64 后变成约 5.1M，超过 4M 上限，服务端直接拒绝。
解决：在上传前检查 base64 长度，估算公式为base64.Length * 3 / 4。超过阈值就调用ImagePreprocessor.NormalizeToJpeg先转 JPEG 质量 75 并缩边到 2048 再编码。尤其注意 PNG 截图场景，无损压缩的 PNG 对 UI 截图反而比 JPG 更大，压缩空间有限，先转 JPEG 再缩放才是正确顺序。
4.2 返回错误码 110 或 111，token 无效或过期
现象：程序运行一段时间后突然大面积识别失败，错误信息为 token 无效或 token 过期。
原因：百度 access_token 有效期是 30 天，过期后必须重新换取。很多工程把 token 写死在配置里，跑了一个月后集体失效。另外，从浏览器复制 token 时容易带上换行或空格，拼进 URL 后也会导致认证失败。
解决：代码侧必须让 TokenManager 在过期前自动刷新，不能只缓存不失效。日志侧要把error_msg完整记下来——110 表示 token 本身无效，111 表示 token 已过期。前者检查 AK/SK 是否正确复制，后者检查服务器系统时间是否被正确同步。我遇到过一次内网机器系统时间慢了 2 天，导致 token 一直被判定为过期，这类问题排错时先对时间。
4.3 返回错误码 18，QPS 超限
现象：用Parallel.For批量识别文件夹里的图片，瞬间发了几十个并发请求，接口返回 18（Open api qps request limit reached）。
原因：百度OCR 免费配额对 QPS 限制严格，通用接口默认每秒 2 次。并发一多必然超限。
解决：在客户端加信号量限速，把并发压到可控范围。下面是一个带节流阀的调用封装：
private static readonly SemaphoreSlim _throttle = new SemaphoreSlim(2, 2); public async Task<string> ThrottledRecognizeAsync(string base64) { await _throttle.WaitAsync(); try { // 两次请求之间至少间隔 450ms，把 QPS 压到 2 以内 await Task.Delay(450); return await RecognizeAsync(base64); } finally { _throttle.Release(); } }逻辑说明：SemaphoreSlim(2, 2)表示最多 2 个并发进入，Task.Delay(450)让每个请求之间至少间隔 450ms，稳定在每秒 2 次左右。450ms 不是精确值，百度限流窗口有抖动，按 95% 余量预留比较稳。上线前可以用 100 张图循环压测，观察日志里是否还有 18 错误码。
4.4 识别出的中文乱码或结果为空字符串
现象：HTTP 返回 200，words_result里没有错误码，但内容是空字符串或一串乱码。
原因：多为请求体编码问题。如果用StringContent手动拼表单，base64 里的+号会被当作空格解码，导致图片数据损坏。另外，中文文本截图若字体渲染带子像素抗锯齿，边缘颜色混杂，通用版对浅色底纹的识别容易漏字。
解决：不要手动拼接表单，直接用FormUrlEncodedContent，它会自动处理+号转义。如果必须手动拼串，把+替换成%2B。识别结果连续出现空字符串时，先怀疑图片预处理，而不是接口——把图片放大到 200% 看看文字边缘是否发虚，发虚就先做灰度化再重新截图。
4.5 识别完保存图片时提示“文件正在被另一进程使用”
现象：WinForm 里选图识别，识别完把图片显示到 PictureBox，然后保存或删除原文件，系统报文件被占用。
原因：Image.FromFile会一直持有文件句柄，Bitmap 是原生资源，GC 不能保证即时释放。这不是百度OCR 的问题，是 C# 桌面开发的经典老坑。
解决：不要直接用Image.FromFile，改为File.ReadAllBytes→MemoryStream→Image.FromStream，用完主动 Dispose。我在前面的代码里已经按这个写法处理了。这条规矩对 WPF 同样适用，上位机工程师心里默认都要有数。
5. 把识别率再往上推：图片预处理管道、方向矫正与离线兜底设计
5.1 先处理图片再调用百度OCR，而不是直接甩原图
百度OCR 对低质量输入的容错有限，识别率提升的第一优先级不是换接口，而是让图片更接近“干净印刷体扫描件”的状态。C# 侧按收益排序可以做的预处理：灰度化、对比度拉伸、倾斜矫正、二值化。灰度化能降低 JPEG 压缩噪声对文字边缘的干扰；对比度拉伸用裁剪 2% 像素的线性映射，能缓解高光反光；二值化采用 Otsu 全局阈值，但只在直方图双峰明显时启用，光照不均的场景直接二值化反而会劣化识别效果。
一个可用的预处理管道：
public static Bitmap PreprocessForOcr(Bitmap src) { var gray = ToGrayscale(src); // 去掉最暗、最亮 2% 像素，拉伸中间对比度 ContrastStretch(gray, 2); float angle = EstimateSkewAngle(gray); if (Math.Abs(angle) > 8) Rotate(gray, -angle); return gray; }逻辑说明：EstimateSkewAngle的实现可以用水平投影法：把灰度图按行累加像素值，找出文本行的峰值位置，计算斜率的反正切。只在角度超过 8 度时执行旋转，避免反复旋转对画质造成损失。小角度倾斜不用自己做，把detect_direction=true交给百度即可——注意它只处理 0/90/180/270 整方向，不做细粒度旋转矫正，真正倾斜严重的图必须自做旋转。
注意：预处理会改变图片的像素坐标系。如果后续要使用
location坐标标注结果，旋转后的坐标值和原图不再对应，要么在旋转后的图上重新取坐标，要么就放弃坐标，只取纯文本。
5.2 竖排文字和纵向阅读顺序：百度OCR的局限与绕行方案
有用户搜“umi ocr 竖排 / 纵向阅读顺序开关”，那是指另一个 OCR 工具的选项。百度OCR 这边的实际情况是：general_basic默认按横排输出，竖排文本会用detect_direction把整图转到 0 度，但竖排文字本身不会被调成横排阅读。如果你处理的是竖排古籍、证书类图片，我的经验是把图片逆时针旋转 90 度让文字变成水平，再交给通用识别，命中率比硬调接口参数高得多。
另一个相关参数是recognize_granularity=small，它会在结果里返回更细粒度的字块坐标。拿到字块坐标后，自己按location.top判断文字块的垂直分布，就能推断出原本的阅读顺序——这是百度接口没直接给、但 C# 侧很容易实现的逻辑。代码里加一个按 top 值排序的步骤，比相信黑匣子输出更可靠。
5.3 批量识别与离线兜底：不把鸡蛋全放在云端一个篮子里
批量识别场景，除了 QPS 限速，还要处理失败重试和中间结果落盘。我建议的调度策略：第一遍全量识别，失败的记录路径并重试一次，再失败的写入 failList；成功的结果每张图单独写同名 .txt，不要攒到最后一次性写盘——程序中途崩了也有半程成果，这是血泪经验。
离线兜底方面，如果项目对网络稳定性有要求，可以搭配 Tesseract OCR 或 PaddleOCR 的本地部署。Tesseract 的优势是部署简单、跨平台，识别率在印刷体场景尚可；PaddleOCR 的中文识别效果更好但部署体积大。一个折中的兜底设计：云端接口失败超过 3 次自动切到本地方案，用同一个预处理管道输出，保证识别流程不断。本地离线 OCR 软件在纯内网场景几乎是刚需，Anytxt 之类偏全文检索，嵌入式集成还得靠 Tesseract 或 Paddle 这类库。
6. 收尾：把 OCR 能力封装成 C# 上位机里可复用的服务，并验证效果
6.1 最小改造方案：DI 容器注册 + 失败重试 + 日志记录
最后一步是把 OCR 从“能跑”变成“能养”。推荐把BaiduOcrClient注册为单例服务，让整个窗体程序共享同一个 HttpClient 和 token 缓存。
// Program.cs 或启动配置中注册 services.AddSingleton<BaiduOcrClient>(sp => new BaiduOcrClient(config["Baidu:ApiKey"], config["Baidu:SecretKey"])); // 窗体里的调用 var ocr = serviceProvider.GetRequiredService<BaiduOcrClient>(); var texts = await ocr.RecognizeAsync(base64, BaiduOcrLevel.Accurate);逻辑说明：单例注册保证 HttpClient 和 token 缓存不因 new 新对象而反复重建。UI 线程里务必用 async/await，不要用.Result阻塞等待——在 WPF 消息循环里这么做很容易触发死锁。重试策略建议只对网络异常生效，业务错误码（比如 17 图片超限、18 限流）不要无脑重试，先修输入再发请求。
6.2 验证方法：准备三类样本做对照，量化识别率
写完后验证用三组图片：第一组是印刷体清晰截图 10 张，目标识别率 99% 以上；第二组是手机自然光拍摄 10 张，目标 90% 以上；第三组是带倾斜、反光、噪点的图 5 张，不设硬性指标，只记录兜底准确率。每张图的识别结果存下来连原图归档，后面换接口版本时直接回测，省得凭感觉判断。
这几步做完，这个方向就站稳了。我自己每次接新的 OCR 需求都先把这三件事写进骨架：token 缓存、QPS 限速、图片预检。后续无论是把 general 换成 accurate 高精度版，还是加离线兜底，都只动一行 URL。做技术方案最怕后期返工，提前把这些常态化，能省掉后面一大半头痛时间。希望帮到你。
本文还有配套的精品资源，点击获取
