msh-system/models-integration/docs/TENCENT_ASR_README.md

# 腾讯云语音识别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**：初始版本，实现录音文件识别、一句话识别和任务查询功能