📖この記事は約10分で読めます
1. ローカルLLM開発者のリアルな落とし穴
ローカルでLLMを微調整していると、HuggingFaceにモデルをアップロードして、さらに追加学習をしようとした際に「なぜか初期モデルに戻っている！」という謎の現象に遭遇する。筆者もUnslothでDPO/SFT学習を実施し、v3モデルをベースにv4の追加学習を計画していたが、なぜかv2モデルが読み込まれて混乱した。
この問題の原因は、マージ済みモデルに意図せずにadapter_config.jsonが混入していること。LoRAアダプタとマージ済みモデルを同じフォルダに保存すると、アップロード時にこの設定ファイルが混入し、モデルのルーティングを狂わせる。
本記事では、Qwen3-4Bをベースにしたv0→v2→v3→v4の学習チェーンで発生したトラブルを例に、技術的な仕組みから回避策までを掘り下げて解説する。
特に「マージ済みモデルなのになぜかベースモデルが古い」というパラドックスに直面した読者には、必須の知識となる。
2. LoRAマージの技術的仕組みと混入問題
LoRA（Low-Rank Adaptation）は、ベースモデルの重みを凍結したまま、小さな差分行列（アダプタ）を学習する手法。merge_and_unload()でアダプタをベースモデルに焼き込み、フルモデルに変換する。
しかし、adapter_config.jsonという設定ファイルが混入すると、マージ済みモデルの「base_model_name_or_path」が意図せずに古いバージョン（例: v2）を指すようになる。このメタデータがモデルロード時に優先され、v3ではなくv2がベースとして扱われる。
具体的には、v3モデルを保存する際、trainer.save_model()とmerge_and_unload()を同じフォルダで実行すると、不要なadapter_config.jsonが残る。このファイルがHuggingFaceのモデルロードロジックに干渉し、学習チェーンの破綻を引き起こす。
筆者の場合、v3モデルをアップロードしたはずが、v4学習時にログ上でv3が読み込まれているように見えたが、実際はv2がベースモデルとして動作していた。
3. 実際のモデルチェーンと発生した問題
意図した学習チェーンは「v0（ベース）→SFT→v2→DPO→v3→DPO→v4」。しかし実際には「v0→SFT→v2→DPO→v3（v2がベース）→D1PO→v4（v2がベース）」と、v2が2度使われていた。
v3モデルはv2をベースにDPO学習済みだが、adapter_config.jsonが混入することで、v4学習時にv2が再び読み込まれた。結果として、v3の学習効果が完全に無視され、不要な計算リソースが消費された。
この問題の発見には、model.safetensors.index.jsonのbase_layerキーの数をチェックする必要があった。0ならマージ済み、正の数ならLoRAアダプタが存在する。
さらに、model.config.name_or_pathでロードされたモデルを確認したところ、v4学習時にもかかわらず「v2」が表示されていた。この矛盾に気づくのが難しいのが最大の落とし穴だ。
4. デメリットと技術的限界
この問題の最大のデメリットは「意図した学習効果が得られない」こと。v3モデルのDPOによる改善が完全に無視され、v4の性能はv2と同等に退化する。
また、ログ上では正常に見えるため、デバッグに時間がかかる。特に分散学習環境では、この不具合が原因で複数のGPUクラスタが無駄に稼働する。
技術的な限界として、HuggingFaceのモデルロードロジックはadapter_config.jsonを優先する設計になっている。これはLoRAアダプタを活用する場合に便利だが、マージ済みモデルでは逆効果となる。
さらに、merge_and_unload()で生成されるファイル構成が複雑で、誤ってアダプタ設定を残してしまう可能性が高い。これは特に初心者に注意が必要な点だ。
5. 実践的な回避策と検証方法
筆者が実際に試した解決策は、LoRAアダプタとマージ済みモデルを「完全に別のフォルダに分ける」こと。これにより、adapter_config.jsonの混入を防ぐ。
具体的には、v3モデルを保存する際、merge_and_unload()の出力先を「merged_models/v3」、LoRAアダプタを「lora_adapters/v3」に分ける。アップロード時はマージ済みモデルフォルダのみを送信する。
検証方法として、model.safetensors.index.jsonのbase_layerキーをチェックする。0ならマージ済み、正の数ならアダプタが存在する。また、model.config.name_or_pathがv3を指しているかを確認する。
さらに、コード上ではtrainer.save_model()とmerge_and_unload()を同じスクリプト内で実行しないようにする。別々のスクリプトで処理を分けることで、ファイル構成の混乱を防げる。
6. 将来のモデル管理の方向性
この問題は、LoRAアダプタとマージ済みモデルの管理方法の重要性を浮き彫りにしている。今後は、HuggingFaceがモデルロード時の優先順位を明確化する必要がある。
また、UnslothやTrainerの設定で、adapter_config.jsonの生成をオプション化する機能が望まれる。ユーザーが「このモデルはマージ済みなのでアダプタは不要」と明示できるようになると理想的だ。
さらに、モデルのバージョン管理ツールが登場する可能性もあり、v0→v2→v3→v4のチェーンを可視化できるようになれば、こうした問題は大幅に減少する。
ローカルLLM開発者は、このような技術的限界を理解し、プロセスの標準化を進めることが重要。筆者も今後は、マージ済みモデルとアダプタを物理的に分離する習慣を定着させる。
実際の活用シーン
企業内でのモデル開発プロセスにおいて、複数のチームが異なるタスク向けにLLMを微調整するケースが挙げられる。例えば、マーケティングチームが顧客分析用モデル（v2）を構築した後、リスク管理チームがそのモデルをベースに金融リスク評価用にDPO学習を実施（v3）する場面がある。しかし、v3の保存時にadapter_config.jsonが混入すると、次のチームがv4学習を実施する際、意図せずにv2がベースモデルとして読み込まれる。これは、企業のAI戦略における継続的学習プロセスを阻害し、業務効率の低下につながる。
研究機関でのモデル再現性確保にも影響を及ぼす。研究者は論文提出に際して、v3モデルの学習プロセスを完全に再現する必要があるが、adapter_config.jsonの混入により、公開されたモデルがv2ベースであることに気づかず、再現結果の信頼性が損なわれる。特に国際的な共同研究では、こうした技術的落とし穴が研究の進展を妨げる。
プロダクション環境におけるモデルデプロイでも問題が発生する。A/Bテスト中にv3モデルをサーバーに配置したはずが、adapter_config.jsonの影響でv2が実行され、顧客体験に深刻な支障が出る可能性がある。これは特に、医療分野や金融サービスのような高リスク領域で致命的となる。
他の選択肢との比較
LoRAアダプタ方式と対照的なFull Fine-Tuningでは、ベースモデルの重みそのものを更新するため、adapter_config.jsonのような設定ファイルの混入問題は発生しない。ただし、Full Fine-Tuningは計算リソースが大きく必要で、モデルのバージョン管理も複雑になる。LoRAの長所は軽量なアダプタで複数モデルを管理できる点だが、その代償としてこの設定ファイルの混入リスクが存在する。
PEFT（Parameter-Efficient Fine-Tuning）ツール群の中には、LoRAと同様のアプローチを採用しているものがあるが、HuggingFace Transformersとの統合度が異なる。例えば、HuggingFace PEFTライブラリでは、アダプタの保存・読み込みプロセスがLoRAより明確に分離されているが、merge_and_unload()の処理においても同様の注意が必要である。
また、Weights & BiasesやDVCなどのモデル管理ツールは、バージョン管理を強化しているが、LoRAアダプタとマージ済みモデルの区別を自動で行う機能はまだ整備されていない。これは今後のモデル管理ツールの進化方向として重要である。
導入時の注意点とベストプラクティス
最初の注意点は、ファイル構成の明確化である。筆者が推奨する「merged_models/」と「lora_adapters/」の分離構造を維持するためには、プロジェクトの初期段階でディレクトリ構造の設計規則を策定する必要がある。これは特に、複数開発者が協働するプロジェクトにおいて重要である。
第二に、自動検証プロセスの導入が効果的である。CI/CDパイプラインに「adapter_config.jsonが存在する場合にビルドを失敗させる」ルールを組み込むことで、誤ったモデルのアップロードを未然に防げる。Pythonスクリプトで「ls merged_models/v3 | grep adapter_config.json」のようなチェックを実行する方法も有効である。
第三に、ドキュメントの標準化が重要となる。モデルバージョンごとに「このモデルはマージ済みである」「LoRAアダプタは別途存在する」などのメタ情報をREADME.mdに記載する習慣をつけることで、後続の開発者が間違ったモデルを読み込まないようにする。HuggingFaceのモデルカード機能を活用して、この情報を公開するのも効果的である。
今後の展望と発展の可能性
今後のHuggingFaceエコシステムの進化において、モデルロードロジックの明確化が求められる。例えば、merge_and_unload()の実行時に自動でadapter_config.jsonを削除するオプションの追加や、モデルロード時の優先度をユーザーがカスタマイズできるインターフェースの提供が期待される。このような改善により、LoRAアダプタとマージ済みモデルの区別がより明確になる。
さらに、モデル管理ツールの進化がこの問題の解消に寄与する可能性がある。今後、Gitベースのバージョン管理に特化したツールが、LoRAアダプタとマージ済みモデルの履歴を可視化する機能を搭載する可能性が高い。これは、特に継続的学習（Continual Learning）を実施するプロジェクトにおいて、極めて有益な機能となる。
最後に、コミュニティ主導のベストプラクティスの標準化が進むと予測される。現時点で非公式ながら広がりつつある「マージ済みモデルとアダプタを分離する習慣」が、将来的にはHuggingFace公式ドキュメントに明記されるような形で定着していく可能性が高い。
コメント