Registry / ai-ml / colpali-engine

colpali-engine

JSON →
library0.3.17pypypiunverified

ColPali Engine is a library for training and running inference with the ColPali architecture, a multimodal retrieval model based on vision-language models. It supports document indexing and retrieval using late interaction over image embeddings. Current version is 0.3.15, with active development and periodic releases.

pip install colpali-engine
INSTALL
IMPORT
SIG · COLPALI-ENGINE
C
colpali-engine
ai-mlpythonv0.3.17
Install
78.7s avg
Import
Disk
5120MB
Pass rate
3/ 10
Env Coverage3 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.17 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✕ timeout
py 3.11
✕ build_error
✓ 83.8s
py 3.12
✕ build_error
✓ 81.1s
py 3.13
✕ build_error
✓ 71.3s
py 3.9
✕ build_error
✕ timeout
5120MB installed
● package 5120MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ColPaliModel
from colpali_engine.models import ColPaliModel
import colpali_engine
Wrong: direct module import doesn't expose model class.
ColPaliProcessor
from colpali_engine.models import ColPaliProcessor
from colpali_engine.processor import ColPaliProcessor
Wrong import path in older versions; processor is in models now.
ColPaliRetriever
from colpali_engine.retrieval import ColPaliRetriever
from colpali_engine import ColPaliRetriever
Wrong: retriever module not top-level.

Basic retrieval using ColPali: load model, index documents, and search.

import torch from colpali_engine.models import ColPaliModel, ColPaliProcessor from colpali_engine.retrieval import ColPaliRetriever model_name = "vidore/colpali-v1.2" model = ColPaliModel.from_pretrained(model_name, torch_dtype=torch.bfloat16, device_map="cuda" if torch.cuda.is_available() else "cpu") processor = ColPaliProcessor.from_pretrained(model_name) # Example documents (can be images or text) docs = [ "A diagram of the ColPali architecture", "Another document with text" ] query = "ColPali architecture" # Process and index documents doc_embeddings = [] for doc in docs: with torch.no_grad(): processed = processor.process_images([doc]) embeddings = model(**processed.to(model.device)) doc_embeddings.append(embeddings) # Index with retriever retriever = ColPaliRetriever(model, processor) retriever.index(doc_embeddings) # Search results = retriever.search(query, k=2) print(results)
Debug
Known issues
breakingVersion 0.3.0 removed the 'ColPali' class and renamed the model class to 'ColPaliModel'. Code using 'from colpali_engine import ColPali' will break.
fix
Use 'from colpali_engine.models import ColPaliModel' instead.
affects: <0.3.0
deprecatedThe method 'ColPaliModel.forward()' has been deprecated in favor of directly calling the model object (__call__) or using 'model.generate()' for generation tasks.
fix
Replace 'model.forward(inputs)' with 'model(inputs)' or 'model.generate(inputs)' for text generation.
affects: >=0.3.4
gotchaGPU vs CPU: ColPali models require significant GPU memory. Running on CPU may be extremely slow. Always check device availability.
fix
Use 'device_map="cuda"' if GPU available, or set 'device_map="auto"' for automatic mapping.
affects: all
gotchaThe processor expects images in PIL format or file paths. Passing raw numpy arrays may cause errors.
fix
Ensure images are loaded via PIL.Image.open() or processor.image_processor.convert_to_rgb() before processing.
affects: all
Upgrade
Version history
0.3.17latest on PyPI · released Jun 8, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
65 hits · last 30 days
node
58
Bingbot
1
OpenAI (training)
1
Resources
colpali-engine — pip install colpali-engine · libregistry