StarTrail-org/PixelRAG

PixelRAG – 스크린샷 기반의 검색 증강 생성

PixelRAG는 문서의 모양에 따라 정보를 검색하고 검색할 수 있는 오픈소스 라이브러리입니다. 단순히 텍스트 내용이 아니라, 시각적 레이아웃(표, 차트, 인포그래픽 등)을 포착함으로써 기존 텍스트 중심 RAG가 놓치는 정보를 검색할 수 있습니다. 웹 페이지, PDF, 이미지를 타일형 스크린샷으로 렌더링하고, 시각-언어 모델로 이미지를 임베딩한 후, FAISS 또는 Qdrant로 벡터 인덱스를 구축합니다. 이후 텍스트 또는 이미지 기반의 쿼리를 통해 검색 가능한 API(또는 Claude 플러그인)를 제공합니다.

기능

• 렌더링: URL, PDF, 이미지를 고해상도 스크린샷 타일로 변환 (pixelshot 사용).
• 임베딩: 시각적 레이아웃(표, 차트, 인포그래픽 등)을 포착하도록 LoRA로 미세조정된 Qwen3-VL-Embedding 모델로 타일을 임베딩.
• 인덱싱: FAISS(또는 Qdrant)로 임베딩을 인덱싱하여 빠른 유사도 검색을 가능하게 함.
• API 제공: 텍스트 또는 이미지 쿼리를 수신하는 REST API (pixelrag serve)를 제공하고, 가장 관련성 높은 스크린샷 타일을 반환.
• Claude Code 플러그인 (pixelbrowse) 제공: Claude가 로컬에서 pixelshot을 호출해 페이지를 '보는' 기능을 제공.

핵심 구성 요소

명령어	역할	설치 옵션
pixelshot	문서 → 이미지 타일로 변환 (Playwright/Chromium 사용)	pip install pixelrag
pixelrag chunk / embed / build-index	타일 → 벡터 → FAISS 인덱스로 변환	pip install 'pixelrag[embed]'
pixelrag index	전체 파이프라인 조율 (소스 → 임포트 → 임베딩 → 인덱싱)	pip install 'pixelrag[index]'
pixelrag serve	FastAPI 검색 서비스 실행 (CPU 또는 GPU 지원)	pip install 'pixelrag[serve]'
Qdrant 백엔드	선택적 디스크 기반, 확장 가능한 벡터 저장소	pip install 'pixelrag[serve,qdrant]'

빠른 시작 (설정 필요 없음)

# 페이지를 타일로 렌더링
pixelshot https://en.wikipedia.org/wiki/Python -o ./tiles

# 공개 Wikipedia 인덱스에 쿼리 (828만 페이지)
curl -X POST https://api.pixelrag.ai/search \
  -H "Content-Type: application/json" \
  -d '{"queries":[{"text":"What is the capital of France?"}],"n_docs":5}'

호스팅된 API는 답변을 포함하는 스크린샷 타일을 반환하여, 하류 LLM이 시각 콘텐츠를 직접 읽을 수 있도록 합니다.

자체 인덱스 구축

# pixelrag.yaml
source:
  type: local
  path: ./my_docs
embed:
  model: Qwen/Qwen3-VL-Embedding-2B
  device: auto   # CUDA, MPS, 또는 CPU 자동 선택
output: ./my_index

pip install 'pixelrag[index]'
pixelrag index build          # 렌더링 → 임베딩 → FAISS 인덱스
pixelrag serve --index-dir ./my_index --port 30001

이후 위와 동일한 curl 요청으로 로컬 서버에 쿼리할 수 있습니다.

Claude "눈" 플러그인

1. CLI 설치로 pixelshot를 PATH에 추가 (uv tool install pixelrag 또는 pipx install pixelrag).
2. Claude Code 마켓플레이스에서 플러그인 추가 및 pixelbrowse@pixelrag-plugins 설치.
3. 다음 명령어 사용:

   claude -p "screenshot https://news.ycombinator.com and summarize the top stories"
   

   Claude는 pixelshot을 호출하고 스크린샷 타일을 수신한 후, 시각적 레이아웃 기반으로 답변합니다.

학습 (선택 사항)

리포지토리에는 Qwen3-VL-Embedding-2B를 대규모 스크린샷 데이터셋으로 LoRA 미세조정하는 train/ 폴더가 별도로 포함되어 있습니다. 사전 학습된 어댑터는 Hugging Face에 게시되어 있어, 학습 없이 바로 사용 가능합니다.

추가 정보

• 라이브 데모 및 문서: https://pixelrag.ai
• API 참조: https://pixelrag.ai/docs
• Colab 빠른 시작 노트북: README에 링크됨
• 사전 구축된 Wikipedia 인덱스: Hugging Face 데이터셋 StarTrail-org/pixelrag-faiss-indexes에서 다운로드 가능 (약 217GB).

라이선스

Apache-2.0 – 상용 및 연구용 무료.

---

PixelRAG은 시각적 구조를 검색 가능한 지식 기반으로 변환하여, LLM(Claude, GPT 등)이 표, 차트, 레이아웃에 의존하는 질문에 답할 수 있도록 합니다. 기존 텍스트 중심 RAG가 놓치는 정보를 포착할 수 있습니다.