📖 概要
このプロジェクトは、Qwen2.5-0.5B-Instructモデルを使用して、大規模言語モデル（LLM）の内部動作を詳細に理解するための教育用ツールです。Chat Templateの適用、トークナイゼーション、テキスト生成の各ステップでの中間データを詳細にログ出力し、LLMの仕組みを可視化します。
Github
🎯 主な目的
- LLMの内部動作の理解: トークナイゼーションからテキスト生成までの全プロセスを可視化
- Chat Templateの学習: Hugging Face TransformersのChat Template機能の理解
- デバッグと分析: 生成過程の詳細なログ出力による問題の特定と分析
- 教育目的: LLMの仕組みを学ぶための実践的な例
✨ 主な機能
🔍 詳細なログ出力
- モデル・トークナイザー情報: 語彙サイズ、特殊トークンID、デバイス情報
- 入力メッセージ: システムメッセージとユーザーメッセージの構造
- Chat Template適用: プロンプトの変換過程と最終的なテキスト
- トークナイゼーション: テキストからトークンIDへの変換詳細
- 生成設定: 温度、top_p、repetition_penalty等のパラメータ
- 生成結果: 入力+生成の完全な出力と新規生成部分のみ
- トークン分析: 各トークンIDとその文字列表現
🛠️ 技術的特徴
-
認証管理:
.envファイルを使用したHugging Face Hub認証 - エラーハンドリング: 認証失敗時の代替手段（ローカルファイル使用）
- デバイス対応: CPU、GPU、MPS（Apple Silicon）対応
- 依存関係管理: uvを使用したモダンなPython依存関係管理
🚀 クイックスタート
前提条件
- Python 3.13+
- uv (推奨) または pip
- Hugging Face Hubアカウント（モデルダウンロード用）
インストール
- リポジトリのクローン
git clone https://github.com/softjapan/qwen-chattemplate.git
cd qwen-chattemplate
- 依存関係のインストール
uv sync
# または
pip install -e .
- Hugging Face Hub認証
# 方法1: CLIでログイン
uv run huggingface-cli login
# 方法2: .envファイルにトークンを設定
cp .env.sample .env
# .envファイルを編集してHF_TOKENを設定
実行
uv run qwen-06b.py
📁 プロジェクト構造
qwen-chattemplate/
├── .env.sample # 環境変数設定サンプルファイル
├── .gitignore # Git除外設定
├── pyproject.toml # プロジェクト設定と依存関係
├── qwen-06b.py # メインスクリプト
├── README.md # このファイル
└── uv.lock # 依存関係ロックファイル
🔧 設定
環境変数
.env.sampleファイルをコピーして.envファイルを作成し、以下の設定が可能です：
# Hugging Face Hub認証トークン
HF_TOKEN=your_huggingface_token_here
# その他の設定（オプション）
# CUDA_VISIBLE_DEVICES=0
# TRANSFORMERS_CACHE=/path/to/cache
モデル設定
qwen-06b.py内で以下の設定を変更できます：
# 使用するモデル（0.6B相当モデルに変更可能）
model_name = "Qwen/Qwen2.5-0.5B-Instruct"
# 生成パラメータ
gen_kwargs = dict(
max_new_tokens=256, # 最大生成トークン数
temperature=0.7, # 温度（創造性の制御）
top_p=0.9, # Top-pサンプリング
repetition_penalty=1.05, # 繰り返しペナルティ
do_sample=True, # サンプリング有効
eos_token_id=tokenizer.eos_token_id
)
📊 出力例
実行すると以下のような詳細なログが出力されます：
=== モデル・トークナイザー情報 ===
モデル名: Qwen/Qwen2.5-0.5B-Instruct
モデルのデバイス: mps:0
モデルのデータ型: torch.float16
トークナイザーの語彙サイズ: 151643
EOS トークンID: 151645
PAD トークンID: 151643
=== 1. 入力メッセージ ===
メッセージ 1: {'role': 'system', 'content': 'You are a helpful assistant that responds in Japanese.'}
メッセージ 2: {'role': 'user', 'content': '富士山を紹介してください。'}
=== 2. Chat Template適用後のプロンプト ===
プロンプト長: 147 文字
プロンプト内容:
--------------------------------------------------
<|im_start|>system
You are a helpful assistant that responds in Japanese.<|im_end|>
<|im_start|>user
富士山を紹介してください。<|im_end|>
<|im_start|>assistant
--------------------------------------------------
=== 3. トークナイズ結果 ===
入力テンソルの形状: torch.Size([1, 32])
入力トークン数: 32
デバイス: mps:0
データ型: torch.int64
=== 4. トークンIDの詳細 ===
トークンID数: 32
最初の20個のトークンID: [151644, 8948, 198, 2610, 525, 264, 10950, 17847, 429, 30580, 304, 10769, 13, 151645, 198, 151644, 872, 198, 99415, 99253]
=== 5. トークンIDから文字列への変換 ===
トークン 0: ID=151644, 文字='<|im_start|>'
トークン 1: ID=8948, 文字='system'
トークン 2: ID=198, 文字='
'
...
🧠 LLMの仕組み理解
1. Chat Template
- 目的: 複数のメッセージを適切な形式に変換
-
例:
<|im_start|>system\n...<|im_end|>形式 - 重要性: モデルが理解できる構造化されたプロンプト
2. トークナイゼーション
- プロセス: テキスト → トークンID配列
- 語彙サイズ: 151,643個のトークン
-
特殊トークン:
<|im_start|>,<|im_end|>, EOS等
3. テキスト生成
- 入力: トークンID配列
- 出力: 新しいトークンID配列
- パラメータ: 温度、top_p、repetition_penalty
4. デコード
- プロセス: トークンID配列 → テキスト
- 結果: 人間が読める形式の回答
🔍 技術的詳細
依存関係
- torch: PyTorchフレームワーク
- transformers: Hugging Face Transformersライブラリ
- python-dotenv: 環境変数管理
- huggingface_hub: Hugging Face Hub連携
- accelerate: モデル最適化
デバイス対応
- CPU: 標準的なCPU実行
- CUDA: NVIDIA GPU対応
- MPS: Apple Silicon GPU対応
エラーハンドリング
- 認証エラー: ローカルファイル使用への自動フォールバック
- モデル読み込みエラー: 詳細なエラーメッセージと解決策提示
- デバイスエラー: 利用可能なデバイスへの自動調整
🤝 貢献
このプロジェクトへの貢献を歓迎します！
貢献方法
- フォークしてブランチを作成
- 変更をコミット
- プルリクエストを作成
貢献できる分野
- ログ出力の改善
- 新しいモデルのサポート
- ドキュメントの改善
- バグ修正
📝 ライセンス
このプロジェクトはMITライセンスの下で公開されています。詳細はLICENSEファイルを参照してください。
🙏 謝辞
- Qwen Team - Qwenモデルの開発
- Hugging Face - TransformersライブラリとHub
- PyTorch Team - PyTorchフレームワーク
📞 サポート
問題や質問がある場合は、Issuesで報告してください。
🔗 関連リンク
注意: このプロジェクトは教育目的で作成されています。商用利用の際は、各ライブラリのライセンス条項を確認してください。
Github