[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-stanford-futuredata--ColBERT":3,"tool-stanford-futuredata--ColBERT":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",143909,2,"2026-04-07T11:33:18",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107888,"2026-04-06T11:32:50",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":75,"owner_company":76,"owner_location":76,"owner_email":76,"owner_twitter":76,"owner_website":76,"owner_url":77,"languages":78,"stars":91,"forks":92,"last_commit_at":93,"license":94,"difficulty_score":10,"env_os":95,"env_gpu":96,"env_ram":97,"env_deps":98,"category_tags":105,"github_topics":76,"view_count":32,"oss_zip_url":76,"oss_zip_packed_at":76,"status":17,"created_at":106,"updated_at":107,"faqs":108,"releases":134},5033,"stanford-futuredata\u002FColBERT","ColBERT","ColBERT: state-of-the-art neural search (SIGIR'20, TACL'21, NeurIPS'21, NAACL'22, CIKM'22, ACL'23, EMNLP'23)","ColBERT 是一款高效且精准的神经搜索模型，专为在大规模文本集合中实现毫秒级检索而设计。它解决了传统搜索方法在速度与精度之间难以兼顾的痛点：既克服了单向量表示模型丢失细节信息的局限，又避免了早期交互模型计算成本过高的问题，让基于 BERT 的高质量搜索能够真正落地应用。\n\n这款工具特别适合开发者、研究人员以及需要构建高性能检索增强生成（RAG）系统的工程师使用。无论是处理海量文档库的企业级搜索，还是学术领域的开放域问答研究，ColBERT 都能提供强有力的支持。\n\n其核心技术创新在于独特的“细粒度上下文延迟交互”机制。与传统方法不同，ColBERT 会将文档和查询分别编码为词元级别的嵌入矩阵，在检索阶段通过高效的 MaxSim 算子进行深度匹配。这种设计不仅保留了丰富的语义细节，显著提升了搜索结果的相关性，还通过可扩展的向量相似度计算确保了极快的响应速度。此外，项目持续迭代，已推出 ColBERTv2 及配套的 PLAID 引擎，进一步降低了资源消耗并提升了易用性，是目前学术界和工业界公认的前沿检索方案。","\u003Cp align=\"center\">\n  \u003Cimg align=\"center\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fstanford-futuredata_ColBERT_readme_26fadd199f9c.png\" width=\"430px\" \u002F>\n\u003C\u002Fp>\n\u003Cp align=\"left\">\n\n# ColBERT (v2)\n\n### ColBERT is a _fast_ and _accurate_ retrieval model, enabling scalable BERT-based search over large text collections in tens of milliseconds.\n\n[\u003Cimg align=\"center\" src=\"https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg\" \u002F>](https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Fstanford-futuredata\u002FColBERT\u002Fblob\u002Fmain\u002Fdocs\u002Fintro2new.ipynb)\n\n\n\u003Cp align=\"center\">\n  \u003Cimg align=\"center\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fstanford-futuredata_ColBERT_readme_ea2cf78e8482.png\" \u002F>\n\u003C\u002Fp>\n\u003Cp align=\"center\">\n  \u003Cb>Figure 1:\u003C\u002Fb> ColBERT's late interaction, efficiently scoring the fine-grained similarity between a queries and a passage.\n\u003C\u002Fp>\n\nAs Figure 1 illustrates, ColBERT relies on fine-grained **contextual late interaction**: it encodes each passage into a **matrix** of token-level embeddings (shown above in blue). Then at search time, it embeds every query into another matrix (shown in green) and efficiently finds passages that contextually match the query using scalable vector-similarity (`MaxSim`) operators.\n\nThese rich interactions allow ColBERT to surpass the quality of _single-vector_ representation models, while scaling efficiently to large corpora.\n\n\n#### You can read more in our papers:\n\n* [**ColBERT: Efficient and Effective Passage Search via Contextualized Late Interaction over BERT**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2004.12832) (SIGIR'20).\n* [**Relevance-guided Supervision for OpenQA with ColBERT**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2007.00814) (TACL'21).\n* [**Baleen: Robust Multi-Hop Reasoning at Scale via Condensed Retrieval**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2101.00436) (NeurIPS'21).\n* [**ColBERTv2: Effective and Efficient Retrieval via Lightweight Late Interaction**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2112.01488) (NAACL'22).\n* [**PLAID: An Efficient Engine for Late Interaction Retrieval**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2205.09707) (CIKM'22).\n* [**Moving Beyond Downstream Task Accuracy for Information Retrieval Benchmarking**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2212.01340) (ACL'23 Findings).\n* [**UDAPDR: Unsupervised Domain Adaptation via LLM Prompting and Distillation of Rerankers**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2303.00807) (EMNLP'23).\n\n----\n\n## 🚨 **Announcements** \n\n* (1\u002F28\u002F24) One of the easiest ways to use ColBERT in applications nowadays is the semi-official, fast-growing [RAGatouille](https:\u002F\u002Fgithub.com\u002Fbclavie\u002Fragatouille) library.\n* (1\u002F29\u002F23) We have merged a new index updater feature and support for additional Hugging Face models! These are in beta so please give us feedback as you try them out.\n* (1\u002F24\u002F23) If you're looking for the **DSPy** framework for composing retrievers like ColBERTv2 and LLMs, it's at: https:\u002F\u002Fgithub.com\u002Fstanfordnlp\u002Fdspy\n\n----\n\n## ColBERTv1\n\nThe ColBERTv1 code from the SIGIR'20 paper is in the [`colbertv1` branch](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Fcolbertv1). See [here](#branches) for more information on other branches.\n\n\n## Installation\n\n(Update: nowadays you can typically do `pip install colbert-ai[torch,faiss-gpu]` to get things up and running, but if you face issues conda is always more reliable for `faiss` and `torch`.)\n\nColBERT requires Python 3.7+ and Pytorch 1.9+ and uses the [Hugging Face Transformers](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Ftransformers) library.\n\nWe strongly recommend creating a conda environment using the commands below. (If you don't have conda, follow the official [conda installation guide](https:\u002F\u002Fdocs.anaconda.com\u002Fanaconda\u002Finstall\u002Flinux\u002F#installation).)\n\nWe have also included a new environment file specifically for CPU-only environments (`conda_env_cpu.yml`), but note that if you are testing CPU execution on a machine that includes GPUs you might need to specify `CUDA_VISIBLE_DEVICES=\"\"` as part of your command. Note that a GPU is required for training and indexing.\n\n```\nconda env create -f conda_env[_cpu].yml\nconda activate colbert\n```\n\nIf you face any problems, please [open a new issue](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fissues) and we'll help you promptly!\n\n\n\n## Overview\n\nUsing ColBERT on a dataset typically involves the following steps.\n\n**Step 0: Preprocess your collection.** At its simplest, ColBERT works with tab-separated (TSV) files: a file (e.g., `collection.tsv`) will contain all passages and another (e.g., `queries.tsv`) will contain a set of queries for searching the collection.\n\n**Step 1: Download the [pre-trained ColBERTv2 checkpoint](https:\u002F\u002Fdownloads.cs.stanford.edu\u002Fnlp\u002Fdata\u002Fcolbert\u002Fcolbertv2\u002Fcolbertv2.0.tar.gz).** This checkpoint has been trained on the MS MARCO Passage Ranking task. You can also _optionally_ [train your own ColBERT model](#training).\n\n**Step 2: Index your collection.** Once you have a trained ColBERT model, you need to [index your collection](#indexing) to permit fast retrieval. This step encodes all passages into matrices, stores them on disk, and builds data structures for efficient search.\n\n**Step 3: Search the collection with your queries.** Given the model and index, you can [issue queries over the collection](#retrieval) to retrieve the top-k passages for each query.\n\nBelow, we illustrate these steps via an example run on the MS MARCO Passage Ranking task.\n\n\n## API Usage Notebook\n\n**NEW**: We have an experimental notebook on [Google Colab](https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Fstanford-futuredata\u002FColBERT\u002Fblob\u002Fmain\u002Fdocs\u002Fintro2new.ipynb) that you can use with free GPUs. Indexing 10,000 on the free Colab T4 GPU takes six minutes.\n\nThis Jupyter notebook **[docs\u002Fintro.ipynb notebook](docs\u002Fintro.ipynb)** illustrates using the key features of ColBERT with the new Python API.\n\nIt includes how to download the ColBERTv2 model checkpoint trained on MS MARCO Passage Ranking and how to download our new LoTTE benchmark.\n\n\n## Data\n\nThis repository works directly with a simple **tab-separated file** format to store queries, passages, and top-k ranked lists.\n\n\n* Queries: each line is `qid \\t query text`.\n* Collection: each line is `pid \\t passage text`.\n* Top-k Ranking: each line is `qid \\t pid \\t rank`.\n\nThis works directly with the data format of the [MS MARCO Passage Ranking](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FMSMARCO-Passage-Ranking) dataset. You will need the training triples (`triples.train.small.tar.gz`), the official top-1000 ranked lists for the dev set queries (`top1000.dev`), and the dev set relevant passages (`qrels.dev.small.tsv`). For indexing the full collection, you will also need the list of passages (`collection.tar.gz`).\n\n\n## Indexing\n\nFor fast retrieval, indexing precomputes the ColBERT representations of passages.\n\nExample usage:\n\n```python\nfrom colbert.infra import Run, RunConfig, ColBERTConfig\nfrom colbert import Indexer\n\nif __name__=='__main__':\n    with Run().context(RunConfig(nranks=1, experiment=\"msmarco\")):\n\n        config = ColBERTConfig(\n            nbits=2,\n            root=\"\u002Fpath\u002Fto\u002Fexperiments\",\n        )\n        indexer = Indexer(checkpoint=\"\u002Fpath\u002Fto\u002Fcheckpoint\", config=config)\n        indexer.index(name=\"msmarco.nbits=2\", collection=\"\u002Fpath\u002Fto\u002FMSMARCO\u002Fcollection.tsv\")\n```\n\n\n## Retrieval\n\nWe typically recommend that you use ColBERT for **end-to-end** retrieval, where it directly finds its top-k passages from the full collection:\n\n```python\nfrom colbert.data import Queries\nfrom colbert.infra import Run, RunConfig, ColBERTConfig\nfrom colbert import Searcher\n\nif __name__=='__main__':\n    with Run().context(RunConfig(nranks=1, experiment=\"msmarco\")):\n\n        config = ColBERTConfig(\n            root=\"\u002Fpath\u002Fto\u002Fexperiments\",\n        )\n        searcher = Searcher(index=\"msmarco.nbits=2\", config=config)\n        queries = Queries(\"\u002Fpath\u002Fto\u002FMSMARCO\u002Fqueries.dev.small.tsv\")\n        ranking = searcher.search_all(queries, k=100)\n        ranking.save(\"msmarco.nbits=2.ranking.tsv\")\n```\n\nYou can optionally specify the `ncells`, `centroid_score_threshold`, and `ndocs` search hyperparameters to trade off between speed and result quality. Defaults for different values of `k` are listed in colbert\u002Fsearcher.py.\n\nWe can evaluate the MSMARCO rankings using the following command:\n\n```\npython -m utility.evaluate.msmarco_passages --ranking \"\u002Fpath\u002Fto\u002Fmsmarco.nbits=2.ranking.tsv\" --qrels \"\u002Fpath\u002Fto\u002FMSMARCO\u002Fqrels.dev.small.tsv\"\n```\n\n## Basic Training (ColBERTv1-style)\n\nWe provide a [pre-trained model checkpoint](https:\u002F\u002Fdownloads.cs.stanford.edu\u002Fnlp\u002Fdata\u002Fcolbert\u002Fcolbertv2\u002Fcolbertv2.0.tar.gz), but we also detail how to train from scratch here.\nNote that this example demonstrates the ColBERTv1 style of training, but the provided checkpoint was trained with ColBERTv2.\n\nTraining requires a JSONL triples file with a `[qid, pid+, pid-]` list per line. The query IDs and passage IDs correspond to the specified `queries.tsv` and `collection.tsv` files respectively.\n\nExample usage (training on 4 GPUs):\n\n```python\nfrom colbert.infra import Run, RunConfig, ColBERTConfig\nfrom colbert import Trainer\n\nif __name__=='__main__':\n    with Run().context(RunConfig(nranks=4, experiment=\"msmarco\")):\n\n        config = ColBERTConfig(\n            bsize=32,\n            root=\"\u002Fpath\u002Fto\u002Fexperiments\",\n        )\n        trainer = Trainer(\n            triples=\"\u002Fpath\u002Fto\u002FMSMARCO\u002Ftriples.train.small.tsv\",\n            queries=\"\u002Fpath\u002Fto\u002FMSMARCO\u002Fqueries.train.small.tsv\",\n            collection=\"\u002Fpath\u002Fto\u002FMSMARCO\u002Fcollection.tsv\",\n            config=config,\n        )\n\n        checkpoint_path = trainer.train()\n\n        print(f\"Saved checkpoint to {checkpoint_path}...\")\n```\n\n## Advanced Training (ColBERTv2-style)\n\n```python\nfrom colbert.infra.run import Run\nfrom colbert.infra.config import ColBERTConfig, RunConfig\nfrom colbert import Trainer\n\n\ndef train():\n    # use 4 gpus (e.g. four A100s, but you can use fewer by changing nway,accumsteps,bsize).\n    with Run().context(RunConfig(nranks=4)):\n        triples = '\u002Fpath\u002Fto\u002Fexamples.64.json'  # `wget https:\u002F\u002Fhuggingface.co\u002Fcolbert-ir\u002Fcolbertv2.0_msmarco_64way\u002Fresolve\u002Fmain\u002Fexamples.json?download=true` (26GB)\n        queries = '\u002Fpath\u002Fto\u002FMSMARCO\u002Fqueries.train.tsv'\n        collection = '\u002Fpath\u002Fto\u002FMSMARCO\u002Fcollection.tsv'\n\n        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)\n        trainer = Trainer(triples=triples, queries=queries, collection=collection, config=config)\n\n        trainer.train(checkpoint='colbert-ir\u002Fcolbertv1.9')  # or start from scratch, like `bert-base-uncased`\n\n\nif __name__ == '__main__':\n    train()\n```\n\n\n## Running a lightweight ColBERTv2 server\nWe provide a script to run a lightweight server which serves k (upto 100) results in ranked order for a given search query, in JSON format. This script can be used to power DSP programs. \n\nTo run the server, update the environment variables `INDEX_ROOT` and `INDEX_NAME` in the `.env` file to point to the appropriate ColBERT index. The run the following command:\n```\npython server.py\n```\n\nA sample query:\n```\nhttp:\u002F\u002Flocalhost:8893\u002Fapi\u002Fsearch?query=Who won the 2022 FIFA world cup&k=25\n```\n\n## Branches\n\n### Supported branches\n\n* [`main`](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Fmain): Stable branch with ColBERTv2 + PLAID.\n* [`colbertv1`](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Fcolbertv1): Legacy branch for ColBERTv1.\n\n### Deprecated branches\n* [`new_api`](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Fnew_api): Base ColBERTv2 implementation.\n* [`cpu_inference`](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Fcpu_inference): ColBERTv2 implementation with CPU search support.\n* [`fast_search`](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Ffast_search): ColBERTv2 implementation with PLAID.\n* [`binarization`](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Fbinarization): ColBERT with a baseline binarization-based compression strategy (as opposed to ColBERTv2's residual compression, which we found to be more robust).\n\n## Acknowledgments\n\nColBERT logo designed by Chuyi Zhang.\n","\u003Cp align=\"center\">\n  \u003Cimg align=\"center\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fstanford-futuredata_ColBERT_readme_26fadd199f9c.png\" width=\"430px\" \u002F>\n\u003C\u002Fp>\n\u003Cp align=\"left\">\n\n# ColBERT (v2)\n\n### ColBERT 是一种_快速_且_精确_的检索模型，能够在数十毫秒内对大规模文本集合实现基于 BERT 的可扩展搜索。\n\n[\u003Cimg align=\"center\" src=\"https:\u002F\u002Fcolab.research.google.com\u002Fassets\u002Fcolab-badge.svg\" \u002F>](https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Fstanford-futuredata\u002FColBERT\u002Fblob\u002Fmain\u002Fdocs\u002Fintro2new.ipynb)\n\n\n\u003Cp align=\"center\">\n  \u003Cimg align=\"center\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fstanford-futuredata_ColBERT_readme_ea2cf78e8482.png\" \u002F>\n\u003C\u002Fp>\n\u003Cp align=\"center\">\n  \u003Cb>图 1：\u003C\u002Fb> ColBERT 的晚期交互机制，高效地计算查询与段落之间的细粒度相似度。\n\u003C\u002Fp>\n\n如图 1 所示，ColBERT 依赖于细粒度的**上下文式晚期交互**：它将每个段落编码为一个由标记级嵌入组成的**矩阵**（上图蓝色部分）。在检索时，它会将每个查询也编码为另一个矩阵（上图绿色部分），并利用可扩展的向量相似度运算符（`MaxSim`）高效地找到与查询上下文匹配的段落。\n\n这种丰富的交互使得 ColBERT 在质量上超越了_单向量_表示模型，同时能够高效地扩展到大规模语料库。\n\n#### 您可以在我们的论文中了解更多：\n\n* [**ColBERT：通过 BERT 上下文式晚期交互实现高效且有效的段落搜索**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2004.12832)（SIGIR'20）。\n* [**基于 ColBERT 的开放问答任务中的相关性引导监督**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2007.00814)（TACL'21）。\n* [**Baleen：通过精简检索实现鲁棒的大规模多跳推理**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2101.00436)（NeurIPS'21）。\n* [**ColBERTv2：通过轻量级晚期交互实现高效且有效的检索**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2112.01488)（NAACL'22）。\n* [**PLAID：用于晚期交互检索的高效引擎**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2205.09707)（CIKM'22）。\n* [**超越下游任务准确率的信息检索基准测试**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2212.01340)（ACL'23 Findings）。\n* [**UDAPDR：通过 LLM 提示和重排序器蒸馏实现无监督领域适应**](https:\u002F\u002Farxiv.org\u002Fabs\u002F2303.00807)（EMNLP'23）。\n\n----\n\n## 🚨 **公告**\n\n* （2024年1月28日）如今在应用中使用 ColBERT 最简单的方法之一是半官方、快速发展的 [RAGatouille](https:\u002F\u002Fgithub.com\u002Fbclavie\u002Fragatouille) 库。\n* （2023年1月29日）我们合并了一个新的索引更新功能，并增加了对更多 Hugging Face 模型的支持！这些功能目前处于测试阶段，请在试用时向我们提供反馈。\n* （2023年1月24日）如果您正在寻找用于组合 ColBERTv2 等检索器和 LLM 的 **DSPy** 框架，可以访问：https:\u002F\u002Fgithub.com\u002Fstanfordnlp\u002Fdspy\n\n----\n\n## ColBERTv1\n\n来自 SIGIR'20 论文的 ColBERTv1 代码位于 [`colbertv1` 分支](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Fcolbertv1)。有关其他分支的更多信息，请参阅 [此处](#branches)。\n\n\n## 安装\n\n（更新：如今通常可以直接运行 `pip install colbert-ai[torch,faiss-gpu]` 来快速启动，但如果遇到问题，使用 conda 安装 `faiss` 和 `torch` 会更加可靠。）\n\nColBERT 需要 Python 3.7 及以上版本和 PyTorch 1.9 及以上版本，并使用 [Hugging Face Transformers](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Ftransformers) 库。\n\n我们强烈建议使用以下命令创建一个 conda 环境。（如果您没有 conda，请按照官方 [conda 安装指南](https:\u002F\u002Fdocs.anaconda.com\u002Fanaconda\u002Finstall\u002Flinux\u002F#installation) 进行安装。）\n\n我们还专门提供了一个仅适用于 CPU 环境的环境文件（`conda_env_cpu.yml`），但请注意，如果在包含 GPU 的机器上测试 CPU 执行，您可能需要在命令中指定 `CUDA_VISIBLE_DEVICES=\"\"`。需要注意的是，训练和索引构建需要 GPU。\n\n```\nconda env create -f conda_env[_cpu].yml\nconda activate colbert\n```\n\n如果您遇到任何问题，请[提交新 issue](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fissues)，我们将尽快为您提供帮助！\n\n\n\n## 概述\n\n在数据集上使用 ColBERT 通常包括以下步骤。\n\n**步骤 0：预处理您的语料库。** 最简单的情况下，ColBERT 可以处理制表符分隔（TSV）文件：一个文件（例如 `collection.tsv`）包含所有段落，另一个文件（例如 `queries.tsv`）则包含用于搜索该语料库的一组查询。\n\n**步骤 1：下载【预训练的 ColBERTv2 检查点】(https:\u002F\u002Fdownloads.cs.stanford.edu\u002Fnlp\u002Fdata\u002Fcolbert\u002Fcolbertv2\u002Fcolbertv2.0.tar.gz)。** 该检查点已在 MS MARCO 段落排序任务上进行过训练。您也可以_可选_地[训练您自己的 ColBERT 模型](#training)。\n\n**步骤 2：索引您的语料库。** 一旦您拥有了经过训练的 ColBERT 模型，就需要对您的语料库进行[索引构建](#indexing)，以便实现快速检索。此步骤会将所有段落编码为矩阵，存储在磁盘上，并构建用于高效搜索的数据结构。\n\n**步骤 3：使用您的查询搜索语料库。** 在拥有模型和索引之后，您可以[对语料库发出查询](#retrieval)，以检索每个查询的前 k 个最相关的段落。\n\n下面，我们通过一个在 MS MARCO 段落排序任务上的示例运行来说明这些步骤。\n\n\n## API 使用笔记本\n\n**新增**：我们在 [Google Colab](https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Fstanford-futuredata\u002FColBERT\u002Fblob\u002Fmain\u002Fdocs\u002Fintro2new.ipynb) 上提供了一个实验性笔记本，您可以使用免费的 GPU 运行。在免费的 Colab T4 GPU 上对 10,000 条记录进行索引构建只需六分钟。\n\n这个 Jupyter 笔记本【docs\u002Fintro.ipynb 笔记本】(docs\u002Fintro.ipynb) 展示了如何使用新的 Python API 来操作 ColBERT 的关键功能。\n\n其中包含了如何下载在 MS MARCO 段落排序任务上训练的 ColBERTv2 模型检查点，以及如何下载我们的全新 LoTTE 基准测试数据集。\n\n\n## 数据\n\n此仓库直接使用简单的**制表符分隔文件**格式来存储查询、段落和 top-k 排名列表。\n\n\n* 查询：每行格式为 `qid \\t query text`。\n* 语料库：每行格式为 `pid \\t passage text`。\n* Top-k 排名：每行格式为 `qid \\t pid \\t rank`。\n\n这与 [MS MARCO 段落排序](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FMSMARCO-Passage-Ranking) 数据集的数据格式直接兼容。您需要训练三元组（`triples.train.small.tar.gz`）、官方开发集查询的前 1000 名排名列表（`top1000.dev`）以及开发集的相关段落（`qrels.dev.small.tsv`）。若要索引整个语料库，还需要段落列表（`collection.tar.gz`）。\n\n## 索引\n\n为了实现快速检索，索引会预先计算段落的 ColBERT 表示。\n\n示例用法：\n\n```python\nfrom colbert.infra import Run, RunConfig, ColBERTConfig\nfrom colbert import Indexer\n\nif __name__=='__main__':\n    with Run().context(RunConfig(nranks=1, experiment=\"msmarco\")):\n\n        config = ColBERTConfig(\n            nbits=2,\n            root=\"\u002Fpath\u002Fto\u002Fexperiments\",\n        )\n        indexer = Indexer(checkpoint=\"\u002Fpath\u002Fto\u002Fcheckpoint\", config=config)\n        indexer.index(name=\"msmarco.nbits=2\", collection=\"\u002Fpath\u002Fto\u002FMSMARCO\u002Fcollection.tsv\")\n```\n\n\n## 检索\n\n我们通常建议您使用 ColBERT 进行**端到端**检索，它可以直接从整个语料库中找到前 k 个最相关的段落：\n\n```python\nfrom colbert.data import Queries\nfrom colbert.infra import Run, RunConfig, ColBERTConfig\nfrom colbert import Searcher\n\nif __name__=='__main__':\n    with Run().context(RunConfig(nranks=1, experiment=\"msmarco\")):\n\n        config = ColBERTConfig(\n            root=\"\u002Fpath\u002Fto\u002Fexperiments\",\n        )\n        searcher = Searcher(index=\"msmarco.nbits=2\", config=config)\n        queries = Queries(\"\u002Fpath\u002Fto\u002FMSMARCO\u002Fqueries.dev.small.tsv\")\n        ranking = searcher.search_all(queries, k=100)\n        ranking.save(\"msmarco.nbits=2.ranking.tsv\")\n```\n\n您可以选择指定 `ncells`、`centroid_score_threshold` 和 `ndocs` 等搜索超参数，以在速度和结果质量之间进行权衡。不同 `k` 值的默认设置列于 colbert\u002Fsearcher.py 中。\n\n我们可以使用以下命令评估 MSMARCO 排序结果：\n\n```\npython -m utility.evaluate.msmarco_passages --ranking \"\u002Fpath\u002Fto\u002Fmsmarco.nbits=2.ranking.tsv\" --qrels \"\u002Fpath\u002Fto\u002FMSMARCO\u002Fqrels.dev.small.tsv\"\n```\n\n## 基本训练（ColBERTv1 风格）\n\n我们提供了一个[预训练模型检查点](https:\u002F\u002Fdownloads.cs.stanford.edu\u002Fnlp\u002Fdata\u002Fcolbert\u002Fcolbertv2\u002Fcolbertv2.0.tar.gz)，但我们也在此详细说明如何从头开始训练。请注意，此示例演示的是 ColBERTv1 的训练方式，而提供的检查点是使用 ColBERTv2 训练的。\n\n训练需要一个 JSONL 三元组文件，每行包含 `[qid, pid+, pid-]` 列表。查询 ID 和段落 ID 分别对应指定的 `queries.tsv` 和 `collection.tsv` 文件。\n\n示例用法（在 4 个 GPU 上训练）：\n\n```python\nfrom colbert.infra import Run, RunConfig, ColBERTConfig\nfrom colbert import Trainer\n\nif __name__=='__main__':\n    with Run().context(RunConfig(nranks=4, experiment=\"msmarco\")):\n\n        config = ColBERTConfig(\n            bsize=32,\n            root=\"\u002Fpath\u002Fto\u002Fexperiments\",\n        )\n        trainer = Trainer(\n            triples=\"\u002Fpath\u002Fto\u002FMSMARCO\u002Ftriples.train.small.tsv\",\n            queries=\"\u002Fpath\u002Fto\u002FMSMARCO\u002Fqueries.train.small.tsv\",\n            collection=\"\u002Fpath\u002Fto\u002FMSMARCO\u002Fcollection.tsv\",\n            config=config,\n        )\n\n        checkpoint_path = trainer.train()\n\n        print(f\"已保存检查点至 {checkpoint_path}...\")\n```\n\n\n## 高级训练（ColBERTv2 风格）\n\n```python\nfrom colbert.infra.run import Run\nfrom colbert.infra.config import ColBERTConfig, RunConfig\nfrom colbert import Trainer\n\n\ndef train():\n    # 使用 4 个 GPU（例如四张 A100 显卡，但您可以通过调整 nway、accumsteps 和 bsize 来使用更少的 GPU）。\n    with Run().context(RunConfig(nranks=4)):\n        triples = '\u002Fpath\u002Fto\u002Fexamples.64.json'  # `wget https:\u002F\u002Fhuggingface.co\u002Fcolbert-ir\u002Fcolbertv2.0_msmarco_64way\u002Fresolve\u002Fmain\u002Fexamples.json?download=true` (26GB)\n        queries = '\u002Fpath\u002Fto\u002FMSMARCO\u002Fqueries.train.tsv'\n        collection = '\u002Fpath\u002Fto\u002FMSMARCO\u002Fcollection.tsv'\n\n        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)\n        trainer = Trainer(triples=triples, queries=queries、collection=collection、config=config)\n\n        trainer.train(checkpoint='colbert-ir\u002Fcolbertv1.9')  # 或者从头开始，比如使用 `bert-base-uncased`\n\n\nif __name__ == '__main__':\n    train()\n```\n\n\n## 运行轻量级 ColBERTv2 服务器\n我们提供了一个脚本，用于运行一个轻量级服务器，该服务器可以为给定的搜索查询以 JSON 格式提供按排名顺序排列的最多 100 个结果。此脚本可用于支持 DSP 程序。\n\n要运行服务器，请在 `.env` 文件中更新环境变量 `INDEX_ROOT` 和 `INDEX_NAME`，使其指向相应的 ColBERT 索引。然后运行以下命令：\n```\npython server.py\n```\n\n示例查询：\n```\nhttp:\u002F\u002Flocalhost:8893\u002Fapi\u002Fsearch?query=Who won the 2022 FIFA world cup&k=25\n```\n\n## 分支\n\n### 支持的分支\n\n* [`main`](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Fmain)：稳定分支，包含 ColBERTv2 + PLAID。\n* [`colbertv1`](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Fcolbertv1)：ColBERTv1 的遗留分支。\n\n### 已弃用的分支\n* [`new_api`](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Fnew_api)：基础 ColBERTv2 实现。\n* [`cpu_inference`](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Fcpu_inference)：支持 CPU 搜索的 ColBERTv2 实现。\n* [`fast_search`](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Ffast_search)：带有 PLAID 的 ColBERTv2 实现。\n* [`binarization`](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Ftree\u002Fbinarization)：采用基于二值化的压缩策略的 ColBERT（与 ColBERTv2 的残差压缩相比，后者被证明更为稳健）。\n\n## 致谢\n\nColBERT 徽标由 Chuyi Zhang 设计。","# ColBERT 快速上手指南\n\nColBERT 是一款基于 BERT 的快速、高精度检索模型，通过细粒度的“上下文晚期交互”（Contextualized Late Interaction）机制，能够在数十毫秒内完成大规模文本集合的搜索。\n\n## 环境准备\n\n在开始之前，请确保您的系统满足以下要求：\n\n*   **操作系统**: Linux (推荐) 或 macOS\n*   **Python**: 3.7 或更高版本\n*   **PyTorch**: 1.9 或更高版本\n*   **硬件**: \n    *   **训练与索引**: 必须使用 GPU。\n    *   **搜索**: 支持 GPU 和 CPU（若在含 GPU 的机器上强制使用 CPU，需设置 `CUDA_VISIBLE_DEVICES=\"\"`）。\n*   **依赖库**: Hugging Face Transformers, FAISS\n\n> **建议**: 推荐使用 `conda` 管理环境以确保 `faiss` 和 `torch` 依赖的正确安装。\n\n## 安装步骤\n\n### 1. 创建 Conda 环境\n\n克隆仓库后，使用项目提供的配置文件创建环境。\n\n```bash\n# 对于 GPU 环境\nconda env create -f conda_env.yml\n# 对于纯 CPU 环境（仅用于测试搜索）\n# conda env create -f conda_env_cpu.yml\n\nconda activate colbert\n```\n\n### 2. 安装 ColBERT 包\n\n激活环境后，通过 pip 安装核心包。国内用户若遇网络问题，可尝试指定清华源或阿里源。\n\n```bash\n# 标准安装\npip install colbert-ai[torch,faiss-gpu]\n\n# 国内加速示例 (使用清华源)\n# pip install colbert-ai[torch,faiss-gpu] -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple\n```\n\n## 基本使用\n\n以下是使用预训练模型进行**索引构建**和**检索**的最小化工作流。\n\n### 第一步：数据准备\n\nColBERT 直接使用制表符分隔（TSV）文件。\n*   **文档集合 (`collection.tsv`)**: 格式为 `pid \\t passage text`\n*   **查询文件 (`queries.tsv`)**: 格式为 `qid \\t query text`\n\n### 第二步：下载预训练模型\n\n下载在 MS MARCO 数据集上训练的 ColBERTv2 检查点：\n\n```bash\nwget https:\u002F\u002Fdownloads.cs.stanford.edu\u002Fnlp\u002Fdata\u002Fcolbert\u002Fcolbertv2\u002Fcolbertv2.0.tar.gz\ntar -xzf colbertv2.0.tar.gz\n# 假设解压后的路径为 \u002Fpath\u002Fto\u002Fcheckpoint\n```\n\n### 第三步：构建索引 (Indexing)\n\n将文档集合编码为矩阵并建立索引结构。\n\n```python\nfrom colbert.infra import Run, RunConfig, ColBERTConfig\nfrom colbert import Indexer\n\nif __name__=='__main__':\n    # nranks 表示使用的 GPU 数量\n    with Run().context(RunConfig(nranks=1, experiment=\"my_experiment\")):\n\n        config = ColBERTConfig(\n            nbits=2,  # 压缩位数\n            root=\"\u002Fpath\u002Fto\u002Fexperiments\", # 实验根目录\n        )\n        \n        indexer = Indexer(checkpoint=\"\u002Fpath\u002Fto\u002Fcheckpoint\", config=config)\n        indexer.index(\n            name=\"my_collection.nbits=2\", \n            collection=\"\u002Fpath\u002Fto\u002Fcollection.tsv\"\n        )\n```\n\n### 第四步：执行检索 (Retrieval)\n\n加载索引并对查询进行搜索。\n\n```python\nfrom colbert.data import Queries\nfrom colbert.infra import Run, RunConfig, ColBERTConfig\nfrom colbert import Searcher\n\nif __name__=='__main__':\n    with Run().context(RunConfig(nranks=1, experiment=\"my_experiment\")):\n\n        config = ColBERTConfig(\n            root=\"\u002Fpath\u002Fto\u002Fexperiments\",\n        )\n        \n        # 加载刚才创建的索引\n        searcher = Searcher(index=\"my_collection.nbits=2\", config=config)\n        \n        # 加载查询文件\n        queries = Queries(\"\u002Fpath\u002Fto\u002Fqueries.tsv\")\n        \n        # 执行搜索，k 为返回结果数量\n        ranking = searcher.search_all(queries, k=100)\n        \n        # 保存结果\n        ranking.save(\"my_collection.ranking.tsv\")\n```\n\n### 进阶提示\n*   **Google Colab 体验**: 官方提供了 [Intro Notebook](https:\u002F\u002Fcolab.research.google.com\u002Fgithub\u002Fstanford-futuredata\u002FColBERT\u002Fblob\u002Fmain\u002Fdocs\u002Fintro2new.ipynb)，可在免费 T4 GPU 上快速试运行（索引 1 万条数据约需 6 分钟）。\n*   **应用集成**: 若需在 RAG 应用中快速集成，推荐使用社区维护的 [RAGatouille](https:\u002F\u002Fgithub.com\u002Fbclavie\u002Fragatouille) 库。","某大型法律科技公司的研发团队正在构建一个智能案情检索系统，需要从数百万份历史判决书中快速定位与当前案件细节高度匹配的先例。\n\n### 没有 ColBERT 时\n- **语义理解肤浅**：传统单向量模型将整段法律文书压缩为一个固定向量，导致“合同违约”与“协议解除”等细微语义差别被抹平，召回结果相关性低。\n- **关键细节丢失**：由于缺乏细粒度交互，模型难以捕捉查询词（如特定赔偿金额或日期）与文档中具体片段的精确对应关系，常漏掉关键证据段落。\n- **响应速度缓慢**：为了保证一定的准确率，不得不引入重排序（Rerank）步骤，导致在大规模数据下的检索延迟高达数秒，无法满足实时交互需求。\n- **扩展成本高昂**：随着文书库从十万级增长到百万级，现有架构的计算资源消耗呈指数级上升，难以在不牺牲速度的前提下进行扩容。\n\n### 使用 ColBERT 后\n- **细粒度精准匹配**：ColBERT 利用“延迟交互”机制，将文档编码为 token 级别的嵌入矩阵，能精准识别查询词与文中具体词汇的上下文关联，显著提升语义匹配度。\n- **保留局部关键信息**：通过 MaxSim 算子高效计算细粒度相似度，即使查询包含复杂的法律术语组合，也能准确锁定文档中包含这些细节的具体句子。\n- **毫秒级极速响应**：无需耗时的重排序步骤，ColBERT 直接在索引阶段完成高效打分，将千万级数据的检索延迟压缩至几十毫秒，实现流畅的用户体验。\n- **低成本线性扩展**：其轻量级的后期交互架构支持 scalable 向量相似度搜索，使得系统在数据量翻倍时，仅需线性增加存储而非巨大的算力投入。\n\nColBERT 通过独创的细粒度上下文交互技术，完美解决了法律垂直领域对检索精度与响应速度的双重苛刻要求。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fstanford-futuredata_ColBERT_26fadd19.png","stanford-futuredata","Future Data Systems","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fstanford-futuredata_1afa6134.png","We are a CS research group building data-intensive systems",null,"https:\u002F\u002Fgithub.com\u002Fstanford-futuredata",[79,83,87],{"name":80,"color":81,"percentage":82},"Python","#3572A5",93.2,{"name":84,"color":85,"percentage":86},"C++","#f34b7d",5.5,{"name":88,"color":89,"percentage":90},"Cuda","#3A4E3A",1.2,3821,468,"2026-04-07T05:10:20","MIT","Linux","训练和索引步骤必需 GPU（未指定具体型号，示例提及 A100）；仅搜索\u002F推理支持 CPU 模式（需设置环境变量 CUDA_VISIBLE_DEVICES=\"\"）；CUDA 版本未明确说明，依赖 PyTorch 版本。","未说明",{"notes":99,"python":100,"dependencies":101},"强烈建议使用 conda 创建环境以确保 faiss 和 torch 的兼容性。虽然提供了 CPU 专用环境文件，但官方明确指出训练和索引过程必须使用 GPU。若在含 GPU 的机器上测试 CPU 执行，需手动指定环境变量禁用 GPU。可通过 pip 安装，但遇到依赖问题时 conda 更可靠。","3.7+",[102,103,104],"torch>=1.9","transformers","faiss-gpu",[35,14],"2026-03-27T02:49:30.150509","2026-04-07T22:59:37.438285",[109,114,119,124,129],{"id":110,"question_zh":111,"answer_zh":112,"source_url":113},22882,"如何训练 ColBERT v2 模型？有示例代码和数据集吗？","维护者已发布 ColBERT v2 的训练代码和示例数据。你可以从 Hugging Face Hub 下载 64-way 的示例文件 (examples.json) 和使用 ColBERT v1.9 作为初始检查点。\n\n示例训练代码如下：\n```python\nfrom colbert.infra.run import Run\nfrom colbert.infra.config import ColBERTConfig, RunConfig\nfrom colbert import Trainer\n\ndef train():\n    # 使用 4 张 GPU (例如 A100)，可通过调整 nway, accumsteps, bsize 来适应更少显卡\n    with Run().context(RunConfig(nranks=4)):\n        triples = '\u002Fpath\u002Fto\u002Fexamples.64.json'  # 下载地址: https:\u002F\u002Fhuggingface.co\u002Fcolbert-ir\u002Fcolbertv2.0_msmarco_64way\u002Fresolve\u002Fmain\u002Fexamples.json?download=true (26GB)\n        queries = '\u002Fpath\u002Fto\u002FMSMARCO\u002Fqueries.train.tsv'\n        collection = '\u002Fpath\u002Fto\u002FMSMARCO\u002Fcollection.tsv'\n\n        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)\n        trainer = Trainer(triples=triples, queries=queries, collection=collection, config=config)\n\n        # 从预训练模型开始训练，也可以从头开始如 'bert-base-uncased'\n        trainer.train(checkpoint='colbert-ir\u002Fcolbertv1.9')\n\nif __name__ == '__main__':\n    train()\n```\n详细指令请参阅项目 README 中的 \"Advanced Training (ColBERTv2-style)\" 部分。","https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fissues\u002F94",{"id":115,"question_zh":116,"answer_zh":117,"source_url":118},22883,"在使用 ColBERT 进行检索时，生成的 unordered.tsv 文件中 rank 列全为 -1 是怎么回事？","这通常是因为文档 ID 或查询 ID 的起始值问题。ColBERT 期望 ID 从 1 开始，而不是从 0 开始。请检查你的输入数据文件（如 tsv 文件），确保所有 ID 都是从 1 开始编号的。如果 ID 从 0 开始，可能会导致内部索引错误，从而产生无效的排名结果（如 -1）。修改数据生成脚本或预处理步骤，使 ID 从 1 开始即可解决此问题。","https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fissues\u002F81",{"id":120,"question_zh":121,"answer_zh":122,"source_url":123},22884,"如何使用 ColBERT 处理长文档并进行自定义模型的训练和检索？","处理长文档和训练自定义模型的推荐流程如下：\n1. **预处理长文档**：使用 `utility\u002Fpreprocess\u002Fdocs2passages.py` 脚本将长文档切分为片段（passages）。该脚本通过滑动窗口方式切分文本。\n2. **准备训练数据**：构建格式为 `query \\t positive_passage \\t negative_passage` 的 TSV 文件。\n3. **训练模型**：使用以下命令训练自定义 ColBERT 模型：\n   ```bash\n   python -m colbert.train --amp --doc_maxlen 180 --mask-punctuation --bsize 32 --accum 1 -- train_dataset.tsv\n   ```\n4. **建立索引**：训练完成后，使用保存的检查点文件，结合 FAISS 对文档库建立索引。如果使用 PyTerrier，代码如下：\n   ```python\n   import pyterrier_colbert.indexing\n   indexer = pyterrier_colbert.indexing.ColBERTIndexer(checkpoint_path, \"\u002Fcontent\", \"colbertindex\", chunksize=3)\n   indexer.index(test_df) # test_df 需包含 docno 和 text 列\n   ```\n5. **检索排序**：索引建立后，传入查询即可对顶部 K 个文档进行排序。\n\n注意：如果需要复杂的重新排序逻辑，建议将 ColBERT 用作检索器（获取 top-100 或 top-1000 结果），然后在此基础上编写自定义的重排序代码，直接修改核心排序代码较为困难且不受官方支持。","https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fissues\u002F73",{"id":125,"question_zh":126,"answer_zh":127,"source_url":128},22885,"在尝试直接调用底层 API 进行重排序时遇到 'stride' 未定义的错误，这是 Bug 吗？","这通常是由于版本差异或特定配置导致的。如果你在使用快速单查询检索 - 重排序方法时遇到分数偏差，可能是因为使用了 `.reconstruct(id)` 方法，该方法返回的是经过乘积量化（product quantization）后的近似向量，导致分数与原始仓库计算结果略有不同。\n\n解决方案与建议：\n1. **接受量化误差**：如果追求速度，这种轻微的分数偏差是使用乘积量化（IVFPQ）的正常现象。\n2. **使用精确索引**：如果需要精确分数，可以尝试配置使用普通的 IVF 索引而不是 IVFPQ，但这会增加内存消耗。\n3. **日志控制**：可以通过修改接口类来控制打印语句或连接到上游日志级别。\n4. **内存优化**：如果数据无法全部加载到内存中，请查阅项目的量化（quantization）相关功能。研究发现，仅保留向量的符号（正数为 +1，负数为 -1，共 128 位）可以在几乎不损失质量的情况下大幅减少文档侧向量的存储空间。","https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fissues\u002F51",{"id":130,"question_zh":131,"answer_zh":132,"source_url":133},22886,"运行 FAISS 索引构建脚本时出现 'Default process group is not initialized' 错误怎么办？","该错误通常与分布式训练环境的初始化有关，即使只使用单卡或多卡也可能发生。虽然具体原因可能因环境而异（如 Docker 容器、PyTorch 版本等），但请确保：\n1. 正确设置了 `CUDA_VISIBLE_DEVICES` 和 `OMP_NUM_THREADS` 环境变量。\n2. 如果使用 `torch.distributed.launch`，请确保参数 `--nproc_per_node` 与实际使用的 GPU 数量匹配。\n3. 检查 PyTorch 版本兼容性（曾有人通过降级 Torch 版本解决类似问题，但也可能是其他配置问题）。\n如果问题依旧，建议检查是否需要在脚本中手动初始化进程组，或者确认当前环境是否正确支持 NCCL 后端。由于该问题在特定环境下已解决，建议对比成功运行的环境配置。","https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fissues\u002F38",[135],{"id":136,"version":137,"summary_zh":138,"released_at":139},136656,"v0.2.22","## 概述\n\n- 错误修复\n  - 修复：[training.py](https:\u002F\u002Fgithub.com\u002Fdipta007\u002FColBERT\u002Fblob\u002F2b14566f8120ba57c47e879150ec73eca0286b2c\u002Fcolbert\u002Ftraining\u002Ftraining.py#L7-L8) 中的 AdamW 导入错误 [#390](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fpull\u002F390)\n  - 更新 [loaders.py](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fblob\u002F9b11d5cf9788c8d32206f6e9f7474c156c8403bc\u002Fcolbert\u002Findexing\u002Floaders.py#L25)，在正则表达式中使用 `r` 标志 [#368](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fpull\u002F368)。\n  - 在 [setup.py](https:\u002F\u002Fgithub.com\u002Fmoritzwilksch\u002FColBERT\u002Fblob\u002F736f88b981078a2c8687c8ee33c0f390e01284cd\u002Fsetup.py#L25) 中使用正确的 GitPython 版本 [#388](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fpull\u002F388)。\n\n- 改进\n  - 在为单个文档池化嵌入时，省略 tqdm 进度条 [#367](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fpull\u002F367)，见 [checkpoint.py](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fblob\u002Fbc7610a7372e8bb1df2efa3b7b91b23369a45050\u002Fcolbert\u002Fmodeling\u002Fcheckpoint.py#L24)。\n  - 如果已传入 pids，则不进行初始检索 [#352](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fpull\u002F352)，见 [index_storage.py](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fblob\u002F7067ef598b5011edaa1f4a731a2c269dbac864e4\u002Fcolbert\u002Fsearch\u002Findex_storage.py#L92)。\n\n主要修复是 [#390](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fpull\u002F390)，它修复了 AdamW 的导入错误（`transformers.AdamW` 已弃用）。这使得用户可以使用最新版本的 transformers。然而，最新的 transformers [依赖于 `torch>=2.1`](https:\u002F\u002Fgithub.com\u002Fhuggingface\u002Ftransformers\u002Fblob\u002F6dfd561d9cd722dfc09f702355518c6d09b9b4e3\u002Fsetup.py#L193C6-L193C16)，而 ColBERT 目前仍然 [依赖于 `torch==1.13.1`](https:\u002F\u002Fgithub.com\u002Fstanford-futuredata\u002FColBERT\u002Fblob\u002F0c743705135932daf911487bd36e1588c2ffc604\u002Fsetup.py#L36)。正如以下各节所示，使用最新版本的 torch（`2.8.0`）和 transformers（`4.55.0`）并不会破坏核心功能，但会导致索引、检索和训练结果与使用 `torch==1.13.1` 和 `transformers==4.38.2`（最后一个包含 `AdamW` 的版本）时有所不同。\n\n## ColBERT 0.2.21 与 0.2.22 对比\n\n在这一部分，我将比较两个不同 `colbert-ai` 安装之间的索引产物、检索产物以及训练日志：\n\n- PyPI 上的上一个版本（0.2.21；2024年8月20日），使用 `torch==1.13.1` 和 `transformers==4.38.2`（最后一个包含 `AdamW` 的版本），以下简称“0.2.21”。\n- 最新版本（0.2.22；2025年8月10日），使用 `torch==2.8.0` 和 `transformers==4.55.0`（两者均为最新版本），以下简称“0.2.22”。\n\n我的索引、检索、训练及对比脚本可以在我的 [colbert-maintenance 仓库](https:\u002F\u002Fgithub.com\u002Fvishalbakshi\u002Fcolbert-maintenance\u002Ftree\u002Fmain\u002F0.2.22) 中找到。\n\n\n### ConditionalQA 索引产物\n\n我比较了两个索引中 `.pt` 文件的形状和数值（使用 `torch.allclose`），这两个索引分别来自 [UKPLab\u002FDAPR\u002FConditionalQA 文档集合](https:\u002F\u002Fhuggingface.co\u002Fdatasets\u002FUKPLab\u002Fd","2025-08-11T03:22:44"]