{"id":21058,"library":"colpali-engine","title":"ColPali Engine","description":"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.","status":"active","version":"0.3.15","language":"python","source_language":"en","source_url":"https://github.com/illuin-tech/colpali-engine","tags":["retrieval","multimodal","colpali","visual-language-model","late-interaction"],"install":[{"cmd":"pip install colpali-engine","lang":"bash","label":"Install from PyPI"}],"dependencies":[],"imports":[{"note":"Wrong: direct module import doesn't expose model class.","wrong":"import colpali_engine","symbol":"ColPaliModel","correct":"from colpali_engine.models import ColPaliModel"},{"note":"Wrong import path in older versions; processor is in models now.","wrong":"from colpali_engine.processor import ColPaliProcessor","symbol":"ColPaliProcessor","correct":"from colpali_engine.models import ColPaliProcessor"},{"note":"Wrong: retriever module not top-level.","wrong":"from colpali_engine import ColPaliRetriever","symbol":"ColPaliRetriever","correct":"from colpali_engine.retrieval import ColPaliRetriever"}],"quickstart":{"code":"import torch\nfrom colpali_engine.models import ColPaliModel, ColPaliProcessor\nfrom colpali_engine.retrieval import ColPaliRetriever\n\nmodel_name = \"vidore/colpali-v1.2\"\nmodel = ColPaliModel.from_pretrained(model_name, torch_dtype=torch.bfloat16, device_map=\"cuda\" if torch.cuda.is_available() else \"cpu\")\nprocessor = ColPaliProcessor.from_pretrained(model_name)\n\n# Example documents (can be images or text)\ndocs = [\n    \"A diagram of the ColPali architecture\",\n    \"Another document with text\"\n]\n\nquery = \"ColPali architecture\"\n\n# Process and index documents\ndoc_embeddings = []\nfor doc in docs:\n    with torch.no_grad():\n        processed = processor.process_images([doc])\n        embeddings = model(**processed.to(model.device))\n        doc_embeddings.append(embeddings)\n\n# Index with retriever\nretriever = ColPaliRetriever(model, processor)\nretriever.index(doc_embeddings)\n\n# Search\nresults = retriever.search(query, k=2)\nprint(results)","lang":"python","description":"Basic retrieval using ColPali: load model, index documents, and search."},"warnings":[{"fix":"Use 'from colpali_engine.models import ColPaliModel' instead.","message":"Version 0.3.0 removed the 'ColPali' class and renamed the model class to 'ColPaliModel'. Code using 'from colpali_engine import ColPali' will break.","severity":"breaking","affected_versions":"<0.3.0"},{"fix":"Replace 'model.forward(inputs)' with 'model(inputs)' or 'model.generate(inputs)' for text generation.","message":"The method 'ColPaliModel.forward()' has been deprecated in favor of directly calling the model object (__call__) or using 'model.generate()' for generation tasks.","severity":"deprecated","affected_versions":">=0.3.4"},{"fix":"Use 'device_map=\"cuda\"' if GPU available, or set 'device_map=\"auto\"' for automatic mapping.","message":"GPU vs CPU: ColPali models require significant GPU memory. Running on CPU may be extremely slow. Always check device availability.","severity":"gotcha","affected_versions":"all"},{"fix":"Ensure images are loaded via PIL.Image.open() or processor.image_processor.convert_to_rgb() before processing.","message":"The processor expects images in PIL format or file paths. Passing raw numpy arrays may cause errors.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-27T00:00:00.000Z","next_check":"2026-07-26T00:00:00.000Z","problems":[{"fix":"Install via 'pip install colpali-engine' and not 'pip install colpali'.","cause":"The package has not been installed or is installed under the wrong name (e.g., 'colpali' instead of 'colpali-engine').","error":"ModuleNotFoundError: No module named 'colpali_engine'"},{"fix":"Use 'from colpali_engine.models import ColPaliModel'.","cause":"Importing from the wrong top-level module; ColPaliModel is in 'colpali_engine.models'.","error":"AttributeError: module 'colpali_engine' has no attribute 'ColPaliModel'"},{"fix":"Use 'processor = ColPaliProcessor.from_pretrained(model_name)' where model_name is from Hugging Face.","cause":"Using an outdated model name or the processor is not compatible; ensure both model and processor are from same repo.","error":"ValueError: The model 'vidore/colpali-v1.2' does not have a processor class"},{"fix":"Reduce batch size, use 'torch_dtype=torch.float16' or 'torch.bfloat16', or offload to CPU with 'device_map=\"auto\"'.","cause":"The model requires more GPU memory than available; batch size too large or using full precision.","error":"RuntimeError: CUDA out of memory"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}