AI生成のゲームデータをJSONで受け取る｜Structured Outputsと検証

最初に、人が使いたいデータの形を決める

クイズなら問題文、選択肢、正解の位置、解説を別の項目にします。ステージなら幅、高さ、開始地点、出口、障害物を分けます。画面に表示する文章とゲームの進行に使う値を一つの文字列へ詰めると、後から分解する処理が増えます。AIへ依頼する前に、画面と処理が必要とする項目を決めましょう。

OpenAIの公式資料は、Structured Outputsによるスキーマに沿った出力と、JSONとして読めることだけを求める形式を区別しています。対応する形式や設定は採用するモデルの資料を確認します。ここでは特定のSDKの呼び出しを固定せず、ゲーム側で必要な構造と受け取り後の確認を中心に説明します。

初期版の項目は少なくして構いません。使わない説明文や装飾設定まで要求すると、検証する範囲が広がります。たとえば一問のクイズなら、識別子、問題文、三つの選択肢、正解の位置から始められます。項目を増やす際には保存済みのデータをどう扱うかも決め、形式の版番号を残す方法を検討します。

型が合っても、正解や到達可能性は別に調べる

正解の位置が整数であっても、選択肢の数より大きければ使えません。選択肢が三つあっても、同じ文章が二つ並ぶと選びにくい問題になります。文字数、重複、値の範囲、必須の項目を検証します。AIが返した値を、画面が表示できるから正しいと受け入れないようにしましょう。

ステージの検証では、座標が盤面に収まるか、開始地点が障害物と重ならないか、出口へたどり着けるかを調べます。到達可能性は、ゲームの移動ルールを使って確認します。四方向移動の迷路とジャンプできるアクションでは、同じ地図でも意味が違います。使える設定の条件をコード側で定義します。

クイズの内容の正しさは、型の検証だけでは分かりません。公開する知識問題なら、答えと解説に根拠があるかを人が確認する工程が必要です。生成時に出典欄を付けたとしても、そのURLが実在し、説明を支えているかを別に確かめます。自動で作る量を増やす前に、一問を確かめる手順を用意しましょう。

検証関数を、生成処理から独立させる

以下は当ブログが用意した簡略化した検証例です。APIへ送る完全なスキーマではなく、受け取ったクイズをゲーム側で検査する部分を示します。実際の用途では文字数の上限、識別子の重複、表示対象の言語などを追加します。何を検証しているかが読める、小さな関数から始めると見直しやすくなります。

検証を独立させておくと、AIの返答だけでなく保存済みのJSONや手作業のデータにも同じ条件を適用できます。形式を変更したときも、どの条件が変わったかを追えます。失敗したデータをプレイ用の一覧へ混ぜず、確認待ちの場所へ保存するようにすれば、公開前にまとめて見直せます。

失敗理由は、修正に使える形で残します。単に「無効」ではなく、正解の位置が範囲外、選択肢が重複、問題文が長すぎる、と分けます。ただし、利用者が入力した内容などを不用意にログへ残す必要はありません。今回の検証で必要な識別子と理由を、扱うデータの範囲に合わせて記録します。

function validQuiz(q) {
  if (!q || typeof q.question !== "string") return false;
  if (!Array.isArray(q.choices) || q.choices.length !== 3) return false;
  if (!q.choices.every(s => typeof s === "string" && s.trim())) return false;
  if (new Set(q.choices).size !== q.choices.length) return false;
  return Number.isInteger(q.answerIndex)
    && q.answerIndex >= 0 && q.answerIndex < q.choices.length;
}
// 内容の正しさや、文字数の上限は別の確認を追加する。

中断や拒否があっても、ゲームを続けられるようにする

OpenAIの公式資料は、拒否などで想定した構造の結果を受け取れない場合の処理も説明しています。通信の失敗や不完全な結果も含め、正常なデータがあるかを確認してから利用します。画面が読み込みのまま止まらないよう、待ち時間と失敗時の表示をゲームの仕様として決めておきましょう。

小規模なブラウザゲームなら、確認済みの問題を同梱し、AI生成は制作時に行う方法もあります。プレイ中に毎回生成しなくても、生成後に選び直したデータを作品へ追加できます。公開前に内容を確認でき、プレイ時の通信が成立しない場合にも遊びを用意しやすくなります。必要な体験に合わせて方式を選びます。

検証が失敗した際の再生成は、回数を決めます。条件を満たすまで無制限に呼び続けると、処理時間と費用が読みにくくなります。何回まで試すか、失敗後はどの確認済みデータを使うかを決め、同じ条件で検証します。構造化された出力は、検証工程を組み立てやすくするために活用しましょう。