`list_models.py` の技術ドキュメント

プログラムの動作

list_models.py は、LiteLLM ライブラリを利用して、OpenAI および Google AI (Gemini) の大規模言語モデル (LLM) に対する操作を支援する Python スクリプトです。このプログラムは主に以下の二つの機能を提供します。

利用可能モデルの一覧表示: 指定されたプロバイダー (OpenAI、Gemini、または両方) が現在提供している LLM のモデル名を一覧表示します。これにより、どのモデルが利用可能であるかを簡単に確認できます。
モデル応答テスト: 指定された LLM モデルに対して、ユーザーが設定したプロンプトを送信し、その応答をコンソールに表示します。これは、API接続が正しく機能しているか、または特定のモデルが期待通りに応答するかを検証する際に役立ちます。

このプログラムは、APIキーの設定ファイル (ai.env など) または環境変数から API キーを読み込み、それを使用して各プロバイダーのサービスにアクセスします。

原理

list_models.py は、LiteLLM ライブラリを核として動作します。LiteLLM は、様々な LLM プロバイダーの API を統一されたインターフェースで扱うことを可能にする軽量なライブラリです。

API キーの読み込み:
- プログラムはまず、tkai_lib_litellm または tkai_lib というカスタムライブラリが存在するかをチェックします。これらのライブラリが存在する場合、read_ai_config() 関数を使用して、指定された設定ファイル (デフォルトは ai.env) から環境変数として API キーを読み込みます。
- これらのライブラリが見つからない場合でも、既存の環境変数 (OPENAI_API_KEY, GOOGLE_API_KEY, GEMINI_API_KEY) を使用して動作します。
- 特に、GOOGLE_API_KEY が設定されており GEMINI_API_KEY が未設定の場合、GOOGLE_API_KEY の値を GEMINI_API_KEY として自動的に設定し、Gemini モデルへのアクセスを容易にします。
モデル一覧の取得:
- mode=list が指定された場合、LiteLLM の get_valid_models() 関数が使用されます。この関数は、check_provider_endpoint=True および custom_llm_provider 引数を通じて、指定されたプロバイダー (例: "openai", "gemini") の API エンドポイントに実際に問い合わせを行い、利用可能なモデル ID のリストを取得します。
- 取得されたモデル ID はソートされて表示されます。
モデル応答のテスト:
- mode=test が指定された場合、まず normalize_model_name() 関数によって、ユーザーが入力したモデル名 (例: gpt-4o-mini, gemini-2.0-flash, openai/gpt-4o-mini) からプロバイダーと LiteLLM が認識する正規化されたモデル名 (openai/gpt-4o-mini, gemini/gemini-2.0-flash など) を判定します。
- 次に、LiteLLM の completion() 関数を呼び出します。この関数は、プロバイダーと正規化されたモデル名、およびユーザーからのプロンプトを含むメッセージリストを受け取り、LLM にリクエストを送信します。
- LLM からの応答オブジェクトは extract_response_text() 関数によって解析され、応答本文（response.choices[0].message.content）が抽出され、コンソールに表示されます。

これらの処理により、ユーザーは LiteLLM を介して簡単に異なる LLM プロバイダーのモデルを管理・テストできます。

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

このプログラムは、以下の非標準ライブラリに依存しています。

litellm: 複数の LLM プロバイダー API を統一的に扱うためのライブラリ。
tkai_lib_litellm または tkai_lib: プログラムで API キーなどの設定ファイルを読み込むために使用される、オプションのカスタムライブラリです。これらがインストールされていない場合でも、環境変数から API キーを読み込むことでプログラムは動作します。

これらのライブラリは pip コマンドでインストールできます。

pip install litellm
# tkai_lib_litellm または tkai_lib は、プロジェクト固有のライブラリであるため、
# 通常は別途提供されるか、リポジトリからインストールします。
# 例: pip install tkai_lib_litellm
# tkai_lib_litellm がない場合は、以下を試します (もし提供されていれば)。
# pip install tkai_lib

必要な入力ファイル

このプログラムは、API キーを管理するために設定ファイルを読み込むことができます。

API キー設定ファイル (デフォルト: ai.env)
- ファイル名: --config オプションで指定されたファイル名 (デフォルトは ai.env)
- 形式: 環境変数形式のキーと値のペア。各行が KEY=VALUE の形式である必要があります。
- 内容例:
```
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
GOOGLE_API_KEY=AIzaSyB-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
- 注意: このファイルに機密情報である API キーを直接記述する場合、ファイルのアクセス権限を適切に設定し、セキュリティに十分注意してください。API キーは環境変数として直接設定することも可能です。

生成される出力ファイル

このプログラムは、いかなるファイルも生成しません。すべての出力は標準出力 (stdout) または標準エラー出力 (stderr) に表示されます。

標準出力:
- mode=list の場合: 各プロバイダーの利用可能モデルの一覧。
- mode=test の場合: モデル名、プロンプト、およびモデルからの応答。
標準エラー出力:
- 警告メッセージ (例: tkai_lib が見つからない場合)。
- エラーメッセージ (例: API キーが未設定、モデル一覧取得失敗、モデル応答失敗など)。

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

list_models.py を実行する際の基本的なコマンドラインオプションは以下の通りです。

python list_models.py [--mode {list,test}] [--api {all,openai,gemini}] [--model MODEL] [--prompt PROMPT] [--config CONFIG]

--mode {list,test}:
- list: 利用可能なモデル一覧を表示します。(既定値)
- test: 指定したモデルにプロンプトを送信し、応答をテストします。
--api {all,openai,gemini}:
- list モードで対象とするプロバイダーを選択します。(既定値: all)
--model MODEL:
- test モードで使用するモデル名を指定します。
- 例: gpt-4o-mini, gemini-2.0-flash, openai/gpt-4o-mini
--prompt PROMPT:
- test モードでモデルに送信するプロンプトを指定します。
- 既定値: "これはAPI接続テストです。日本語で、あなたのモデル名を名乗らずに、『接続テストに成功しました』と短く回答してください。"
--config CONFIG:
- API キー設定ファイルのパスを指定します。(既定値: ai.env)

また、mode=list のような key=value 形式の引数もサポートしています。これは内部で argparse の --key value 形式に変換されます。

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

ここでは、list_models.py の具体的な使用例と、それぞれの実行結果の概要を示します。

利用可能な全プロバイダーのモデル一覧を表示する
- コマンド:
```
python list_models.py
# または
python list_models.py mode=list
# または
python list_models.py --mode list --api all
```
- 実行結果の説明: 設定されている API キーに応じて、OpenAI および Gemini (Google AI) の利用可能なモデルが、それぞれセクションに分けて一覧表示されます。API キーが設定されていないプロバイダーについては、スキップされた旨のメッセージが表示されます。
特定のプロバイダー (OpenAI) のモデル一覧を表示する
- コマンド:
```
python list_models.py mode=list api=openai
# または
python list_models.py --mode list --api openai
```
- 実行結果の説明: OpenAI の利用可能なモデルのみが一覧表示されます。OpenAI の API キー (OPENAI_API_KEY) が設定されていない場合は、エラーメッセージが表示されます。
特定のプロバイダー (Gemini) のモデル一覧を表示する
- コマンド:
```
python list_models.py mode=list api=gemini
# または
python list_models.py --mode list --api gemini
```
- 実行結果の説明: Gemini (Google AI) の利用可能なモデルのみが一覧表示されます。Gemini の API キー (GEMINI_API_KEY または GOOGLE_API_KEY) が設定されていない場合は、エラーメッセージが表示されます。
OpenAI の gpt-4o-mini モデルに対する応答テスト
- コマンド:
```
python list_models.py mode=test model=gpt-4o-mini
# または
python list_models.py --mode test --model openai/gpt-4o-mini
```
- 実行結果の説明: gpt-4o-mini モデルに対し、デフォルトのプロンプトでリクエストが送信され、その応答がコンソールに表示されます。API キーが未設定の場合や、モデル名が不正な場合、または接続エラーが発生した場合は、エラーメッセージが表示されます。
Gemini の gemini-2.0-flash モデルに対し、カスタムプロンプトで応答テスト
- コマンド:
```
python list_models.py mode=test model=gemini-2.0-flash prompt="こんにちは、あなたの得意なことは何ですか？"
# または
python list_models.py --mode test --model gemini/gemini-2.0-flash --prompt "こんにちは、あなたの得意なことは何ですか？"
```
- 実行結果の説明: gemini-2.0-flash モデルに対し、指定されたカスタムプロンプトでリクエストが送信され、その応答がコンソールに表示されます。API キーや接続に関する問題が発生した場合は、エラーメッセージが表示されます。
カスタム設定ファイル (my_ai_keys.env) を使用してモデル一覧を表示する
- コマンド:
```
python list_models.py --mode list --config my_ai_keys.env
```
- 実行結果の説明: my_ai_keys.env ファイルから API キーを読み込み、それを使用して全プロバイダーのモデル一覧を取得・表示します。

list_models.py の技術ドキュメント