Transformers documentation

How to convert a 🀗 Transformers model to TensorFlow?

You are viewing v4.38.2 version. A newer version v4.46.2 is available.
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

How to convert a 🀗 Transformers model to TensorFlow?

🀗 Transformersを䜿甚するために耇数のフレヌムワヌクが利甚可胜であるこずは、アプリケヌションを蚭蚈する際にそれぞれの匷みを掻かす柔軟性を提䟛したすが、 互換性をモデルごずに远加する必芁があるこずを意味したす。しかし、幞いなこずに 既存のモデルにTensorFlow互換性を远加するこずは、れロから新しいモデルを远加するこずよりも簡単です 倧芏暡なTensorFlowモデルの詳现を理解したり、䞻芁なオヌプン゜ヌスの貢献を行ったり、 遞択したモデルをTensorFlowで有効にするためのガむドです。

このガむドは、コミュニティのメンバヌであるあなたに、TensorFlowモデルの重みおよび/たたは アヌキテクチャを🀗 Transformersで䜿甚するために、Hugging Faceチヌムからの最小限の監芖で貢献できる力を䞎えたす。新しいモデルを曞くこずは小さな偉業ではありたせんが、 このガむドを読むこずで、それがロヌラヌコヌスタヌのようなものから散歩のようなものになるこずを願っおいたす🎢🚶。 このプロセスをたすたす簡単にするために、私たちの共通の経隓を掻甚するこずは非垞に重芁ですので、 このガむドの改善を提案するこずを匷くお勧めしたす

さらに詳しく調べる前に、以䞋のリ゜ヌスをチェックするこずをお勧めしたす。🀗 Transformersが初めおの堎合

このガむドの残りの郚分では、新しいTensorFlowモデルアヌキテクチャを远加するために必芁なもの、 PyTorchをTensorFlowモデルの重みに倉換する手順、およびMLフレヌムワヌク間の䞍䞀臎を効率的にデバッグする方法に぀いお孊びたす。それでは始めたしょう

䜿甚したいモデルに察応するTensorFlowアヌキテクチャがすでに存圚するかどうかわからないですか

 

遞択したモデルのconfig.jsonのmodel_typeフィヌルドをチェックしおみおください 䟋。 🀗 Transformersの該圓するモデルフォルダに、名前が”modeling_tf”で始たるファむルがある堎合、それは察応するTensorFlow アヌキテクチャを持っおいるこずを意味したす䟋。

Step-by-step guide to add TensorFlow model architecture code

倧芏暡なモデルアヌキテクチャを蚭蚈する方法はさたざたであり、その蚭蚈を実装する方法もさたざたです。 しかし、🀗 Transformersの䞀般的な抂芁から 思い出しおいただけるかもしれたせんが、私たちは意芋のあるグルヌプです - 🀗 Transformersの䜿いやすさは䞀貫性のある蚭蚈の遞択肢に䟝存しおいたす。経隓から、TensorFlowモデルを远加する際に重芁なこずをいく぀かお䌝えできたす

  • 車茪を再発明しないでくださいほずんどの堎合、確認すべき少なくずも2぀の参照実装がありたす。それは、 あなたが実装しおいるモデルのPyTorchバヌゞョンず、同じ皮類の問題に察する他のTensorFlowモデルです。
  • 優れたモデル実装は時間の詊緎を乗り越えたす。これは、コヌドがきれいだからではなく、コヌドが明確で、デバッグしやすく、 構築しやすいからです。TensorFlow実装でPyTorch実装ず䞀臎するパタヌンを耇補し、PyTorch実装ずの䞍䞀臎を最小限に抑えるこずで、 あなたの貢献が長期間にわたっお有甚であるこずを保蚌したす。
  • 行き詰たったら助けを求めおください 🀗 Transformersチヌムはここにいたすし、おそらくあなたが盎面しおいる同じ問題に察する解決策を芋぀けおいたす。

TensorFlowモデルアヌキテクチャを远加するために必芁なステップの抂芁は次のずおりです

  1. 倉換したいモデルを遞択
  2. transformersの開発環境を準備
  3. オプション理論的な偎面ず既存の実装を理解
  4. モデルアヌキテクチャを実装
  5. モデルのテストを実装
  6. プルリク゚ストを提出
  7. オプションデモを構築しお䞖界ず共有

1.-3. Prepare your model contribution

1. 倉換したいモデルを遞択する

たず、基本から始めたしょう。最初に知っおおく必芁があるこずは、倉換したいアヌキテクチャです。 特定のアヌキテクチャを決めおいない堎合、🀗 Transformers チヌムに提案を求めるこずは、圱響を最倧限にする玠晎らしい方法です。 チヌムは、TensorFlow サむドで䞍足しおいる最も泚目されるアヌキテクチャに向けおガむドしたす。 TensorFlow で䜿甚したい特定のモデルに、🀗 Transformers に既に TensorFlow アヌキテクチャの実装が存圚しおいるが、重みが䞍足しおいる堎合、 このペヌゞの重みの远加セクションに盎接移動しおください。

簡単にするために、このガむドの残りの郚分では、TensorFlow バヌゞョンの BrandNewBert を貢献するこずを決定したず仮定しおいたす これは、新しいモデルの远加ガむドでの䟋ず同じです。

TensorFlow モデルのアヌキテクチャに取り組む前に、それを行うための進行䞭の取り組みがないかを再確認しおください。 GitHub ペヌゞのプルリク゚ストで BrandNewBert を怜玢しお、 TensorFlow 関連のプルリク゚ストがないこずを確認できたす。

2. transformers 開発環境の準備

モデルアヌキテクチャを遞択したら、意向を瀺すためにドラフト PR を開くための環境を蚭定しおください。 以䞋の手順に埓っお、環境を蚭定し、ドラフト PR を開いおください。

  1. リポゞトリのペヌゞで ‘Fork’ ボタンをクリックしお、リポゞトリをフォヌクしたす。 これにより、コヌドのコピヌが GitHub ナヌザヌアカりントの䞋に䜜成されたす。

  2. ロヌカルディスクにある ‘transformers’ フォヌクをクロヌンし、ベヌスリポゞトリをリモヌトずしお远加したす:

git clone https://github.com/[your Github handle]/transformers.git
cd transformers
git remote add upstream https://github.com/huggingface/transformers.git
  1. 開発環境を蚭定したす。たずえば、以䞋のコマンドを実行しおください
git clone https://github.com/[your Github handle]/transformers.git
cd transformers
git remote add upstream https://github.com/huggingface/transformers.git

䟝存関係が増えおいるため、OSに応じお、Transformersのオプションの䟝存関係の数が増えるかもしれたせん。その堎合は、TensorFlowをむンストヌルしおから次のコマンドを実行しおください。

pip install -e ".[quality]"

泚意: CUDAをむンストヌルする必芁はありたせん。新しいモデルをCPUで動䜜させるこずが十分です。

  1. メむンブランチからわかりやすい名前のブランチを䜜成しおください。
git checkout -b add_tf_brand_new_bert
  1. 珟圚のmainブランチにフェッチしおリベヌスする
git fetch upstream
git rebase upstream/main
  1. transformers/src/models/brandnewbert/にmodeling_tf_brandnewbert.pyずいう名前の空の.pyファむルを远加したす。これはあなたのTensorFlowモデルファむルです。

  2. 以䞋を䜿甚しお倉曎内容をアカりントにプッシュしたす

git add .
git commit -m "initial commit"
git push -u origin add_tf_brand_new_bert
  1. GitHub䞊でフォヌクしたりェブペヌゞに移動し、「プルリク゚スト」をクリックしたす。将来の倉曎に備えお、Hugging Face チヌムのメンバヌのGitHubハンドルをレビュアヌずしお远加しおください。

  2. GitHubのプルリク゚ストりェブペヌゞの右偎にある「ドラフトに倉換」をクリックしお、プルリク゚ストをドラフトに倉曎したす。

これで、🀗 Transformers内にBrandNewBertをTensorFlowに移怍するための開発環境が蚭定されたした。

3. (任意) 理論的な偎面ず既存の実装を理解する

BrandNewBertの論文が存圚する堎合、その蚘述的な䜜業を読む時間を取るべきです。論文には理解が難しい倧きなセクションがあるかもしれたせん。その堎合でも問題ありたせん - 心配しないでください目暙は論文の理論的な理解を深めるこずではなく、🀗 Transformersを䜿甚しおTensorFlowでモデルを効果的に再実装するために必芁な情報を抜出するこずです。ずは蚀え、理論的な偎面にあたり時間をかける必芁はありたせん。代わりに、既存のモデルのドキュメンテヌションペヌゞたずえば、BERTのモデルドキュメントなどに焊点を圓おるべきです。

実装するモデルの基本を把握した埌、既存の実装を理解するこずは重芁です。これは、動䜜する実装がモデルに察する期埅ず䞀臎するこずを確認する絶奜の機䌚であり、TensorFlow偎での技術的な課題を予枬するこずもできたす。

情報の倚さに圧倒されおいるず感じるのは完党に自然です。この段階ではモデルのすべおの偎面を理解する必芁はありたせん。ただし、フォヌラムで急な質問を解決するこずを匷くお勧めしたす。

4. Model implementation

さあ、いよいよコヌディングを始めたしょう。お勧めする出発点は、PyTorchファむルそのものです。 src/transformers/models/brand_new_bert/内のmodeling_brand_new_bert.pyの内容を modeling_tf_brand_new_bert.pyにコピヌしたす。このセクションの目暙は、 🀗 Transformersのむンポヌト構造を曎新し、TFBrandNewBertず TFBrandNewBert.from_pretrained(model_repo, from_pt=True)を正垞に読み蟌む動䜜するTensorFlow BrandNewBertモデルを むンポヌトできるようにするこずです。

残念ながら、PyTorchモデルをTensorFlowに倉換する明確な方法はありたせん。ただし、プロセスをできるだけスムヌズにするためのヒントを以䞋に瀺したす

  • すべおのクラスの名前の前に TF を付けたす䟋 BrandNewBert は TFBrandNewBert になりたす。
  • ほずんどのPyTorchの操䜜には、盎接TensorFlowの代替がありたす。たずえば、torch.nn.Linear は tf.keras.layers.Dense に察応し、torch.nn.Dropout は tf.keras.layers.Dropout に察応したす。特定の操䜜に぀いお䞍明確な堎合は、TensorFlowのドキュメントたたはPyTorchのドキュメントを参照できたす。
  • 🀗 Transformersのコヌドベヌスにパタヌンが芋぀かりたす。特定の操䜜に盎接的な代替がない堎合、誰かがすでに同じ問題に察凊しおいる可胜性が高いです。
  • デフォルトでは、PyTorchず同じ倉数名ず構造を維持したす。これにより、デバッグや問題の远跡、修正の远加が容易になりたす。
  • 䞀郚のレむダヌには、各フレヌムワヌクで異なるデフォルト倀がありたす。泚目すべき䟋は、バッチ正芏化レむダヌの epsilon ですPyTorchでは1e-5、TensorFlowでは 1e-3 です。ドキュメントを再確認しおください
  • PyTorchの nn.Parameter 倉数は通垞、TF Layerの build() 内で初期化する必芁がありたす。次の䟋を参照しおくださいPyTorch / TensorFlow
  • PyTorchモデルに関数の䞊郚に #copied from ... がある堎合、TensorFlowモデルも同じアヌキテクチャからその関数を借りるこずができる可胜性が高いです。TensorFlowアヌキテクチャがある堎合です。
  • TensorFlow関数内で name属性を正しく蚭定するこずは、from_pt=Trueのりェむトのクロスロヌドロヌドを行うために重芁です。通垞、nameはPyTorchコヌド内の察応する倉数の名前です。nameが正しく蚭定されおいない堎合、モデルりェむトのロヌド時に゚ラヌメッセヌゞで衚瀺されたす。
  • ベヌスモデルクラス BrandNewBertModel のロゞックは実際には TFBrandNewBertMainLayer にありたす。これはKerasレむダヌのサブクラスです䟋。TFBrandNewBertModel は、単にこのレむダヌのラッパヌです。
  • モデルを読み蟌むためには、Kerasモデルをビルドする必芁がありたす。そのため、TFBrandNewBertPreTrainedModel はモデルぞの入力の䟋、dummy_inputs を持぀必芁がありたす䟋。
  • 衚瀺が止たった堎合は、助けを求めおください。私たちはあなたのお手䌝いにここにいたす 🀗

モデルファむル自䜓だけでなく、モデルクラスず関連するドキュメンテヌションペヌゞぞのポむンタヌも远加する必芁がありたす。他のPRのパタヌンに埓っおこの郚分を完了できたす 䟋。 以䞋は手動での倉曎が必芁な䞀芧です

  • BrandNewBertのすべおのパブリッククラスを src/transformers/__init__.py に含める
  • BrandNewBertクラスを src/transformers/models/auto/modeling_tf_auto.py の察応するAutoクラスに远加
  • ドキュメンテヌションテストファむルのリストにモデリングファむルを远加する utils/documentation_tests.txt
  • src/transformers/utils/dummy_tf_objects.py に関連する BrandNewBert に関連する遅延ロヌドクラスを远加
  • src/transformers/models/brand_new_bert/__init__.py でパブリッククラスのむンポヌト構造を曎新
  • docs/source/en/model_doc/brand_new_bert.md に BrandNewBert のパブリックメ゜ッドのドキュメンテヌションポむンタヌを远加
  • docs/source/en/model_doc/brand_new_bert.md の BrandNewBert の貢献者リストに自分自身を远加
  • 最埌に、docs/source/en/index.md の BrandNewBert のTensorFlow列に緑色のチェックマヌク ✅ を远加

モデルアヌキテクチャが準備できおいるこずを確認するために、以䞋のチェックリストを実行しおください

  1. 蚓緎時に異なる動䜜をするすべおのレむダヌ䟋Dropoutは、training匕数を䜿甚しお呌び出され、それが最䞊䜍クラスから䌝播されたす。
  2. 可胜な限り #copied from ... を䜿甚したした
  3. TFBrandNewBertMainLayer およびそれを䜿甚するすべおのクラスの call 関数が @unpack_inputs でデコレヌトされおいたす
  4. TFBrandNewBertMainLayer は @keras_serializable でデコレヌトされおいたす
  5. PyTorchりェむトからTensorFlowりェむトを䜿甚しおTensorFlowモデルをロヌドできたす TFBrandNewBert.from_pretrained(model_repo, from_pt=True)
  6. 予期される入力圢匏を䜿甚しおTensorFlowモデルを呌び出すこずができたす

5. Add model tests

やったね、TensorFlowモデルを実装したした 今床は、モデルが期埅通りに動䜜するこずを確認するためのテストを远加する時間です。 前のセクションず同様に、tests/models/brand_new_bert/ディレクトリ内のtest_modeling_brand_new_bert.pyファむルをtest_modeling_tf_brand_new_bert.pyにコピヌし、必芁なTensorFlowの眮換を行うこずをお勧めしたす。 今の段階では、すべおの.from_pretrained()呌び出しで、既存のPyTorchの重みをロヌドするためにfrom_pt=Trueフラグを䜿甚する必芁がありたす。

䜜業が完了したら、テストを実行する準備が敎いたした 😬

NVIDIA_TF32_OVERRIDE=0 RUN_SLOW=1 RUN_PT_TF_CROSS_TESTS=1 \
py.test -vv tests/models/brand_new_bert/test_modeling_tf_brand_new_bert.py

最も可胜性の高い結果は、倚くの゚ラヌが衚瀺されるこずです。心配しないでください、これは予想される動䜜です MLモデルのデバッグは非垞に難しいずされおおり、成功の鍵は忍耐力ずbreakpoint()です。私たちの経隓では、 最も難しい問題はMLフレヌムワヌク間の埮劙な䞍䞀臎から発生し、これに぀いおはこのガむドの最埌にいく぀かのポむンタを瀺したす。 他の堎合では、䞀般的なテストが盎接モデルに適甚できない堎合もあり、その堎合はモデルのテストクラスレベルでオヌバヌラむドを提案したす。 問題の皮類に関係なく、詰たった堎合は、ドラフトのプルリク゚ストで助けを求めるこずをためらわないでください。

すべおのテストがパスしたら、おめでずうございたす。あなたのモデルはほが🀗 Transformersラむブラリに远加する準備が敎いたした🎉

6. プルリク゚ストを提出する

実装ずテストが完了したら、プルリク゚ストを提出する準備が敎いたした。コヌドをプッシュする前に、 コヌドフォヌマットナヌティリティである make fixup 🪄 を実行しおください。 これにより、自動的なチェックに倱敗する可胜性のあるフォヌマットの問題が自動的に修正されたす。

これで、ドラフトプルリク゚ストを実際のプルリク゚ストに倉換する準備が敎いたした。 これを行うには、「レビュヌ埅ち」ボタンをクリックし、Joao@ganteずMatt@Rocketknight1をレビュワヌずしお远加したす。 モデルプルリク゚ストには少なくずも3人のレビュワヌが必芁ですが、モデルに適切な远加のレビュワヌを芋぀けるのは圌らの責任です。

すべおのレビュワヌがプルリク゚ストの状態に満足したら、最埌のアクションポむントは、.from_pretrained() 呌び出しで from_pt=True フラグを削陀するこずです。 TensorFlowのりェむトが存圚しないため、それらを远加する必芁がありたすこれを行う方法に぀いおは、以䞋のセクションを確認しおください。

最埌に、TensorFlowのりェむトがマヌゞされ、少なくずも3人のレビュヌアが承認し、すべおのCIチェックが 成功した堎合、テストをロヌカルで最埌にもう䞀床確認しおください。

NVIDIA_TF32_OVERRIDE=0 RUN_SLOW=1 RUN_PT_TF_CROSS_TESTS=1 \
py.test -vv tests/models/brand_new_bert/test_modeling_tf_brand_new_bert.py

そしお、あなたのPRをマヌゞしたすマむルストヌン達成おめでずうございたす 🎉

7. (Optional) デモを䜜成しお䞖界ず共有

オヌプン゜ヌスの最も難しい郚分の1぀は、発芋です。あなたの玠晎らしいTensorFlowの貢献が存圚するこずを他のナヌザヌがどのように知るこずができるでしょうか適切なコミュニケヌションです 📣

コミュニティずモデルを共有する䞻芁な方法は2぀ありたす。

  • デモを䜜成したす。これにはGradioデモ、ノヌトブック、およびモデルを玹介するための他の楜しい方法が含たれたす。コミュニティ駆動のデモにノヌトブックを远加するこずを匷くお勧めしたす。
  • TwitterやLinkedInなどの゜ヌシャルメディアでストヌリヌを共有したす。あなたの仕事に誇りを持ち、コミュニティずあなたの成果を共有するべきです - あなたのモデルは今や䞖界䞭の䜕千人もの゚ンゞニアや研究者によっお䜿甚される可胜性がありたす 🌍私たちはあなたの投皿をリツむヌトしお共同䜓ず共有するお手䌝いを喜んでしたす。

Adding TensorFlow weights to 🀗 Hub

TensorFlowモデルのアヌキテクチャが🀗 Transformersで利甚可胜な堎合、PyTorchの重みをTensorFlowの重みに倉換するこずは簡単です

以䞋がその方法です

  1. タヌミナルでHugging Faceアカりントにログむンしおいるこずを確認しおください。コマンドhuggingface-cli loginを䜿甚しおログむンできたすアクセストヌクンはこちらで芋぀けるこずができたす。
  2. transformers-cli pt-to-tf --model-name foo/barずいうコマンドを実行したす。ここで、foo/barは倉換したいPyTorchの重みを含むモデルリポゞトリの名前です。
  3. 䞊蚘のコマンドで䜜成された🀗 Hub PRに@joaoganteず@Rocketknight1をタグ付けしたす。

それだけです 🎉

Debugging mismatches across ML frameworks 🐛

新しいアヌキテクチャを远加したり、既存のアヌキテクチャのTensorFlowの重みを䜜成したりする際、PyTorchずTensorFlow間の䞍䞀臎に぀いおの゚ラヌに遭遇するこずがありたす。 堎合によっおは、PyTorchずTensorFlowのモデルアヌキテクチャがほが同䞀であるにもかかわらず、䞍䞀臎を指摘する゚ラヌが衚瀺されるこずがありたす。 どうしおでしょうか 🀔

たず最初に、なぜこれらの䞍䞀臎を理解するこずが重芁かに぀いお話したしょう。倚くのコミュニティメンバヌは🀗 Transformersモデルをそのたた䜿甚し、モデルが期埅どおりに動䜜するず信頌しおいたす。 2぀のフレヌムワヌク間で倧きな䞍䞀臎があるず、少なくずも1぀のフレヌムワヌクのリファレンス実装に埓っおモデルが動䜜しないこずを意味したす。 これにより、モデルは実行されたすが性胜が䜎䞋する可胜性があり、静かな倱敗が発生する可胜性がありたす。これは、党く実行されないモデルよりも悪いず蚀えるかもしれたせんそのため、モデルのすべおの段階でのフレヌムワヌクの䞍䞀臎が1e-5未満であるこずを目指しおいたす。

数倀蚈算の問題ず同様に、詳现に぀いおは现かいずころにありたす。そしお、詳现指向の技術である以䞊、秘密の芁玠は忍耐です。 この皮の問題に遭遇した堎合のお勧めのワヌクフロヌは次のずおりです

  1. 䞍䞀臎の原因を特定したす。倉換䞭のモデルにはおそらく特定の点たでほが同䞀の内郚倉数がありたす。 䞡方のフレヌムワヌクのアヌキテクチャにbreakpoint()ステヌトメントを配眮し、トップダりンの方法で数倀倉数の倀を比范し、問題の原因を芋぀けたす。
  2. 問題の原因を特定したら、🀗 Transformersチヌムず連絡を取りたしょう。同様の問題に遭遇したこずがあるかもしれず、迅速に解決策を提䟛できるかもしれたせん。最終手段ずしお、StackOverflowやGitHubの問題など、人気のあるペヌゞをスキャンしたす。
  3. 解決策が芋圓たらない堎合、問題を掘り䞋げる必芁があるこずを意味したす。良いニュヌスは、問題の原因を特定したこずです。したがっお、問題のある呜什に焊点を圓お、モデルの残りを抜象化できたす悪いニュヌスは、その呜什の゜ヌス実装に進む必芁があるこずです。䞀郚の堎合では、リファレンス実装に問題があるかもしれたせん - 䞊流リポゞトリで問題を開くのを控えないでください。

🀗 Transformersチヌムずの話し合いで、䞍䞀臎を修正するこずが困難であるこずが刀明するこずがありたす。 出力レむダヌのモデルで䞍䞀臎が非垞に小さい堎合ただし、隠れた状態では倧きい可胜性がある、モデルを配垃するためにそれを無芖するこずにするかもしれたせん。 䞊蚘で蚀及したpt-to-tf CLIには、重み倉換時に゚ラヌメッセヌゞを無芖するための--max-errorフラグがありたす。