[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-texttron--tevatron":3,"tool-texttron--tevatron":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 真正成长为懂上",160784,2,"2026-04-19T11:32:54",[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 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",109154,"2026-04-18T11:18:24",[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},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"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":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":72,"owner_avatar_url":73,"owner_bio":74,"owner_company":75,"owner_location":75,"owner_email":75,"owner_twitter":75,"owner_website":75,"owner_url":76,"languages":77,"stars":86,"forks":87,"last_commit_at":88,"license":89,"difficulty_score":10,"env_os":90,"env_gpu":91,"env_ram":92,"env_deps":93,"category_tags":106,"github_topics":108,"view_count":32,"oss_zip_url":75,"oss_zip_packed_at":75,"status":17,"created_at":115,"updated_at":116,"faqs":117,"releases":147},9680,"texttron\u002Ftevatron","tevatron","Tevatron - Unified Document Retrieval Toolkit across Scale, Language, and Modality. Demo in SIGIR 2023, SIGIR 2025.","Tevatron 是一款统一的文档检索工具包，旨在跨越数据规模、语言种类及模态限制，为构建高性能神经检索系统提供一站式解决方案。它主要解决了在大规模数据环境下，训练和优化检索模型时面临的算力消耗大、多模态适配难以及前沿模型集成复杂等痛点。\n\n无论是希望复现学术成果的研究人员，还是需要部署工业级检索系统的开发者，都能从中受益。Tevatron 支持在 GPU 和 TPU 上训练十亿参数级别的大语言模型（LLM）检索器，并集成了 LoRA 参数高效微调技术，显著降低了硬件门槛。其独特亮点在于深度整合了 vLLM、DeepSpeed、FlashAttention 等主流加速框架，支持梯度累积等高效训练策略。此外，它内置了丰富的多模态与多语言数据集，并能直接加载和微调 HuggingFace 上的最先进预训练模型（如 BGE-Embedding、Instruct-E5）。通过简洁的配置，用户即可轻松完成从数据准备到模型微调的全流程，快速构建适用于开放域问答或多语言搜索场景的强力检索引擎。","# Tevatron V2.0\n\n\u003Cdiv align=\"center\">\n\u003Ca href=\"https:\u002F\u002Farxiv.org\u002Fabs\u002F2203.05765\" target=\"_blank\">\u003Cimg src=https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FarXiv-b5212f.svg?logo=arxiv>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fhuggingface.co\u002FTevatron\" target=\"_blank\">\u003Cimg src=https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F%F0%9F%A4%97%20HuggingFace%20Datasets-27b3b4.svg>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fopensource.org\u002Flicense\u002Fapache-2-0\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fstatic\u002Fv1?label=License&message=Apache-2.0&color=red\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fpepy.tech\u002Fprojects\u002Ftevatron\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftexttron_tevatron_readme_a90e877c9891.png\" alt=\"PyPI Downloads\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fstar-history.com\u002F#texttron\u002Ftevatron\"> \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Ftexttron\u002Ftevatron?style=social\" alt=\"GitHub stars\"> \u003C\u002Fa>\n\u003C!--   -->\n\u003C\u002Fdiv>\n\nTevatron: Unified Document Retrieval Toolkit across Scale, Language, and Modality.\n\n> Some of the features in Tevatron v1 is not yet migrated to Tevatron v2.0. We are working on it.\n> If you are looking for the Tevatron v1 features, please pull the [v1 branch](https:\u002F\u002Fgithub.com\u002Ftexttron\u002Ftevatron\u002Ftree\u002Ftevatron-v1).\n\n## Features\n- Training billion-scale LLM neural retriever on GPUs and TPUs.\n- Parameter efficient tuning with LoRA.\n- Integration with vLLM, DeepSpeed, FlashAttention, gradient accumulation, and other efficient training and inference techniques.\n- Self-contained [huggingface datasets](https:\u002F\u002Fhuggingface.co\u002FTevatron) for multi-modal and multilingual neural retrieval and open-domain QA tasks.\n- Direct loading and finetuning SoTA pre-trained models (BGE-Embbedding, Instruct-E5) from HuggingFace.\n\n## Installation\n\n\u003Cdetails>\u003Csummary>\u003Cb>PyTorch (GPU)\u003C\u002Fb>\u003C\u002Fsummary>\n\n0. Clone the repository.\n1. Install PyTorch based on your CUDA version from [PyTorch](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F).\n2. Install dependencies and Tevatron.\n```bash\npip install transformers datasets peft\npip install deepspeed accelerate\npip install faiss-cpu\npip install -e .\n```\n\n\n\u003C\u002Fdetails>\n\u003Cdetails>\u003Csummary>\u003Cb>JAX (TPU)\u003C\u002Fb>\u003C\u002Fsummary>\n\n0. Clone the repository.\n1. Install JAX by following the [official guide](https:\u002F\u002Fjax.readthedocs.io\u002Fen\u002Flatest\u002Finstallation.html#pip-installation-google-cloud-tpu)\n2. Install dependencies\n```bash\npip install transformers datasets\npip install flax optax\n```\n3. Install Magix and GradCache\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fluyug\u002Fmagix.git\ncd magix && pip install -e . && cd ..\ngit clone https:\u002F\u002Fgithub.com\u002Fluyug\u002FGradCache.git\ncd GradCache && pip install -e . && cd ..\n```\n\n4. Install Tevatron\n```bash\npip install -e .\n```\n\n\u003C\u002Fdetails>\n\u003Cdetails>\u003Csummary>\u003Cb>JAX (GPU)\u003C\u002Fb>\u003C\u002Fsummary>\n\nTo run the JAX implementation of Tevatron on GPU, we encourage using the jax-toolbox [jax container](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FJAX-Toolbox\u002Fpkgs\u002Fcontainer\u002Fjax) image from NVIDIA.\n\nBelow is a Dockerfile example to set up Tevatron on top of the jax container.\n```Dockerfile\nFROM ghcr.io\u002Fnvidia\u002Fjax:jax-2024-03-08\n\nRUN apt-get update && \\\n    apt-get install -y --no-install-recommends python3-pip && \\\n    apt-get clean && \\\n    rm -rf \u002Fvar\u002Flib\u002Fapt\u002Flists\u002F* && \\\n    pip install --no-cache-dir transformers sentencepiece simple_parsing datasets orbax==0.4.8 && \\\n    pip install --no-cache-dir torch --index-url https:\u002F\u002Fdownload.pytorch.org\u002Fwhl\u002Fcpu\n\nRUN git clone https:\u002F\u002Fgithub.com\u002Fluyug\u002Fmagix.git && \\\n    cd magix && pip install -e . && cd .. && \\\n    git clone https:\u002F\u002Fgithub.com\u002Fluyug\u002FGradCache.git \\\n    cd GradCache && pip install -e . && cd .. \\\n    git clone https:\u002F\u002Fgithub.com\u002Ftexttron\u002Ftevatron.git && \\\n    cd tevatron && pip install -e .\n```\n\n\n\n\n\u003C\u002Fdetails>\n\n\n\n## Tevatron 101\nIn this example, we will demonstrate how to use Tevatron to LoRA fine-tune a Mistral-7B model on the MSMARCO passage dataset. The obtained LLM Retriever is expected to have `MRR@10=42.3` on the MS MARCO dev set with straightforward training.\n\n\u003Cdetails>\u003Csummary>\u003Cb>Data Preparation\u003C\u002Fb>\u003C\u002Fsummary>\n\nTevatron takes training or inference data in `jsonl` format with each line organized as a json object as follows:\n### 1. Training Data\n```json\n{\n   \"query_id\": \"\u003Cquery id>\",\n   \"query_text\": \"\u003Cquery text>\",\n   \"query_image\": \"\u003Cquery image>\",\n   \"positive_document_ids\": [\"\u003Cpassage id>\", ...],\n   \"negative_document_ids\": [\"\u003Cpassage id>\", ...],\n}\n```\nwhere the passages in `positive_passages` are the annotated relevant passages of the `query` \nand passages in `negative_passages` are usually non-relevant (hard negative) passages from top results of a retrieval system (e.g. BM25, DPR). Additional fields such as `answers` for QA datasets can be included as well.\n\n#### 2. Corpus Data\n```json\n{\n   \"docid\": \"\u003Cdocument id>\",\n   \"document_text\": \"\u003Cdocument text>\",\n   \"document_image\": \"\u003Cdocument image>\",\n}\n```\nwhere each line represents a document in the corpus. \n\nNote that the image field for both training and corpus data are optional and can be omitted (i.e., pure textual modality retrieval).\n\n### Self-Contained Dataset\nTevatron self-contained several commonlly used datasets for neural retrieval. \n(via [HuggingFace](https:\u002F\u002Fhuggingface.co\u002FTevatron)).\nThese datasets can downloaded automatically during training and encoding\nby setting `--dataset_name \u003Chgf dataset name>`.\n\nIn this example, we will use the self-contained dataset `Tevatron\u002Fmsmarco-passage-aug` for training, whose hard negative passages are sampled from the mix of top200 BM25 and top200 CoCondenser results.\n\n\u003C\u002Fdetails>\n\n\n\u003Cdetails>\u003Csummary>\u003Cb>Run with PyTorch (GPU)\u003C\u002Fb>\u003C\u002Fsummary>\n\n### Training\n\n```bash\ndeepspeed --include localhost:0,1,2,3 --master_port 60000 --module tevatron.retriever.driver.train \\\n  --deepspeed deepspeed\u002Fds_zero3_config.json \\\n  --output_dir retriever-mistral \\\n  --model_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n  --lora \\\n  --lora_target_modules q_proj,k_proj,v_proj,o_proj,down_proj,up_proj,gate_proj \\\n  --save_steps 50 \\\n  --dataset_name Tevatron\u002Fmsmarco-passage-aug \\\n  --query_prefix \"Query: \" \\\n  --passage_prefix \"Passage: \" \\\n  --bf16 \\\n  --pooling eos \\\n  --append_eos_token \\\n  --normalize \\\n  --temperature 0.01 \\\n  --per_device_train_batch_size 8 \\\n  --gradient_checkpointing \\\n  --train_group_size 16 \\\n  --learning_rate 1e-4 \\\n  --query_max_len 32 \\\n  --passage_max_len 156 \\\n  --num_train_epochs 1 \\\n  --logging_steps 10 \\\n  --overwrite_output_dir \\\n  --gradient_accumulation_steps 4\n```\n\nIn batch passages per query: 8x4x16 = 512\n\nNumber of queries per update: 8x4x4 = 128\n\nThe above training setting tooks about 70 hours on 4xA6000 GPU.\n\nEquivalent training tooks about 110 hours on 1xA100 GPU.\n\n\n\n### Encoding\n\n#### Query Encoding\n```bash\nEMBEDDING_OUTPUT_DIR=\u003Cfolder to save query embedding>\nCUDA_VISIBLE_DEVICES=4 python -m tevatron.retriever.driver.encode \\\n  --output_dir=temp \\\n  --model_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n  --lora_name_or_path retriever-mistral \\\n  --lora \\\n  --query_prefix \"Query: \" \\\n  --passage_prefix \"Passage: \" \\\n  --bf16 \\\n  --pooling eos \\\n  --append_eos_token \\\n  --normalize \\\n  --encode_is_query \\\n  --per_device_eval_batch_size 128 \\\n  --query_max_len 32 \\\n  --passage_max_len 156 \\\n  --dataset_name Tevatron\u002Fmsmarco-passage \\\n  --dataset_split dev \\\n  --encode_output_path $EMBEDDING_OUTPUT_DIR\u002Fquery-dev.pkl\n```\n\n#### Corpus Encoding\n```bash\nEMBEDDING_OUTPUT_DIR=\u003Cfolder to save query embedding>\nfor s in 0 1 2 3\ndo\ngpuid=$s\nCUDA_VISIBLE_DEVICES=$gpuid python -m tevatron.retriever.driver.encode \\\n  --output_dir=temp \\\n  --model_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n  --lora_name_or_path retriever-mistral \\\n  --lora \\\n  --query_prefix \"Query: \" \\\n  --passage_prefix \"Passage: \" \\\n  --bf16 \\\n  --pooling eos \\\n  --append_eos_token \\\n  --normalize \\\n  --per_device_eval_batch_size 128 \\\n  --query_max_len 32 \\\n  --passage_max_len 156 \\\n  --dataset_name Tevatron\u002Fmsmarco-passage-corpus \\\n  --dataset_number_of_shards 4 \\\n  --dataset_shard_index ${s} \\\n  --encode_output_path $EMBEDDING_OUTPUT_DIR\u002Fcorpus.${s}.pkl\ndone\n```\n> add & to the end of the command to run in the background in parallel.\n\n### Retrieval\n```bash\nset -f && python -m tevatron.retriever.driver.search \\\n    --query_reps $EMBEDDING_OUTPUT_DIR\u002Fquery-dev.pkl \\\n    --passage_reps $EMBEDDING_OUTPUT_DIR\u002Fcorpus*.pkl \\\n    --depth 1000 \\\n    --batch_size 64 \\\n    --save_text \\\n    --save_ranking_to $EMBEDDING_OUTPUT_DIR\u002Frun.dev.txt\n```\n\nThe output file is in the format of `\u003Cquery_id> \u003Cpassage_id> \u003Cscore>` in each line.\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\u003Csummary>\u003Cb>Run with JAX (TPU\u002FGPU)\u003C\u002Fb>\u003C\u002Fsummary>\n\n### Training\n\n> For GPU training, set `XLA_PYTHON_CLIENT_MEM_FRACTION=.95` and make sure the query and passage length are multiples of 64 if TransformersEngine is installed.\n\n```bash\npython -m tevatron.tevax.experimental.mp.train_lora  \\\n   --checkpoint_dir retriever-mistral-jax \\\n   --train_file Tevatron\u002Fmsmarco-passage-aug \\\n   --model_name mistralai\u002FMistral-7B-v0.1 \\\n   --model_type mistral \\\n   --batch_size 128 \\\n   --num_target_passages 16 \\\n   --learning_rate 1e-4 \\\n   --seed 12345 \\\n   --mesh_shape 1 -1 \\\n   --weight_decay 0.00001 \\\n   --num_epochs 1 \\\n   --max_query_length 64 \\\n   --max_passage_length 128 \\\n   --pooling eos \\\n   --scale_by_dim True \\\n   --grad_cache \\\n   --passage_num_chunks 32 \\\n   --query_num_chunks 4\n```\n\nIn batch passages per query: 128x16 = 2048\n\nNumber of queries per update: 128\n\nThe above training setting tooks about 35 hours on a v4-8 TPU VM.\n\nEquivalent training tooks about 80 hours on 1xA100 GPU.\n\n### Encoding\n\n#### Query Encoding\n```bash\npython -m tevatron.tevax.experimental.mp.encode  \\\n   --model_type mistral \\\n   --model_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n   --model_config_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n   --tokenizer_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n   --dataset_name_or_path Tevatron\u002Fmsmarco-passage \\\n   --split dev \\\n   --output_dir $EMBEDDING_OUTPUT_DIR\u002Fquery-embedding \\\n   --batch_size 32 \\\n   --input_type query \\\n   --max_seq_length 64 \\\n   --mesh_shape 1 -1 \\\n   --lora retriever-mistral-jax\u002Flora \\\n   --scale_by_dim\n```\n\n#### Corpus Encoding\n```bash\npython -m tevatron.tevax.experimental.mp.encode  \\\n   --model_type mistral \\\n   --model_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n   --model_config_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n   --tokenizer_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n   --dataset_name_or_path Tevatron\u002Fmsmarco-passage-corpus \\\n   --output_dir $EMBEDDING_OUTPUT_DIR\u002Fcorpus-embedding \\\n   --batch_size 32 \\\n   --input_type passage \\\n   --max_seq_length 128 \\\n   --mesh_shape 1 -1 \\\n   --lora retriever-mistral-jax\u002Flora \\\n   --scale_by_dim\n```\n\n### Retrieval\n```bash\nset -f && python -m tevatron.retriever.driver.search \\\n    --query_reps $EMBEDDING_OUTPUT_DIR\u002Fquery-embedding\u002F*.pkl \\\n    --passage_reps $EMBEDDING_OUTPUT_DIR\u002Fcorpus-embedding\u002F*.pkl \\\n    --depth 1000 \\\n    --batch_size 64 \\\n    --save_text \\\n    --save_ranking_to $EMBEDDING_OUTPUT_DIR\u002Frun.dev.txt\n```\n\nThe output file is in the format of `\u003Cquery_id> \u003Cpassage_id> \u003Cscore>` in each line.\n\n\u003C\u002Fdetails>\n\n## Examples\n+ [Unified multi-modal and multilingual retrieval](.\u002Fexamples\u002Fmultimodal)\n+ [vLLM encoding and retrieval](.\u002Fexamples\u002Fexample_repllama_vllm.md)\n\n## Citation\nIf you find Tevatron helpful, please consider citing our [paper](https:\u002F\u002Farxiv.org\u002Fabs\u002F2203.05765).\n```bibtex\n@article{Gao2022TevatronAE,\n  title={Tevatron: An Efficient and Flexible Toolkit for Dense Retrieval},\n  author={Luyu Gao and Xueguang Ma and Jimmy J. Lin and Jamie Callan},\n  journal={ArXiv},\n  year={2022},\n  volume={abs\u002F2203.05765}\n}\n```\n\n```bibtex\n@article{ma2025tevatron,\n  title={Tevatron 2.0: Unified Document Retrieval Toolkit across Scale, Language, and Modality},\n  author={Ma, Xueguang and Gao, Luyu and Zhuang, Shengyao and Zhan, Jiaqi Samantha and Callan, Jamie and Lin, Jimmy},\n  journal={arXiv preprint arXiv:2505.02466},\n  year={2025}\n}\n```\n\n\n## Contacts\nIf you have a toolkit specific question, feel free to open an issue. \n\nYou can also reach out to us for general comments\u002Fsuggestions\u002Fquestions through email.\n- Luyu Gao luyug@cs.cmu.edu\n- Xueguang Ma x93ma@uwaterloo.ca\n- Shengyao Zhuang shengyaozhuang@gmail.com\n\n\n## Acknowledgement\n\n* We thank all the contributors of dependency libraries.\n* We thank Google's [TPU research cloud](https:\u002F\u002Fsites.research.google\u002Ftrc\u002Fabout\u002F) for providing TPU resources.\n","# Tevatron V2.0\n\n\u003Cdiv align=\"center\">\n\u003Ca href=\"https:\u002F\u002Farxiv.org\u002Fabs\u002F2203.05765\" target=\"_blank\">\u003Cimg src=https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FarXiv-b5212f.svg?logo=arxiv>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fhuggingface.co\u002FTevatron\" target=\"_blank\">\u003Cimg src=https:\u002F\u002Fimg.shields.io\u002Fbadge\u002F%F0%9F%A4%97%20HuggingFace%20Datasets-27b3b4.svg>\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fopensource.org\u002Flicense\u002Fapache-2-0\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fstatic\u002Fv1?label=License&message=Apache-2.0&color=red\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fpepy.tech\u002Fprojects\u002Ftevatron\">\u003Cimg src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftexttron_tevatron_readme_a90e877c9891.png\" alt=\"PyPI Downloads\">\u003C\u002Fa>\n\u003Ca href=\"https:\u002F\u002Fstar-history.com\u002F#texttron\u002Ftevatron\"> \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fstars\u002Ftexttron\u002Ftevatron?style=social\" alt=\"GitHub stars\"> \u003C\u002Fa>\n\u003C!--   -->\n\u003C\u002Fdiv>\n\nTevatron：跨规模、跨语言、跨模态的统一文档检索工具包。\n\n> Tevatron v1 中的部分功能尚未迁移到 Tevatron v2.0。我们正在努力推进这一工作。\n> 如果您需要 Tevatron v1 的功能，请拉取 [v1 分支](https:\u002F\u002Fgithub.com\u002Ftexttron\u002Ftevatron\u002Ftree\u002Ftevatron-v1)。\n\n## 特性\n- 在 GPU 和 TPU 上训练数十亿参数级别的 LLM 神经检索器。\n- 使用 LoRA 进行参数高效的微调。\n- 集成 vLLM、DeepSpeed、FlashAttention、梯度累积等高效训练和推理技术。\n- 自包含的 [HuggingFace 数据集](https:\u002F\u002Fhuggingface.co\u002FTevatron)，适用于多模态和多语言的神经检索及开放域问答任务。\n- 直接从 HuggingFace 加载并微调当前最优的预训练模型（如 BGE-Embedding、Instruct-E5）。\n\n## 安装\n\n\u003Cdetails>\u003Csummary>\u003Cb>PyTorch (GPU)\u003C\u002Fb>\u003C\u002Fsummary>\n\n0. 克隆仓库。\n1. 根据您的 CUDA 版本，从 [PyTorch](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F) 安装 PyTorch。\n2. 安装依赖项和 Tevatron。\n```bash\npip install transformers datasets peft\npip install deepspeed accelerate\npip install faiss-cpu\npip install -e .\n```\n\n\n\u003C\u002Fdetails>\n\u003Cdetails>\u003Csummary>\u003Cb>JAX (TPU)\u003C\u002Fb>\u003C\u002Fsummary>\n\n0. 克隆仓库。\n1. 按照 [官方指南](https:\u002F\u002Fjax.readthedocs.io\u002Fen\u002Flatest\u002Finstallation.html#pip-installation-google-cloud-tpu) 安装 JAX。\n2. 安装依赖项。\n```bash\npip install transformers datasets\npip install flax optax\n```\n3. 安装 Magix 和 GradCache。\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fluyug\u002Fmagix.git\ncd magix && pip install -e . && cd ..\ngit clone https:\u002F\u002Fgithub.com\u002Fluyug\u002FGradCache.git\ncd GradCache && pip install -e . && cd ..\n```\n\n4. 安装 Tevatron。\n```bash\npip install -e .\n```\n\n\u003C\u002Fdetails>\n\u003Cdetails>\u003Csummary>\u003Cb>JAX (GPU)\u003C\u002Fb>\u003C\u002Fsummary>\n\n要在 GPU 上运行 Tevatron 的 JAX 实现，我们建议使用 NVIDIA 提供的 jax-toolbox [jax container](https:\u002F\u002Fgithub.com\u002FNVIDIA\u002FJAX-Toolbox\u002Fpkgs\u002Fcontainer\u002Fjax) 镜像。\n\n以下是基于 jax 容器搭建 Tevatron 的 Dockerfile 示例。\n```Dockerfile\nFROM ghcr.io\u002Fnvidia\u002Fjax:jax-2024-03-08\n\nRUN apt-get update && \\\n    apt-get install -y --no-install-recommends python3-pip && \\\n    apt-get clean && \\\n    rm -rf \u002Fvar\u002Flib\u002Fapt\u002Flists\u002F* && \\\n    pip install --no-cache-dir transformers sentencepiece simple_parsing datasets orbax==0.4.8 && \\\n    pip install --no-cache-dir torch --index-url https:\u002F\u002Fdownload.pytorch.org\u002Fwhl\u002Fcpu\n\nRUN git clone https:\u002F\u002Fgithub.com\u002Fluyug\u002Fmagix.git && \\\n    cd magix && pip install -e . && cd .. && \\\n    git clone https:\u002F\u002Fgithub.com\u002Fluyug\u002FGradCache.git \\\n    cd GradCache && pip install -e . && cd .. \\\n    git clone https:\u002F\u002Fgithub.com\u002Ftexttron\u002Ftevatron.git && \\\n    cd tevatron && pip install -e .\n```\n\n\n\n\n\u003C\u002Fdetails>\n\n\n\n## Tevatron 101\n在本示例中，我们将演示如何使用 Tevatron 对 Mistral-7B 模型在 MSMARCO passage 数据集上进行 LoRA 微调。经过简单训练后，得到的 LLM Retriever 在 MS MARCO 开发集上的 MRR@10 预计可达 42.3。\n\n\u003Cdetails>\u003Csummary>\u003Cb>数据准备\u003C\u002Fb>\u003C\u002Fsummary>\n\nTevatron 接受 `jsonl` 格式的训练或推理数据，每行是一个 JSON 对象，格式如下：\n### 1. 训练数据\n```json\n{\n   \"query_id\": \"\u003Cquery id>\",\n   \"query_text\": \"\u003Cquery text>\",\n   \"query_image\": \"\u003Cquery image>\",\n   \"positive_document_ids\": [\"\u003Cpassage id>\", ...],\n   \"negative_document_ids\": [\"\u003Cpassage id>\", ...],\n}\n```\n其中，`positive_passages` 是与查询相关联的标注相关段落，而 `negative_passages` 通常是来自检索系统（如 BM25、DPR）顶部结果中的不相关（硬负样本）段落。对于 QA 数据集，还可以包含 `answers` 等其他字段。\n\n#### 2. 语料数据\n```json\n{\n   \"docid\": \"\u003Cdocument id>\",\n   \"document_text\": \"\u003Cdocument text>\",\n   \"document_image\": \"\u003Cdocument image>\",\n}\n```\n其中，每行代表语料库中的一个文档。\n\n需要注意的是，训练和语料数据中的图像字段是可选的，可以省略（即纯文本模态的检索）。\n\n### 自包含数据集\nTevatron 自带了几种常用的神经检索数据集。\n（通过 [HuggingFace](https:\u002F\u002Fhuggingface.co\u002FTevatron) 提供）。\n这些数据集可以在训练和编码过程中通过设置 `--dataset_name \u003Chgf dataset name>` 自动下载。\n\n在本示例中，我们将使用自包含数据集 `Tevatron\u002Fmsmarco-passage-aug` 进行训练，其硬负样本是从 BM25 前 200 名和 CoCondenser 前 200 名结果中混合采样的。\n\n\u003C\u002Fdetails>\n\n\n\u003Cdetails>\u003Csummary>\u003Cb>使用 PyTorch (GPU) 运行\u003C\u002Fb>\u003C\u002Fsummary>\n\n### 训练\n\n```bash\ndeepspeed --include localhost:0,1,2,3 --master_port 60000 --module tevatron.retriever.driver.train \\\n  --deepspeed deepspeed\u002Fds_zero3_config.json \\\n  --output_dir retriever-mistral \\\n  --model_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n  --lora \\\n  --lora_target_modules q_proj,k_proj,v_proj,o_proj,down_proj,up_proj,gate_proj \\\n  --save_steps 50 \\\n  --dataset_name Tevatron\u002Fmsmarco-passage-aug \\\n  --query_prefix \"Query: \" \\\n  --passage_prefix \"Passage: \" \\\n  --bf16 \\\n  --pooling eos \\\n  --append_eos_token \\\n  --normalize \\\n  --temperature 0.01 \\\n  --per_device_train_batch_size 8 \\\n  --gradient_checkpointing \\\n  --train_group_size 16 \\\n  --learning_rate 1e-4 \\\n  --query_max_len 32 \\\n  --passage_max_len 156 \\\n  --num_train_epochs 1 \\\n  --logging_steps 10 \\\n  --overwrite_output_dir \\\n  --gradient_accumulation_steps 4\n```\n\n每次查询处理的段落数：8×4×16 = 512\n\n每次更新的查询数：8×4×4 = 128\n\n上述训练配置在 4 张 A6000 GPU 上大约需要 70 小时。\n\n如果仅使用 1 张 A100 GPU，则相当于约 110 小时的训练时间。\n\n### 编码\n\n#### 查询编码\n```bash\nEMBEDDING_OUTPUT_DIR=\u003C用于保存查询嵌入的文件夹>\nCUDA_VISIBLE_DEVICES=4 python -m tevatron.retriever.driver.encode \\\n  --output_dir=temp \\\n  --model_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n  --lora_name_or_path retriever-mistral \\\n  --lora \\\n  --query_prefix \"Query: \" \\\n  --passage_prefix \"Passage: \" \\\n  --bf16 \\\n  --pooling eos \\\n  --append_eos_token \\\n  --normalize \\\n  --encode_is_query \\\n  --per_device_eval_batch_size 128 \\\n  --query_max_len 32 \\\n  --passage_max_len 156 \\\n  --dataset_name Tevatron\u002Fmsmarco-passage \\\n  --dataset_split dev \\\n  --encode_output_path $EMBEDDING_OUTPUT_DIR\u002Fquery-dev.pkl\n```\n\n#### 语料库编码\n```bash\nEMBEDDING_OUTPUT_DIR=\u003C用于保存查询嵌入的文件夹>\nfor s in 0 1 2 3\ndo\ngpuid=$s\nCUDA_VISIBLE_DEVICES=$gpuid python -m tevatron.retriever.driver.encode \\\n  --output_dir=temp \\\n  --model_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n  --lora_name_or_path retriever-mistral \\\n  --lora \\\n  --query_prefix \"Query: \" \\\n  --passage_prefix \"Passage: \" \\\n  --bf16 \\\n  --pooling eos \\\n  --append_eos_token \\\n  --normalize \\\n  --per_device_eval_batch_size 128 \\\n  --query_max_len 32 \\\n  --passage_max_len 156 \\\n  --dataset_name Tevatron\u002Fmsmarco-passage-corpus \\\n  --dataset_number_of_shards 4 \\\n  --dataset_shard_index ${s} \\\n  --encode_output_path $EMBEDDING_OUTPUT_DIR\u002Fcorpus.${s}.pkl\ndone\n```\n> 在命令末尾添加 `&` 可以在后台并行运行。\n\n### 检索\n```bash\nset -f && python -m tevatron.retriever.driver.search \\\n    --query_reps $EMBEDDING_OUTPUT_DIR\u002Fquery-dev.pkl \\\n    --passage_reps $EMBEDDING_OUTPUT_DIR\u002Fcorpus*.pkl \\\n    --depth 1000 \\\n    --batch_size 64 \\\n    --save_text \\\n    --save_ranking_to $EMBEDDING_OUTPUT_DIR\u002Frun.dev.txt\n```\n\n输出文件的格式为每行 `\u003Cquery_id> \u003Cpassage_id> \u003Cscore>`。\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\u003Csummary>\u003Cb>使用 JAX（TPU\u002FGPU）运行\u003C\u002Fb>\u003C\u002Fsummary>\n\n### 训练\n\n> 对于 GPU 训练，设置 `XLA_PYTHON_CLIENT_MEM_FRACTION=.95`，并且如果已安装 TransformersEngine，则确保查询和段落长度是 64 的倍数。\n\n```bash\npython -m tevatron.tevax.experimental.mp.train_lora  \\\n   --checkpoint_dir retriever-mistral-jax \\\n   --train_file Tevatron\u002Fmsmarco-passage-aug \\\n   --model_name mistralai\u002FMistral-7B-v0.1 \\\n   --model_type mistral \\\n   --batch_size 128 \\\n   --num_target_passages 16 \\\n   --learning_rate 1e-4 \\\n   --seed 12345 \\\n   --mesh_shape 1 -1 \\\n   --weight_decay 0.00001 \\\n   --num_epochs 1 \\\n   --max_query_length 64 \\\n   --max_passage_length 128 \\\n   --pooling eos \\\n   --scale_by_dim True \\\n   --grad_cache \\\n   --passage_num_chunks 32 \\\n   --query_num_chunks 4\n```\n\n每个查询的批次数：128x16 = 2048\n\n每次更新的查询数量：128\n\n上述训练设置在 v4-8 TPU VM 上大约需要 35 小时。\n\n在 1xA100 GPU 上进行等效训练大约需要 80 小时。\n\n### 编码\n\n#### 查询编码\n```bash\npython -m tevatron.tevax.experimental.mp.encode  \\\n   --model_type mistral \\\n   --model_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n   --model_config_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n   --tokenizer_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n   --dataset_name_or_path Tevatron\u002Fmsmarco-passage \\\n   --split dev \\\n   --output_dir $EMBEDDING_OUTPUT_DIR\u002Fquery-embedding \\\n   --batch_size 32 \\\n   --input_type query \\\n   --max_seq_length 64 \\\n   --mesh_shape 1 -1 \\\n   --lora retriever-mistral-jax\u002Flora \\\n   --scale_by_dim\n```\n\n#### 语料库编码\n```bash\npython -m tevatron.tevax.experimental.mp.encode  \\\n   --model_type mistral \\\n   --model_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n   --model_config_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n   --tokenizer_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n   --dataset_name_or_path Tevatron\u002Fmsmarco-passage-corpus \\\n   --output_dir $EMBEDDING_OUTPUT_DIR\u002Fcorpus-embedding \\\n   --batch_size 32 \\\n   --input_type passage \\\n   --max_seq_length 128 \\\n   --mesh_shape 1 -1 \\\n   --lora retriever-mistral-jax\u002Flora \\\n   --scale_by_dim\n```\n\n### 检索\n```bash\nset -f && python -m tevatron.retriever.driver.search \\\n    --query_reps $EMBEDDING_OUTPUT_DIR\u002Fquery-embedding\u002F*.pkl \\\n    --passage_reps $EMBEDDING_OUTPUT_DIR\u002Fcorpus-embedding\u002F*.pkl \\\n    --depth 1000 \\\n    --batch_size 64 \\\n    --save_text \\\n    --save_ranking_to $EMBEDDING_OUTPUT_DIR\u002Frun.dev.txt\n```\n\n输出文件的格式为每行 `\u003Cquery_id> \u003Cpassage_id> \u003Cscore>`。\n\n\u003C\u002Fdetails>\n\n## 示例\n+ [统一的多模态和多语言检索](.\u002Fexamples\u002Fmultimodal)\n+ [vLLM 编码与检索](.\u002Fexamples\u002Fexample_repllama_vllm.md)\n\n## 引用\n如果您觉得 Tevatron 有用，请考虑引用我们的论文：[arXiv:2203.05765](https:\u002F\u002Farxiv.org\u002Fabs\u002F2203.05765)。\n```bibtex\n@article{Gao2022TevatronAE,\n  title={Tevatron: 一种高效灵活的密集检索工具包},\n  author={Luyu Gao 和 Xueguang Ma 和 Jimmy J. Lin 和 Jamie Callan},\n  journal={ArXiv},\n  year={2022},\n  volume={abs\u002F2203.05765}\n}\n```\n\n```bibtex\n@article{ma2025tevatron,\n  title={Tevatron 2.0：跨规模、语言和模态的统一文档检索工具包},\n  author={Ma, Xueguang 和 Gao, Luyu 和 Zhuang, Shengyao 和 Zhan, Jiaqi Samantha 和 Callan, Jamie 和 Lin, Jimmy},\n  journal={arXiv 预印本 arXiv:2505.02466},\n  year={2025}\n}\n```\n\n\n## 联系方式\n如果您对工具包有任何具体问题，欢迎随时提交问题。\n\n您也可以通过电子邮件与我们联系，提出一般性意见、建议或问题：\n- Luyu Gao luyug@cs.cmu.edu\n- Xueguang Ma x93ma@uwaterloo.ca\n- Shengyao Zhuang shengyaozhuang@gmail.com\n\n\n## 致谢\n\n* 我们感谢所有依赖库的贡献者。\n* 我们感谢 Google 的 [TPU 研究云](https:\u002F\u002Fsites.research.google\u002Ftrc\u002Fabout\u002F) 提供的 TPU 资源。","# Tevatron V2.0 快速上手指南\n\nTevatron 是一个统一的文档检索工具包，支持跨规模、多语言和多模态的神经检索任务。它允许用户在 GPU 和 TPU 上训练十亿级参数的 LLM 检索器，并支持 LoRA 参数高效微调。\n\n## 环境准备\n\n### 系统要求\n- **操作系统**: Linux (推荐 Ubuntu)\n- **硬件**: \n  - **GPU 方案**: 支持 CUDA 的 NVIDIA GPU (建议显存 24GB+ 以运行大模型)\n  - **TPU 方案**: Google Cloud TPU 或兼容环境\n- **软件依赖**:\n  - Python 3.8+\n  - PyTorch (GPU 方案) 或 JAX (TPU\u002FGPU 方案)\n  - CUDA Toolkit (需与 PyTorch 版本匹配)\n\n### 前置依赖\n在开始之前，请确保已安装对应的深度学习框架：\n- **PyTorch 用户**: 请访问 [PyTorch 官网](https:\u002F\u002Fpytorch.org\u002Fget-started\u002Flocally\u002F) 根据CUDA版本安装。\n- **JAX 用户**: 请参考 [JAX 官方安装指南](https:\u002F\u002Fjax.readthedocs.io\u002Fen\u002Flatest\u002Finstallation.html)。\n\n> **国内加速建议**: 安装 Python 依赖时，推荐使用清华或阿里镜像源以提升下载速度。\n> 例如：`pip install -i https:\u002F\u002Fpypi.tuna.tsinghua.edu.cn\u002Fsimple \u003Cpackage_name>`\n\n---\n\n## 安装步骤\n\n### 方案 A: PyTorch (GPU)\n\n1. 克隆仓库：\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Ftexttron\u002Ftevatron.git\ncd tevatron\n```\n\n2. 安装基础依赖和 Tevatron：\n```bash\npip install transformers datasets peft\npip install deepspeed accelerate\npip install faiss-cpu\npip install -e .\n```\n\n### 方案 B: JAX (TPU\u002FGPU)\n\n1. 克隆仓库并安装基础依赖：\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Ftexttron\u002Ftevatron.git\ncd tevatron\npip install transformers datasets\npip install flax optax\n```\n\n2. 安装 Magix 和 GradCache (JAX 必需组件)：\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fluyug\u002Fmagix.git\ncd magix && pip install -e . && cd ..\n\ngit clone https:\u002F\u002Fgithub.com\u002Fluyug\u002FGradCache.git\ncd GradCache && pip install -e . && cd ..\n```\n\n3. 安装 Tevatron：\n```bash\npip install -e .\n```\n\n> **注意**: 若在 GPU 上运行 JAX 版本，建议使用 NVIDIA 提供的 `jax-toolbox` Docker 镜像以获得最佳兼容性。\n\n---\n\n## 基本使用\n\n以下示例演示如何使用 **PyTorch (GPU)** 配合 **LoRA** 微调 `Mistral-7B` 模型，并在 MSMARCO 数据集上进行检索。\n\n### 1. 数据准备\nTevatron 支持直接从 HuggingFace 加载内置数据集。本例使用 `Tevatron\u002Fmsmarco-passage-aug`，无需手动下载。\n数据格式通常为 `jsonl`，包含 `query_text`, `positive_document_ids`, `negative_document_ids` 等字段。\n\n### 2. 模型训练 (Training)\n使用 DeepSpeed Zero3 进行分布式训练，开启 LoRA 微调。\n\n```bash\ndeepspeed --include localhost:0,1,2,3 --master_port 60000 --module tevatron.retriever.driver.train \\\n  --deepspeed deepspeed\u002Fds_zero3_config.json \\\n  --output_dir retriever-mistral \\\n  --model_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n  --lora \\\n  --lora_target_modules q_proj,k_proj,v_proj,o_proj,down_proj,up_proj,gate_proj \\\n  --save_steps 50 \\\n  --dataset_name Tevatron\u002Fmsmarco-passage-aug \\\n  --query_prefix \"Query: \" \\\n  --passage_prefix \"Passage: \" \\\n  --bf16 \\\n  --pooling eos \\\n  --append_eos_token \\\n  --normalize \\\n  --temperature 0.01 \\\n  --per_device_train_batch_size 8 \\\n  --gradient_checkpointing \\\n  --train_group_size 16 \\\n  --learning_rate 1e-4 \\\n  --query_max_len 32 \\\n  --passage_max_len 156 \\\n  --num_train_epochs 1 \\\n  --logging_steps 10 \\\n  --overwrite_output_dir \\\n  --gradient_accumulation_steps 4\n```\n*注：上述配置在 4x A6000 GPU 上约需 70 小时。*\n\n### 3. 向量编码 (Encoding)\n训练完成后，分别对查询（Query）和文档库（Corpus）进行编码。\n\n**编码查询 (Query):**\n```bash\nEMBEDDING_OUTPUT_DIR=.\u002Fembeddings\nmkdir -p $EMBEDDING_OUTPUT_DIR\n\npython -m tevatron.retriever.driver.encode \\\n  --output_dir=temp \\\n  --model_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n  --lora_name_or_path retriever-mistral \\\n  --lora \\\n  --query_prefix \"Query: \" \\\n  --passage_prefix \"Passage: \" \\\n  --bf16 \\\n  --pooling eos \\\n  --append_eos_token \\\n  --normalize \\\n  --encode_is_query \\\n  --per_device_eval_batch_size 128 \\\n  --query_max_len 32 \\\n  --passage_max_len 156 \\\n  --dataset_name Tevatron\u002Fmsmarco-passage \\\n  --dataset_split dev \\\n  --encode_output_path $EMBEDDING_OUTPUT_DIR\u002Fquery-dev.pkl\n```\n\n**编码文档库 (Corpus):**\n(支持多卡并行，以下为单卡示例，多卡可循环执行)\n```bash\nCUDA_VISIBLE_DEVICES=0 python -m tevatron.retriever.driver.encode \\\n  --output_dir=temp \\\n  --model_name_or_path mistralai\u002FMistral-7B-v0.1 \\\n  --lora_name_or_path retriever-mistral \\\n  --lora \\\n  --query_prefix \"Query: \" \\\n  --passage_prefix \"Passage: \" \\\n  --bf16 \\\n  --pooling eos \\\n  --append_eos_token \\\n  --normalize \\\n  --per_device_eval_batch_size 128 \\\n  --query_max_len 32 \\\n  --passage_max_len 156 \\\n  --dataset_name Tevatron\u002Fmsmarco-passage-corpus \\\n  --dataset_number_of_shards 1 \\\n  --dataset_shard_index 0 \\\n  --encode_output_path $EMBEDDING_OUTPUT_DIR\u002Fcorpus.0.pkl\n```\n\n### 4. 检索 (Retrieval)\n利用生成的向量文件进行相似度搜索并输出排序结果。\n\n```bash\nset -f && python -m tevatron.retriever.driver.search \\\n    --query_reps $EMBEDDING_OUTPUT_DIR\u002Fquery-dev.pkl \\\n    --passage_reps $EMBEDDING_OUTPUT_DIR\u002Fcorpus*.pkl \\\n    --depth 1000 \\\n    --batch_size 64 \\\n    --save_text \\\n    --save_ranking_to $EMBEDDING_OUTPUT_DIR\u002Frun.dev.txt\n```\n\n输出文件 `run.dev.txt` 每行格式为：`\u003Cquery_id> \u003Cpassage_id> \u003Cscore>`。","某大型跨境电商团队正致力于构建一个支持中、英、西三语的智能商品检索系统，需从亿级多模态商品库中精准匹配用户查询。\n\n### 没有 tevatron 时\n- **训练门槛极高**：想要在 GPU 集群上训练十亿参数级别的神经检索模型，需自行搭建复杂的分布式训练框架，开发周期长达数月。\n- **多语言适配困难**：缺乏统一的多语言数据集接口，团队需花费大量精力清洗和对齐不同语种的商品描述数据，且难以复用现有预训练模型。\n- **资源消耗巨大**：全量微调大模型导致显存爆炸，不得不缩减模型规模或降低批次大小，直接牺牲了检索准确率。\n- **技术栈割裂**：无法灵活整合 FlashAttention、DeepSpeed 等加速技术，推理延迟高，难以满足实时搜索需求。\n\n### 使用 tevatron 后\n- **开箱即用的大规模训练**：tevatron 原生支持在 GPU\u002FTPU 上训练十亿级模型，结合 LoRA 参数高效微调，几天内即可完成 Mistral-7B 等大模型的检索能力适配。\n- **统一的多模态多语言支持**：直接加载 HuggingFace 上的多语言数据集和 BGE、Instruct-E5 等 SOTA 模型，轻松实现中英西三语商品库的统一索引与检索。\n- **极致性能优化**：内置集成 vLLM、FlashAttention 及梯度累积技术，在显著降低显存占用的同时，将检索响应速度提升数倍。\n- **灵活的架构扩展**：一套代码即可切换 PyTorch 或 JAX 后端，无缝对接现有云基础设施，快速迭代实验策略。\n\ntevatron 通过统一的工具链打破了规模、语言和模态的壁垒，让企业能以最低成本构建工业级的大模型检索系统。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Ftexttron_tevatron_634d6168.png","texttron","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Ftexttron_7ef5b1f6.png","",null,"https:\u002F\u002Fgithub.com\u002Ftexttron",[78,82],{"name":79,"color":80,"percentage":81},"Python","#3572A5",98.1,{"name":83,"color":84,"percentage":85},"Shell","#89e051",1.9,733,126,"2026-04-01T04:03:56","Apache-2.0","Linux","PyTorch 版本：需要 NVIDIA GPU（示例使用 A6000, A100），支持 CUDA（需根据 PyTorch 版本安装对应 CUDA）；JAX 版本：支持 NVIDIA GPU（推荐使用 NVIDIA jax-toolbox 容器）或 Google Cloud TPU。","未说明",{"notes":94,"python":92,"dependencies":95},"该工具提供 PyTorch (GPU) 和 JAX (TPU\u002FGPU) 两种实现。PyTorch 版本需手动安装与 CUDA 版本匹配的 PyTorch；JAX GPU 版本强烈建议使用 NVIDIA 提供的 Docker 容器环境。训练十亿参数模型（如 Mistral-7B）时，示例显示在 4x A6000 上需约 70 小时，单卡 A100 需约 110 小时，建议使用多卡并行并配合 DeepSpeed ZeRO-3 或 Gradient Checkpointing 以节省显存。部分 v1 功能尚未迁移至 v2.0。",[96,97,98,99,100,101,102,103,104,105],"torch","transformers","datasets","peft","deepspeed","accelerate","faiss-cpu","jax","flax","optax",[107,35,14],"其他",[109,110,111,112,113,114,103,104],"pytorch","transformer","dense-retrieval","dpr","information-retrieval","question-answering","2026-03-27T02:49:30.150509","2026-04-20T04:06:02.286311",[118,123,128,133,138,143],{"id":119,"question_zh":120,"answer_zh":121,"source_url":122},43461,"如何复现论文中的模型性能（如 RepLLaMA）？如果结果不一致该怎么办？","结果差异通常由随机种子（random seeds）引起。请检查超参数设置是否与原始实验一致，例如：\n1. 确认批次大小设置：原始实验在 16 个 V100 GPU 上每设备批次大小为 2，若使用 8 个 A100，需确保总批次大小和跨设备负采样（--negatives_x_device）设置等效。\n2. 尝试调整 LoRA 秩（lora_r），有用户反馈设置 lora_r=32 后结果更接近原始数据（dev mrr@10: 41.6, dl19 ndcg@10: 74.6）。\n3. 确保训练脚本中的其他参数（如学习率、最大长度等）与官方提供的脚本完全一致。","https:\u002F\u002Fgithub.com\u002Ftexttron\u002Ftevatron\u002Fissues\u002F129",{"id":124,"question_zh":125,"answer_zh":126,"source_url":127},43462,"如何使用自定义数据集进行训练？遇到缓存空间不足报错怎么办？","可以通过指定 `--dataset_files` 参数加载自定义的 JSONL 文件。如果在加载数据集时遇到报错（通常涉及 pyarrow 转换），主要原因是 Huggingface 数据集会先将 JSON 转换为 pyarrow 文件并存储在默认缓存目录（通常是 `\u002Froot\u002F.cache`），若该目录空间不足会导致失败。\n解决方案：在加载数据集时更改 `cache_dir` 到一个空间更大的目录。例如在代码或配置中指定新的缓存路径，即可解决该问题。","https:\u002F\u002Fgithub.com\u002Ftexttron\u002Ftevatron\u002Fissues\u002F84",{"id":129,"question_zh":130,"answer_zh":131,"source_url":132},43463,"如何复现 NQ 数据集上的结果（MRR@5=84.3）？需要注意哪些细节？","为了复现 NQ 数据集上的结果，必须严格遵循原始 DPR（Dense Passage Retriever）工具的指令设置，因为作者特意使用了 DPR 工具包以确保结果可比性。关键配置包括：\n1. 使用 8 个 GPU。\n2. 每设备批次大小（batch size per device）设为 16。\n3. 使用 DDP（Distributed Data Parallel）训练模式。\n4. 确保硬负样本挖掘（hard-negative mining）的细节与原始设置一致。任何偏离都可能导致结果不稳定。","https:\u002F\u002Fgithub.com\u002Ftexttron\u002Ftevatron\u002Fissues\u002F10",{"id":134,"question_zh":135,"answer_zh":136,"source_url":137},43464,"训练 DSE 模型时遇到 'Unsupported model class' 错误如何解决？","该错误通常发生在保存检查点时，提示不支持当前的模型类（特别是当结合 PEFT\u002FLoRA 使用时）。\n解决方案：\n1. 确保使用正确的驱动脚本和参数组合。尝试使用 `--module tevatron.retriever.driver.train` 方式运行，并配合 DeepSpeed 配置（如 `ds_zero3_config.json`）。\n2. 检查命令中是否包含了必要的参数，如 `--lora`、`--pooling eos`、`--normalize` 等。\n3. 参考以下成功运行的命令结构：\n`deepspeed --include localhost:0,1,2,3 --master_port 60000 --module tevatron.retriever.driver.train --deepspeed ds_zero3_config.json --output_dir [输出目录] --model_name_or_path [模型路径] --lora --dataset_name [数据集] ...`\n确保环境中的 transformers 和 tevatron 版本兼容。","https:\u002F\u002Fgithub.com\u002Ftexttron\u002Ftevatron\u002Fissues\u002F175",{"id":139,"question_zh":140,"answer_zh":141,"source_url":142},43465,"运行 coCondenser MS-MARCO 示例时在训练阶段报错 'At least one data file must be specified' 是什么原因？","此错误通常发生在 datasets 库尝试加载本地 JSON 文件但未正确找到文件或文件格式不符合预期时。\n解决方法：\n1. 检查 `--dataset_files` 参数指向的文件路径是否正确，确保文件存在且可读。\n2. 确认 JSONL 文件格式正确，每一行都是一个合法的 JSON 对象。\n3. 如果是使用旧版本的 datasets 库（如 1.9.0），可能存在兼容性问题，建议升级 datasets 库或检查 tevatron 对特定版本 datasets 的要求。\n4. 确保在调用 `datasets.load_dataset` 时，如果是本地文件，必须显式提供文件路径列表。","https:\u002F\u002Fgithub.com\u002Ftexttron\u002Ftevatron\u002Fissues\u002F15",{"id":144,"question_zh":145,"answer_zh":146,"source_url":127},43466,"在自定义数据训练时，如何避免 Huggingface 数据集转换过程中的内存或磁盘溢出？","Huggingface 的 datasets 库在加载自定义 JSON\u002FJSONL 数据时，默认会将其转换为 Arrow 格式并缓存在本地（默认为 `~\u002F.cache\u002Fhuggingface`）。如果数据量较大，容易导致磁盘空间不足。\n具体解决步骤：\n1. 不要依赖默认缓存路径。\n2. 在代码中加载数据集时，显式设置 `cache_dir` 参数到一个拥有充足空间的磁盘目录。\n3. 示例逻辑：在调用 `load_dataset` 时传入 `cache_dir='\u002Fpath\u002Fto\u002Flarge\u002Fdisk\u002Fcache'`。\n这样可以避免根目录空间爆满导致的训练中断。",[148],{"id":149,"version":150,"summary_zh":151,"released_at":152},343083,"0.1.0","https:\u002F\u002Fdl.acm.org\u002Fdoi\u002Fabs\u002F10.1145\u002F3539618.3591805","2023-12-10T20:34:40"]