人工智能大模型AI 应用移动开发交互助手【免费下载链接】rikkahubRikkaHub is an Android APP that supports for multiple LLM providers.项目地址https://gitcode.com/gh_mirrors/ri/rikkahub点击查看免费下载导读本文以 .agents/skills/claude-api/php/claude-api/batches.md 为核心系统讲解如何使用官方 Anthropic PHP SDK 的 Message Batches API 批量提交 Messages API 请求创建批次、轮询状态、收集结果三个核心步骤。该 API 以标准价格 50%的费率异步处理大量非实时请求适合分类、摘要、翻译、情感分析等离线批处理场景。读完本文你将掌握 PHP 环境下完整的批次生命周期管理并理解底层POST /v1/messages/batches端点的配额、时限与结果语义。一、Message Batches API 是什么Message Batches API 对应的底层端点是POST /v1/messages/batches。它允许把大量 Messages API 请求打包成一个批次由服务端异步处理处理完成后统一取回结果。与实时messages-create()的最大区别在于不追求低延迟换取约 50% 的成本折扣。以下是该 API 的关键事实在 python 版 batches.md 与 typescript 版 batches.md 中有完整描述适用于 PHP 等所有官方 SDK维度上限 / 约定单批次请求数最多 100,000 个请求单批次体积最多 256 MB完成时间大多数批次 1 小时内完成最长不超过 24 小时结果保留创建后 29 天内可取回成本所有 token 用量享受 50% 折扣功能覆盖支持全部 Messages API 特性视觉、工具调用、Prompt Caching 等需要特别强调的是批处理结果返回顺序不固定unordered。SKILL.md 的 Common Pitfalls 一节明确警告“Batch results are unordered. Match bycustom_id, never by position in the results stream”因此每条请求必须携带唯一的customId按 ID 而不是按位置匹配结果。从当前仓库看ClaudeProvider.kt 展示了 RikkaHub 在实时对话场景中对 Claude Messages API 的实现含流式解码与工具调用而批次 API 则是同一 Messages 体系下面向离线批量场景的补充端点。可以推断任何支持 Claude 的 SDK 客户端包括 Android 端采用 Kotlin 实现的 RikkaHub 架构都遵循相同的“请求 → 轮询 → 取结果”三段式模型。二、环境准备安装 SDK 与初始化客户端安装PHP 端通过 Composer 安装官方 Anthropic SDKcomposer require anthropic-ai/sdk初始化客户端批次 API 复用的是同一个Anthropic\Client实例从环境变量读取 API Keyuse Anthropic\Client; $client new Client(apiKey: getenv(ANTHROPIC_API_KEY));关于 PHP 参数命名的注意点SKILL.md 的 API Drift 表格指出PHP 顶层具名参数采用camelCase如maxTokens而嵌套数组键按功能各不相同如cacheControl、mcp_server_name编写时应严格照抄官方示例中的确切键名不要批量转换。这一约定直接体现在下文批次代码中customId、maxTokens。三、创建批次CreatePHP 的批次创建通过$client-messages-batches-create(requests: [...])完成每个请求由两部分组成customId调用方自定义的唯一标识用于在结果流中定位该条请求params标准的 Messages API 请求参数model、maxTokens、messages等。这是 php/claude-api/batches.md 中的核心示例$batch $client-messages-batches-create(requests: [ [customId req-1, params [model claude-opus-4-8, maxTokens 1024, messages [...]]], [customId req-2, params [...]], ]);对照 python 版 的完整示例可以更直观地理解params的组成$batch $client-messages-batches-create(requests: [ [ customId request-1, params [ model claude-opus-4-8, maxTokens 16000, messages [ [role user, content Summarize climate change impacts], ], ], ], [ customId request-2, params [ model claude-opus-4-8, maxTokens 16000, messages [ [role user, content Explain quantum computing basics], ], ], ], ]); echo Batch ID: {$batch-id}\n; echo Status: {$batch-processingStatus}\n;创建成功后返回的批对象包含id批次 ID后续轮询、取结果、取消均依赖它processingStatus当前处理状态processing/ended等。模型 ID 说明SKILL.md 中的模型表显示claude-opus-4-8是默认推荐模型1M 上下文、$5/$25 每百万 token若在 Amazon Bedrock 上使用模型 ID 需加anthropic.前缀如anthropic.claude-opus-4-8而 Vertex AI 则使用无前缀的裸 ID。四、轮询批次状态Retrieve批次创建后异步执行客户端需要周期性调用retrieve查询processingStatus直到变为ended才可收集结果while (true) { $batch $client-messages-batches-retrieve($batch-id); if ($batch-processingStatus ended) { break; } echo Status: {$batch-processingStatus}, processing: {$batch-requestCounts-processing}\n; sleep(60); // 大多数批次 1 小时内完成60 秒轮询间隔是合理起点 } echo Batch complete!\n; echo Succeeded: {$batch-requestCounts-succeeded}\n; echo Errored: {$batch-requestCounts-errored}\n;requestCounts对象在轮询期间即可用来观察进度主要字段processing仍在处理中的请求数succeeded成功的请求数errored失败的请求数另有canceled、expired等见下文结果类型。轮询间隔可根据批次规模调整对等待时间敏感的作业也可以缩短到 10 秒python 版端到端示例即采用 10 秒间隔。最长时间上限为 24 小时超出仍未结束的批次会以expired状态收尾。五、收集结果Results状态变为ended后调用$client-messages-batches-results($batch-id)迭代取回每条请求的结果。结果流中每项都携带原始customId与result对象且顺序不固定必须按键匹配foreach ($client-messages-batches-results($batch-id) as $result) { switch ($result-result-type) { case succeeded: $text ; foreach ($result-result-message-content as $block) { if ($block-type text) { $text $block-text; break; } } echo [{$result-customId}] . mb_substr($text, 0, 100) . \n; break; case errored: if ($result-result-error-type invalid_request) { echo [{$result-customId}] Validation error - fix request and retry\n; } else { echo [{$result-customId}] Server error - safe to retry\n; } break; case canceled: echo [{$result-customId}] Canceled\n; break; case expired: echo [{$result-customId}] Expired - resubmit\n; break; } }结果类型共有四种type含义处理建议succeeded请求成功result-message为完整 Messages 响应提取content中的文本块errored请求失败error-type区分错误类别invalid_request需修正参数后重试其余服务端错误可安全重试canceled批次被取消时未处理的请求视情况重新提交expired超过时限未处理重新提交文本提取时注意多态内容块与 php/claude-api/README.md 中基本消息一节一致content是TextBlock、ToolUseBlock、ThinkingBlock等多态块数组直接取content[0]-text可能在首个块不是文本块时抛错因此示例中先判断$block-type text再读取。六、取消与更多管理操作取消批次对仍在处理中的批次可以发起取消$cancelled $client-messages-batches-cancel($batch-id); echo Status: {$cancelled-processingStatus}; // canceling取消后状态先变为canceling最终ended已取消批次中未完成的请求在结果流中以canceled类型呈现。列举批次需要审计历史批次时list()支持自动分页PHP 与 Python、TypeScript SDK 行为一致迭代返回值会跨页拉取全部数据foreach ($client-messages-batches-list(limit: 20) as $batch) { echo {$batch-id} - {$batch-processingStatus}\n; }七、进阶批次内使用 Prompt Caching批量任务往往共享同一份系统提示或大段参考文档这正是 Prompt Caching 的最佳场景公共前缀只需计费一次批内每条请求都能命中缓存进一步摊薄成本。python 版 batches.md 给出了完整范式PHP 的写法与其等价注意 PHP 使用 camelCase 顶层参数与对应的嵌套键cacheControl$sharedSystem [ [type text, text You are a literary analyst.], [ type text, text $largeDocumentText, // 所有请求共享 cacheControl [type ephemeral], ], ]; $requests []; foreach ($questions as $i $question) { $requests[] [ customId analysis-{$i}, params [ model claude-opus-4-8, maxTokens 16000, system $sharedSystem, messages [[role user, content $question]], ], ]; } $batch $client-messages-batches-create(requests: $requests);缓存命中验证批内请求的响应usage中包含cacheCreationInputTokens与cacheReadInputTokens字段可据此确认缓存是否生效详见 php/claude-api/README.md 的 Prompt Caching 一节。缓存放置的详细策略前缀稳定性、断点位置、静默失效检查清单可参考 .agents/skills/claude-api/shared/prompt-caching.md。八、完整端到端示例批量情感分类综合以上各节给出一个可直接运行的 PHP 端到端示例对应 python 版 的 Full End-to-End Example将一批文本按 positive / negative / neutral 分类。use Anthropic\Client; $client new Client(apiKey: getenv(ANTHROPIC_API_KEY)); // 1. 准备请求 $items [ The product quality is excellent!, Terrible customer service, never again., Its okay, nothing special., ]; $requests []; foreach ($items as $i $text) { $requests[] [ customId classify-{$i}, params [ model claude-haiku-4-5, maxTokens 50, messages [[ role user, content Classify as positive/negative/neutral (one word): {$text}, ]], ], ]; } // 2. 创建批次 $batch $client-messages-batches-create(requests: $requests); echo Created batch: {$batch-id}\n; // 3. 等待完成 while (true) { $batch $client-messages-batches-retrieve($batch-id); if ($batch-processingStatus ended) { break; } sleep(10); } // 4. 收集结果按键匹配不依赖顺序 $results []; foreach ($client-messages-batches-results($batch-id) as $result) { if ($result-result-type succeeded) { foreach ($result-result-message-content as $block) { if ($block-type text) { $results[$result-customId] $block-text; break; } } } } ksort($results); foreach ($results as $customId $classification) { echo {$customId}: {$classification}\n; }提示分类这类低maxTokens场景也可选用更经济的claude-haiku-4-5200K 上下文、$1/$5 每百万 token批量场景下成本优势更明显。九、适用场景与注意事项总结典型适用场景大规模离线文本分类、情感分析、意图识别文档批量摘要、翻译、关键词抽取数据清洗与结构化抽取配合工具调用与 Prompt Caching任何不要求实时响应、可接受数分钟到数小时延迟的处理流水线。关键注意事项结果无序始终用customId匹配结果严禁按位置取用maxTokens合理取值SKILL.md 建议非流式请求默认约 16000分类等短输出场景可降到 256 左右避免输出被截断错误分级invalid_request如参数校验失败需修正后重试其余服务端错误可直接安全重试结果过期批次创建后 29 天内必须取回结果逾期不可再访问成本核算虽然 token 单价享 50% 折扣但应结合 Prompt Caching 进一步压缩共享前缀的重复计费。与仓库源码的关联本仓库 ai 模块 通过 ClaudeProvider.kt 和 ClaudeStreamDecoder.kt 在 Android 端完整实现了 Claude Messages API 的请求构造、SSE 流式解码与多态内容块文本 / 工具调用 / 思考块处理——这些正是编写批次params与解析结果content时所依赖的同一套语义。可以推断若在 RikkaHub 架构中引入批量能力只需复用既有 provider 层的参数构建逻辑外包一层batches生命周期管理即可。参考文档索引PHP SDK 总览与安装README.md客户端初始化、基础请求、Extended Thinking、Prompt Caching、错误处理Message BatchesPHP 版本文核心创建 / 轮询 / 取结果的骨架代码Message BatchesPython 版 / Message BatchesTypeScript 版同一 API 的跨语言完整示例与关键事实Claude API 技能入口SKILL.md模型表、批次适用性判定、Common PitfallsPrompt Caching 共享文档批次内共享前缀的缓存放置策略ClaudeProvider.kt仓库内 Claude Messages API 的 Kotlin 实现参照赞分享人工智能大模型AI 应用移动开发交互助手【免费下载链接】rikkahubRikkaHub is an Android APP that supports for multiple LLM providers.项目地址https://gitcode.com/gh_mirrors/ri/rikkahub点击查看免费下载相关推荐agentic-awesome-skills 中的 Claude Message Batches APIPython异步批量消息处理实战指南agentic awesome skills 中的 Claude Message Batches APIPython异步批量消息处理实战指南 导读 本文以AI 技能AI 插件使用 Anthropic TypeScript SDK 构建 Claude Message Batches 批量处理管线使用 Anthropic TypeScript SDK 构建 Claude Message Batches 批量处理管线 导读 本文聚焦于 Claude APIAI 技能AI 插件Claude 批量处理如何用 Message Batches API 异步跑大规模请求并降低一半成本Claude 批量处理如何用 Message Batches API 异步跑大规模请求并降低一半成本 当你手上有大量不需要实时响应的 Claude Messa示例工程上一篇QMCDecode终极指南5分钟解锁QQ音乐加密格式实现跨平台播放自由下一篇NS-USBLoader终极指南Switch文件传输与RCM注入一站式解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
