0
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

【備忘録】Gemini APIのStructured OutputをColabで試す - JSON出力をPydanticで受け取る

0
Last updated at Posted at 2026-08-01

はじめに

Gemini APIをアプリケーションやデータ処理に組み込むとき、自由文の回答をそのまま扱うよりも、JSONのような決まった形で受け取れると後処理がしやすくなります。

Google AI for Developersの公式ドキュメントでは、Gemini APIの Structured outputs として、モデルの応答をJSON Schemaに沿った形式で生成する方法が案内されています。PythonではPydanticのモデルからJSON Schemaを作り、Gemini APIへ渡す書き方ができます。

この記事では、Google Colab上で google-genai を使い、Gemini APIの出力をJSONとして受け取り、Pydanticで検証するところまでを小さく整理します。

※本記事は2026-08-02時点で確認した公式情報をもとにした個人の整理メモです。Gemini APIのSDK、モデル名、料金、利用条件は変更される可能性があります。

この記事でやること

fig_01_overview.png

この記事では、次の流れを扱います。

  1. ColabでGemini APIを使う準備をする
  2. response_format でJSON出力を指定する
  3. PydanticモデルからJSON Schemaを作る
  4. 応答JSONをPydanticで検証する
  5. 使うときの注意点を整理する

なお、ここでは最小構成を確認するため、複雑なRAGや外部ツール連携は扱いません。

前提

fig_02_prerequisites.png

  • Google Colabを使う
  • Gemini APIキーを取得済み
  • Python SDKとして google-genai を使う
  • APIキーはコードに直接書かず、Colab Secretsから読み込む

Colab Secretsを使う場合、左側メニューの「鍵」アイコンから、たとえば GEMINI_API_KEY という名前でAPIキーを登録しておきます。

1. SDKをインストールする

fig_03_install.png

Colabのセルで、まずSDKをインストールします。

%pip install -U -q "google-genai>=2.9.0" pydantic

Google Gemini CookbookのJSON Mode Quickstartでは、Interactions API向けの例として google-genai>=2.9.0 が使われています。

2. APIキーを読み込んでクライアントを作る

fig_04_client_setup.png

APIキーは記事やノートブックに直接書かず、Colab Secretsから読み込みます。

from google.colab import userdata
from google import genai

GEMINI_API_KEY = userdata.get("GEMINI_API_KEY")
client = genai.Client(api_key=GEMINI_API_KEY)

公開記事にする場合、APIキー、組織ID、社内データなどが出力やスクリーンショットに含まれていないか確認しておくと安全です。

3. まずはJSONとして返す指定をする

fig_05_json_minimal.png

Structured Outputを本格的に使う前に、まずは「JSONだけを返してほしい」と指定する最小例を確認します。

import json

MODEL_ID = "gemini-3.6-flash"

prompt = """
次のJSONスキーマに沿って、架空の社内勉強会テーマを3件作ってください。

StudyTopic = {'title': str, 'target_reader': str}
Return: list[StudyTopic]
"""

interaction = client.interactions.create(
    model=MODEL_ID,
    input=prompt,
    response_format={"type": "text", "mime_type": "application/json"},
)

text = interaction.steps[-1].content[0].text
items = json.loads(text)
print(json.dumps(items, ensure_ascii=False, indent=2))

ポイントは response_format={"type": "text", "mime_type": "application/json"} の部分です。

これにより、Markdownのコードブロックや説明文を混ぜず、JSONとして扱いやすい形で返すことを期待できます。

ただし、この段階では「どのフィールドを必ず含めるか」「値の型をどうするか」といった厳密な指定は弱いです。そこで次に、PydanticモデルからJSON Schemaを作って渡します。

image.png

4. Pydanticでスキーマを定義する

fig_06_pydantic_schema.png

ここでは、勉強会テーマを表す小さなモデルを作ります。

from pydantic import BaseModel, Field
from typing import List

class StudyTopic(BaseModel):
    title: str = Field(description="勉強会テーマのタイトル")
    target_reader: str = Field(description="想定読者")
    learning_points: List[str] = Field(description="読者が学べること")

BaseModel を使うと、Python側で扱うデータ構造を先に定義できます。

さらに、Pydanticの model_json_schema() を使うと、このモデルからJSON Schemaを生成できます。

import json

print(json.dumps(StudyTopic.model_json_schema(), ensure_ascii=False, indent=2))

スキーマをコードから生成できるため、手書きのJSON SchemaとPython側の型定義がずれるリスクを減らしやすくなります。

ここで確認している StudyTopic.model_json_schema() は、単一の StudyTopic オブジェクト用のスキーマです。今回のように「3件のテーマをリストで受け取りたい」場合は、次の節でリスト用のスキーマを作って渡します。

5. リスト用のスキーマをGemini APIに渡す

fig_07_list_schema.png

次に、Pydanticモデルから作ったJSON Schemaを response_format に渡します。

ここでは「勉強会テーマを3件」返してほしいため、応答全体は StudyTopic の単一オブジェクトではなく、list[StudyTopic] になる想定です。そのため、StudyTopic.model_json_schema() をそのまま渡すのではなく、Pydanticの TypeAdapter からリスト用のJSON Schemaを作ります。

from typing import List
from pydantic import TypeAdapter

TopicsAdapter = TypeAdapter(List[StudyTopic])

prompt = """
Python初心者向けに、Gemini APIを学ぶための社内勉強会テーマを3件提案してください。
各テーマには、タイトル、想定読者、学べることを含めてください。
"""

result = client.interactions.create(
    model=MODEL_ID,
    input=prompt,
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": TopicsAdapter.json_schema(),
    },
)

raw_json = result.steps[-1].content[0].text
print(raw_json)

ポイントは、期待する出力全体の形に合わせてスキーマを作ることです。

  • 1件だけ返すなら StudyTopic.model_json_schema()
  • 複数件のリストで返すなら TypeAdapter(List[StudyTopic]).json_schema()

公式サンプルでも、response_format の schema にPydanticから生成したJSON Schemaを渡す例が示されています。また、Interactions APIの応答からテキストを取り出す方法として interaction.steps[-1].content[0].text が使われています。

image.png

6. Pydanticで検証してPythonオブジェクトとして扱う

fig_08_validate.png

JSON文字列をそのまま使うのではなく、Pydanticで検証してから扱うと、後続処理でのエラーに気づきやすくなります。

topics = TopicsAdapter.validate_json(raw_json)

for topic in topics:
    print(f"# {topic.title}")
    print(f"想定読者: {topic.target_reader}")
    print("学べること:")
    for point in topic.learning_points:
        print(f"- {point}")
    print()

このようにしておくと、以降の処理では topic.title や topic.learning_points のように、Pythonオブジェクトとして扱えます。

image.png

7. DataFrameに変換して確認する

fig_09_dataframe.png

Colabで試す場合は、最後に pandas.DataFrame にして眺めると、出力結果を確認しやすいです。

import pandas as pd

df = pd.DataFrame([topic.model_dump() for topic in topics])
df

learning_points のようなリスト項目はセル内に配列として入ります。CSVなどに出す場合は、用途に合わせて文字列へ変換するか、別テーブルとして扱うとよさそうです。

Structured Outputを使うと何がうれしいか

fig_10_use_cases.png

個人的には、Structured Outputは「LLMの回答をアプリケーションで扱いやすい形に寄せるための仕組み」と捉えると理解しやすいです。

たとえば、次のような場面で便利です。

  • 問い合わせ文から項目を抽出する
  • 文章をカテゴリ分類する
  • 回答結果をDataFrameやDBに入れる
  • 次のAPI呼び出しに渡す入力を作る
  • UI表示用のデータ構造を作る

自由文のままでは、後処理のたびに正規表現や文字列分割に頼りがちです。最初からJSONとして受け取れると、処理の見通しがよくなります。

注意点

fig_11_cautions.png

1. 生成結果は必ず検証する

Structured Outputを指定していても、実運用ではPython側での検証を入れておくのが安全です。

Pydanticで validate_json() することで、期待した型や必須項目から外れた場合に気づきやすくなります。

特に、単一オブジェクトを期待しているのか、リストを期待しているのかは、スキーマ作成時点で合わせておく必要があります。スキーマと検証側の型がずれていると、生成結果が正しくてもPython側で扱いにくくなります。

2. スキーマは小さく始める

最初から複雑なネスト構造や多数のフィールドを要求すると、プロンプトも後処理も読みにくくなります。

まずは、次のような小さい構造から試すのがよさそうです。

class SimpleItem(BaseModel):
    title: str
    summary: str

その後、必要に応じてフィールドやネストを増やすと整理しやすいです。

3. モデル名やSDKの書き方は変わる可能性がある

Gemini APIは更新が速いため、記事を公開する前に次の点を再確認しておく必要があります。

  • 公式ドキュメント上の推奨API
  • SDKのバージョン
  • 利用するモデル名
  • Structured Outputの対応状況
  • 料金、レート制限、利用可能リージョン

特に、古い記事では generate_content 系のサンプルが多く見つかる可能性があります。この記事では、2026-08-02時点の公式ドキュメントで案内されているInteractions API側の書き方に寄せています。

まとめ

fig_12_summary.png

この記事では、Google Colab上でGemini APIのStructured Outputを試す流れを整理しました。

  • response_format でJSON出力を指定できる
  • Pydanticモデルや TypeAdapter からJSON Schemaを生成できる
  • Gemini APIの応答をPydanticで検証してから扱える
  • DataFrame化するとColab上で結果を確認しやすい
  • 公開前には、SDK、モデル名、提供条件を公式情報で再確認する

LLMの出力を「読むための文章」ではなく「後処理しやすいデータ」として扱いたい場合、Structured Outputは最初に試しておきたい機能だと感じました。

参考(公式情報)

0
1
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
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?