この記事は、Worksi の AI エージェントが英語の原文をもとに日本語で書き直し、別の AI エージェントが内容を事実確認したものです。原文(英語)へのリンクは末尾にあります。
Adapted into Japanese by Worksi's AI agents from the English original (linked at the end), and fact-checked by a separate AI agent.
OpenAI の Batch ジョブが expired を返したとき、失敗したリクエストを再試行する手っ取り早い方法は、入力ファイルをまるごと再送信することです。しかしこれでは、すでに料金を払った処理を捨てることになり、完了していた項目に2つ目の結果を書き込んでしまうおそれがあります。逆の近道、つまり batch_expired と記された行だけを再試行する方法は、手元の証拠が完全であることを暗黙のうちに前提にしています。どちらも安全ではありません。expired というステータスは、個々の行のどれが完了したかを教えてくれません。各行の結果は、行単位のファイルから確定させてください。
対処法は小さな復旧台帳(リカバリーレジャー)です。入力1行につき1行を持ち、バッチが生成したすべてのものと custom_id で結合し、状態は2層の証拠から決めます。1層目はリクエストに何が起きたか。2層目は、完了したリクエストが使える結果を返したかどうかです。この記事では、5行の合成データの例でこの台帳を組み立て、正しい行を再試行する方法と、重複した結果が下流のストアを壊さないようにする方法を示します。
Batch ガイドが実際に約束していること
OpenAI Batch API ガイド(2026年11月15日に確認)には、必要な材料がそろっています。まとめると次のとおりです。
- 各リクエスト行には一意の
custom_idを含める必要があり、これを使って結果を入力に対応づけます。 - 出力ファイルには、成功したリクエストごとに1行があります。失敗したリクエストのエラー情報は別のエラーファイルに書き込まれ、バッチの
error_file_idから見つけられます。 - 「出力行の順序は入力行の順序と一致しない場合があります(The output line order may not match the input line order.)」。位置ではなく
custom_idで対応づけてください。 - expired のバッチとは「24時間の期間内に完了できなかった(was not able to be completed within the 24-hour time window)」バッチです。未完了のリクエストはキャンセルされ、完了したリクエストのレスポンスは出力ファイルで取得でき、期限切れのリクエストはコード
batch_expiredでエラーファイルに書き込まれます。 - 「完了したリクエストで消費されたトークンについては課金されます(You will be charged for tokens consumed from any completed requests.)」。
- 出力ファイルとエラーファイルは、デフォルトではファイル作成から30日で期限切れになります。
output_expires_afterで1時間から30日の範囲で設定できます。
つまり expired のバッチは、形式が文書化された部分的な結果セットです。やるべきことは、そのうちどの部分が手元にあるかを突き止めることです。
終端ステータスはどれも同じ意味ではない
行に手をつける前に、バッチオブジェクトを取得し、どの終端状態にあるかを確認します。ガイドには4つが挙げられており、それぞれ必要な作業が異なります。
-
failed: 入力ファイルが検証に失敗しました。バッチのerrorsフィールドを確認してください。同じファイルを再送信しても同じように失敗するので、入力を修正します。 -
expired: 未完了の処理を残したまま期間が終わりました。出力ファイルに完了した行が、エラーファイルにbatch_expiredの行があると考えてください。 -
cancelled: 誰かがキャンセルしました。ガイドによると、処理中のリクエストはcancellingの間に完了し、それには最大10分かかることがあります。ただし、その結果生じるファイルについては、期限切れの場合ほど詳しく説明していません。決めつけずに、取得したオブジェクトからoutput_file_idとerror_file_idを読み取ってください。 -
completed: バッチは終了しましたが、個々のリクエストが失敗している可能性はあります。ガイドではそうしたものもエラーファイルに送られるので、completed のバッチにも同じ台帳が必要です。
ステータスからわかるのは、入力検証が失敗したかどうか、処理が終わったかどうか、そしてどのファイルを探せばよいかです。どの行が完了したかはわかりません。以下の台帳は、4つすべてについてその答えを出します。
合成データの例
この例の内容はすべて、手法を示すために作ったものです。バッチ ID、ファイルの内容、欠けている行は説明用であり、報告された障害ではありません。
5つの文書を invoice、contract、other のいずれかに分類するために送信したとします。この仮定の例では、リクエストは通常の JSON モードを使っていました。Structured Outputs ガイドによると、JSON モードは有効な JSON を生成しますが、スキーマへの準拠は保証しません。
アップロード前に、各行の論理項目 ID、試行 ID、custom_id を記録しておきました。バッチを作成するとその ID が返ってきたので、それも追加しました。これが拡張したマニフェストです。
| logical_item_id | attempt_id | batch_id | custom_id |
|---|---|---|---|
| doc-0001 | att-01 | batch_SYN_A | a01-doc-0001 |
| doc-0002 | att-01 | batch_SYN_A | a01-doc-0002 |
| doc-0003 | att-01 | batch_SYN_A | a01-doc-0003 |
| doc-0004 | att-01 | batch_SYN_A | a01-doc-0004 |
| doc-0005 | att-01 | batch_SYN_A | a01-doc-0005 |
logical_item_id は関心の対象そのもので、試行をまたいで変わりません。custom_id は1回の送信に限定されたものです。試行のプレフィックスを含めることで、後のバッチがこのバッチと証拠ストア内で衝突する ID を生まないようにしています。これらの ID には個人データを入れないでください。ログ、ファイル名、チケットに残るからです。
バッチは expired で返ってきました。出力ファイルをダウンロードします。順序に注意してください。
{"id": "batch_req_s5", "custom_id": "a01-doc-0005", "response": {"status_code": 200, "body": {"label": "receipt"}}, "error": null}
{"id": "batch_req_s1", "custom_id": "a01-doc-0001", "response": {"status_code": 200, "body": {"label": "contract"}}, "error": null}
行5が行1より前に来ています。出力と入力を行番号で zip するコードは、doc-0001 に receipt というラベルを付けてしまいます。ボディは省略したプレースホルダーで、実際のレスポンスの形ではありません。また、doc-0005 は 200 を返しましたが、ラベルは3つのクラスのどれでもありません。リクエストは完了していても、その結果は使えるものではありません。
次にエラーファイルです。
{"id": "batch_req_s2", "custom_id": "a01-doc-0002", "response": null, "error": {"code": "batch_expired", "message": "This request could not be executed before the completion window expired."}}
{"id": "batch_req_s3", "custom_id": "a01-doc-0003", "response": null, "error": {"code": "SYNTHETIC_OTHER_ERROR", "message": "Placeholder for a non-expiry failure."}}
1行目は、ガイドが期限切れについて文書化している形をそのまま写したものです。2行目はプレースホルダーです。期限切れ以外の実際のエラーはエンドポイントやリクエストによって異なるので、ここで作ったコードに一致させるのではなく、行の内容を読んでください。
そして a01-doc-0004 はどちらのファイルにも現れません。この仮定の例では、エラーファイルをダウンロードしたジョブが途中で止まり、その失敗を報告しませんでした。OpenAI が行を落とすと主張しているわけではありません。このシナリオは、自分たちの側の証拠の欠落を表しています。途中で切れたダウンロード、復旧ジョブの実行前に output_expires_after を過ぎてしまったファイル、ジョブが取得しなかったファイル ID などです。どれも見え方は同じで、何も紐づかない行が残ります。
台帳を組み立てる
- バッチを取得します。ステータス、
errors、output_file_id、error_file_id、request_countsを記録します。 - オブジェクトが指すファイルをすべてダウンロードし、何かをパースする前に生のバイト列を保存します。ファイルは期限切れになり、その後は生のコピーだけが証拠になります。
- この
batch_idのマニフェストだけを読み込みます。複数の試行が混ざったマニフェストは、古い結果を新しい行に対応づけてしまいます。 -
custom_idで結合し、すべての行にリクエストレベルの状態を付け、そのうえで、何かが結果ストアに届く前に、完了したすべての結果を検証します。
import json
from collections import defaultdict
ALLOWED_LABELS = {"invoice", "contract", "other"}
def read_jsonl(path):
"""None means the file was not available, which is not the same as empty."""
if path is None:
return None
with open(path, encoding="utf-8") as f:
return [json.loads(line) for line in f if line.strip()]
def classify_transport(line):
"""Request-level outcome only. A 2xx says the request completed,
not that the result is usable."""
error = line.get("error")
response = line.get("response") or {}
if error and error.get("code") == "batch_expired":
return "expired"
if error or not 200 <= response.get("status_code", 0) < 300:
return "failed"
return "completed"
def validate_result(body):
"""Application-level gate, run before any sink write.
Returns (label, None) if usable, (None, reason) if not."""
if not is_complete(body): # the endpoint's own completion indicator
return None, "incomplete"
if is_refusal(body): # the endpoint's own refusal indicator
return None, "refusal"
label = extract_label(body) # parse against your schema
if label not in ALLOWED_LABELS:
return None, f"label outside allowed set: {label!r}"
return label, None
def build_ledger(manifest, batch_id, output_lines, error_lines):
evidence = defaultdict(list)
for source, lines in (("output", output_lines), ("error", error_lines)):
for line in lines or []:
evidence[line["custom_id"]].append({"file": source, "raw": line})
ledger = []
for row in manifest:
if row["batch_id"] != batch_id:
raise ValueError(f"manifest row from another batch: {row['custom_id']}")
seen = evidence.pop(row["custom_id"], [])
label, reason = None, None
if len(seen) > 1:
state = "conflict" # same ID twice: keep both, decide by hand
elif not seen:
state = "unresolved" # no evidence either way
else:
state = classify_transport(seen[0]["raw"])
if state == "completed":
label, reason = validate_result(seen[0]["raw"]["response"]["body"])
state = "usable" if reason is None else "needs_review"
ledger.append({**row, "state": state, "label": label,
"reason": reason, "evidence": seen})
unexpected = sorted(evidence) # IDs in the files but not in the manifest
return ledger, unexpected
is_complete、is_refusal、extract_label は、バッチに使ったエンドポイントに合わせて自分で書く関数です。Chat Completions と Responses ではこれらが報告される場所が異なるので、そのエンドポイントのリファレンスを確認してください。Structured Outputs ガイドは、スキーマを強制した場合でも、アプリケーションは「拒否、不完全なレスポンス、API エラーを処理し、スキーマが表現しないビジネスルールを検証する必要がある(still needs to handle refusals, incomplete responses, and API errors, and validate any business rules that the schema does not express.)」と明記しています。
classify_transport は、行がどちらのファイルから来たかを信用せず、すべての行について error フィールドと response.status_code の両方を確認します。コストはかからず、想定外の行を捕まえられます。重複した custom_id は「最初のものを採用」ではなく conflict になります。ファイルにはあるがマニフェストにない ID は、捨てずに返します。それは間違ったマニフェストか間違ったバッチと結合したことを意味するからです。
次に、合計を request_counts と照合します。不一致は調べる理由であって、結論ではありません。ガイドは、期限切れのリクエストがそこでどう数えられるかを説明していません。
合成バッチの台帳は次のようになります。
| logical_item_id | custom_id | 状態 | 証拠 |
|---|---|---|---|
| doc-0001 | a01-doc-0001 | usable | 出力、2行目、ラベル contract
|
| doc-0002 | a01-doc-0002 | expired | エラー、batch_expired
|
| doc-0003 | a01-doc-0003 | failed | エラー、その他のコード |
| doc-0004 | a01-doc-0004 | unresolved | なし |
| doc-0005 | a01-doc-0005 | needs_review | 出力、1行目、200 でラベル receipt
|
unresolved に対して行動する前に、証拠を修復してください。ファイルがまだ存在するうちに再取得し、保存したもののバイト数と比較し、結合をやり直します。再ダウンロードで doc-0004 の行が見つかれば、その状態に移ります。見つからなければ unresolved のままで、そのときはじめて本当の「不明」になります。
行ごとに判断する
| 観測された証拠 | 解釈 | 次のアクション | 課金の確実性 |
|---|---|---|---|
| 出力行、2xx、検証に合格 | リクエストは完了し、結果は使える | シンクに書き込む。再試行しない。 | 文書化されている: 完了したリクエストのトークンは課金される |
| 出力行、2xx、検証に不合格 | リクエストは完了したが、結果は使えない | 生の行を保持する。シンクには書き込まない。再試行するかは理由に応じて明示的に決める。 | 完了したリクエストなので、同じ課金の記述が当てはまる。完了した再試行は、それ自体のトークンが加わる。 |
エラー行、batch_expired
|
ガイドによれば、期限切れのリクエストは期間が終わる前に実行できなかった | 新しい試行で再試行する | ガイドは完了したリクエストの課金を文書化しているが、期限切れのものについてはそれ以上何も述べていない。使用量データを確認する。 |
| エラー行、その他のコード | 行に書かれた理由でリクエストが失敗した | まずエラーを読む。原因が一時的か、修正済みの場合にだけ再試行する。不正な形式のリクエストは再び失敗する。 | エラーによる。どちらとも決めつけない。 |
| 行なし、証拠は完全 | 異常: 結果は2つのファイルのどちらかに入るというガイドの説明と矛盾する | 隔離する。再試行の前に調査する。 | 不明 |
| 行なし、証拠が不完全 | わからない | 証拠を修復し、結合をやり直す | 不明 |
needs_review では理由が次の手を決めます。私たちの考えでは、これは自動再試行ではなく人が判断すべきものです。不完全なレスポンスは、リクエストを変えれば、たとえば出力上限を大きくすれば成功するかもしれません。拒否や、doc-0005 のようなスキーマ外のラベルは、入力、プロンプト、あるいはスキーマがないことに原因があることを示しています。同じリクエストを変えずに再送信するのは、修正ではなく賭けです。いずれにしても、再試行は新しい試行です。
表の最後の2行は、「期限切れになったのだから実行されていない」という考えが誤りになる場所です。行がないことは、証拠がないということにすぎません。unresolved の行を再試行すると決めることはできますが、それは最初の試行が何もしなかったと信じるからではなく、許容できるコストと重複の扱いについての判断として行ってください。
再試行は新しい試行であり、新しい ID を使う
doc-0002 と doc-0003 の再試行は新しいマニフェストに入れます。doc-0005 は誰かが確認するまで待ちます。
| logical_item_id | attempt_id | batch_id | custom_id | previous_batch_id |
|---|---|---|---|---|
| doc-0002 | att-02 | batch_SYN_B | a02-doc-0002 | batch_SYN_A |
| doc-0003 | att-02 | batch_SYN_B | a02-doc-0003 | batch_SYN_A |
論理 ID はそのままです。custom_id は変わります。両方のバッチ ID を記録しておけば、後で自分や同僚が「doc-0002 を何回送信したか」と尋ねたとき、答えはクエリ1本で出ます。そのうちどの送信が課金されたかは別の問題です。台帳をプロバイダーの使用量データや請求データと結合し、そのデータで決着がつかない課金は「不明」としておいてください。上流の試行と課金された使用量の違いについては、当ブログの請求書の突き合わせと再試行に関する記事で扱っています。
残った行が少数なら、2回目のバッチだけが選択肢ではありません。それらの行を同期エンドポイントに送り、もう一度完了期間を待つのを省くこともできます。その場合、Batch ガイドが同期 API と比べた Batch の割引として示している 50% を手放すことになります。数行であれば絶対額の差は小さいですが、大きなバッチの半分となるとそうはいきません。
プロバイダーではなくシンクを守る
doc-0004 が unresolved のままで、下流のレポートを待てないので再試行したとします。後で完全に再ダウンロードしたところ、最初の試行が完了していたことがわかりました。これで1つの項目に2つの結果があり、ラベルが異なる可能性もあります。この段階に届くのは validate_result に合格した結果だけです。ストアが構造的に2つ目の勝者を拒否するようにします。
CREATE TABLE item_result (
logical_item_id text PRIMARY KEY,
batch_id text NOT NULL,
custom_id text NOT NULL,
result_json jsonb NOT NULL,
written_at timestamptz NOT NULL DEFAULT now()
);
CREATE TABLE item_result_extra (
logical_item_id text NOT NULL,
batch_id text NOT NULL,
custom_id text NOT NULL,
result_json jsonb NOT NULL,
seen_at timestamptz NOT NULL DEFAULT now(),
UNIQUE (batch_id, custom_id)
);
-- First validated result for an item wins.
INSERT INTO item_result (logical_item_id, batch_id, custom_id, result_json)
VALUES ($1, $2, $3, $4)
ON CONFLICT (logical_item_id) DO NOTHING
RETURNING logical_item_id;
insert が行を返さなければ、その項目にはすでに結果があります。保存済みの (batch_id, custom_id) が一致するなら、同じファイルを再処理しただけです。一致しないなら、新しい結果を item_result_extra に(そのキーに対して ON CONFLICT DO NOTHING を付けて)挿入し、レビュー対象としてフラグを立てます。何も上書きされず、黙って重複することもありません。
これが守るのは結果のシンクです。プロバイダーがリクエストを2回実行するのを防ぐものではなく、再試行を無料にするものでもなく、exactly-once 処理でもありません。同じ項目に対する2回の試行の料金を払う可能性は残ります。「最初の結果が勝つ」はポリシーであって、真実ではありません。再試行で修正したプロンプトを使ったのなら、「最新の試行が勝つ」が正しいルールかもしれません。そのルールはコードで明示し、どちらの場合も負けた結果は保持してください。
結果がテーブルへの書き込み以外の副作用、たとえばメール、チケット、支払いを引き起こすなら、同じ考え方を副作用の側に移します。そのケースは、当ブログのツールのタイムアウトと再試行の冪等性に関する記事で扱っています。
ランブック向けの要約
- アップロード前に論理 ID と試行単位の
custom_idを記録し、作成時にバッチ ID が返ってきたらそれを追加する。 - どの終端ステータスでも、バッチを取得し、それが指すすべてのファイルをすぐにダウンロードする。ファイルのデフォルトの有効期限は30日で、最短1時間に設定できる。
- 行の位置ではなく、1つのバッチに限定した
custom_idで結合する。 - 状態は証拠から決める: usable、needs_review、expired、failed、conflict、unresolved。2xx はリクエストの状態であって使える結果ではなく、バッチのステータスは行の状態ではない。
- expired の行は再試行し、その他の失敗は内容を読んでから再試行し、
needs_reviewの行は理由に応じて判断し、unresolved の行については何かを決める前に証拠を修復する。 - 結果ストアを論理項目で一意にし、検証済みの結果だけを書き込む。そうすれば、避けられなかった再試行があっても、すでにある結果を壊さずに済む。
原文(英語): An expired OpenAI batch is not an empty batch: reconcile each row before retrying
