Instructor 批量处理完整指南BatchProcessor 多提供商 LLM 批量结构化抽取实战【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor在 Lambda 函数里你想用 LLM 批量 API 做批量结构化抽取第一步就卡住了请求要先写成磁盘上的临时.jsonl文件而 Serverless 运行时根本没有多少磁盘可用。Instructor 的批量处理功能给你的是一套叫 BatchProcessor 的统一接口——你面向它写一次代码它按模型字符串里的 provider 前缀自动路由请求可以完全留在内存里各家的状态和结果也被归一化成同一套词汇。下面按建任务 → 提交 → 轮询 → 拆结果的顺序讲清楚整条链路。一分钟看懂批量 API 到底替你省了什么一句话版本批量处理就是把一大批结构化抽取请求邮寄给提供商异步处理官方批量价格约为实时调用的一半文档口径最高省 50%。代价是等待——任务可能跑几十分钟到几小时所以轮询和拆结果的逻辑必须可靠。BatchProcessor 做的事就是把每家批 API 长得都不一样收敛成你只写一遍。你只管BatchProcessor 替你写一个模型字符串如openai/gpt-4o-mini按/拆出 provider 前缀路由到对应实现定义一个 Pydantic 响应模型生成 JSON Schema包装成各家的请求报文轮询get_batch_status(batch_id)把各家原始状态映射到六种统一状态调get_results(batch_id)逐行解析 JSONL产出BatchSuccess/BatchError实现全部集中在 instructor/batch/processor.py是门面request.py管请求格式models.py定义结果模型providers/放各家实现。想对照源码看从这四个文件进。上手篇Serverless 里零磁盘 I/O 的内存批处理怎么写传统流程是先把请求写成.jsonl文件再上传提交。对 Lambda、Cloud Functions 这类环境磁盘配额小临时文件还带来额外的安全暴露面。Instructor 的解法只是一个参数file_pathNone。传路径时create_batch_from_messages会逐条把请求追加写进磁盘文件传None时它切到io.BytesIO内存缓冲区写完自动seek(0)归位缓冲区可以直接喂给submit_batch。最小可运行路径如下这段演示从消息到提交 ID的最短闭环from pydantic import BaseModel from instructor.batch import BatchProcessor class User(BaseModel): # 抽取的目标格式 name: str age: int processor BatchProcessor(openai/gpt-4o-mini, User) messages [ [ {role: system, content: Extract name and age from the text}, {role: user, content: Im Alice, 28 years old}, ] ] # file_pathNone不落地返回内存缓冲区 buffer processor.create_batch_from_messages( messages, file_pathNone, max_tokens200, temperature0.1 ) batch_id processor.submit_batch(buffer) # 提交拿到任务 ID三个值得记住的细节模型字符串必须含/BatchProcessor.__init__用model.split(/, 1)拆出 provider 和模型名缺了会抛出明确的ValueErrormax_tokens默认 1000、temperature默认 0.1调用时可覆盖返回值是str | io.BytesIO联合类型——str是文件路径BytesIO是内存缓冲。仓库里的 examples/batch_api/in_memory_batch_example.py 演示了含轮询和结果打印的完整流程脚本里还有一个compare_file_vs_memory()函数逐行对比文件与内存两种做法。下一步建议export OPENAI_API_KEY后直接跑它先亲眼看到缓冲区类型和字节数打印出来。进阶篇同一个接口三家提供商的报文差异同一个create_batch_from_messages对不同 provider 产出完全不同的 JSONL。这一层由BatchRequest.save_to_file按 provider 分发维度OpenAIAnthropicGoogle结构化输出靠什么response_format用 strictjson_schema代码递归给所有 object 补additionalProperties: false把 Schema 包装成名为extract_data的工具tool_choice强制调用内联提交不上传文件提交路径files.create(purposebatch)batches.createcompletion_window默认 24hbeta 端点client.beta.messages.batches测试脚本直接submit_batch(messages_list..., use_inlineTrue)Key 环境变量OPENAI_API_KEY必需ANTHROPIC_API_KEY必需GOOGLE_API_KEY可选缺失时警告并进入模拟模式原始状态词validating/in_progress/finalizingin_progress/ended—其中 Anthropic 还有一步预处理system角色消息会被抽出来合并成顶层system参数而不是留在 messages 里。一个诚实的提醒当前版本的路由工厂get_providerinstructor/batch/providers/init.py实际只实例化 OpenAI 和 Anthropic 两家且用importlib.util.find_spec做懒加载——没装openai包时会抛出 OpenAI is not installed。传google/前缀目前会收到Unsupported provider异常Google 的完整任务需要GOOGLE_CLOUD_PROJECT、GCS_BUCKET与服务账号凭据外加aiplatform.user和storage.objectUser权限。建议先拿前两家跑真实任务Google 路径作为已知规划看待。创建之后的生命周期不必手写代码CLI 全都有。这段命令演示免代码盯任务 拉结果# 实时刷新一张表看所有批任务的状态 instructor batch list --provider anthropic --live # 任务完成后把原始结果下载成文件 instructor batch results \ --batch-id batch_xxx \ --output-file results.jsonl \ --model anthropic/claude-3-5-sonnet-20241022instructor batch下还有create从消息文件生成请求文件需--messages-file、--response-model、create-from-file提交已生成的文件、cancel、delete、download-file。表格里展示的是BatchJobInfo归一化后的字段批次 ID、状态、创建/开始时间、耗时外加 provider 特有统计OpenAI 是 Completed/Failed/TotalAnthropic 是 Succeeded/Errored/Processing。看完这张表你基本不需要再开浏览器去各家控制台。实战篇像取快递一样轮询批任务、拆结果批任务就像快递提交后你拿到的是运单号batch ID不能立刻拆包得等承运方宣告已送达终态。取快递有两条规矩——别每秒刷一次单号而且包裹里可能是退回件不是商品。状态机六家词六个统一状态各家状态词不一样BatchJobInfo把它们翻译成六态状态机pending/processing/completed/failed/cancelled/expired。映射规则是OpenAI 的validating归入 pendingin_progress和finalizing都算 processingcancelling并入 cancelledAnthropic 的in_progress是 processingended是 completed。原始词保留在raw_status字段里排查时用它。轮询代码照示例脚本的写法这段演示查到终态才停的最小循环import time while True: state processor.get_batch_status(batch_id).get(status) if state completed: break if state in (failed, cancelled, expired): raise SystemExit(fBatch job failed: {state}) time.sleep(10) # 每 10 秒查一次别打爆 API results processor.get_results(batch_id) # Maybe/Result 联合类型列表拆袋Maybe/Result 结果模型get_results返回的不是裸对象列表而是BatchResult BatchSuccess[T] | BatchError的列表——这是个 Maybe/Result 模式意思是每一项可能是包裹也可能是退件单。BatchSuccess带运单号custom_id和解析好的 Pydantic 对象resultBatchError带同样的运单号外加error_type、error_message和原始数据raw_data。某条失败不会中断整个流程它只是变成一张退件单。配套四个工具函数不用手写 if/else。这段演示拆袋的完整动作from instructor.batch import extract_results, filter_errors users extract_results(results) # 只取成功的 Pydantic 对象 errors filter_errors(results) # 失败项含 error_type / error_message for user in users: print(user.name, user.age)custom_id是创建时按顺序生成的request-0、request-1……失败条目可以凭它和原始提示词对账get_results_by_custom_id还能直接建一个运单号 → 结果的索引。另外两个过滤函数filter_successful和get_results_by_custom_id也都从instructor.batch顶层导出。想加一道验收examples/batch_api/run_batch_test.py的fetch子命令默认会把抽取结果和预期的User列表逐一比对按名字排序后核对姓名与年龄全部匹配才算通过show-results则把每条结果打印到model_dump()级别并复验它确实是 Pydantic 实例。跑通一遍比读十页文档更有说服力。避坑篇高频报错速查与二次开发症状原因一步修复Error: OPENAI_API_KEY environment variable is not set没导出 Keyexport OPENAI_API_KEYyour-keyAnthropic 同理用ANTHROPIC_API_KEYModel string must be in format provider/model-name模型字符串缺/改成openai/gpt-4o-mini这种形式Unsupported provider: google当前工厂只接了 openai / anthropic先用前两家Google 真实任务还需 GCS 与权限配置OpenAI is not installed对应 SDK 未安装pip install openai或pip install anthropicAll N batch requests failed. No output file任务里每条请求都失败先用 2~3 条小批量验证提示词与 SchemaGoogle 报 Missing GCS_BUCKET真实任务缺 GCS 配置设置GCS_BUCKET、GOOGLE_CLOUD_PROJECT、GOOGLE_APPLICATION_CREDENTIALS几条经验值OpenAI 批量与常规 API 的速率限制相互独立批量任务通常几小时内完成、24 小时保底Anthropic 多数批次一小时内跑完Google 真实任务有 24 小时执行上限且 GCS 桶要与任务同区域。要二次开发扩展点很明确换测试数据——示例脚本的create_test_messages()与get_expected_results()一一对应改响应模型——Schema 由 Pydantic 的model_json_schema()即时生成改字段即生效接新 provider——实现BatchProvider抽象基类的七个方法submit_batch/get_status/retrieve_results/download_results/cancel_batch/delete_batch/list_batches在get_provider注册再给request.py的BatchRequest补一个to_xxx_format。下一步一句话收尾面向 BatchProcessor 写一次代码provider 差异只是袋子里不同形状的报文轮询和拆结果的骨架三家通用。现在就能做的三件事cd examples/batch_apiexport OPENAI_API_KEY后运行python in_memory_batch_example.py亲眼看到内存缓冲区的创建、提交与结果打印任务在跑的时候另开一个终端用instructor batch list --live看着状态从 pending 走到 completed想啃源码就从 instructor/batch/processor.py 开始完整设计看 docs/concepts/batch.mdCLI 命令族看 docs/cli/batch.md。【免费下载链接】instructorstructured outputs for llms项目地址: https://gitcode.com/GitHub_Trending/in/instructor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考