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

写在前面：大家复现项目时可以把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 文件。

步骤：

1. 访问 flash-attn releases 页面。
2. 找到 v2.7.4.post1 版本。
3. 下载对应你系统的 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 账号认证

1. 打开 Hugging Face 个人设置，获取访问令牌（Access Token）：
   • 访问 https://huggingface.co/settings/tokens
   • 登录后，点击 “New token”，创建一个具有read权限的令牌（复制保存，只显示一次）。
2. 在终端执行 hf auth login，然后系统会提示你输入token 之后就ok了
3. 执行 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里面啦