roboflow-custom-weights-upload

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
For agents: This skill is authored in
roboflow/computer-vision-skills
. If your client already has it loaded as a skill (for example from a Roboflow plugin), use that copy. The
skill://roboflow/<name>/SKILL.md
MCP resources serve the same skills for clients that don't have them loaded.
对于 Agent: 此 skill 编写于
roboflow/computer-vision-skills
。如果你的客户端已将其作为 skill 加载(例如从 Roboflow 插件加载),请使用该副本。
skill://roboflow/<name>/SKILL.md
MCP resources 为尚未加载这些 skill 的客户端提供相同的 skills。

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
models_custom_weights_upload_guide
MCP tool is a guide, not an uploader: calling it returns this recipe and echoes back the arguments you passed (its
upload_mode
field says whether they describe a versioned or a workspace upload, or
undetermined
when they pin down neither). It never packages or uploads anything, because the MCP server cannot read the user's filesystem.
打包流程会从磁盘读取 checkpoint,因此上传始终在持有权重的机器上运行——也就是在客户端,使用下面的 Python SDK 流程。
models_custom_weights_upload_guide
MCP 工具是一份指南,而不是上传器:调用它会返回本操作说明,并回显你传入的参数(其
upload_mode
字段会说明这些参数描述的是 versioned upload 还是 workspace upload;如果两者都未确定,则为
undetermined
)。它绝不会打包或上传任何内容,因为 MCP server 无法读取用户的 filesystem。

Client-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
torch
and the matching
ultralytics
).
  1. Install the SDK: both
    roboflow>=1.3.13
    and
    rfdetr
    require Python >= 3.10; check
    python3 --version
    first (macOS ships 3.9). If it is too old, create a venv:
    uv venv --python 3.12 && source .venv/bin/activate
    . Then
    pip install "roboflow>=1.3.13"
    .
  2. 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. If
    ROBOFLOW_API_KEY
    is already set in the environment (
    test -n "$ROBOFLOW_API_KEY"
    ) or the working project has a
    .env
    that defines it, use it. Otherwise mint a scoped key with the MCP
    api_keys_create
    tool — it returns the secret once (
    api_keys_roll
    is the only other tool that does;
    api_keys_list
    /
    api_keys_get
    return masked metadata) — and write it yourself to a
    .gitignore
    'd
    .env
    as
    ROBOFLOW_API_KEY
    . Writing
    .env
    does not populate
    os.environ
    : load it before running. For a
    .env
    you just wrote yourself,
    set -a; source .env; set +a
    is fine. For a pre-existing
    .env
    , never
    source
    it — 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. with
    python-dotenv
    (
    pip install python-dotenv
    ) in the script:
    python
    import 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's
    rf.workspace()
    reads the workspace and its project list before deploying, so
    project:read
    plus
    model:deploy
    alone fails with missing permissions. Include
    workspace:read
    ,
    project:read
    ,
    model:deploy
    , and for a versioned deploy also
    version:read
    and
    version:update
    . 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.
    If the
    api_keys_create
    call 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 with
    api_keys_revoke
    after the upload; (b) set
    ROBOFLOW_API_KEY
    themselves in their shell or a
    .env
    ; or (c) point you at an existing
    .env
    that already defines it.
  3. 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 for
    model_name
    on a workspace upload: ask the user what the model should be called; do not invent a name.
在持有权重的机器上运行此流程,最好使用训练所用的同一个 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 key:绝不要要求用户将 private API key 粘贴到 chat 中,也不要扫描 dotfiles、shell profiles 或 config files 来寻找 key——权限系统理应阻止这种行为。如果环境中已经设置了
    ROBOFLOW_API_KEY
    (
    test -n "$ROBOFLOW_API_KEY"
    ),或者 working project 中已有一个定义该变量的
    .env
    ,则直接使用。否则,使用 MCP
    api_keys_create
    tool 创建一个 scoped key——该工具只会返回一次 secret(
    api_keys_roll
    是唯一另一个也会返回 secret 的 tool;
    api_keys_list
    /
    api_keys_get
    只返回 masked metadata)——并自行将其写入一个已被
    .gitignore
    忽略的
    .env
    ,内容为
    ROBOFLOW_API_KEY
    。写入
    .env
    并不会填充
    os.environ
    :运行前必须加载它。对于你刚自行写入的
    .env
    ,可以使用
    set -a; source .env; set +a
    。对于已有的
    .env
    ,绝不执行
    source
    ——sourcing 会执行文件中的任意 shell 代码,并将其中保存的所有其他 secret 导出到进程中。改为只读取所需的一个 key,例如在脚本中使用
    python-dotenv
    (
    pip install python-dotenv
    ):
    python
    import os
    from dotenv import dotenv_values
    
    os.environ["ROBOFLOW_API_KEY"] = dotenv_values(".env")["ROBOFLOW_API_KEY"]
    应为整个 deploy flow 设置 key 的 scope,而不是只授予最小权限:SDK 的
    rf.workspace()
    会在部署前读取 workspace 及其 project 列表,因此仅具备
    project:read
    和
    model:deploy
    会因权限不足而失败。应包括
    workspace:read
    、
    project:read
    、
    model:deploy
    ;对于 versioned deploy,还应包括
    version:read
    和
    version:update
    。在创建时正确设置 scope 才是保护上传的关键:下述 preflight 只确认 key 和 workspace 读取权限,不检查 deploy scope。
    如果
    api_keys_create
    调用被拒绝(权限系统可能会将上传任务期间创建凭据的行为标记为异常)或该工具不可用,不要绕过此拒绝。请让用户选择:(a) 明确授权创建临时 scoped key,上传后使用
    api_keys_revoke
    撤销;(b) 自行在 shell 或
    .env
    中设置
    ROBOFLOW_API_KEY
    ;或 (c) 指向一个已经定义
    ROBOFLOW_API_KEY
    的现有
    .env
    。
  3. 与用户确认目标位置和名称:注册模型不容易撤销。绝不要根据 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:
  1. Python is >= 3.10 (
    python3 --version
    ).
  2. Required imports load:
    torch
    for YOLO, RF-DETR, and YOLO-NAS;
    ultralytics
    for YOLO v8/v10/v11/v12/26;
    rfdetr>=1.8.0
    for raw PyTorch-Lightning RF-DETR checkpoints.
  3. The key is valid and covers the workspace read — one cheap call that exercises the same workspace/project-list read
    deploy_model
    starts with:
    python
    import 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
    model:deploy
    , which the platform only tests at
    models/prepareUpload
    , 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.
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_type
must name the real architecture (
yolov8n
,
yolov11s
,
rfdetr-base
,
rfdetr-seg-medium
,
yolonas
, a supported PaliGemma or Florence-2 type). For YOLO families the SDK infers a missing size suffix from the weights; RF-DETR accepts no bare
rfdetr
— pass the exact variant, which the SDK cross-checks against the checkpoint.
On a size/variant or dependency mismatch,
deploy_model
/
version.deploy
print the error and then interactively prompt "Would you like to continue anyway? y/n" — in a headless run the prompt surfaces as an
EOFError
right after the printed error. Recover by error type:
  • Size/variant mismatch: when the error names the type that fits, fix
    model_type
    to it and rerun; when it says the size could not be inferred, pass an explicit size.
  • Dependency mismatch: the error names a pip pin, not a model type (
    yolov8
    recommends
    ultralytics==8.0.196
    , so most current training environments hit this prompt). Install the named version, or — only with the user's explicit confirmation — answer
    y
    (headless:
    printf 'y\n' | python upload.py
    ) to continue with the installed version.
Never force past either prompt without the user explicitly confirming the override is intentional.
打包加上 100 MB+ 的上传很慢;先执行开销较低的检查,并一次性报告所有问题,而不是每次只失败一个步骤:
  1. Python 版本为 >= 3.10(
    python3 --version
    )。
  2. 所需 imports 能够成功加载:YOLO、RF-DETR 和 YOLO-NAS 需要
    torch
    ;YOLO v8/v10/v11/v12/26 需要
    ultralytics
    ;原始 PyTorch-Lightning RF-DETR checkpoint 需要
    rfdetr>=1.8.0
    。
  3. key 有效且能够读取 workspace——执行一次开销较低的调用,走与
    deploy_model
    启动时相同的 workspace/project-list 读取路径:
    python
    import os
    from roboflow import Roboflow
    
    Roboflow(api_key=os.environ["ROBOFLOW_API_KEY"]).workspace()
    应如实说明此检查的局限:它不会测试
    model:deploy
    ,平台只会在打包后通过
    models/prepareUpload
    测试该权限。这就是第 2 步一开始就创建具备完整 scope 的 key 的原因——preflight 只能发现无效或读取权限不足的 key,无法发现现有 key 缺少 deploy scope。
仅在三项检查全部通过后才进行打包和上传。
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_type
必须指定真实架构(
yolov8n
、
yolov11s
、
rfdetr-base
、
rfdetr-seg-medium
、
yolonas
、受支持的 PaliGemma 或 Florence-2 type)。对于 YOLO 系列,SDK 可以从权重推断缺失的 size suffix;RF-DETR 不接受仅写
rfdetr
——必须传入确切的 variant,SDK 会将其与 checkpoint 交叉核验。
当 size/variant 或 dependency 不匹配时,
deploy_model
/
version.deploy
会打印错误,然后交互式提示 "Would you like to continue anyway? y/n"——在 headless 运行中,该提示会在打印错误后立即以
EOFError
形式出现。按错误类型进行恢复:
  • Size/variant mismatch:如果错误信息指出了匹配的 type,请将
    model_type
    修改为该 type 后重新运行;如果提示无法推断 size,请显式传入 size。
  • Dependency mismatch:错误信息会指出 pip pin,而不是 model type(
    yolov8
    推荐
    ultralytics==8.0.196
    ,因此大多数当前的训练环境都会触发此提示)。请安装指定的版本,或者——仅在用户明确确认后——回答
    y
    (headless:
    printf 'y\n' | python upload.py
    ),以继续使用当前已安装的版本。
除非用户明确确认有意覆盖默认行为,否则绝不要强行越过任何一种提示。

Per-family requirements

各模型系列的要求

  • YOLO v8/v10/v11/v12/YOLO26: needs
    torch
    and
    ultralytics
    importable (
    yolov8
    recommends
    ultralytics==8.0.196
    ; see the dependency-mismatch note above). Legacy YOLO v5/v7/v9: needs
    torch
    plus an
    opt.yaml
    in
    model_path
    with
    imgsz
    (or
    img_size
    ) and
    batch_size
    ;
    ultralytics
    is not used. There is no yolov6 support.
  • RF-DETR: needs
    torch
    to read the checkpoint. If a
    class_names.txt
    (one class per line) sits in
    model_path
    it is used; otherwise class names come from the checkpoint's
    args
    . Raw PyTorch-Lightning checkpoints additionally need
    rfdetr>=1.8.0
    installed (the SDK's error names the exact minimum if yours is older). An explicit
    filename
    that does not exist is a hard error; the default
    weights/best.pt
    falls back to the first top-level
    .pt
    /
    .pth
    file, with a warning.
  • YOLO-NAS:
    model_type="yolonas"
    plus an
    opt.yaml
    in
    model_path
    with
    imgsz
    ,
    batch_size
    , and
    architecture
    .
  • PaliGemma / Florence-2:
    model_path
    is the Hugging Face save directory (config, tokenizer, and weights files); no
    torch
    needed.
  • YOLO v8/v10/v11/v12/YOLO26:需要能够导入
    torch
    和
    ultralytics
    (
    yolov8
    推荐
    ultralytics==8.0.196
    ;参见上文中的 dependency mismatch 说明)。旧版 YOLO v5/v7/v9:需要
    torch
    ,并且
    model_path
    中必须包含带有
    imgsz
    (或
    img_size
    )和
    batch_size
    的
    opt.yaml
    ;不会使用
    ultralytics
    。不支持 yolov6。
  • RF-DETR:需要
    torch
    才能读取 checkpoint。如果
    model_path
    中存在
    class_names.txt
    (每行一个 class),SDK 会使用它;否则,class 名称来自 checkpoint 的
    args
    。原始 PyTorch-Lightning checkpoint 还需要安装
    rfdetr>=1.8.0
    (如果版本过旧,SDK 的错误信息会指出确切的最低版本)。显式指定但不存在的
    filename
    会触发 hard error;默认的
    weights/best.pt
    会回退到第一个顶层
    .pt
    /
    .pth
    文件,并给出 warning。
  • YOLO-NAS:
    model_type="yolonas"
    ,并且
    model_path
    中必须包含带有
    imgsz
    、
    batch_size
    和
    architecture
    的
    opt.yaml
    。
  • PaliGemma / Florence-2:
    model_path
    是 Hugging Face save directory(包含 config、tokenizer 和 weights 文件);不需要
    torch
    。

Verify the upload

验证上传

Conversion runs server-side after the upload and usually takes a few minutes. Check it with the MCP
models_list
/
models_get
tools or at
app.roboflow.com/WORKSPACE/PROJECT/models
, then run a test inference on a sample image to confirm classes and predictions look right.
转换会在上传后于服务器端运行,通常需要几分钟。通过 MCP
models_list
/
models_get
工具或访问
app.roboflow.com/WORKSPACE/PROJECT/models
检查上传结果,然后对 sample image 运行 test inference,确认 classes 和 predictions 看起来正确。