roboflow-custom-weights-upload

エージェント向け： このスキルは roboflow/computer-vision-skills で作成されています。クライアントにスキルとしてすでに読み込まれている場合（たとえば Roboflow プラグインから読み込まれている場合）は、そのコピーを使用してください。roboflow://skills/<name>/... MCP リソースは、スキルが読み込まれていないクライアント向けに同じスキルを提供します。

カスタム重みのアップロード

Roboflow の外部（ノート PC、トレーニングサーバー、Colab）でトレーニングしたモデルの重みを登録し、Roboflow で変換、ホスティング、配信できるようにします。

アップロードの実行場所

パッケージ化ではディスクからチェックポイントを読み込むため、アップロードは重みがあるマシン上、つまり以下の Python SDK フローを使用してクライアント側で実行されます。

models_custom_weights_upload_guide MCP ツールはガイドであり、アップローダーではありません。このツールを呼び出すと、この手順が返され、渡された引数がそのまま返されます（upload_mode フィールドには、引数がバージョン単位のアップロードまたはワークスペースへのアップロードのどちらを示すかが記載されます。どちらも特定できない場合は undetermined になります）。MCP サーバーはユーザーのファイルシステムを読み取れないため、パッケージ化やアップロードは行いません。

Python SDK を使ったクライアント側でのアップロード

重みがあるマシン上で実行してください。できれば、トレーニングに使用したものと同じ Python 環境を使ってください（すでに torch と対応する ultralytics がインストールされています）。

1. SDK をインストールする：roboflow>=1.3.13 と rfdetr はどちらも Python >= 3.10 を必要とするため、まず python3 --version で確認してください（macOS には 3.9 が付属しています）。古い場合は、次のように venv を作成します：uv venv --python 3.12 && source .venv/bin/activate。続いて pip install "roboflow>=1.3.13" を実行します。

2. API キーを安全に扱う：ユーザーに秘密の API キーをチャットに貼り付けるよう求めないでください。また、キーを探すためにドットファイル、シェルプロファイル、設定ファイルをスキャンしないでください。権限システムがこれをブロックするのは適切な動作です。環境にすでに ROBOFLOW_API_KEY が設定されている場合（test -n "$ROBOFLOW_API_KEY"）、または作業中のプロジェクトに定義済みの .env がある場合は、それを使用してください。そうでなければ、MCP の api_keys_create ツールでスコープ付きキーを発行します。このツールは秘密鍵を一度だけ返します（同様の動作をする他のツールは api_keys_roll のみです。api_keys_list / api_keys_get はマスクされたメタデータを返します）。キーは自分で .gitignore に追加した .env に ROBOFLOW_API_KEY として書き込みます。.env に書き込んでも os.environ には設定されないため、実行前に読み込んでください。自分で書き込んだ .env であれば、set -a; source .env; set +a を使用できます。既存の .env は決して source しないでください。ファイル内のシェルコマンドが実行され、含まれる他のすべての秘密情報がプロセスにエクスポートされるためです。代わりに、たとえばスクリプト内で python-dotenv（pip install python-dotenv）を使い、必要なキーだけを読み込んでください：

   import os
   from dotenv import dotenv_values
   
   os.environ["ROBOFLOW_API_KEY"] = dotenv_values(".env")["ROBOFLOW_API_KEY"]
   

   キーのスコープは最小限にせず、デプロイの全フローに必要なものを設定してください。SDK の rf.workspace() はデプロイ前にワークスペースとプロジェクト一覧を読み込むため、project:read と model:deploy だけでは権限不足で失敗します。workspace:read、project:read、model:deploy を含め、バージョン単位でデプロイする場合はさらに version:read と version:update も含めてください。キーの発行時に適切なスコープを設定することでアップロードを保護できます。以下の事前確認で確認するのはキーの有効性とワークスペースの読み取り権限だけであり、デプロイ権限は確認されません。

   api_keys_create の呼び出しが拒否された場合（アップロード作業中の認証情報作成が権限システムによって検知されることがあります）、または利用できない場合は、拒否を回避しないでください。ユーザーに次のいずれかを選んでもらってください：（a）一時的なスコープ付きキーの発行を明示的に許可する。このキーはアップロード後に api_keys_revoke で失効させます。（b）ユーザー自身がシェルまたは .env に ROBOFLOW_API_KEY を設定する。（c）すでにキーが定義されている既存の .env を指定してもらう。

3. 保存先と名前をユーザーに確認する：モデルの登録は簡単には元に戻せません。チェックポイントのクラス数やファイル名から、対象のプロジェクトやバージョンを決して推測しないでください。必ず尋ねてください。ワークスペースへのアップロード時の model_name も同様です。モデル名をどうするかユーザーに尋ね、勝手に名前を決めないでください。

パッケージ化前の事前確認

パッケージ化と100 MB以上のアップロードには時間がかかるため、まず手軽なチェックを実行し、手順を一つずつ失敗するのではなく、すべての不足をまとめて報告します。

1. Python が >= 3.10 であること（python3 --version）。

2. 必要なインポートが読み込めること：YOLO、RF-DETR、YOLO-NAS には torch、YOLO v8/v10/v11/v12/26 には ultralytics、raw PyTorch-Lightning RF-DETR チェックポイントには rfdetr>=1.8.0。

3. キーが有効で、ワークスペースの読み取り権限を持つこと — deploy_model が最初に行うものと同じワークスペース／プロジェクト一覧の読み取りを試す、手軽な呼び出しです。

   import os
   from roboflow import Roboflow
   
   Roboflow(api_key=os.environ["ROBOFLOW_API_KEY"]).workspace()
   

このチェックの限界を正しく理解してください。プラットフォームが model:deploy をテストするのは、パッケージ化後の models/prepareUpload のみであり、このチェックでは model:deploy は試しません。そのため、ステップ2では最初から必要なスコープをすべて含むキーを発行します。事前確認で検出できるのは無効なキーや読み取り権限が不十分なキーであり、既存のキーにデプロイスコープがないことではありません。

3つすべてに合格してから、パッケージ化とアップロードを行ってください。

データセットのバージョンを必要としないワークスペースモデルのアップロード：

import os
from roboflow import Roboflow

rf = Roboflow(api_key=os.environ["ROBOFLOW_API_KEY"])
workspace = rf.workspace("WORKSPACE_SLUG")
workspace.deploy_model(
    model_type="rfdetr-base",
    model_path="/path/to/training/output",
    project_ids=["PROJECT_SLUG"],
    model_name="MODEL_NAME",
    filename="checkpoint_best_total.pth",  # relative to model_path
)

バージョン指定のデプロイ（既存のデータセットバージョンに重みを添付）：

import os
from roboflow import Roboflow

rf = Roboflow(api_key=os.environ["ROBOFLOW_API_KEY"])
version = rf.workspace("WORKSPACE_SLUG").project("PROJECT_SLUG").version(3)
version.deploy(
    model_type="yolov8n",
    model_path="/path/to/runs/detect/train",
    filename="weights/best.pt",
)

model_type には、実際のアーキテクチャ（yolov8n、yolov11s、rfdetr-base、rfdetr-seg-medium、yolonas、サポート対象の PaliGemma または Florence-2 のタイプ）を指定する必要があります。YOLO ファミリーでは、サイズのサフィックスが省略されている場合、SDK が重みから推定します。RF-DETR では rfdetr のみの指定は受け付けられません。正確なバリアントを指定してください。SDK はそのバリアントをチェックポイントと照合します。

サイズ／バリアントまたは依存関係が一致しない場合、deploy_model／version.deploy はエラーを表示した後、対話形式で「このまま続行しますか？ y/n」と確認します。ヘッドレス実行では、表示されたエラーの直後に確認プロンプトが EOFError として現れます。エラーの種類に応じて対処してください。

• サイズ／バリアントの不一致：エラーに適合するタイプが示されている場合は、model_type をそのタイプに修正して再実行します。サイズを推定できなかったと表示された場合は、サイズを明示的に指定します。
• 依存関係の不一致：エラーにはモデルタイプではなく pip のバージョン指定が示されます（yolov8 は ultralytics==8.0.196 を推奨するため、現在の多くの学習環境ではこの確認が表示されます）。指定されたバージョンをインストールするか、ユーザーから明示的な確認を得た場合に限り、y と回答して続行します（ヘッドレス実行の場合：printf 'y\n' | python upload.py）。その場合は、インストール済みのバージョンで続行します。

ユーザーが上書きを意図していると明示的に確認しない限り、どちらの確認も強制的に通過させないでください。

ファミリー別の要件

• YOLO v8/v10/v11/v12/YOLO26：torch と ultralytics をインポートできる必要があります（yolov8 は ultralytics==8.0.196 を推奨します。上記の依存関係の不一致に関する注意を参照してください）。レガシー YOLO v5/v7/v9：torch と、imgsz（または img_size）および batch_size を含む model_path 内の opt.yaml が必要です。ultralytics は使用されません。yolov6 はサポートされていません。
• RF-DETR：チェックポイントの読み取りに torch が必要です。model_path に class_names.txt（1行に1クラス）があれば使用されます。ない場合は、クラス名をチェックポイントの args から取得します。raw PyTorch-Lightning チェックポイントには、さらに rfdetr>=1.8.0 のインストールが必要です（使用中のバージョンが古い場合、SDK のエラーに正確な最小バージョンが示されます）。存在しない filename を明示的に指定すると、エラーになります。デフォルトの weights/best.pt は、トップレベルにある最初の .pt／.pth ファイルにフォールバックし、警告を表示します。
• YOLO-NAS：model_type="yolonas" と、imgsz、batch_size、architecture を含む model_path 内の opt.yaml が必要です。
• PaliGemma／Florence-2：model_path には Hugging Face の保存ディレクトリ（config、tokenizer、重みファイル）を指定します。torch は必要ありません。

アップロードの確認

変換はアップロード後にサーバー側で実行され、通常は数分かかります。MCP の models_list／models_get ツール、または app.roboflow.com/WORKSPACE/PROJECT/models で確認した後、サンプル画像に対してテスト推論を実行し、クラスと予測が正しく見えることを確認してください。