PydanticAI ビジュアルガイド

Lesson CH05-L02

Thinking (Gemini 3)

thinking_levelを切り替え、推論ステップの深さを制御する。

読了目安
10 min
Colab目安
15 min
合計
25 min
前提
WebSearch

関連: 公式ドキュメント

一行サマリ

GoogleModelSettings(google_thinking_config={'thinking_level': 'high'}) を Agent に渡すと、Gemini 3 が 回答前に多段階の推論ステップ を内部で踏むようになる。難問の正答率が上がる代わりに トークン使用量・レイテンシが増える トレードオフ。

ヒーロー: thinking_level の効き目

Gemini 3 系には 「考える深さ」を切り替えるノブ があります。デフォルトの軽い思考から、複雑な数学/コード/論理問題に向けた 深い思考モード へ、1 設定で切り替えられます。

図を読み込み中…
図1. thinking_level: low と high の応答プロセス

概念: いつ thinking を上げるべきか

thinking_level は 'low' (デフォルト) と 'high' の 2 段階。

問題タイプ推奨
一般的な質問・要約・翻訳'low' (デフォルト)
多段階の数学・論理パズル'high'
プログラミング (アルゴリズム設計・バグの根本原因解析)'high'
ライブ応答が必要なチャット (体感速度優先)'low'
ビジネスロジックの設計判断'high'

コスト・レイテンシは数倍になりうる ため、用途で切り分けることが大事です。

注: Gemini 2.5 系には別の名称 thinking_budget (token 数指定) があります。Gemini 3 から thinking_level (low/high の 2 段階) に整理されました。本ガイドはデフォルトの gemini-3-flash-preview を使うため、以降 thinking_level を主に扱います。

コード: 3 つのパターン

パターン 1: 1 つの Agent を thinking high で動かす

from pydantic_ai import Agent
from pydantic_ai.models.google import GoogleModel, GoogleModelSettings
 
model = GoogleModel('gemini-3-flash-preview')
high_settings = GoogleModelSettings(
    google_thinking_config={'thinking_level': 'high'}
)
 
agent_high = Agent(
    model,
    model_settings=high_settings,
    instructions='論理問題を慎重に解いてください。',
)
 
result = agent_high.run_sync(
    'A は B より背が高い。B は C より低い。C は A より背が高い。'
    'この矛盾の有無を分析してください。'
)
print(result.output)

ポイント:

  • GoogleModel(...) を明示的に作る + model_settings に GoogleModelSettings を渡す
  • 'low' / 'high' の 2 段階で制御
  • 同じ Agent から複数 run しても settings は共通

パターン 2: low と high の応答時間を比較

import time
from pydantic_ai import Agent
from pydantic_ai.models.google import GoogleModel, GoogleModelSettings
 
model = GoogleModel('gemini-3-flash-preview')
 
agent_low = Agent(model, model_settings=GoogleModelSettings(
    google_thinking_config={'thinking_level': 'low'}
))
agent_high = Agent(model, model_settings=GoogleModelSettings(
    google_thinking_config={'thinking_level': 'high'}
))
 
prompt = '7 桁の素数を 3 つ挙げてください。それぞれが素数であることを簡潔に検証してください。'
 
t0 = time.time()
r_low = agent_low.run_sync(prompt)
t_low = time.time() - t0
 
t0 = time.time()
r_high = agent_high.run_sync(prompt)
t_high = time.time() - t0
 
print(f'low : {t_low:.1f}s, usage={r_low.usage()}')
print(f'high: {t_high:.1f}s, usage={r_high.usage()}')

体感的には high のほうが応答時間とトークン消費が伸びる ことが分かります。難問で精度が必要な場面でだけ high を選ぶのがコストパフォーマンスに優しい戦略。

パターン 3: 同じ Agent インスタンスで run ごとに切り替える

model_settings は agent.run(...) の引数でも渡せる ので、run ごとに上書きできます。

from pydantic_ai.models.google import GoogleModelSettings
 
agent = Agent('google-gla:gemini-3-flash-preview', instructions='短く日本語で。')
 
# 通常はデフォルト (low)
print(agent.run_sync('1 + 1 は?').output)
 
# 難しい問いだけ high で
high = GoogleModelSettings(google_thinking_config={'thinking_level': 'high'})
print(agent.run_sync(
    '次の式を満たす整数 (x, y, z) を全て挙げてください: x^2 + y^2 = z^2 (1 ≤ x ≤ y ≤ 10)。',
    model_settings=high,
).output)

run 単位で settings を分離できると、リクエストの重要度に応じて動的に thinking を切り替える 実装が楽になります。

図を読み込み中…
図2. thinking_level 切替の判断フロー

観察: usage で thinking のコストを測る

result.usage() で 実際に消費したトークン が分かります。high のほうが大きい数値になるはずです。

print(r_low.usage())
# RunUsage(requests=1, input_tokens=..., output_tokens=...)
print(r_high.usage())
# RunUsage(requests=1, input_tokens=..., output_tokens=...)  ← high のほうが大きい

本番運用ではこの数値を Logfire (Ch9) で時系列に観測し、コスト最適化の判断材料にします。

まとめ

  • GoogleModelSettings(google_thinking_config={'thinking_level': 'high'}) で深い推論モードに
  • 'low' (デフォルト) と 'high' の 2 段階。コスト・レイテンシとトレードオフ
  • agent.run_sync(..., model_settings=...) で run ごとに上書き可能
  • result.usage() で実消費トークンを観察

次レッスンでは Safety Settings — Gemini の安全フィルタを用途別に調整するパターンを扱います。

Colab で実際に動かす

本レッスンの内容を Google Colab 上で実行できるノートブックを用意しています。下のボタンから自分のColab環境に開けます (要 Google アカウント / GOOGLE_API_KEY)。

Open in Colab

notebooks/ch05/02-thinking.ipynb