pixelrag_embed: Chunking and Embedding Python API

pixelrag_embed provides the chunking, embedding, and index-building stages of the PixelRAG pipeline. Each stage can be run independently or together via the pixelrag index build orchestrator. Install it with pip install 'pixelrag[embed]'. The three CLI entry points correspond to the three stages:

Command	Stage	Input → Output
`pixelrag chunk`	Split tiles into 1024 px chunks	`tiles/` → `tiles/*/chunks.json`
`pixelrag embed`	Embed chunks with Qwen3-VL	`tiles/` → `embeddings/*.npz`
`pixelrag build-index`	Build FAISS or Qdrant index	`embeddings/` → `index/`

pixelrag chunk

Split 8192 px tile images into 1024 px chunk strips and write chunks.json manifests alongside the tile files. The chunking stage must run before embedding.

pixelrag chunk --tiles-dir ./tiles

Options

--tiles-dir

string

required

Directory of tile subdirectories (contains shard_* subdirectories or directly *.png.tiles directories). Mutually exclusive with --shard-dir.

--shard-dir

string

Process a single shard directory instead of all shards under --tiles-dir. Mutually exclusive with --tiles-dir.

--workers

integer

default:"96"

Number of parallel processes for shard-level parallelism.

--force

boolean

Rechunk even if chunks.json already exists. The stage compares tile MD5 hashes and skips articles whose tiles have not changed.

--delete-tiles

boolean

Delete the original tile_*.png source images from each shard after chunking. Chunk files (chunk_*.png) that are used directly as chunks are preserved. Useful for reclaiming disk space once chunking is complete.

--dry-run

boolean

Count chunks that would be written without writing any files.

Examples

# Chunk all shards under ./tiles using 16 workers
pixelrag chunk --tiles-dir ./tiles --workers 16

# Force rechunk a single shard
pixelrag chunk --shard-dir ./tiles/shard_042 --force

# Dry run to count chunks
pixelrag chunk --tiles-dir ./tiles --dry-run

pixelrag embed

Embed chunk images using Qwen3-VL-Embedding-2B and write .npz shard files. Supports multi-GPU parallelism via the sglang backend (default) or the direct GPU backend.

pixelrag embed \
  --shard-dir ./tiles/shard_042 \
  --output-dir ./embeddings/shard_042 \
  --gpu-ids 0,1

Options

--shard-dir

string

required

Input shard directory to embed (e.g. tiles/shard_042).

--output-dir

string

required

Directory to write the output .npz shard file.

--gpu-ids

string

default:"all"

Comma-separated GPU IDs to use, or "all" to use every visible GPU. Examples: "0", "0,1,2,3", "all".

--batch-size

integer

default:"128"

Number of chunk images per embedding call.

--backend

string

default:"sglang"

Embedding backend. Options: "sglang" (recommended for GPU, highest throughput), "vllm", or "direct_gpu" (direct HuggingFace transformers inference; produces embeddings identical to those used by pixelrag serve).

--mode

string

default:"chunks"

Embedding unit: "chunks" (default, 1024 px strips) or "tiles" (full 8192 px tiles). The chunks mode is strongly recommended — it reduces visual token count approximately 8×.

--model

string

default:"Qwen/Qwen3-VL-Embedding-2B"

HuggingFace model name or local path.

Examples

# Single GPU
pixelrag embed \
  --shard-dir ./tiles/shard_042 \
  --output-dir ./embeddings \
  --gpu-ids 0

# Multi-GPU with explicit batch size
pixelrag embed \
  --shard-dir ./tiles/shard_042 \
  --output-dir ./embeddings \
  --gpu-ids 0,1,2,3 \
  --batch-size 256 \
  --backend sglang

# Resume from checkpoint
pixelrag embed \
  --shard-dir ./tiles/shard_042 \
  --output-dir ./embeddings \
  --gpu-ids 0 \
  --resume

NPZ Shard Schema

Each .npz output file contains the following arrays:

Array	dtype	Shape	Description
`embeddings`	`float16`	`[N, D]`	L2-normalized embedding vectors
`article_ids`	`int64`	`[N]`	Document position index
`tile_indices`	`int32`	`[N]`	Which 8192 px tile (0-based)
`chunk_indices`	`int32`	`[N]`	Which 1024 px strip within tile (0-based)
`y_offsets`	`int32`	`[N]`	Y position of chunk top edge in page (px)
`tile_heights`	`int32`	`[N]`	Actual chunk height in pixels
`page_heights`	`int32`	`[N]`	Full page height in pixels
`viewport_widths`	`int32`	`[N]`	Page render width in pixels (capped at 875)
`image_hashes`	`S32`	`[N]`	MD5 hex digest of source chunk PNG
`tile_paths`	`S512`	`[N]`	Absolute path to the chunk PNG file
`shard_id`	`int32`	scalar	Shard number (derived from the shard directory name)

Rows are lexicographically sorted by (article_id, tile_index, chunk_index).

pixelrag build-index

Merge all shard .npz files, deduplicate, and build a FAISS IVF index (default) or upload to a Qdrant collection.

pixelrag build-index \
  --embeddings-dir ./embeddings \
  --output-dir ./index

Options

--embeddings-dir

string

default:"./data/embeddings"

Directory containing shard_*.npz files written by pixelrag embed.

--output-dir

string

default:"./output/search_index"

Directory to write index.faiss, metadata.npz, and summary.json.

--nlist

integer

default:"4096"

Number of IVF clusters. The default of 4096 is suitable for approximately 30 million vectors. pixelrag index build auto-adjusts this based on the actual vector count.

--nprobe

integer

default:"128"

Default search nprobe stored in the index and returned by /status.

--backend

string

default:"faiss"

Index backend: "faiss" (default) or "qdrant".

--qdrant-url

string

Qdrant server or Qdrant Cloud URL. Required when --backend qdrant.

--collection

string

default:"pixelrag"

Qdrant collection name.

--append

boolean

Upsert into an existing Qdrant collection instead of failing.

--recreate

boolean

Delete and recreate an existing Qdrant collection before uploading.

Examples

# Build FAISS index (default)
pixelrag build-index \
  --embeddings-dir ./embeddings \
  --output-dir ./index

# Build with custom nlist and nprobe
pixelrag build-index \
  --embeddings-dir ./embeddings \
  --output-dir ./index \
  --nlist 8192 \
  --nprobe 256

# Build Qdrant index
pixelrag build-index \
  --embeddings-dir ./embeddings \
  --output-dir ./index \
  --backend qdrant \
  --qdrant-url https://my-cluster.qdrant.io \
  --collection pixelrag \
  --recreate

The FAISS backend writes three files to --output-dir:

index/
├── index.faiss      # FAISS IVFFlat index
├── metadata.npz     # article_ids, tile_indices, chunk_indices, y_offsets, tile_heights
└── summary.json     # backend, total_vectors, dimension, nlist, nprobe, metric

REST API

Python SDK

CLI Reference

pixelrag_embed: Chunking and Embedding Python API

pixelrag chunk

Options

Examples

pixelrag embed

Options

Examples

NPZ Shard Schema

pixelrag build-index

Options

Examples

Build docs developers (and LLMs) love

REST API

Python SDK

CLI Reference

Documentation Index

​pixelrag chunk

​Options

​Examples

​pixelrag embed

​Options

​Examples

​NPZ Shard Schema

​pixelrag build-index

​Options

​Examples

Build docs developers (and LLMs) love

pixelrag chunk

Options

Examples

pixelrag embed

Options

Examples

NPZ Shard Schema

pixelrag build-index

Options

Examples