https://arxiv.org/abs/2606.28344. The end of web parsing. The beginning of scalable pixel-native search. link: https://pixelrag.ai/
ci: blue-green search API + ops docs + faiss fix (#12)
Zhifei Li2e6c42e8783b
diff --git a/.gitignore b/.gitignoreindex 02c834b..a28f164 100644--- a/.gitignore+++ b/.gitignore@@ -66,3 +66,7 @@ eval/evqa_lora_inat_nothink.jsonleval/paper_grader_out/node_modules/.next/++# local scratch / test artifacts (never commit)+tmp/+demos/demo_tiles/diff --git a/CLAUDE.md b/CLAUDE.mdnew file mode 100644index 0000000..87aeed0--- /dev/null+++ b/CLAUDE.md@@ -0,0 +1,28 @@+# PixelRAG++Visual RAG: render documents (web pages, PDFs) as screenshot tiles and retrieve over the images+with a Qwen3-VL embedding model. See `README.md` for the product overview and `deploy/README.md`+for how it runs in production.++## Layout+- `render/` — `pixelshot` capture (Playwright/CDP, PDF)+- `embed/`, `index/` — tiles → vectors → FAISS index+- `serve/` — FAISS search API (`pixelrag serve`)+- `web/` — Next.js frontend (on Vercel) + `agent-server.mjs` (the chat agent backend)+- `train/` — **separate uv project** (LoRA finetune); install from inside `train/`, not the root+- `deploy/` — systemd units, CD workflow, blue-green scripts++## Conventions+- Python: `uv` only (`uv add`, never `uv pip install`); work in `.venv`; commit `uv.lock`.+- One distribution (`pixelrag`) with extras; the CLIs are `pixelshot` and `pixelrag <stage>`.+- `main` is branch-protected — land changes via PRs.++## Operational context (host-specific, kept out of this public repo)+Deploy/runtime details that are specific to the live host are **not** committed here. They are+imported below; the import is a harmless no-op anywhere the file doesn't exist:++@~/.claude/pixelrag-ops.md++If deploy-host notes appeared from that import, **you are on the deploy host** — production+services run there, so operate carefully. If nothing appeared, you're on a normal dev checkout+and can ignore deployment concerns.diff --git a/deploy/README.md b/deploy/README.mdnew file mode 100644index 0000000..b5df1b7--- /dev/null+++ b/deploy/README.md@@ -0,0 +1,47 @@+# Deploy++How PixelRAG runs in production. (Host-specific details — the actual machine, secrets, live+state — are intentionally **not** in this public repo; they live in an out-of-repo file the+root `CLAUDE.md` imports on the deploy host.)++## Topology+- **Frontend** (`web/`) — deployed on Vercel from `main`, automatically.+- **Search API** (`serve/`) — `pixelrag serve` behind nginx, run **blue-green** (two slots).+- **Chat agent** (`web/agent-server.mjs`) — a Node service that calls the search API.++## CD — self-hosted runner (egress-only)+Continuous deployment uses a **self-hosted GitHub Actions runner** on the deploy box. The runner+dials *out* to GitHub (no inbound access, no SSH keys or hostnames in the repo/secrets), so the+machine stays private and works behind a firewall.++`.github/workflows/deploy.yml` triggers **only** on push to `main` (post-merge = trusted code) and+manual dispatch — never `pull_request` — so fork PRs can't run on the runner. All CI stays on+GitHub-hosted runners.++On each deploy, `deploy/deploy.sh` fast-forwards the checkout and restarts **only what changed**:+- `uv.lock` → `uv sync`+- `web/agent-server.mjs` → restart the agent (cheap)+- `serve/**` → flagged only (a search-index reload is expensive — use blue-green instead)++It refuses to run unless the checkout is on a clean `main` (the deploy box doubles as a dev+machine, so it must never clobber in-progress work).++## Blue-green search API+Two slots — **blue** and **green** — each an independent `pixelrag serve` on its own port, fronted+by an nginx `upstream` (`pixelrag-api-upstream.conf` → `/etc/nginx/conf.d/`). To roll out a new+index or model with zero downtime:++1. Bring up the idle slot with the new config (`pixelrag-api-green.service` is the green slot).+2. `deploy/api-switch.sh <port>` — health- and smoke-checks the target, flips the nginx upstream+ with a graceful reload (no dropped connections), and repoints + restarts the agent.+3. **Rollback** = `deploy/api-switch.sh <other-port>`.++This is preferred over restarting a slot in place, which reloads the (large) FAISS index and would+mean minutes of downtime.++## Files+- `deploy.sh` — CD restart logic (invoked by the Deploy workflow)+- `api-switch.sh` — blue-green cutover + rollback+- `pixelrag-api.service`, `pixelrag-api-green.service` — the two search-API slots+- `pixelrag-agent.service` — the chat agent+- `pixelrag-api-upstream.conf` — nginx upstream the switch script rewritesdiff --git a/deploy/api-switch.sh b/deploy/api-switch.shnew file mode 100755index 0000000..421c11e--- /dev/null+++ b/deploy/api-switch.sh@@ -0,0 +1,41 @@+#!/usr/bin/env bash+# Blue-green switch for the PixelRAG search API.+#+# Points BOTH api.pixelrag.ai (via nginx) and the agent backend (direct on+# localhost) at the chosen slot, but only after the target passes a health+# check and a smoke query. Rollback is just switching back to the other port.+#+# blue = 30001 (base model, pixelrag-api.service)+# green = 30002 (LoRA model, pixelrag-api-green.service)+#+# Usage: deploy/api-switch.sh <port>+set -euo pipefail+PORT="${1:?usage: api-switch.sh <port> (30001=blue/base, 30002=green/lora)}"+UPSTREAM=/etc/nginx/conf.d/pixelrag-api-upstream.conf+AGENT_DROPIN=/etc/systemd/system/pixelrag-agent.service.d/backend.conf++base="http://127.0.0.1:${PORT}"++# 1. Target must be healthy.+echo "checking ${base}/health ..."+curl -fsS "${base}/health" >/dev/null || { echo "ABORT: :${PORT} is not healthy"; exit 1; }++# 2. Smoke query — the target must return sane results before taking traffic.+echo "smoke query ..."+hits=$(curl -fsS -X POST "${base}/search" -H 'Content-Type: application/json' \+ -d '{"queries":[{"text":"Albert Einstein"}],"n_docs":3}' \+ | python3 -c "import sys,json; print(len(json.load(sys.stdin)['results'][0]['hits']))")+[ "${hits:-0}" -ge 1 ] || { echo "ABORT: smoke query returned no hits"; exit 1; }+echo "smoke ok (${hits} hits)"++# 3. Flip nginx (api.pixelrag.ai) — graceful reload, zero dropped connections.+echo "upstream pixelrag_api { server 127.0.0.1:${PORT}; }" | sudo tee "$UPSTREAM" >/dev/null+sudo nginx -t && sudo nginx -s reload++# 4. Repoint the agent (it calls the API directly on localhost) + restart.+sudo mkdir -p "$(dirname "$AGENT_DROPIN")"+printf '[Service]\nEnvironment=PIXELRAG_SEARCH_URL=http://localhost:%s\n' "$PORT" | sudo tee "$AGENT_DROPIN" >/dev/null+sudo systemctl daemon-reload+sudo systemctl restart pixelrag-agent.service++echo "SWITCHED: api.pixelrag.ai + agent -> 127.0.0.1:${PORT}"diff --git a/deploy/pixelrag-api-green.service b/deploy/pixelrag-api-green.servicenew file mode 100644index 0000000..9f064af--- /dev/null+++ b/deploy/pixelrag-api-green.service@@ -0,0 +1,22 @@+[Unit]+Description=PixelRAG Search API (green slot — LoRA model)+After=network.target++[Service]+Type=simple+User=yichuan+WorkingDirectory=/home/yichuan/visrag+ExecStart=/home/yichuan/visrag/.venv/bin/pixelrag serve \+ --index-dir /home/yichuan/visrag-data/search_index_lora_vit_ckpt200_v2 \+ --tiles-dir /home/yichuan/visrag-data/tiles \+ --articles-json /home/yichuan/visrag-data/articles.json \+ --model /home/yichuan/visrag-data/models/Qwen3-VL-Embedding-2B-lora-vit-ckpt200 \+ --device cpu \+ --port 30002+Restart=always+RestartSec=10+StandardOutput=journal+StandardError=journal++[Install]+WantedBy=multi-user.targetdiff --git a/deploy/pixelrag-api-upstream.conf b/deploy/pixelrag-api-upstream.confnew file mode 100644index 0000000..e613e8a--- /dev/null+++ b/deploy/pixelrag-api-upstream.conf@@ -0,0 +1,8 @@+# Blue-green upstream for the PixelRAG search API. Installed at+# /etc/nginx/conf.d/pixelrag-api-upstream.conf and rewritten by+# deploy/api-switch.sh to point api.pixelrag.ai at the active slot.+# blue = 127.0.0.1:30001 (base model)+# green = 127.0.0.1:30002 (LoRA model)+upstream pixelrag_api {+ server 127.0.0.1:30001;+}diff --git a/uv.lock b/uv.lockindex 5e64cce..3d066a6 100644--- a/uv.lock+++ b/uv.lock@@ -379,17 +379,15 @@ wheels = [[[package]]name = "faiss-cpu"-version = "1.13.2"+version = "1.14.2"source = { registry = "https://pypi.org/simple" }dependencies = [{ name = "numpy", marker = "sys_platform == 'linux'" },{ name = "packaging", marker = "sys_platform == 'linux'" },]wheels = [- { url = "https://files.pythonhosted.org/packages/0b/d0/0940575f059591ca31b63a881058adb16a387020af1709dcb7669460115c/faiss_cpu-1.13.2-cp310-abi3-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0ee330a284042c2480f2e90450a10378fd95655d62220159b1408f59ee83ebf1", size = 11485825, upload-time = "2025-12-24T10:27:05.681Z" },- { url = "https://files.pythonhosted.org/packages/e7/e1/a5acac02aa593809f0123539afe7b4aff61d1db149e7093239888c9053e1/faiss_cpu-1.13.2-cp310-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ab88ee287c25a119213153d033f7dd64c3ccec466ace267395872f554b648cd7", size = 23845772, upload-time = "2025-12-24T10:27:08.194Z" },- { url = "https://files.pythonhosted.org/packages/9c/7b/49dcaf354834ec457e85ca769d50bc9b5f3003fab7c94a9dcf08cf742793/faiss_cpu-1.13.2-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:85511129b34f890d19c98b82a0cd5ffb27d89d1cec2ee41d2621ee9f9ef8cf3f", size = 13477567, upload-time = "2025-12-24T10:27:10.822Z" },- { url = "https://files.pythonhosted.org/packages/f7/6b/12bb4037921c38bb2c0b4cfc213ca7e04bbbebbfea89b0b5746248ce446e/faiss_cpu-1.13.2-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:8b32eb4065bac352b52a9f5ae07223567fab0a976c7d05017c01c45a1c24264f", size = 25102239, upload-time = "2025-12-24T10:27:13.476Z" },+ { url = "https://files.pythonhosted.org/packages/35/b4/d130a1908ad548671cd5ee9a1b537c7d3753cfdf0b2b134f3c10ccc6b537/faiss_cpu-1.14.2-cp310-abi3-manylinux_2_27_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b340c33212351f04d4f167cb7b22c9e756705a634d3b7b58987651f3ba1f6217", size = 9592827, upload-time = "2026-05-22T19:58:30.772Z" },+ { url = "https://files.pythonhosted.org/packages/7f/66/108f7075591b84852a6b285a81922e773c1c6d3b2c45da8ec4822f1bfab4/faiss_cpu-1.14.2-cp310-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ec4784d9a14973f2eead3a3480e6d14e74253b234e2c12717d4319f21dfadfcd", size = 18234781, upload-time = "2026-05-22T19:58:33.268Z" },][[package]]