ColBERT (v2)

ColBERT 是一种_快速_且_精确_的检索模型，能够在数十毫秒内对大规模文本集合实现基于 BERT 的可扩展搜索。

图 1： ColBERT 的晚期交互机制，高效地计算查询与段落之间的细粒度相似度。

如图 1 所示，ColBERT 依赖于细粒度的上下文式晚期交互：它将每个段落编码为一个由标记级嵌入组成的矩阵（上图蓝色部分）。在检索时，它会将每个查询也编码为另一个矩阵（上图绿色部分），并利用可扩展的向量相似度运算符（MaxSim）高效地找到与查询上下文匹配的段落。

这种丰富的交互使得 ColBERT 在质量上超越了_单向量_表示模型，同时能够高效地扩展到大规模语料库。

您可以在我们的论文中了解更多：

• ColBERT：通过 BERT 上下文式晚期交互实现高效且有效的段落搜索（SIGIR'20）。
• 基于 ColBERT 的开放问答任务中的相关性引导监督（TACL'21）。
• Baleen：通过精简检索实现鲁棒的大规模多跳推理（NeurIPS'21）。
• ColBERTv2：通过轻量级晚期交互实现高效且有效的检索（NAACL'22）。
• PLAID：用于晚期交互检索的高效引擎（CIKM'22）。
• 超越下游任务准确率的信息检索基准测试（ACL'23 Findings）。
• UDAPDR：通过 LLM 提示和重排序器蒸馏实现无监督领域适应（EMNLP'23）。

---

🚨 公告

• （2024年1月28日）如今在应用中使用 ColBERT 最简单的方法之一是半官方、快速发展的 RAGatouille 库。
• （2023年1月29日）我们合并了一个新的索引更新功能，并增加了对更多 Hugging Face 模型的支持！这些功能目前处于测试阶段，请在试用时向我们提供反馈。
• （2023年1月24日）如果您正在寻找用于组合 ColBERTv2 等检索器和 LLM 的 DSPy 框架，可以访问：https://github.com/stanfordnlp/dspy

---

ColBERTv1

来自 SIGIR'20 论文的 ColBERTv1 代码位于 colbertv1 分支。有关其他分支的更多信息，请参阅 此处。

安装

（更新：如今通常可以直接运行 pip install colbert-ai[torch,faiss-gpu] 来快速启动，但如果遇到问题，使用 conda 安装 faiss 和 torch 会更加可靠。）

ColBERT 需要 Python 3.7 及以上版本和 PyTorch 1.9 及以上版本，并使用 Hugging Face Transformers 库。

我们强烈建议使用以下命令创建一个 conda 环境。（如果您没有 conda，请按照官方 conda 安装指南 进行安装。）

我们还专门提供了一个仅适用于 CPU 环境的环境文件（conda_env_cpu.yml），但请注意，如果在包含 GPU 的机器上测试 CPU 执行，您可能需要在命令中指定 CUDA_VISIBLE_DEVICES=""。需要注意的是，训练和索引构建需要 GPU。

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

如果您遇到任何问题，请提交新 issue，我们将尽快为您提供帮助！

概述

在数据集上使用 ColBERT 通常包括以下步骤。

步骤 0：预处理您的语料库。 最简单的情况下，ColBERT 可以处理制表符分隔（TSV）文件：一个文件（例如 collection.tsv）包含所有段落，另一个文件（例如 queries.tsv）则包含用于搜索该语料库的一组查询。

步骤 1：下载【预训练的 ColBERTv2 检查点】(https://downloads.cs.stanford.edu/nlp/data/colbert/colbertv2/colbertv2.0.tar.gz)。 该检查点已在 MS MARCO 段落排序任务上进行过训练。您也可以_可选_地训练您自己的 ColBERT 模型。

步骤 2：索引您的语料库。 一旦您拥有了经过训练的 ColBERT 模型，就需要对您的语料库进行索引构建，以便实现快速检索。此步骤会将所有段落编码为矩阵，存储在磁盘上，并构建用于高效搜索的数据结构。

步骤 3：使用您的查询搜索语料库。 在拥有模型和索引之后，您可以对语料库发出查询，以检索每个查询的前 k 个最相关的段落。

下面，我们通过一个在 MS MARCO 段落排序任务上的示例运行来说明这些步骤。

API 使用笔记本

新增：我们在 Google Colab 上提供了一个实验性笔记本，您可以使用免费的 GPU 运行。在免费的 Colab T4 GPU 上对 10,000 条记录进行索引构建只需六分钟。

这个 Jupyter 笔记本【docs/intro.ipynb 笔记本】(docs/intro.ipynb) 展示了如何使用新的 Python API 来操作 ColBERT 的关键功能。

其中包含了如何下载在 MS MARCO 段落排序任务上训练的 ColBERTv2 模型检查点，以及如何下载我们的全新 LoTTE 基准测试数据集。

数据

此仓库直接使用简单的制表符分隔文件格式来存储查询、段落和 top-k 排名列表。

• 查询：每行格式为 qid \t query text。
• 语料库：每行格式为 pid \t passage text。
• Top-k 排名：每行格式为 qid \t pid \t rank。

这与 MS MARCO 段落排序 数据集的数据格式直接兼容。您需要训练三元组（triples.train.small.tar.gz）、官方开发集查询的前 1000 名排名列表（top1000.dev）以及开发集的相关段落（qrels.dev.small.tsv）。若要索引整个语料库，还需要段落列表（collection.tar.gz）。

索引

为了实现快速检索，索引会预先计算段落的 ColBERT 表示。

示例用法：

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")

检索

我们通常建议您使用 ColBERT 进行端到端检索，它可以直接从整个语料库中找到前 k 个最相关的段落：

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 = Queries("/path/to/MSMARCO/queries.dev.small.tsv")
        ranking = searcher.search_all(queries, k=100)
        ranking.save("msmarco.nbits=2.ranking.tsv")

您可以选择指定 ncells、centroid_score_threshold 和 ndocs 等搜索超参数，以在速度和结果质量之间进行权衡。不同 k 值的默认设置列于 colbert/searcher.py 中。

我们可以使用以下命令评估 MSMARCO 排序结果：

python -m utility.evaluate.msmarco_passages --ranking "/path/to/msmarco.nbits=2.ranking.tsv" --qrels "/path/to/MSMARCO/qrels.dev.small.tsv"

基本训练（ColBERTv1 风格）

我们提供了一个预训练模型检查点，但我们也在此详细说明如何从头开始训练。请注意，此示例演示的是 ColBERTv1 的训练方式，而提供的检查点是使用 ColBERTv2 训练的。

训练需要一个 JSONL 三元组文件，每行包含 [qid, pid+, pid-] 列表。查询 ID 和段落 ID 分别对应指定的 queries.tsv 和 collection.tsv 文件。

示例用法（在 4 个 GPU 上训练）：

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"已保存检查点至 {checkpoint_path}...")

高级训练（ColBERTv2 风格）

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


def train():
    # 使用 4 个 GPU（例如四张 A100 显卡，但您可以通过调整 nway、accumsteps 和 bsize 来使用更少的 GPU）。
    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')  # 或者从头开始，比如使用 `bert-base-uncased`


if __name__ == '__main__':
    train()

运行轻量级 ColBERTv2 服务器

我们提供了一个脚本，用于运行一个轻量级服务器，该服务器可以为给定的搜索查询以 JSON 格式提供按排名顺序排列的最多 100 个结果。此脚本可用于支持 DSP 程序。

要运行服务器，请在 .env 文件中更新环境变量 INDEX_ROOT 和 INDEX_NAME，使其指向相应的 ColBERT 索引。然后运行以下命令：

python server.py

示例查询：

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

分支

支持的分支

• main：稳定分支，包含 ColBERTv2 + PLAID。
• colbertv1：ColBERTv1 的遗留分支。

已弃用的分支

• new_api：基础 ColBERTv2 实现。
• cpu_inference：支持 CPU 搜索的 ColBERTv2 实现。
• fast_search：带有 PLAID 的 ColBERTv2 实现。
• binarization：采用基于二值化的压缩策略的 ColBERT（与 ColBERTv2 的残差压缩相比，后者被证明更为稳健）。

致谢

ColBERT 徽标由 Chuyi Zhang 设计。

ColBERT 快速上手指南

ColBERT 是一款基于 BERT 的快速、高精度检索模型，通过细粒度的“上下文晚期交互”（Contextualized Late Interaction）机制，能够在数十毫秒内完成大规模文本集合的搜索。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: Linux (推荐) 或 macOS
• Python: 3.7 或更高版本
• PyTorch: 1.9 或更高版本
• 硬件:
  • 训练与索引: 必须使用 GPU。
  • 搜索: 支持 GPU 和 CPU（若在含 GPU 的机器上强制使用 CPU，需设置 CUDA_VISIBLE_DEVICES=""）。
• 依赖库: Hugging Face Transformers, FAISS

建议: 推荐使用 conda 管理环境以确保 faiss 和 torch 依赖的正确安装。

安装步骤

1. 创建 Conda 环境

克隆仓库后，使用项目提供的配置文件创建环境。

# 对于 GPU 环境
conda env create -f conda_env.yml
# 对于纯 CPU 环境（仅用于测试搜索）
# conda env create -f conda_env_cpu.yml

conda activate colbert

2. 安装 ColBERT 包

激活环境后，通过 pip 安装核心包。国内用户若遇网络问题，可尝试指定清华源或阿里源。

# 标准安装
pip install colbert-ai[torch,faiss-gpu]

# 国内加速示例 (使用清华源)
# pip install colbert-ai[torch,faiss-gpu] -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

以下是使用预训练模型进行索引构建和检索的最小化工作流。

第一步：数据准备

ColBERT 直接使用制表符分隔（TSV）文件。

• 文档集合 (collection.tsv): 格式为 pid \t passage text
• 查询文件 (queries.tsv): 格式为 qid \t query text

第二步：下载预训练模型

下载在 MS MARCO 数据集上训练的 ColBERTv2 检查点：

wget https://downloads.cs.stanford.edu/nlp/data/colbert/colbertv2/colbertv2.0.tar.gz
tar -xzf colbertv2.0.tar.gz
# 假设解压后的路径为 /path/to/checkpoint

第三步：构建索引 (Indexing)

将文档集合编码为矩阵并建立索引结构。

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

if __name__=='__main__':
    # nranks 表示使用的 GPU 数量
    with Run().context(RunConfig(nranks=1, experiment="my_experiment")):

        config = ColBERTConfig(
            nbits=2,  # 压缩位数
            root="/path/to/experiments", # 实验根目录
        )
        
        indexer = Indexer(checkpoint="/path/to/checkpoint", config=config)
        indexer.index(
            name="my_collection.nbits=2", 
            collection="/path/to/collection.tsv"
        )

第四步：执行检索 (Retrieval)

加载索引并对查询进行搜索。

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="my_experiment")):

        config = ColBERTConfig(
            root="/path/to/experiments",
        )
        
        # 加载刚才创建的索引
        searcher = Searcher(index="my_collection.nbits=2", config=config)
        
        # 加载查询文件
        queries = Queries("/path/to/queries.tsv")
        
        # 执行搜索，k 为返回结果数量
        ranking = searcher.search_all(queries, k=100)
        
        # 保存结果
        ranking.save("my_collection.ranking.tsv")

进阶提示

• Google Colab 体验: 官方提供了 Intro Notebook，可在免费 T4 GPU 上快速试运行（索引 1 万条数据约需 6 分钟）。
• 应用集成: 若需在 RAG 应用中快速集成，推荐使用社区维护的 RAGatouille 库。