［開発者向け］Google Gemini API、Structured Outputsを強化：Pydantic/Zodのネイティブ対応とプロパティ順序保証を実現

2025-11-06

はじめに

　Googleは2025年11月5日、Gemini APIにおけるStructured Outputs(構造化出力)の機能強化を発表しました。JSON Schemaのサポート拡大とプロパティ順序の保証により、PythonのPydanticやJavaScript/TypeScriptのZodといったライブラリがそのまま使える環境が整いました。本稿では、この発表内容をもとに、機能強化の詳細と実用上の意義について解説します。

参考記事

メイン記事:

タイトル: Improving Structured Outputs in the Gemini API
著者: Gemini API Team
発行元: Google Blog
発行日: 2025年11月5日
URL: https://blog.google/technology/developers/gemini-api-structured-outputs/

要点

Gemini APIのStructured Outputsに、JSON Schemaの包括的なサポートが追加され、PydanticやZodなどのライブラリがそのまま利用可能になった
anyOf(条件分岐構造)、$ref(再帰的スキーマ)、minimum/maximum(数値制約)、additionalProperties、prefixItems(タプル型配列)などの頻繁に要求されていたJSON Schema機能が新たにサポートされた
Gemini 2.5以降のモデルでは、スキーマ内のキーの順序を保持した出力が暗黙的に保証されるようになり、OpenAI互換APIでも同様の動作が適用される
Agentic UsersやAlkimi AIなどの早期アクセスパートナーは、データ抽出ワークフローでAPI呼び出しを最大6倍削減し、JSONの破損エラーを完全に排除したと報告している

詳細解説

Structured Outputsとは何か

　Googleによれば、Structured OutputsはAIモデルが指定されたJSON Schemaに厳密に準拠した応答を生成する機能です。この機能により、予測可能で解析可能な結果が保証され、形式と型の安全性が確保されます。

　この技術は、構造化されていないテキストから特定の情報を抽出する「データ抽出」、テキストを事前定義されたカテゴリに分類する「構造化分類」、他のツールやAPIを呼び出すための構造化データを生成する「エージェントワークフロー」など、幅広い用途で有効とされています。エージェント間の通信においては、あるエージェントの出力が別のエージェントのフォーマットされた入力となるため、翻訳レイヤーなしで複雑なマルチエージェントシステムの連携が可能になります。

JSON Schemaサポートの拡大

　今回のアップデートでは、Googleのすべてのアクティブサポート対象Geminiモデルに対して、JSON Schemaのサポートが追加されました。これにより、PythonのPydanticやJavaScript/TypeScriptのZodといったスキーマ定義ライブラリが、Gemini APIとそのまま連携できるようになります。

　新たにサポートされたJSON Schemaのキーワードには、以下のようなものがあります:

anyOf: 条件分岐構造(Union型)のサポート
$ref: 再帰的なスキーマ定義
minimum/maximum: 数値の範囲制約
additionalProperties: オブジェクトの追加プロパティ制御
type: ‘null’: null値の明示的な許可
prefixItems: タプル型配列のサポート

　これらの機能は、従来のOpenAPI 3.0ベースのSchemaオブジェクトに加えて利用できます。anyOfは複数の型を許容する柔軟な構造定義に、$refは階層的なデータ構造の表現に有用です。

プロパティ順序の暗黙的な保証

　Googleの発表によれば、APIはスキーマ内のキーの順序と同じ順序を保持するようになりました。この機能はGemini 2.5以降のすべてのモデルでサポートされ、OpenAI互換APIにも適用されます。

　APIドキュメントで示されているコンテンツモデレーションの例では、Pydanticを使用してSpamDetails(スパム詳細)とNotSpamDetails(非スパム詳細)をUnion型で定義し、ModerationResult(モデレーション結果)として出力させています。この際、スキーマで定義された順序通りにプロパティが出力されることが保証されます。

class SpamDetails(BaseModel):
    """Details for content classified as spam."""
    reason: str = Field(description="The reason why the content is considered spam.")
    spam_type: Literal["phishing", "scam", "unsolicited promotion", "other"]

class NotSpamDetails(BaseModel):
    """Details for content classified as not spam."""
    summary: str = Field(description="A brief summary of the content.")
    is_safe: bool

class ModerationResult(BaseModel):
    """The result of content moderation."""
    decision: Union[SpamDetails, NotSpamDetails]

　プロパティ順序の保証は、出力結果の一貫性を高め、パースロジックの簡素化につながると考えられます。

実用事例:早期アクセスパートナーの活用例

　Googleによれば、早期アクセスパートナーがこの機能を実際のワークフローで活用し、顕著な効果を上げています。

　Agentic Usersは、ウェブ向けの自律エージェントプラットフォームを運営しており、ブランドガイドラインに関連する属性を画像やテキストの例から抽出するデータ抽出において、最も大きなインパクトとコスト削減を実現したと報告しています。同社の創業者兼CEOのLuis Vega氏によれば、一部のワークフローでAPI呼び出しが最大6倍削減され、以前は追加の検証チェックが必要だったJSONの破損応答が完全に排除されたとのことです。

　Alkimi AIは、企業や教育機関向けに知識に基づいたAIアシスタントを構築しており、JSON Schemaを使用して複数段階のLLMパイプライン内で保証されたスキーマを通じてデータを確実に渡しています。創業者のDillon Uzar氏は、「Structured Outputsは信頼性、速度、コスト効率のすべてに関わります。LLMに予測可能で機械可読な形式を強制することで、より堅牢な機能をより速く構築でき、エラーを減らし、そうでなければより高価なモデルが必要なタスクにより安価なモデルを使用できます」と述べています。

サポート対象モデルと技術仕様

　APIドキュメントによれば、以下のモデルがStructured Outputsをサポートしています:

Gemini 2.5 Pro
Gemini 2.5 Flash
Gemini 2.5 Flash-Lite
Gemini 2.0 Flash
Gemini 2.0 Flash-Lite

　なお、Gemini 2.0系モデルでは、JSON入力内に明示的なpropertyOrderingリストを定義して優先する構造を指定する必要があります。

　サポートされるJSON Schemaの型には、string(テキスト)、number(浮動小数点数)、integer(整数)、boolean(真偽値)、object(構造化データ)、array(リスト)、null(null値の許可)が含まれます。また、title(プロパティの短い説明)やdescription(詳細な説明)といった記述的プロパティを使用してモデルをガイドできます。

Structured OutputsとFunction Callingの違い

　APIドキュメントでは、両者の用途の違いが明確に示されています。Structured Outputsは「ユーザーへの最終応答をフォーマットする」ために使用され、モデルの回答を特定の形式にする場合(例:文書からデータを抽出してデータベースに保存)に適しています。

　一方、Function Callingは「会話中にアクションを実行する」ために使用され、モデルが最終回答を提供する前にタスクの実行を要求する場合(例:「現在の天気を取得する」)に適しています。この区別により、開発者は目的に応じて適切な機能を選択できます。

ベストプラクティスと制限事項

　APIドキュメントでは、効果的な利用のためのベストプラクティスとして、以下が推奨されています:

明確な説明: スキーマのdescriptionフィールドを使用して、各プロパティが何を表すかを明確に説明する
強い型付け: 可能な限り具体的な型(integer、string、enum)を使用する
プロンプトエンジニアリング: プロンプトでモデルに何をしてほしいかを明確に述べる
検証: 構文的に正確なJSONは保証されるが、値が意味的に正確であることは保証されないため、アプリケーションコードで最終出力を検証する

　制限事項としては、JSON Schema仕様のすべての機能がサポートされているわけではないこと、非常に大きいまたは深くネストされたスキーマはAPIに拒否される可能性があることが挙げられています。エラーが発生した場合は、プロパティ名の短縮化、ネストの削減、制約の数の制限などによってスキーマを簡素化することが推奨されています。

まとめ

　Gemini APIのStructured Outputs強化により、JSON Schemaの包括的なサポートとプロパティ順序の保証が実現されました。PydanticやZodなどの主要ライブラリとのネイティブ連携が可能になり、開発者はより堅牢なAIアプリケーションを構築できるようになります。早期アクセスパートナーの事例からは、API呼び出しの大幅な削減とエラーの排除という具体的な成果が報告されており、実用性の高さがうかがえます。