roboflow-custom-weights-upload

**面向 Agent：**此技能由 roboflow/computer-vision-skills 编写。如果你的客户端已将其作为技能加载（例如来自 Roboflow 插件），请使用该副本。对于尚未加载这些技能的客户端，roboflow://skills/<name>/... MCP 资源提供相同的技能。

自定义权重上传

注册在 Roboflow 之外（笔记本电脑、训练服务或 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 密钥，也绝不要扫描点文件、shell 配置文件或配置文件来寻找密钥——权限系统会合理地阻止此类操作。如果环境中已设置 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——这会执行文件中的任意 shell 命令，并将其中包含的所有其他密钥导出到进程中。应只读取这一个密钥，例如在脚本中使用 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) 由用户自行在 shell 或 .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；原始 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 阶段测试该权限。因此，第 2 步会预先为密钥授予完整的权限范围——预检查能发现密钥无效或读取权限不足，但无法发现现有密钥缺少部署权限。

只有三项检查全部通过后，才进行打包和上传。

工作区模型上传（无需数据集版本）：

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 会打印错误，然后以交互方式提示“Would you like to continue anyway? 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，并且 model_path 中要有一个包含 imgsz（或 img_size）和 batch_size 的 opt.yaml；不使用 ultralytics。不支持 yolov6。
• RF-DETR：需要 torch 来读取检查点。如果 model_path 中有 class_names.txt（每行一个类别），则使用该文件；否则从检查点的 args 中获取类别名称。原始 PyTorch-Lightning 检查点还需要安装 rfdetr>=1.8.0（如果你的版本较旧，SDK 错误会指出准确的最低版本）。指定的 filename 不存在时会直接报错；默认的 weights/best.pt 会回退到第一个顶层 .pt / .pth 文件，并发出警告。
• YOLO-NAS：model_type="yolonas"，且 model_path 中需要有一个包含 imgsz、batch_size 和 architecture 的 opt.yaml。
• PaliGemma / Florence-2：model_path 是 Hugging Face 保存目录（包含 config、tokenizer 和权重文件）；不需要 torch。

验证上传

上传后会在服务端执行转换，通常需要几分钟。请使用 MCP models_list / models_get 工具或访问 app.roboflow.com/WORKSPACE/PROJECT/models 检查，然后在示例图像上运行测试推理，确认类别和预测结果正确。