智谱AI-1.BatchApi详细介绍（Python-SDK版）

2024年5月17日，智谱ai推出了Batch API，下面我们一起来学习其基本概念和入门使用。

1.1 什么是Batch API

Batch API是专为处理大量数据而设计的。它允许开发者在不需要实时结果的情况下，提交批量任务进行处理。适用的场景如下：

• 文章分类： 在负载较轻的非高峰时段，对大量的文章、帖子或产品描述执行分类标签工作。
• 情感分析： 对顾客反馈、社交媒体发文或商品评价实施大范围的情感倾向分析。
• 文档处理： 为批量文档提供生成摘要、提炼关键信息或执行翻译的全面处理服务。
• 信息提取： 对众多的支持票据、报告等进行高效的内容识别和信息抽取工作（利用GLM-4V模型）。

Batch API的优点：
（1）对于大模型提供方来说，可以利用闲时算力处理Batch请求，降低成本
（2）对于大模型使用方来说，Batchq请求价格更低，并且不需要使用方机器同步等待返回结果或不断轮训查询异步调用结果，降低使用方成本。

1.2 如何使用Batch API

使用Batch API一共需要3步：

• 上传Batch文件
• 创建Batch
• 等待Batch处理完成

1.2.1 上传Batch文件

用于Batch请求的文件格式需要满足以下要求：
（1）文件格式必须为.jsonl格式，必须严格遵循JSON Lines格式，其中每行包含一个完整的JSON对象，代表一个API请求。
（2）必需字段

必填字段	字段说明
custom_id	必须全局唯一，用于识别和跟踪每个请求的状态，方便用户拿到请求结果后与请求match
method	请求方式，目前只支持POST
url	定义调用的API端点，目前只支持/v4/chat/completions
body	请求体数据，是一个json，其中包括model、messages等信息

{"custom_id": "request-1", "method": "POST", "url": "/v4/chat/completions", "body": {"model": "glm-4", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}
{"custom_id": "request-2", "method": "POST", "url": "/v4/chat/completions", "body": {"model": "glm-4", "messages": [{"role": "system", "content": "You are an helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}

通过智谱提供的Python SDK提交自己准备的Batch文件（通过pip install zhipuai下载sdk即可），通过上传 Batch 文件后得到文件 ID。

from zhipuai import ZhipuAI

client = ZhipuAI(api_key="") # 请填写您自己的APIKey
  
result = client.files.create(
    file=open("product_reviews.jsonl", "rb"), /
    purpose="batch"
)
print(result.id)
  

1.2.2 创建Batch

用上传的到的文件id来创建Batch，智谱AI后台即可根据其调度算法在适当的时间处理我们的Batch请求。

from zhipuai import ZhipuAI
    client = ZhipuAI(api_key="") # 填写您自己的APIKey
  
    create = client.batches.create(
        input_file_id="file_123", ##上一步返回的文件id
        endpoint="/v4/chat/completions",
        completion_window="24h",
        metadata={
            "description": "sentiment classification"
        }
    )
    print(create)

参数说明：

参数	含义
input_file_id	文件id
endpoint	请求端点。目前支持 /v4/chat/completions
completion_window	指定 Batch 任务在多长时间内完成。目前只支持设定为 “24h”。
metadata	个人元数据，按原样输出

1.2.3 等待Batch执行完成

Batch任务状态机如下：

状态说明：

状态	状态含义
Validating	上传文件，后台正在校验文件是否正确
in_progress	文件检验成果，开始处理batch中的请求
finalizing	Batch请求处理完成，开始将请求和响应数据写入文件
completed	Batch请求响应数据归档完成，用户可以下载最终文件
cancelling	用户主动取消Batch任务，任务开始取消
cancelled	Batch任务取消完成，用户可以下载最终文件
expired	Batch任务24小时未完成，文件过期，用户可以下载最终文件

实时查询Batch处理结果：

from zhipuai import ZhipuAI
    client = ZhipuAI(api_key="") # 填写您自己的APIKey
    
    retrieve = client.batches.retrieve("batch_123")
    print(retrieve)

Batch处理结果说明：

字段名	类型	描述
id	string	批处理的唯一标识符。
object	string	对象类型，这里为 “batch”。
endpoint	string	批处理使用的 API 端点。
input_file_id	string	批处理使用的输入文件的ID。
completion_window	string	批处理应在此时间框架内完成的期限。
status	string	批处理的当前状态。
output_file_id	string	包含成功执行请求的输出的文件ID。
error_file_id	string	包含出现错误的请求的输出的文件ID。
created_at	integer	创建批处理的Unix时间戳（秒）。
in_progress_at	integer	批处理开始处理的Unix时间戳（秒）。
expires_at	integer	批处理将过期的Unix时间戳（秒）。
finalizing_at	integer	批处理开始最终处理的Unix时间戳（秒）。
completed_at	integer	批处理完成的Unix时间戳（秒）。
failed_at	integer	批处理失败的Unix时间戳（秒）。
expired_at	integer	批处理过期的Unix时间戳（秒）。
cancelling_at	integer	批处理开始取消的Unix时间戳（秒）。
cancelled_at	integer	批处理取消完成的Unix时间戳（秒）。
request_counts	integer	batch 请求计数。
├── total	integer	批处理中的请求总数。
├── completed	integer	批处理中已成功完成的请求数量。
└── failed	integer	批处理中失败的请求数量。
metadata	map	可附加到对象上的 16 个键值对的集合。这有助于以结构化格式存储对象的附加信息。键的长度最多为 64 个字符，值的长度最多为 512 个字符。

下载处理结果：
通过查询Batch处理结果中的output_file_id（正确处理文件id）、output_file_id（请求错误文件id）进行下载，

from zhipuai import ZhipuAI
 
    client = ZhipuAI()  # 填写您自己的APIKey
    # client.files.content返回 _legacy_response.HttpxBinaryResponseContent实例
    content = client.files.content("result_123") 
    
    # 使用write_to_file方法把返回结果写入文件
    content.write_to_file("write_to_file_batchoutput.jsonl")
    

处理结果文件示例如下：

{"body":{"created":1715958264,"usage":{"completion_tokens":80,"prompt_tokens":435,"total_tokens":515},"model":"glm-3-turbo","id":"8668357705649024922","choices":[{"finish_reason":"stop","index":0,"message":{"role":"assistant","content":"{\"user问题\": \"我购买的商品一直没有收到\",\n\"客服方案\": \"确认订单号后查询物流信息，告知包裹正在途中，预计明天到达\",\n\"是否接受\": \"是\",\n\"是否负面情绪\": \"否\",\n\"是否有公关风险\": \"否\",\n\"问题风险等级和原因\": \"1,用户无不满情绪\"}\"}"}}],"request_id":"1-request-0"},"status_code":200}

github：https://github.com/haiyang679/zhipu_ai_python_example
以上内容，均来源智谱官网
[1]:https://open.bigmodel.cn/dev/api#batch