Spring Boot开发者指南：从零构建腾讯云OCR服务（附完整源码）

原创 于 2025-07-26 18:00:32 发布 · 置顶 · 796 阅读 · 20 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#spring boot #腾讯云 #ocr

一、腾讯云OCR简介与应用场景

腾讯云OCR（光学字符识别）服务提供高精度的文字识别能力，支持身份证、银行卡、营业执照、通用印刷体等多种识别场景。相比百度OCR，腾讯云OCR在金融票据识别和证件识别方面具有独特优势。

主要应用场景：

  • 金融行业：支票、汇票识别

  • 政务领域：身份证、驾驶证识别

  • 企业办公：合同、发票数字化

  • 教育行业：试卷、文档电子化

二、项目配置与依赖设置

1. 腾讯云账号准备

  1. 访问腾讯云控制台

  2. 创建子账号并分配OCR权限

  3. 获取SecretId和SecretKey

2. Maven依赖 (pom.xml)

<dependencies>
    <!-- Spring Boot基础依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- 配置属性处理 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-configuration-processor</artifactId>
        <optional>true</optional>
    </dependency>
    
    <!-- 腾讯云Java SDK -->
    <dependency>
        <groupId>com.tencentcloudapi</groupId>
        <artifactId>tencentcloud-sdk-java</artifactId>
        <version>3.1.270</version>
    </dependency>
</dependencies>

3. YAML配置 (application.yml)

tencent:
  ocr:
    secret-id: "your-secret-id"          # 腾讯云SecretId
    secret-key: "your-secret-key"        # 腾讯云SecretKey
    region: "ap-guangzhou"               # 服务区域
    general-ocr-endpoint: "ocr.tencentcloudapi.com"
    id-card-ocr-endpoint: "ocr.tencentcloudapi.com"
    engine-type: "GeneralBasicOCR"       # 默认引擎
    
    # 连接池配置
    max-idle-conns: 100                  # 最大空闲连接数
    keep-alive-seconds: 120              # 保持连接时间(秒)
    
    # 重试策略
    max-retries: 3                       # 最大重试次数
    
    # 图像限制
    max-image-size: 3145728              # 3MB (3 * 1024 * 1024)

# Spring异步配置
spring:
  task:
    execution:
      pool:
        core-size: 10
        max-size: 50
        queue-capacity: 100
        thread-name-prefix: OCR-Async-

# 文件上传限制
spring:
  servlet:
    multipart:
      max-file-size: 3MB
      max-request-size: 10MB

三、配置参数封装

1.配置类 (TencentOcrProperties.java)

@Data
@Builder
@Component
@AllArgsConstructor
@NoArgsConstructor
@ConfigurationProperties(prefix = "tencent.ocr")
public class TencentOcrProperties {
    private String secretId;
    private String secretKey;
    private String region;
    private String generalOcrEndpoint;
    private String idCardOcrEndpoint;
    private String engineType;
    
    // 新增连接池配置
    private int maxIdleConns = 50;
    private int keepAliveSeconds = 60;
    private int maxRetries = 3;
    private int maxImageSize = 3 * 1024 * 1024; // 3MB
}

2.配置类OcrClientConfig （客户端Bean管理） 

import com.tencentcloudapi.common.Credential;
import com.tencentcloudapi.common.profile.ClientProfile;
import com.tencentcloudapi.common.profile.HttpProfile;
import com.tencentcloudapi.ocr.v20181119.OcrClient;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OcrClientConfig {

    @Autowired
    private TencentOcrProperties ocrProperties;

    @Bean(name = "generalOcrClient", destroyMethod = "shutdown")
    public OcrClient generalOcrClient() {
        return createOcrClient(ocrProperties.getGeneralOcrEndpoint());
    }

    @Bean(name = "idCardOcrClient", destroyMethod = "shutdown")
    public OcrClient idCardOcrClient() {
        return createOcrClient(ocrProperties.getIdCardOcrEndpoint());
    }

    private OcrClient createOcrClient(String endpoint) {
        Credential cred = new Credential(
            ocrProperties.getSecretId(), 
            ocrProperties.getSecretKey()
        );
        
        HttpProfile httpProfile = new HttpProfile();
        httpProfile.setEndpoint(endpoint);
        httpProfile.setMaxIdleConns(ocrProperties.getMaxIdleConns());
        httpProfile.setKeepAliveDuration(ocrProperties.getKeepAliveSeconds() * 1000);
        
        ClientProfile clientProfile = new ClientProfile();
        clientProfile.setHttpProfile(httpProfile);
        
        return new OcrClient(cred, ocrProperties.getRegion(), clientProfile);
    }
}

3. 异步配置支持 AsyncConfig

import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.annotation.AsyncConfigurer;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;

import java.util.concurrent.Executor;

@Configuration
@EnableAsync
public class AsyncConfig implements AsyncConfigurer {

    @Override
    public Executor getAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(10);
        executor.setMaxPoolSize(50);
        executor.setQueueCapacity(100);
        executor.setThreadNamePrefix("OCR-Async-");
        executor.initialize();
        return executor;
    }
}

四、OCR服务实现

1. OCR服务类 (TencentOcrService.java)

import com.tencentcloudapi.common.Credential;
import com.tencentcloudapi.common.exception.TencentCloudSDKException;
import com.tencentcloudapi.common.profile.ClientProfile;
import com.tencentcloudapi.common.profile.HttpProfile;
import com.tencentcloudapi.ocr.v20181119.OcrClient;
import com.tencentcloudapi.ocr.v20181119.models.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;
import org.springframework.web.multipart.MultipartFile;

import javax.annotation.PostConstruct;
import javax.annotation.PreDestroy;
import javax.imageio.ImageIO;
import java.awt.*;
import java.awt.image.BufferedImage;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.util.Base64;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

@Service
public class TencentOcrService {

    private final TencentOcrProperties ocrProperties;
    private OcrClient generalOcrClient;
    private OcrClient idCardOcrClient;
    private final ExecutorService asyncExecutor = Executors.newFixedThreadPool(10);

    @Autowired
    public TencentOcrService(TencentOcrProperties ocrProperties) {
        this.ocrProperties = ocrProperties;
    }

    // 初始化OCR客户端（带连接池）
    @PostConstruct
    public void init() {
        this.generalOcrClient = createOcrClient(ocrProperties.getGeneralOcrEndpoint());
        this.idCardOcrClient = createOcrClient(ocrProperties.getIdCardOcrEndpoint());
    }

    // 销毁资源
    @PreDestroy
    public void shutdown() {
        if (generalOcrClient != null) {
            generalOcrClient.shutdown();
        }
        if (idCardOcrClient != null) {
            idCardOcrClient.shutdown();
        }
        asyncExecutor.shutdown();
    }

    // 创建OCR客户端（带连接池配置）
    private OcrClient createOcrClient(String endpoint) {
        Credential cred = new Credential(ocrProperties.getSecretId(), ocrProperties.getSecretKey());
        
        HttpProfile httpProfile = new HttpProfile();
        httpProfile.setEndpoint(endpoint);
        httpProfile.setMaxIdleConns(ocrProperties.getMaxIdleConns());
        httpProfile.setKeepAliveDuration(ocrProperties.getKeepAliveSeconds() * 1000);
        
        ClientProfile clientProfile = new ClientProfile();
        clientProfile.setHttpProfile(httpProfile);
        
        return new OcrClient(cred, ocrProperties.getRegion(), clientProfile);
    }

    /**
     * 通用文字识别（同步）
     */
    public String recognizeGeneralText(MultipartFile file) throws Exception {
        validateImage(file);
        BufferedImage processedImage = preprocessImage(file);
        String imageBase64 = convertToBase64(processedImage);
        
        GeneralBasicOCRRequest request = new GeneralBasicOCRRequest();
        request.setImageBase64(imageBase64);
        
        return callOcrApiWithRetry(
            request, 
            "GeneralBasicOCR", 
            generalOcrClient, 
            ocrProperties.getMaxRetries()
        );
    }

    /**
     * 通用文字识别（异步）
     */
    @Async
    public CompletableFuture<String> recognizeGeneralTextAsync(MultipartFile file) {
        return CompletableFuture.supplyAsync(() -> {
            try {
                return recognizeGeneralText(file);
            } catch (Exception e) {
                throw new RuntimeException("异步OCR识别失败", e);
            }
        }, asyncExecutor);
    }

    /**
     * 身份证识别
     */
    public String recognizeIdCard(MultipartFile file, boolean isFront) throws Exception {
        validateImage(file);
        BufferedImage processedImage = preprocessImage(file);
        String imageBase64 = convertToBase64(processedImage);
        
        IdCardOCRRequest request = new IdCardOCRRequest();
        request.setImageBase64(imageBase64);
        request.setCardSide(isFront ? "FRONT" : "BACK");
        
        return callOcrApiWithRetry(
            request, 
            "IDCardOCR", 
            idCardOcrClient, 
            ocrProperties.getMaxRetries()
        );
    }

    /**
     * 带重试机制的API调用
     */
    private String callOcrApiWithRetry(AbstractModel request, String engineType, 
                                       OcrClient client, int maxRetries) 
        throws Exception {
        
        int retryCount = 0;
        while (true) {
            try {
                return executeOcrApiCall(request, engineType, client);
            } catch (TencentCloudSDKException e) {
                if (shouldRetry(e, retryCount, maxRetries)) {
                    retryCount++;
                    Thread.sleep(calculateBackoffTime(retryCount));
                } else {
                    throw new Exception("OCR识别失败: " + e.getMessage(), e);
                }
            }
        }
    }

    /**
     * 执行OCR API调用
     */
    private String executeOcrApiCall(AbstractModel request, String engineType, OcrClient client) 
        throws TencentCloudSDKException {
        
        switch (engineType) {
            case "GeneralBasicOCR":
                return GeneralBasicOCRResponse.toJsonString(
                    client.GeneralBasicOCR((GeneralBasicOCRRequest) request));
                    
            case "GeneralAccurateOCR":
                return GeneralAccurateOCRResponse.toJsonString(
                    client.GeneralAccurateOCR((GeneralAccurateOCRRequest) request));
                    
            case "IDCardOCR":
                return IdCardOCRResponse.toJsonString(
                    client.IdCardOCR((IdCardOCRRequest) request));
                    
            default:
                throw new IllegalArgumentException("不支持的OCR引擎类型: " + engineType);
        }
    }

    /**
     * 图像预处理（灰度化）
     */
    private BufferedImage preprocessImage(MultipartFile file) throws IOException {
        BufferedImage originalImage = ImageIO.read(file.getInputStream());
        
        // 转换为灰度图像
        BufferedImage grayImage = new BufferedImage(
            originalImage.getWidth(), 
            originalImage.getHeight(),
            BufferedImage.TYPE_BYTE_GRAY
        );
        
        Graphics2D g2d = grayImage.createGraphics();
        g2d.drawImage(originalImage, 0, 0, null);
        g2d.dispose();
        
        return grayImage;
    }

    /**
     * 将BufferedImage转换为Base64
     */
    private String convertToBase64(BufferedImage image) throws IOException {
        ByteArrayOutputStream baos = new ByteArrayOutputStream();
        ImageIO.write(image, "jpg", baos);
        return Base64.getEncoder().encodeToString(baos.toByteArray());
    }

    /**
     * 验证图片
     */
    private void validateImage(MultipartFile file) throws IOException {
        if (file == null || file.isEmpty()) {
            throw new IllegalArgumentException("请上传图片文件");
        }
        
        if (file.getSize() > ocrProperties.getMaxImageSize()) {
            throw new IllegalArgumentException(
                "图片大小不能超过" + (ocrProperties.getMaxImageSize() / 1024) + "KB");
        }
        
        // 验证图片格式
        String contentType = file.getContentType();
        if (contentType == null || 
            !(contentType.equals("image/jpeg") || 
             contentType.equals("image/png") || 
             contentType.equals("image/bmp"))) {
            throw new IllegalArgumentException("仅支持JPG/PNG/BMP格式图片");
        }
    }

    /**
     * 判断是否需要重试
     */
    private boolean shouldRetry(TencentCloudSDKException e, int retryCount, int maxRetries) {
        return retryCount < maxRetries && 
               (e.getErrorCode().equals("RequestLimitExceeded") || 
                e.getErrorCode().equals("InternalError"));
    }

    /**
     * 计算退避时间（指数退避）
     */
    private long calculateBackoffTime(int retryCount) {
        return (long) (500 * Math.pow(2, retryCount));
    }
}

五、控制器实现

OCR控制器 (OcrController.java)

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;

import java.util.concurrent.CompletableFuture;

@RestController
@RequestMapping("/api/ocr")
public class OcrController {

    private final TencentOcrService ocrService;

    @Autowired
    public OcrController(TencentOcrService ocrService) {
        this.ocrService = ocrService;
    }

    // 同步通用文字识别
    @PostMapping("/general")
    public ResponseEntity<?> generalOcr(@RequestParam("image") MultipartFile file) {
        try {
            String result = ocrService.recognizeGeneralText(file);
            return ResponseEntity.ok(result);
        } catch (Exception e) {
            return ResponseEntity.badRequest().body(
                new ErrorResponse("OCR_FAILED", e.getMessage()));
        }
    }

    // 异步通用文字识别
    @PostMapping("/general/async")
    public CompletableFuture<ResponseEntity<?>> generalOcrAsync(
            @RequestParam("image") MultipartFile file) {
        return ocrService.recognizeGeneralTextAsync(file)
            .thenApply(ResponseEntity::ok)
            .exceptionally(ex -> ResponseEntity.badRequest().body(
                new ErrorResponse("ASYNC_OCR_FAILED", ex.getCause().getMessage())));
    }

    // 身份证识别（正面）
    @PostMapping("/idcard/front")
    public ResponseEntity<?> idCardFront(@RequestParam("image") MultipartFile file) {
        try {
            String result = ocrService.recognizeIdCard(file, true);
            return ResponseEntity.ok(result);
        } catch (Exception e) {
            return ResponseEntity.badRequest().body(
                new ErrorResponse("IDCARD_OCR_FAILED", e.getMessage()));
        }
    }

    // 身份证识别（反面）
    @PostMapping("/idcard/back")
    public ResponseEntity<?> idCardBack(@RequestParam("image") MultipartFile file) {
        try {
            String result = ocrService.recognizeIdCard(file, false);
            return ResponseEntity.ok(result);
        } catch (Exception e) {
            return ResponseEntity.badRequest().body(
                new ErrorResponse("IDCARD_OCR_FAILED", e.getMessage()));
        }
    }

    // 错误响应封装
    private static class ErrorResponse {
        private String errorCode;
        private String message;

        public ErrorResponse(String errorCode, String message) {
            this.errorCode = errorCode;
            this.message = message;
        }

        // Getters
        public String getErrorCode() { return errorCode; }
        public String getMessage() { return message; }
    }
}

六. 高级功能解析

1. 连接池优化

  • 通过 HttpProfile.setMaxIdleConns() 配置最大空闲连接数

  • 使用 keep-alive 减少TCP连接建立开销

  • 客户端单例模式避免重复创建

2. 智能重试机制

  • 指数退避算法：重试间隔 = 500ms * 2^retryCount

  • 条件重试：仅对限流错误(RequestLimitExceeded)和系统错误(InternalError)重试

  • 最大重试次数：通过配置灵活控制

3. 异步处理流程

4. 图像预处理优化

  • 灰度转换：减少颜色干扰，提高识别准确率

  • 格式统一：统一转换为JPG格式

  • 大小校验：防止过大文件导致API失败

5. 防御性编程

  • 文件类型校验：仅允许JPG/PNG/BMP格式

  • 大小限制：防止DDoS攻击

  • 错误封装：统一错误响应格式

Spring AI 项目实战（二）：Spring Boot + AI + DeepSeek 深度实战（附完整源码）
博客
05-25 2565
本文介绍了SpringAI框架与国产大模型DeepSeek的工程化集成方案，探讨了传统软件开发与AI工程化开发的核心差异。文章详细演示了从环境搭建到应用开发的全流程，包括项目配置、API集成、流式响应处理等关键环节。通过SpringAI的标准化接口封装，开发者可以快速实现营销文案生成、代码生成、智能问答等功能，并支持高并发推理和多模型管理。本文还剖析了SpringAI的自动装配原理和核心接口设计，为企业级AI应用开发提供了可扩展的技术方案。该方案显著降低了AI集成门槛，为国产化AI模型落地提供了工程实践参考
Spring AI 项目实战（三）：Spring Boot + AI + DeepSeek 打造智能客服系统（附完整源码）
最新发布
博客
06-02 1611
摘要 本文介绍了基于Spring Boot 3.2和Spring AI 1.0.0-M4构建智能客服系统的技术方案。系统采用分层架构设计，集成DeepSeek API提供自然语言处理能力，使用MyBatis和H2数据库实现数据持久化，并通过Thymeleaf+Bootstrap构建前端界面。文章详细阐述了项目的技术栈选择、Maven依赖配置、应用架构设计，以及各模块的功能划分，为开发者提供了完整的智能客服系统实现方案，涵盖从后端服务到前端交互的全流程开发指导。
通过腾讯云的文字识别进行图文转换【java】
civilizationV的博客
07-01 1142
#1、获取secretId和secretKey https://console.cloud.tencent.com/cam/capi 生成密钥 #2、 inputStream读取图片 解析出的json异常 本应为double的现在为int 百度调用图文识别 tess4j调用图文识别
Java腾讯云文字识别相关问题以及使用方法，结合springboot+vue
weixin_45521812的博客
06-25 1341
Java实现文字识别（腾讯云）
Java集成腾讯云OCR身份证识别接口
Aikes Blog
10-27 2903
经过验证，该方式可以访问经过Nginx代理的腾讯云接口。整个解决过程缺少对问题现状的分析，并没有制定切入点，而是想到哪里改哪里，所以修改的过程异常煎熬。后续对于问题的挖掘及解决要整体分析然后列出各个怀疑的情况和解决方案，然后对照着清单逐一排查，如此条理清晰的处理过程才会更有效的解决问题。
腾讯云OCR识别
qq_58399194的博客
03-07 6184
腾讯云OCR高精度表格识别之各种API接口使用介绍
腾讯云OCR（印刷体识别） API使用
braxuyu4的博客
11-28 1146
腾讯云OCR（印刷体识别） API使用
SpringBoot整合Tesseract-OCR实现图像文字识别
xiaoyu❅的博客
03-12 2249
是由HP实验室开发、现由Google维护的开源OCR（Optical Character Recognition）引擎，支持超过100种语言的文字识别。开源免费：Apache 2.0许可证跨平台支持多语言识别：支持中文、英文、日文等可训练模型：支持自定义字库训练。
spring-boot-停车场管理系统.rar
08-02
3. 入场管理：车辆进入停车场时，系统记录车牌号、入场时间等信息，可能使用到OCR技术识别车牌，Spring Boot结合WebSocket实现实时通信，通知后台处理。 4. 出场管理：车辆离开时，根据入场信息计算停车费用，支持...
spring-boot使用培训.pdf
12-14
Spring Boot是一个流行的Java框架，它简化了基于Spring的应用开发，使得开发者能够快速搭建和运行独立的、生产级别的基于Spring的应用。本培训文档旨在介绍Spring Boot的基础知识和使用方法，使初学者能够迅速掌握...
Spring Boot个人理财记账系统源码解析
Spring Boot是Spring开源框架的一个子项目，它简化了基于Spring的应用开发过程，通过提供一系列大型项目中常见的默认配置，从而允许开发者迅速启动和运行项目。Spring Boot非常适合构建独立的、生产级别的Spring基础...
腾讯云OCR简介和使用流程
tiancaijiben的博客
06-07 6355
腾讯云OCR（Optical Character Recognition）是一款基于腾讯云计算能力和深度学习技术，提供高精度、高效率、易集成的文字识别服务。支持多种类型的识别，包括身份证、银行卡、驾驶证、行驶证、车牌号、通用印刷体、手写体等。在人工智能、金融、教育、物流、医疗等行业中广泛应用，帮助用户快速、准确地完成数据录入、识别、处理和管理。
腾讯云健康码+行程码OCR文字识别
SHEN525758203的专栏
09-17 2147
这边文章基于腾讯云的OCR文字识别
java调用腾讯文字识别接口：行驶证识别
m0_61387445的博客
12-10 1421
识别行驶证的正副页面，java调用腾讯OCR
Java实现数据标注功能
qq_48959845的博客
12-20 1226
只能做好相对比较好的图片，对于图片被旋转 或是图片不规则的标注出来还是有一定误差和缺陷的，而且严重依赖第三方ocr识别接口。温馨提示：使用他们的接口不是免费的喔，厉害的大神可以自己去训练一个这样的模型。这个其实应该用python实现会容易一些，不过不影响Java也可以。又是奇葩需求的一天，产品给了一张原图。
依赖包冲突，Error creating bean
weixin_42049458的博客
04-14 2035
启动Spring项目失败，日志提示Error creating bean with name ‘gsonBuilder’ defined in class path resource 这里是在提醒创建在类路径资源中定义了名为“gsonBuilder”的bean时出错，通常是gsonBuilder这个依赖包有冲突，比如你pom导入的依赖包下，有子依赖包与Spring的子依赖包重复时，就会抛出这个错误，根据类路径资源导入bean时抛出了这个错误。 笔者完整抛错如下： 2021-04-14 23:33:38..
集成腾讯云短信接口
Ss信仰的博客
09-14 1409
1、引入依赖 compile('com.tencentcloudapi:tencentcloud-sdk-java:3.1.69') compile('commons-beanutils:commons-beanutils:1.7.0') 2、编写工具类 import java.util.Arrays; import java.util.List; import java.util.Random; import org.apache.log4j.Logger; import ...
maven无法加载腾讯云存储com.qcloud:cos_api
ytgytg28的博客
08-07 1634
折腾一下午，晚上要睡觉了，突然想到，能不能子pom.xml中看看能不能引入，结果一遍就成功引入了，更换了几个版本号，都没有问题。打算使用腾讯云的存储COS，由于项目中使用的是父子moudel,在父pom.xml中引入依赖。于是返回主pom,设置成引入成功的版本，结果也成功了。2、此方法也可以作为解决以来无法引入的一个方法来尝试一下。4.jar包直接安装没试，因为没找到jar包~~~腾讯云存储的依赖服务器出问题了，无法正常下载依赖。基本上网上的方法都试了，就是不行。3.将本地库全删除重新加载。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值