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 跟蹤器等）的工作成果。