# new-api_custom

**Repository Path**: agent-research/new-api_custom

## Basic Information

- **Project Name**: new-api_custom
- **Description**: based on https://github.com/QuantumNous/new-api
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-23
- **Last Updated**: 2025-10-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 批处理 API 客户端使用指南

## 📖 概述

批处理 API 客户端 (`batch_api_client.py`) 是一个用于调用阿里云百炼 (DashScope) 批处理 API 的 Python 工具。它支持批量处理大规模 AI 请求，相比实时 API 具有以下优势：

- ✅ **成本优惠**：批处理 API 享受 50% 折扣
- ✅ **大规模处理**：单个批次最多支持 10,000 个请求
- ✅ **异步执行**：提交后无需等待，任务在后台处理
- ✅ **自动重试**：失败请求会自动重试
- ✅ **进度跟踪**：实时显示处理进度和状态

## 🔧 前置要求

### 系统要求
- Python 3.7 或更高版本
- 网络连接（访问 New-API 服务器）

### 依赖库
- `requests`：HTTP 请求库
- `tqdm`：进度条显示（可选，但推荐安装）

## 📦 安装

### 1. 安装 Python 依赖

```bash
pip install requests tqdm
```

或使用 `requirements.txt`：

```bash
pip install -r requirements.txt
```

### 2. 验证安装

```bash
python3 batch_api_client.py --help
```

如果看到帮助信息，说明安装成功。

## ⚙️ 配置参数

### 必需参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `--input` | 输入 JSONL 文件路径 | `test_input.jsonl` |
| `--api-key` | New-API 认证密钥 | `sk-xxx` |
| `--channel_id` | 渠道 ID（必须是云百炼渠道） | `2` |
| `--model` | 模型名称 | `qwen-plus`, `qwen3-max` |

### 可选参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--output` | 输出文件路径 | `results_[model]_[timestamp].jsonl` |
| `--poll-interval` | 状态轮询间隔（秒） | `10` |
| `--debug` | 显示调试信息（API 原始响应） | `False` |
| `--cleanup` | 完成后删除输入文件 | `False` |
| `--base-url` | New-API 服务器地址 | `http://localhost:3000` |
| `--list` | 列出所有批处理任务 | - |
| `--cancel` | 取消指定的批处理任务 | - |

## 🚀 使用示例

### 1. 基本批处理工作流

```bash
python3 batch_api_client.py \
  --input test_input.jsonl \
  --api-key sk-Cp8uWdQnOHO69VsWo9gybzyp0SXC4mYpzP6RlpNP7xDXx9fs \
  --channel_id 2 \
  --model qwen-plus
```

**输出示例：**
```
============================================================
🚀 批处理 API 工作流
============================================================
🔍 验证模型 'qwen-plus' (渠道 ID: 2) 是否支持批处理 API...
✅ 模型 'qwen-plus' 支持批处理 API
   渠道: 云百炼 (ID: 2)
   端点: https://dashscope.aliyuncs.com/compatible-mode

📤 上传文件: test_input.jsonl
   文件大小: 21.08 KB
✅ 文件上传成功
   文件 ID: file-batch-xxx

📝 创建批处理任务
✅ 批处理任务创建成功
   批处理 ID: batch_xxx
   初始状态: validating

⏳ 轮询批处理状态 (间隔: 10秒)
状态: in_progress: 100%|████████| 100/100 [00:30<00:00, ok=100, fail=0, total=100]

📊 最终状态: completed

📥 下载文件: file-batch_output-xxx
✅ 文件下载成功
   保存路径: results_qwen-plus_20251023-001706.jsonl
✅ 批处理完成！结果已保存到: results_qwen-plus_20251023-001706.jsonl
============================================================
```

### 2. 使用调试模式查看 API 响应

```bash
python3 batch_api_client.py \
  --input test_input.jsonl \
  --api-key sk-xxx \
  --channel_id 2 \
  --model qwen-plus \
  --debug
```

调试模式会显示每次状态检查的完整 API 响应：

```
======================================================================
🐛 调试信息 - 轮询 #1 (2025-10-23 00:23:29)
======================================================================
状态: in_progress
request_counts: {'total': 100, 'completed': 0, 'failed': 0}
  - total: 100
  - completed: 0
  - failed: 0
  - done (comp+fail): 0
完整响应:
{
  "id": "batch_xxx",
  "status": "in_progress",
  "request_counts": {
    "total": 100,
    "completed": 0,
    "failed": 0
  },
  ...
}
======================================================================
```

### 3. 列出所有批处理任务

```bash
python3 batch_api_client.py \
  --list \
  --api-key sk-xxx \
  --channel_id 2 \
  --model qwen-plus
```

### 4. 取消批处理任务

```bash
python3 batch_api_client.py \
  --cancel batch_xxx \
  --api-key sk-xxx \
  --channel_id 2 \
  --model qwen-plus
```

### 5. 自定义输出文件名

```bash
python3 batch_api_client.py \
  --input test_input.jsonl \
  --api-key sk-xxx \
  --channel_id 2 \
  --model qwen-plus \
  --output my_results.jsonl
```

### 6. 调整轮询间隔

```bash
python3 batch_api_client.py \
  --input test_input.jsonl \
  --api-key sk-xxx \
  --channel_id 2 \
  --model qwen-plus \
  --poll-interval 5  # 每 5 秒检查一次状态
```

### 7. 处理完成后自动清理输入文件

```bash
python3 batch_api_client.py \
  --input test_input.jsonl \
  --api-key sk-xxx \
  --channel_id 2 \
  --model qwen-plus \
  --cleanup
```

## 📄 输入文件格式

输入文件必须是 **JSONL** (JSON Lines) 格式，每行一个 JSON 对象。

### 标准格式

```jsonl
{"custom_id": "request-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "qwen-plus", "messages": [{"role": "user", "content": "你好"}], "max_tokens": 100}}
{"custom_id": "request-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "qwen-plus", "messages": [{"role": "user", "content": "介绍一下人工智能"}], "max_tokens": 200}}
{"custom_id": "request-3", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "qwen-plus", "messages": [{"role": "user", "content": "写一首诗"}], "max_tokens": 150}}
```

### 字段说明

| 字段 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `custom_id` | String | 是 | 自定义请求 ID，用于匹配结果 |
| `method` | String | 是 | HTTP 方法，固定为 `"POST"` |
| `url` | String | 是 | API 端点，固定为 `"/v1/chat/completions"` |
| `body` | Object | 是 | 请求体，包含模型和消息 |
| `body.model` | String | 是 | 模型名称（如 `qwen-plus`） |
| `body.messages` | Array | 是 | 对话消息数组 |
| `body.max_tokens` | Integer | 否 | 最大生成 token 数 |

### 生成示例输入文件

```python
import json

requests = []
for i in range(1, 101):
    request = {
        "custom_id": f"request-{i}",
        "method": "POST",
        "url": "/v1/chat/completions",
        "body": {
            "model": "qwen-plus",
            "messages": [
                {"role": "user", "content": f"写一个关于数字 {i} 的句子"}
            ],
            "max_tokens": 50
        }
    }
    requests.append(request)

with open('test_input_100.jsonl', 'w') as f:
    for req in requests:
        f.write(json.dumps(req, ensure_ascii=False) + '\n')

print(f'生成了 {len(requests)} 个请求')
```

## 📤 输出文件格式

### 文件命名规则

默认输出文件名格式：`results_[model_name]_[YYYYMMDD-HHMMSS].jsonl`

**示例：**
- `results_qwen-plus_20251023-001706.jsonl`
- `results_qwen3-max_20251023-143052.jsonl`

### 输出内容格式

输出文件也是 JSONL 格式，每行包含一个请求的结果：

```jsonl
{"id": "batch_req_xxx", "custom_id": "request-1", "response": {"status_code": 200, "request_id": "xxx", "body": {"id": "chatcmpl-xxx", "object": "chat.completion", "created": 1234567890, "model": "qwen-plus", "choices": [{"index": 0, "message": {"role": "assistant", "content": "你好！有什么我可以帮助你的吗？"}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 5, "completion_tokens": 12, "total_tokens": 17}}}, "error": null}
{"id": "batch_req_yyy", "custom_id": "request-2", "response": {"status_code": 200, "request_id": "yyy", "body": {"id": "chatcmpl-yyy", "object": "chat.completion", "created": 1234567890, "model": "qwen-plus", "choices": [{"index": 0, "message": {"role": "assistant", "content": "人工智能（AI）是..."}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 8, "completion_tokens": 150, "total_tokens": 158}}}, "error": null}
```

### 解析输出文件

```python
import json

with open('results_qwen-plus_20251023-001706.jsonl', 'r') as f:
    for line in f:
        result = json.loads(line)
        custom_id = result['custom_id']
        if result['error'] is None:
            content = result['response']['body']['choices'][0]['message']['content']
            print(f"{custom_id}: {content}")
        else:
            print(f"{custom_id}: 错误 - {result['error']}")
```

## 🔍 故障排查

### 1. 模型验证失败

**错误信息：**
```
❌ 批处理工作流终止: 模型不支持批处理 API
```

**原因：**
- 模型不是通过云百炼 (DashScope) 渠道提供
- 渠道 ID 不正确

**解决方案：**
```bash
# 确保使用正确的渠道 ID（云百炼渠道）
# 检查 New-API 后台的渠道配置
python3 batch_api_client.py \
  --input test_input.jsonl \
  --api-key sk-xxx \
  --channel_id 2 \  # 确认这是云百炼渠道
  --model qwen-plus
```

### 2. 认证失败

**错误信息：**
```
unauthorized
```

**解决方案：**
- 检查 API 密钥是否正确
- 确认密钥有足够的权限
- 检查 New-API 服务器地址是否正确

### 3. 文件格式错误

**错误信息：**
```
failed to extract model from batch file
```

**解决方案：**
- 确保输入文件是有效的 JSONL 格式
- 每行必须是完整的 JSON 对象
- 检查是否有空行（脚本会自动过滤）
- 确保每个请求都包含 `body.model` 字段

### 4. 进度条不更新

**现象：**
进度条一直显示 `ok=0, fail=0`，直到任务完成才跳到 100%

**说明：**
这是**正常行为**。阿里云百炼批处理 API 不提供增量进度更新，只在任务完成时返回最终计数。

**验证方法：**
使用 `--debug` 参数查看 API 原始响应：
```bash
python3 batch_api_client.py \
  --input test_input.jsonl \
  --api-key sk-xxx \
  --channel_id 2 \
  --model qwen-plus \
  --debug
```

### 5. Ctrl+C 中断后任务状态

**问题：**
按 Ctrl+C 停止客户端脚本后，批处理任务会被取消吗？

**答案：**
**不会**。批处理任务在服务器端运行，客户端脚本只是轮询状态。

**说明：**
- ✅ Ctrl+C 只停止客户端监控
- ❌ 不会取消服务器端的批处理任务
- ✅ 任务会继续在后台处理
- ✅ 可以随时重新运行脚本查看状态

**如何真正取消任务：**
```bash
python3 batch_api_client.py \
  --cancel batch_xxx \
  --api-key sk-xxx \
  --channel_id 2 \
  --model qwen-plus
```

## 🎯 高级功能

### 1. 调试模式

调试模式显示每次 API 调用的完整响应，帮助诊断问题：

```bash
python3 batch_api_client.py \
  --input test_input.jsonl \
  --api-key sk-xxx \
  --channel_id 2 \
  --model qwen-plus \
  --debug
```

**用途：**
- 查看 API 返回的原始数据
- 验证 `request_counts` 更新情况
- 诊断认证或网络问题
- 了解批处理任务的状态变化

### 2. 进度跟踪

脚本使用 `tqdm` 库显示实时进度条：

```
状态: in_progress: 45%|████▌     | 45/100 [01:30<01:50, ok=45, fail=0, total=100, elapsed=0:01:30]
```

**进度条信息：**
- `45%`：完成百分比
- `45/100`：已完成/总数
- `[01:30<01:50]`：已用时间<预计剩余时间
- `ok=45`：成功完成的请求数
- `fail=0`：失败的请求数
- `total=100`：总请求数
- `elapsed=0:01:30`：总耗时

### 3. 自动文件清理

使用 `--cleanup` 参数在处理完成后自动删除输入文件：

```bash
python3 batch_api_client.py \
  --input test_input.jsonl \
  --api-key sk-xxx \
  --channel_id 2 \
  --model qwen-plus \
  --cleanup
```

**注意：** 只有在批处理成功完成后才会删除输入文件。

### 4. 批量任务管理

**列出所有任务：**
```bash
python3 batch_api_client.py --list --api-key sk-xxx --channel_id 2 --model qwen-plus
```

**取消特定任务：**
```bash
python3 batch_api_client.py --cancel batch_xxx --api-key sk-xxx --channel_id 2 --model qwen-plus
```

## 📊 性能和限制

### 批处理 API 限制

根据阿里云百炼文档：

| 限制项 | 值 |
|--------|-----|
| 单个文件最大大小 | 500 MB |
| 单个批次最大请求数 | 10,000 |
| 最大并发批处理任务 | 1,000 |
| 总存储空间 | 100 GB |
| 完成时间窗口 | 24 小时 |

### 成本优势

批处理 API 享受 **50% 折扣**：

| API 类型 | 价格 | 示例（qwen-plus） |
|----------|------|-------------------|
| 实时 API | 标准价格 | ¥0.004/1K tokens |
| 批处理 API | **50% 折扣** | ¥0.002/1K tokens |

**节省计算：**
- 10,000 个请求，每个 1,000 tokens
- 实时 API：¥0.004 × 10,000 = ¥40
- 批处理 API：¥0.002 × 10,000 = ¥20
- **节省：¥20 (50%)**

## 📚 相关文档

- [阿里云百炼批处理 API 文档](bailian_batch_api.md)
- [New-API 批处理实现文档](new-api/BATCH_API_IMPLEMENTATION.md)
- [New-API 批处理快速开始](new-api/BATCH_API_QUICKSTART.md)
- [New-API 批处理使用指南](new-api/BATCH_API_USAGE.md)

## 🤝 支持

如有问题或建议，请：
1. 查看故障排查部分
2. 使用 `--debug` 模式获取详细信息
3. 检查相关文档
4. 提交 Issue 或联系技术支持

---

**版本：** v1.0.0-batch-api  
**最后更新：** 2025-10-23