PixelRAG 딥다이브
— 웹을 "읽지" 말고 "스크린샷으로 검색"하기

문서(웹페이지·PDF·이미지)를 텍스트로 뜯어내지 않고, 화면 캡처 그대로 비전 모델에 넣어 검색하는 새로운 RAG. 표·차트·수식·레이아웃이 깨지지 않아 "사람이 눈으로 읽듯" 찾아낸다. 버클리(Berkeley SkyLab) 논문 "Web Screenshots Beat Text for Retrieval-Augmented Generation"의 공식 코드베이스다. (저장소: StarTrail-org/PixelRAG · Python(+소수 TS) · ★28→급상승 · Apache-2.0)

1프로젝트 한줄 요약

"문서를 글자로 바꾸지 말고, 찍은 사진 그대로 검색한다."

여기서 RAG를 먼저 풀어두자. 챗봇(LLM)은 자기가 학습한 것만 알기 때문에, 모르는 최신 정보나 사내 문서를 물으면 지어낸다. 그래서 "질문에 관련된 문서를 먼저 찾아와서(Retrieval), 그걸 같이 넣어주고 답을 생성(Generation)"하게 만든다. 이 "검색 + 생성" 묶음이 RAG다. PixelRAG는 그 중 '찾아오는' 부분을 텍스트가 아니라 이미지로 한다.

핵심 슬로건은 README 첫 줄 그대로다 — "The end of web parsing(웹 파싱의 종말)." 즉, 웹페이지를 분해(parsing)해 텍스트로 만드는 고전적 방법을 더 이상 쓰지 말자는 선언이다. 벤치마크의 기준은 위키백과 전체(약 828만 문서)이지만, 시스템 자체는 어떤 문서 더미에도 쓸 수 있는 범용 도구다.

2왜 주목받는가

텍스트 파싱이 잃어버리는 것 — 표·차트·레이아웃을, 픽셀은 안 잃는다.

RAG의 오랜 약점은 "문서를 글자로 바꾸는 첫 단계"에 있었다. 잘 만든 보고서 PDF를 텍스트로 추출해 보면, 깔끔하던 표가 숫자 죽처럼 엉키고, 그래프는 통째로 사라지며, 2단 편집은 줄이 뒤섞인다. 정보의 30~50%가 '글자가 아닌 형태'로 담겨 있는데, 텍스트 파싱은 그걸 버린다. PixelRAG는 이 버려지던 정보를 픽셀 그대로 보존한다.

숫자로 보는 효과 (논문 Table 1, 리더 모델 Qwen3.5-4B, 상위 3개 문서)

아래는 같은 질문 세트에 대해 "검색을 어떻게 했느냐"만 바꿔 정답률을 잰 것이다. naive=검색 거의 없음, Trafilatura=고전 텍스트 추출 RAG, base=PixelRAG(스크린샷), LoRA=PixelRAG를 위키 스크린샷에 맞게 미세조정한 버전.

표·시각 질문(NQ-Tables·EVQA·LiveVQA)에서 격차가 특히 크다 — 바로 텍스트 파싱이 약한 영역이다. 여기에 더해 트렌딩을 끌어올린 두 번째 이유가 있다: "AI 에이전트에게 눈을 달아주는" Claude Code 플러그인(pixelbrowse)을 함께 낸 것. 코딩 에이전트가 웹페이지를 글자가 아니라 스크린샷으로 직접 보게 해주는 도구라, 에이전트 개발자 사이에서 화제가 됐다(8번 섹션에서 직접 써본다).

3기술 스택 전체 지도

렌더링은 가볍게(토치 없음), 임베딩·검색은 무겁게(GPU·FAISS). 단계별로 의존성을 쪼갰다.

PixelRAG는 uv(빠른 파이썬 패키지 매니저)로 묶인 파이썬 프로젝트다. 영리한 점은 단계마다 필요한 라이브러리만 따로 설치하게 쪼갠 것 — 스크린샷만 찍고 싶은 사람은 무거운 PyTorch를 안 깔아도 된다. 아래가 "어느 단계에 무엇이 쓰이는지" 지도다.

왜 이렇게 단계별로 쪼갰을까? 위키 전체를 다루는 시스템이라 각 단계의 규모와 하드웨어가 완전히 다르기 때문이다. 렌더는 CPU만 많으면 되고(GPU 불필요), 임베딩은 GPU가 핵심이며, 검색은 메모리(RAM)가 관건이다. 한 덩어리로 묶으면 "스크린샷만 찍고 싶은데 PyTorch 2GB를 깔아야 하는" 낭비가 생긴다. 그래서 pip install 'pixelrag[embed]'처럼 필요한 단계만 골라 설치한다.

4아키텍처 심화 분석

먼저 전체 그림 한 장 → 그다음 "질문 하나가 답이 되기까지"를 한 줄기로 따라간다.

PixelRAG는 5단계 파이프라인이다. 문서가 들어가 → 그림이 되고 → 숫자가 되고 → 색인이 되고 → 검색된다. 먼저 숲을 보자.

이 다섯 단계는 모두 하나의 명령어 pixelrag로 부른다(예: pixelrag embed, pixelrag serve). 단, 1단계 캡처만은 별도 명령 pixelshot이다. 이제 대표 흐름 한 줄기를 입력부터 출력까지 손으로 따라가 보자.

흐름 ① — "웹페이지 한 장이 검색 가능한 벡터가 되기까지"

# ① RENDER — 헤드리스 크롬을 CDP로 조종해 캡처
1. 페이지 로드   크롬을 띄우고(viewport 폭 875px) URL 접속
2. 준비 대기     load → 네트워크 잠잠 → document.fonts.ready → rAF 2번(최대 1초)
3. 타일 캡처   페이지를 위→아래로 8192px씩 끊어 JPEG로 저장
                 (각 타일 직전 그 위치로 스크롤 — 안 보이면 크롬이 안 그림)
                 → tile_0000.jpg, tile_0001.jpg … + tiles.json(높이·목록)

# ② CHUNK — 긴 타일을 1024px 조각으로 자른다
4. 절단          8192px 타일 1장 → 1024px 조각 8개 (chunk_XXXX_YY.png)
                 왜? 조각이 작을수록 비전 "토큰" 수가 8배 줄어 처리량↑

# ③ EMBED — 비전 모델로 숫자 벡터화 (GPU)
5. 임베딩     각 조각을 Qwen3-VL-Embedding-2B에 통과
                 마지막 토큰 추출(last-token pool) + 길이1로 정규화(L2)
                 → embeddings float16 [N, 2048]  (.npz로 저장)

# ④ BUILD-INDEX — FAISS 색인 구축 (CPU, 일부 GPU)
6. 색인       50만 개 표본으로 군집(k-means) 학습 → 벡터 전부 추가
                 → index.faiss (IndexIVFFlat, 코사인=내적, nlist 4096)

여기서 가장 영리한 두 결정을 짚자. (1) 조각내기(chunk) — 비전 모델은 큰 그림일수록 시각 토큰(이미지를 잘게 나눈 처리 단위)을 많이 쓴다. 8192px 타일을 통째로 넣으면 토큰이 폭발한다. 1024px 조각으로 자르면 토큰이 약 8배 줄어 같은 GPU로 8배 빠르게 처리된다. (2) 정규화 + 내적 — 벡터를 길이 1로 맞추면(L2 정규화), 두 벡터의 내적(inner product)이 곧 코사인 유사도가 된다. 그래서 FAISS를 "내적" 모드로 돌리면 "방향(의미)이 가장 비슷한" 조각을 찾는 검색이 된다.

흐름 ② — "질문을 던지면 답 타일이 나오기까지"(서빙)

# ⑤ SERVE — FastAPI 검색 서버
1. 질문 인코딩  "프랑스 수도는?"을 같은 Qwen3-VL 모델로 벡터화
                 (인덱스와 똑같이: 마지막 토큰 + L2 정규화 → 코사인 일치)
2. FAISS 검색    index.search(질문벡터, k) → 가장 가까운 조각 id들
3. 결과 해석  각 id를 (article_id, tile_index, chunk_index)로 풀어
                 실제 타일 이미지 경로/URL로 변환
4. 응답          타일 이미지(또는 base64)·문서 정보를 JSON으로 반환

# 실제 호출 예시 (README)
curl -X POST http://localhost:30001/search \
  -H "Content-Type: application/json" \
  -d '{"queries": [{"text": "What is the capital of France?"}], "n_docs": 5}'

질문을 벡터로 바꿀 때 인덱스를 만들 때와 토씨 하나 안 틀리게 같은 방식(마지막 토큰 풀링 + L2 정규화)을 쓴다는 게 핵심이다. 그래야 질문 벡터와 문서 벡터가 같은 좌표계에 놓여 "코사인 유사도 1.0 = 완벽히 같은 방향"이 의미를 갖는다. GPU에서 질문 하나 인코딩은 약 42ms, FAISS 검색은 CPU에서 처리된다.

설계 패턴 — 이 레포에서 "정상"이 뭔지

코드를 처음 열면 낯선 관례가 몇 개 보인다. 미리 알아두면 길을 덜 잃는다. (가) render·embed·index·serve는 폴더가 나뉘어 있지만 사실 하나의 패키지다(루트 pyproject.toml 하나가 다섯 소스 폴더를 한 휠로 묶는다). (나) 오직 train/만 진짜 별도 프로젝트라 자체 pyproject.toml과 고정된 PyTorch 버전을 갖는다 — 학습은 cd train 후 따로 설치한다. (다) pixelrag <단계> 명령은 내부의 STAGES 표를 보고 해당 모듈을 그때그때 불러온다 — 그래서 안 깐 단계를 부르면 "pip install 'pixelrag[...]' 하세요" 안내가 뜬다.

5디렉토리 구조 해부

폴더 이름이 곧 파이프라인 단계다. 다섯 단계 + 학습 + 플러그인.

최상위 폴더를 "단계 순서"로 읽으면 구조가 한눈에 들어온다. 문서가 들어가 검색되어 나오는 길을 따라 폴더가 배치돼 있다.

6학습 포인트 (기술별)

이 레포 하나로 "멀티모달 검색 + 헤드리스 자동화 + FAISS + LoRA + 대규모 분산"을 한꺼번에.

PixelRAG는 단일 기술 예제가 아니라 현대 AI 검색 시스템의 부품이 다 모인 교과서다. 분야별로 무엇을 건질지 짚는다.

7시스템 요구사항

"맛보기"는 노트북도 OK. "위키 전체"는 데이터센터급. 단계마다 천차만별.

PixelRAG의 요구사항은 무엇을 하느냐에 따라 극단적으로 갈린다. 미리 만든 위키 인덱스로 검색만 해보는 건 가볍지만, 위키 전체를 직접 캡처·임베딩하는 건 수십 TB 디스크와 다중 GPU가 필요하다.

가장 가벼운 출발점은 "미리 만든 인덱스로 검색"이 아니라 사실 "내 문서 몇 개를 직접 렌더·임베딩"이다(위키 215GB는 개인이 감당하기 어렵다). README의 "Build an index from local documents"가 그 길로, my_docs/ 폴더 하나로 작은 인덱스를 만들어 검색까지 끝낼 수 있다 — GPU 1장이면 충분하다.

8직접 해볼 수 있는 실습 과제

"에이전트에게 눈 달기"는 10분, "내 문서 검색 엔진"은 한나절. 난이도 순.

9관련 기술 심화 학습 로드맵

PixelRAG를 100% 소화하는 8주 코스(주당 6~8시간 가정).

10핵심 키워드 사전

이 문서와 레포에 등장한 용어를 한자리에.

11참고 링크

원문·모델·관련 기술 더 파기.

• GitHub 저장소 — github.com/StarTrail-org/PixelRAG (소스·README·docs)
• 공식 사이트 / 데모 — pixelrag.ai (호스팅된 위키 검색 API)
• 임베딩 모델 — Qwen3-VL-Embedding-2B (HuggingFace)
• 공개 LoRA 어댑터 — Chrisyichuan/wiki-screenshot-embedding-lora (ckpt200)
• FAISS 인덱스 — StarTrail-org/pixelrag-faiss-indexes
• FAISS 공식 — faiss.ai · uv — docs.astral.sh/uv
• Chrome DevTools Protocol — chromedevtools.github.io/devtools-protocol
• ColPali(시각 문서 검색) — 참고: 비슷한 발상의 멀티모달 RAG · TrendShift — trendshift.io