# STT 国际版问题诊断报告

## 问题现象

使用国际版配置（`USE_DASHSCOPE_INTL=true`）时：
- ✅ LLM 正常工作
- ✅ TTS 正常工作  
- ❌ STT 无识别结果（超时后使用默认文本）

日志显示：
```
[request_id] ⚠️  STT未识别到文本，使用默认
识别文本长度: 0字
```

## 根本原因

**API Key 不匹配**

国内版（北京地域）和国际版（新加坡地域）的 API Key 是在**不同地域申请**的，互不通用。

当设置 `USE_DASHSCOPE_INTL=true` 时：
- ✅ URL 切换到 `dashscope-intl.aliyuncs.com`（正确）
- ❌ 但仍使用国内版的 API Key（错误）

导致：
- STT WebSocket 连接建立成功
- 但 API 认证失败，无法返回识别结果
- LLM/TTS 使用国内 key 仍能工作的原因可能是容错机制或缓存

## 解决方案

### 方案1：使用单个 key（简单，需手动切换）

在 `.env` 中根据地域设置对应的 key：

```bash
# 使用国内版
DASHSCOPE_API_KEY=sk-beijing-xxx
USE_DASHSCOPE_INTL=false

# 切换到国际版时，需要手动改 key
DASHSCOPE_API_KEY=sk-singapore-xxx
USE_DASHSCOPE_INTL=true
```

### 方案2：分别配置两个 key（推荐，自动切换）

**已实现**，在 `.env` 中同时配置：

```bash
# 国内版 key（北京地域申请）
DASHSCOPE_API_KEY=sk-beijing-xxx

# 国际版 key（新加坡地域申请）
DASHSCOPE_API_KEY_INTL=sk-singapore-xxx

# 切换地域（自动使用对应的 key）
USE_DASHSCOPE_INTL=false  # 或 true
```

系统会自动使用：
- `USE_DASHSCOPE_INTL=false` → 使用 `DASHSCOPE_API_KEY`
- `USE_DASHSCOPE_INTL=true` → 使用 `DASHSCOPE_API_KEY_INTL`（如果配置了）

## 代码修改

### 1. config.py
添加 `active_dashscope_api_key` 属性：
```python
@property
def active_dashscope_api_key(self) -> str:
    """获取当前激活的API Key（根据国际版/国内版自动选择）"""
    if self.use_dashscope_intl and self.dashscope_api_key_intl:
        return self.dashscope_api_key_intl
    return self.dashscope_api_key
```

### 2. websocket_handler.py
STT 使用动态 key：
```python
dashscope.api_key = settings.active_dashscope_api_key
```

### 3. ai_service.py
LLM/TTS 使用动态 key：
```python
dashscope.api_key = settings.active_dashscope_api_key
```

## 验证方法

### test_stt_xjp.py 成功的原因

该测试脚本成功的关键：
```python
# 明确使用国际版 key
dashscope.api_key = "sk-28defb4cde1c440c9f26191b0c781aaf"

# 明确使用国际版 URL
url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime'
```

**Key 和 URL 匹配**，所以成功。

### 修复后测试步骤

1. 在 `.env` 中配置：
```bash
DASHSCOPE_API_KEY=sk-国内版key
DASHSCOPE_API_KEY_INTL=sk-28defb4cde1c440c9f26191b0c781aaf
USE_DASHSCOPE_INTL=true
```

2. 重启后端：
```bash
python main.py
```

3. 观察日志：
```
🔧 预解析DNS (dashscope-intl.aliyuncs.com)...
[request_id] 🔗 STT连接已打开
[request_id] 💬 STT识别(⏳中间): xxx  # 应该有识别结果
[request_id] ✓ STT识别完成: "xxx" (长度: xx字)
```

## 关键点总结

1. **API Key 地域绑定**：北京 key ≠ 新加坡 key
2. **URL 和 Key 必须匹配**：
   - `dashscope.aliyuncs.com` + 北京 key ✅
   - `dashscope-intl.aliyuncs.com` + 新加坡 key ✅
   - `dashscope-intl.aliyuncs.com` + 北京 key ❌
3. **LLM/TTS 可能有容错**：所以单独 STT 失败更明显
4. **解决方案**：使用 `active_dashscope_api_key` 自动选择正确的 key