### LoTTE Evaluation Script Output Example

Source: https://github.com/stanford-futuredata/colbert/blob/main/LoTTE.md

Shows example output from the `evaluate_lotte_rankings.py` script, including Success@k metrics for different query types and datasets.

```text
[query_type=search, dataset=writing] Success@5: 80.1
[query_type=search, dataset=recreation] Success@5: 72.3
[query_type=search, dataset=science] Success@5: 56.7
[query_type=search, dataset=technology] Success@5: 66.1
[query_type=search, dataset=lifestyle] Success@5: 84.7
[query_type=search, dataset=pooled] Success@5: 71.6

[query_type=forum, dataset=writing] Success@5: 76.3
[query_type=forum, dataset=recreation] Success@5: 70.8
[query_type=forum, dataset=science] Success@5: 46.1
[query_type=forum, dataset=technology] Success@5: 53.6
[query_type=forum, dataset=lifestyle] Success@5: 76.9
[query_type=forum, dataset=pooled] Success@5: 63.4

```

--------------------------------

### Install ColBERT with GPU Support

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Install ColBERT using pip or conda. The pip installation is recommended for most users. Conda is more reliable for GPU servers with faiss and torch.

```bash
# pip (recommended for most users)
pip install colbert-ai[torch,faiss-gpu]
```

```bash
# conda (more reliable for faiss + torch on GPU servers)
conda env create -f conda_env.yml
conda activate colbert
```

```bash
# CPU-only environment
conda env create -f conda_env_cpu.yml
conda activate colbert
```

--------------------------------

### ColBERT Search Example

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2updated.ipynb

Demonstrates how to perform a search query using ColBERT and print the top-k retrieved passages with their scores and content.

```python
queries = [filtered_queries[13], filtered_queries[5], filtered_queries[3], "How do I move files from desktop to virtual machine?"] # try with an in-range query or supply your own

for query in queries:
  print(f">> {query}")

  # Find the top-3 passages for this query
  results = searcher.search(query, k=3)

  # Print out the top-k retrieved passages
  for passage_id, passage_rank, passage_score in zip(*results):
      print(f"\t [{passage_rank}] \t\t {passage_score:.1f} \t\t {searcher.collection[passage_id]}")

```

--------------------------------

### Install ColBERT with FAISS-GPU and PyTorch

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2updated.ipynb

Installs the ColBERT library along with FAISS-GPU and PyTorch dependencies. Ensure you have a compatible CUDA version if using FAISS-GPU.

```bash
!pip install "colbert-ir[faiss-gpu, torch]"
```

--------------------------------

### Query Tokenizer Tensorization Example

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2new.ipynb

Demonstrates the tensorization of a query using QueryTokenizer, showing input and output IDs and masks. This is useful for preparing text data for transformer models.

```python
#> are some cats just skinny?

#> QueryTokenizer.tensorize(batch_text[0], batch_background[0], bsize) ==
#> Input: . are some cats just skinny?, 		 True, 		 None
#> Output IDs: torch.Size([32]), tensor([  101,     1,  2024,  2070,  8870,  2074, 15629,  1029,   102,   103,
          103,   103,   103,   103,   103,   103,   103,   103,   103,   103,
          103,   103,   103,   103,   103,   103,   103,   103,   103,   103,
          103,   103])
#> Output Mask: torch.Size([32]), tensor([1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
        0, 0, 0, 0, 0, 0, 0, 0])
```

--------------------------------

### Start ColBERT HTTP Server

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Set environment variables for index location and name, then run the server script. The server will be accessible at http://localhost:8893.

```bash
# Set environment variables in .env
# INDEX_ROOT=/path/to/experiments/msmarco/indexes
# INDEX_NAME=msmarco.nbits=2

python server.py
# Server runs at http://localhost:8893
```

--------------------------------

### Trainer.train

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/source/trainer.rst

Starts and executes the training process.

```APIDOC
## trainer.Trainer.train(self, ...)

Executes the training process.

### Parameters

This method accepts various parameters to control the training execution. Please refer to the full documentation for a detailed list of parameters.
```

--------------------------------

### ColBERT Progress Bar Example

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2updated.ipynb

Example of a progress bar indicating the completion of a ColBERT task.

```text
100%|██████████| 1/1 [00:00<00:00, 59.96it/s]

```

--------------------------------

### Run ColBERTv2 Server

Source: https://github.com/stanford-futuredata/colbert/blob/main/README.md

This command starts a lightweight ColBERTv2 server. Ensure the INDEX_ROOT and INDEX_NAME environment variables are set in the .env file to point to your ColBERT index. The server provides search results in JSON format.

```bash
python server.py
```

--------------------------------

### ColBERT Query Tokenization Output

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2updated.ipynb

Example output from ColBERT's QueryTokenizer, showing input, output IDs, and output mask for a given query.

```text
#> are some cats just skinny?

#> QueryTokenizer.tensorize(batch_text[0], batch_background[0], bsize) ==
#> Input: . are some cats just skinny?, 		 True, 		 None
#> Output IDs: torch.Size([32]), tensor([  101,     1,  2024,  2070,  8870,  2074, 15629,  1029,   102,   103,
          103,   103,   103,   103,   103,   103,   103,   103,   103,   103,
          103,   103,   103,   103,   103,   103,   103,   103,   103,   103,
          103,   103])
#> Output Mask: torch.Size([32]), tensor([1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
        0, 0, 0, 0, 0, 0, 0, 0])

	 [1] 		 15.6 		 It could be an indication of a fever, or it could be a sign of some other medical problem, such as an ear infection. It is probably a good idea to get your dog checked out by a vet.
	 [2] 		 15.6 		 So I was at the feed store today getting a couple bales of hay, and some wood pellet litter. I picked up a 10 pound bag of whole safflower seed. When I got home I spread some out in the bottom of a baking pan and set on the floor where the bunnies would encounter it. After about 30 minutes the first bunny approached the pan. After her exploration of the pan she had to taste the contents, ate a bit and hopped off. A couple minutes later she was back again, for another serving. I picked up the pan and presented it to one of the other girls, who had not come over to explore, she tasted some, the went back for more. As John points out in his answer. there does not seem to be any issues with rabbits ingesting safflower seed. It can be a valuable food product. So other than over eating there are probably no health concerns. Based on my minimal experiment a drain through litter box using whole safflower seed is probably not a good solution with a rabbit. It is relatively expensive, and they could easily overeat assuming you kept it topped off. If a cat is using this solution you would want to keep the box away from the rabbit as cat feces could be digested, and this could be problematic. I dont see any advantages to using a safflower seed drain through litter box with a rabbit. If you want to feed the seed, do so in a controlled method. With the rabbit eating the all the litter you are unlikely to see the benefits with this type of system as you would with a cat. P.S. I tasted the seed it is like a small sunflower seed with a woody but edible shell, The meat inside is correspondingly small. Excessive intake would be a very rich diet and would be contraindicated see this related question
	 [3] 		 15.5 		 Always assume that essential oils are not safe for cats. There are a few, however, that are. If cedarwood oil is made without phenol, then it is ok. If you cannot find it without phenol, I recommend bathing them with a 50/50 solution of dawn dish soap and warm water. Do not wet them first. Use a flea comb to remove the fleas from their head, then start applying the dawn mixture as high up on their neck as you can safely. Saturate them in the mixture and then wrap them in a towel. It will need to stay on for 15 to 20 minutes, so theyll need to be kept warm. The fleas will start to die after about 12 minutes. Put any live fleas from the comb in a dawn mixture as well. Then rinse the kitten well with warm water, towel them like a burrito for a while and perhaps use a cool blowdryer on low to finish if they dont freak out. Good luck.
#> is cat skin tougher than human skin?

```

--------------------------------

### Create and Activate Conda Environment for ColBERT

Source: https://github.com/stanford-futuredata/colbert/blob/main/README.md

Use these commands to create a new conda environment for ColBERT and activate it. This is the recommended installation method, especially for managing dependencies like FAISS and PyTorch.

```bash
conda env create -f conda_env[_cpu].yml
conda activate colbert
```

--------------------------------

### Trainer Training

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/_sources/trainer.rst.txt

Starts and manages the model training process.

```APIDOC
## trainer.Trainer.train

Executes the training loop for the model.
```

--------------------------------

### Install ColBERT Dependencies in Colab

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2new.ipynb

Installs ColBERT and its dependencies (faiss-gpu, torch) using pip, specifically for Google Colab environments. Includes fallback for non-Colab environments.

```python
try: # When on google Colab, let's install all dependencies with pip.
    import google.colab
    !pip install -U pip
    !pip install -e ColBERT/['faiss-gpu','torch']
except Exception:
  import sys; sys.path.insert(0, 'ColBERT/')
  try:
    from colbert import Indexer, Searcher
  except Exception:
    print("If you're running outside Colab, please make sure you install ColBERT in conda following the instructions in our README. You can also install (as above) with pip but it may install slower or less stable faiss or torch dependencies. Conda is recommended.")
    assert False

```

--------------------------------

### Train ColBERTv2 Style Model

Source: https://github.com/stanford-futuredata/colbert/blob/main/README.md

This snippet demonstrates advanced training for ColBERTv2 style models. It allows for more configuration options, including learning rate, warmup steps, document maximum length, and dimension size. Training can start from a pre-trained ColBERTv1 checkpoint or from scratch.

```python
from colbert.infra.run import Run
from colbert.infra.config import ColBERTConfig, RunConfig
from colbert import Trainer


def train():
    # use 4 gpus (e.g. four A100s, but you can use fewer by changing nway,accumsteps,bsize).
    with Run().context(RunConfig(nranks=4)):
        triples = '/path/to/examples.64.json'  # `wget https://huggingface.co/colbert-ir/colbertv2.0_msmarco_64way/resolve/main/examples.json?download=true` (26GB) 
        queries = '/path/to/MSMARCO/queries.train.tsv'
        collection = '/path/to/MSMARCO/collection.tsv'

        config = ColBERTConfig(bsize=32, lr=1e-05, warmup=20_000, doc_maxlen=180, dim=128, attend_to_mask_tokens=False, nway=64, accumsteps=1, similarity='cosine', use_ib_negatives=True)
        trainer = Trainer(triples=triples, queries=queries, collection=collection, config=config)

        trainer.train(checkpoint='colbert-ir/colbertv1.9')  # or start from scratch, like `bert-base-uncased`


if __name__ == '__main__':
    train()
```

--------------------------------

### Sample ColBERTv2 Server Query

Source: https://github.com/stanford-futuredata/colbert/blob/main/README.md

Example of a search query to the ColBERTv2 server. Replace 'Who won the 2022 FIFA world cup' with your query and adjust 'k' for the number of results.

```http
http://localhost:8893/api/search?query=Who won the 2022 FIFA world cup&k=25
```

--------------------------------

### Query ColBERT Server via HTTP

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Use curl to send an HTTP GET request to the search API, specifying the query and the number of top results (k). The response is returned as JSON.

```bash
# Query via HTTP GET — returns top-k results as JSON
curl "http://localhost:8893/api/search?query=Who+won+the+2022+FIFA+world+cup&k=5"
```

--------------------------------

### Create and Run Indexer

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro.ipynb

Initializes and runs the `Indexer` to create a compressed index for the collection. This process requires specifying the number of ranks (GPUs) and an experiment name.

```python
with Run().context(RunConfig(nranks=4, experiment='notebook')):  # nranks specifies the number of GPUs to use.
    config = ColBERTConfig(doc_maxlen=doc_maxlen, nbits=nbits)

    indexer = Indexer(checkpoint=checkpoint, config=config)
    indexer.index(name=index_name, collection=collection, overwrite=True)
```

--------------------------------

### Evaluate LoTTE Benchmark Rankings

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Download the LoTTE dataset, prepare rankings in the specified format, and run the evaluation script. The script calculates Success@k metrics for different splits and datasets.

```bash
# Download dataset
wget https://downloads.cs.stanford.edu/nlp/data/colbert/colbertv2/lotte.tar.gz
tar -xzf lotte.tar.gz

# Produce rankings directory with this structure:
# rankings/test/writing.search.ranking.tsv  (qid<TAB>pid<TAB>rank<TAB>score)
# rankings/test/technology.search.ranking.tsv
# ... (one file per domain + query type)

# Run evaluation — Success@5 metric
python evaluate_lotte_rankings.py \
    --k 5 \
    --split test \
    --data_path /path/to/lotte \
    --rankings_path /path/to/rankings
```

--------------------------------

### Indexer Class Initialization

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/indexer.html

Initializes the Indexer with a specified checkpoint and an optional configuration. Use Run().context() to choose the run's configuration; they are NOT extracted from config.

```APIDOC
## Indexer Class

### Description
Initializes the Indexer with a specified checkpoint and an optional configuration.

### Parameters
*   **checkpoint**: The checkpoint to use for initialization.
*   **config** (optional): The configuration object. Use Run().context() to choose the run's configuration. They are NOT extracted from config.
```

--------------------------------

### Trainer.__init__

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/source/trainer.rst

Initializes the Trainer object.

```APIDOC
## trainer.Trainer.__init__(self, ...)

Initializes the Trainer.

### Parameters

This method accepts various parameters to configure the trainer. Please refer to the full documentation for a detailed list of parameters.
```

--------------------------------

### Evaluate LoTTE Rankings Script Usage

Source: https://github.com/stanford-futuredata/colbert/blob/main/LoTTE.md

Demonstrates how to use the `evaluate_lotte_rankings.py` script with specified paths and parameters.

```bash
python evaluate_lotte_rankings.py --k 5 --split test --data_path /path/to/lotte --rankings_path /path/to/rankings

```

--------------------------------

### Get Index

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/indexer.html

Retrieves the current index managed by the Indexer.

```APIDOC
## get_index

### Description
Retrieves the current index managed by the Indexer.

### Returns
The index object.
```

--------------------------------

### Download ColBERTv2 Checkpoint and LoTTE Dataset

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro.ipynb

Downloads the pre-trained ColBERTv2 model checkpoint and the LoTTE benchmark dataset. These are necessary for indexing and searching.

```bash
!mkdir -p downloads/

# ColBERTv2 checkpoint trained on MS MARCO Passage Ranking (388MB compressed)
!wget https://downloads.cs.stanford.edu/nlp/data/colbert/colbertv2/colbertv2.0.tar.gz -P downloads/
!tar -xvzf downloads/colbertv2.0.tar.gz -C downloads/

# The LoTTE dev and test sets (3.4GB compressed)
!wget https://downloads.cs.stanford.edu/nlp/data/colbert/colbertv2/lotte.tar.gz -P downloads/
!tar -xvzf downloads/lotte.tar.gz -C downloads/
```

--------------------------------

### Get Index Path

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro.ipynb

Retrieves the absolute file path of the generated index. This can be useful for referencing the index in other contexts.

```python
indexer.get_index() # You can get the absolute path of the index, if needed.
```

--------------------------------

### Download Pre-built ColBERT Index

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2updated.ipynb

Downloads a pre-built ColBERT index from the HuggingFace repository. This is an alternative to manually running the indexer, saving time.

```python
APPLY_INDEXING = True

if APPLY_INDEXING:
    from huggingface_hub import snapshot_download

    !mkdir "index"
    indexer = snapshot_download(repo_id="colbert-ir/indexes", local_dir="index")
    index_name = indexer + "/intro_colbert"
```

--------------------------------

### Initialize and Run ColBERT Indexer

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2new.ipynb

Initialize the ColBERT Indexer with a specified checkpoint and configuration, then index a subset of the collection. The `overwrite=True` argument ensures that an existing index with the same name is replaced.

```python
checkpoint = 'colbert-ir/colbertv2.0'

with Run().context(RunConfig(nranks=1, experiment='notebook')):  # nranks specifies the number of GPUs to use
    config = ColBERTConfig(doc_maxlen=doc_maxlen, nbits=nbits, kmeans_niters=4) # kmeans_niters specifies the number of iterations of k-means clustering; 4 is a good and fast default.
                                                                                # Consider larger numbers for small datasets.

    indexer = Indexer(checkpoint=checkpoint, config=config)
    indexer.index(name=index_name, collection=collection[:max_id], overwrite=True)
```

--------------------------------

### Trainer Initialization

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/trainer.html

Initializes the Trainer object with triples, queries, collection, and an optional configuration.

```APIDOC
## Trainer

### Description
Initializes the Trainer object.

### Signature
`trainer.Trainer(triples, queries, collection, config=None)`

### Parameters
- **triples**: Data representing triples.
- **queries**: Data representing queries.
- **collection**: Data representing the collection.
- **config** (optional): Configuration object for the trainer.
```

--------------------------------

### Launch Indexer

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/source/indexer.rst

Launches the Indexer service or process.

```APIDOC
## indexer.Indexer.__launch__(*args, **kwargs)

Launches the Indexer service or process.
```

--------------------------------

### Indexer Initialization

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/source/indexer.rst

Initializes a new instance of the Indexer class.

```APIDOC
## indexer.Indexer.__init__(*args, **kwargs)

Initializes a new instance of the Indexer class.
```

--------------------------------

### Trainer Initialization

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/_sources/trainer.rst.txt

Initializes the Trainer object.

```APIDOC
## trainer.Trainer.__init__

Initializes a new instance of the Trainer class.
```

--------------------------------

### Run Context Manager for Experiment Configuration

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Use the `Run` context manager to set up experiment paths, GPU assignments, and distributed configuration. Nested contexts inherit settings from the outer context by default.

```python
from colbert.infra import Run, RunConfig

# Single-GPU context, results saved under ./experiments/msmarco/
with Run().context(RunConfig(nranks=1, experiment="msmarco")):
    # All Indexer / Searcher / Trainer calls go here
    pass

# Multi-GPU context (4 GPUs)
with Run().context(RunConfig(nranks=4, experiment="msmarco")):
    pass

# Nested contexts are supported; inner context inherits outer by default
with Run().context(RunConfig(nranks=1, experiment="outer")):
    with Run().context(RunConfig(experiment="inner")):
        print(Run().experiment)  # "inner"
        print(Run().nranks)      # 1 (inherited)
```

--------------------------------

### Trainer.configure

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/trainer.html

Configures the trainer with keyword arguments.

```APIDOC
## Trainer.configure

### Description
Configures the trainer using keyword arguments.

### Signature
`trainer.Trainer.configure(self, **kw_args)`

### Parameters
- **&&kw_args**: Arbitrary keyword arguments to configure the trainer.
```

--------------------------------

### Initialize ColBERT Searcher

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2new.ipynb

Initialize the ColBERT Searcher using the index name and collection. The `RunConfig` should specify the same experiment name used during indexing to locate the index correctly.

```python
# To create the searcher using its relative name (i.e., not a full path), set
# experiment=value_used_for_indexing in the RunConfig.
with Run().context(RunConfig(experiment='notebook')):
    searcher = Searcher(index=index_name, collection=collection)


# If you want to customize the search latency--quality tradeoff, you can also supply a
# config=ColBERTConfig(ncells=.., centroid_score_threshold=.., ndocs=..) argument.
# The default settings with k <= 10 (1, 0.5, 256) gives the fastest search,
# but you can gain more extensive search by setting larger values of k or
# manually specifying more conservative ColBERTConfig settings (e.g. (4, 0.4, 4096)).
```

--------------------------------

### Trainer.train

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/trainer.html

Initiates the training process using a specified checkpoint.

```APIDOC
## Trainer.train

### Description
Starts the training process. The `config.checkpoint` is ignored; only the provided `checkpoint` is used.

### Signature
`trainer.Trainer.train(self, checkpoint='bert-base-uncased')`

### Parameters
- **checkpoint** (string, optional): The checkpoint to use for training. Defaults to 'bert-base-uncased'.
```

--------------------------------

### Initialize ColBERT Searcher

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2updated.ipynb

Initializes a ColBERT Searcher for retrieving documents from a pre-built index. The index name and collection are required parameters. Custom search latency-quality tradeoffs can be configured.

```python
# To create the searcher using its relative name (i.e., not a full path), set
# experiment=value_used_for_indexing in the RunConfig.
with Run().context(RunConfig(experiment='notebook')):
    searcher = Searcher(index=index_name, collection=collection)


# If you want to customize the search latency--quality tradeoff, you can also supply a
# config=ColBERTConfig(ncells=.., centroid_score_threshold=.., ndocs=..) argument.
# The default settings with k <= 10 (1, 0.5, 256) gives the fastest search,
# but you can gain more extensive search by setting larger values of k or

```

--------------------------------

### Searcher Initialization

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/searcher.html

Initializes the Searcher object with an index and optional checkpoint, collection, or configuration.

```APIDOC
## Searcher Initialization

### Description
Initializes the Searcher object.

### Parameters
- **index**: The index to search.
- **checkpoint** (optional): The checkpoint to load.
- **collection** (optional): The collection to use.
- **config** (optional): The configuration to use.
```

--------------------------------

### Initialize Searcher

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro.ipynb

Initializes the `Searcher` object using the index name. The `RunConfig` must specify the same `experiment` name used during indexing.

```python
# To create the searcher using its relative name (i.e., not a full path), set
# experiment=value_used_for_indexing in the RunConfig.
with Run().context(RunConfig(experiment='notebook')):
    searcher = Searcher(index=index_name)


# If you want to customize the search latency--quality tradeoff, you can also supply a
# config=ColBERTConfig(ncells=.., centroid_score_threshold=.., ndocs=..) argument.
# The default settings with k <= 10 (1, 0.5, 256) gives the fastest search,
# but you can gain more extensive search by setting larger values of k or
# manually specifying more conservative ColBERTConfig settings (e.g. (4, 0.4, 4096)).
```

--------------------------------

### Inspect Loaded Data

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2new.ipynb

Prints a sample query and passage from the loaded dataset to verify the data was loaded correctly.

```python
print(queries[24])
print()
print(collection[19929])
print()
```

--------------------------------

### Indexer Configuration

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/indexer.html

Configures the Indexer with provided keyword arguments.

```APIDOC
## configure

### Description
Configures the Indexer with provided keyword arguments.

### Parameters
*   **&&kw_args**: Arbitrary keyword arguments for configuration.
```

--------------------------------

### ColBERTConfig for Training Settings

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Configure training parameters for ColBERTv2, including batch size, learning rate, warmup steps, document length, embedding dimension, and the use of in-batch negatives. Specify similarity metric and accumulation steps.

```python
# Training config — ColBERTv2 style with in-batch negatives
train_config = ColBERTConfig(
    bsize=32,
    lr=1e-05,
    warmup=20_000,
    doc_maxlen=180,
    dim=128,
    attend_to_mask_tokens=False,
    nway=64,                  # number of negatives per positive
    accumsteps=1,
    similarity="cosine",
    use_ib_negatives=True,    # in-batch negatives (ColBERTv2)
)
```

--------------------------------

### Trainer.configure

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/source/trainer.rst

Configures the trainer with specified settings.

```APIDOC
## trainer.Trainer.configure(self, ...)

Configures the trainer settings.

### Parameters

This method accepts various parameters to configure the trainer. Please refer to the full documentation for a detailed list of parameters.
```

--------------------------------

### Batch Retrieval Over a Query File with Searcher.search_all

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Execute retrieval for multiple queries from a file and save the results in MSMARCO ranking format. Ensure the queries.tsv file is correctly formatted and specify the desired number of results (k).

```python
from colbert.data import Queries
from colbert.infra import Run, RunConfig, ColBERTConfig
from colbert import Searcher

if __name__ == '__main__':
    with Run().context(RunConfig(nranks=1, experiment="msmarco")):

        config = ColBERTConfig(root="/path/to/experiments")
        searcher = Searcher(index="msmarco.nbits=2", config=config)

        # queries.tsv format: each line is  qid<TAB>query_text
        queries = Queries("/path/to/MSMARCO/queries.dev.small.tsv")
        ranking = searcher.search_all(queries, k=100)

        # Save as TSV: qid<TAB>pid<TAB>rank<TAB>score
        ranking.save("msmarco.nbits=2.ranking.tsv")
        # Output: /path/to/experiments/msmarco/.../msmarco.nbits=2.ranking.tsv

        # Evaluate with official MSMARCO script
        # python -m utility.evaluate.msmarco_passages \
        #   --ranking "/path/to/msmarco.nbits=2.ranking.tsv" \
        #   --qrels "/path/to/MSMARCO/qrels.dev.small.tsv"
        # Expected: MRR@10 ~= 0.397
```

--------------------------------

### Advanced ColBERTv2-style Training

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Perform ColBERTv2 training using 64-way distillation triples and in-batch negatives for state-of-the-art retrieval quality. This method requires multiple GPUs and specific configuration parameters.

```python
from colbert.infra import Run, RunConfig, ColBERTConfig
from colbert import Trainer

def train():
    # Requires 4 GPUs (e.g. A100s); reduce nway/bsize for fewer GPUs
    with Run().context(RunConfig(nranks=4)):
        # Download: https://huggingface.co/colbert-ir/colbertv2.0_msmarco_64way
        triples    = '/path/to/examples.64.json'
        queries    = '/path/to/MSMARCO/queries.train.tsv'
        collection = '/path/to/MSMARCO/collection.tsv'

        config = ColBERTConfig(
            bsize=32,
            lr=1e-05,
            warmup=20_000,
            doc_maxlen=180,
            dim=128,
            attend_to_mask_tokens=False,
            nway=64,
            accumsteps=1,
            similarity='cosine',
            use_ib_negatives=True,
        )

        trainer = Trainer(
            triples=triples,
            queries=queries,
            collection=collection,
            config=config,
        )

        # Start from ColBERTv1.9 (recommended) or 'bert-base-uncased'
        trainer.train(checkpoint='colbert-ir/colbertv1.9')

if __name__ == '__main__':
    train()

```

--------------------------------

### Trainer Configuration

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/_sources/trainer.rst.txt

Configures the Trainer with specified parameters.

```APIDOC
## trainer.Trainer.configure

Configures the trainer with various settings.
```

--------------------------------

### Load LoTTE Benchmark Dataset

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2new.ipynb

Loads the LoTTE benchmark dataset from HuggingFace, specifically the 'lifestyle:dev' collection and search queries. It then extracts the text passages and query strings into Python lists. This snippet also shows the expected output format for the dataset loading process.

```python
from datasets import load_dataset

dataset = 'lifestyle'
datasplit = 'dev'

collection_dataset = load_dataset("colbertv2/lotte_passages", dataset)
collection = [x['text'] for x in collection_dataset[datasplit + '_collection']]

queries_dataset = load_dataset("colbertv2/lotte", dataset)
queries = [x['query'] for x in queries_dataset['search_' + datasplit]]

f'Loaded {len(queries)} queries and {len(collection):,} passages'
```

--------------------------------

### Load and Use Collection and Queries

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Load data from TSV files or construct collections and queries in-memory using the Collection and Queries classes. Supports saving data to disk.

```python
from colbert.data import Collection, Queries

# Load from TSV files
collection = Collection(path="/path/to/collection.tsv")
queries    = Queries(path="/path/to/queries.dev.small.tsv")

print(len(collection))         # e.g. 8841823
print(collection[0])           # "The presence of communication ..."
print(list(queries.items())[:2])
# [(0, "What is a lobster roll?"), (1, "What is LIWC?")]

# In-memory construction
collection = Collection.cast(["First passage text.", "Second passage text."])
queries    = Queries.cast({0: "example query one", 1: "example query two"})

# Save to disk
collection.save("my_collection.tsv")
queries.save("my_queries.tsv")
```

--------------------------------

### ColBERTConfig for Search Settings

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Configure search parameters to tune the speed/quality trade-off, including the number of IVF cells to probe, centroid pre-filter threshold, and the number of candidate passages per query. Specify the root directory for experiments.

```python
# Search config — tune speed/quality trade-off
search_config = ColBERTConfig(
    ncells=2,                       # IVF cells to probe
    centroid_score_threshold=0.45,  # centroid pre-filter threshold
    ndocs=1024,                     # candidate passages per query
    root="/path/to/experiments",
)
```

--------------------------------

### Searcher.configure

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/searcher.html

Configures the Searcher with keyword arguments.

```APIDOC
## Searcher.configure

### Description
Configures the Searcher with keyword arguments.

### Parameters
- **\*\*kw_args**: Arbitrary keyword arguments for configuration.
```

--------------------------------

### LoTTE Dataset Structure

Source: https://github.com/stanford-futuredata/colbert/blob/main/LoTTE.md

Illustrates the directory and file organization of the LoTTE dataset.

```text
|-- lotte
  |-- writing
     |-- dev
	     |-- collection.tsv
	     |-- metadata.jsonl
	     |-- questions.search.tsv
	     |-- qas.search.jsonl
	     |-- questions.forum.tsv
	     |-- qas.forum.jsonl
	  |-- test
	     |-- collection.tsv
	     |-- ...
  |-- recreation
     |-- ...
  |-- ...

```

--------------------------------

### Searcher Class Initialization

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/_sources/searcher.rst.txt

Initializes the Searcher object. This is the entry point for using the searcher functionality.

```APIDOC
## Searcher.__init__

### Description
Initializes the Searcher object.

### Method
__init__

### Parameters
(No parameters explicitly documented in the source)
```

--------------------------------

### Import ColBERT Library

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2new.ipynb

Imports the main ColBERT library for use in the notebook.

```python
import colbert
```

--------------------------------

### ColBERTConfig for Indexing Settings

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Configure indexing parameters such as residual compression bits, document length, embedding dimension, and k-means iterations. Specify the root directory for experiments.

```python
from colbert.infra import ColBERTConfig

# Indexing config — 2-bit residual compression, custom doc length
index_config = ColBERTConfig(
    nbits=2,           # residual compression bits (1 or 2)
    doc_maxlen=180,    # max tokens per passage
    dim=128,           # embedding dimension
    kmeans_niters=4,   # k-means iterations for centroid training
    root="/path/to/experiments",
)
```

--------------------------------

### Import ColBERTv2 Classes

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro.ipynb

Imports the essential classes for ColBERTv2 indexing and search, including configuration and data handling utilities. Ensure the project path is correctly set in `sys.path`.

```python
import os
import sys
sys.path.insert(0, '../')

from colbert.infra import Run, RunConfig, ColBERTConfig
from colbert.data import Queries, Collection
from colbert import Indexer, Searcher
```

--------------------------------

### Build a ColBERT Index with Indexer

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Use the Indexer to encode a passage collection into a compressed vector index. Configure compression bits, document maximum length, and the root directory for experiments. Ensure the collection.tsv file is correctly formatted.

```python
from colbert.infra import Run, RunConfig, ColBERTConfig
from colbert import Indexer

if __name__ == '__main__':
    with Run().context(RunConfig(nranks=1, experiment="msmarco")):

        config = ColBERTConfig(
            nbits=2,                    # 2-bit residual compression
            doc_maxlen=180,
            root="/path/to/experiments",
        )

        indexer = Indexer(
            checkpoint="colbert-ir/colbertv2.0",  # HuggingFace Hub or local path
            config=config,
        )

        # collection.tsv format: each line is  pid<TAB>passage_text
        index_path = indexer.index(
            name="msmarco.nbits=2",
            collection="/path/to/MSMARCO/collection.tsv",
            overwrite=False,   # True | 'reuse' | 'resume' | 'force_silent_overwrite'
        )

        print(f"Index saved to: {index_path}")
        # Expected output:
        # Index saved to: /path/to/experiments/msmarco/indexes/msmarco.nbits=2
```

--------------------------------

### Import ColBERT Components

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2new.ipynb

Imports necessary classes and functions from the ColBERT library for indexing and searching, as well as configuration utilities.

```python
from colbert import Indexer, Searcher
from colbert.infra import Run, RunConfig, ColBERTConfig
from colbert.data import Queries, Collection
```

--------------------------------

### Configure Indexer

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/source/indexer.rst

Configures the Indexer with specified parameters.

```APIDOC
## indexer.Indexer.configure(**kwargs)

Configures the Indexer with specified parameters.
```

--------------------------------

### Load Queries and Collection

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro.ipynb

Loads queries and collection data from specified TSV files using the `Queries` and `Collection` classes. This prepares the data for indexing and search.

```python
dataroot = 'downloads/lotte'
dataset = 'lifestyle'
datasplit = 'dev'

queries = os.path.join(dataroot, dataset, datasplit, 'questions.search.tsv')
collection = os.path.join(dataroot, dataset, datasplit, 'collection.tsv')

queries = Queries(path=queries)
collection = Collection(path=collection)

f'Loaded {len(queries)} queries and {len(collection):,} passages'
```

--------------------------------

### Configure Indexing Parameters

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro.ipynb

Sets parameters for indexing, including the number of bits for encoding dimensions (`nbits`) and the maximum passage length in tokens (`doc_maxlen`).

```python
nbits = 2   # encode each dimension with 2 bits
doc_maxlen = 300   # truncate passages at 300 tokens

checkpoint = 'downloads/colbertv2.0'
index_name = f'{dataset}.{datasplit}.{nbits}bits'
```

--------------------------------

### Train ColBERTv1 Style Model

Source: https://github.com/stanford-futuredata/colbert/blob/main/README.md

Use this snippet to train a ColBERT model following the ColBERTv1 training style. Requires a JSONL triples file and specific paths for queries and collection. Ensure RunConfig is set for the number of GPUs.

```python
from colbert.infra import Run, RunConfig, ColBERTConfig
from colbert import Trainer

if __name__=='__main__':
    with Run().context(RunConfig(nranks=4, experiment="msmarco")):

        config = ColBERTConfig(
            bsize=32,
            root="/path/to/experiments",
        )
        trainer = Trainer(
            triples="/path/to/MSMARCO/triples.train.small.tsv",
            queries="/path/to/MSMARCO/queries.train.small.tsv",
            collection="/path/to/MSMARCO/collection.tsv",
            config=config,
        )

        checkpoint_path = trainer.train()

        print(f"Saved checkpoint to {checkpoint_path}...")
```

--------------------------------

### Manually Run ColBERT Indexer

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/intro2updated.ipynb

Manually runs the ColBERT Indexer to create a compressed index on disk. This requires specifying the checkpoint, configuration, and collection data. It's recommended to set APPLY_INDEXING to False to use this block.

```python
else:
    checkpoint = 'colbert-ir/colbertv2.0'

    with Run().context(RunConfig(nranks=1, experiment='notebook')):  # nranks specifies the number of GPUs to use
        config = ColBERTConfig(doc_maxlen=doc_maxlen, nbits=nbits, kmeans_niters=4) # kmeans_niters specifies the number of iterations of k-means clustering; 4 is a good and fast default.                                                                           # Consider larger numbers for small datasets.

        indexer = Indexer(checkpoint=checkpoint, config=config)
        indexer.index(name=index_name, collection=collection[:max_id], overwrite=True)
```

--------------------------------

### Trainer.best_checkpoint_path

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/trainer.html

Retrieves the path to the best performing checkpoint.

```APIDOC
## Trainer.best_checkpoint_path

### Description
Returns the file path to the best checkpoint found during training.

### Signature
`trainer.Trainer.best_checkpoint_path(self)`
```

--------------------------------

### Index Collection with ColBERT

Source: https://github.com/stanford-futuredata/colbert/blob/main/README.md

Use the Indexer class to precompute ColBERT representations of passages for fast retrieval. Ensure the checkpoint and collection paths are correctly specified.

```python
from colbert.infra import Run, RunConfig, ColBERTConfig
from colbert import Indexer

if __name__=='__main__':
    with Run().context(RunConfig(nranks=1, experiment="msmarco")):

        config = ColBERTConfig(
            nbits=2,
            root="/path/to/experiments",
        )
        indexer = Indexer(checkpoint="/path/to/checkpoint", config=config)
        indexer.index(name="msmarco.nbits=2", collection="/path/to/MSMARCO/collection.tsv")
```

--------------------------------

### Searcher.search_all — Batch Retrieval Over a Query File

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Runs retrieval for all queries in a TSV file and returns a `Ranking` object that can be saved to disk.

```APIDOC
## Searcher.search_all

### Description
Performs batch retrieval for multiple queries from a file and generates a ranking.

### Method
`searcher.search_all(queries: Queries, k: int)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters for Searcher initialization
- `index` (str): The name or path of the ColBERT index to load.
- `config` (ColBERTConfig):
    - `root` (str): Root directory where indexes are stored.

### Parameters for `searcher.search_all()` method
- `queries` (Queries): A `Queries` object loaded from a TSV file (format: `qid<TAB>query_text`).
- `k` (int): The number of top results to retrieve for each query.

### Request Example
```python
from colbert.data import Queries
from colbert.infra import Run, RunConfig, ColBERTConfig
from colbert import Searcher

with Run().context(RunConfig(nranks=1, experiment="msmarco")):
    config = ColBERTConfig(root="/path/to/experiments")
    searcher = Searcher(index="msmarco.nbits=2", config=config)
    queries = Queries("/path/to/MSMARCO/queries.dev.small.tsv")
    ranking = searcher.search_all(queries, k=100)
    ranking.save("msmarco.nbits=2.ranking.tsv")
```

### Response
#### Success Response (200)
Returns a `Ranking` object containing the retrieval results, which can be saved to a file.

#### Response Example
```
# Ranking object saved to msmarco.nbits=2.ranking.tsv
# Example content of the saved file (TSV format: qid<TAB>pid<TAB>rank<TAB>score):
# 1	4823	1	28.4
# 1	12034	2	27.1
# ...
```
```

--------------------------------

### LoTTE Metadata JSONL Format

Source: https://github.com/stanford-futuredata/colbert/blob/main/LoTTE.md

Describes the structure of the metadata.jsonl file, containing information for each question.

```json
{
    	"dataset": dataset,
    	"question_id": question_id,
    	"post_ids": [post_id_1, post_id_2, ..., post_id_n],
    	"scores": [score_1, score_2, ..., score_n],
    	"post_urls": [url_1, url_2, ..., url_n],
    	"post_authors": [author_1, author_2, ..., author_n],
    	"post_author_urls": [url_1, url_2, ..., url_n],
    	"question_author": question_author,
    	"question_author_url", question_author_url
    }

```

--------------------------------

### Train a ColBERT Model (v1-style)

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Fine-tune a BERT checkpoint on triplet data using the ColBERT pairwise margin loss. Requires specifying paths to triples, queries, and collection data.

```python
from colbert.infra import Run, RunConfig, ColBERTConfig
from colbert import Trainer

if __name__ == '__main__':
    with Run().context(RunConfig(nranks=1, experiment="msmarco")):

        config = ColBERTConfig(
            bsize=32,
            root="/path/to/experiments",
        )

        trainer = Trainer(
            # triples.tsv: each line is  qid<TAB>pos_pid<TAB>neg_pid
            triples="/path/to/MSMARCO/triples.train.small.tsv",
            queries="/path/to/MSMARCO/queries.train.small.tsv",
            collection="/path/to/MSMARCO/collection.tsv",
            config=config,
        )

        trainer.train(checkpoint="bert-base-uncased")  # or a local checkpoint

        best_ckpt = trainer.best_checkpoint_path()
        print(f"Best checkpoint: {best_ckpt}")
        # Expected output:
        # Best checkpoint: /path/to/experiments/msmarco/.../checkpoints/colbert-XXXXX

```

--------------------------------

### Perform Single-Query Search with Searcher

Source: https://context7.com/stanford-futuredata/colbert/llms.txt

Load a ColBERT index and checkpoint into memory to perform dense retrieval. The searcher uses PLAID's candidate generation and MaxSim scoring pipeline. Results include passage IDs, ranks, and scores.

```python
from colbert.infra import Run, RunConfig, ColBERTConfig
from colbert import Searcher

if __name__ == '__main__':
    with Run().context(RunConfig(nranks=1, experiment="msmarco")):

        config = ColBERTConfig(root="/path/to/experiments")
        searcher = Searcher(index="msmarco.nbits=2", config=config)

        # --- Single query search ---
        results = searcher.search("Who won the 2022 FIFA World Cup?", k=10)
        pids, ranks, scores = results
        # pids   = [4823, 12034, 99213, ...]   (passage IDs, best first)
        # ranks  = [1, 2, 3, ...]
        # scores = [28.4, 27.1, 25.8, ...]

        for pid, rank, score in zip(pids, ranks, scores):
            print(f"Rank {rank} | PID {pid} | Score {score:.2f}")
            print(searcher.collection[pid])
            print()
```

--------------------------------

### Searcher.configure

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/source/searcher.rst

Configures the Searcher instance with specific settings. This method is used to customize the behavior of the searcher.

```APIDOC
## Searcher.configure

### Description
Configures the Searcher instance.

### Method
`configure`

### Parameters
None explicitly documented for direct user invocation.
```

--------------------------------

### Searcher Configuration

Source: https://github.com/stanford-futuredata/colbert/blob/main/docs/html/_sources/searcher.rst.txt

Configures the Searcher object with necessary parameters for its operation.

```APIDOC
## Searcher.configure

### Description
Configures the Searcher object.

### Method
configure

### Parameters
(No parameters explicitly documented in the source)
```