semvec/pypi-packages huggingface dataset:
qwen-proxy 0.1.0
Qwen-MT API Key 智能轮换客户端
Requires Python: >=3.14
Keywords: api, dashscope, key-rotation, qwen, translation

# Qwen-Proxy

Qwen-MT 多 Key 智能轮换客户端。基于 OpenAI SDK 封装，支持多 API Key 自动轮换、429 限流冷却、401 自动禁用，业务代码只需将 `OpenAI(...)` 替换为 `QwenMTClient(...)` 即可。

## 特性

- **多 Key 轮换** — Round-Robin 策略，自动在多个 DASHSCOPE API Key 之间轮换
- **智能容错** — 429 限流自动冷却（可配置），401 鉴权失败自动禁用
- **OpenAI 兼容** — 调用方式与 OpenAI SDK 完全一致，支持流式/非流式
- **Key 自动发现** — 支持文件、环境变量、手动传入三种方式
- **线程安全** — KeyManager 全局互斥锁保护
- **结构化日志** — 自动按级别输出到 `logs/` 目录

## 快速开始

### 环境要求

- Python >= 3.14
- [uv](https://docs.astral.sh/uv/) 包管理器

### 安装依赖

```bash
uv sync
```

### 配置 API Key

复制示例文件并填写你的 DASHSCOPE API Key（一行一个，`#` 开头的行会被忽略）：

```bash
cp .keys.example .keys
```

也可以使用环境变量（逗号分隔多个 Key）：

```bash
export DASHSCOPE_API_KEYS="sk-aaa,sk-bbb,sk-ccc"
```

### 运行示例

```bash
uv run python main.py
```

### 测试所有 Key 可用性

```bash
uv run python test_all_keys.py
```

## 使用方式

```python
from qwen_proxy import QwenMTClient

client = QwenMTClient()

# 基础翻译
result = client.chat.completions.create(
    model="qwen-mt-plus",
    messages=[{"role": "user", "content": "你好世界"}],
    extra_body={
        "translation_options": {
            "source_lang": "Chinese",
            "target_lang": "English",
        }
    },
)
print(result.choices[0].message.content)

# 带术语干预
result = client.chat.completions.create(
    model="qwen-mt-plus",
    messages=[{"role": "user", "content": "这套生物传感器运用了石墨烯"}],
    extra_body={
        "translation_options": {
            "source_lang": "Chinese",
            "target_lang": "English",
            "terms": [
                {"source": "生物传感器", "target": "biological sensor"},
            ],
        }
    },
)

# 查看 Key 使用统计
for stat in client.key_manager.get_stats():
    print(f"{stat['key']}: {stat['status']} | 请求: {stat['requests']}")
```

## 项目结构

```
qwen-proxy/
├── qwen_proxy/              # 核心包
│   ├── __init__.py
│   ├── client.py             # QwenMTClient 主客户端
│   ├── key_manager.py        # 多 Key 轮换管理器
│   └── logging_config.py     # 日志配置
├── docs/                     # API 参考文档
├── main.py                   # 使用示例
├── test_all_keys.py          # Key 全覆盖测试
├── .keys.example             # Key 文件模板
├── pyproject.toml
└── uv.lock
```

## 配置项

`QwenMTClient` 支持以下参数：

| 参数 | 默认值 | 说明 |
|---|---|---|
| `api_keys` | `None` | 直接传入 Key 列表 |
| `keys_file` | `None` | Key 文件路径 |
| `base_url` | DashScope 地址 | API 基础 URL |
| `cooldown_seconds` | `60.0` | 限流冷却时间（秒） |
| `max_retries` | `3` | 最大重试次数 |

## License

MIT