智谱AI-1.BatchApi Python SDK版详细介绍
2024年5月17日,智谱ai推出了Batch API,下面我们一起来学习其基本概念和入门使用。
1.1 什么是Batch API
Batch API是专为处理大量数据而设计的。它允许开发者在不需要实时结果的情况下,提交批量任务进行处理。适用的场景如下:
Batch API的优点:
(1)对于大模型提供方来说,可以利用闲时算力处理Batch请求,降低成本
(2)对于大模型使用方来说,Batchq请求价格更低,并且不需要使用方机器同步等待返回结果或不断轮训查询异步调用结果,降低使用方成本。
1.2 如何使用Batch API
使用Batch API一共需要3步:
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
作者:do__something