scottpan/msh-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
aae96b15be969e67ca27d75c6d2cd21aa399805e
msh-system/models-integration/docs/TENCENT_ASR_README.md

8.8 KiB
Raw Blame History

腾讯云语音识别API对接文档

功能概述

本项目已成功集成腾讯云语音识别（ASR）服务，提供了以下功能：

  1. 录音文件识别：适用于较长的音频文件，采用异步方式识别
  2. 一句话识别：适用于60秒以内的短音频，采用同步方式识别
  3. 任务状态查询：查询异步识别任务的状态和结果

API文档参考

配置说明

1. 配置文件 (application.yml)

# 腾讯云语音识别配置
tencent-asr:
  # API密钥ID
  secret-id: AKIDf9OM3TdWBZqqZ1C7k6B0Ypqb6KIzQaT5
  # API密钥Key（需要在实际使用时提供）
  secret-key: ${TENCENT_SECRET_KEY:}
  # API地区
  region: ap-shanghai
  # 连接超时时间（毫秒）
  connect-timeout: 30000
  # 读取超时时间（毫秒）
  read-timeout: 60000
  # 默认引擎模型类型（16k_zh：中文普通话、16k_en：英文）
  default-engine-model: 16k_zh
  # 默认结果文本格式（0：识别结果文本，包含标点符号；1：不带标点的识别结果）
  default-res-text-format: 0
  # 默认音频声道数（1：单声道；2：双声道）
  default-channel-num: 1
  # 是否启用
  enabled: true

2. 环境变量配置

为了安全起见，建议通过环境变量设置 SecretKey：

export TENCENT_SECRET_KEY=your_secret_key_here

或在启动命令中指定：

java -jar models-integration-0.0.1.jar --tencent-asr.secret-key=your_secret_key_here

API接口说明

基础URL

http://localhost:5081/api/tencent/asr

1. 创建录音文件识别任务

接口地址：POST /api/tencent/asr/create-task

适用场景：适用于较长的音频文件（支持多种格式：wav、pcm、mp3、silk、speex、amr、m4a等）

请求示例：

{
  "url": "https://example.com/audio.wav",
  "engineModelType": "16k_zh",
  "channelNum": 1,
  "resTextFormat": 0,
  "sourceType": 0,
  "callbackUrl": "https://your-callback-url.com/callback",
  "filterDirty": false,
  "filterModal": false,
  "convertNumMode": true
}

请求参数说明：

参数 类型 必填 说明
url String 是 音频文件URL地址
engineModelType String 否 引擎模型类型，默认：16k_zh
channelNum Integer 否 音频声道数，1：单声道；2：双声道，默认：1
resTextFormat Integer 否 识别结果文本格式，0：带标点；1：不带标点，默认：0
sourceType Integer 否 音频来源，0：音频URL；1：音频数据（base64），默认：0
callbackUrl String 否 回调URL，任务完成后将结果POST到该地址
hotwordId String 否 热词表ID，用于提高专有名词识别准确率
filterDirty Boolean 否 是否过滤脏词，默认：false
filterModal Boolean 否 是否过滤语气词，默认：false
convertNumMode Boolean 否 是否进行阿拉伯数字智能转换，默认：false

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "1234567890",
    "status": 0,
    "statusStr": "等待处理",
    "requestId": "req_abc123def456",
    "errorCode": 0,
    "errorMsg": "成功"
  }
}

引擎模型类型说明：

  • 16k_zh：16k 中文普通话通用
  • 16k_zh_video：16k 音视频领域
  • 16k_en：16k 英语
  • 16k_ca：16k 粤语
  • 8k_zh：8k 中文普通话通用

2. 查询识别任务状态

接口地址：GET /api/tencent/asr/query-status/{taskId}

适用场景：查询异步识别任务的状态和结果

请求示例：

GET /api/tencent/asr/query-status/1234567890

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "1234567890",
    "status": 2,
    "statusStr": "识别成功",
    "result": "你好，这是一段语音识别测试内容。",
    "audioDuration": 5.5,
    "errorCode": 0,
    "errorMsg": "",
    "resultDetail": "{\"Result\":[{\"Text\":\"你好，这是一段语音识别测试内容。\"}]}"
  }
}

任务状态说明：

  • 0：等待处理
  • 1：执行中
  • 2：识别成功
  • 3：识别失败

3. 一句话识别

接口地址：POST /api/tencent/asr/sentence-recognition

适用场景：适用于60秒以内的短音频，同步返回识别结果

请求示例：

{
  "url": "https://example.com/short-audio.wav",
  "engineModelType": "16k_zh",
  "sourceType": 0,
  "filterDirty": false,
  "filterModal": false,
  "convertNumMode": true
}

请求参数说明：参数与创建任务接口相同，但不需要 callbackUrl

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "status": 2,
    "statusStr": "识别成功",
    "result": "你好世界",
    "audioDuration": 1.5,
    "requestId": "req_xyz789",
    "errorCode": 0,
    "errorMsg": "成功"
  }
}

4. 健康检查

接口地址：GET /api/tencent/asr/health

适用场景：检查服务是否正常运行

响应示例：

{
  "code": 200,
  "message": "success",
  "data": "腾讯云语音识别服务运行正常"
}

使用流程

场景1：长音频识别（异步）

  1. 调用 创建录音文件识别任务 接口，获取 taskId
  2. 使用 taskId 调用 查询识别任务状态 接口
  3. 当 status 为 2 时，表示识别成功，可从 result 字段获取识别结果

场景2：短音频识别（同步）

  1. 直接调用 一句话识别 接口
  2. 同步返回识别结果

测试示例

使用 curl 测试

1. 创建识别任务

curl -X POST http://localhost:5081/api/tencent/asr/create-task \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/audio.wav",
    "engineModelType": "16k_zh",
    "channelNum": 1,
    "resTextFormat": 0,
    "convertNumMode": true
  }'

2. 查询任务状态

curl http://localhost:5081/api/tencent/asr/query-status/1234567890

3. 一句话识别

curl -X POST http://localhost:5081/api/tencent/asr/sentence-recognition \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/short-audio.wav",
    "engineModelType": "16k_zh",
    "convertNumMode": true
  }'

使用 Swagger UI 测试

启动应用后，访问：http://localhost:5081/swagger-ui.html

在 Swagger UI 中找到 "腾讯云语音识别接口" 分组，即可进行可视化测试。

音频格式要求

支持的音频格式

  • wav
  • pcm
  • mp3
  • silk
  • speex
  • amr
  • m4a

音频参数建议

  • 采样率：16k 或 8k（根据选择的引擎模型）
  • 位深度：16bit
  • 声道数：1（单声道）或 2（双声道）
  • 编码：PCM

注意事项

  1. API密钥安全：

    • 不要将 SecretKey 直接写入配置文件
    • 建议使用环境变量或密钥管理服务

  2. 音频时长限制：

    • 一句话识别：≤ 60秒
    • 录音文件识别：≤ 5小时

  3. 音频大小限制：

    • 单个音频文件 ≤ 500MB

  4. 回调地址：

    • 如果设置了 callbackUrl，任务完成后会自动回调
    • 回调地址必须是公网可访问的 HTTP/HTTPS 地址

  5. 费用说明：

    • 腾讯云语音识别服务按使用量计费
    • 请在腾讯云控制台查看具体计费标准

错误处理

常见错误码：

错误码 说明 解决方案
InvalidParameter 参数错误 检查请求参数是否正确
AuthFailure.SignatureFailure 签名错误 检查 SecretId 和 SecretKey 是否正确
ResourceUnavailable.NotFound 资源不存在 检查 taskId 是否正确
LimitExceeded 超过配额限制 联系腾讯云增加配额

项目结构

src/main/java/com/integration/api/
├── config/
│   └── TencentAsrConfig.java              # 腾讯云ASR配置类
├── controller/
│   └── TencentAsrController.java          # ASR控制器
├── dto/
│   ├── TencentAsrRequest.java             # ASR请求DTO
│   ├── TencentAsrResponse.java            # ASR响应DTO
│   └── TencentAsrTaskStatus.java          # ASR任务状态DTO
└── service/
    ├── TencentAsrService.java             # ASR服务接口
    └── impl/
        └── TencentAsrServiceImpl.java     # ASR服务实现类

依赖说明

项目使用了腾讯云官方 Java SDK：

<dependency>
    <groupId>com.tencentcloudapi</groupId>
    <artifactId>tencentcloud-sdk-java</artifactId>
    <version>3.1.909</version>
</dependency>

联系方式

如有问题，请联系项目维护者或查看腾讯云官方文档。

更新日志

  • 2025-11-05：初始版本，实现录音文件识别、一句话识别和任务查询功能
Reference in New Issue View Git Blame Copy Permalink