💻 6月3日の MS Build で開催される VS Code Live に参加しましょう。

VS Code用Foundry Toolkitでモデルを変換する

モデル変換（Model conversion）は、開発者やAIエンジニアが、ローカルのWindows環境で構築済みの機械学習モデルを変換、量子化、最適化、評価するための統合開発環境です。Hugging Faceなどのソースから取得したモデルを最適化し、NPU、GPU、CPUを搭載したローカルデバイス上で推論を実行できるようにする、合理的でエンドツーエンドの体験を提供します。

前提条件

プロジェクトの作成

モデル変換におけるプロジェクト作成は、機械学習モデルの変換、最適化、量子化、評価に向けた最初のステップです。

  1. Foundry Toolkitビューを開き、Models > Conversionを選択してモデル変換を起動します。

  2. New Model Project（新しいモデルプロジェクト）を選択して、新しいプロジェクトを開始します。

    Screenshot that shows view for creating model project, including Primary Side Bar and create project button.

  3. ベースモデルを選択します。

    • Hugging Face Model：サポートされているモデルリストから、定義済みのレシピを持つベースモデルを選択します。
    • Model Template：モデルがベースモデルに含まれていない場合は、カスタマイズしたレシピ用に空のテンプレートを選択します（高度なシナリオ）。

    Screenshot that shows model list, such as bert, resnet, llama and so on.

  4. プロジェクトの詳細（一意のProject FolderとProject Name）を入力します。

    指定したプロジェクト名を持つ新しいフォルダが、プロジェクトファイルを保存するために選択した場所に作成されます。

注意

初めてモデルプロジェクトを作成する場合、環境のセットアップに時間がかかることがあります。セットアップを完了させなくても問題ありません。準備ができたときに、改めて環境を再セットアップすることができます。再セットアップを示すスクリーンショット。

各プロジェクトにはREADME.mdファイルが含まれています。閉じてしまった場合は、ワークスペースから再度開くことができます。モデルのreadmeを示すスクリーンショット。

サポートされているモデル

モデル変換は現在、PyTorch形式の主要なHugging Faceモデルを含む、増加中のモデルリストをサポートしています。詳細なモデルリストについては、モデルリストを参照してください。

(オプション) 既存のプロジェクトにモデルを追加する

  1. モデルプロジェクトを開きます。

  2. Models > Conversionを選択し、右側のパネルでAdd Modelsを選択します。

    Screenshot that shows how to add model. It contains a button to add models.

  3. ベースモデルまたはテンプレートを選択し、Addを選択します。

    新しいモデルファイルを含むフォルダが、現在のプロジェクトフォルダ内に作成されます。

(オプション) 新しいモデルプロジェクトを作成する

  1. モデルプロジェクトを開きます。

  2. Models > Conversionを選択し、右側のパネルでNew Projectを選択します。

    Screenshot that shows how to create a new project. It contains a button to create a new project.

  3. あるいは、現在のモデルプロジェクトを閉じて、最初から新しいプロジェクトを作成します。

(オプション) モデルプロジェクトを削除する

  1. モデルプロジェクトを開き、Models > Conversionを選択します。

  2. 右上隅のビューで、省略記号（...）を選択し、Deleteを選択して現在選択されているモデルプロジェクトを削除します。

    Screenshot that shows how to delete a model project. It contains a button to open mean and detele a model project.

ワークフローの実行

モデル変換でのワークフロー実行は、構築済みのMLモデルを最適化・量子化されたONNXモデルに変換するための中心的な手順です。

  1. VS CodeでFile > Open Folderを選択し、モデルプロジェクトのフォルダを開きます。

  2. ワークフロー設定を確認します。

    1. Models > Conversionを選択します。
    2. ワークフローテンプレートを選択して、変換レシピを表示します。

    Screenshot that shows running a workflow. There is a workflow configuration section containing Conversion, Quantization and Evaluation.

    変換（Conversion）

    ワークフローでは、モデルをONNX形式に変換する変換ステップが常に実行されます。このステップを無効にすることはできません。

    量子化（Quantization）

    このセクションでは、量子化のパラメータを設定できます。

    重要

    Hugging Faceコンプライアンスアラート：量子化中にはキャリブレーションデータセットが必要です。進行前にライセンス条項への同意を求められる場合があります。通知を見逃した場合、実行プロセスが一時停止し、入力を待機します。通知が有効になっていること、および必要なライセンスに同意していることを確認してください。免責事項を示すスクリーンショット。

    • Activation Type：ニューラルネットワークの各層の中間出力（アクティベーション）を表すために使用されるデータ型です。

    • Weight Type：モデルの学習済みパラメータ（重み）を表すために使用されるデータ型です。

    • Quantization Dataset：量子化に使用するキャリブレーションデータセットです。

      ワークフローでHugging Face上でのライセンス契約の承認が必要なデータセット（例：ImageNet-1k）を使用する場合、進行前にデータセットページで条項への同意を求められます。これは法的コンプライアンスのために必須です。

      1. HuggingFace Access Tokenボタンを選択して、Hugging Faceアクセストークンを取得します。

        Screenshot that shows input token step 1: start to get Hugging Face Access Token.

      2. Openを選択して、Hugging Faceのウェブサイトを開きます。

        Screenshot that shows input token step 2: open Hugging Face websites.

      3. Hugging Faceポータルでトークンを取得し、クイックピックに貼り付けます。Enterキーを押します。

        Screenshot that shows input token step 3: input token on dropdown textbox.

    • Quantization Dataset Split：データセットには、検証、訓練、テストなどの異なる分割（スプリット）がある場合があります。

    • Quantization Dataset Size：モデルの量子化に使用されるデータ数です。

    アクティベーションおよび重みタイプの詳細については、データ型の選択を参照してください。

    このセクションを無効にすることも可能です。その場合、ワークフローはモデルをONNX形式に変換するだけで、量子化は行いません。

    評価

    このセクションでは、モデルの変換元のプラットフォームに関係なく、評価に使用する実行プロバイダー（EP）を選択する必要があります。

    • Evaluate on：モデルを評価するターゲットデバイスです。可能な値は以下の通りです：
      • Qualcomm NPU：これを使用するには、互換性のあるQualcommデバイスが必要です。
      • AMD NPU：これを使用するには、サポートされているAMD NPUを搭載したデバイスが必要です。
      • Intel CPU/GPU/NPU：これを使用するには、サポートされているIntel CPU/GPU/NPUを搭載したデバイスが必要です。
      • NVIDIA TRT for RTX：これを使用するには、TensorRT for RTXをサポートするNVIDIA GPUを搭載したデバイスが必要です。
      • DirectML：これを使用するには、DirectMLをサポートするGPUを搭載したデバイスが必要です。
      • CPU：すべてのCPUで動作可能です。
    • Evaluation Dataset：評価に使用するデータセットです。
    • Evaluation Dataset Split：データセットには、検証、訓練、テストなどの異なる分割がある場合があります。
    • Evaluation Dataset Size：モデルの評価に使用されるデータ数です。

    このセクションを無効にすることも可能です。その場合、ワークフローはモデルをONNX形式に変換するだけで、評価は行いません。

  3. Runを選択してワークフローを実行します。

    追跡を容易にするため、ワークフロー名とタイムスタンプ（例：bert_qdq_2025-05-06_20-45-00）を使用してデフォルトのジョブ名が生成されます。

    ジョブの実行中、履歴ボードのステータスインジケーターまたはAction下の三点メニューを選択し、Stop Runningを選択することで、ジョブをCancel（キャンセル）できます。

    Hugging Faceコンプライアンスアラート：量子化中にはキャリブレーションデータセットが必要です。進行前にライセンス条項への同意を求められる場合があります。通知を見逃した場合、実行プロセスが一時停止し、入力を待機します。通知が有効になっていること、および必要なライセンスに同意していることを確認してください。

  4. (オプション) クラウドでモデル変換を実行する

    クラウド変換（Cloud Conversion）を使用すると、ローカルマシンに十分なコンピューティング容量やストレージ容量がない場合に、クラウド上でモデルの変換と量子化を実行できます。クラウド変換を使用するにはAzureサブスクリプションが必要です。

    1. 右上のドロップダウンからRun with Cloudを選択します。クラウド環境には推論用のターゲットプロセッサがないため、Evaluationセクションは無効になることに注意してください。

      Screenshot that shows Run with Cloud button.

    2. Foundry Toolkitはまず、クラウド変換用のAzureリソースが準備されているかを確認します。必要な場合、Azureリソースをプロビジョニングするために、Azureサブスクリプションとリソースグループの入力を求められます。

      Screenshot that shows prompt for provisionning.

    3. プロビジョニングが完了すると、プロビジョニング設定がワークスペースのルートフォルダにあるmodel_lab.workspace.provision.configに保存されます。この情報は、Azureリソースを再利用し、クラウド変換プロセスを加速するためにキャッシュされます。新しいリソースを使用したい場合は、このファイルを削除して、再度クラウド変換を実行してください。

    4. クラウド変換を実行するために、Azure Container App (ACA) ジョブがトリガーされます。実行中のジョブに対しては、以下の操作が可能です：

      • ステータスリンクを選択して、Azure ACAジョブ実行履歴ページに移動します。
      • logsを選択して、Azure Log Analyticsに移動します。
      • 更新ボタンを選択して、現在のジョブステータスを取得します。

      Screenshot that shows prompt for provisionning.

ヒント

LLMモデル変換用のGPUが利用できない場合は、Run with Cloudを使用できます。Run with Cloudオプションは、モデルの変換と量子化のみをサポートしています。評価を行うには、変換済みモデルをローカルマシンにダウンロードする必要があります。

Run with Cloudは、DirectMLまたはNVIDIA TRT for RTXワークフローを使用したモデル変換をサポートしていません。

注意

Recommended列には、デバイスが変換済みモデルを実行する準備ができているかどうかに基づいて、推奨されるワークフローが表示されます。もちろん、好みのワークフローを選択することも可能です。Model conversion and quantization：LLMモデルを除き、どのデバイスでもワークフローを実行できます。Quantization構成はNPU専用に最適化されています。ターゲットシステムがNPUではない場合は、このステップのチェックを外すことを推奨します。

LLM model quantization：LLMモデルを量子化する場合は、NVIDIA GPUが必要です。

GPUを搭載した別のデバイスでモデルを量子化したい場合は、環境を自分でセットアップできます。ManualConversionOnGPUを参照してください。なお、「Quantization」ステップのみGPUが必要である点に注意してください。量子化後、NPUまたはCPU上でモデルを評価できます。

再評価のヒント

モデルが正常に変換された後、再評価機能を使用して、モデルの変換をやり直すことなく評価を再度実行できます。

履歴ボードに移動し、モデル実行ジョブを見つけます。Action下の三点メニューを選択し、モデルをRe-evaluate（再評価）します。

再評価のために、異なるEPやデータセットを選択できます。

Screenshot that shows re-evaluation. It contains configurations such as name, system and datasets settings.

失敗したジョブのヒント

ジョブがキャンセルまたは失敗した場合、ジョブ名を選択してワークフローを調整し、再度ジョブを実行できます。意図しない上書きを防ぐため、実行のたびに独自の構成と結果を持つ新しい履歴フォルダが作成されます。

注意

ワークフローによっては、事前にHugging Faceへのログインが必要な場合があります。huggingface_hub.errors.LocalTokenNotFoundError: Token is required ('token=True'), but no token found. You need to provide a token or be logged in to Hugging Face with 'hf auth login' or 'huggingface_hub.login'のような出力でジョブが失敗した場合は、https://huggingface.co/settings/tokensに移動し、指示に従ってログインプロセスを完了してから、再度試行してください。

Microsoft Visual C++ Redistributable is not installedのような出力警告で再評価が失敗した場合は、以下のパッケージを手動でインストールする必要があります。

  1. Microsoft Visual C++ Redistributable
  2. (ARM64の場合はオプション) Microsoft C++ Build Toolsからダウンロードします。インストール中にC++によるデスクトップ開発ワークロードにもチェックを入れてください。

結果の表示

Conversion内の履歴ボードは、すべてのワークフロー実行を追跡、レビュー、管理するための中心的なダッシュボードです。モデルの変換と評価を実行するたびに履歴ボードに新しいエントリが作成されるため、完全なトレーサビリティと再現性が保証されます。

  • レビューしたいワークフロー実行を見つけます。各実行には、ステータスインジケーター（例：Succeeded、Cancelled）が表示されます。

  • 実行名を選択して、変換設定を表示します。

  • ステータスインジケーターの下にあるlogsを選択して、ログと詳細な実行結果を表示します。

  • モデルの変換が成功すると、Metricsの下で評価結果を確認できます。精度（accuracy）、遅延（latency）、スループット（throughput）などのメトリクスが、各実行結果の横に表示されます。

    Screenshot that shows history, including name, time, parameters and so on.

  • 変換済みモデルを操作するには、Action下の三点メニューを選択します。

    Screenshot that shows actions, including inference, copy model path and re-evaluate.

変換済みモデルのパスをコピー

  • ドロップダウンからCopy model pathを選択します。c:/{workspace}/{model_project}/history/{workflow}/model/model.onnxのような変換済みモデルのパスがクリップボードにコピーされ、参照できるようになります。LLMモデルの場合、代わりにパスが出力フォルダへコピーされます。

サンプルノートブックを使用したモデル推論

  • ドロップダウンからInference in Sampleを選択します。
  • Python環境を選択します。
    • Python仮想環境の選択を求められます。デフォルトのランタイムはC:\Users\{user_name}\.aitk\bin\model_lab_runtime\Python-WCR-win32-x64-3.12.9です。
    • デフォルトのランタイムには必要なものがすべて含まれていますが、そうでない場合はrequirements.txtを手動でインストールしてください。
  • サンプルがJupyter Notebookで起動します。入力データやパラメータをカスタマイズして、さまざまなシナリオをテストできます。
注意

クラウド変換を使用したモデルの場合、ステータスがSucceededに変わったら、クラウドダウンロードアイコンを選択して、出力モデルをローカルマシンにダウンロードします。クラウドからモデルをダウンロードするアイコンを含む操作を示すスクリーンショット。

構成ファイルや履歴関連ファイルなど、既存のローカルファイルの上書きを避けるため、欠落しているファイルのみがダウンロードされます。クリーンなコピーをダウンロードしたい場合は、先にローカルフォルダを削除してから、再度ダウンロードしてください。

ヒント

モデルの互換性：変換済みモデルが推論サンプルで指定されたEPをサポートしていることを確認してください。

サンプルの場所：推論サンプルは、履歴フォルダ内の実行アーティファクトと一緒に保存されます。

エクスポートと共有

履歴ボードに移動します。Exportを選択して、モデルプロジェクトを他のユーザーと共有します。これにより、履歴フォルダを含まないモデルプロジェクトがコピーされます。モデルを他のユーザーと共有したい場合は、対応するジョブを選択してください。これにより、モデルとその構成を含む選択された履歴フォルダがコピーされます。

学んだこと

この記事では、以下の方法を学びました。

  • Foundry Toolkit for VS Codeでモデル変換プロジェクトを作成する。
  • 量子化や評価設定を含む、変換ワークフローを構成する。
  • 変換ワークフローを実行し、構築済みのモデルを最適化されたONNXモデルに変換する。
  • メトリクスやログを含む変換結果を表示する。
  • モデルの推論とテストのためにサンプルノートブックを使用する。
  • モデルプロジェクトをエクスポートし、他のユーザーと共有する。
  • 異なる実行プロバイダーやデータセットを使用してモデルを再評価する。
  • 失敗したジョブに対処し、再実行のために構成を調整する。
  • サポートされているモデルと、それらの変換および量子化の要件を理解する。

関連項目

07/14/2025
© . This site is unofficial and not affiliated with Microsoft.