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/

docs: add collapsible PDF quickstart example to README (#58)

Yichuan Wang86e1de4f4198
diff --git a/README.md b/README.md
index 72cacd7..650cc7f 100644
--- a/README.md
+++ b/README.md
@@ -144,6 +144,8 @@ curl -X POST http://localhost:30001/search \
### Build an index from your own documents
+Works on **Linux (CUDA)** and **macOS (Apple Silicon / MPS)** — `device: auto` picks the best backend.
+
```bash
pip install 'pixelrag[index]'
@@ -155,8 +157,7 @@ source:
embed:
model: Qwen/Qwen3-VL-Embedding-2B
- device: cuda
- gpu_ids: [0]
+ device: auto # cuda on Linux, mps on macOS, cpu as fallback
output: ./my_index
EOF
@@ -166,6 +167,44 @@ pixelrag index build
pixelrag serve --index-dir ./my_index --port 30001
```
+<details>
+<summary><strong>Try it: index a PDF and search it locally</strong></summary>
+
+No GPU required — runs on macOS (Apple Silicon) or any machine with Python 3.10+.
+
+```bash
+pip install 'pixelrag[index]'
+
+# 1. Grab a sample PDF (or use your own)
+curl -L -o paper.pdf https://raw.githubusercontent.com/StarTrail-org/PixelRAG/main/assets/pixelrag-paper.pdf
+
+# 2. Create config (device: auto picks MPS on Mac, CUDA on Linux)
+cat > pixelrag.yaml << 'EOF'
+source:
+ type: local
+ path: ./paper.pdf
+
+embed:
+ model: Qwen/Qwen3-VL-Embedding-2B
+ device: auto
+
+output: ./paper_index
+EOF
+
+# 3. Build the index (~3 min on Apple M-series, ~1 min on GPU)
+pixelrag index build
+
+# 4. Serve it
+pixelrag serve --index-dir ./paper_index --port 30001
+
+# 5. Search — should return page 2 (the overview diagram)
+curl -X POST http://localhost:30001/search \
+ -H "Content-Type: application/json" \
+ -d '{"queries": [{"text": "Overview of PixelRAG and the diagram"}], "n_docs": 1}'
+```
+
+</details>
+
### Render a page programmatically
```python
diff --git a/embed/src/pixelrag_embed/embed.py b/embed/src/pixelrag_embed/embed.py
index eea8ce7..e210b9a 100644
--- a/embed/src/pixelrag_embed/embed.py
+++ b/embed/src/pixelrag_embed/embed.py
@@ -128,7 +128,9 @@ def _smart_resize_pil(img: "Image.Image", max_pixels: int) -> "Image.Image":
return img.resize((new_w, new_h), Image.LANCZOS)
-def _clamp_width_pil(img: "Image.Image", max_width: int = _MAX_CHUNK_WIDTH) -> "Image.Image":
+def _clamp_width_pil(
+ img: "Image.Image", max_width: int = _MAX_CHUNK_WIDTH
+) -> "Image.Image":
"""Resize image so width <= max_width, preserving aspect ratio.
Dimensions are rounded to multiples of 28 (Qwen3-VL patch alignment).
@@ -942,7 +944,10 @@ def _embed_tile_infos_with_engine(
resized_wide[0] += 1
logger.debug(
"Resized wide chunk %s ci=%d to %dx%d",
- img_path, ci, cw, ch,
+ img_path,
+ ci,
+ cw,
+ ch,
)
# Dedup key: use file path for pre-chunked files (avoids
# expensive tobytes + MD5 on ~2.7MB raw pixels per chunk)
diff --git a/embed/src/pixelrag_embed/embed_cpu.py b/embed/src/pixelrag_embed/embed_cpu.py
index e782e4e..3b717af 100644
--- a/embed/src/pixelrag_embed/embed_cpu.py
+++ b/embed/src/pixelrag_embed/embed_cpu.py
@@ -174,7 +174,9 @@ def embed_items(
)
inputs = processor(text=[text], images=[img], return_tensors="pt", padding=True)
if device != "cpu":
- inputs = {k: v.to(device) if hasattr(v, "to") else v for k, v in inputs.items()}
+ inputs = {
+ k: v.to(device) if hasattr(v, "to") else v for k, v in inputs.items()
+ }
with torch.no_grad():
outputs = model(**inputs, output_hidden_states=True)
@@ -222,7 +224,9 @@ def main():
items = items[: args.limit]
else:
logger.info("Found %d chunks to embed", len(items))
- embeddings = embed_items(items, args.model, device=args.device, instruction=args.instruction)
+ embeddings = embed_items(
+ items, args.model, device=args.device, instruction=args.instruction
+ )
output_path = Path(args.output_dir) / "shard_000.npz"
np.savez(
diff --git a/render/src/pixelrag_render/backends/pdf.py b/render/src/pixelrag_render/backends/pdf.py
index 8897fcf..17f306c 100644
--- a/render/src/pixelrag_render/backends/pdf.py
+++ b/render/src/pixelrag_render/backends/pdf.py
@@ -90,15 +90,17 @@ def render_pdf(
saved_tiles.append(tile_name)
w, h = img.size
# Each PDF page = one chunk (no further splitting)
- chunks_info.append({
- "tile": tile_name,
- "tile_index": idx,
- "chunk_index": 0,
- "file": tile_name,
- "y_offset": 0,
- "height": h,
- "width": w,
- })
+ chunks_info.append(
+ {
+ "tile": tile_name,
+ "tile_index": idx,
+ "chunk_index": 0,
+ "file": tile_name,
+ "y_offset": 0,
+ "height": h,
+ "width": w,
+ }
+ )
logger.debug(" Page %d → %s (%dx%d)", idx, tile_name, w, h)
manifest = {