tiiuae/Falcon-Perception

Falcon‑Perception – 多模态视觉-语言模型

是什么 – 一个轻量级、开源的 PyTorch（及 Apple-Silicon MLX）推理库，用于 Falcon Perception，这是一种密集的自回归变换器，能够根据自然语言查询 检测对象、分割实例或执行 OCR。仓库包含模型权重（通过 Hugging Face 提供）、一组高度优化的推理引擎、REST 服务器以及多个演示如何使用该模型进行视觉-语言任务的笔记本。

为何重要 – Falcon Perception 将对象检测、实例分割和光学字符识别（OCR）这三个经典计算机视觉问题统一到一个语言条件模型中。270 M 参数的 Falcon OCR 1.5 变体在保持约 3 倍更小体积的同时，实现了与更大 VLM 相当的端到端 OCR 质量，使其适用于实时或边缘部署。

---

主要组件

组件	功能
PyTorch 分页推理引擎	使用 FlexAttention、CUDA 图捕获和虚拟页 KV 缓存，实现低延迟的连续批处理（在 H100 上，预填充约 100 ms，上采样 200 ms，解码 50 ms）。
分页 OCR 引擎	添加轻量级布局检测器（PP-DocLayoutV3）和区域 OCR，仍使用相同的分页 KV 缓存以实现高吞吐量。
批处理引擎	简单的左填充批处理推理，适用于调试或复现训练前向传播。
MLX 引擎	相同模型转换为 MLX 框架，可在 Apple-Silicon Mac 上无 PyTorch/transformers 依赖地进行批处理推理。
推理服务器	基于 FastAPI 的 REST 服务，每 GPU 启动一个引擎（数据并行），并暴露 Streamlit UI 用于交互式演示。
vLLM Docker 镜像	预构建容器，专用于 Falcon-OCR 服务，支持 OpenAI 兼容 API，可处理端到端和布局+OCR 流水线。
笔记本	分步 Colab 笔记本，涵盖感知、OCR、感知代理（VLM 协调推理）和开放词汇多对象跟踪。

---

快速开始（从源码）

# 克隆并安装（自动检测后端）
git clone https://github.com/tiiuae/Falcon-Perception.git
cd Falcon-Perception
pip install -e .               # Linux 上为 PyTorch，macOS 上为 MLX
# 或显式选择后端
pip install -e "[torch]"      # CUDA GPU
pip install -e "[mlx]"        # Apple Silicon

该包包含可选扩展： ocr（添加布局检测器）、dev（tensorboard、matplotlib、ipykernel）、server（FastAPI & Uvicorn）。

---

运行模型

1. 感知（检测 / 分割）

# GPU 示例 – 自动下载模型和样本图像
python demo/perception_single.py
# 自定义图像 / 查询
python demo/perception_single.py --image myphoto.jpg --query "cat on the left"
# 仅边界框（无掩码）
python demo/perception_single.py --task detection

2. OCR（文本提取）

# 端到端 OCR（默认，适用于大多数文档）
python demo/ocr_single.py --image doc.png
# 布局感知 OCR（适用于密集多列页面）
python demo/ocr_single.py --task ocr_layout   # 需要 [ocr] 扩展

3. 批处理 / 分页处理

# 在 PBench 数据集上进行基准测试（从 HF 流式传输 50 个样本）
python demo/perception_benchmark.py
# OCRBench-v2 完整基准测试
python demo/ocr_benchmark.py

4. 服务器与 UI

# 启动多 GPU REST 服务器
python -m falcon_perception.server --config.num-gpus 2 --config.port 7680
# 在另一个终端中启动 Streamlit 演示 UI
streamlit run demo/streamlit_app.py

UI 允许上传图像、选择任务，并可视化边界框、掩码或 OCR 输出及时间信息。

---

使用 vLLM（Docker）部署 Falcon-OCR

# 拉取官方镜像并在一个或两个 GPU 上运行
docker run -d --name falcon-ocr \
  --gpus "'device=0,1'" \
  -e EXPOSED_GPU_IDS=0,1 -e VLLM_GPU=0 -e PIPELINE_GPU=1 \
  -p 8000:8000 -p 5002:5002 ghcr.io/tiiuae/falcon-ocr:latest

API 示例（端到端 OCR）

curl -X POST http://localhost:5002/falconocr/parse \
  -H "Content-Type: application/json" \
  -d '{"images": ["data:image/jpeg;base64,<...>"]}'

在 A100-80GB 上运行完整布局+OCR 流水线时，容器报告约 5,800 令牌/秒和约 2.9 图像/秒的吞吐量。

---

谁应该使用此项目？

• 研究人员：探索需要紧凑、开源基线的多模态 VLM，用于检测、分割或 OCR。
• 开发者：构建需要语言条件视觉推理的应用程序（例如，“分割左侧的猫”）。
• 部署者：寻找可在单 GPU 上以高吞吐量提供 OCR 的生产就绪服务器（FastAPI 或 vLLM Docker）。
• Apple-Silicon 用户：希望在 Mac 上运行相同模型而无需安装 PyTorch 的用户。

---

引用

如果在出版物中使用 Falcon-Perception，请引用 arXiv 技术报告：

@article{bevli2026falcon,
  title   = {Falcon Perception},
  author  = {Bevli, Aviraj and Chaybouti, Sofian and Dahou, Yasser and Hacid, Hakim and Huynh, Ngoc Dung and Le Khac, Phuc H. and Narayan, Sanath and Para, Wamiq Reyaz and Singh, Ankit},
  journal = {arXiv preprint arXiv:2603.27365},
  year    = {2026},
  url     = {https://arxiv.org/abs/2603.27365}
}

---

致谢

本项目基于 PyTorch Titan、Flex-Attention、Moondream、AnyUp 以及多个开源视觉库（Roboflow 跟踪器等）的工作成果。