roboflow-batch-processing
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseFor agents: This skill is authored in. If your client already has it loaded as a skill (for example from a Roboflow plugin), use that copy. Theroboflow/computer-vision-skillsMCP resources serve the same skills for clients that don't have them loaded.skill://roboflow/<name>/SKILL.md
对于 Agent: 此 skill 由编写。如果你的客户端已经加载了它(例如通过 Roboflow 插件加载),请使用该副本。对于尚未加载这些 skill 的客户端,roboflow/computer-vision-skillsMCP 资源提供相同的 skill。skill://roboflow/<name>/SKILL.md
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
选择哪条路径?三个问题
- Are the files already in Roboflow (Asset Library)? Call
with a stable idempotency key and exactly one selection:
batch_processing_asset_library_job_create,image_ids, orquery. The platform performs access checks, selects the files, stages them, verifies Workflow compatibility, bills, and registers the durable job. Poll the returnedall_images=truewithtaskIduntil the task is terminal; then monitor itsbatch_processing_asset_library_task_getwithjobId.batch_processing_job_get - Files outside Roboflow, and you only want the outputs? Stage them
yourself and drive the run with +
batch_processing_guideas 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.batch_processing_run - 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 (, see the
connect_cloud_storageskill). 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).cloud-storage
"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.
- 文件是否已位于 Roboflow 中(Asset Library)? 使用稳定的幂等性 key 调用 ,并且只能提供以下三种选择之一:
batch_processing_asset_library_job_create、image_ids或query。平台会执行访问权限检查、选择文件、暂存文件、验证 Workflow 兼容性、计费并注册持久化作业。使用all_images=true轮询返回的batch_processing_asset_library_task_get,直至任务进入终态;然后使用taskId监控其batch_processing_job_get。jobId - 文件位于 Roboflow 之外,并且你只需要输出结果? 自行暂存文件,并按照下文所述方式使用 +
batch_processing_guide驱动运行(经典 ETL 形态:不会向工作区导入任何内容)。暂存和结果导出必须在能够访问文件的机器上运行。batch_processing_run - 文件位于 Roboflow 之外,并且你希望将其导入 Roboflow 内部(用于标注、筛选整理、训练)?这不是批处理作业,而是导入操作:使用 datasource(,参见
connect_cloud_storageskill)镜像 bucket。镜像完成后,这些文件就成为 Asset Library 图像;如果你还希望批量生成预测结果,则可对其运行 Asset Library 作业(经典 ELT 形态:先加载,再转换)。cloud-storage
“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). Jobs reference it byworkflows_create; there is no inline-spec option.workflow_id - API key: the inference-cli reads from the environment, and every command also accepts
ROBOFLOW_API_KEY. A key stored by--api-key=<key>(roboflow login) is NOT picked up by the inference-cli: export it or pass~/.config/roboflow/config.jsonexplicitly. Mint one with the--api-keyMCP tool. Never have the user paste a private key into chat.api_keys_create
- 工作区需要启用批处理功能。受套餐限制的调用失败时会返回 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;不支持内联规格选项。workflow_id - API key:inference-cli 从环境变量 读取密钥,每个命令也可接受
ROBOFLOW_API_KEY。通过--api-key=<key>保存的密钥(roboflow login)不会被 inference-cli 读取:请导出该变量,或显式传入~/.config/roboflow/config.json。可使用--api-keyMCP 工具创建密钥。绝不要让用户将私钥粘贴到聊天中。api_keys_create
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 () downloads into a local directory.
export-batch
Everything in between needs only an API key, so it works either way: the MCP
tools (, ,
, ,
, ,
, plus the
and
families) or the equivalent CLI commands. Prefer the MCP tools when the host has no shell or the user has
no local ; prefer the CLI when the user is already in a
terminal. The full command set for both content types is in sections 1-5.
batch_processing_runbatch_processing_staged_job_startbatch_processing_job_getbatch_processing_jobs_listbatch_processing_job_logsbatch_processing_job_abortbatch_processing_job_restartbatch_processing_asset_library_*batch_processing_staging_*inference-cliThe 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.
batch_processing_guide有两个步骤只能通过 inference-cli 执行,因为 MCP server 既无法读取也无法写入用户磁盘:
- 暂存在能够访问文件的机器上运行,或使用用户的云凭据执行(bucket 来源)。
- 导出结果()会下载到本地目录。
export-batch
两者之间的所有步骤只需要 API key,因此两种方式都适用:可以使用 MCP 工具(、、
、、
、、
,以及 和 系列工具),也可以使用等效的 CLI 命令。当宿主没有 shell 或用户没有本地 时,优先使用 MCP 工具;当用户已经在终端中时,优先使用 CLI。两类内容的完整命令集见第 1-5 节。
batch_processing_runbatch_processing_staged_job_startbatch_processing_job_getbatch_processing_jobs_listbatch_processing_job_logsbatch_processing_job_abortbatch_processing_job_restartbatch_processing_asset_library_*batch_processing_staging_*inference-clibatch_processing_guideThe master tool for staged batches: batch_processing_run
batch_processing_runstaged 批次的主工具:batch_processing_run
batch_processing_runPrefer to
drive the flow over a staging batch you name (for Asset Library selections,
use instead). Each call reads
current state, advances what it can, and returns immediately with a status:
batch_processing_run(batch_id, workflow_id, content_type, ...)batch_processing_asset_library_job_create- — no batch yet; the response contains the CLI commands for the whole run plus cloud-credential guidance. Run them, then call again.
staging_required - — files still registering.
ingest_in_progress - — ingest failed or returned an unknown shard state; no paid job was started.
ingest_failed - — the job was started or is still working; includes stage progress.
running - — includes the export batch id and the first result files with signed download URLs.
completed - — includes logs and a restart hint.
failed
The server never waits on your behalf. Non-terminal responses carry
; sleep that long on your side, then call again with the
returned and the same 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.
retryAfterSecondsjob_idbatch_idThe 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 for a separate run.
job_idFor the advanced knobs (, ,
, ) use
directly.
max_runtime_secondsmax_parallel_tasksmax_image_failure_rateimage_outputs_to_savebatch_processing_staged_job_start对于你指定名称的暂存批次,优先使用 驱动整个流程(对于 Asset Library 选择,请改用 )。每次调用都会读取当前状态,尽可能推进流程,并立即返回状态:
batch_processing_run(batch_id, workflow_id, content_type, ...)batch_processing_asset_library_job_create- ——尚不存在批次;响应中包含整个运行流程的 CLI 命令以及云凭据指南。执行这些命令后,再次调用。
staging_required - ——文件仍在注册中。
ingest_in_progress - ——ingest 失败,或返回了未知分片状态;未启动付费作业。
ingest_failed - ——作业已启动或仍在执行;包含各阶段进度。
running - ——包含导出批次 id,以及首批结果文件及其签名下载 URL。
completed - ——包含日志和重启提示。
failed
服务器绝不会代你等待。 非终态响应带有 ;在你端等待相应时长,然后使用返回的 和相同的 再次调用以继续。只读恢复时不要省略创建作业的可选设置:付费作业已保存的定义才是权威依据。服务器不在调用之间保存状态。
retryAfterSecondsjob_idbatch_id作业的 id 根据(workspace、batch、workflow)派生,因此在响应丢失后重试会重新注册同一个作业,而不是为第二次运行付费。(平台会在进行幂等性比较之前检查 credits,因此重试仍可能先收到 429。)409 表示该 id 已存在,但关联了不同的批次/Workflow 标识,或与你显式提供的某个可选设置冲突。请检查作业,省略可选设置以按已保存配置进行监控,或传入新的显式 以开始一次独立运行。
job_id对于高级选项(、、、),请直接使用 。
max_runtime_secondsmax_parallel_tasksmax_image_failure_rateimage_outputs_to_savebatch_processing_staged_job_startWebhooks
Webhooks
Roboflow will POST job and ingest notifications to a URL you control. There is
no MCP-side relay: pass to , or
on the CLI commands, pointing at your own receiver. The
POST carries an header with your publishable key.
notifications_urlbatch_processing_staged_job_start--notifications-urlAuthorizationCaveat: local video staging does not support (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.
--notifications-urlIf you have no receiver, just poll (or
, which reports progress on each call).
batch_processing_job_getbatch_processing_runRoboflow 会将作业和 ingest 通知 POST 到你控制的 URL。MCP 端没有中继机制:将 传给 ,或在 CLI 命令中使用 ,并指向你自己的接收端。POST 请求会携带包含 publishable key 的 header。
notifications_urlbatch_processing_staged_job_start--notifications-urlAuthorization注意:本地视频暂存不支持 (CLI 会打印警告并忽略该参数),本地图像的小型批次(32 个或更少文件,以简单批次形式暂存)也会忽略该参数。分片本地图像、cloud-storage 和引用文件 ingest 均支持该参数。
--notifications-url如果没有接收端,只需轮询 (或 ,它会在每次调用时报告进度)。
batch_processing_job_getbatch_processing_run1. Install the CLI
1. 安装 CLI
bash
pip install inference-clibash
pip install inference-cliFor 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
undefinedLocal 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
--batch-id my-batch --images-dir ./images
inference rf-cloud data-staging create-batch-of-images
--batch-id my-batch --images-dir ./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
--batch-id my-batch --videos-dir ./videos
inference rf-cloud data-staging create-batch-of-videos
--batch-id my-batch --videos-dir ./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'
--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'
--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'
--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'
--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
--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-batchor the MCP tool, which returns the file
count plus an block with and flags. Do not start a
job while is true or is true: the job costs credits and
would run over incomplete input.
batch_processing_staging_batch_getingestpendingfailedpendingfailedPractical 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.
shows every staged batch in the workspace (inputs and job results).
batch_processing_staging_batches_listinference rf-cloud data-staging create-batch-of-images
--batch-id my-batch --data-source references-file --references refs.jsonl
--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也可以使用 MCP 工具,它会返回文件数量,以及包含 和 标志的 区块。当 为 true 或 为 true 时,不要启动作业:作业会消耗 credits,并且会基于不完整的输入运行。
batch_processing_staging_batch_getpendingfailedingestpendingfailed实际限制:每个 ingest 请求最多支持 20,000 个图像引用(自动分块;视频引用每次请求上限为 5,000,且不分块),建议每个批次约 1,000 个视频;图像格式支持 jpg/png/webp/bmp/jp2,视频格式支持 mp4/mov/avi/mkv/flv/wmv/m4v。 会列出工作区中的每个 staged 批次(输入和作业结果)。
batch_processing_staging_batches_list3. 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 gpuCLI, 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 5Shared 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: (the server rejects it on
video jobs). Videos only: .
--max-image-failure-rate 0.0-1.0--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 and optionally
(prediction subsampling). The tool rejects on image jobs and
on video jobs, matching the platform.
content_type="videos"max_video_fps=5max_video_fpsmax_image_failure_rateCLI,图像:
bash
inference rf-cloud batch-processing process-images-with-workflow \
--batch-id my-batch --workflow-id my-workflow --machine-type gpuCLI,视频:
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=5max_video_fpsmax_image_failure_rateChoosing cpu vs gpu (machine_type
)
machine_type如何选择 cpu 或 gpu(machine_type
)
machine_typeDefault compute is CPU. Decide with two quick checks before starting a paid
job over the whole batch:
- Test-run the Workflow on one representative image (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
workflows_run.gpu - Inspect the Workflow spec (): count the model steps and note their sizes. One small fine-tuned detector/classifier:
workflows_getis the cheapest and usually enough. Several models chained, or any large foundation model (SAM family, CLIP, OCR, VLM blocks):cpu.gpu
Videos multiply per-frame work with , so lean there
too. (1/2/4/8) then scales throughput on one machine:
more workers means better utilization but a higher OOM risk.
--max-video-fpsgpuworkers_per_machineSame 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 ; it is also
supported by . Both tools default to the current
backend; use only for a
known compatibility requirement.
part_namebatch_processing_runinference-modelsinference_backend="old-inference"默认计算资源为 CPU。在对整个批次启动付费作业前,先通过两项快速检查做决定:
- 在一张有代表性的图像上测试运行 Workflow(使用 MCP 工具或托管 API),并测量实际耗时。运行两次,并记录第二次调用的耗时(第一次可能需要冷启动)。如果单张图像的模型耗时超过约一秒,CPU worker 处理大批次时速度会非常缓慢:请选择
workflows_run。gpu - 检查 Workflow 规格():统计模型步骤数量并记录其规模。一个体积较小的微调 detector/classifier:
workflows_get成本最低,通常也足够。多个模型串联,或使用任何大型 foundation model(SAM 系列、CLIP、OCR、VLM 模块):cpu。gpu
视频会按每帧的工作量成倍放大,因此处理视频时也应倾向使用 。随后,(1/2/4/8)用于扩展单台机器的吞吐量:worker 越多,资源利用率越高,但发生 OOM 的风险也越大。
gpuworkers_per_machine相同的 job_id 加上相同的定义具有幂等性;定义不一致则会被拒绝并返回 409。该工具会在调用付费注册前检查 ingest 是否已完成。对于多部分输入,请传入 ; 也支持此参数。两个工具默认使用当前的 后端;仅在存在已知兼容性要求时才使用 。
part_namebatch_processing_runinference-modelsinference_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-jobMCP equivalents, which return JSON rather than a rendered table:
- — status, current/planned stages, per-stage progress, output batches;
batch_processing_job_get(job_id)+job.isTerminalare the end states.job.error - — info/error logs for diagnosis.
batch_processing_job_logs(job_id) - /
batch_processing_job_abort(job_id)— stop a run, or retry a failed one (optionally overriding machine type, workers, timeout).batch_processing_job_restart(job_id) - — 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_jobs_list(search=...)label each job withbatch_processing_job_get:inputSource(platform-staged selection) orasset-library(a batch you staged yourself).staged-batch
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-jobMCP 等价工具会返回 JSON,而不是渲染后的表格:
- ——状态、当前/计划阶段、各阶段进度、输出批次;
batch_processing_job_get(job_id)+job.isTerminal是终态。job.error - ——用于诊断的 info/error 日志。
batch_processing_job_logs(job_id) - /
batch_processing_job_abort(job_id)——停止运行,或重试失败的运行(可选择覆盖 machine type、worker 数和 timeout)。batch_processing_job_restart(job_id) - ——工作区最近的 Workflow 作业,用于查找未保留 job id 的作业。内部 TensorRT 编译作业不包含在内。该工具和
batch_processing_jobs_list(search=...)都会使用batch_processing_job_get标记每个作业:inputSource(由平台暂存的选择集)或asset-library(由你自行暂存的批次)。staged-batch
5. Download results
5. 下载结果
Results land in Data Staging as platform-generated batches:
(raw per-shard outputs) and
(packaged, downloadable archives).
<job-id>-processing<job-id>-exportDownloading writes to disk, so this step is CLI only:
bash
inference rf-cloud data-staging export-batch \
--batch-id my-job-export --target-dir ./resultsIt is resumable; add to re-pull content already
exported, and to fetch one part of a multipart batch.
--override-existing--part-name <part>The MCP tool
lists the same files with signed 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
(the parts are in ). Archives
( / ) must be unpacked after download, and listings are capped
at 10,000 entries per call — past that scale keep paginating with
and per-part listings, or pull everything with the
resumable .
batch_processing_staging_batch_files_list(batch_id="<job-id>-export")downloadURLpart_namebatch_processing_staging_batch_get.tar.tar.gznextPageTokenpart_nameexport-batchDo 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 工具 会列出相同的文件及其签名 (约 24 小时有效),因此即使宿主没有 shell 也能获取它们。导出批次是多部分的:当仅有一个部分时,该工具会自动选择它;否则会要求你传入 (各部分可通过 获取)。归档文件( / )下载后必须解包,并且每次调用最多列出 10,000 个条目——超过该规模时,请结合 和按 列出的结果继续分页,或使用可恢复的 拉取全部内容。
batch_processing_staging_batch_files_list(batch_id="<job-id>-export")downloadURLpart_namebatch_processing_staging_batch_get.tar.tar.gznextPageTokenpart_nameexport-batch请在 7 天内完成:staged 输入和结果都会过期。