Initial commit: MSH System\n\n- msh_single_uniapp: Vue 2 + UniApp 前端（微信小程序/H5/App/支付宝小程序）\n- msh_crmeb_22: Spring Boot 2.2 后端（C端API/管理端/业务逻辑）\n- models-integration: AI服务集成（Coze/KieAI/腾讯ASR）\n- docs: 产品文档与设计稿
This commit is contained in:
363
models-integration/docs/TENCENT_ASR_README.md
Normal file
363
models-integration/docs/TENCENT_ASR_README.md
Normal file
@@ -0,0 +1,363 @@
|
||||
# 腾讯云语音识别API对接文档
|
||||
|
||||
## 功能概述
|
||||
|
||||
本项目已成功集成腾讯云语音识别（ASR）服务，提供了以下功能：
|
||||
|
||||
1. **录音文件识别**：适用于较长的音频文件，采用异步方式识别
|
||||
2. **一句话识别**：适用于60秒以内的短音频，采用同步方式识别
|
||||
3. **任务状态查询**：查询异步识别任务的状态和结果
|
||||
|
||||
## API文档参考
|
||||
|
||||
- 官方文档：https://cloud.tencent.com/document/product/1093/35637
|
||||
- API概览：https://cloud.tencent.com/document/api/1093/35640
|
||||
|
||||
## 配置说明
|
||||
|
||||
### 1. 配置文件 (application.yml)
|
||||
|
||||
```yaml
|
||||
# 腾讯云语音识别配置
|
||||
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：
|
||||
|
||||
```bash
|
||||
export TENCENT_SECRET_KEY=your_secret_key_here
|
||||
```
|
||||
|
||||
或在启动命令中指定：
|
||||
|
||||
```bash
|
||||
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等）
|
||||
|
||||
**请求示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"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 |
|
||||
|
||||
**响应示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
```
|
||||
|
||||
**响应示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"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秒以内的短音频，同步返回识别结果
|
||||
|
||||
**请求示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"url": "https://example.com/short-audio.wav",
|
||||
"engineModelType": "16k_zh",
|
||||
"sourceType": 0,
|
||||
"filterDirty": false,
|
||||
"filterModal": false,
|
||||
"convertNumMode": true
|
||||
}
|
||||
```
|
||||
|
||||
**请求参数说明**：参数与创建任务接口相同，但不需要 callbackUrl
|
||||
|
||||
**响应示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"status": 2,
|
||||
"statusStr": "识别成功",
|
||||
"result": "你好世界",
|
||||
"audioDuration": 1.5,
|
||||
"requestId": "req_xyz789",
|
||||
"errorCode": 0,
|
||||
"errorMsg": "成功"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 健康检查
|
||||
|
||||
**接口地址**：`GET /api/tencent/asr/health`
|
||||
|
||||
**适用场景**：检查服务是否正常运行
|
||||
|
||||
**响应示例**：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "success",
|
||||
"data": "腾讯云语音识别服务运行正常"
|
||||
}
|
||||
```
|
||||
|
||||
## 使用流程
|
||||
|
||||
### 场景1：长音频识别（异步）
|
||||
|
||||
1. 调用 **创建录音文件识别任务** 接口，获取 taskId
|
||||
2. 使用 taskId 调用 **查询识别任务状态** 接口
|
||||
3. 当 status 为 2 时，表示识别成功，可从 result 字段获取识别结果
|
||||
|
||||
### 场景2：短音频识别（同步）
|
||||
|
||||
1. 直接调用 **一句话识别** 接口
|
||||
2. 同步返回识别结果
|
||||
|
||||
## 测试示例
|
||||
|
||||
### 使用 curl 测试
|
||||
|
||||
#### 1. 创建识别任务
|
||||
|
||||
```bash
|
||||
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. 查询任务状态
|
||||
|
||||
```bash
|
||||
curl http://localhost:5081/api/tencent/asr/query-status/1234567890
|
||||
```
|
||||
|
||||
#### 3. 一句话识别
|
||||
|
||||
```bash
|
||||
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：
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.tencentcloudapi</groupId>
|
||||
<artifactId>tencentcloud-sdk-java</artifactId>
|
||||
<version>3.1.909</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
## 联系方式
|
||||
|
||||
如有问题，请联系项目维护者或查看腾讯云官方文档。
|
||||
|
||||
## 更新日志
|
||||
|
||||
- **2025-11-05**：初始版本，实现录音文件识别、一句话识别和任务查询功能
|
||||
|
||||
Reference in New Issue
Block a user