做大規(guī)模 LLM 應(yīng)用時(shí)你遲早會(huì)撞到一堵墻批量任務(wù)到底應(yīng)該怎么跑比如領(lǐng)導(dǎo)丟給你 10 萬條商品評(píng)論要求每條都做情感分類和摘要比如運(yùn)營要你把一個(gè)季度 2 萬條客服工單全部打上標(biāo)簽再比如你負(fù)責(zé)把代碼倉庫里幾千個(gè)文件的啟動(dòng)報(bào)錯(cuò)信息交給模型做第一輪定位。你第一反應(yīng)是寫個(gè) for 循環(huán)一條條調(diào)用模型 API。跑完第 500 條的時(shí)候429 限流報(bào)錯(cuò)開始刷屏你改成多線程并發(fā)成本上去了結(jié)果順序又對(duì)不上了你咬著牙把整個(gè)任務(wù)重跑一遍發(fā)現(xiàn)其中一批因?yàn)槌瑫r(shí)丟了幾十條還得手動(dòng)補(bǔ)。這個(gè)場景恰恰是“從零到 Claude Certified Architect”這條學(xué)習(xí)路徑里繞不開的一道坎。很多人以為架構(gòu)師只需要設(shè)計(jì)系統(tǒng)、管理集群實(shí)際上在 AI 應(yīng)用時(shí)代能不能把模型調(diào)用做成一條可監(jiān)控、可恢復(fù)、可計(jì)算的流水線才是真正拉開水平的差距。這篇文章要講的就是面向 Claude 的批處理Batch Processing方案。我會(huì)沿著一條完整的學(xué)習(xí)路線展開先講清楚 Batch API 到底改變了什么再給你一套可以直接跑通的最小示例最后補(bǔ)充生產(chǎn)環(huán)境里最容易踩的坑和架構(gòu)建議。如果你正準(zhǔn)備“Claude Certified Architect”相關(guān)的認(rèn)證或能力建設(shè)這篇文章可以當(dāng)作批處理部分的入門筆記。1. 為什么批處理值得成為架構(gòu)師的基本功先說判斷對(duì)于離線、非實(shí)時(shí)、高吞吐的大模型調(diào)用能走批處理就不要走同步調(diào)用。這個(gè)原則不是我拍腦袋總結(jié)的而是被真實(shí)工程里的成本、限流和運(yùn)維問題逼出來的。如果你只是寫小腳本一次調(diào)用幾十條同步循環(huán)完全夠用。但當(dāng)任務(wù)量級(jí)到幾千、幾萬甚至十萬條時(shí)同步調(diào)用會(huì)暴露三個(gè)尖銳問題。第一是速率限制。絕大多數(shù)大模型 API 都按并發(fā)和每分鐘請(qǐng)求數(shù)做限流。你寫一個(gè) while 循環(huán)一條條發(fā)可能 200 條以內(nèi)沒事再往后就會(huì)出現(xiàn) HTTP 429。很多人上來就上多線程結(jié)果限流更快還容易被臨時(shí)封禁。第二是成本模型。同步請(qǐng)求每一次都是完整往返一旦網(wǎng)絡(luò)抖動(dòng)、超時(shí)重試錢就花在無意義的重復(fù)調(diào)用上。第三是結(jié)果管理。循環(huán)里的結(jié)果散落在內(nèi)存或日志里哪一條成功、哪一條失敗了要靠額外代碼記錄任務(wù)一旦中斷恢復(fù)成本非常高。Batch API 換了一個(gè)思路不要求你在請(qǐng)求發(fā)出后立刻拿到結(jié)果而是把一批請(qǐng)求打包提交由服務(wù)端排隊(duì)處理完成后統(tǒng)一拉取結(jié)果。聽起來只是“晚點(diǎn)拿結(jié)果”但它帶來的架構(gòu)收益是結(jié)構(gòu)性的。你可以把批處理理解成“菜市場代加工”和“中央廚房”的區(qū)別。同步調(diào)用是你站在柜臺(tái)前一條魚從殺到切好要等十分鐘你一直占著位置批處理是把一筐魚送去中央廚房幾小時(shí)后統(tǒng)一取貨單位成本和吞吐量完全不一樣。對(duì)“Claude Certified Architect”這條學(xué)習(xí)路徑來說掌握批處理的意義在于你在為一個(gè)真實(shí)業(yè)務(wù)設(shè)計(jì) AI 能力時(shí)必須能區(qū)分哪些任務(wù)可以延遲處理哪些必須是實(shí)時(shí)交互。能夠做出這種判斷才叫架構(gòu)能力而不僅僅是 API 調(diào)用能力。2. Claude Batch API 核心概念與原理2.1 什么是 Batch APIClaude Batch API 是 Anthropic 提供的一種異步請(qǐng)求方式。你通過 API 提交一個(gè)包含若干單條請(qǐng)求的批次服務(wù)端會(huì)生成一個(gè)批處理任務(wù)在后臺(tái)調(diào)度模型執(zhí)行完成后提供結(jié)果供你下載。關(guān)鍵點(diǎn)在于批次里的每條請(qǐng)求本質(zhì)上仍然是標(biāo)準(zhǔn)的 Messages API 格式。也就是說你構(gòu)造請(qǐng)求時(shí)用的是和平時(shí)實(shí)時(shí)調(diào)用一樣的model、messages、max_tokens、system這些參數(shù)只是不立即發(fā)送執(zhí)行而是包在一個(gè)批次里統(tǒng)一提交。一個(gè)典型的批次提交結(jié)構(gòu)長這樣{ requests: [ { custom_id: review-000001, params: { model: claude-3-5-haiku-latest, max_tokens: 200, messages: [ {role: user, content: 分析這條評(píng)論的情感傾向手機(jī)很好但續(xù)航一般。} ] } } ] }注意這里的custom_id它是你給每條請(qǐng)求起的唯一標(biāo)識(shí)結(jié)果返回時(shí)靠它對(duì)齊。這是批處理架構(gòu)里最重要的約定后面我會(huì)專門展開。2.2 Batch API 與同步 API 的差異如果你之前只用過同步 Messages API可以先記住這張對(duì)比表對(duì)比維度同步 Messages APIBatch API請(qǐng)求方式請(qǐng)求發(fā)出后阻塞等待結(jié)果提交批次后立即返回后臺(tái)異步處理返回耗時(shí)秒級(jí)甚至毫秒級(jí)分鐘級(jí)到小時(shí)級(jí)適用場景聊天對(duì)話、實(shí)時(shí)助手、在線查詢離線分析、批量分類、數(shù)據(jù)清洗成本標(biāo)準(zhǔn)費(fèi)率通常有更優(yōu)惠的批處理費(fèi)率配額受實(shí)時(shí)速率限制約束使用獨(dú)立的批處理配額池吞吐更高結(jié)果獲取響應(yīng)體直接攜帶輪詢狀態(tài)完成后下載結(jié)果文檔失敗處理當(dāng)前請(qǐng)求直接報(bào)錯(cuò)批次中單條失敗會(huì)記錄在結(jié)果文檔中從架構(gòu)角度看Batch API 把“調(diào)用模型”從在線鏈路中拿了出來變成一種離線計(jì)算任務(wù)。這個(gè)轉(zhuǎn)變讓任務(wù)調(diào)度、重試、結(jié)果對(duì)齊都變成了常規(guī)工程問題而不是疊加在 LLM 調(diào)用上的額外復(fù)雜度。2.3 適用場景與不適用場景適合用批處理的場景有一個(gè)共同特征用戶不坐在屏幕前等結(jié)果或者可以接受分鐘級(jí)以上的返回延遲。典型場景包括批量內(nèi)容分類給新聞、商品、社交評(píng)論打標(biāo)簽。信息抽取從合同、工單、郵件中抽取結(jié)構(gòu)化字段。文本摘要對(duì)大量文檔生成摘要。數(shù)據(jù)清洗與格式化把非結(jié)構(gòu)化文本轉(zhuǎn)成 JSON。代碼分析批量檢查倉庫中的代碼模式、生成建議。離線的運(yùn)營分析和報(bào)表加工。不適合的場景也很明顯。實(shí)時(shí)對(duì)話機(jī)器人、在線搜索問答、RAG 應(yīng)用的在線檢索生成這些鏈路對(duì)延遲極其敏感必須走同步調(diào)用。交互式的 Agent 循環(huán)也不適合批處理因?yàn)?Agent 每一步都需要根據(jù)上一步結(jié)果決定下一步動(dòng)作無法預(yù)先打包。簡單總結(jié)延遲越低、交互性越強(qiáng)的任務(wù)越應(yīng)該走同步量越大、實(shí)時(shí)性要求越低的離線任務(wù)越應(yīng)該走 Batch。3. 環(huán)境準(zhǔn)備與前置條件在動(dòng)手寫代碼之前先把環(huán)境準(zhǔn)備到位。很多人卡在批處理這里不是代碼邏輯問題而是環(huán)境變量、SDK 版本和賬號(hào)權(quán)限沒確認(rèn)清楚。3.1 運(yùn)行環(huán)境本文示例使用 Python 3。建議使用 3.10 或更高版本太舊的 Python 版本對(duì)類型注解和依賴兼容不太友好。操作系統(tǒng)的限制不大Windows、macOS、Linux 都可以但命令行方式略有差異。3.2 安裝官方 SDKAnthropic 提供了官方 Python SDK包名就是anthropic。安裝命令pip install anthropic如果網(wǎng)絡(luò)環(huán)境特殊可以從公司內(nèi)部 PyPI 鏡像安裝或者指定版本號(hào)。安裝后建議確認(rèn)一下版本不同 SDK 版本的批處理方法名有過調(diào)整python -c import anthropic; print(anthropic.__version__)3.3 獲取 API Key 并配置環(huán)境變量調(diào)用 Claude API 需要 API Key。申請(qǐng)賬號(hào)和 Key 一定要走官方正規(guī)渠道。如果你是公司項(xiàng)目找管理員開通權(quán)限如果是個(gè)人學(xué)習(xí)用你自己賬號(hào)下的 Key。這里有一個(gè)所有開發(fā)者都應(yīng)該嚴(yán)格遵守的習(xí)慣不要把 API Key 硬編碼到代碼里更不要提交到 Git 倉庫。正確做法是放到環(huán)境變量中export ANTHROPIC_API_KEYsk-ant-你的keyWindows 環(huán)境下使用set ANTHROPIC_API_KEYsk-ant-你的key之所以強(qiáng)調(diào)這一點(diǎn)是因?yàn)榇竽Ｐ?API Key 直接關(guān)聯(lián)賬號(hào)費(fèi)用。一旦泄露到公網(wǎng)倉庫幾小時(shí)內(nèi)就可能被掃描工具盜刷產(chǎn)生高額賬單。3.4 確認(rèn)模型可用性Batch API 支持的模型范圍以官方文檔和賬號(hào)權(quán)限為準(zhǔn)。本文示例代碼會(huì)預(yù)留環(huán)境變量MODEL_NAME os.getenv(ANTHROPIC_MODEL, claude-3-5-haiku-latest)你運(yùn)行時(shí)可以先查一下賬號(hào)在當(dāng)前區(qū)域可用的模型列表把ANTHROPIC_MODEL設(shè)置成實(shí)際可用模型名。寫死模型名是初學(xué)者最常見的翻車點(diǎn)代碼本身沒問題但模型名不對(duì)提交批次直接報(bào)錯(cuò)。4. 核心流程拆解三階段工作流理解了 Batch API 的原理之后要把“能用”變成“好用”關(guān)鍵是建立完整的批處理工作流意識(shí)。整個(gè)流程可以拆成三個(gè)階段構(gòu)造請(qǐng)求、提交與輪詢、結(jié)果回收。階段一構(gòu)造請(qǐng)求數(shù)據(jù)這個(gè)階段最重要的決定不是模型參數(shù)而是custom_id的設(shè)計(jì)。custom_id是批次中每條請(qǐng)求的唯一業(yè)務(wù)標(biāo)識(shí)它在任務(wù)提交時(shí)由你決定在結(jié)果返回時(shí)原樣帶回來。你可以把它看作是快遞單號(hào)下單時(shí)填寫派送全程跟蹤簽收時(shí)核對(duì)。工程上custom_id建議直接關(guān)聯(lián)你的業(yè)務(wù)主鍵。例如處理商品評(píng)論時(shí)用評(píng)論 ID 作為custom_id處理工單時(shí)用工單 ID。這樣結(jié)果回來時(shí)不需要額外維護(hù)映射關(guān)系直接按 ID 回寫數(shù)據(jù)庫。此外構(gòu)造請(qǐng)求時(shí)還要想清楚 prompt 模板。批處理的特點(diǎn)是量大你不可能手動(dòng)逐條檢查所以 prompt 模板要設(shè)計(jì)得足夠穩(wěn)定輸出格式要盡量結(jié)構(gòu)化。推薦在system里明確輸出格式讓模型返回 JSON便于后續(xù)解析和落庫。階段二提交與輪詢創(chuàng)建批次后服務(wù)端會(huì)返回一個(gè)批次對(duì)象包含批次 ID 和初始狀態(tài)。批次會(huì)經(jīng)歷排隊(duì)、處理、完成等階段你無法知道確切完成時(shí)間所以需要輪詢狀態(tài)。輪詢不是一個(gè)循環(huán)反復(fù)請(qǐng)求而是有節(jié)奏地檢查。間隔太短白白消耗 API 額度間隔太長結(jié)果出來后不能及時(shí)處理。一般建議初始間隔設(shè)定在 30 到 60 秒根據(jù)任務(wù)量調(diào)整。如果一批有幾千條請(qǐng)求處理時(shí)間可能要幾十分鐘輪詢間隔可以放寬到 5 分鐘以上。階段三結(jié)果回收批次完成后你會(huì)拿到一個(gè)結(jié)果文檔。結(jié)果文檔里包含了每條請(qǐng)求的處理狀態(tài)成功消息、模型輸出文本、或者失敗原因。結(jié)果回收階段要做的第一件事不是急著寫庫而是先做數(shù)量核對(duì)。成功的條數(shù)加上失敗的條數(shù)應(yīng)該等于你提交的總條數(shù)。如果對(duì)不上說明你的custom_id可能有重復(fù)或者請(qǐng)求構(gòu)造時(shí)有遺漏。對(duì)于失敗的請(qǐng)求要根據(jù)error字段里的原因分類處理。有的是單條請(qǐng)求格式問題可以直接修正后重新提交有的是模型臨時(shí)不可用可以直接重試有的是輸入內(nèi)容觸發(fā)了內(nèi)容過濾需要人工復(fù)核。最忌諱的是把所有失敗請(qǐng)求原樣重跑一遍這樣既浪費(fèi)成本也無法解決真正的問題。5. 完整示例從零跑通一個(gè)批處理任務(wù)這一節(jié)我們直接上手用一個(gè)真實(shí)的業(yè)務(wù)場景把整個(gè)流程跑通。場景設(shè)定某電商平臺(tái)有一批商品評(píng)論每條的原始文本是英文需要做三件事判斷情感傾向、提取核心問題、輸出簡潔摘要。要求結(jié)果以 JSON 格式返回方便后續(xù)寫入數(shù)據(jù)庫。5.1 構(gòu)造請(qǐng)求數(shù)據(jù)先準(zhǔn)備一個(gè)小型 Python 腳本只展示請(qǐng)求構(gòu)造的核心邏輯# 文件路徑build_requests.py import os import json MODEL_NAME os.getenv(ANTHROPIC_MODEL, claude-3-5-haiku-latest) SYSTEM_PROMPT ( You are a review analysis assistant. Given a product review, return JSON with fields: sentiment (positive/negative/neutral), issue (string, main complaint or empty), summary (string, one sentence). ) def build_batch_requests(reviews): # reviews 是 list[dict]包含 id 和 text 兩個(gè)字段 requests_payload [] for item in reviews: requests_payload.append({ custom_id: freview-{item[id]}, params: { model: MODEL_NAME, max_tokens: 200, system: SYSTEM_PROMPT, messages: [ {role: user, content: item[text]} ] } }) return requests_payload if __name__ __main__: sample_reviews [ {id: 1, text: Fast shipping and great battery life, but the screen is a bit dim.}, {id: 2, text: Terrible product, the strap broke after two days.}, ] payload build_batch_requests(sample_reviews) print(json.dumps(payload[:1], ensure_asciiFalse, indent2))這段代碼的關(guān)鍵點(diǎn)有兩個(gè)。第一system字段被顯式設(shè)置要求模型返回結(jié)構(gòu)化 JSON這比在用戶消息里夾帶格式說明更穩(wěn)定。第二custom_id使用review-{id}格式既保證了唯一性也保留了業(yè)務(wù) ID 信息。運(yùn)行這個(gè)腳本可以看到第一批請(qǐng)求的數(shù)據(jù)結(jié)構(gòu)python build_requests.py5.2 創(chuàng)建批次并輪詢接下來是完整運(yùn)行腳本創(chuàng)建批次并輪詢狀態(tài)。這里使用官方 Python SDK# 文件路徑submit_batch.py import os import time import anthropic client anthropic.Anthropic() def create_batch(requests_payload): batch client.message_batches.create( requestsrequests_payload ) print(batch id:, batch.id) return batch.id def wait_for_batch(batch_id, interval_seconds30): while True: batch client.message_batches.retrieve(batch_id) status batch.processing_status print(status:, status) if status in (completed, canceled, expired, errored): return batch time.sleep(interval_seconds)如果你的 SDK 版本較舊processing_status字段可能叫processing_state打印當(dāng)前批次對(duì)象就能看到實(shí)際字段名。輪詢循環(huán)必須在超時(shí)和異常上有保護(hù)生產(chǎn)環(huán)境建議加一個(gè)最大等待時(shí)間超過預(yù)期時(shí)間直接告警而不是無限循環(huán)。5.3 獲取結(jié)果并落庫批次完成后通過results方法獲取結(jié)果# 文件路徑fetch_results.py import json def parse_results(batch_id): results client.message_batches.results(batch_id) output [] for item in results.data: record { custom_id: item.custom_id, } # 新版本 SDK 中 result 是對(duì)象舊版本可能返回 dict result_obj item.result if hasattr(result_obj, type): result_type result_obj.type else: result_type result_obj.get(type) if result_type succeeded: # 成功時(shí)message 里保存模型輸出 if hasattr(result_obj, message): msg result_obj.message else: msg result_obj.get(message) content_text .join( block.get(text, ) if isinstance(block, dict) else block.text for block in msg.content ) record[status] succeeded record[content] content_text else: record[status] failed record[error] result_obj.error if hasattr(result_obj, error) else result_obj.get(error) output.append(record) with open(batch_results.json, w, encodingutf-8) as fp: json.dump(output, fp, ensure_asciiFalse, indent2) return output代碼里我做了兼容處理因?yàn)椴煌姹镜?SDK 對(duì)result的封裝形式有差異。如果你在生產(chǎn)環(huán)境鎖定了 SDK 版本可以刪掉這些分支只保留你當(dāng)前版本對(duì)應(yīng)的寫法。從架構(gòu)角度解析結(jié)果時(shí)你其實(shí)是在做兩件事一是把成功結(jié)果轉(zhuǎn)為業(yè)務(wù)數(shù)據(jù)二是把失敗結(jié)果單獨(dú)挑出來進(jìn)入補(bǔ)償流程。不要把它們混在一個(gè)表里處理。6. 運(yùn)行結(jié)果與效果驗(yàn)證6.1 運(yùn)行與預(yù)期輸出把上面三個(gè)文件按順序組織好先構(gòu)造請(qǐng)求再提交批次最后拉取結(jié)果。跑通后的預(yù)期輸出類似這樣batch id: msgbatch_xxxxxxxxxxxx status: in_progress status: in_progress status: completed結(jié)果文件batch_results.json中每條記錄大致為[ { custom_id: review-1, status: succeeded, content: {\sentiment\: \positive\, \issue\: \dim screen\, \summary\: \Fast shipping and good battery life, but screen brightness is below average.\} } ]注意content是模型返回的原始文本。因?yàn)槲覀冏屇Ｐ洼敵?JSON所以這里是一個(gè) JSON 字符串還需要再解析一次才能寫入數(shù)據(jù)庫。6.2 如何判斷成功判斷批處理任務(wù)是否真正成功不能只看批次狀態(tài)為completed。建議按這三步核驗(yàn)數(shù)量核對(duì)結(jié)果文檔中的記錄數(shù)是否等于提交的請(qǐng)求數(shù)。失敗率檢查request_counts里的succeeded和errored是否符合預(yù)期是否有個(gè)別請(qǐng)求因?yàn)檩斎雰?nèi)容被過濾而失敗。內(nèi)容抽檢隨機(jī)抽 5 到 10 條結(jié)果人工確認(rèn)模型輸出是有效的 JSON字段沒有缺失摘要沒有明顯幻覺。如果批量規(guī)模很大人工抽檢比例可以適當(dāng)降低但絕對(duì)不能省。批處理是離線鏈路錯(cuò)誤如果在下游才暴露定位成本會(huì)高得多。7. 常見問題與排查思路7.1 請(qǐng)求提交時(shí)報(bào)錯(cuò)問題現(xiàn)象可能原因排查方式解決方案返回 400 錯(cuò)誤提示 requests 格式錯(cuò)誤custom_id缺失或重復(fù)打印請(qǐng)求數(shù)據(jù)檢查每條請(qǐng)求是否都包含custom_id和params確保custom_id唯一且類型為字符串返回 400提示模型名不可用模型名拼寫錯(cuò)誤或賬號(hào)無權(quán)限查看賬號(hào)可用的模型列表修改環(huán)境變量ANTHROPIC_MODEL為可用模型返回 401 或 403API Key 無效或權(quán)限不足檢查環(huán)境變量是否加載成功重新設(shè)置ANTHROPIC_API_KEY確認(rèn)賬號(hào)有 Batch 使用權(quán)限返回 429觸發(fā)實(shí)時(shí)限流或批處理配額不足查看響應(yīng)頭中的retry-after等待后重試或聯(lián)系管理員提升批處理配額7.2 批次狀態(tài)異常processing_status一直停留在in_progress是最常見的情況不等于報(bào)錯(cuò)。批處理任務(wù)本來就是排隊(duì)執(zhí)行幾分鐘到幾小時(shí)都正常。你需要關(guān)注的是expired和canceled狀態(tài)。expired意味著批次超過了官方允許的最大等待時(shí)間。遇到這種情況先檢查是不是請(qǐng)求量太大導(dǎo)致排隊(duì)過久然后考慮拆成多個(gè)小批次。canceled表示你主動(dòng)取消了批次或者賬號(hào)側(cè)有限制。7.3 結(jié)果對(duì)不上結(jié)果文檔里缺少某幾個(gè)custom_id或者成功數(shù)加失敗數(shù)不等于提交數(shù)。這種情況大概率是請(qǐng)求構(gòu)造階段出了問題custom_id有重復(fù)會(huì)導(dǎo)致結(jié)果只保留一個(gè)或者requests數(shù)組里某些請(qǐng)求被攔截沒有進(jìn)入正式處理流程。另外下載結(jié)果后要盡快歸檔。批次結(jié)果不會(huì)無限期保留過期后就無法再拉取。生產(chǎn)環(huán)境建議把結(jié)果落庫或存對(duì)象存儲(chǔ)不要只依賴 API 側(cè)的結(jié)果文檔。7.4 和 Claude Code 相關(guān)的誤區(qū)最近關(guān)于 Claude Code 的熱度很高很多初學(xué)者容易把 Claude Code 的安裝問題、環(huán)境配置問題與 Batch API 混在一起。這里做一個(gè)區(qū)分Claude Code 是 Anthropic 推出的編程輔助工具主要面向命令行和 IDE 場景幫助開發(fā)者在終端里完成代碼編寫、審查和重構(gòu)。它的安裝和配置問題比如“claude 無法識(shí)別為 cmdlet 函數(shù)”“VSCode 中如何配置 Claude Code”屬于另一套工具鏈的范疇。而本文討論的 Batch API 是面向程序開發(fā)的模型調(diào)用能力兩者不是同一個(gè)層面的概念。如果你在做批處理開發(fā)遇到問題時(shí)應(yīng)優(yōu)先查看 API 錯(cuò)誤碼和官方文檔而不是用 Claude Code 的排錯(cuò)方式去解決。8. 最佳實(shí)踐與架構(gòu)設(shè)計(jì)建議8.1 把custom_id當(dāng)作業(yè)務(wù)主鍵批處理架構(gòu)里custom_id不是可有可無的輔助字段而是整個(gè)系統(tǒng)的“對(duì)齊錨點(diǎn)”。它應(yīng)該來自業(yè)務(wù)主鍵并且在提交前做唯一性校驗(yàn)。不要用隨機(jī)數(shù)不要用時(shí)間戳更不要用模型輸出的內(nèi)容去反推業(yè)務(wù)數(shù)據(jù)。正確的做法是提交前先查一次數(shù)據(jù)庫確認(rèn)這批custom_id沒有處理過。這保證了批處理任務(wù)的冪等性——重復(fù)提交同一批任務(wù)時(shí)不會(huì)產(chǎn)生重復(fù)處理。8.2 小批次試跑大批次生產(chǎn)第一次接入 Batch API不要直接提交十萬條。先用 50 到 100 條小批次跑通流程確認(rèn)三個(gè)方面模型輸出格式是否符合預(yù)期、custom_id對(duì)齊是否準(zhǔn)確、失敗率是否在可接受范圍內(nèi)。確認(rèn)無誤后再放大規(guī)模。大任務(wù)也要拆成多個(gè)批次而不是單批次塞到底。原因有兩點(diǎn)一是單批次過大一旦某一條請(qǐng)求內(nèi)容有問題整個(gè)批次的重跑成本很高二是拆成多個(gè)批次后可以按批次做進(jìn)度跟蹤和局部重試。8.3 結(jié)果數(shù)據(jù)要持久化批處理任務(wù)的結(jié)果應(yīng)該被持久化存儲(chǔ)。建議流程是批次完成后把結(jié)果同步到數(shù)據(jù)庫表記錄batch_id、custom_id、status、raw_output、processed_at等字段。后續(xù)所有下游消費(fèi)都從數(shù)據(jù)庫讀取而不是反復(fù)調(diào)用 API 拉取結(jié)果。如果結(jié)果需要寫回原始業(yè)務(wù)表也建議先落到中間表經(jīng)過校驗(yàn)和清洗后再更新正式表避免模型輸出直接污染業(yè)務(wù)數(shù)據(jù)。8.4 成本控制與監(jiān)控批處理雖然成本比同步低但量大之后費(fèi)用依然可觀。建議在提交批次前做一次 token 預(yù)估用 5 條代表性樣本統(tǒng)計(jì)平均 token 消耗乘以總數(shù)得到預(yù)估成本。監(jiān)控層面至少記錄四個(gè)指標(biāo)提交條數(shù)、成功條數(shù)、失敗條數(shù)、平均處理時(shí)長。配套告警規(guī)則失敗率超過 5% 告警批次處理時(shí)長超過預(yù)估時(shí)間 2 倍告警。這些數(shù)據(jù)既可以幫助你判斷模型和 API 的健康狀態(tài)也可以用來評(píng)估 prompt 模板是否需要優(yōu)化。8.5 API Key 與安全邊界再強(qiáng)調(diào)一次安全紅線。API Key 一律走環(huán)境變量或密鑰管理服務(wù)不能出現(xiàn)在代碼、日志和倉庫中。生產(chǎn)環(huán)境建議使用云廠商的密鑰管理系統(tǒng)并配置最小權(quán)限例如只允許訪問 Batch API不允許訪問賬號(hào)管理接口。模型輸出內(nèi)容也可能包含業(yè)務(wù)敏感信息。批處理結(jié)果在落庫、傳輸、展示時(shí)要根據(jù)公司數(shù)據(jù)安全規(guī)范做脫敏和權(quán)限控制。不要因?yàn)閿?shù)據(jù)是模型生成的就忽略了它本身屬于業(yè)務(wù)資產(chǎn)。9. 總結(jié)與下一步批處理聽起來是個(gè)很基礎(chǔ)的 API 功能真正難的是把它放進(jìn)工程鏈路里。你需要想清楚custom_id怎么設(shè)計(jì)批次怎么拆分結(jié)果怎么核對(duì)失敗怎么補(bǔ)償。這些不是模型能力問題而是分布式任務(wù)處理的通用問題。Claude Batch API 只是把模型調(diào)用變成了一個(gè)異步任務(wù)剩下的架構(gòu)設(shè)計(jì)還得靠你按工程標(biāo)準(zhǔn)來做。今天這篇內(nèi)容覆蓋了 Batch API 的概念、環(huán)境準(zhǔn)備、核心流程和完整代碼示例也把常見錯(cuò)誤和最佳實(shí)踐梳理了一遍。你可以先找一個(gè)數(shù)據(jù)量只有幾百條的離線任務(wù)按文中步驟跑通再逐漸擴(kuò)大到上萬條。跑通之后再思考從單機(jī)批處理升級(jí)到任務(wù)隊(duì)列和調(diào)度系統(tǒng)那時(shí)候你的架構(gòu)能力就真的進(jìn)階了。建議收藏備用尤其是里面關(guān)于結(jié)果核對(duì)和custom_id設(shè)計(jì)的兩段等你真正跑大規(guī)模批處理時(shí)大概率會(huì)回來復(fù)習(xí)。