colbert-server

CLI tooling to fetch the ColBERT Wikipedia 2017 dataset and run a lightweight Flask API on top of the ColBERT v2 searcher.

$> I wrote this because the ColBERT server is down and I couldn't try one of the tutorial from DSPy.
$> I only tested this on my macbook, please open an issue if you have problems or feature requests.

Features

• One-command install and execution via uv tool.
• Automatically downloads either ready-to-serve indexes/collection or the original archives.
• Optional archive extraction flow for offline usage.
• Caches ColBERT queries for fast, repeated lookups.
• Exposes a simple /api/search endpoint for programmatic access.
• Ships with a doctor command that validates Torch/FAISS installs before the 13 GB download.

Installation

uv tool install colbert-server

This registers a colbert-server executable in your uv toolchain.

Check the installed version at any time:

colbert-server --version

Run the built-in diagnostic command to verify torch/faiss before downloading the index:

colbert-server doctor

Or if you just want to run it:

uvx run colbert-server --help

Running the server

Use data from the Hugging Face cache (recommended quick start)

colbert-server serve --from-cache

This downloads only the collection/ and indexes/ folders from nielsgl/colbert-wiki2017, resolves the on-disk paths from the Hugging Face cache, and starts the server.

Provide existing local assets

colbert-server serve \
  --index-root /path/to/indexes \
  --index-name wiki17.nbits.local \
  --collection-path /path/to/collection/wiki.abstracts.2017/collection.tsv

Use this mode when you already have ColBERT indexes and a collection TSV locally.

Download archives first, then serve

colbert-server serve \
  --download-archives /tmp/wiki-assets \
  --extract \
  --port 8894

This fetches the archive files into /tmp/wiki-assets/archives, extracts them into /tmp/wiki-assets, auto-detects the resulting layout (e.g. wiki17.nbits.local), and starts the Flask server on port 8894.

API usage

Once running, the server listens on the host/port provided (defaults to 0.0.0.0:8893) and serves ColBERT search results via:

GET /api/search?query=<text>&k=<top-k>

Example request:

http://127.0.0.1:8893/api/search?query=halloween+movie&k=3

The JSON response includes the ranked passages, their scores, and normalized probabilities.

Managing dataset archives only

If you just want the raw archive bundles in a local directory:

colbert-server download-archives ./downloads --extract

Add --extract-to /desired/path to unpack into a different directory. You can later reuse the extracted paths with the serve command’s --index-root and --collection-path flags.

Alternative / Manual Method

In case you don't want to use the script / uv tool you can set it up as follows:

1. Add the dependencies to your project: uv add colbert-ai flask faiss-cpu and uv add torch --index pytorch-cpu (the repo already provides the PyTorch CPU index in pyproject.toml).
2. Download the files (both the index and the collection) from the archives directory from the HuggingFace dataset and unzip them.
3. Copy the standalone.py script from this repository and edit the INDEX_ROOT and COLLECTION_PATH variables.
4. Run the server with uv run standalone.py and <tada.wav>

Development tips

• Requires Python 3.13+ (or adjust the pyproject.toml requirement to match your interpreter).
• Run colbert-server --help or colbert-server serve --help to inspect available options.
• The dataset helpers live under colbert_server/data.py; server configuration sits in colbert_server/server.py.
• GitHub Actions runs lint/tests on every push across Ubuntu, macOS, and Windows; see .github/workflows/ci.yml for details.
• Publishing is handled via the Manual Release workflow. Trigger it from the Actions tab, choose the desired bump (patch/minor/major), and it will bump the version, run tests/builds, push the commit, and create the vX.Y.Z tag. Create a RELEASE_TOKEN secret with repo scope so the workflow can push back to main.
• The CLI pings PyPI at most once per day and nudges you if a newer version exists. Set COLBERT_SERVER_DISABLE_UPDATE_CHECK=1 to disable this behaviour.
• The tag automatically kicks off the Publish workflow, which uploads the artifacts to PyPI via trusted publishing. After that completes the Verify Release workflow installs the new version on Ubuntu, macOS, and Windows and runs colbert-server --version/doctor to ensure the artifact works cross-platform.

Happy searching! 🧠📚