roboflow-inference

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

提示： 如果你已连接到 Roboflow MCP 服务，优先使用其推理工具，而不是原始 HTTP；OAuth 和 API 密钥连接的身份验证会自动处理。对于已保存并发布的 Workflow，请使用 workflows_run，并通过 URL slug 指定（workflow_id）；工作区取自连接。单模型调用请使用 models_infer。保存或运行新规格前，请使用 workflow_specs_validate；测试未发布的草稿或运行已获授权的一次性任务时，请使用 workflow_specs_run。

推理与部署

集成代码优先使用 Workflows。 与直接调用 models_infer 不同，Workflow 可将模型、可视化和逻辑组合为一个可部署单元，受益于服务端优化，并让主动学习和后处理能够轻松添加——这类似于微服务相比点对点调用所具备的可扩展性优势。默认推荐使用 Workflow；用户明确要求直接推理或需要快速的一次性检查时，才使用 models_infer。请参阅 workflows 和 workflow-templates。

编写 Workflows。 在 Roboflow 平台上保存可复用的 Workflows，并通过标识符运行已发布版本。根据用户请求和现有会话上下文选择编写方式：

• 模式 A：由 Agent 驱动（MCP，会话内）。 对于简单的 Workflows，使用直接编写工具，并通过 workflow_blocks_list / workflow_blocks_get_schema 为设计提供依据。复杂构建请使用 agent_chat。保存或运行前，使用 workflow_specs_validate 验证。agent_chat 保存的编辑属于草稿；获得执行授权后，发布前请使用 workflow_specs_run 测试。
• 模式 B：由平台驱动（Roboflow 应用 + 应用内 Agent）。 用户希望进行可视化交互或客户端无法完成任务时使用。发送 Workflow 返回的 app_url，或使用 roboflow-product-navigation 获取正确的构建器链接。用户可在那里查看、编辑和测试。

workflows_run 执行的是最新发布版本，而非 Agent 的草稿。只有在获得发布授权时才使用 agent_workflow_publish。测试草稿无需发布。完整流程请参阅 workflows 中的“编写与部署”。

对于实时视频（网络摄像头、RTSP、文件）： MCP workflows_run 工具仅处理单张静态图像。对于实时视频，向用户提供三个选项（不要擅自替用户选择）：（A） WebRTC → 无服务器 GPU、（B） WebRTC → 本地 inference server，或**（C）** 进程内 InferencePipeline。这些选项的设置成本、依赖包大小和延迟特性各不相同——请分别用一行简要说明，并让用户选择。完整代码和对比表请参阅 roboflow://skills/roboflow-inference/workflows（“视频流”部分）。

部署选项

选项	最适合	延迟	扩缩容	成本模式	GPU
无服务器	入门、流量可变	低	自动	按推理次数计费	是
专用	工作负载可预测、低延迟	极低	手动/自动扩缩容	按小时计费	可选
自托管	完全控制、边缘部署	取决于硬件	手动	按量计费 + 基础设施成本	可选
批处理	大型离线数据集、视频	异步（分钟至小时）	自动配置	按任务计费	可选

何时使用哪种方式

• 无服务器 —— 默认选择。零配置、自动扩缩容、上传大小限制为 20MB。使用 models_infer 或 workflows_run MCP 工具。

• 专用服务 —— 需要稳定的延迟、较大的模型（Florence 2）或较高的吞吐量。提供开发和生产级别。子域名：<name>.roboflow.cloud。

• 自托管 —— 在自己的硬件（Jetson、云 VM、RPi）上通过 Docker 部署 Roboflow Inference。API 接口与无服务器版本相同，只需更改 api_url。

• 批处理 —— 异步运行 Workflow 来处理上传的图像/视频。不要求实时处理。结果以 JSON 形式交付。

• 实时视频（摄像头/RTSP/文件） —— 有三种部署方式；编写代码前先询问用户选择哪种：

  • (A) 无服务器 GPU + WebRTC — 零配置，只需 API 密钥；按分钟计费，按套餐等级划分（webrtc-gpu-small/medium/large）。
  • (B) 本地推理服务 + WebRTC — pip install inference-cli && inference server start（推荐使用 Docker）；延迟最低，并将繁重的 CV/模型依赖隔离在服务中。
  • (C) 进程内 InferencePipeline — 在虚拟环境中运行 pip install inference（优先使用 uv）；直接在用户的 Python 进程中运行工作流循环，无需单独的服务。繁重的依赖项（torch、opencv、onnxruntime）会安装在本地。

  以上三种方式首次运行时都会较慢（需要下载模型/预热），之后的运行会使用缓存状态；请告知用户这一点，避免他们误以为脚本卡住了。

  • 完整代码和对比表请参阅 roboflow://skills/roboflow-inference/workflows（“Video Stream”部分）。

用于推理的 MCP 工具

工具	用途
models_list	列出项目的已训练模型
models_get	获取已训练模型的详细信息
models_infer	通过无服务器 API 对一张图像运行单模型推理
trainings_create	在数据集版本上启动模型训练
trainings_list	查找项目和版本的运行记录及其 trainingId
trainings_get	使用 project_id、version_number 和 training_id 检查已知运行记录；如需 NAS 模型详细信息，请使用训练技能中的分页路径
workflows_run	通过 workflow_id（URL 路径名）运行已发布的 Workflow；工作区来自连接。可选参数为 parameters。
workflow_specs_validate	验证内联工作流规范但不运行；任何内联运行前都应使用此工具。
workflow_specs_run	测试未发布的草稿，或根据内联规范运行已授权的一次性任务

本地工具：MCP 无法满足需求时

对于大多数操作，优先使用上面的 Roboflow MCP 工具——它们会处理身份验证，且无需在本地安装任何内容。只有在以下场景的功能缺口需要时，才使用本地 Python 包：集成脚本（inference-sdk）、批处理/数据暂存（inference-cli）、自托管服务（inference-cli），以及需要带类型 Python 对象的资源脚本。

请参阅 local-tooling，了解不同用例需要安装哪些内容、推荐的 uv 环境配置、conda/venv 备用方案及常见问题。

按任务划分的响应结构

如需查看规范响应结构（目标检测、分类、分割、关键点），包括 class_id、detection_id、class_confidence 等所有字段，请参阅 roboflow://skills/roboflow-api-reference/inference。

大型响应处理

实例分割的 points 数组是响应臃肿的主要原因。 每个检测结果都包含一个多边形，其中可能有数百对坐标。包含大量检测结果的单张图像可能返回数 MB 的 JSON。

缓解策略：

1. 使用工作流，而不是直接推理——添加多边形简化或属性提取模块，在输出到达客户端之前缩减结果
2. 筛选类别——使用 class_filter，只返回所需的类别
3. 提高置信度阈值——检测结果越少，响应越小
4. 后处理——如果要使用原始响应，而只需要边界框，则删除或简化 points 数组
5. 避免通过 LLM 上下文返回原始分割结果——只提取所需字段（类别计数、边界框），并丢弃多边形数据

工作流图像输出是另一个主要原因。 可视化模块（边界框、多边形、掩码、标签、光晕，……）会在响应中以 Base64 编码数据块的形式输出渲染后的图像——一帧带标注的 720p 视频画面就会产生数百 KB 经 JSON 转义的字符串。通过 MCP 调用 workflows_run / workflow_specs_run 时，这通常会超出工具结果的 token 预算。请解码每个图像格式的输出（{"type": "base64", "value": "..."}），并将其写入磁盘，而不要让它经过 Agent 上下文。不要硬编码字段名称——输出键由工作流作者通过 JsonField 声明；请遍历 output.keys() 并检查数据形状。

批处理

完整操作指南（暂存、作业、监控、结果、MCP 工具）请参阅 roboflow-batch-processing 技能；本节仅比较部署方式。

简介。 由 Roboflow 管理的云服务，可为你配置基础设施，并异步运行工作流以批量处理图像或视频。“非常适合异步处理大量数据。”——Roboflow 文档。

解决的问题。 无需搭建自己的 GPU、队列或自动扩缩容器，即可对数千到数百万个文件进行批量推理。你向 Roboflow 提交工作流和一批输入，按作业付费，并在作业完成后获取 JSON 结果。

适用于以下情况： 数据已存储（而非实时数据），每个文件的成本比延迟更重要，且每个作业耗时数分钟到数小时可以接受。以下情况请选用其他方案： 需要实时获取每个请求的结果（使用 Serverless 或 Dedicated），或者需要气隙隔离／本地部署处理（使用 Self-hosted）。

使用入口：Roboflow Web UI、inference rf-cloud CLI 和 REST API。

流程

1. 在工作区中保存一个工作流。
2. 提供输入：选择 Asset Library 中的资源（平台会为你暂存），或者自行将外部文件暂存为 Data Staging 批次（本地目录、包含签名 URL 的 JSONL，或 S3 / GCS / Azure 上的云存储路径）。
3. 提交引用该工作流和输入批次的作业；选择 CPU 或 GPU。
4. 监控作业——轮询作业状态或注册 Webhook。
5. 将输出批次导出为 JSON。

CLI

inference rf-cloud CLI 提供两组子命令：data-staging（管理输入／输出批次）和 batch-processing（提交并监控作业）。运行任意命令并添加 --help，即可查看完整选项列表。

最简端到端流程：

# Stage images
inference rf-cloud data-staging create-batch-of-images \
  --images-dir ./my-images --batch-id my-batch

# Submit
inference rf-cloud batch-processing process-images-with-workflow \
  --workflow-id my-workflow --batch-id my-batch
# -> prints JOB_ID

# Monitor
inference rf-cloud batch-processing show-job-details --job-id JOB_ID

# Export results
inference rf-cloud data-staging export-batch \
  --target-dir ./results --batch-id OUTPUT_BATCH_ID

数据暂存命令 — 有关详细说明（数据源、JSONL 引用格式、多部分批次、Webhook 通知），请参阅 batch-staging：

命令	用途
data-staging list-batches	列出工作区中的暂存批次
data-staging create-batch-of-images	从本地目录、签名 URL JSONL 或云存储路径创建输入批次
data-staging create-batch-of-videos	与上方相同，但用于视频文件
data-staging show-batch-details	显示单个批次的元数据
data-staging list-batch-content	列出批次中的文件 URL（按部分筛选，写入 JSONL）
data-staging list-ingest-details	显示各分片的摄取状态，用于调试 URL 摄取
data-staging export-batch	将批次中的所有文件（例如作业输出）下载到本地目录

批处理（作业）命令 — 有关详细说明（计算配置、工作流参数、图像输出持久化、聚合格式、视频 FPS、重启、TRT 编译），请参阅 batch-jobs：

命令	用途
batch-processing list-jobs	列出工作区中的作业
batch-processing show-job-details	显示单个作业的阶段和当前状态
batch-processing process-images-with-workflow	提交图像批次作业
batch-processing process-videos-with-workflow	提交视频批次作业
batch-processing fetch-logs	获取作业日志（按严重性筛选，写入 JSONL）
batch-processing abort-job	终止正在运行的作业
batch-processing restart-job	重启失败的作业（可选使用新的计算设置）
batch-processing trt-compile	为一个或多个 NVIDIA 设备将模型编译为 TensorRT

说明和限制

• 仅支持异步处理 — 根据数据量和硬件情况，延迟从几分钟到几小时不等。不适用于实时场景。
• 定价：按作业计费；GPU 作业的费用高于 CPU 作业。请参阅 roboflow-plans-and-pricing。
• 图像引用摄取需要来自可信来源的签名 URL；系统会拒绝任意公共 URL — 请改为暂存到本地目录或云存储路径。

完整参考：Roboflow 批处理文档。