Skip to content

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/.gitignore
index 02c834b..a28f164 100644
--- a/.gitignore
+++ b/.gitignore
@@ -66,3 +66,7 @@ eval/evqa_lora_inat_nothink.jsonl
eval/paper_grader_out/
node_modules/
.next/
+
+# local scratch / test artifacts (never commit)
+tmp/
+demos/demo_tiles/
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 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.md
new file mode 100644
index 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 rewrites
diff --git a/deploy/api-switch.sh b/deploy/api-switch.sh
new file mode 100755
index 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.service
new file mode 100644
index 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.target
diff --git a/deploy/pixelrag-api-upstream.conf b/deploy/pixelrag-api-upstream.conf
new file mode 100644
index 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.lock
index 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]]