list_gemini_models.py 技術ドキュメント

プログラムの動作

list_gemini_models.py は、Google Gemini API を利用して、現在利用可能なモデルの一覧を取得し、特にコンテンツ生成 (generateContent) メソッドをサポートしているモデルのIDを標準出力に表示するPythonプログラムです。

このプログラムの主な機能は以下の通りです。

  1. APIキーの読み込み: プログラムと同じディレクトリに配置された ai.env ファイルから GOOGLE_API_KEY 環境変数を読み込みます。

  2. API設定: 読み込んだAPIキーを使用して、Google Generative AI ライブラリを設定します。

  3. モデル一覧の取得とフィルタリング: Google Gemini API に問い合わせ、利用可能な全てのモデルのリストを取得します。その中から、generateContent メソッドに対応しているモデルのみを抽出し、そのモデルID (models/gemini-pro など) を表示します。

  4. エラーハンドリング: APIキーが設定されていない場合、無効なAPIキーが指定された場合、または権限エラーが発生した場合など、APIとの通信中に発生しうる様々なエラーを検出し、ユーザーに分かりやすいエラーメッセージと解決策のヒントを提供します。

  5. 終了ステータス: 処理が正常に完了した場合は終了コード0を、エラーが発生した場合は終了コード1を返します。

このプログラムは、開発者がGoogle Gemini APIでどのモデルがコンテンツ生成に利用可能であるかを迅速に確認し、アプリケーション開発の際に適切なモデルを選択できるようにすることを目的としています。

原理

list_gemini_models.py は、以下の原理に基づいて動作します。

  1. APIキーの取得と環境設定: プログラムは tkai_lib.read_ai_config("ai.env") を呼び出すことで、指定された ai.env ファイルの内容を環境変数としてロードします。その後、os.getenv("GOOGLE_API_KEY") を使用して GOOGLE_API_KEY を取得します。 このAPIキーは、Google Gemini APIへの認証に使用されます。

  2. Google Generative AI ライブラリの設定: 取得したAPIキーは genai.configure(api_key=api_key) 関数に渡され、google.generativeai ライブラリがGoogle Gemini APIへのリクエストを行う際に、このキーが認証情報として自動的に付加されるように設定されます。

  3. 利用可能モデルの列挙: genai.list_models() メソッドが呼び出されると、Google Gemini APIのエンドポイントに対し、現在利用可能な全てのモデルに関する情報を取得するリクエストが送信されます。APIは、各モデルの名前、サポートされる生成メソッド、入力トークン数、出力トークン数などの詳細情報を含むオブジェクトのイテレータを返します。

  4. コンテンツ生成モデルのフィルタリング: プログラムは genai.list_models() から返される各モデルオブジェクトを繰り返し処理します。各モデルオブジェクトには supported_generation_methods という属性があり、これはそのモデルがサポートする操作（例: 'generateContent', 'embedContent'）のリストです。プログラムは、このリストに 'generateContent' が含まれているかどうかをチェックし、コンテンツ生成機能をサポートするモデルのみを識別します。

  5. エラーハンドリング: API通信や設定の過程で発生しうる例外は try-except ブロックで捕捉されます。特に、例外メッセージのテキスト内容を分析することで、APIキーの無効性 (api_key_invalid, invalid api key) や権限の不足 (permissiondenied, 403) といった具体的なエラーの種類を特定し、ユーザーに適切な診断情報を提供します。

このプログラムは特定の数式や物理式を使用せず、主にAPIとの対話とデータ構造のフィルタリングに基づいています。

必要な非標準ライブラリとインストール方法

list_gemini_models.py を実行するには、以下の非標準ライブラリが必要です。

  1. google-generativeai

    • 説明: Google Gemini APIと対話するための公式Pythonライブラリです。

    • インストール方法: pip コマンドを使用してインストールします。

      pip install google-generativeai

  2. tkai_lib

    • 説明: ai.env ファイルから環境変数を読み込むためのカスタムライブラリです。プログラム内で read_ai_config 関数が使用されています。

    • インストール方法: このライブラリは、このプロジェクト固有のカスタムライブラリである可能性が高いため、標準的な pip install では入手できない場合があります。このライブラリは、ユーザーの環境に存在するか、別途提供される必要があります。

必要な入力ファイル

プログラムは、Google Gemini API キーを読み込むために、以下のファイルを必要とします。

  • ファイル名: ai.env

  • 場所: プログラム list_gemini_models.py と同じディレクトリに配置する必要があります。

  • ファイル形式: シンプルなテキストファイルで、GOOGLE_API_KEY 環境変数を定義する行を含んでいる必要があります。

    GOOGLE_API_KEY=YOUR_GEMINI_API_KEY_HERE

    • YOUR_GEMINI_API_KEY_HERE の部分には、Google AI Studio で取得した有効な Gemini API キーを記述してください。このキーがない場合、または無効な場合、プログラムはエラーで終了します。

生成される出力ファイル

list_gemini_models.py は、いかなるファイルも生成しません。 全ての実行結果（利用可能なモデルID、処理状況メッセージ、エラーメッセージなど）は、標準出力（コンソール）に直接表示されます。

コマンドラインでの使用例 (Usage)

list_gemini_models.py プログラムは、コマンドライン引数を必要としません。 必要なAPIキーは ai.env ファイルから自動的に読み込まれます。

基本的な実行コマンドは以下の通りです。

python list_gemini_models.py

コマンドラインでの具体的な使用例

事前準備

プログラムを実行する前に、Google AI Studio で Gemini API キーを取得し、そのキーを格納した ai.env ファイルを list_gemini_models.py と同じディレクトリに作成する必要があります。

ai.env ファイルの例:

GOOGLE_API_KEY=AIzaSyCXXXXXXXXXXXXXXXXXXXXX

(上記の AIzaSyCXXXXXXXXXXXXXXXXXXXXX は、実際に取得したAPIキーに置き換えてください。)

成功例

ai.env ファイルが正しく設定され、有効なAPIキーが提供されている場合の実行例です。

コマンド:

python list_gemini_models.py

実行結果:

--- Gemini (Google AI) 利用可能モデル確認 ---
ai.env を読み込みます...
GOOGLE_API_KEY exists = True
API を設定中...
--- 利用可能なモデル一覧を取得します ---
ID: models/gemini-pro
ID: models/gemini-pro-vision
--- 完了: 2 件 ---

(出力されるモデルのIDや数は、APIの最新の状況や、ご利用のGoogleアカウントのアクセス権によって異なる場合があります。)

APIキーが設定されていない場合のエラー例

ai.env ファイルが存在しない、または GOOGLE_API_KEY が ai.env ファイル内に設定されていない場合の実行例です。

コマンド:

python list_gemini_models.py

実行結果:

--- Gemini (Google AI) 利用可能モデル確認 ---
ai.env を読み込みます...
GOOGLE_API_KEY exists = False
ERROR: GOOGLE_API_KEY が設定されていません
       ai.env の内容、または read_ai_config() を確認してください

無効なAPIキーの場合のエラー例

ai.env ファイルは存在するものの、記述されたAPIキーが無効である場合の実行例です。

コマンド:

python list_gemini_models.py

実行結果:

--- Gemini (Google AI) 利用可能モデル確認 ---
ai.env を読み込みます...
GOOGLE_API_KEY exists = True
API を設定中...
--- 利用可能なモデル一覧を取得します ---
ERROR: Google API の認証に失敗しました
       API KEY が無効か、設定が間違っている可能性があります
       Google AI Studio で新しいキーを確認し、ai.env を更新してください