Registry / ai-ml / colbert-ai

colbert-ai

JSON →
library0.2.22pypypiunverified

ColBERT (Contextualized Late Interaction over BERT) is an advanced neural information retrieval model that enables efficient and effective passage search over large text collections, leveraging fine-grained contextualized late interaction. The library is currently at version 0.2.22 and receives regular updates, focusing on performance, bug fixes, and broader compatibility.

pip install colbert-ai
INSTALL
IMPORT
SIG · COLBERT-AI
C
colbert-ai
ai-mlpythonv0.2.22
Install
58.8s avg
Import
Disk
613MB
Pass rate
2/ 10
Env Coverage2 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.2.22 · 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
4/8 runs
✓ 56.81s
py 3.11
4/8 runs
5/8 runs
py 3.12
4/8 runs
4/8 runs
py 3.13
4/8 runs
4/8 runs
py 3.9
4/8 runs
✓ 60.73s
613MB installed
● package 613MB
Code
Verified usage

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

ColBERT
from colbert import ColBERT
from colbert import ColBERT

This quickstart demonstrates the basic workflow for indexing a small collection of passages and then performing a search using a pre-trained ColBERT model. It covers the `Indexer` for creating a ColBERT index and the `Searcher` for querying that index. Ensure a ColBERT checkpoint is available, either by letting the library download it or by providing a local path.

import os from colbert.infra import ColBERTConfig, RunConfig, Run from colbert import Indexer, Searcher # Basic setup for running ColBERT # You might need to set up a dummy experiment directory # For real use, ensure a checkpoint exists or is downloaded # For example, download colbertv2.0 checkpoint via 'wget https://huggingface.co/colbert-ir/colbertv2.0/resolve/main/colbertv2.0.tar.gz' # A dummy collection and query for demonstration collection = [ "The quick brown fox jumps over the lazy dog.", "Artificial intelligence is a rapidly evolving field.", "Python is a popular programming language for AI and machine learning.", "Machine learning is a subset of artificial intelligence." ] queries = ["What is AI?", "Python programming"] # Configure ColBERT # Replace 'colbert-ir/colbertv2.0' with a local path if downloaded COLBERT_CHECKPOINT = os.environ.get('COLBERT_CHECKPOINT', 'colbert-ir/colbertv2.0') INDEX_ROOT = os.environ.get('COLBERT_INDEX_ROOT', 'experiments') INDEX_NAME = os.environ.get('COLBERT_INDEX_NAME', 'my_simple_index') with Run().context(RunConfig(nranks=1, experiment='default')): config = ColBERTConfig(checkpoint=COLBERT_CHECKPOINT) # 1. Indexing indexer = Indexer(checkpoint=COLBERT_CHECKPOINT, config=config, root=INDEX_ROOT) indexer.index(name=INDEX_NAME, collection=collection) # 2. Searching searcher = Searcher(index=INDEX_NAME, config=config, collection=collection, root=INDEX_ROOT) print(f"\nSearching with query: '{queries[0]}'") results = searcher.search(queries[0], k=3) for passage_id, rank, score in zip(*results): print(f"Passage ID: {passage_id}, Rank: {rank}, Score: {score:.2f}, Text: {collection[passage_id]}") print(f"\nSearching with query: '{queries[1]}'") results = searcher.search(queries[1], k=3) for passage_id, rank, score in zip(*results): print(f"Passage ID: {passage_id}, Rank: {rank}, Score: {score:.2f}, Text: {collection[passage_id]}")
Debug
Known issues
breakingThe `AdamW` optimizer was removed from the `transformers` library in recent versions (e.g., v4.36+). Older versions of `colbert-ai` (prior to 0.2.22) that import `AdamW` directly from `transformers` will break.
fix
Upgrade `colbert-ai` to version 0.2.22 or newer: `pip install --upgrade colbert-ai`. If upgrading is not an option, downgrade `transformers` to a compatible version (e.g., `transformers==4.35.2`).
affects: <0.2.22
gotchaInstalling PyTorch and FAISS (especially `faiss-gpu`) via `pip` can sometimes lead to stability issues or incorrect CUDA configurations. The official ColBERT documentation often recommends using `conda` for these specific dependencies.
fix
Consider setting up your environment with `conda` for `pytorch` and `faiss-gpu` to ensure optimal and stable installations, especially for GPU acceleration. Refer to the official ColBERT GitHub README for `conda` installation commands.
affects: All
gotchaIndexing large collections can be memory and compute intensive, particularly without GPU acceleration. Failures can occur if CUDA is not correctly configured or if system resources are exhausted during the indexing process.
fix
Ensure CUDA drivers and `faiss-gpu` are correctly installed and configured. Monitor GPU memory usage during indexing. For very large collections, consider processing in batches or using more powerful hardware. Check for `nvcc` path errors if running on GPU.
affects: All
bugA bug in `loaders.py` related to regex handling could cause indexing failures with certain collection inputs.
fix
Upgrade `colbert-ai` to version 0.2.22 or newer: `pip install --upgrade colbert-ai`.
affects: <0.2.22
Upgrade
Version history
0.2.22latest on PyPI · released Aug 11, 2025
Audit
Dependencies
torchrequiredCore deep learning framework for model operations.
transformersrequiredIntegrates Hugging Face models and utilities.
faiss-cpuoptionalEfficient similarity search for CPU (required if [faiss-cpu] extra is not used).
faiss-gpuoptionalEfficient similarity search for GPU (highly recommended for performance, requires CUDA).
Agent activity
52 hits · last 30 days
node
44
OpenAI (training)
1
Resources