GPT-6 Luna 批量处理实战指南

在处理海量文本数据时，最让人头疼的往往不是算法本身的复杂度，而是如何高效地调动 API 资源。很多开发者习惯了单条请求的同步模式，当面对成千上万条需要翻译、摘要或分析的数据时，逐个发送请求不仅耗时极长，还容易因为网络波动导致整个脚本中断。更糟糕的是，这种"笨办法"根本无法充分利用服务端提供的并发能力，导致任务排队时间过长，项目进度严重受阻。

其实，主流的大模型服务平台都提供了专门的批量处理接口（Batch API），这正是为了解决上述痛点而设计的。它允许我们将成百上千个任务打包成一个文件上传，服务端会在后台异步处理，完成后通知我们去下载结果。这种方式不仅能显著降低单次调用的成本，还能通过自动重试机制提高任务的稳定性。对于需要定期跑数据报表、清洗大规模语料库或者进行离线推理的团队来说，掌握这套流程是提升工程效率的关键一步。

本文将基于实际开发经验，带你从零开始构建一个完整的批量处理工作流。我们会从环境搭建讲起，深入探讨任务文件的格式规范，手把手编写提交与轮询代码，并重点解决超时重试、速率限制以及成本监控等生产环境中必然遇到的棘手问题。无论你是第一次接触批量接口，还是想优化现有的数据处理管道，接下来的内容都能提供可落地的参考方案。

① 环境配置与 API 密钥快速部署

工欲善其事，必先利其器。在开始编写代码之前，我们需要确保本地开发环境已经就绪。首先，你需要拥有一个有效的大模型服务平台账号，并在控制台的"API Keys"页面生成一个新的密钥。这个密钥是你所有请求的身份凭证，务必妥善保管，切勿直接硬编码在代码仓库中。

推荐的做法是使用环境变量来管理密钥。在你的终端中执行以下命令（以 Linux/macOS 为例）：

export OPENAI_API_KEY="sk-你的密钥字符串"

如果是 Windows 用户，可以在 PowerShell 中使用 $env:OPENAI_API_KEY="sk-你的密钥字符串"，或者在项目根目录创建 .env 文件，利用 python-dotenv 库在代码中加载。

接下来，安装官方提供的 Python 客户端库，这是最稳定且功能最全的交互方式：

pip install openai python-dotenv

安装完成后，我们可以写一个简单的脚本验证连接是否成功。这段代码会尝试获取账户信息或列出可用的模型，如果没有任何报错，说明环境配置无误：

import os
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()  # 加载 .env 文件中的变量

client = OpenAI(
    api_key=os.getenv("OPENAI_API_KEY")
)

try:
    # 简单测试连接，列出可用模型
    models = client.models.list()
    print(f"连接成功！当前可用模型数量：{len(models.data)}")
except Exception as e:
    print(f"连接失败，请检查密钥配置：{e}")

② 批量任务数据结构与格式规范

批量接口的核心在于输入数据的组织形式。与实时聊天接口不同，批量任务不接受直接的 JSON 对象列表，而是要求上传一个特定的 JSONL（JSON Lines）文件。在这种格式中，文件的每一行都是一个独立的、合法的 JSON 对象，行与行之间没有逗号分隔。

每个 JSON 对象必须包含三个关键字段：

• custom_id：由你自定义的唯一标识符。当任务完成后，你需要通过这个 ID 将结果与原始数据对应起来。建议使用业务系统中的主键或生成的 UUID。
• method：固定为 "POST"，表示这是一个 HTTP POST 请求。
• url：指定调用的具体 API 端点，通常是 /v1/chat/completions。
• body：包含实际发送给模型的参数，结构与普通的聊天请求完全一致，包括 model、messages 等。

下面是一个标准的 JSONL 文件示例片段：

{"custom_id": "task-001", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "请将这句话翻译成英文：你好世界"}]}}
{"custom_id": "task-002", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "提取以下文本中的实体：苹果公司发布了新手机"}]}}
{"custom_id": "task-003", "method": "POST", "url": "/v1/chat/completions", "body": {"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "总结这篇新闻的核心观点..."}]}}

注意，文件中不能有多余的空行或注释，每一行都必须能被独立解析。如果你的数据存储在 CSV 或数据库中，需要先编写一个转换脚本，将其清洗并序列化为这种格式。

③ 构建首个批量请求代码实例

准备好 JSONL 文件后，我们就可以通过代码将其上传并创建批量任务了。这一步非常直观，主要调用 batches.create 方法。我们需要指定上传的文件路径、期望的处理端点以及完成后的回调地址（可选）。

以下是完整的上传代码示例：

import os
from openai import OpenAI

client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))

# 假设我们已经生成了 input.jsonl 文件
input_file_path = "input.jsonl"

# 1. 上传文件
with open(input_file_path, "rb") as file:
    uploaded_file = client.files.create(
        file=file,
        purpose="batch"
    )
    print(f"文件上传成功，ID: {uploaded_file.id}")

# 2. 创建批量任务
batch_job = client.batches.create(
    input_file_id=uploaded_file.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",  # 设置任务完成的窗口期，最长 24 小时
    metadata={"description": "首批文本处理任务"}
)

print(f"批量任务已创建，ID: {batch_job.id}")
print(f"当前状态：{batch_job.status}")

这里有两个细节值得注意：purpose 参数必须设为 "batch"，否则服务端会拒绝该文件；completion_window 定义了任务必须在多长时间内完成，通常设置为"24h"即可，这给了服务端足够的调度弹性。

④ 提交任务与异步状态轮询机制

任务提交后，并不会立即返回结果，而是进入异步处理队列。此时，任务的状态可能是 validating（验证中）、in_progress（进行中）或 completed（已完成）。我们需要编写一个轮询机制来定期检查任务状态，直到它结束。

虽然可以使用 Webhook 接收完成通知，但在简单的脚本场景中，主动轮询更加可控。我们可以使用 time.sleep 配合循环来实现：

import time

def poll_batch_status(batch_id):
    while True:
        batch_status = client.batches.retrieve(batch_id)
        status = batch_status.status
        
        print(f"当前任务状态：{status}")
        
        if status == "completed":
            print("任务处理完毕！")
            return batch_status
        elif status in ["failed", "expired", "cancelled"]:
            print(f"任务异常终止：{status}")
            return None
        
        # 每隔 10 秒检查一次，避免过于频繁的请求
        time.sleep(10)

# 使用示例
final_status = poll_batch_status(batch_job.id)
if final_status and final_status.output_file_id:
    print(f"结果文件 ID: {final_status.output_file_id}")
else:
    print("未找到输出文件，请检查错误日志")

在这个循环中，我们不仅要关注 completed 状态，还要警惕 failed 或 expired 等异常状态。一旦检测到异常，应立即停止轮询并记录日志，以便排查原因。

⑤ 结果下载与本地数据解析流程

当任务状态变为 completed 后，响应对象中会包含 output_file_id。我们需要再次调用文件下载接口，获取包含所有结果的 JSONL 文件。这个文件的结构与输入文件类似，但每一行增加了一个 response 字段，里面包含了模型的实际返回内容。

下载并解析结果的代码如下：

import json

# 下载结果文件
result_file_content = client.files.content(file_id=final_status.output_file_id)
result_lines = result_file_content.text.splitlines()

processed_data = {}

for line in result_lines:
    data = json.loads(line)
    custom_id = data['custom_id']
    
    # 检查是否有错误
    if 'error' in data:
        print(f"任务 {custom_id} 处理出错：{data['error']}")
        continue
    
    # 提取模型回复
    response_body = data['response']['body']
    content = response_body['choices'][0]['message']['content']
    
    # 将结果存入字典，方便后续使用
    processed_data[custom_id] = content

print(f"成功解析 {len(processed_data)} 条结果")
# 示例：打印第一条结果
first_key = list(processed_data.keys())[0]
print(f"ID {first_key} 的结果：{processed_data[first_key][:50]}...")

解析过程中，务必处理可能存在的单条任务失败情况。即使整个批量任务显示为 completed，其中的个别请求仍可能因为内容违规或超时而失败，这些错误信息会保留在对应的行中。

⑥ 常见超时错误与重试策略优化

在大规模数据处理中，网络波动或服务端临时过载是不可避免的。虽然批量接口本身具有较好的容错性，但我们仍需考虑极端情况下的重试策略。

如果在上传文件或轮询状态时遇到 ConnectionError 或 Timeout 异常，不要立即放弃。建议引入指数退避（Exponential Backoff）机制：第一次失败等待 1 秒，第二次等待 2 秒，第三次等待 4 秒，以此类推，并设置最大重试次数（如 5 次）。

此外，如果某个具体的 custom_id 在结果中标记为错误，可以将这些失败的任务单独提取出来，生成一个新的 JSONL 文件，重新发起一个小规模的批量任务进行补救。这种"分而治之"的策略能确保最终数据的完整性，避免因少量错误导致整体返工。

⑦ 大规模并发下的速率限制应对

虽然批量接口将并发控制权交给了服务端，但我们自身的操作（如上传、下载、轮询）仍然受到 API 速率限制（Rate Limit）的约束。如果在短时间内发起过多的管理请求，可能会触发 429 Too Many Requests 错误。

应对策略主要有两点：

1. 控制轮询频率：如前所述，轮询间隔不宜过短，10-30 秒通常是合理的区间。对于非紧急任务，甚至可以延长到 1 分钟。
2. 监听响应头 ：客户端库通常会自动处理部分限流重试，但手动捕获异常并读取 Retry-After 头部信息是最稳妥的做法。根据提示的时间进行休眠，可以有效避免被封禁。

切记，批量处理的优势在于"吞吐量"而非"低延迟"，因此耐心等待是最佳策略，无需为了追求速度而高频请求。

⑧ 成本估算与 Token 消耗监控技巧

使用批量接口的一大动力是成本优势。通常，批量处理的输入和输出 Token 价格会有所折扣。为了精确控制预算，我们需要在任务完成后分析消耗情况。

在批量任务的详情对象中，通常包含 request_counts 字段，记录了总请求数、成功数和失败数。更详细的 Token 消耗数据则存在于结果文件的每一行中。解析结果时，可以顺便累加 usage 字段中的 prompt_tokens 和 completion_tokens。

total_prompt_tokens = 0
total_completion_tokens = 0

for line in result_lines:
    data = json.loads(line)
    if 'response' in data:
        usage = data['response']['body'].get('usage', {})
        total_prompt_tokens += usage.get('prompt_tokens', 0)
        total_completion_tokens += usage.get('completion_tokens', 0)

print(f"总消耗 Prompt Tokens: {total_prompt_tokens}")
print(f"总消耗 Completion Tokens: {total_completion_tokens}")

通过这种方式，你可以清晰地知道每个项目的具体开销，从而优化提示词长度或调整模型版本，实现成本效益最大化。

⑨ 复杂场景下的分片处理方案

当待处理的数据量达到百万级时，单个 JSONL 文件可能会变得过大，导致上传超时或内存溢出。此时，分片处理（Sharding）是必要的架构选择。

你可以编写一个预处理脚本，将原始大数据集切割成多个较小的文件（例如每个文件包含 1 万条记录）。然后，依次上传这些文件并创建多个批量任务。为了管理这些分散的任务，建议在本地维护一个状态表，记录每个分片的任务 ID、文件名和处理状态。

这种方案不仅降低了单次操作的风险，还允许并行处理多个分片，进一步缩短整体完工时间。即使某个分片失败，也只需重传该部分，不影响其他任务的进度。

⑩ 自动化工作流集成最佳实践

最后，将上述步骤整合进自动化工作流是提升生产效率的终极目标。你可以利用 Cron 定时任务、Airflow 或 GitHub Actions 等工具，定期触发数据处理脚本。

一个典型的自动化流程是：

1. 从数据库或对象存储中拉取新增数据。
2. 动态生成 JSONL 文件。
3. 调用批量接口提交任务。
4. 后台守护进程持续轮询状态。
5. 任务完成后自动下载结果，解析并写回数据库。
6. 发送通知（邮件或即时消息）报告处理结果。

在这个过程中，日志记录至关重要。每一步操作都应写入日志文件，包括任务 ID、开始时间、结束时间及任何异常堆栈。这不仅有助于故障排查，也为后续的性能优化提供了数据支撑。通过这样一套闭环系统，你可以真正实现"无人值守"的大规模数据智能处理。