roboflow-batch-processing

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
编写。如果你的客户端已经加载了它(例如通过 Roboflow 插件加载),请使用该副本。对于尚未加载这些 skill 的客户端,
skill://roboflow/<name>/SKILL.md
MCP 资源提供相同的 skill。

Batch Processing

批处理

Run a Roboflow Workflow over a very large set of images or videos on Roboflow's autoscaling compute. Every job processes a temporary Data Staging batch; the two input paths differ only in who fills that batch:
  • Asset Library job — the files are already in Roboflow. You hand the platform a selection and it selects and stages them for you.
  • Staged job — the files are outside Roboflow (local disk, cloud bucket, references file), so you stage them yourself with the inference-cli: only your machine and credentials can reach them. Nothing is imported into the workspace, and staged data expires after ~7 days.
在 Roboflow 的自动扩缩容计算资源上,针对非常大量的图像或视频运行 Roboflow Workflow。每个作业都会处理一个临时的 Data Staging 批次;两条输入路径的区别仅在于由谁填充该批次:
  • Asset Library 作业——文件已位于 Roboflow 中。你向平台提供一组选择条件,由平台负责选择并为你暂存文件。
  • staged 作业——文件位于 Roboflow 之外(本地磁盘、云端 bucket、引用文件),因此你需使用 inference-cli 自行暂存:只有你的机器和凭据能够访问这些文件。不会向工作区导入任何内容,staged 数据约 7 天后过期。

Which path? Three questions

选择哪条路径?三个问题

  1. Are the files already in Roboflow (Asset Library)? Call
    batch_processing_asset_library_job_create
    with a stable idempotency key and exactly one selection:
    image_ids
    ,
    query
    , or
    all_images=true
    . The platform performs access checks, selects the files, stages them, verifies Workflow compatibility, bills, and registers the durable job. Poll the returned
    taskId
    with
    batch_processing_asset_library_task_get
    until the task is terminal; then monitor its
    jobId
    with
    batch_processing_job_get
    .
  2. Files outside Roboflow, and you only want the outputs? Stage them yourself and drive the run with
    batch_processing_guide
    +
    batch_processing_run
    as described below (the classic ETL shape: nothing lands in the workspace). Staging and result export must run on the machine that can access the files.
  3. Files outside Roboflow that you want INSIDE it (labeling, curation, training)? That is an import, not a batch processing job: mirror the bucket with a datasource (
    connect_cloud_storage
    , see the
    cloud-storage
    skill). Once mirrored, the files are Asset Library images, so if you also want bulk predictions, run an Asset Library job over them (the classic ELT shape: load first, then transform).
"Datasource" and "bucket mirror" are one thing: a datasource is the user-facing name for a bucket-mirror config, the importer that fills the Asset Library. It never runs Workflows itself.
In pipeline terms: a staged job is the T of an ETL flow (no load ever happens), and an Asset Library job is the T of an ELT flow — the load already happened, via uploads or a datasource mirror.
  1. 文件是否已位于 Roboflow 中(Asset Library)? 使用稳定的幂等性 key 调用
    batch_processing_asset_library_job_create
    ,并且只能提供以下三种选择之一:
    image_ids
    、
    query
    或
    all_images=true
    。平台会执行访问权限检查、选择文件、暂存文件、验证 Workflow 兼容性、计费并注册持久化作业。使用
    batch_processing_asset_library_task_get
    轮询返回的
    taskId
    ,直至任务进入终态;然后使用
    batch_processing_job_get
    监控其
    jobId
    。
  2. 文件位于 Roboflow 之外,并且你只需要输出结果? 自行暂存文件,并按照下文所述方式使用
    batch_processing_guide
    +
    batch_processing_run
    驱动运行(经典 ETL 形态:不会向工作区导入任何内容)。暂存和结果导出必须在能够访问文件的机器上运行。
  3. 文件位于 Roboflow 之外,并且你希望将其导入 Roboflow 内部(用于标注、筛选整理、训练)?这不是批处理作业,而是导入操作:使用 datasource(
    connect_cloud_storage
    ,参见
    cloud-storage
    skill)镜像 bucket。镜像完成后,这些文件就成为 Asset Library 图像;如果你还希望批量生成预测结果,则可对其运行 Asset Library 作业(经典 ELT 形态:先加载,再转换)。
“Datasource”和“bucket mirror”指的是同一概念:datasource 是 bucket-mirror 配置面向用户的名称,也就是负责填充 Asset Library 的导入器。它本身从不运行 Workflow。
在流水线术语中:staged 作业是 ETL 流程中的 T(完全不发生加载),而 Asset Library 作业是 ELT 流程中的 T——加载已经通过上传或 datasource 镜像完成。

Prerequisites

前置条件

  • The workspace needs the batch-processing feature. Gated calls fail with a 402 "Batch processing is not enabled for this workspace. Upgrade your plan or contact sales at https://roboflow.com/sales."
  • Jobs consume credits; the workspace must have a positive balance.
  • The Workflow must already exist in the workspace (
    workflows_list
    ,
    workflows_create
    ). Jobs reference it by
    workflow_id
    ; there is no inline-spec option.
  • API key: the inference-cli reads
    ROBOFLOW_API_KEY
    from the environment, and every command also accepts
    --api-key=<key>
    . A key stored by
    roboflow login
    (
    ~/.config/roboflow/config.json
    ) is NOT picked up by the inference-cli: export it or pass
    --api-key
    explicitly. Mint one with the
    api_keys_create
    MCP tool. Never have the user paste a private key into chat.
  • 工作区需要启用批处理功能。受套餐限制的调用失败时会返回 402 "Batch processing is not enabled for this workspace. Upgrade your plan or contact sales at https://roboflow.com/sales."
  • 作业会消耗 credits;工作区必须拥有正余额。
  • Workflow 必须已存在于工作区中(
    workflows_list
    、
    workflows_create
    )。作业通过
    workflow_id
    引用 Workflow;不支持内联规格选项。
  • API key:inference-cli 从环境变量
    ROBOFLOW_API_KEY
    读取密钥,每个命令也可接受
    --api-key=<key>
    。通过
    roboflow login
    保存的密钥(
    ~/.config/roboflow/config.json
    )不会被 inference-cli 读取:请导出该变量,或显式传入
    --api-key
    。可使用
    api_keys_create
    MCP 工具创建密钥。绝不要让用户将私钥粘贴到聊天中。

Where each step runs, and why

每一步在哪里运行,以及原因

Two steps are inference-cli only, because the MCP server can neither read nor write the user's disk:
  • Staging runs on the machine that can reach the files (local disk) or with the user's cloud credentials (bucket sources).
  • Exporting results (
    export-batch
    ) downloads into a local directory.
Everything in between needs only an API key, so it works either way: the MCP tools (
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
, plus the
batch_processing_asset_library_*
and
batch_processing_staging_*
families) or the equivalent CLI commands. Prefer the MCP tools when the host has no shell or the user has no local
inference-cli
; prefer the CLI when the user is already in a terminal. The full command set for both content types is in sections 1-5.
The
batch_processing_guide
MCP tool routes a request: it settles the batch id, picks the staging source, and returns the exact ordered commands. It never touches files or the network, and it does not repeat this document.
有两个步骤只能通过 inference-cli 执行,因为 MCP server 既无法读取也无法写入用户磁盘:
  • 暂存在能够访问文件的机器上运行,或使用用户的云凭据执行(bucket 来源)。
  • 导出结果(
    export-batch
    )会下载到本地目录。
两者之间的所有步骤只需要 API key,因此两种方式都适用:可以使用 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 工具负责路由请求:确定 batch id、选择暂存来源,并返回精确的有序命令。它不会接触文件或网络,也不会重复本文档。

The master tool for staged batches:
batch_processing_run

staged 批次的主工具:
batch_processing_run

Prefer
batch_processing_run(batch_id, workflow_id, content_type, ...)
to drive the flow over a staging batch you name (for Asset Library selections, use
batch_processing_asset_library_job_create
instead). Each call reads current state, advances what it can, and returns immediately with a status:
  • staging_required
    — no batch yet; the response contains the CLI commands for the whole run plus cloud-credential guidance. Run them, then call again.
  • ingest_in_progress
    — files still registering.
  • ingest_failed
    — ingest failed or returned an unknown shard state; no paid job was started.
  • running
    — the job was started or is still working; includes stage progress.
  • completed
    — includes the export batch id and the first result files with signed download URLs.
  • failed
    — includes logs and a restart hint.
The server never waits on your behalf. Non-terminal responses carry
retryAfterSeconds
; sleep that long on your side, then call again with the returned
job_id
and the same
batch_id
to resume. Omit optional creation settings on a read-only resume: the paid job's stored definition is authoritative. The server holds no state between calls.
The job is started under an id derived from (workspace, batch, workflow), so retrying after a lost response re-registers the same job instead of paying for a second run. (The platform checks credits before that idempotency comparison, so a retry can still see a 429 first.) A 409 means that id already exists with different batch/Workflow identity or conflicts with an optional setting you explicitly supplied. Inspect the job, omit optional settings to monitor it as stored, or pass a new explicit
job_id
for a separate run.
For the advanced knobs (
max_runtime_seconds
,
max_parallel_tasks
,
max_image_failure_rate
,
image_outputs_to_save
) use
batch_processing_staged_job_start
directly.
对于你指定名称的暂存批次,优先使用
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
    ——ingest 失败,或返回了未知分片状态;未启动付费作业。
  • running
    ——作业已启动或仍在执行;包含各阶段进度。
  • completed
    ——包含导出批次 id,以及首批结果文件及其签名下载 URL。
  • failed
    ——包含日志和重启提示。
服务器绝不会代你等待。 非终态响应带有
retryAfterSeconds
;在你端等待相应时长,然后使用返回的
job_id
和相同的
batch_id
再次调用以继续。只读恢复时不要省略创建作业的可选设置:付费作业已保存的定义才是权威依据。服务器不在调用之间保存状态。
作业的 id 根据(workspace、batch、workflow)派生,因此在响应丢失后重试会重新注册同一个作业,而不是为第二次运行付费。(平台会在进行幂等性比较之前检查 credits,因此重试仍可能先收到 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
。

Webhooks

Webhooks

Roboflow will POST job and ingest notifications to a URL you control. There is no MCP-side relay: pass
notifications_url
to
batch_processing_staged_job_start
, or
--notifications-url
on the CLI commands, pointing at your own receiver. The POST carries an
Authorization
header with your publishable key.
Caveat: local video staging does not support
--notifications-url
(the CLI prints a warning and drops it), and a small local image batch (32 files or fewer stages as a simple batch) ignores it too. Sharded local image, cloud-storage and references-file ingests all support it.
If you have no receiver, just poll
batch_processing_job_get
(or
batch_processing_run
, which reports progress on each call).
Roboflow 会将作业和 ingest 通知 POST 到你控制的 URL。MCP 端没有中继机制:将
notifications_url
传给
batch_processing_staged_job_start
,或在 CLI 命令中使用
--notifications-url
,并指向你自己的接收端。POST 请求会携带包含 publishable key 的
Authorization
header。
注意:本地视频暂存不支持
--notifications-url
(CLI 会打印警告并忽略该参数),本地图像的小型批次(32 个或更少文件,以简单批次形式暂存)也会忽略该参数。分片本地图像、cloud-storage 和引用文件 ingest 均支持该参数。
如果没有接收端,只需轮询
batch_processing_job_get
(或
batch_processing_run
,它会在每次调用时报告进度)。

1. Install the CLI

1. 安装 CLI

bash
pip install inference-cli
bash
pip install inference-cli

For s3:// gs:// az:// sources:

For s3:// gs:// az:// sources:

pip install 'inference-cli[cloud-storage]'

Every `inference rf-cloud` command below authenticates via `ROBOFLOW_API_KEY`
from the environment, or `--api-key=<key>` on the command itself.

Cloud credentials are picked up from the standard env chains on the machine
running the CLI: AWS via the default credential chain (`AWS_PROFILE` honored;
R2/MinIO work via `AWS_ENDPOINT_URL`, with `AWS_REGION` applied alongside it),
GCS via `GOOGLE_APPLICATION_CREDENTIALS`, Azure via
`AZURE_STORAGE_ACCOUNT_NAME` plus `AZURE_STORAGE_ACCOUNT_KEY` or
`AZURE_STORAGE_SAS_TOKEN`. For S3/GCS the CLI generates presigned URLs (24h
expiry); for Azure it appends your SAS token, so those URLs stay valid as long
as the token does. Either way the URLs are handed to Roboflow and bucket
secrets never leave the machine.
pip install 'inference-cli[cloud-storage]'

下面每个 `inference rf-cloud` 命令都通过环境变量中的 `ROBOFLOW_API_KEY` 进行认证,也可以在命令本身中使用 `--api-key=<key>`。

云凭据会从运行 CLI 的机器上的标准环境变量链中读取:AWS 使用默认凭据链(支持 `AWS_PROFILE`;R2/MinIO 可通过 `AWS_ENDPOINT_URL` 使用,并同时应用 `AWS_REGION`),GCS 使用 `GOOGLE_APPLICATION_CREDENTIALS`,Azure 使用 `AZURE_STORAGE_ACCOUNT_NAME` 加上 `AZURE_STORAGE_ACCOUNT_KEY` 或 `AZURE_STORAGE_SAS_TOKEN`。对于 S3/GCS,CLI 会生成有效期为 24 小时的预签名 URL;对于 Azure,则会在 URL 后附加你的 SAS token,因此这些 URL 只要 token 仍然有效就保持有效。无论采用哪种方式,URL 都会交给 Roboflow,而 bucket 密钥不会离开本机。

2. Stage a batch

2. 暂存批次

Batch ids: lowercase letters, digits,
-
or
_
. Staged batches expire after ~7 days.
bash
undefined
批次 id 可使用小写字母、数字、
-
或
_
。Staged 批次约 7 天后过期。
bash
undefined

Local images (>32 images are packed into tar shards automatically)

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
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)

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
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).

Cloud bucket (S3/GCS/Azure; glob over object paths).

Videos work exactly the same way: create-batch-of-videos.

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'
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://..."}

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

Images vs videos is a choice you make, not something inferred from the path:
`create-batch-of-images` and `create-batch-of-videos` both accept every data
source. Pick the one matching the content.

Sharded, cloud-storage, and references ingests are asynchronous. Wait until
the batch is fully ingested before starting a job:

```bash
inference rf-cloud data-staging show-batch-details --batch-id my-batch
inference rf-cloud data-staging list-ingest-details --batch-id my-batch
or the
batch_processing_staging_batch_get
MCP tool, which returns the file count plus an
ingest
block with
pending
and
failed
flags. Do not start a job while
pending
is true or
failed
is true: the job costs credits and would run over incomplete input.
Practical limits: up to 20,000 image references per ingest request (auto-chunked; video references cap at 5,000 per request and are not chunked), ~1,000 videos per batch suggested, image formats jpg/png/webp/bmp/jp2, video formats mp4/mov/avi/mkv/flv/wmv/m4v.
batch_processing_staging_batches_list
shows every staged batch in the workspace (inputs and job results).
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` 都接受所有数据源。请选择与内容类型匹配的命令。

分片、cloud-storage 和引用文件 ingest 均为异步操作。开始作业前,请等待整个批次完成 ingest:

```bash
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
为 true 或
failed
为 true 时,不要启动作业:作业会消耗 credits,并且会基于不完整的输入运行。
实际限制:每个 ingest 请求最多支持 20,000 个图像引用(自动分块;视频引用每次请求上限为 5,000,且不分块),建议每个批次约 1,000 个视频;图像格式支持 jpg/png/webp/bmp/jp2,视频格式支持 mp4/mov/avi/mkv/flv/wmv/m4v。
batch_processing_staging_batches_list
会列出工作区中的每个 staged 批次(输入和作业结果)。

3. Start the job

3. 启动作业

CLI, images:
bash
inference rf-cloud batch-processing process-images-with-workflow \
  --batch-id my-batch --workflow-id my-workflow --machine-type gpu
CLI, videos:
bash
inference rf-cloud batch-processing process-videos-with-workflow \
  --batch-id my-batch --workflow-id my-workflow --machine-type gpu \
  --max-video-fps 5
Shared optional flags:
--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>
.
Images only:
--max-image-failure-rate 0.0-1.0
(the server rejects it on video jobs). Videos only:
--max-video-fps <n>
.
MCP equivalent:
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
)
For videos, set
content_type="videos"
and optionally
max_video_fps=5
(prediction subsampling). The tool rejects
max_video_fps
on image jobs and
max_image_failure_rate
on video jobs, matching the platform.
CLI,图像:
bash
inference rf-cloud batch-processing process-images-with-workflow \
  --batch-id my-batch --workflow-id my-workflow --machine-type gpu
CLI,视频:
bash
inference rf-cloud batch-processing process-videos-with-workflow \
  --batch-id my-batch --workflow-id my-workflow --machine-type gpu \
  --max-video-fps 5
共享的可选 flags:
--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
,其行为与平台一致。

Choosing cpu vs gpu (
machine_type
)

如何选择 cpu 或 gpu(
machine_type
)

Default compute is CPU. Decide with two quick checks before starting a paid job over the whole batch:
  1. Test-run the Workflow on one representative image (
    workflows_run
    MCP tool, or the hosted API) and measure the wall time. Run it twice and time the second call (the first may cold-start). If a single image takes more than about a second of model time, CPU workers will crawl through a large batch: take
    gpu
    .
  2. Inspect the Workflow spec (
    workflows_get
    ): count the model steps and note their sizes. One small fine-tuned detector/classifier:
    cpu
    is the cheapest and usually enough. Several models chained, or any large foundation model (SAM family, CLIP, OCR, VLM blocks):
    gpu
    .
Videos multiply per-frame work with
--max-video-fps
, so lean
gpu
there too.
workers_per_machine
(1/2/4/8) then scales throughput on one machine: more workers means better utilization but a higher OOM risk.
Same job_id plus an identical definition is idempotent; a divergent one is rejected with a 409. The tool checks that ingest is complete before the paid registration call. For a multipart input, pass
part_name
; it is also supported by
batch_processing_run
. Both tools default to the current
inference-models
backend; use
inference_backend="old-inference"
only for a known compatibility requirement.
默认计算资源为 CPU。在对整个批次启动付费作业前,先通过两项快速检查做决定:
  1. 在一张有代表性的图像上测试运行 Workflow(使用
    workflows_run
    MCP 工具或托管 API),并测量实际耗时。运行两次,并记录第二次调用的耗时(第一次可能需要冷启动)。如果单张图像的模型耗时超过约一秒,CPU worker 处理大批次时速度会非常缓慢:请选择
    gpu
    。
  2. 检查 Workflow 规格(
    workflows_get
    ):统计模型步骤数量并记录其规模。一个体积较小的微调 detector/classifier:
    cpu
    成本最低,通常也足够。多个模型串联,或使用任何大型 foundation model(SAM 系列、CLIP、OCR、VLM 模块):
    gpu
    。
视频会按每帧的工作量成倍放大,因此处理视频时也应倾向使用
gpu
。随后,
workers_per_machine
(1/2/4/8)用于扩展单台机器的吞吐量:worker 越多,资源利用率越高,但发生 OOM 的风险也越大。
相同的 job_id 加上相同的定义具有幂等性;定义不一致则会被拒绝并返回 409。该工具会在调用付费注册前检查 ingest 是否已完成。对于多部分输入,请传入
part_name
;
batch_processing_run
也支持此参数。两个工具默认使用当前的
inference-models
后端;仅在存在已知兼容性要求时才使用
inference_backend="old-inference"
。

4. Monitor

4. 监控

bash
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 equivalents, which return JSON rather than a rendered table:
  • batch_processing_job_get(job_id)
    — status, current/planned stages, per-stage progress, output batches;
    job.isTerminal
    +
    job.error
    are the end states.
  • batch_processing_job_logs(job_id)
    — info/error logs for diagnosis.
  • batch_processing_job_abort(job_id)
    /
    batch_processing_job_restart(job_id)
    — stop a run, or retry a failed one (optionally overriding machine type, workers, timeout).
  • batch_processing_jobs_list(search=...)
    — the workspace's recent Workflow jobs, for finding a job id you did not keep. Internal TensorRT compilation jobs are excluded. Both this tool and
    batch_processing_job_get
    label each job with
    inputSource
    :
    asset-library
    (platform-staged selection) or
    staged-batch
    (a batch you staged yourself).
bash
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)
    ——用于诊断的 info/error 日志。
  • batch_processing_job_abort(job_id)
    /
    batch_processing_job_restart(job_id)
    ——停止运行,或重试失败的运行(可选择覆盖 machine type、worker 数和 timeout)。
  • batch_processing_jobs_list(search=...)
    ——工作区最近的 Workflow 作业,用于查找未保留 job id 的作业。内部 TensorRT 编译作业不包含在内。该工具和
    batch_processing_job_get
    都会使用
    inputSource
    标记每个作业:
    asset-library
    (由平台暂存的选择集)或
    staged-batch
    (由你自行暂存的批次)。

5. Download results

5. 下载结果

Results land in Data Staging as platform-generated batches:
<job-id>-processing
(raw per-shard outputs) and
<job-id>-export
(packaged, downloadable archives).
Downloading writes to disk, so this step is CLI only:
bash
inference rf-cloud data-staging export-batch \
  --batch-id my-job-export --target-dir ./results
It is resumable; add
--override-existing
to re-pull content already exported, and
--part-name <part>
to fetch one part of a multipart batch.
The MCP tool
batch_processing_staging_batch_files_list(batch_id="<job-id>-export")
lists the same files with signed
downloadURL
s (~24h expiry) so a host with no shell can still fetch them. Export batches are multipart: the tool selects the part automatically when there is exactly one, and otherwise asks you to pass
part_name
(the parts are in
batch_processing_staging_batch_get
). Archives (
.tar
/
.tar.gz
) must be unpacked after download, and listings are capped at 10,000 entries per call — past that scale keep paginating with
nextPageToken
and per-part
part_name
listings, or pull everything with the resumable
export-batch
.
Do this within 7 days: staged inputs and results expire.
结果会以平台生成的批次形式落在 Data Staging 中:
<job-id>-processing
(原始分片输出)和
<job-id>-export
(已打包、可下载的归档文件)。
下载会写入磁盘,因此此步骤只能通过 CLI 执行:
bash
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 天内完成:staged 输入和结果都会过期。