在Spring Boot工程中接入语音识别接口，本质上就是把音频数据通过HTTP请求发送给识别服务，再解析返回的JSON结果。不同厂商的参数略有差异，但整体流程一致：读取音频文件、进行Base64编码或直接二进制上传、携带应用凭证、接收识别文本。本文抽象出一个通用调用结构，方便替换底层供应商。
工程准备与依赖配置
首先创建Spring Boot项目，引入Web能力即可满足HTTP客户端需求。这里使用RestTemplate作为调用工具，后续可以换成WebClient或OkHttp。在pom.xml中添加如下依赖：
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
如果项目中已经使用了Spring Cloud OpenFeign，也可以采用接口代理方式，但RestTemplate更直观。为了统一管理识别服务的地址和凭证，建议在application.yml中配置相关参数。
voice:
recognize:
url: https://api.ipipp.com/asr
app-key: your-app-key
access-token: your-access-token
timeout: 10000
注意示例中的地址是占位符，实际接入时需要替换成服务商提供的正式接口地址。音频格式尽量统一为16k采样率、16bit位深、单声道的PCM或WAV数据，这种格式识别率比较稳定。如果原始音频是mp3或者其他格式，可以用ffmpeg先做转换。
依赖就绪后，需要配置一个RestTemplate Bean。默认的RestTemplate足够使用，但建议关闭自动跳转并设置请求工厂的超时，避免因为服务端响应慢导致线程长期占用。
@Configuration
public class HttpClientConfig {
@Bean
public RestTemplate restTemplate() {
SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
factory.setConnectTimeout(5000);
factory.setReadTimeout(10000);
return new RestTemplate(factory);
}
}
这里设置的连接超时和读取超时可以根据实际音频大小调整。如果是长音频或较大文件，读取超时不宜过短，否则可能提前中断。
核心服务层封装
为了让调用逻辑清晰，先定义两个DTO：识别请求参数和识别响应结果。识别请求包含音频数据、音频格式、采样率等字段；识别响应包含识别文本、状态码、错误信息等。使用Lombok可以简化代码。
@Data
public class RecognizeRequest {
private String audioBase64;
private String format = "pcm";
private Integer sampleRate = 16000;
private String language = "zh-CN";
}
@Data
public class RecognizeResponse {
private Integer code;
private String message;
private String text;
}
服务接口只暴露一个识别方法，接收字节数组和文件名，内部完成编码和参数封装。这样控制器层不需要关心底层细节。实现类使用RestTemplate发送POST请求，并把响应JSON解析成RecognizeResponse。
@Service
public class VoiceRecognizeService {
private final RestTemplate restTemplate;
private final VoiceProperties properties;
public VoiceRecognizeService(RestTemplate restTemplate, VoiceProperties properties) {
this.restTemplate = restTemplate;
this.properties = properties;
}
public String recognize(byte[] audioBytes, String format) {
String base64 = Base64.getEncoder().encodeToString(audioBytes);
RecognizeRequest request = new RecognizeRequest();
request.setAudioBase64(base64);
request.setFormat(format);
HttpHeaders headers = new HttpHeaders();
headers.setContentType(MediaType.APPLICATION_JSON);
headers.set("X-App-Key", properties.getAppKey());
headers.set("Authorization", "Bearer " + properties.getAccessToken());
HttpEntity<RecognizeRequest> entity = new HttpEntity<>(request, headers);
ResponseEntity<RecognizeResponse> response = restTemplate.postForEntity(
properties.getUrl(), entity, RecognizeResponse.class);
if (response.getBody() == null || response.getBody().getCode() != 0) {
throw new IllegalStateException("识别失败: " + response.getBody());
}
return response.getBody().getText();
}
}
上面的代码假设服务端返回的JSON结构与RecognizeResponse一致。如果实际返回格式不同，可以通过自定义ResponseErrorHandler或手动解析JSON来适配。对于多家服务商并存的情况，可以定义接口并写多个实现类，通过配置切换。
短音频同步识别适合60秒以内的文件，长音频建议使用异步接口。异步方式先提交任务拿到任务ID，再定时轮询结果。实现上可以增加一个submit方法返回taskId，以及一个query方法根据taskId查询识别状态。轮询间隔建议1到2秒，最大等待时间根据音频长度调整。
控制器与调用测试
控制器接收上传的音频文件，调用服务层返回识别文本。这里使用MultipartFile接收文件，适合前端通过表单上传。也可以改为接收Base64字符串，方便移动端调用。
@RestController
@RequestMapping("/api/voice")
public class VoiceController {
private final VoiceRecognizeService recognizeService;
public VoiceController(VoiceRecognizeService recognizeService) {
this.recognizeService = recognizeService;
}
@PostMapping("/recognize")
public Map<String, Object> recognize(@RequestParam("file") MultipartFile file) throws IOException {
String text = recognizeService.recognize(file.getBytes(), "pcm");
Map<String, Object> result = new HashMap<>();
result.put("success", true);
result.put("text", text);
return result;
}
}
测试时可以使用curl命令模拟上传。假设接口路径为本地服务，音频文件为test.wav，命令如下：
curl -X POST http://localhost:8080/api/voice/recognize \ -F "file=@./test.wav"
如果音频文件较大，MultipartFile默认有大小限制，需要在application.yml中调整spring.servlet.multipart.max-file-size和max-request-size。比如设置为20MB，避免出现文件过大异常。
实际业务里还可以返回更多信息，比如置信度、语速、说话人分离结果。这些字段可以扩展RecognizeResponse，让前端展示更丰富的识别结果。对于实时字幕场景，应使用WebSocket流式识别，而不是等整段音频结束后再返回。
常见问题与优化建议
语音识别接口最常见的报错是音频格式不匹配。很多服务商明确要求PCM格式，如果传入WAV带文件头，可能导致识别为空。遇到识别结果为空时，先确认音频参数是否匹配，再检查Base64编码是否完整。可以用ffmpeg命令统一转换音频格式：
ffmpeg -i input.mp3 -ar 16000 -ac 1 -f s16le output.pcm
鉴权失败通常是因为accessToken过期或appKey不匹配。建议在服务层增加缓存机制，提前刷新令牌，并在收到401状态码时自动重试一次。网络超时问题可以通过设置合理的连接和读取超时缓解，同时对瞬时错误做指数退避重试。
识别结果的后处理同样重要。原始识别文本可能缺少标点，数字识别成中文或英文，特定词汇容易出错。可以配置热词表来提升专业术语的识别准确率。也可以对返回文本做规则替换，例如把全角数字转半角、统一日期格式。如果业务对准确率要求很高，可以引入人工校对流程。
安全方面，不要把应用密钥和访问令牌硬编码在代码里，也不要提交到公共仓库。推荐使用环境变量或者配置中心管理敏感信息。生产环境如果涉及用户隐私音频，还需要做好传输加密和存储脱敏。
通过以上步骤，Spring Boot工程可以比较稳妥地接入语音识别接口。核心是把音频数据组织成服务商要求的格式，封装HTTP调用并妥善处理异常，再根据业务场景选择同步或异步识别方案。
Spring Boot语音识别语音转文字修改时间：2026-09-24 10:12:23