【重要】Gemini API Python SDK移行ガイド：google-generativeaiから新SDKへ
Googleの強力な生成AIモデルであるGeminiをPythonで活用している開発者の皆さん、こんにちは！
これまで多くのプロジェクトで利用されてきた google-generativeai ライブラリのサポートが、2025年8月をもって終了することが決定しました。これに伴い、新しい google-genai ライブラリへの移行が強く推奨されています。
この移行は単なるライブラリの置き換えにとどまりません。特に、最新のGeminiモデル（例: Gemini 2.0、2.5系）が持つ全機能、そしてこの記事で特に注目するGoogle検索によるグラウンディング機能を利用するためには、新しいSDKへの対応が不可欠となります。
この記事では、google-generativeai から google-genai への移行をスムーズに行うための主要なポイントと、Google検索グラウンディング機能を有効にするための具体的なコード変更について、SWELLテーマの装飾を交えながら分かりやすく解説します。
なぜ今、新しいSDKへの移行が必要なのか？
まずは、なぜこのタイミングでSDKの移行が求められているのか、その理由を明確にしておきましょう。
- サポート終了: 最も直接的な理由として、旧SDK
google-generativeaiが2025年8月にサポートを終了することが挙げられます。サポート終了後も利用は可能かもしれませんが、新たなバグ修正やセキュリティアップデートは提供されなくなるため、継続的な利用は非推奨です。 - 新機能への完全対応: 新しい
google-genaiライブラリは、進化し続けるGeminiモデルファミリーに最適化されています。Gemini 2.0や2.5といった最新モデルはもちろん、今後登場するであろうVeo（動画生成）やImagen（画像生成）といった新しいマルチモーダル機能、そしてGoogle検索グラウンディングのような高度なツール連携機能も、新SDKでなければ十分に活用できません。 - APIの統一性:
google-genaiSDKは、Gemini Developer APIとGoogle CloudのVertex AI上で提供されるGemini APIの両方をサポートするように設計されています。これにより、利用する環境に関わらず、より統一されたインターフェースでGeminiモデルを扱えるようになります。
これらの理由から、Gemini APIを継続的かつ最大限に活用していくためには、新しい google-genai SDKへの移行は避けて通れません。
移行ステップ 1: SDKのインストールとインポート方法の変更
移行の最初のステップは、使用するライブラリそのものを変更することです。インストールコマンドとPythonコード内のインポート文が変わります。
変更点は以下の通りです。
| 項目 | 変更前 (`google-generativeai`) | 変更後 (`google.genai`) |
|---|---|---|
| パッケージ名 | `google-generativeai` | `google-genai` |
| インストールコマンド | “`bash pip install -U google-generativeai “` |
“`bash pip install -U google-genai “` |
| 主要なインポート文 | “`python import google.generativeai as genai from google.generativeai import types “` |
“`python from google import genai from google.genai import types “` |
ポイント:
- インストールするパッケージ名が
google-generativeaiからgoogle-genaiに変わります。 - インポートの方法も変更され、主要なモジュールは
google.genaiのサブモジュールとしてアクセスする形になります。特にtypesはgoogle.generativeai.typesではなくgoogle.genai.typesからインポートする必要がある点に注意してください。
まずはターミナルやコマンドプロンプトで新しいSDKをインストールし、Pythonコードの冒頭部分にあるインポート文を上記の「変更後」に合わせて修正しましょう。
移行ステップ 2: クライアントの初期化方法の変更
SDKのインストールとインポートが完了したら、次にAPIを利用するためのクライアントの初期化方法を変更します。
変更前後の初期化方法を比較してみましょう。
| 項目 | 変更前 (`google-generativeai`) | 変更後 (`google.genai`) |
|---|---|---|
| 初期化の主体 | `genai.configure()` による設定と `genai.GenerativeModel()` でモデルを直接インスタンス化 | `genai.Client()` オブジェクトを作成し、それを通じて操作 |
| APIキー設定 | 主に `genai.configure(api_key=”YOUR_API_KEY”)` | 環境変数 `GOOGLE_API_KEY` (推奨) または `genai.Client(api_key=”YOUR_API_KEY”)` |
| モデルインスタンス化 | `model = genai.GenerativeModel(model_name=”…”)` | `client.models.generate_content(…)` など、クライアントオブジェクト経由でモデルを指定 |
コード例:
変更前 (google-generativeai):
import google.generativeai as genai
genai.configure(api_key="YOUR_API_KEY")
model = genai.GenerativeModel(model_name="gemini-1.5-flash-latest")
# この model オブジェクトを使ってコンテンツ生成などを行っていた
# response = model.generate_content(...)
変更後 (google-genai):
from google import genai
import os
# 環境変数 GOOGLE_API_KEY を設定 (推奨される方法)
# export GOOGLE_API_KEY="YOUR_API_KEY" # ターミナルで実行
# Pythonコード内では、環境変数から自動的に読み込まれる
client = genai.Client()
# または、APIキーを直接渡す場合 (非推奨)
# client = genai.Client(api_key="YOUR_API_KEY")
# この client オブジェクトを使ってコンテンツ生成などを行う
# response = client.models.generate_content(...)
新しいSDKでは、genai.Client() を使って明示的にクライアントオブジェクトを作成するのが標準的な方法です。APIキーは、セキュリティと管理の観点から環境変数 GOOGLE_API_KEY で設定することが強く推奨されます。もしコード内で設定する場合は、クライアント作成時に api_key 引数で渡します。
旧SDKのように GenerativeModel を直接インスタンス化するのではなく、コンテンツ生成などの操作は、この作成した client オブジェクトを通じて行います。
移行ステップ 3: コンテンツ生成とグラウンディング設定の変更
SDK移行の最も重要な部分であり、特にGoogle検索グラウンディング機能を有効にするためのコード変更が集約されているのが、このコンテンツ生成メソッドの呼び出し方です。
変更前後のメソッド呼び出し方と引数の違いを見てみましょう。
| 項目 | 変更前 (`google-generativeai`) | 変更後 (`google.genai`) |
|---|---|---|
| コンテンツ生成メソッド | 主に `model.generate_content()` | `client.models.generate_content()` |
| 設定引数 | `generation_config`, `safety_settings` などが直接引数として渡される | `config` 引数に `types.GenerateContentConfig` オブジェクトを渡す |
| ツールの指定方法 (グラウンディング含む) | `tools` 引数が存在したが、グラウンディングへの対応は限定的か不明確 | `config` 引数で渡す `types.GenerateContentConfig` オブジェクトの `tools` プロパティにリストとして指定 |
| グラウンディングの有効化 | 明確な方法は少なかった | `tools` に `types.Tool(google_search=types.GoogleSearch())` を含めることで有効化 |
コード例 (グラウンディング対応):
from google import genai
from google.genai import types # types は google.genai からインポート！
import os
# APIキーは環境変数から自動的に読み込まれるか、ここで指定
# os.environ['GOOGLE_API_KEY'] = "YOUR_API_KEY" # 非推奨だが例として
client = genai.Client()
# 使用するモデル名を指定 (例: 環境変数や設定ファイルから読み込む)
model_name_from_env = "gemini-2.5-flash-preview-04-17"
# 1. グラウンディングツールの準備
# types.Tool と types.GoogleSearch が利用可能かチェック (SDKバージョン依存)
google_search_tool = None
if hasattr(types, 'Tool') and hasattr(types, 'GoogleSearch'):
google_search_tool = types.Tool(google_search=types.GoogleSearch())
print("GoogleSearchツールが利用可能です。")
else:
print("警告: お使いのSDKバージョンでは types.GoogleSearch がサポートされていません。SDKを更新してください。")
tools_list = [google_search_tool] if google_search_tool else None
# 2. GenerationConfig オブジェクトの作成
# 各種設定 (temperature, tools, safety_settingsなど) は config 引数に集約
generation_config_args = {"temperature": 0.7}
if tools_list:
generation_config_args["tools"] = tools_list
# 必要に応じて他の設定 (例: response_modalities) も追加
# generation_config_args["response_modalities"] = ["TEXT"]
config_obj = types.GenerateContentConfig(**generation_config_args)
# 3. コンテンツ生成の実行
prompt = "2025年の主要なテクノロジートレンドは何ですか？ 最新情報を踏まえて教えてください。"
response = client.models.generate_content(
model=model_name_from_env, # 使用するモデル名を指定
contents=prompt, # プロンプト内容
config=config_obj # ★★★ ここが重要！ config 引数に設定オブジェクトを渡す ★★★
)
# 生成されたテキストの表示
print("--- 生成結果 ---")
print(response.text)
# グラウンディングメタデータの確認 (参照情報源の表示)
print("\n--- グラウンディング情報 ---")
if response.candidates and hasattr(response.candidates[0], 'grounding_metadata'):
metadata = response.candidates[0].grounding_metadata
if metadata and hasattr(metadata, 'search_entry_point') and metadata.search_entry_point:
print("参照された情報源 (HTML):")
print(metadata.search_entry_point.rendered_content) # HTML形式で参照情報が表示される
if metadata and hasattr(metadata, 'web_search_queries') and metadata.web_search_queries:
print("実行された検索クエリ:")
print(metadata.web_search_queries) # 実際に実行された検索クエリが表示される
else:
print("グラウンディング情報は取得できませんでした。")
- コンテンツ生成は、旧SDKのように
model.generate_content()ではなく、client.models.generate_content()を使用します。 - 生成に関する様々な設定（温度、安全性設定、そしてツール）は、
configという単一の引数を通じて渡すtypes.GenerateContentConfigオブジェクトに集約されました。 - Google検索グラウンディングを有効にするには、この
types.GenerateContentConfigオブジェクトのtoolsプロパティに、types.Tool(google_search=types.GoogleSearch())を含むリストを指定します。このtypes.Toolやtypes.GoogleSearchといった新しい型は、google.genai.typesモジュールからインポートする必要があります。これらの型が利用可能になったのは、SDKバージョン1.19.0以降です。もしコード例が動作しない場合は、SDKのバージョンを確認し、必要であれば更新してください。 - 生成結果に含まれるグラウンディング情報は、
response.candidates.grounding_metadataからアクセスできます。ここに含まれるsearch_entry_point.rendered_contentを表示することで、モデルが回答生成時に参照した具体的な情報源（HTML形式）を確認できます。また、web_search_queriesで実際にモデル内部で実行された検索クエリを確認することも可能です。
- **情報の鮮度向上:** 最新の出来事やトレンドに関する質問にも、より正確な情報に基づいた回答が得られます。
- **信頼性の向上:** 参照された情報源を確認できるため、回答の根拠を検証しやすくなります。
- **ハルシネーションの抑制:** 事実に基づいた情報に grounding されることで、モデルが誤った情報を生成するリスクを低減できます。
特に、ニュース性の高いトピックや、常に情報が更新される分野に関するアプリケーションを開発する際には、非常に強力な武器となります。
移行をスムーズに進めるためのアドバイス
SDKの移行は、既存のコードベースに影響を与えるため、慎重に進める必要があります。ここでは、移行作業を円滑に行うためのいくつかのアドバイスを共有します。
- 公式ドキュメントを参照: Googleの公式ドキュメントは常に最新の情報源です。この記事の内容と合わせて、必ず公式ドキュメント（特に移行ガイドやAPIリファレンス）を参照しながら作業を進めてください。
- 段階的な移行: 可能であれば、プロジェクト全体を一度に移行するのではなく、小規模な機能やモジュールから段階的に新しいSDKに置き換えていくことを検討しましょう。
- SDKバージョンの確認: 特にグラウンディング関連の機能は、特定のSDKバージョン以降でサポートされています。もしコード例がうまく動作しない場合は、まずインストールされている
google-genaiのバージョンを確認してください。 - エラーメッセージの確認: 移行中にエラーが発生した場合は、エラーメッセージをよく読み、原因を特定してください。新しいSDKではエラーの種類やメッセージも変更されている可能性があります。
- コミュニティの活用: もし問題に直面したり疑問点がある場合は、Stack Overflowなどの開発者コミュニティで質問したり、既存の回答を検索したりするのも有効です。
まとめ
この記事では、google-generativeai から新しい google-genai Python SDKへの移行が必要な理由と、具体的な移行手順、特にGoogle検索グラウンディング機能を有効にするためのコード変更のポイントを解説しました。
新しい google-genai SDKは、最新のGeminiモデルの全機能を利用するための唯一のパスとなります。特に、リアルタイムの情報に基づいた信頼性の高い回答を可能にするグラウンディング機能は、これからのAIアプリケーション開発において非常に強力な武器となるでしょう。
2025年8月の旧SDKサポート終了に向けて、計画的に新しい google-genai SDKへの移行を進めることを強くお勧めします。この記事が、皆さんの移行作業の一助となれば幸いです。新しいSDKで、Geminiのさらなる可能性を引き出しましょう！
