msh-system/models-integration/docs/TENCENT_ASR_配置指南.md

# 腾讯云语音识别 - 快速配置指南

## ⚠️ 当前错误

您遇到的错误：
```
The provided credentials could not be validated. Please check your signature is correct.
```

**原因**：SecretKey 未配置或配置错误

---

## 🔧 解决方案（3种方式任选其一）

### 方式1：环境变量配置（✅ 推荐，最安全）

#### 步骤1：获取完整的密钥对
1. 登录腾讯云控制台
2. 访问：https://console.cloud.tencent.com/cam/capi
3. 找到您的 SecretId：`AKIDf9OM3TdWBZqqZ1C7k6B0Ypqb6KIzQaT5`
4. 复制对应的 **SecretKey**（通常是一个40位的字符串）

#### 步骤2：设置环境变量
```bash
# 设置环境变量
export TENCENT_SECRET_KEY="你的SecretKey"

# 验证是否设置成功
echo $TENCENT_SECRET_KEY
```

#### 步骤3：重启应用
```bash
# 停止应用
./stop.sh

# 启动应用（会自动读取环境变量）
./start.sh
```

---

### 方式2：修改 application.yml（⚠️ 不推荐生产环境）

编辑配置文件：
```yaml
tencent-asr:
  secret-id: AKIDf9OM3TdWBZqqZ1C7k6B0Ypqb6KIzQaT5
  secret-key: 你的SecretKey  # 直接填写，但不要提交到Git
```

然后重启应用。

---

### 方式3：启动时指定参数

```bash
java -jar target/models-integration-0.0.1.jar \
  --tencent-asr.secret-key=你的SecretKey
```

---

## ✅ 验证配置

重启应用后，访问配置检查接口验证：

```bash
curl http://localhost:5081/api/tencent/asr/config-check
```

**成功响应示例**：
```json
{
  "code": 200,
  "message": "success",
  "data": "✅ 配置已正确加载（API密钥验证通过）"
}
```

**失败响应示例**：
```json
{
  "code": 500,
  "message": "fail",
  "data": "❌ 配置错误：SecretKey 未配置。\n\n解决方案：\n1. 设置环境变量：export TENCENT_SECRET_KEY=你的密钥\n2. 或在 application.yml 中配置 tencent-asr.secret-key"
}
```

---

## 🧪 测试接口

### 1. 配置检查（新增）
```bash
curl http://localhost:5081/api/tencent/asr/config-check
```

### 2. 健康检查
```bash
curl http://localhost:5081/api/tencent/asr/health
```

### 3. 一句话识别测试
```bash
curl -X POST http://localhost:5081/api/tencent/asr/sentence-recognition \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://jxz.uj345.cc/static/images/xhs-wechat.mp3",
    "engineModelType": "16k_zh"
  }'
```

---

## 🔐 安全提醒

### ❌ 不要做：
- ❌ 将 SecretKey 提交到 Git 仓库
- ❌ 在代码中硬编码密钥
- ❌ 在公共场合分享密钥
- ❌ 在日志中输出完整密钥

### ✅ 应该做：
- ✅ 使用环境变量管理密钥
- ✅ 使用密钥管理服务（如 Vault）
- ✅ 定期轮换密钥
- ✅ 为不同环境使用不同的密钥

---

## 📋 当前配置状态

### application.yml 中的配置：
```yaml
tencent-asr:
  secret-id: AKIDf9OM3TdWBZqqZ1C7k6B0Ypqb6KIzQaT5  # ✅ 已配置
  secret-key: ${TENCENT_SECRET_KEY:}              # ❌ 需要配置
  region: ap-shanghai                             # ✅ 已配置
  default-engine-model: 16k_zh                    # ✅ 已配置
```

**问题**：`secret-key: ${TENCENT_SECRET_KEY:}` 表示从环境变量读取，如果环境变量不存在，值为空。

---

## 🚀 快速开始（完整流程）

### 1. 获取密钥
访问：https://console.cloud.tencent.com/cam/capi

### 2. 设置环境变量
```bash
export TENCENT_SECRET_KEY="你的40位SecretKey"
```

### 3. 重启应用
```bash
./stop.sh && ./start.sh
```

### 4. 验证配置
```bash
curl http://localhost:5081/api/tencent/asr/config-check
```

### 5. 测试识别
```bash
curl -X POST http://localhost:5081/api/tencent/asr/sentence-recognition \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://jxz.uj345.cc/static/images/xhs-wechat.mp3",
    "engineModelType": "16k_zh",
    "convertNumMode": true
  }'
```

---

## 💡 常见问题

### Q1: 如何知道密钥是否配置成功？
A: 访问 `/api/tencent/asr/config-check` 接口，会明确告诉您配置状态。

### Q2: 重启应用后环境变量丢失怎么办？
A: 将 `export TENCENT_SECRET_KEY="..."` 添加到 `~/.bashrc` 或 `~/.zshrc` 文件中，或使用启动脚本。

### Q3: 可以把密钥写到配置文件吗？
A: 可以，但不推荐。如果必须这样做，请确保：
- 将 `application.yml` 添加到 `.gitignore`
- 使用 `application-prod.yml` 区分环境
- 只在测试环境使用

### Q4: 如何在启动脚本中设置环境变量？
A: 修改 `start.sh` 文件：
```bash
#!/bin/bash
export TENCENT_SECRET_KEY="你的密钥"
nohup java -jar target/models-integration-0.0.1.jar > logs/api-demo.log 2>&1 &
echo $! > app.pid
```

---

## 📞 需要帮助？

如果按照以上步骤操作后仍有问题，请检查：

1. ✅ SecretId 和 SecretKey 是否匹配（同一对密钥）
2. ✅ 环境变量是否在应用启动前设置
3. ✅ 应用是否已重启
4. ✅ 密钥是否有语音识别服务的权限
5. ✅ 腾讯云账号是否已开通语音识别服务

访问配置检查接口可获得详细的错误信息：
```bash
curl http://localhost:5081/api/tencent/asr/config-check
```