roboflow/inference · 上手攻略

  • 仓库：roboflow/inference
  • 链接：https://github.com/roboflow/inference
  • 分类：llm-infra / app（自托管计算机视觉推理服务器 + Workflow）
  • 作者：spark
  • 更新：2026-07-30

版本说明：仓库 README 中没有写死顶层版本号，文档站 inference.roboflow.com/using_inference/about 自称 "Inference 1.0"，PyPI 上 inference-sdk 的最新轮转版本为 1.3.x（如 1.3.7）——下面的命令以当前 README 与 PyPI 通用写法为准，不写死小版本号，使用 pip install ... --upgrade 拉到最新。

1. 是什么

inference 是 Roboflow 维护的自托管计算机视觉推理服务器 + Python SDK，定位是"把任意一台电脑或边缘设备变成 CV 指挥中心"。它把模型加载、GPU/CPU 加速、传统 CV（OCR、Barcode、QR、模板匹配）、最新基础模型（Florence-2、CLIP、SAM2 等）、Workflow（可视化编排）、摄像头/RTSP 视频流管理、通知与外部集成都打包在一个 Docker 镜像里，对外提供 REST API 和 inference-sdk Python 客户端。

它跟 Roboflow SaaS（roboflow.com 标注平台）的关系：roboflow Python 包负责上传/管理数据集和训练任务，inference / inference-sdk 负责部署、推理与流水线编排。Hosted 模式也可以不部署本地，直接用 https://detect.roboflow.com 之类的 API URL。

2. 解决什么问题

  • 训练完（或下载）一个 YOLO/RF-DETR/CLIP/SAM/OCR 模型后，不想手写 Flask/FastAPI + 模型加载 + 预处理 + 后处理 + GPU batching 这套模板代码。
  • 想做"链式 CV Pipeline"：检测 → 跟踪 → OCR → 业务判断 → 通知/写库。inference 的 Workflows 就是为此而生，比 OpenCV + 自写胶水代码省太多事。
  • 多摄像头 RTSP / USB 摄像头的实时分析，需要解码、GPU batching、多进程调度这些脏活。
  • 既想自己托管（数据合规/低延迟/离线）又不想放弃云端可观测性，可用 inference-cli 一键起本地 dev 模式。

不适合：

  • 训练计算机视觉模型本身——请用 roboflow Python 包（上传图片、fine-tune、下载 weights）；本仓库聚焦部署侧。
  • 想"零代码 SaaS 体验"且不在意数据出境——直接用 Roboflow Hosted API，没必须自托管。

3. 快速安装

3.1 推荐路径：inference-cli 一键启动 dev 容器

需要 Docker（如果机器有 NVIDIA GPU，再装 NVIDIA Container Toolkit）。

pip install inference-cli
inference server start --dev

该命令会自动拉适合你机器架构的镜像并以 dev 模式启动，控制台会输出 Jupyter notebook server 地址：http://localhost:9001/notebook/start。打开就是 quickstart tour。

3.2 纯 pip 路径（CPU/GPU 直接嵌到 Python 项目）

# 文档建议用 venv
python -m venv .venv && source .venv/bin/activate
pip install inference             # 服务器/库本体
pip install inference-sdk         # 轻量级 HTTP 客户端 SDK

Python 版本注意：社区报告 inference-sdk 在 Python 3.13 下有依赖兼容问题（社区贴显示需用 3.12 及以下）。本地装报错就先降到 3.11/3.12 试。

3.3 Windows 原生安装

不想装 Docker，可以下 Windows 原生安装器（README 上有链接），装好之后从开始菜单启动 "Roboflow Inference"。

3.4 Docker 自定义（生产部署）

docker pull roboflow/roboflow-inference-server-gpu    # 带 GPU
# 或
docker pull roboflow/roboflow-inference-server-cpu

docker run -p 9001:9001 \
  -e ROBOFLOW_API_KEY=... \
  roboflow/roboflow-inference-server-gpu

4. 核心用法

4.1 用 InferenceHTTPClient 调本地服务器

from inference_sdk import InferenceHTTPClient

client = InferenceHTTPClient(
    api_url="http://localhost:9001",   # 本地自托管
    # api_key="<YOUR API KEY>"          # 私有模型才需要
)

# 单张图：目标检测 / 分类 / 分割
result = client.infer(
    "https://example.com/cat.jpg",
    model_id="yolov8n-640",
)
print(result)

inference-sdk 也支持文件路径、PIL.Image、NumPy 数组；可对视频流逐帧推理（infer_on_stream("video.mp4", model_id="...")）。

4.2 本地 in-process 推理（不开服务器）

inference 主包提供 get_model(...) + .infer(...)，不需要 HTTP：

from inference import get_model

model = get_model(model_id="rfdetr-small")
results = model.infer("https://example.com/cat.jpg")

# 也可用本地图像 / NumPy
# results = model.infer("/path/to/image.jpg")

4.3 Workflows：可视化流水线

通过 Web UI 在 https://app.roboflow.com/workflows 拖拽"块"（检测、跟踪、计数、OCR、视觉条件分支、LMM 决策、HTTP 通知…），也可以通过 API 调用：

result = client.run_workflow(
    workspace_name="roboflow-docs",
    workflow_id="model-comparison",
    images={"image": "https://media.roboflow.com/workflows/examples/bleachers.jpg"},
    parameters={"model1": "yolov8n-640", "model2": "yolov11n-640"},
)
print(result)

自带 model-comparison、small-object-detection-with-sahi、multi-model-consensus、active-learning、license-plate-reader、face-blur、background-removal 等可嵌入 workflow 模板。

4.4 后端选择

文档说 inference 自动按硬件挑最快后端：ONNX / TensorRT / Hugging Face / PyTorch。如果机器有 NVIDIA GPU/Jetson，模型在该平台有 TensorRT engine 时优先使用 TensorRT。可手动通过环境变量或启动参数禁用某后端。

4.5 视频 / RTSP 流

dev 模式启动后，可在 Web UI 里接入 RTSP 或本地摄像头，inference server 负责解码、多进程调度、GPU batching、RTSP/WebRTC 输出。也可通过 SDK 让 workflow 直接消费视频流。

4.6 API 文档

启动 server 后访问 http://localhost:9001/docs（OpenAPI）或 /redoc（Redoc），可交互式调任意接口。

5. 典型适用场景

  • 零售/工单/园区/巡检的实时视频分析：车辆/人员计数、异常闯入检测、人脸/车牌模糊。
  • 少样本定制视觉模型上线：用 Roboflow 平台训练了 50 张自定义类别的小模型，要把它快速 deploy 到车间/门口设备。
  • 多模型流水线编排：OCR + 检测 + 业务规则一次性编排，免写胶水。
  • 多摄像头 OEM 集成：Roboflow 现在做 NVIDIA Jetson-based Flowbox（ruggedized CV center），预装 inference，集成 Basler/Lucid GigE 工业相机、OPC/MQTT PLC 接口（来自 PyPI 页面）。
  • 私有云 + 边缘：通过 Docker 自托管，对接企业网/PLC，业务数据不出园区。

6. 坑与注意

  • 自托管默认无鉴权 / 无 TLS / 无网络隔离——上线前必须读 Securing a Self-Hosted Server，自行加反向代理/HTTPS/防火墙。
  • Python 3.13 兼容性：inference-sdk 在 3.13 下历史上有 yanked 版本兼容问题，避开 3.13 用 3.11/3.12 最稳。
  • 私有 workspace 模型必须传 api_key 或设置 ROBOFLOW_API_KEY 环境变量；泄露 token 等于让别人用你的额度。
  • TensorRT engine 与硬件绑死，跨机迁移要重新构建；CPU/GPU 切换后端会显著影响吞吐。
  • 大视频流 + 高频推理是重负载机器，硬件资源要做 baseline：建议先在只跑一台 RTSP 时测延迟，再横向扩展。
  • 业务合规：自托管但仍然依赖 Roboflow 私有 model catalog 时，离线环境要提前确认是否真的能跑（部分模型需要首次在线校验）。

7. 与同类对比

  • vs FiftyOne / Voxel51：那些偏数据集可视化、模型评测；本仓库偏生产部署。
  • vs Ultralytics HUB / Roboflow Hosted SaaS：SaaS 模式省心，但本仓库对自托管、对工业协议、对 LLM-in-the-loop workflow 支持更深。
  • vs Hugging Face transformers + 自写 FastAPI：inference 把"模型→预处理→后处理→GPU batching→视频流→通知"的模板都做了，省 80% 胶水；代价是绑定 Roboflow 生态。
  • vs OpenVINO Model Server（OVMS）、Triton Inference Server：OVMS / Triton 更底层、跨框架（不只 CV），需要自己写前后处理；inference 是垂直 CV 解决方案，Workflows 是杀手锏。
  • vs LLM 框架（LangChain、LlamaIndex）：那些是 LLM 编排；本仓库是 CV/视觉模型编排，但 Workflows 里也接入了 VLM/LMM 块做"视觉+语言"组合判断。

8. 一句话结论

如果你需要在本地或边缘跑"摄像头 + 自定义 CV 模型 + 流水线 + 通知"这一整套东西、且不想从零拼 OpenCV+FastAPI+CUDA batching，roboflow/inference 是当下最省力的方案——pip install inference-cli && inference server start --dev 三条命令就能干起来；纯研究或只有几张图的简单分类，先用 Hugging Face pipeline 更轻，不必上 inference。