名称： doubleword-batches
描述： 使用 Doubleword API (api.doubleword.ai) 创建和管理批量推理任务。适用于以下场景：(1) 以批量模式处理多个 AI 请求；(2) 提交 JSONL 批量文件进行异步推理；(3) 监控批量任务进度并获取结果；(4) 使用 OpenAI 兼容的批量端点；(5) 处理无需即时响应的大规模推理工作负载；(6) 在批量中使用工具调用或结构化输出；(7) 使用自动批处理器自动批量处理 API 调用。

Doubleword 批量推理

使用 Doubleword 批量 API 异步处理多个 AI 推理请求，实现高吞吐量和低成本。

前提条件

提交批量任务前，您需要：
1. Doubleword 账户 - 在 https://app.doubleword.ai/ 注册
2. API 密钥 - 在仪表板的 API 密钥部分创建一个
3. 账户余额 - 充值以处理请求（见下文定价）

何时使用批量处理

批量处理适用于：
- 可以同时运行的多个独立请求
- 不需要即时响应的工作负载
- 如果单独发送会超出速率限制的大规模请求
- 对成本敏感的工作负载（24 小时窗口比实时处理便宜 50-60%）
- 大规模的工具调用和结构化输出生成

可用模型与定价

定价基于每 100 万令牌（输入 / 输出）：

Qwen3-VL-30B-A3B-Instruct-FP8（中等规模）：
- 实时 SLA：$0.16 / $0.80
- 1 小时 SLA：$0.07 / $0.30（便宜 56%）
- 24 小时 SLA：$0.05 / $0.20（便宜 69%）

Qwen3-VL-235B-A22B-Instruct-FP8（旗舰版）：
- 实时 SLA：$0.60 / $1.20
- 1 小时 SLA：$0.15 / $0.55（便宜 75%）
- 24 小时 SLA：$0.10 / $0.40（便宜 83%）
- 支持最多 262K 总令牌，每个请求 16K 新令牌

成本估算：提交前，可将文件上传至 Doubleword 控制台预览费用。

快速开始

两种提交批量的方式：

通过 API：
1. 创建包含请求的 JSONL 文件
2. 上传文件获取文件 ID
3. 使用文件 ID 创建批量任务
4. 轮询状态直至完成
5. 从 output_file_id 下载结果

通过 Web 控制台：
1. 导航至 https://app.doubleword.ai/ 的 Batches 部分
2. 上传 JSONL 文件
3. 配置批量设置（模型、完成窗口）
4. 在实时仪表板中监控进度
5. 完成后下载结果

工作流程

步骤 1：创建批量请求文件

创建一个 .jsonl 文件，其中每行包含一个完整、有效的 JSON 对象，对象内部不能有换行符：

{"custom_id": "req-1", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "anthropic/claude-3-5-sonnet", "messages": [{"role": "user", "content": "What is 2+2?"}]}}
{"custom_id": "req-2", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "anthropic/claude-3-5-sonnet", "messages": [{"role": "user", "content": "What is the capital of France?"}]}}

每行必需字段：
- custom_id：唯一标识符（最多 64 个字符）- 建议使用描述性 ID，如 "user-123-question-5"，便于结果映射
- method：始终为 "POST"
- url：API 端点 - "/v1/chat/completions" 或 "/v1/embeddings"
- body：包含 model 和 messages 的标准 API 请求

可选的 body 参数：
- temperature：0-2（默认：1.0）
- max_tokens：最大响应令牌数
- top_p：核心采样参数
- stop：停止序列
- tools：工具调用的工具定义（见工具调用部分）
- response_format：结构化输出的 JSON 模式（见结构化输出部分）

文件要求：
- 最大大小：200MB
- 格式：仅限 JSONL（JSON Lines - 换行符分隔的 JSON）
- 每行必须是有效的 JSON，且内部无换行符
- 不能有重复的 custom_id 值
- 如有需要，可将大批量任务拆分为多个文件

常见问题：
- JSON 对象内部有换行符（会导致解析错误）
- 无效的 JSON 语法
- 重复的 custom_id 值

辅助脚本：
使用 scripts/create_batch_file.py 以编程方式生成 JSONL 文件：

python scripts/create_batch_file.py output.jsonl

修改脚本中的 requests 列表以生成您特定的批量请求。

步骤 2：上传文件

通过 API：

curl https://api.doubleword.ai/v1/files \
  -H "Authorization: Bearer $DOUBLEWORD_API_KEY" \
  -F purpose="batch" \
  -F file="@batch_requests.jsonl"

通过控制台：
通过 https://app.doubleword.ai/ 的 Batches 部分上传。

响应包含 id 字段 - 保存此文件 ID 用于下一步。

步骤 3：创建批量任务

通过 API：

curl https://api.doubleword.ai/v1/batches \
  -H "Authorization: Bearer $DOUBLEWORD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input_file_id": "file-abc123",
    "endpoint": "/v1/chat/completions",
    "completion_window": "24h"
  }'

通过控制台：
在 Web 界面中配置批量设置。

参数：
- input_file_id：上传步骤获取的文件 ID
- endpoint：API 端点（"/v1/chat/completions" 或 "/v1/embeddings"）
- completion_window：根据紧急程度和预算选择：
- "24h"：最佳定价，24 小时内出结果（通常更快）
- "1h"：价格溢价 50%，1 小时内出结果（通常更快）
- 实时：容量有限，成本最高（批量服务针对异步优化）

响应包含批量任务 id - 保存此 ID 用于状态轮询。

提交前，请验证：
- 您有权访问指定的模型
- 您的 API 密钥处于活动状态
- 您的账户余额充足

步骤 4：轮询状态

通过 API：

curl https://api.doubleword.ai/v1/batches/batch-xyz789 \
  -H "Authorization: Bearer $DOUBLEWORD_API_KEY"

通过控制台：
在 Batches 仪表板中实时监控进度。

状态流转：
1. validating - 检查输入文件格式
2. in_progress - 处理请求中
3. completed - 所有请求已完成

其他状态：
- failed - 批量任务失败（检查 error_file_id）
- expired - 批量任务超时
- cancelling/cancelled - 批量任务取消中/已取消

响应包含：
- output_file_id - 从此处下载结果
- error_file_id - 失败的请求（如果有）
- request_counts - 总计/已完成/失败的数量

轮询频率： 处理期间每 30-60 秒检查一次。

提前访问： 结果在批量任务完全完成前即可通过 output_file_id 获取 - 检查 X-Incomplete 标头。

步骤 5：下载结果

通过 API：

curl https://api.doubleword.ai/v1/files/file-output123/content \
  -H "Authorization: Bearer $DOUBLEWORD_API_KEY" \
  > results.jsonl

通过控制台：
直接从 Batches 仪表板下载结果。

响应标头：
- X-Incomplete: true - 批量任务仍在处理中，更多结果即将到来
- X-Last-Line: 45 - 部分下载的恢复点

输出格式（每行）：

{
  "id": "batch-req-abc",
  "custom_id": "request-1",
  "response": {
    "status_code": 200,
    "body": {
      "id": "chatcmpl-xyz",
      "choices": [{
        "message": {
          "role": "assistant",
          "content": "答案是 4。"
        }
      }]
    }
  }
}

下载错误（如果有）：

curl https://api.doubleword.ai/v1/files/file-error123/content \
  -H "Authorization: Bearer $DOUBLEWORD_API_KEY" \
  > errors.jsonl

错误格式（每行）：

{
  "id": "batch-req-def",
  "custom_id": "request-2",
  "error": {
    "code": "invalid_request",
    "message": "缺少必需参数"
  }
}

批量中的工具调用

工具调用（函数调用）使模型能够智能地选择和使用外部工具。Doubleword 保持与 OpenAI 的完全兼容性。

包含工具的批量请求示例：

{
  "custom_id": "tool-req-1",
  "method": "POST",
  "url": "/v1/chat/completions",
  "body": {
    "model": "anthropic/claude-3-5-sonnet",
    "messages": [{"role": "user", "content": "巴黎的天气怎么样？"}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定位置的当前天气",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string"}
          },
          "required": ["location"]
        }
      }
    }]
  }
}

使用场景：
- 大规模与 API 交互的智能体
- 为多个查询获取实时信息
- 通过标准化的工具定义执行操作

批量中的结构化输出

结构化输出保证模型响应符合您的 JSON 模式，消除了字段缺失或枚举值无效的问题。

包含结构化输出的批量请求示例：

{
  "custom_id": "structured-req-1",
  "method": "POST",
  "url": "/v1/chat/completions",
  "body": {
    "model": "anthropic/claude-3-5-sonnet",
    "messages": [{"role": "user", "content": "从以下文本提取关键信息：John Doe，30 岁，住在纽约市"}],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "person_info",
        "schema": {
          "type": "object",
          "properties": {
            "name": {"type": "string"},
            "age": {"type": "integer"},
            "city": {"type": "string"}
          },
          "required": ["name", "age", "city"]
        }
      }
    }
  }
}

优势：
- 保证模式合规性
- 没有缺失的必需键
- 没有臆造的枚举值
- 无缝的 OpenAI 兼容性

autobatcher：自动批处理

autobatcher 是一个 Python 客户端，可自动将单个 API 调用转换为批量请求，无需更改代码即可降低成本。

安装：

pip install autobatcher

工作原理：
1. 收集阶段：请求在时间窗口（默认：1 秒）内或达到批量大小阈值前累积
2. 批量提交：收集的请求一起提交
3. 结果轮询：系统监控已完成的响应
4. 透明响应：您的代码接收标准的 ChatCompletion 响应

关键优势：通过自动批处理显著降低成本，同时使用熟悉的 OpenAI 接口编写正常的异步代码。

文档： https://github.com/doublewordai/autobatcher

其他操作

列出所有批量任务

通过 API：

curl https://api.doubleword.ai/v1/batches?limit=10 \
  -H "Authorization: Bearer $DOUBLEWORD_API_KEY"

通过控制台：
在仪表板中查看所有批量任务。

取消批量任务

通过 API：

curl https://api.doubleword.ai/v1/batches/batch-xyz789/cancel \
  -X POST \
  -H "Authorization: Bearer $DOUBLEWORD_API_KEY"

通过控制台：
在批量任务详情视图中点击取消。

注意：
- 未处理的请求将被取消
- 已处理的结果仍可下载
- 仅对已完成的工作收费
- 无法取消已完成的批量任务

常见模式

处理结果

逐行解析 JSONL 输出：

import json

with open('results.jsonl') as f:
    for line in f:
        result = json.loads(line)
        custom_id = result['custom_id']
        content = result['response']['body']['choices'][0]['message']['content']
        print(f"{custom_id}: {content}")

处理部分结果

检查未完成的批量任务并恢复：

import requests

response = requests.get(
    'https://api.doubleword.ai/v1/files/file-output123/content',
    headers={'Authorization': f'Bearer {api_key}'}
)

if response.headers.get('X-Incomplete') == 'true':
    last_line = int(response.headers.get('X-Last-Line', 0))
    print(f"批量任务未完成。目前已处理 {last_line} 个请求。")
    # 继续轮询并在稍后重新下载

重试失败的请求

从错误文件中提取失败的请求并重新提交：

import json

failed_ids = []
with open('errors.jsonl') as f:
    for line in f:
        error = json.loads(line)
        failed_ids.append(error['custom_id'])

print(f"失败的请求：{failed_ids}")
# 仅使用失败的请求创建新的批量任务

处理工具调用

处理工具调用响应：

import json

with open('results.jsonl') as f:
    for line in f:
        result = json.loads(line)
        message = result['response']['body']['choices'][0]['message']

        if message.get('tool_calls'):
            for tool_call in message['tool_calls']:
                print(f"工具：{tool_call['function']['name']}")
                print(f"参数：{tool_call['function']['arguments']}")

最佳实践

1. 描述性的 custom_ids：在 ID 中包含上下文，便于结果映射

   • 好："user-123-question-5"，"dataset-A-row-42"
   • 差："1"，"req1"

2. 本地验证 JSONL：上传前确保每行都是有效的 JSON 且内部无换行符

3. 无重复 ID：每个 custom_id 在批量任务中必须是唯一的

4. 拆分大文件：通过拆分为多个批量任务保持在 200MB 限制以下

5. 选择合适的窗口：为节省成本使用 24h（便宜 50-83%），仅在时间敏感时使用 1h

6. 优雅地处理错误：始终检查 error_file_id 并重试失败的请求

7. 监控 request_counts：通过 completed/total 比率跟踪进度

8. 保存文件 ID：存储 batch_id、input_file_id、output_file_id 以便后续检索

9. 使用成本估算器：提交大批量任务前在控制台预览费用

10. 考虑使用 autobatcher：对于持续的工作负载，使用 autobatcher 自动批量处理单个 API 调用

参考文档

完整的 API 详情，请参阅：
- API 参考：references/api_reference.md - 完整的端点文档和模式
- 入门指南：references/getting_started.md - 详细的设置和账户管理
- 定价详情：references/pricing.md - 模型成本和 SLA 比较