# Qwen 模型路由逻辑说明

## 📋 决策流程

Qwen 模型的路由遵循以下优先级（从高到低）：

```
1. 功能开关检查 (QWEN_ENABLED)
   ↓ (enabled)
2. 是否为阿里云集群？
   ↓ (不是)
3. 是否为特定 cluster_id？
   ↓ (不是)
4. 保持原模型
```

---

## 🎛️ 1. 功能开关 (最高优先级)

**环境变量**: `QWEN_ENABLED`

**默认值**: `false` (禁用) - **更安全的默认行为**

**可选值**:
- 启用: `true`, `1`, `yes`
- 禁用: `false`, `0`, `no`, 或未配置

**行为**:
- **未配置或 `QWEN_ENABLED=false`** 时，**完全禁用** Qwen 路由，所有请求保持原模型
- 需要**显式设置 `QWEN_ENABLED=true`** 才启用千问路由
- 用于紧急回滚或下线 Qwen 模型

**示例**:
```bash
# 启用 Qwen（需要显式设置）
export QWEN_ENABLED=true

# 禁用 Qwen（默认行为，或显式禁用）
export QWEN_ENABLED=false
# 或不设置环境变量（默认禁用）
```

**日志示例（未配置或禁用）**:
```
[INFO] session_id = 488436, Qwen is disabled by QWEN_ENABLED flag, keeping original model = gpt-4
```

**日志示例（启用）**:
```
[INFO] session_id = 488436, cluster_id = 12345, cloud_provider = aws, original_model = gpt-4, qwen_enabled = True
```

---

## 🌩️ 2. 阿里云集群 (优先级 2)

**判断条件**: `cloud_provider in ["alibaba", "aliyun", "alicloud"]`

**行为**:
- 阿里云集群 **100% 走 Qwen**
- 自动检测云平台信息

**日志示例**:
```
[INFO] session_id = 488436, detected Alibaba Cloud, switching to Qwen model,
       cluster_id = 12345, cloud_provider = alibaba, original_model = gpt-4, new_model = qwen-turbo
```

---

## 🎯 3. 特定集群白名单 (优先级 3)

**配置位置**: `svc/eda_task.py:78`

**当前白名单**:
```python
qwen_cluster_ids = ["10072363520111170484"]
```

**行为**:
- 白名单中的集群 **100% 走 Qwen**
- 支持添加多个 cluster_id

**扩展方式**:
```python
# 添加更多 cluster_id
qwen_cluster_ids = [
    "10072363520111170484",
    "另一个集群ID",
    "再一个集群ID"
]
```

**日志示例**:
```
[INFO] session_id = 488436, detected specific cluster_id, switching to Qwen model,
       cluster_id = 10072363520111170484, cloud_provider = aws, original_model = gpt-4, new_model = qwen-turbo
```

---

## 📊 流量分布总结

| 场景 | 模型选择 |
|------|----------|
| **QWEN_ENABLED=false/未配置** | 原模型 |
| **QWEN_ENABLED=true + 阿里云集群** | Qwen.DEFAULT |
| **QWEN_ENABLED=true + 特定 cluster_id** | Qwen.DEFAULT |
| **QWEN_ENABLED=true + 其他集群** | 原模型 |

**默认情况（未配置）**: **0%** Qwen 流量（功能禁用）

**显式启用后 (QWEN_ENABLED=true)**：只有阿里云集群和白名单集群自动路由到 Qwen。

---

## 🛠️ 运维操作指南

### 场景 1: 紧急回滚 Qwen

```bash
# 方法 1: 环境变量 (推荐)
export QWEN_ENABLED=false
# 重启服务
kubectl rollout restart deployment/edaservice-worker

# 方法 2: Pulumi 配置
pulumi stack select edaservice-prod
pulumi config set edaservice:qwenEnabled false
pulumi up
```

### 场景 2: 灰度测试特定集群

```python
# 编辑 svc/eda_task.py:78
qwen_cluster_ids = [
    "10072363520111170484",  # 现有测试集群
    "新集群ID"                # 添加新的测试集群
]
```

---

## 🔍 日志追踪示例

### 完整流程 (其他云厂商保持原模型)

```log
[INFO] session_id = 488436, cluster_id = 12345, cloud_provider = aws, original_model = gpt-4, qwen_enabled = True
[INFO] session_id = 488436, cluster is not eligible for Qwen routing, cluster_id = 12345, cloud_provider = aws, keeping original model = gpt-4
```

### 完整流程 (功能开关关闭)

```log
[INFO] session_id = 488436, Qwen is disabled by QWEN_ENABLED flag, keeping original model = gpt-4
[INFO] session_id = 488436, routing to Claude model, model = claude3-sonnet
```

---

## ⚠️ 注意事项

1. **默认禁用**: 未配置 `QWEN_ENABLED` 时，千问路由**默认关闭**，需要显式设置为 `true` 才启用
2. **功能开关优先级最高**: 即使是阿里云集群或白名单集群，`QWEN_ENABLED=false` 或未配置都会禁用 Qwen
3. **白名单集群**: 如果某个集群需要 100% 走 Qwen，添加到 `qwen_cluster_ids` 列表（仍需 `QWEN_ENABLED=true`）
4. **日志监控**: 所有路由决策都有完整日志，可通过 `session_id` 追踪

---

## 📈 监控指标建议

建议监控以下指标：

1. **Qwen 调用成功率**: `qwen_requests_total / qwen_requests_success`
2. **Qwen 流量占比**: `qwen_requests / total_ai_requests`
3. **特定集群路由**: 监控白名单集群的路由情况
4. **功能开关状态**: 监控 `QWEN_ENABLED` 环境变量

---

## 🔗 相关文档

- [Qwen 实现总结](./QWEN_IMPLEMENTATION_SUMMARY.md)
- [K8s 部署指南](./K8S_QWEN_DEPLOYMENT_GUIDE.md)
- [API Key 配置映射](./API_KEY_CONFIG_MAPPING.md)