PixelRAG: Cho Claude đôi mắt bằng cách retrieval trên ảnh chụp thay vì text

TL;DR

PixelRAG là hệ RAG open-source từ Berkeley SkyLab, BAIR và Berkeley NLP. Ý tưởng đơn giản mà điên rồ: bỏ hoàn toàn khâu parse HTML thành text, thay bằng chụp screenshot trang web rồi embed và tìm kiếm trực tiếp trên ảnh. Cả retrieval lẫn reading đều nằm trong pixel space, nhờ đó bảng số, biểu đồ, layout - những thứ text pipeline hay đánh rơi - được giữ nguyên vẹn.

Kết quả trên các benchmark khó: cải thiện tới 18.1% accuracy so với text-based RAG, giảm 3 lần chi phí token trong agent runs. Repo StarTrail-org/PixelRAG ship kèm hosted API api.pixelrag.ai phục vụ index 8.28M trang Wikipedia (~30 triệu tile ảnh) không cần key, cộng với Claude Code plugin pixelbrowse để Claude tự screenshot và đọc trang bằng mắt.

Vấn đề PixelRAG muốn giải

RAG truyền thống làm 3 việc: crawl trang, parse HTML thành text chunk, rồi embed text. Quy trình này ngon với bài blog đơn thuần, nhưng vỡ trận với web thực tế. Wikipedia stats table, báo cáo tài chính, dashboard, product doc có screenshot - bất cứ thứ gì mang thông tin ở dạng bảng, chart hay layout đều bị pipeline text bào mòn dần.

Banner PixelRAG - Web Screenshots Beat Text — Banner chính thức của PixelRAG - visual search at scale trên hàng triệu trang render.

Cứ hình dung câu hỏi "Inter Milan sút trúng đích bao nhiêu lần trong trận chung kết UCL 2010 với Bayern?". Số này nằm trong <table class="wikitable">. Text-based RAG chunk qua HTML, bảng bị flatten thành chuỗi ký tự lộn xộn, retriever bốc về đúng đoạn text quanh bảng, nhưng con số cần tìm đã bay đi từ khâu parse. Reader model đọc chunk đó không thấy số đâu, trả lời "không xác định".

PixelRAG bỏ khâu parse. Trang được render bằng Chromium (Playwright + CDP), cắt thành tile ảnh, embed bằng model vision. Khi query, retriever chọn đúng tile chứa bảng, reader model đọc thẳng con số trên hình ảnh. Câu trả lời: 7.

Kiến trúc: render, tile, embed, serve

So sánh Text-Based RAG vs PixelRAG — Text-Based RAG parse HTML mất bảng, reader không thấy số. PixelRAG render thành ảnh tile, reader đọc thẳng con số 7 trên hình (Figure 1 trong paper).

Hai mảnh ghép chính:

Rendering thay vì parsing: lệnh pixelshot chạy headless Chromium qua CDP, output là các tile ảnh. Trên Linux x64, repo bundle sẵn binary headless_shell nhẹ để tăng tốc; macOS/Windows fallback về Chrome hệ thống hoặc Chromium của Playwright, có thể ép bằng biến môi trường CHROME_PATH. Mỗi lần render dùng profile ephemeral - không đụng phiên Chrome đang mở.
Embedding model: Qwen/Qwen3-VL-Embedding-2B, LoRA fine-tune trên screenshot data. Kết quả embed đưa vào FAISS index. Adapter LoRA đã public trên Hugging Face (Chrisyichuan/wiki-screenshot-embedding-lora), kèm cả dataset screenshot-training-natural-filtered-v2 để cộng đồng adapt sang backbone khác.

Pipeline tách thành các stage độc lập, cài rời từng phần:

pip install pixelrag - có ngay pixelshot để chụp URL/PDF.
pip install 'pixelrag[embed]' - pixelrag chunk, embed, build-index.
pip install 'pixelrag[index]' - orchestrator pixelrag index chạy full pipeline source → ingest → embed → index.
pip install 'pixelrag[serve]' - FastAPI search server, CPU hoặc GPU.

Riêng phần training nằm ở train/, là uv project riêng với môi trường pin cứng (torch==2.9.1+cu129, transformers==4.57.1, cuDNN 9.20). Muốn re-train phải cd train && uv sync, không sync từ root.

Số liệu: 18.1% accuracy, giảm 3 lần token

Nhóm test trên bộ benchmark khó cho hệ RAG: NQ (Natural Questions), SimpleQA, MMSearch (multimodal open-domain QA), LiveVQA (noisy news corpora), và MoNaCo (agentic benchmarks). Với những câu hỏi phụ thuộc bảng, chart hoặc layout, PixelRAG hơn baseline text-based tới 18.1% accuracy.

Điểm lý thú thứ hai là chi phí. Nén ảnh về resolution thấp hơn giảm chi phí token per query tới 3 lần trong agent runs mà accuracy vẫn cao hơn text baseline. Với tác vụ dạng agent - nơi mỗi vòng suy nghĩ đều đốt token - đây là con số quan trọng hơn cả accuracy tuyệt đối.

Về quy mô, PixelRAG được nhóm tuyên bố là pipeline đầu tiên chạy full Wikipedia corpus dưới dạng ảnh chụp: 8.28 triệu trang Wikipedia được tile thành ~30 triệu ảnh trong datastore. Pre-built FAISS index nặng ~217 GB, publish trên Hugging Face dataset StarTrail-org/pixelrag-faiss-indexes (gồm 4 index: base/LoRA Wikipedia pixel, Wikipedia text, news pixel).

Quick start: query API hosted, hoặc index PDF local

Cách dễ nhất: gọi luôn hosted API, không setup gì.

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}'

Response trả về top 5 tile ảnh liên quan từ index 8.28M trang Wikipedia. Endpoint cũng nhận query dạng ảnh (visual search) - đưa ảnh, tìm trang có visual tương tự.

Muốn tự host index Wikipedia:

pip install 'pixelrag[serve]'

huggingface-cli download StarTrail-org/pixelrag-faiss-indexes \
  --repo-type dataset --include "search_index_normed_v2/*" --local-dir ./index

pixelrag serve --index-dir ./index/search_index_normed_v2 --port 30001

Muốn index PDF hoặc thư mục tài liệu local, một file pixelrag.yaml là đủ:

source:
  type: local
  path: ./my_docs

embed:
  model: Qwen/Qwen3-VL-Embedding-2B
  device: auto

output: ./my_index

Rồi pixelrag index build theo sau là pixelrag serve. Trên Apple M-series, index 1 PDF paper mất ~3 phút; GPU thì ~1 phút. device: auto tự chọn CUDA trên Linux, MPS trên Apple Silicon, fallback CPU nếu cần.

Give Claude eyes: plugin pixelbrowse

Phần đáng chú ý nhất với dev tag AI: renderer đóng gói thành Claude Code plugin tên pixelbrowse. Thay vì fetch HTML thô rồi mắc kẹt với DOM lộn xộn, Claude gọi pixelshot chụp trang rồi đọc ảnh. Nó thấy chart, diagram, bảng, layout đúng như con người nhìn.

uv tool install pixelrag
claude plugin marketplace add StarTrail-org/PixelRAG
claude plugin install pixelbrowse@pixelrag-plugins

Sau khi cài, chỉ cần bảo Claude nhìn trang:

claude -p "screenshot https://news.ycombinator.com and summarize the top stories"
claude -p "screenshot https://arxiv.org/abs/2404.12387 and explain the key findings"

Trong session interactive có slash command /screenshot https://example.com. Không MCP server, không backend - skill chỉ gọi pixelshot local. Điểm quan trọng: cài pixelshot qua uv tool hoặc pipx, không pip install vào venv của project - vì cần pixelshot nằm trên PATH để Claude gọi được.

So sánh nhanh với text-based RAG

Khía cạnh	Text-based RAG	PixelRAG
Ingest	Parse HTML thành text chunk	Chụp screenshot rồi tile ảnh
Embed	Text embedder (BGE, E5, OpenAI)	Qwen3-VL-Embedding-2B + LoRA
Retrieve	Text vector search	Pixel vector search
Read	Text chunk vào LLM	Ảnh tile vào VLM
Bảng, chart, layout	Thường bị mất	Giữ nguyên
Chi phí token per query	Baseline	Có thể giảm 3 lần
Accuracy khó (SimpleQA...)	Baseline	+ tới 18.1%

Giới hạn và điều kiện

Disk lớn: pre-built FAISS index Wikipedia ~217 GB. Self-host toàn bộ 4 index cần vài trăm GB SSD.
VRAM cho embed: model 2B parameters chạy được CPU/MPS, nhưng throughput thực tế ổn định khi có GPU.
Chrome dependency: Windows/macOS cần Chrome/Chromium hoặc Playwright browser. Không tìm thấy binary → set CHROME_PATH.
Hosted API best-effort: api.pixelrag.ai miễn phí, không có SLA. Ứng dụng production nên self-host.
Train env riêng biệt: muốn re-train phải sync uv project trong train/, torch phiên bản cứng cuDNN 9.20 - không dễ tuỳ biến.

Ai nên thử ngay

Dev tag AI dùng Claude Code: cài pixelbrowse. Chuyển từ "fetch HTML rồi mù" sang "screenshot rồi đọc bằng mắt" là upgrade ngay lập tức cho tác vụ browsing.
Team làm agent research: muốn agent đọc dashboard tài chính, báo cáo có chart, product doc có screenshot - PixelRAG là câu trả lời sẵn sàng dùng ngay.
Researcher RAG: paper mở, adapter mở, dataset mở, pipeline data curation documented. Thay LoRA sang backbone lớn hơn (Qwen 8B, hoặc backbone khác) là hướng nghiên cứu tự nhiên.
Ai đang xây search vertical: Wikipedia là proof-of-concept. Ingest tài liệu nội bộ (Confluence, Notion export, PDF report) chỉ là đổi source trong pixelrag.yaml.

Kết

PixelRAG không phải bài toán mới - retrieval on images đã có nhiều thử nghiệm - nhưng đây là lần đầu có pipeline chạy được ở quy mô full Wikipedia, kèm hosted API mở, plugin Claude Code, model + adapter + dataset đều Apache-2.0. Nếu app của bạn phải đọc web nhiều - search, agent browsing, RAG trên tài liệu giàu visual - thì cứ query thẳng api.pixelrag.ai hoặc index thử một thư mục PDF local là biết ngay có phù hợp không.

via StarTrail-org/PixelRAG trên GitHub - kèm via paper PIXELRAG: Web Screenshots Beat Text for Retrieval-Augmented Generation (arXiv 2606.28344).