Batch API — 大量処理を安く回す

これは何か

Batch API（バッチ推論、Batch Inference）とは、急がない大量のリクエストをまとめて投げ、非同期（asynchronous、送信してから結果が返るまでの間に他の処理を進められる方式）に処理してもらう仕組みである。第 5 章で見た Serverless 推論が「リクエストを送ったらすぐ応答が返る」ことを前提にしていたのに対し、Batch API は「結果は後でまとめて受け取ればよい」という前提に立つ。その見返りとして、標準の Serverless 単価より安い料金で処理してもらえる。

投入経路は 3 つある。コンソール（app.fireworks.ai）にはBatch Inference タブがあり、公式ガイドは「Batch Inference タブに移動し、Create Batch Inference Job をクリックする」という手順を示している。ここでモデルとデータセットをドロップダウンで選んでジョブを作成できる。CLI からは firectl の batch-inference-job 系サブコマンドを使う。プログラムから制御したいときは REST API（https://api.fireworks.ai/v1/accounts/{account_id}/batchInferenceJobs）を直接叩く。どの経路でも、投入するデータはJSONL（JSON Lines、1 行が 1 つの完結した JSON オブジェクトになっているテキスト形式）で用意したデータセットという単位にまとめる必要がある。データセットの作成自体はfirectl dataset createや dataset タブなど、Batch とは別の仕組みで行う。

いつ使うのか

Batch API が向くユースケースとして、公式ガイドは次の 4 つを挙げている。

• データラベリング・合成データ生成 — 大量のデータにラベルや教師データを付ける
• 大きいモデルで小さいモデルを蒸留するための学習データ生成 — distillation（蒸留、大きいモデルの出力を小さいモデルの学習データにする手法）向けのデータ作り
• 大規模な評価・ベンチマーク — 多数のテストケースをまとめて評価する
• 文書処理など — 大量ドキュメントの要約・抽出・分類

いずれも「今すぐ 1 件だけ答えが欲しい」のではなく「まとまった量を、多少待ってもよいから安く処理したい」という場面である。隣接する第 5 章の Serverless 推論、第 9 章の On-demand Deployments との使い分けは次のとおり。

特に、Batch 対応かどうかは投入前に必ず確認する必要がある。対応モデルは「Model Library 上で On-demand Deployments に対応しているベースモデル、またはそのベースモデル上に構築したカスタムモデル」であり、新しく追加されたモデルは対応が遅れることもある、と公式ドキュメントは注意している。

仕組み（1）— ジョブのライフサイクルと有効期限

Batch ジョブを投入すると、ガイドページが示す主要な状態を次の順にたどる。

まず検証中（VALIDATING）でデータセットの形式をチェックし、待機中（PENDING）でリソースが確保されるのを待ち、実行中（RUNNING）で実際に推論が行われ、すべて処理し終えると完了（COMPLETED）になる。回復不能なエラーが起きれば失敗（FAILED）、後述の有効期限に達すれば期限切れ（EXPIRED）という扱いになるが、期限切れでも完了済みのリクエストの結果は失われず出力データセットに保存されている。

実行中はさらに、容量の再取得のために一時的に止まることがある（waitingOnCapacity）。これはジョブが一度 RUNNING になった後、プリエンプション（他の優先度の高い処理に一時的に GPU を明け渡すこと）や GPU 不足で内部的な待機フェーズへ戻り、再開を待っている状態を指す。公式 API の説明では、ジョブの state 自体は RUNNING のまま変わらず、このあいだ進捗は保存されていて自動的に再開する、とされている。コンソール上では「Briefly paused — waiting on capacity」という表示になる。

また、ここで示した 6 つの状態はガイドページが解説用に挙げている主要な状態にすぎない。API（gatewayJobState）が実際に返しうる値は JOB_STATE_WRITING_RESULTS や JOB_STATE_RE_QUEUEING なども含む合計 20 種類（2026-09 時点）あり、ジョブの状態をポーリング（一定間隔で状態を問い合わせて変化を待つこと）する実装を書くときはこの主要 6 状態だけを想定してはいけない。

ジョブの有効期限（実行ウィンドウ）は、コンソールやガイドの説明では 12・24・48・72 時間から選べるとされ、既定値は 24 時間である。API 側の maxJobDuration フィールドで見ると、サーバがこの値を 12 時間〜72 時間の範囲にクランプ（切り詰め）し、未設定なら既定 24 時間になる、というのが実装上の正確な挙動である。期限を過ぎるとジョブは EXPIRED になるが、それまでに完了した行の結果は課金対象になり出力データセットに保存される。なお、レスポンスに含まれる expireTime（実際の期限日時）はサーバが create_time + 実行ウィンドウ から計算して返す値で、クライアント側から指定しても無視される。期限を変えたいときは maxJobDuration の方を設定する。

期限切れなどで未完了のリクエストが残った場合は、--continue-from で元のジョブを指定すると、未完了・失敗した行だけを対象に新しいジョブとして再実行できる。継続チェーン全体の出力をまとめてダウンロードしたいときは firectl dataset download <dataset-id> --download-lineage を使う。

仕組み（2）— JSONL フォーマットとジョブレベル system prompt

Batch ジョブへの入力は、1 行が 1 リクエストに対応する JSONL ファイルで用意する。各行には一意な custom_id と、リクエストパラメータをまとめた body という 2 つのフィールドが必須で、入力データセットの上限は 80 GiB である。

{"custom_id": "request-1", "body": {"messages": [{"role": "user", "content": "日本の首都はどこですか？"}], "max_tokens": 50}}
{"custom_id": "request-2", "body": {"messages": [{"role": "user", "content": "量子コンピュータを一言で説明してください"}], "max_tokens": 50}}
{"custom_id": "request-3", "body": {"messages": [{"role": "user", "content": "冗談を一つ言ってください"}], "max_tokens": 50}}

body の中身は、標準の messages 形式か、事前にトークン化済みの prompt_token_ids 形式のどちらかを使う。この 2 つは排他で、同じ行に両方を入れることはできない。prompt_token_ids は独自のトークナイザ（文字列をトークン ID 列に変換する処理）やレンダラ（トークン列をモデル入力の形式に整形する処理）で作った入力をそのままモデルに渡したいときに使う上級者向けの経路で、通常は messages 形式で十分である。

各行にまったく同じ system メッセージを繰り返し書く代わりに、ジョブ全体に対して 1 つだけジョブレベルの system promptを設定できる。

公式ドキュメントの説明では、ジョブレベルの system prompt は「まだ system メッセージで始まっていない行」だけに、先頭の system メッセージとして注入される。行自身が先頭に system メッセージを持っていれば、その行の指定が常に優先される。すべての行が同じ大きな system prompt を共有している場合、これを行ごとに書く代わりにジョブレベルへ切り出すことで、アップロードするデータセットを小さくでき、しかも注入されるプレフィックスは全行でバイト同一になるので、後述するプロンプトキャッシュも効き続ける。

ジョブが終わると、出力データセットには結果ファイル（成功したレスポンスの JSONL）とエラーファイル（失敗したリクエストのデバッグ情報）の 2 つが入る。どちらも入力行と対応付けて読む前提のファイルだが、出力行の具体的なスキーマは公式ドキュメントに記載がない。公式は追跡用途に意味のある custom_id を付けることを推奨している。REST API からダウンロードする場合は、出力データセットに対して署名付き URL（一定時間だけ有効な、認証情報なしでダウンロードできる URL）のマップを取得してから、個別にファイルを取りに行くという 2 段構えになる（後述のハンズオンで使う firectl dataset download は、この 2 段階を 1 コマンドにまとめている）。

サイズの上限は入力と出力で単位そのものが違う。入力データセットは最大 80 GiB、出力データセットは最大 8 GB（いずれも 2026-09 時点）で、公式ドキュメントの原文でもこの 2 つの単位は揃えられていない。出力側は上限に達するとジョブが早期に expire することがあるので、1 行あたりの max_tokens を無闇に大きくしすぎないことが、有効期限だけでなく出力サイズの面でも効いてくる。

仕組み（3）— 割引とリアルタイム推論の対比

Batch API の割引は 2 段階で重なる。まず、標準の Serverless 単価（第 5 章）に対して入力・出力とも 50% オフになる（Serverless Pricing の原文は「Batch inference is billed at 50% of serverless pricing on both input and output」と明記している）。さらに、Batch ジョブは自動的にプロンプトキャッシュ（同じ内容のプロンプト冒頭をキャッシュし、再利用分の課金を抑える仕組み。詳しくは第 7 章）を使うため、キャッシュにヒットしたトークン分にはさらに追加で 50% の節約が乗る、と公式ガイドは説明している。キャッシュのヒット率を上げるコツは、プロンプトの中で変わらない部分（指示文やスキーマなど）を先頭にまとめて置くことである。ジョブの進捗（jobProgress）には cachedInputTokenCount というフィールドがあり、実際にどれだけのトークンがキャッシュにヒットしたかを実測できる。

この図が示すとおり、Serverless は個々のリクエストがすぐに終わる代わりに標準単価がかかり、Batch は投入後しばらく待つ代わりに安くなる。「待てるかどうか」が両者を選ぶ最初の判断軸になる。

ハンズオン — Batch ジョブを実際に動かす

ここでは公式ガイドの最小構成に沿って、まず firectl でジョブを一通り動かし、次に REST API でジョブレベル system prompt を試す。

{"custom_id": "request-1", "body": {"messages": [{"role": "user", "content": "日本の首都はどこですか？"}], "max_tokens": 50}}
{"custom_id": "request-2", "body": {"messages": [{"role": "user", "content": "量子コンピュータを一言で説明してください"}], "max_tokens": 50}}
{"custom_id": "request-3", "body": {"messages": [{"role": "user", "content": "冗談を一つ言ってください"}], "max_tokens": 50}}

firectl dataset create batch-input-dataset ./batch_input_data.jsonl

firectl batch-inference-job create \
  --job-id ch08-handson-job \
  --model accounts/fireworks/models/gpt-oss-120b \
  --input-dataset-id batch-input-dataset \
  --output-dataset-id batch-output-dataset \
  --max-tokens 50 \
  --temperature 0.7

firectl batch-inference-job get ch08-handson-job

firectl dataset download batch-output-dataset

export ACCOUNT_ID=<your-account-id>

curl -X POST "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/batchInferenceJobs?batchInferenceJobId=ch08-handson-job-2" \
  -H "Authorization: Bearer ${FIREWORKS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "accounts/fireworks/models/gpt-oss-120b",
    "inputDatasetId": "accounts/'${ACCOUNT_ID}'/datasets/batch-input-dataset",
    "outputDatasetId": "accounts/'${ACCOUNT_ID}'/datasets/batch-output-dataset-2",
    "systemPrompt": "あなたは日本語で簡潔に答えるアシスタントです。",
    "inferenceParameters": { "maxTokens": 50 }
  }'

curl -s -X GET "https://api.fireworks.ai/v1/accounts/${ACCOUNT_ID}/batchInferenceJobs/ch08-handson-job-2" \
  -H "Authorization: Bearer ${FIREWORKS_API_KEY}" \
  | python3 -m json.tool

つまずきポイント

理解度チェック

まとめ

• Batch API は急がない大量リクエストをまとめて非同期処理し、標準 Serverless 単価の 50% オフに加え、キャッシュヒット分の追加割引を受けられる仕組みである
• ジョブは検証中→待機中→実行中→完了という主要な状態遷移をたどり、有効期限は既定 24 時間・最大 72 時間で、API はより細かい合計 20 状態を返す
• 投入経路はコンソールの Batch Inference タブ・firectl・REST API の 3 つがあり、いずれも custom_id と body を持つ JSONL データセットを介する
• 非対応モデルへの投入・コンテキスト超過・キャッシュキー未設定は、いずれもエラーを出さずに静かに失敗するため、事前確認と jobProgress の実測が欠かせない

次章では、Batch と同じく JSONL や API を使う場面もあるが、専有 GPU 上でモデルを動かす On-demand Deployments を見ていく。

参考リンク

• Batch API ガイド
• API リファレンス: Create Batch Inference Job
• API リファレンス: Get Batch Inference Job
• API リファレンス: List Batch Inference Jobs
• firectl batch-inference-job create
• firectl batch-inference-job get
• Serverless Pricing
• Inference Error Codes