0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

OpenAI Batch の expired は空のバッチではない: 再試行の前に行ごとに突き合わせる

0
Posted at

この記事は、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.

A stopped filling nozzle over a long rack of jars, most already full of orange liquid, one half full and a few left empty.
イラストは AI で作成しました。

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 などです。どれも見え方は同じで、何も紐づかない行が残ります。

台帳を組み立てる

  1. バッチを取得します。ステータス、errors、output_file_id、error_file_id、request_counts を記録します。
  2. オブジェクトが指すファイルをすべてダウンロードし、何かをパースする前に生のバイト列を保存します。ファイルは期限切れになり、その後は生のコピーだけが証拠になります。
  3. この batch_id のマニフェストだけを読み込みます。複数の試行が混ざったマニフェストは、古い結果を新しい行に対応づけてしまいます。
  4. 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

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?