手把手github多模态大模型项目复现流程（小白可用）

Ne0inhk

24 Mar 2026 — 10 min read

写在前面：大家复现项目时可以把readme 丢给GPT 先了解整体需要做的流程框架，在复现项目之前先仔细阅读readme、分析项目框架，以下是我复现项目的相关流程以及遇到的问题

1. autodl租用

这里建议直接在autodl上租一个GPU进行环境配置进行学生认证刚开始使用无卡启动先搭好环境后再直接开机

Autodl使用教程：AutoDL使用教程：1）创建实例 2）配置环境+上传数据 3）PyCharm2021.3专业版下载安装与远程连接完整步骤 4）实时查看tensorboard曲线情况

这里，我选择基础镜像--miniconda 3.10版本

pycharm镜像是官方已经把 PyTorch、CUDA、cuDNN 等常用深度学习工具都安装并配置好了，版本也是互相匹配的；复现论文代码时候我们一般选择miniconda，里面只有一个最小化的 Conda 环境管理器，其他所有东西都需要自己从头安装。

配置好之后和pycharm/vscode进行远程连接，教程见PyCharm专业版连接AutoDl详细教程（手把手教程！！）以及一些操作小知识（重点），和再开机连接教程！！！

2. 环境配置 (Installation)

# Clone this repo with submodules
git clone --recurse-submodules https://github.com/EvolvingLMMs-Lab/multimodal-search-r1.git
cd multimodal-search-r1
# Init Conda Env
conda create -n mmsearch_r1 python==3.10 -y
conda activate mmsearch_r1
# Install Dependencies
pip3 install -e ./verl
pip3 install vllm==0.8.2
pip3 install transformers==4.51.0
pip3 install flash-attn==2.7.4.post1
# Init wandb
pip3 install wandb
export WANDB_API_KEY="XXX"
wandb login $WANDB_API_KEY

解析如下：

1.下载代码到本地

这些环境配置代码需要了解否则后续报错修改时候不方便

git clone --recurse-submodules ...
- 关键点：--recurse-submodules 这个参数很重要。它说明这个项目依赖了其他的 Git 仓库（子模块），使用这个参数可以确保把所有依赖的代码一并下载下来。

代码下载有两个方式

一是在github上code直接下载zip到本地

二是readme上一般有克隆指令

# Clone this repo with submodules git clone --recurse-submodules https://github.com/EvolvingLMMs-Lab/multimodal-search-r1.git

2.conda指令

conda create -n mmsearch_r1 python==3.10 -y
- 创建一个名为 mmsearch_r1 的独立 Python 环境，并且严格指定了 Python 版本为 3.10。

这里会报错CommandNotFound

conda activate执行之前需要初始化conda脚本，依次执行下面的代码,然后关掉终端重新打开一个

conda init bash

source ~/.bashrc

conda activate mmsearch_r1

配好的环境用conda en list查看一下如下：

3.安装依赖

pip3 install -e ./verl
- 关键点：-e 参数表示以“可编辑模式”安装。verl 是这个项目自带的一个核心本地代码包。用这种模式安装后，如果您修改了 verl 文件夹里的源代码，会立刻生效，无需重新安装。
pip3 install vllm==0.8.2, transformers==4.51.0, flash-attn==2.7.4.post1
- 关键点：这里严格指定了三个核心库的版本。这是因为AI领域的库更新换代非常快，不同版本之间可能完全不兼容。

遇见报错：

解决方法：

手动下载并安装预编译的 wheel

因为 flash-attn 的源码编译非常复杂，建议直接使用官方提供的 .whl 文件。

步骤：

访问 flash-attn releases 页面。
找到 v2.7.4.post1 版本。
下载对应你系统的 wheel 文件。

这里我的cuda为11.8 v2.7.4.post1 都是cu12 所以我选择了v2.7.3.post1

4.安装 wandb（用于可视化和日志）

wandb login ...
- wandb (Weights & Biases) 是一个用于记录和可视化机器学习实验过程的工具。您需要去 wandb.ai 网站注册一个账号，获取您自己的 API_KEY，然后替换掉命令中的 "XXX"。

2. 核心功能：多模态搜索工具的实现

这是整个项目的灵魂。项目定义了两种搜索工具。

图片搜索工具 (Image Search Tool)：
- 技术：仅使用 SerpAPI。
- 流程：模型给出一个图片（比如URL），这个工具通过 SerpAPI 查找视觉上相似的网页，并返回这些网页的缩略图和标题。
- SerpAPI 是一个付费服务，它能让您通过API访问Google等搜索引擎的结果。

文本搜索工具 (Text Search Tool)：
- 技术：结合了 SerpAPI, JINA Reader, 和 Qwen3-32B 模型。
- 流程：
  1. 模型提出一个文本问题（比如“最近有哪些关于AI的重大新闻？”）。
  2. SerpAPI 返回最相关的几个网页链接。
  3. JINA Reader 访问这些链接，并提取网页的正文内容（去除广告、导航栏等无关信息）。
  4. 一个强大的语言模型（这里指定用Qwen3-32B）负责阅读提取出的正文，并根据原始问题生成摘要。
  5. 最终，工具返回这些摘要内容以及对应的原始链接。
⚠️ 最重要的警告 ⚠️ 文档明确指出：在开始正式训练之前，您需要自己在 mmsearch_r1/utils/tools/ 目录下构建自己的搜索工具管道。这意味着您需要去申请 SerpAPI 的密钥，并编写代码将上面描述的流程实现出来。项目本身不提供现成的、带密钥的工具。

原本的image_search.py和text_search.py 里是占位符现在通过GPT进行修改这里需要注册Serpapi来获取一个API Key

3. 数据构建 (Data Construction)

格式：训练和验证数据都需要遵循 veRL 定义的格式。veRL 应该是这个项目使用的底层强化学习框架。
内容：项目在 mmsearch_r1/data 目录下提供了一个示例数据集。需要参照这个示例的格式，准备您自己的训练数据。数据内容可能是“问题-答案”对，其中答案可能包含需要通过搜索才能获得的信息。

这里先使用官方提供的数据集进行实验，本项目数据集在huggingface上，下载见 huggingface镜像源

教程参考：NLP小白怎么自己复现一篇论文的代码，见第三部分下载模型

然后有一个重要的问题在执行text.py文件时候需要调用Qwen1.5-0.5B-Chat，模型，然后会显示Network is unreachable，就是huggingface的连接问题

参考这个blog：解决AutoDL服务器无法访问huggingface或SSL证书验证错误

解决完huggingface连接问题之后就ok了！

也是非常欣慰呀

成功执行并返回！

4.模型下载

下载模型之前需要 Hugging Face 账号认证

打开 Hugging Face 个人设置，获取访问令牌（Access Token）：
- 访问 https://huggingface.co/settings/tokens
- 登录后，点击 “New token”，创建一个具有read权限的令牌（复制保存，只显示一次）。
在终端执行 hf auth login，然后系统会提示你输入token 之后就ok了
执行 hf download lmms-lab/MMSearch-R1-7B --local-dir /root/autodl-tmp/multimodal-search-r1/Qwen2.5-VL-7B 注意这里MMSearch-R1-7B为模型名字不同需要更改

5. 训练与评估 (Train & Eval)

这部分是项目的最终执行环节。

5.1 启动命令

通过运行一个脚本 bash mmsearch_r1/scripts/run_mmsearch_r1_grpo.sh 来统一开始训练和评估。
下图这个输出说明 Ray 成功启动了本地实例，也就是说你的脚本已经开始正常运行了。

后面一直报错通过GPT修改.yaml文件和.sh文件里面的配置参数然后就得到数据集和 DataLoader 创建成功

重要训练参数解读：
- actor_rollout_ref.rollout.name: 必须设置为 vllm_multiturn_mmsearch，这会启用专门为多轮搜索设计的逻辑。
- actor_rollout_ref.actor.use_multi_turn_response_mask: 必须为 True，这是一个技术细节，用于在多轮对话中正确地计算模型的学习损失。
- max_gen_round, max_response_length, response_length_total: 这些参数共同定义了模型在训练时生成对话的轮数和长度限制。
只进行评估：
- 如果您已经训练好了一个模型，只想在验证集上测试效果，可以修改脚本中的参数，设置 trainer.val_only=True。
- 评估结果会以 JSON 格式保存在 trainer.val_only_save_dir 指定的目录中，方便后续进行分析。

5.2 参数修改

tips：

.yaml 文件 = 默认配置
- 像 ppo_trainer.yaml 这样的文件定义了您项目的所有默认参数。
- 里面很可能就写着类似 train_files: null 或者 train_files: /path/to/placeholder/data.jsonl，以及 n_gpus_per_node: 8 这样的默认值。
.sh 脚本 = 覆盖配置
- 您运行的 run_mmsearch_r1_grpo.sh 脚本，它在 python3 ... 命令后面跟的一长串 data.train_files=$TRAIN_DATA_PATH 和 trainer.n_gpus_per_node=8，目的就是为了在运行时“覆盖”掉 .yaml 文件里的默认值。
- 这是一种常见且灵活的做法，让您不必每次都去修改 .yaml 源文件。

5.3 常见错误

总结到另一篇blog里面啦