tiiuae/Falcon-Perception

Falcon‑Perception – 다중 모달 시각-언어 모델

무엇인가요 – Falcon Perception을 위한 경량 오픈소스 PyTorch(또는 Apple‑Silicon MLX) 추론 라이브러리입니다. 자연어 질의를 기반으로 객체 탐지, 인스턴스 세그멘테이션, OCR을 수행할 수 있는 밀집형 자동회귀 트랜스포머입니다. 리포지토리는 모델 가중치(Hugging Face 경유), 고도로 최적화된 추론 엔진, REST 서버, 시각-언어 작업 사용법을 보여주는 여러 노트북을 포함합니다.

왜 중요한가요 – Falcon Perception은 객체 탐지, 인스턴스 세그멘테이션, 광학 문자 인식(OCR)이라는 세 가지 전통적인 컴퓨터 비전 문제를 하나의 언어 조건부 모델로 통합합니다. 270 M 파라미터의 Falcon OCR 1.5 버전은 훨씬 더 큰 VLM과 동등한 엔드투엔드 OCR 품질을 제공하면서도 크기가 약 3배 작아 실시간 또는 엣지 배포에 실용적입니다.

---

주요 구성 요소

구성 요소	기능
PyTorch 페이지 기반 추론 엔진	FlexAttention, CUDA-그래프 캡처, 가상 페이지 KV 캐시를 사용하여 최소 지연으로 지속적인 배치 처리를 구현(예: H100에서 프리필 약 100 ms, 업샘플링 200 ms, 디코딩 50 ms).
페이지 기반 OCR 엔진	가벼운 레이아웃 검출기(PP‑DocLayoutV3)와 영역별 OCR을 추가하되, 동일한 페이지 기반 KV 캐시를 사용해 고처리량 유지.
배치 엔진	디버깅 또는 학습 전방전파 재현에 유용한 간단한 왼쪽 패딩 배치 추론.
MLX 엔진	동일한 모델을 MLX 프레임워크로 변환하여 PyTorch/transformers 의존성 없이 Apple‑Silicon 맥에서 배치 추론 가능.
추론 서버	FastAPI 기반 REST 서비스로 GPU당 하나의 엔진을 실행(데이터 병렬)하고, 인터랙티브 데모용 Streamlit UI를 제공.
vLLM Docker 이미지	Falcon‑OCR 전용 사전 빌드 컨테이너로 OpenAI 호환 API 지원, 엔드투엔드 및 레이아웃+OCR 파이프라인 모두 가능.
노트북	인식, OCR, VLM 오케스트레이션 기반 인식 에이전트, 오픈 박스 다중 객체 추적을 위한 단계별 Colab 노트북.

---

빠른 시작 (소스에서)

# 복제 및 설치 (백엔드 자동 감지)
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 배포

# 공식 이미지 다운로드 및 1~2개 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이미지/초의 처리량 보고.

---

누구에게 적합한가요?

• 연구자 – 탐지, 세그멘테이션, OCR에 사용할 수 있는 컴팩트하고 오픈소스 기준 모델을 탐색하는 사람.
• 개발자 – "왼쪽의 고양이를 세그멘테이션"과 같은 언어 조건부 시각적 추론이 필요한 애플리케이션을 개발하는 사람.
• 배포자 – 단일 GPU에서 고처리량 OCR을 제공할 수 있는 프로덕션 준비 서버(FastAPI 또는 vLLM Docker)를 찾는 사람.
• Apple‑Silicon 사용자 – 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 트래커 등)의 작업을 기반으로 합니다.