platform-cli

平台 CLI（ul cloud）

ul 需要 Python 3.11+，可通过 pip install ultralytics 或 pip install ultralytics-platform 安装。ul cloud <resource> <operation> 通过生成的 SDK 调用平台 API；ul login、ul train、ul predict、ul cloud train|predict|export|download 快捷命令（参见 yolo）以及其他本地命令则委托给 ultralytics 包。此技能涵盖平台操作，不涉及模型选择或超参数调优。

pip install ultralytics                   # or `pip install ultralytics-platform`
export ULTRALYTICS_API_KEY="YOUR_API_KEY" # or `ul login API_KEY`
ul cloud --help                           # every resource and operation
ul cloud training start --help            # one operation's arguments, types, and choices

规范命令形式

ul cloud account summary # plan, credits, counts; `username` is your workspace
ul cloud datasets list   # omit owner= for your own workspace; owner=TEAM for a team
ul cloud projects create project=helmets name="Helmet Detection" visibility=private
ul cloud models create body='{"owner":"WS","project":"helmets","model":"exp1","name":"Experiment 1"}'
ul cloud training start model_id=MODEL_ID gpu_type=l4 \
  train_args='{"model":"yolo26n.pt","data":"ul://WS/datasets/helmets","epochs":50}'
ul cloud models training project=helmets model=exp1 # live status, epoch progress, metrics
ul cloud models files project=helmets model=exp1    # short-lived weights download URL

参数规则：

• 使用此处展示的命令形式，不要预先调用 --help。缺少必需参数或出现参数错误后，再查看操作帮助。
• 参数使用 SDK 的 Python 名称，以 key=value 的形式传入（gpu_type、project_id），不要使用 --key value。布尔键若不带 =value，则表示 true。在 shell 中为 JSON 加引号。
• 只有当操作帮助列出 body (dict[str, Any]) 时，操作才接受一个 body= JSON 对象。这些操作的 API 请求是多种形状的联合类型：models create、deployments update、images update、lifecycle delete-trash、datasets ingest、datasets create-batch、upload signed-url、storage-integrations create/discover，以及 models predict/deployments predict。其他所有操作都接受扁平字段；train_args、metadata 和 args 等嵌套对象仍是 JSON 值。
• 对象和数组值接受 @file.json 或用于从标准输入读取的 @-。预测的 file 字段等多部分二进制数据只接受 @path。
• 对于 body 键和值类型，只读取请求 schema，例如生产契约 https://platform.ultralytics.com/openapi.json 中的 paths["/api/models"].post.requestBody，不要猜测或加载整个文件。

行为规则：

• 完整 API 响应会根据其内容类型，以 JSON、文本或字节形式打印到标准输出。下载操作返回的是会过期的签名 URL，而非字节：datasets export、datasets create-export、models files 和已完成的 exports retrieve。请原样保留这些 URL，并单独获取内容。
• 错误会输出到标准错误：API/连接错误的退出码为 1，参数/文件错误为 2，中断时为 130。中断不会取消已提交的任务；请使用相应的取消操作（models delete-training、exports delete、datasets delete-batch）。
• 不支持 --json、--fields、--dry-run 或自动分页。datasets list（limit、include_samples、include_image_urls）和 projects list（limit）不接受 offset 或 search；传入 include_samples=false 可缩小数据集列表。models list 必须提供 project=。支持分页的操作会提供 page、offset、cursor 或 page_token。请持续使用返回的续页字段，直到没有更多结果。仅指定 limit 的列表仍可能不完整。
• 若路径中省略 owner，则在查询一次账户后，默认使用已登录的用户名。对于团队工作区，请传入 owner=TEAM。账户、账单、回收站、存储集成和 Roboflow 命令操作的是凭据所属账户；API 密钥的 account summary 不会列出团队。
• 显示名称、URL slug、数据库 ID 和 URI 各不相同。训练数据使用 ul://OWNER/datasets/DATASET；初始权重使用检查点名称或 ul://OWNER/PROJECT/MODEL。将返回的 ID 和 slug 用于后续命令；缺少标识符时请先检索，不要根据名称或 URL 推断。检索具名数据集或项目之前，请从其列表中获取 slug。

工作方法

1. 确定所需结果和目标。使用明确提供的标识符；否则列出并选择一个无歧义的匹配项。如果有多个匹配项，请检查用于区分的元数据；如果目标或后果仍有歧义，请先询问。找不到指定资源时，应明确说明并提供最接近的匹配项；绝不能用其他资源替代。范围有限的列表无法证明资源不存在；应扩大搜索范围，或说明已搜索的范围。查找用户指定的工作区中的数据集；查找新的公开数据集时，使用 explore search q=... type=datasets，每次使用一个简短关键词（先试 aerial，再试 UAV），并通过 task= 缩小范围。Explore 数据集搜索会按 sort 顺序列出名称中匹配自动补全词条的内容，之后列出图像内容与搜索词匹配的数据集；项目搜索则匹配字面子字符串。推荐公开数据集用于训练之前，请验证其是否符合克隆条件、是否有标签，以及是否包含数据拆分。如果没有匹配项或搜索失败，请如实说明。
2. 如果当前状态会影响变更（可见性、状态、现有子项），请先读取当前状态。
3. 执行用户要求的最小变更，然后根据响应进行验证。如果响应未提供所需状态、写入结果不确定，或任务是异步的，请再次检索。
4. 报告实际变更、当前状态、警告，以及可用时已验证的资源链接。创建条目、接受任务和完成任务是不同的结果。

清楚要求执行的操作，无需反复确认。对于涉及支出、共享或不可逆的变更，应先消除目标或后果方面的歧义。用户请求建议并不代表授权执行；“整理一下”不等于允许删除整个账户的内容。不要编造命令、标志或状态编辑来模拟 CLI 未提供的操作；遇到这种情况，请引导用户使用 Platform UI。

工作流

以下命令省略了 ul cloud 前缀和默认的 owner。

目标	命令
清点	projects list、datasets list、models list project=P。explore search q=... type=datasets 用于搜索公开内容，并非私有清单。检索数据集以查看任务、类别、数据划分和就绪状态。
创建	projects create project=slug name="Display"、datasets create dataset=slug name="Display" task=detect。请谨慎设置 visibility=。
复制	datasets clone dataset=D owner_body=DEST_OWNER、projects clone project=P owner_body=DEST_OWNER、models clone project=P model=M owner_body=DEST_OWNER project_body=DEST_PROJECT。路径字段指定源；*_body 字段指定目标。模型的目标项目必须已存在。
重命名、编辑、移动	通过 <resource> update 仅传入更改的字段；新的 name 也会更改 URL slug，因此之后请使用返回的 slug。移动模型时，使用 models update project=P model=M project_id=DEST_ID，且只更改此字段。
比较运行	使用 projects retrieve project=P 查看模型摘要，models list project=P，或 datasets models dataset=D 查看数据集上的运行；只有指标缺失时才使用 models retrieve project=P model=M。将状态、数据集/版本、配置和所需指标制成表格并附上链接。缺失的指标表示未知，而非零。没有比较命令。
分析模型	models retrieve project=P model=M analysis=1，然后在需要时运行 models find-similar-training-images project=P model=M。有关覆盖范围和哈希选择，请参阅模型分析与相似度。
权重	models files project=P model=M 返回临时检查点 URL。无需训练或导出。
转换	exports create project=P model=M format=onnx，然后运行 exports retrieve project=P model=M export_id=ID 查看进度和下载 URL。format=engine 需要 gpu_type。导出不会部署模型。
数据集版本	datasets create-export dataset=D 会保存带有签名 NDJSON URL 的不可变编号快照；datasets export dataset=D（已保存的版本使用 v=N）会返回下载 URL；datasets restore dataset=D version=N 会将数据集回滚；datasets update-export dataset=D version=N description="TEXT" 会更新已保存版本的描述。
部署	deployments create project=P model=M deployment=slug name="Display" region=us-central1。deployments update deployment=D body='{"action":"replace","project":"P","model":"M"}' 会在同一 URL 上替换模型；body='{"action":"stop"}' 和 {"action":"start"} 会分别暂停和恢复部署。deployments health deployment=D 会预热部署。
用量、服务	account storage、billing usage-summary 和 billing transactions 用于查看凭据所属账户的用量；deployments list、retrieve、logs 和 metrics 用于查看端点。有关筛选条件和分页，请参阅用量与计费和计算。
推理	models predict project=P model=M body='{"file":"@image.jpg"}' 或 deployments predict deployment=D body='{"file":"@image.jpg"}'。images predict image_id=ID model_id=ul://... 可对数据集图像进行预测，而不保存标签。
Agent	agents save name="Display" graph='{...}' version=0 会创建画布 Agent；请先阅读 agents save --help 了解区块。请使用真实的数据集、模型、部署和可检测类别；修复返回的 errors。编辑：通过 agents list id=ID 读取当前 graph 和 version，然后使用完整的编辑后图运行 agents save id=ID name=N version=V graph='{...}'。
导入数据	datasets create dataset=D name="Display"，然后对单个 .zip、.tar、.tar.gz、.tgz 或 .ndjson 文件运行 upload signed-url body=（字段为 assetType、assetId、filename、contentType、totalBytes），使用返回的标头 PUT 文件内容，再运行 datasets ingest dataset=D body='{"sessionId":"S"}'（完成上传；也可使用 {"sourceUrl":...}），随后持续检索，直到状态就绪。已排队不代表已导入。
回收站	projects delete project=P、datasets delete dataset=D 和 models delete project=P model=M 会将其移至保留 30 天的回收站。lifecycle trash 会列出回收站内容；lifecycle restore id=ID type=model 会恢复删除项；lifecycle delete-trash body='{"id":"ID","type":"model"}' 会永久删除单个项目；body='{"all":true}' 会永久清空整个工作区的回收站。

云端训练

1. 确认工作区、项目、已就绪的数据集、起始权重和所需设置。选择 gpu_type 前，先检查 training gpu-availability。云端训练会消耗额度。data 必须使用数据集的实际所有者，该所有者可能与模型的所有者不同。
2. 使用 models create body=... 创建新实验，并提供 owner、project、model slug 和 name。对于启动失败后留下的待处理条目，先检查其状态，再决定是否复用。
3. 使用 training start model_id=ID gpu_type=... train_args=...，其中 train_args 应为新建的参数，包含 model、data、数值类型的 epochs 以及所需设置。省略 device。不要原样复制已保存的 worker 参数；保存的数据路径可能仅在 worker 本地有效。
4. 使用 models training 或 models retrieve 查看进度。返回运行链接和实际状态，除非用户要求，否则不要等待任务完成。models delete-training 会取消运行并保留条目；对于运行仍处于活动状态的模型，绝不要调用 training start。

恢复处理

• 401：检查凭据来源，但不要泄露机密。ULTRALYTICS_API_KEY 会覆盖已保存的登录密钥，因此重新登录不会替换过期的环境变量值。如果执行环境会注入凭据，请使用该环境提供的流程。之后通过读取操作进行验证。
• 403：查看错误信息，确认是工作区访问、权限还是操作限制；不要假设是登录过期。
• 对于明确的验证错误，在所请求的操作范围内修正。超时或写入结果不确定时，重试前先检查状态。如果输入、权限问题仍未解决，或反复失败，请停止操作；报告部分结果和剩余工作，不要重复写入。

资源链接

资源链接使用 https://platform.ultralytics.com：项目为 /{owner}/{project}，数据集为 /{owner}/datasets/{dataset}，模型和训练为 /{owner}/{project}/{model}，部署为 /{owner}/deploy/{deployment}，其中 {deployment} 使用返回的 deployment slug。状态变为 ready 后，报告 deployments retrieve 返回的确切 serviceUrl，以供推理使用；绝不要自行构造服务 URL。

操作注意事项

操作帮助已说明每条命令的功能。以下是帮助中未提及的副作用和限制；若与之不符，以 --help 和错误文本为准。

克隆

• 项目、数据集和模型只能克隆到不同的目标工作区。克隆不能用于在同一工作区创建实验；请使用 models create。
• 模型源必须包含可用权重，且不能正在训练。项目克隆会包含已完成且带有权重的模型，但不包含数据集、部署、导出内容或未完成的运行。

可见性

• 创建时可能默认设为公开，克隆时也可能沿用源对象的可见性，因此请明确设置 visibility=。公开项目会公开其模型。公开可见不代表协作者拥有编辑权限。

更新

• 数组和 metadata 对象会替换之前的值。请发送完整的数组或对象，包括未更改的条目。
• 如果更新中包含 starred，其他所有字段都会被忽略；请单独发送该字段。
• 对现有模型再次启动训练会清除之前的运行指标和结果。若要保留这些内容，请创建新模型。使用现有权重进行微调不会恢复优化器状态或轮次计数。
• capture_dataset_version=true 会保存新的快照；它不会选择现有快照。

删除、移入回收站、恢复

• lifecycle delete-trash 不可逆。只有在用户明确要求永久删除指定项目时才运行；body='{"all":true}' 需要用户明确要求清空整个工作区的回收站。否则，应将清空操作留给用户在 UI 中完成。
• projects update archived=true 仅用于整理，不会释放任何空间。
• 将项目移入回收站也会将其模型移入回收站，并取消这些模型的训练。projects delete 和 models delete 会在移入回收站的操作期间永久删除关联的部署；恢复项目或模型不会恢复部署。如果存在关联部署（lifecycle trash id=ID type=project 或 type=model 会预览这些部署），除非用户的请求已经涵盖永久删除这些部署，否则应说明这一后果并取得明确授权后再移入回收站。502 响应表示清理未完成；在报告部署已删除前，应检查部署状态。
• 先恢复父项，再恢复其子项；单独移入回收站的子项需要单独恢复。数据集版本的恢复是独立操作：datasets restore dataset=D version=N 会用所选快照替换当前图像、划分、类别和标注。除非事先为当前状态创建了版本，否则无法撤销此操作。如果需要保留当前状态，请先运行 datasets create-export dataset=D。恢复前请停止正在进行的标注，然后等待数据集恢复到 ready 状态。
• images delete 和 images delete-bulk 会永久删除图像，且不会经过回收站。
• datasets create-export 会复用相同的现有快照，而不是创建副本。

标签和自动标注

• images update body='{"labels":[...]}' 会替换图像上的所有标签，而单独运行 images predict 不会保存任何内容。进行部分编辑前，请先检索图像；如果检索结果报告 labelsTruncated，请勿更新该图像的标签，因为替换操作会删除未显示的标签。
• datasets create-batch dataset=D body='{"modelId":"ul://OWNER/PROJECT/MODEL"}' 会为未标注的图像自动添加标签、持久化标签并保存一个版本。对于含有 1–200 个类别的检测数据集，modelId 也可以是一个托管模型，并以类别名称作为提示词：sam3.1（SAM 3.1 Text）、sam3、moondream、qwen、florence2、owlv2、yoloe26x 或 groundingdino。在请求体中添加 "includeAnnotated":true，也可处理已标注的图像（保留其现有标签）。datasets delete-batch 会取消或关闭一次运行，但不会撤销已保存的标签。
• datasets create-batch dataset=D body='{"operation":"blur"}' 会模糊数据集中的人脸（如果请求体包含 "imageId"，则只处理单张图像），且不保存版本；如果需要保留原始图像，请先运行 datasets create-export。
• 标注预测需要任务和类别兼容，或提供显式映射：对 images predict 使用 class_mapping=，对 datasets create-batch 在 body= 中使用 classMapping。该操作不支持 connected、depth 和通道数超过 3 的数据集。

类别、划分和任务

• class_names 按索引替换名称；重命名时请保持顺序不变。合并或删除类别会重新映射或移除标签，并调整 ID。
• datasets redistribute-splits 会重新划分整个数据集。images update-bulk 会移动所选 ID，而冲突策略 replace 可能会移除目标图像。
• datasets adopt-images 会将图像引用作为未标注的训练图像添加，并跳过已有图像；只有 release=false（复制）、release=true（移动）或 class_mapping 会从你有权编辑的数据集中带入标签、元数据和划分。
• 更改 task 不会转换任何标注。切换到或切换出 depth 任务时，数据集必须为空。

数据集检查与分析

• 要检查重复项或数据集划分泄漏，请按哈希值对所有图像记录分组，并比较 ID 和数据集划分。存储去重并不能防止记录重复。请使用较小的分页或下载的导出文件；如果记录缺失或被截断，请报告覆盖不完整，而不是报告重复数为零。
• datasets retrieve dataset=D 返回任务、类别、数据集划分和计数。datasets class-stats dataset=D 返回分布和热力图；如果设置了 sampleSize，则表示统计数据来自有上限的子集，每个直方图区间的 size 表示其宽度。在 objectsPerImageHistogram 中，bin 是下限：bin=0, size=6 统计的是包含 0–5 个对象的图像，而不只是零对象图像。要获取未标注图像数量，请使用 datasets images dataset=D has_label=false limit=1 并读取 total。
• 使用 datasets images dataset=D 列出数据集的图像（没有 images list）；该命令支持按 split、has_label、has_error、class_ids 和 search 过滤。若只需计数，请使用 limit=1 并读取 total（默认包含），而不是读取当前页长度。has_error 表示存在已记录的处理错误。传入 include_thumbnails=false 可缩小清单页面（include_image_urls 和 include_labels 默认关闭）；在 hasMore 为 true 时，将 nextCursor 作为 cursor 传入。游标仅适用于 newest 或 oldest 排序（包括默认排序）；其他排序方式使用 offset 分页。相同的 hash 值表示存储的字节相同，不代表视觉相似。
• search=TERM 会匹配文件名（扩展名可选）的子字符串、类别名称，以及元数据键、标量值和数组条目，但不会匹配嵌套对象中的值。没有字段选择器；请检索匹配结果，以确认命中的是哪个字段。32 位十六进制词条会与内容 hash 精确匹配，24 位十六进制词条会与图像 ID 匹配，因此 search=HASH 无需导出即可找到图像的所有存储副本。
• 列表不会包含自定义 metadata；images retrieve image_id=ID 会连同标签一起返回这些元数据。列表和检索结果都可能截断标签：请留意 labelsTruncated，并将返回长度与 labelCount 或检索结果中的 properties.annotationCount 比较。datasets selected-images dataset=D image_ids='["ID1","ID2"]' 可在一次调用中获取多个已知 ID，而不必分别调用 images retrieve；它接受与 datasets images 相同的 include_* 选项。images urls image_ids='["ID1","ID2"]' 可刷新一个数据集内最多 100 个 ID 的签名 URL。datasets export dataset=D 提供 NDJSON 元数据和标注，供批量汇总使用；On Premise 数据集无法导出。
• images find-similar-images image_id=ID 会从公共数据集、你自己的数据集和团队数据集中返回最多 24 个近邻，但会排除源数据集已包含的图像以及查询图像的近重复副本。该命令只接受已存在的图像 ID，并且需要身份验证。没有嵌入的图像会按需生成嵌入，这可能需要几分钟；503 表示准备失败，请重试。
• datasets embeddings dataset=D 报告分析的新鲜度和进度。datasets clustering dataset=D 返回 2D UMAP 坐标点，而不是原始嵌入；在 hasMore 为 true 时，将 nextOffset 作为 offset 传入，包括使用默认页面大小时。not_analyzed 表示不存在布局；请使用返回的 ID，通过 datasets selected-images 获取详情。datasets create-embeddings 会启动分析；datasets delete-embeddings 会取消分析，但不会删除图像。

模型分析与相似度

• models retrieve project=P model=M analysis=1 需要身份验证，并返回每张图像的验证 analysis，而非模型详情；null 表示分析不可用。必须有已完成且记录了每张图像结果的检测运行；如果缺少数据集版本或清单，则会返回分数，并将 traitsAvailable=false 和 coverage.mode="unavailable"，而不是返回 null 分析。进行概括前，请比较 population 与 retained，并查看 coverage.mode：只有 full 才涵盖所有验证图像。traitsAvailable 决定是否提供 comparisons（图像特征与 F1 的对比）；cohorts.worst 和 .best 会给出整个队列的 count 和 metrics，但 examples 中只有前 100 行，其标签来自运行保存的清单，而非当前数据集。scatterSample.rows 是 [f1, width, height, pixels, aspectRatio, instanceCount] 点。每张图像的 tp/fp/fn/f1 使用 IoU 0.50 和运行时未记录的置信度阈值，因此无法据此重算其他阈值下的指标。诊断性能不佳前，请先检查模型报告的精确率/召回率；这些计数本身既无法确定部署精确率，也无法解释某个特定的假阳性。
• models find-similar-training-images project=P model=M 根据运行中验证效果最差的图像，在公共数据集、你自己的数据集和团队数据集中搜索图片，并排除模型训练数据集中已有的图片。请使用有权访问该模型工作区的凭据。此命令会返回候选图片，但不会将其添加到数据集中。hashes=H1,H2 中的值必须全部来自 analysis.cohorts.worst.examples[].hash；任何其他哈希都会导致整个请求被拒绝。未捕获队列的运行会返回空列表；缺少运行/数据集标识符或嵌入不可用时则会报错。

已连接的存储

• 已连接的数据集（云存储或本地部署）会原地建立索引，不会被复制。这些数据集不能追加上传、创建版本或克隆，也不能进行批量标注或新的嵌入分析；不要为了获取缺失的聚类布局而启动分析。
• 断开集成后，提供商的对象仍会保留，但在同一账户重新连接之前，无法访问数据集。Roboflow 凭据与 Platform 凭据相互独立。

使用情况与计费

• account storage 会以 usage.<resource>.current/limit/percent 的形式返回配额，其中 limit=-1 表示不限量；details=true 会额外返回最大的 10 个 breakdown.topItems，而非完整清单。billing usage-summary 会返回套餐用量和额度。
• billing transactions from_=START to=END 使用的是 from_，而非 from；并且需要完整的 ISO 日期时间，例如 2026-09-01T00:00:00Z；仅有日期会被拒绝。时间戳位于 createdAt 中。

计算资源

• 编辑模型的 status 不会启动或停止任何内容。
• deployments list model=P/M 按项目中的模型筛选，而非按模型 ID 或单独的名称筛选。请将返回的 deployment slug 用于 deployments retrieve、logs 和 metrics。日志通过 nextPageToken 进行分页，并将其作为 page_token 使用；metrics range= 用于选择时间范围，sparkline=true 则会返回精简版仪表板摘要，而非完整响应。
• Deployment delete 操作不可逆；deployment 没有回收站。
• Export delete 会取消正在进行的转换，或删除已完成的文件；源模型不受影响。

已安装的 CLI 才是权威依据：ul version 会显示版本，ul cloud <resource> <operation> --help 会列出有效参数和选项，遇到冲突时应以错误文本为准，而不是本文件中的命令格式或注意事项。对于端点语义，Platform API 参考 和实时 /openapi.json 的说明优先于记忆。