roboflow-custom-weights-upload
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseFor agents: This skill is authored in. If your client already has it loaded as a skill (for example from a Roboflow plugin), use that copy. Theroboflow/computer-vision-skillsMCP resources serve the same skills for clients that don't have them loaded.skill://roboflow/<name>/SKILL.md
对于 Agent: 此 skill 编写于。如果你的客户端已将其作为 skill 加载(例如从 Roboflow 插件加载),请使用该副本。roboflow/computer-vision-skillsMCP resources 为尚未加载这些 skill 的客户端提供相同的 skills。skill://roboflow/<name>/SKILL.md
Custom Weights Upload
自定义权重上传
Register weights from a model trained outside Roboflow (a laptop, a training
server, Colab) so Roboflow can convert, host, and serve it.
注册在 Roboflow 之外训练的模型(笔记本电脑、训练服务器或 Colab 上训练的模型)的权重,使 Roboflow 能够对其进行转换、托管并提供服务。
Where the upload runs
上传在哪里运行
Packaging reads the checkpoint from disk, so the upload always runs on the
machine that has the weights — client-side, with the Python SDK flow below.
The MCP tool is a guide, not an uploader:
calling it returns this recipe and echoes back the arguments you passed
(its field says whether they describe a versioned or a
workspace upload, or when they pin down neither). It never
packages or uploads anything, because the MCP server cannot read the user's
filesystem.
models_custom_weights_upload_guideupload_modeundetermined打包流程会从磁盘读取 checkpoint,因此上传始终在持有权重的机器上运行——也就是在客户端,使用下面的 Python SDK 流程。
models_custom_weights_upload_guideupload_modeundeterminedClient-side upload with the Python SDK
使用 Python SDK 进行客户端上传
Run this on the machine that has the weights, ideally in the same Python
environment used for training (it already has and the matching
).
torchultralytics-
Install the SDK: bothand
roboflow>=1.3.13require Python >= 3.10; checkrfdetrfirst (macOS ships 3.9). If it is too old, create a venv:python3 --version. Thenuv venv --python 3.12 && source .venv/bin/activate.pip install "roboflow>=1.3.13" -
Handle the API key safely: never ask the user to paste a private API key into chat, and never scan dotfiles, shell profiles, or config files hunting for one — permission systems rightly block that. Ifis already set in the environment (
ROBOFLOW_API_KEY) or the working project has atest -n "$ROBOFLOW_API_KEY"that defines it, use it. Otherwise mint a scoped key with the MCP.envtool — it returns the secret once (api_keys_createis the only other tool that does;api_keys_roll/api_keys_listreturn masked metadata) — and write it yourself to aapi_keys_get'd.gitignoreas.env. WritingROBOFLOW_API_KEYdoes not populate.env: load it before running. For aos.environyou just wrote yourself,.envis fine. For a pre-existingset -a; source .env; set +a, never.envit — sourcing executes any shell in the file and exports every other secret it holds into the process. Read only the one key instead, e.g. withsource(python-dotenv) in the script:pip install python-dotenvpythonimport os from dotenv import dotenv_values os.environ["ROBOFLOW_API_KEY"] = dotenv_values(".env")["ROBOFLOW_API_KEY"]Scope the key for the whole deploy flow, not minimally: the SDK'sreads the workspace and its project list before deploying, sorf.workspace()plusproject:readalone fails with missing permissions. Includemodel:deploy,workspace:read,project:read, and for a versioned deploy alsomodel:deployandversion:read. Getting the scopes right at mint time is what protects the upload: the preflight below only confirms the key and the workspace read, not the deploy scope.version:updateIf thecall is denied (permission systems may flag credential creation during an upload task) or unavailable, do not work around the denial. Ask the user to choose: (a) explicitly authorize minting a temporary scoped key, which you revoke withapi_keys_createafter the upload; (b) setapi_keys_revokethemselves in their shell or aROBOFLOW_API_KEY; or (c) point you at an existing.envthat already defines it..env -
Confirm the destination and the name with the user: registering a model is not easily undone. Never infer the target project or version from the checkpoint's class count or filename — ask. The same goes foron a workspace upload: ask the user what the model should be called; do not invent a name.
model_name
在持有权重的机器上运行此流程,最好使用训练所用的同一个 Python 环境(其中已经安装了 和匹配版本的 )。
torchultralytics-
安装 SDK:和
roboflow>=1.3.13均要求 Python >= 3.10;先检查rfdetr(macOS 自带 3.9)。如果版本过旧,请创建 venv:python3 --version。然后执行uv venv --python 3.12 && source .venv/bin/activate。pip install "roboflow>=1.3.13" -
安全处理 API key:绝不要要求用户将 private API key 粘贴到 chat 中,也不要扫描 dotfiles、shell profiles 或 config files 来寻找 key——权限系统理应阻止这种行为。如果环境中已经设置了(
ROBOFLOW_API_KEY),或者 working project 中已有一个定义该变量的test -n "$ROBOFLOW_API_KEY",则直接使用。否则,使用 MCP.envtool 创建一个 scoped key——该工具只会返回一次 secret(api_keys_create是唯一另一个也会返回 secret 的 tool;api_keys_roll/api_keys_list只返回 masked metadata)——并自行将其写入一个已被api_keys_get忽略的.gitignore,内容为.env。写入ROBOFLOW_API_KEY并不会填充.env:运行前必须加载它。对于你刚自行写入的os.environ,可以使用.env。对于已有的set -a; source .env; set +a,绝不执行.env——sourcing 会执行文件中的任意 shell 代码,并将其中保存的所有其他 secret 导出到进程中。改为只读取所需的一个 key,例如在脚本中使用source(python-dotenv):pip install python-dotenvpythonimport os from dotenv import dotenv_values os.environ["ROBOFLOW_API_KEY"] = dotenv_values(".env")["ROBOFLOW_API_KEY"]应为整个 deploy flow 设置 key 的 scope,而不是只授予最小权限:SDK 的会在部署前读取 workspace 及其 project 列表,因此仅具备rf.workspace()和project:read会因权限不足而失败。应包括model:deploy、workspace:read、project:read;对于 versioned deploy,还应包括model:deploy和version:read。在创建时正确设置 scope 才是保护上传的关键:下述 preflight 只确认 key 和 workspace 读取权限,不检查 deploy scope。version:update如果调用被拒绝(权限系统可能会将上传任务期间创建凭据的行为标记为异常)或该工具不可用,不要绕过此拒绝。请让用户选择:(a) 明确授权创建临时 scoped key,上传后使用api_keys_create撤销;(b) 自行在 shell 或api_keys_revoke中设置.env;或 (c) 指向一个已经定义ROBOFLOW_API_KEY的现有ROBOFLOW_API_KEY。.env -
与用户确认目标位置和名称:注册模型不容易撤销。绝不要根据 checkpoint 的 class 数量或 filename 推断目标 project 或 version——应当询问。对于 workspace upload 的也同样如此:询问用户模型应叫什么,不要自行编造名称。
model_name
Preflight before packaging
打包前的 preflight
Packaging plus a 100 MB+ upload is slow; run the cheap checks first and
report every gap at once instead of failing one step at a time:
-
Python is >= 3.10 ().
python3 --version -
Required imports load:for YOLO, RF-DETR, and YOLO-NAS;
torchfor YOLO v8/v10/v11/v12/26;ultralyticsfor raw PyTorch-Lightning RF-DETR checkpoints.rfdetr>=1.8.0 -
The key is valid and covers the workspace read — one cheap call that exercises the same workspace/project-list readstarts with:
deploy_modelpythonimport os from roboflow import Roboflow Roboflow(api_key=os.environ["ROBOFLOW_API_KEY"]).workspace()Be honest about the limit of this check: it does not exercise, which the platform only tests atmodel:deploy, after packaging. That is why step 2 mints the key with the full scope set up front — the preflight catches a bad or under-read key, not a missing deploy scope on an existing key.models/prepareUpload
Only package and upload after all three pass.
Workspace model upload (no dataset version required):
python
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
)Versioned deploy (attach weights to an existing dataset version):
python
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_typeyolov8nyolov11srfdetr-baserfdetr-seg-mediumyolonasrfdetrOn a size/variant or dependency mismatch, /
print the error and then interactively prompt "Would you like to continue
anyway? y/n" — in a headless run the prompt surfaces as an right
after the printed error. Recover by error type:
deploy_modelversion.deployEOFError- Size/variant mismatch: when the error names the type that fits, fix
to it and rerun; when it says the size could not be inferred, pass an explicit size.
model_type - Dependency mismatch: the error names a pip pin, not a model type
(recommends
yolov8, so most current training environments hit this prompt). Install the named version, or — only with the user's explicit confirmation — answerultralytics==8.0.196(headless:y) to continue with the installed version.printf 'y\n' | python upload.py
Never force past either prompt without the user explicitly confirming the
override is intentional.
打包加上 100 MB+ 的上传很慢;先执行开销较低的检查,并一次性报告所有问题,而不是每次只失败一个步骤:
-
Python 版本为 >= 3.10()。
python3 --version -
所需 imports 能够成功加载:YOLO、RF-DETR 和 YOLO-NAS 需要;YOLO v8/v10/v11/v12/26 需要
torch;原始 PyTorch-Lightning RF-DETR checkpoint 需要ultralytics。rfdetr>=1.8.0 -
key 有效且能够读取 workspace——执行一次开销较低的调用,走与启动时相同的 workspace/project-list 读取路径:
deploy_modelpythonimport os from roboflow import Roboflow Roboflow(api_key=os.environ["ROBOFLOW_API_KEY"]).workspace()应如实说明此检查的局限:它不会测试,平台只会在打包后通过model:deploy测试该权限。这就是第 2 步一开始就创建具备完整 scope 的 key 的原因——preflight 只能发现无效或读取权限不足的 key,无法发现现有 key 缺少 deploy scope。models/prepareUpload
仅在三项检查全部通过后才进行打包和上传。
Workspace 模型上传(不需要 dataset version):
python
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
)Versioned deploy(将权重附加到现有 dataset version):
python
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_typeyolov8nyolov11srfdetr-baserfdetr-seg-mediumyolonasrfdetr当 size/variant 或 dependency 不匹配时, / 会打印错误,然后交互式提示 "Would you like to continue anyway? y/n"——在 headless 运行中,该提示会在打印错误后立即以 形式出现。按错误类型进行恢复:
deploy_modelversion.deployEOFError- Size/variant mismatch:如果错误信息指出了匹配的 type,请将 修改为该 type 后重新运行;如果提示无法推断 size,请显式传入 size。
model_type - Dependency mismatch:错误信息会指出 pip pin,而不是 model type(推荐
yolov8,因此大多数当前的训练环境都会触发此提示)。请安装指定的版本,或者——仅在用户明确确认后——回答ultralytics==8.0.196(headless:y),以继续使用当前已安装的版本。printf 'y\n' | python upload.py
除非用户明确确认有意覆盖默认行为,否则绝不要强行越过任何一种提示。
Per-family requirements
各模型系列的要求
- YOLO v8/v10/v11/v12/YOLO26: needs and
torchimportable (ultralyticsrecommendsyolov8; see the dependency-mismatch note above). Legacy YOLO v5/v7/v9: needsultralytics==8.0.196plus antorchinopt.yamlwithmodel_path(orimgsz) andimg_size;batch_sizeis not used. There is no yolov6 support.ultralytics - RF-DETR: needs to read the checkpoint. If a
torch(one class per line) sits inclass_names.txtit is used; otherwise class names come from the checkpoint'smodel_path. Raw PyTorch-Lightning checkpoints additionally needargsinstalled (the SDK's error names the exact minimum if yours is older). An explicitrfdetr>=1.8.0that does not exist is a hard error; the defaultfilenamefalls back to the first top-levelweights/best.pt/.ptfile, with a warning..pth - YOLO-NAS: plus an
model_type="yolonas"inopt.yamlwithmodel_path,imgsz, andbatch_size.architecture - PaliGemma / Florence-2: is the Hugging Face save directory (config, tokenizer, and weights files); no
model_pathneeded.torch
- YOLO v8/v10/v11/v12/YOLO26:需要能够导入 和
torch(ultralytics推荐yolov8;参见上文中的 dependency mismatch 说明)。旧版 YOLO v5/v7/v9:需要ultralytics==8.0.196,并且torch中必须包含带有model_path(或imgsz)和img_size的batch_size;不会使用opt.yaml。不支持 yolov6。ultralytics - RF-DETR:需要 才能读取 checkpoint。如果
torch中存在model_path(每行一个 class),SDK 会使用它;否则,class 名称来自 checkpoint 的class_names.txt。原始 PyTorch-Lightning checkpoint 还需要安装args(如果版本过旧,SDK 的错误信息会指出确切的最低版本)。显式指定但不存在的rfdetr>=1.8.0会触发 hard error;默认的filename会回退到第一个顶层weights/best.pt/.pt文件,并给出 warning。.pth - YOLO-NAS:,并且
model_type="yolonas"中必须包含带有model_path、imgsz和batch_size的architecture。opt.yaml - PaliGemma / Florence-2:是 Hugging Face save directory(包含 config、tokenizer 和 weights 文件);不需要
model_path。torch
Verify the upload
验证上传
Conversion runs server-side after the upload and usually takes a few minutes.
Check it with the MCP / tools or at
, then run a test inference on a
sample image to confirm classes and predictions look right.
models_listmodels_getapp.roboflow.com/WORKSPACE/PROJECT/models转换会在上传后于服务器端运行,通常需要几分钟。通过 MCP / 工具或访问 检查上传结果,然后对 sample image 运行 test inference,确认 classes 和 predictions 看起来正确。
models_listmodels_getapp.roboflow.com/WORKSPACE/PROJECT/models