roboflow-batch-processing

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

批处理

在 Roboflow 的自动扩缩计算资源上，对大量图像或视频运行 Roboflow Workflow。每个作业都会处理一个临时的 Data Staging 批次；两种输入路径的区别仅在于由谁填充该批次：

• Asset Library 作业 — 文件已在 Roboflow 中。你向平台提供所选文件，平台会为你选择并暂存这些文件。
• 暂存作业 — 文件位于 Roboflow 之外（本地磁盘、云存储桶、引用文件），因此你需要使用 inference-cli 自行暂存：只有你的机器和凭据能够访问这些文件。文件不会导入工作区，暂存数据会在约 7 天后过期。

该选哪条路径？三个问题

1. 文件是否已在 Roboflow 中（Asset Library）？ 使用稳定的幂等键，并且仅指定一种选择方式：image_ids、query 或 all_images=true，然后调用 batch_processing_asset_library_job_create。平台会执行访问检查、选择文件、暂存文件、验证 Workflow 兼容性、计费并注册持久作业。轮询返回的 taskId，调用 batch_processing_asset_library_task_get，直到任务进入终态；然后使用 batch_processing_job_get 监控其 jobId。
2. 文件位于 Roboflow 之外，而且你只想要输出结果？ 按下文所述自行暂存文件，并使用 batch_processing_guide + batch_processing_run 驱动运行（经典 ETL 模式：数据不会进入工作区）。暂存和结果导出必须在能够访问这些文件的机器上运行。
3. 文件位于 Roboflow 之外，而且你想把它们放进去（用于标注、整理、训练）？这属于导入，而非批处理作业：使用数据源镜像云存储桶（connect_cloud_storage，参见 cloud-storage 技能）。镜像完成后，这些文件就成为 Asset Library 图像；如果你还想批量预测，可针对它们运行 Asset Library 作业（经典 ELT 模式：先加载，再转换）。

“数据源”和“存储桶镜像”是一回事：数据源是面向用户的存储桶镜像配置名称，也是填充 Asset Library 的导入器。它本身不会运行 Workflows。

从流水线角度看：暂存作业是 ETL 流程中的 T（不会执行加载），而 Asset Library 作业是 ELT 流程中的 T——加载已通过上传或数据源镜像完成。

前提条件

• 工作区需要启用批处理功能。受限调用会返回 402 错误：“Batch processing is not enabled for this workspace. Upgrade your plan or contact sales at https://roboflow.com/sales.”
• 作业会消耗积分；工作区必须有正余额。
• Workflow 必须已存在于工作区中（workflows_list、workflows_create）。作业通过 workflow_id 引用它；不支持内联规格。
• API 密钥：inference-cli 会从环境变量中读取 ROBOFLOW_API_KEY，每条命令也都接受 --api-key=<key>。inference-cli 不会读取通过 roboflow login 保存的密钥（~/.config/roboflow/config.json）：请导出该密钥或显式传入 --api-key。使用 api_keys_create MCP 工具生成密钥。切勿让用户在聊天中粘贴私密密钥。

每个步骤在哪里运行，以及原因

有两个步骤仅能通过 inference-cli 完成，因为 MCP 服务既不能读取也不能写入用户的磁盘：

• 暂存在可以访问文件（本地磁盘）的机器上运行，或使用用户的云凭据运行（存储桶来源）。
• 导出结果（export-batch）会将结果下载到本地目录。

中间的所有步骤只需要 API 密钥，因此两种方式都能使用：MCP 工具（batch_processing_run、batch_processing_staged_job_start、 batch_processing_job_get、batch_processing_jobs_list、 batch_processing_job_logs、batch_processing_job_abort、 batch_processing_job_restart，以及 batch_processing_asset_library_* 和 batch_processing_staging_* 系列工具）或对应的 CLI 命令。如果宿主没有 shell，或用户本地没有 inference-cli，优先使用 MCP 工具；如果用户已经在终端中，则优先使用 CLI。两种内容类型的完整命令集请参见第 1-5 节。

batch_processing_guide MCP 工具会为请求规划流程：确定批次 ID、选择暂存来源，并返回按顺序排列的准确命令。它不会接触文件或网络，也不会重复本文档的内容。

暂存批次的主工具：batch_processing_run

优先使用 batch_processing_run(batch_id, workflow_id, content_type, ...) 来处理你指定的暂存批次（对于 Asset Library 选择，请改用 batch_processing_asset_library_job_create）。每次调用都会读取当前状态、推进可执行的步骤，并立即返回状态：

• staging_required — 尚无批次；响应中包含本次运行所需的全部 CLI 命令以及云凭据说明。执行命令后，再次调用。
• ingest_in_progress — 文件仍在注册中。
• ingest_failed — 摄取失败或返回了未知分片状态；未启动付费作业。
• running — 作业已启动或仍在运行；其中包含阶段进度。
• completed — 包含导出批次 ID，以及带签名下载 URL 的首批结果文件。
• failed — 包含日志和重新启动提示。

服务不会代你等待。 非终态响应会包含 retryAfterSeconds；在你这边等待相应时间，然后使用返回的 job_id 和相同的 batch_id 再次调用，以继续处理。仅以只读方式恢复时，请省略可选的创建设置；已存储的付费作业定义具有权威性。服务不会在调用之间保留状态。

作业会使用根据（工作区、批次、工作流）派生的 ID 启动，因此响应丢失后重试会重新注册同一个作业，而不是为第二次运行付费。（平台会在检查幂等性之前检查额度，因此重试时仍可能先收到 429。）如果出现 409，表示该 ID 已存在，但其批次/Workflow 身份不同，或与你明确提供的可选设置冲突。请检查作业，省略可选设置以按已存储的设置监控作业，或传入新的显式 job_id 来单独运行。

如需使用高级参数（max_runtime_seconds、max_parallel_tasks、 max_image_failure_rate、image_outputs_to_save），请直接使用 batch_processing_staged_job_start。

Webhook

Roboflow 会向你控制的 URL 发送作业和摄取通知的 POST 请求。MCP 端没有中继：请将 notifications_url 传给 batch_processing_staged_job_start，或在 CLI 命令中使用 --notifications-url，并指向你自己的接收端。POST 请求会携带一个包含可发布密钥的 Authorization 标头。

注意：本地 视频 暂存不支持 --notifications-url（CLI 会打印警告并忽略该参数）；小型本地 图像 批次（32 个文件或更少，以简单批次方式暂存）也会忽略该参数。分片的本地图像、云存储和引用文件摄取均支持此参数。

如果没有接收端，只需轮询 batch_processing_job_get（或 batch_processing_run，它会在每次调用时报告进度）。

1. 安装 CLI

pip install inference-cli
# For s3:// gs:// az:// sources:
pip install 'inference-cli[cloud-storage]'

以下每条 inference rf-cloud 命令都会通过环境变量 ROBOFLOW_API_KEY 进行身份验证，也可以在命令中使用 --api-key=<key>。

云凭据会从运行 CLI 的机器上的标准环境变量链中读取：AWS 使用默认凭据链（支持 AWS_PROFILE；通过 AWS_ENDPOINT_URL 使用 R2/MinIO，并同时应用 AWS_REGION），GCS 使用 GOOGLE_APPLICATION_CREDENTIALS，Azure 使用 AZURE_STORAGE_ACCOUNT_NAME，以及 AZURE_STORAGE_ACCOUNT_KEY 或 AZURE_STORAGE_SAS_TOKEN。对于 S3/GCS，CLI 会生成预签名 URL（有效期 24 小时）；对于 Azure，CLI 会附加你的 SAS 令牌，因此只要令牌有效，这些 URL 就会保持有效。无论哪种情况，URL 都会发送给 Roboflow，而存储桶密钥不会离开本机。

2. 暂存一个批次

批次 ID：小写字母、数字、- 或 _。暂存的批次会在约 7 天后过期。

# Local images (>32 images are packed into tar shards automatically)
inference rf-cloud data-staging create-batch-of-images \
  --batch-id my-batch --images-dir ./images

# Local videos (uploaded one by one via signed URLs)
inference rf-cloud data-staging create-batch-of-videos \
  --batch-id my-batch --videos-dir ./videos

# Cloud bucket (S3/GCS/Azure; glob over object paths).
# Videos work exactly the same way: create-batch-of-videos.
inference rf-cloud data-staging create-batch-of-images \
  --batch-id my-batch --data-source cloud-storage \
  --bucket-path 's3://my-bucket/images/**/*.jpg'

inference rf-cloud data-staging create-batch-of-videos \
  --batch-id my-batch --data-source cloud-storage \
  --bucket-path 's3://my-bucket/videos/**/*.mp4'

# References file: JSONL lines of {"name": ..., "url": "https://..."}
inference rf-cloud data-staging create-batch-of-images \
  --batch-id my-batch --data-source references-file --references refs.jsonl

图像还是视频是由你选择的，而不是根据路径推断的：create-batch-of-images 和 create-batch-of-videos 都接受所有数据源。请选择与内容匹配的命令。

分片、云存储和引用数据的摄取都是异步的。启动任务前，请等待批次完全摄取完成：

inference rf-cloud data-staging show-batch-details --batch-id my-batch
inference rf-cloud data-staging list-ingest-details --batch-id my-batch

也可以使用 batch_processing_staging_batch_get MCP 工具，该工具会返回文件数量，以及包含 pending 和 failed 标记的 ingest 块。pending 或 failed 为 true 时，不要启动任务：任务会消耗额度，并会在输入不完整的情况下运行。

实际限制：每个摄取请求最多 20,000 个图像引用（会自动分块；视频引用每个请求最多 5,000 个，且不会分块），建议每个批次约 1,000 个视频；图像格式为 jpg/png/webp/bmp/jp2，视频格式为 mp4/mov/avi/mkv/flv/wmv/m4v。batch_processing_staging_batches_list 会显示工作区中的所有暂存批次（输入和任务结果）。

3. 启动任务

CLI，图像：

inference rf-cloud batch-processing process-images-with-workflow \
  --batch-id my-batch --workflow-id my-workflow --machine-type gpu

CLI，视频：

inference rf-cloud batch-processing process-videos-with-workflow \
  --batch-id my-batch --workflow-id my-workflow --machine-type gpu \
  --max-video-fps 5

通用可选标志：--workers-per-machine 1|2|4|8、 --aggregation-format jsonl|csv、--save-image-outputs、 --image-outputs-to-save <name>、--image-input-name <name>、 --workflow-params params.json、--max-runtime-seconds <n>、 --max-parallel-tasks <n>、--job-id <id>、--job-name <name>、 --notifications-url <url>、--part-name <part>。

仅适用于图像：--max-image-failure-rate 0.0-1.0（服务端会在视频任务中拒绝此参数）。仅适用于视频：--max-video-fps <n>。

MCP 对应方式：

batch_processing_staged_job_start(
  job_id="my-stable-job-id",           # required; reuse for retries
  batch_id="my-batch", workflow_id="my-workflow",
  content_type="images",            # or "videos"
  machine_type="gpu",               # cpu|gpu, optional
  workers_per_machine=4,            # 1, 2, 4 or 8, optional
  aggregation_format="jsonl",       # or "csv"
  save_image_outputs=True,          # persist crops/visualizations
)

对于视频，请设置 content_type="videos"，也可以选择设置 max_video_fps=5（预测抽帧）。该工具会在图像任务中拒绝 max_video_fps，并在视频任务中拒绝 max_image_failure_rate，与平台行为一致。

选择 CPU 还是 GPU（machine_type）

默认计算资源为 CPU。在对整个批次启动付费任务前，先通过以下两项快速检查做出决定：

1. 在一张有代表性的图像上试运行工作流（使用 workflows_run MCP 工具或托管 API），并测量实际耗时。运行两次，记录第二次调用的耗时（第一次可能需要冷启动）。如果处理单张图像的模型耗时超过约一秒，CPU 工作进程处理大型批次会非常缓慢：选择 gpu。
2. 检查工作流规范（workflows_get）：统计模型步骤并留意其规模。只有一个小型微调检测器／分类器时，cpu 成本最低，通常也足够。若串联了多个模型，或包含任何大型基础模型（SAM 系列、CLIP、OCR、VLM 模块），则选择 gpu。

视频会通过 --max-video-fps 按帧增加工作量，因此也建议选择 gpu。 workers_per_machine（1/2/4/8）可进一步调整单台机器的吞吐量：工作进程越多，资源利用率越高，但 OOM 风险也越大。

相同的 job_id 和相同的定义具有幂等性；若定义不同，则会被拒绝并返回 409。该工具会在付费注册调用前检查数据导入是否完成。对于多部分输入，请传入 part_name；batch_processing_run 也支持此参数。这两个工具默认使用当前的 inference-models 后端；只有在明确存在兼容性要求时才使用 inference_backend="old-inference"。

4. 监控

inference rf-cloud batch-processing show-job-details --job-id my-job
inference rf-cloud batch-processing fetch-logs --job-id my-job
inference rf-cloud batch-processing abort-job --job-id my-job
inference rf-cloud batch-processing restart-job --job-id my-job

对应的 MCP 工具会返回 JSON，而不是渲染后的表格：

• batch_processing_job_get(job_id) — 状态、当前／计划阶段、各阶段进度、输出批次；job.isTerminal + job.error 表示结束状态。
• batch_processing_job_logs(job_id) — 用于诊断的信息／错误日志。
• batch_processing_job_abort(job_id) / batch_processing_job_restart(job_id) — 停止运行，或重试失败的任务（可选覆盖机器类型、工作进程数和超时时间）。
• batch_processing_jobs_list(search=...) — 工作区最近的工作流任务，可用于查找未保存的任务 ID。内部 TensorRT 编译任务不包含在内。此工具和 batch_processing_job_get 都会为每个任务标注 inputSource：asset-library（平台暂存的选择）或 staged-batch（自行暂存的批次）。

5. 下载结果

结果会以平台生成的批次形式存入 Data Staging： <job-id>-processing（每个分片的原始输出）和 <job-id>-export （打包后的可下载存档）。

下载会写入磁盘，因此此步骤仅支持 CLI：

inference rf-cloud data-staging export-batch \
  --batch-id my-job-export --target-dir ./results

此操作支持恢复；添加 --override-existing 可重新拉取已导出的内容，添加 --part-name <part> 可获取多部分批次中的一个部分。

MCP 工具 batch_processing_staging_batch_files_list(batch_id="<job-id>-export") 会列出相同的文件及带签名的 downloadURL（约 24 小时后过期），因此没有 shell 的主机也可以获取这些文件。导出批次包含多个部分：若只有一个部分，该工具会自动选择；否则会要求你传入 part_name（各部分可通过 batch_processing_staging_batch_get 查看）。存档文件（.tar / .tar.gz）下载后必须解包，而且每次调用最多列出 10,000 个条目。超过此规模时，请使用 nextPageToken 继续分页，并按部分使用 part_name 列出内容，或通过支持恢复的 export-batch 拉取全部内容。

请在 7 天内完成此操作：暂存的输入和结果会过期。