Mistral-finetune

mistral-finetune 是一个轻量级代码库，支持对 Mistral 模型进行高效且节省显存的微调。它基于 LoRA，这是一种训练范式：大部分权重被冻结，仅对以低秩矩阵扰动形式存在的 1-2% 额外权重进行训练。

为获得最佳效率，建议使用 A100 或 H100 GPU。该代码库针对多 GPU 单节点训练环境进行了优化，但对于较小的模型（如 7B），单个 GPU 也足够。

注意

• 本仓库的目标是提供一个简单、有指导性的入口，用于微调 Mistral 模型。 因此，它在某些方面（尤其是数据格式）较为固定，并不旨在覆盖多种模型架构或硬件类型。 如果您需要更通用的方法，可以参考其他优秀的项目，例如 torchtune。

最新消息

• 2024年8月13日：Mistral Large v2 现已兼容 mistral-finetune！

  • 1. 请从 这里 下载 123B 的 Instruct 版本，并将 model_id_or_path 设置为下载的检查点目录。
  • 2. 微调 Mistral-Large v2 由于模型规模较大，需要显著更多的显存。目前请将 seq_len 设置为 ≤ 8192。
  • 3. 建议使用比其他模型更低的学习率，例如 lr=1e-6 在大多数情况下效果良好。

• 2024年7月19日：Mistral Nemo 现已兼容 mistral-finetune！

  • 1. 请从 这里 下载 12B 的 Base 或 Instruct 版本，并将 model_id_or_path 设置为下载的检查点目录。
  • 2. 运行 pip install --upgrade mistral-common 以获取支持 Tekkenizer 的版本（≥1.3.1）。
  • 3. 目前，微调 Mistral-Nemo 由于词汇表规模更大，导致交叉熵损失的峰值显存需求激增（我们很快会在此处添加改进的交叉熵损失）。因此，暂时请将 seq_len 设置为 ≤ 16384。
  • 4. 建议使用与 7B v3 相同的超参数。

安装

要开始使用 Mistral LoRA 进行微调，请按照以下步骤操作：

1. 克隆本仓库：

cd $HOME && git clone https://github.com/mistralai/mistral-finetune.git

2. 安装所有必需的依赖项：

cd mistral-finetune
pip install -r requirements.txt

模型下载

我们推荐微调官方的 Mistral 模型之一，您可以在这里下载：

模型	链接	校验和
7B Base V3	7B Base	0663b293810d7571dad25dae2f2a5806
7B Instruct v3	7B Instruct v3	80b71fcb6416085bcb4efad86dfb4d52
8x7B Base V1	8x7B Base	(HF 链接)
8x7B Instruct V1	8x7B Instruct	8e2d3930145dc43d3084396f49d38a3f
8x22 Instruct V3	8x22 Instruct	471a02a6902706a2f1e44a693813855b
8x22B Base V3	8x22B Base	a2fa75117174f87d1197e3a4eb50371a
12B Instruct	12B Instruct (Mistral-Nemo)	296fbdf911cb88e6f0be74cd04827fe7
12B Base	12 Base (Mistral-Nemo)	c5d079ac4b55fc1ae35f51f0a3c0eb83
Mistral Large 2	123B Instruct (Large v2)	fc602155f9e39151fba81fcaab2fa7c4

重要提示：对于 8x7B Base V1 和 8x7B Instruct V1，必须使用我们的 v3 分词器，并在微调之前将词汇表大小扩展到 32768。有关此过程的详细说明，请参阅“模型扩展”部分：[https://github.com/mistralai/mistral-finetune?tab=readme-ov-file#model-extension]。

例如，要下载 7B-base 模型，可以运行以下命令：

mkdir -p ~/${HOME}/mistral_models
cd ${HOME} && wget https://models.mistralcdn.com/mistral-7b-v0-3/mistral-7B-v0.3.tar
tar -xf mistral-7B-v0.3.tar -C mistral_models

请务必修改您的训练脚本，并将下载文件夹的路径作为 model_id_or_path 添加进去。

例如，修改 example/7B.yaml，加入 $HOME/mistral_models/7B 的绝对路径：

model_id_or_path: "/Users/johndoe/mistral_models/7B"

准备数据集

为确保训练效果，mistral-finetune 对训练数据的格式有严格要求。

所有数据文件必须以 jsonl 格式存储。

您可以构建两种类型的数据文件：

预训练：

预训练数据对应于存储在 "text" 键中的纯文本数据。例如：

{"text": "文档第1号中包含的文本"}
{"text": "文档第2号中包含的文本"}

指令：

目前支持两种不同类型的指令遵循数据：

• 指令：以列表形式存储在 "messages" 键中的对话数据。每个列表项是一个字典，包含 "content" 和 "role" 键。"role" 是一个字符串，取值为 "user"、"assistant" 或 "system"。只有当 "role" == "assistant" 时才会计算损失。例如：

{
  "messages": [
    {
      "role": "user",
      "content": "文档1中的用户交互第1条"
    },
    {
      "role": "assistant",
      "content": "文档1中的机器人交互第1条"
    },
    {
      "role": "user",
      "content": "文档1中的用户交互第2条"
    },
    {
      "role": "assistant",
      "content": "文档1中的机器人交互第2条"
    }
  ]
}
{
  "messages": [
    {
      "role": "user",
      "content": "文档2中的用户交互第1条"
    },
    {
      "role": "assistant",
      "content": "文档2中的机器人交互第1条"
    },
    {
      "role": "user",
      "content": "文档2中的用户交互第2条"
    },
    {
      "role": "assistant",
      "content": "文档2中的机器人交互第2条",
      "weight": 0,  # 不对第2条进行训练
    },
    {
      "role": "user",
      "content": "文档2中的用户交互第3条"
    },
    {
      "role": "assistant",
      "content": "文档2中的机器人交互第3条"
    }
  ]
}

• 函数调用：以列表形式存储在 "messages" 键中的对话数据。每个列表项是一个字典，包含 "role" 和 "content" 或 "tool_calls" 键。"role" 是一个字符串，取值为 "user"、"assistant"、"system" 或 "tool"。只有当 "role" == "assistant" 时才会计算损失。

注意：在函数调用中，"tool_calls" 的 "id" 和 "tool_call_id" 是随机生成的、长度恰好为9个字符的字符串。我们建议在数据准备脚本中自动生成这些ID，如此处所示。

例如：

{
  "messages": [
    {
      "role": "system",
      "content": "你是一位助手，可以访问以下函数来帮助用户，必要时可以调用这些函数"
    },
    {
      "role": "user",
      "content": "你能帮我生成单词‘listen’的字谜吗？"
    },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "TX92Jm8Zi",
          "type": "function",
          "function": {
            "name": "generate_anagram",
            "arguments": "{\"word\": \"listen\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "content": "{\"anagram\": \"silent\"}",
      "tool_call_id": "TX92Jm8Zi"
    },
    {
      "role": "assistant",
      "content": "单词‘listen’的字谜是‘silent’。"
    },
    {
      "role": "user",
      "content": "太棒了！那你能再生成一个‘race’的字谜吗？"
    },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "3XhQnxLsT",
          "type": "function",
          "function": {
            "name": "generate_anagram",
            "arguments": "{\"word\": \"race\"}"
          }
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "generate_anagram",
        "description": "生成给定单词的字谜",
        "parameters": {
          "type": "object",
          "properties": {
            "word": {
              "type": "string",
              "description": "要生成字谜的单词"
            }
          },
          "required": [
            "word"
          ]
        }
      }
    }
  ]
}

数据集验证

在开始训练之前，您应该验证数据集的格式是否正确，并估算训练所需时间。您可以使用 ./utils/validate_data 脚本来完成此操作。

请注意，这一步骤至关重要，可确保数据格式正确无误。

指令遵循

让我们通过一个简单的示例来训练一个指令遵循模型：

• 1. 加载一段 Ultachat_200k 数据

创建数据文件夹并进入该文件夹。

cd $HOME && mkdir -p data && cd $HOME/data

将数据加载到 Pandas DataFrame 中。

注意：请确保已安装 pandas 和 pyarrow（pip install pandas pyarrow）。

import pandas as pd

df = pd.read_parquet('https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k/resolve/main/data/test_gen-00000-of-00001-3d4cd8309148a71f.parquet')

• 2. 划分训练集和评估集

df_train=df.sample(frac=0.95,random_state=200)
df_eval=df.drop(df_train.index)

• 3. 将数据保存为 jsonl 格式

df_train.to_json("ultrachat_chunk_train.jsonl", orient="records", lines=True)
df_eval.to_json("ultrachat_chunk_eval.jsonl", orient="records", lines=True)

• 4. 修改训练配置文件以包含 ultrachat 数据集，并验证配置文件

修改 example/7B.yaml，加入 $HOME/data/ultrachat_chunk_train.jsonl 的绝对路径以及训练用的数据集混合权重，同时加入 $HOME/data/ultrachat_chunk_eval.jsonl 作为评估数据，例如：

data:
  instruct_data: "/Users/johndoe/data/ultrachat_chunk_train.jsonl"
  eval_instruct_data: "/Users/johndoe/data/ultrachat_chunk_eval.jsonl"

现在可以验证你的训练配置文件，以确保数据格式正确，并估算训练所需时间。

cd $HOME/mistral-finetune
python -m utils.validate_data --train_yaml example/7B.yaml

运行完成后，你应该会看到类似以下的错误报告：

/Users/johndoe/data/ultrachat_chunk_eval.jsonl 数据集中第1412行的数据格式不正确。期望最后一个角色是 [assistant]，但实际是 user。
/Users/johndoe/data/ultrachat_chunk_eval.jsonl 数据集中第1413行的数据格式不正确。期望最后一个角色是 [assistant]，但实际是 user。
/Users/johndoe/data/ultrachat_chunk_eval.jsonl 数据集中第1414行的数据格式不正确。期望最后一个角色是 [assistant]，但实际是 user。
/Users/johndoe/data/ultrachat_chunk_eval.jsonl 数据集中第1415行的数据格式不正确。期望最后一个角色是 [assistant]，但实际是 user。

许多对话似乎以 user 角色结束，而我们只训练 assistant 消息，因此这些不必要的 user 角色会导致数据被无谓地处理。

你可以使用 ./utils/reformat_data.py 来修正数据：

cd $HOME/mistral-finetune
python -m utils.reformat_data $HOME/data/ultrachat_chunk_train.jsonl
python -m utils.reformat_data $HOME/data/ultrachat_chunk_eval.jsonl

你可能会发现有少数样本被跳过。

• 5. 可能需要调整训练步数

在修正数据集后，再次运行脚本：

cd $HOME/mistral-finetune
python -m utils.validate_data --train_yaml example/7B.yaml

你应该会得到关于数据输入和训练参数的摘要：

训练状态
 --------------------
{
   "expected": {
       "eta": "00:52:44",
       "data_tokens": 25169147,
       "train_tokens": 131072000,
       "epochs": "5.21",
       "max_steps": 500,
       "data_tokens_per_dataset": {
           "/Users/johndoe/data/ultrachat_chunk_train.jsonl": "25169147.0"
       },
       "train_tokens_per_dataset": {
           "/Users/johndoe/data/ultrachat_chunk_train.jsonl": "131072000.0"
       },
       "epochs_per_dataset": {
           "/Users/johndoe/data/ultrachat_chunk_train.jsonl": "5.2"
       }
   },
}

将 max_steps 设置为 500 步意味着大约会遍历数据集 5 次，这在合理范围内，但可能稍显过多。推荐的设置如下，这样在一个 8xH100 集群上只需约 30 分钟即可完成训练。

函数调用

接下来，我们来看一个更高级的用例，即微调一个支持函数调用的模型。函数调用要求数据必须按照 上述说明 的格式进行组织。下面是一个示例。

• 1. 加载 Glaive 函数调用数据集 的聊天格式版本

创建数据文件夹并进入该文件夹。

cd $HOME && mkdir -p data && cd $HOME/data

将数据加载到 Pandas DataFrame 中。

注意：请确保已安装 pandas 和 pyarrow（pip install pandas pyarrow）。

import pandas as pd

df = pd.read_parquet('https://huggingface.co/datasets/Locutusque/function-calling-chatml/resolve/main/data/train-00000-of-00001-f0b56c6983b4a78f.parquet')

• 2. 划分训练集和评估集

df_train=df.sample(frac=0.95,random_state=200)
df_eval=df.drop(df_train.index)

• 3. 将数据保存为 jsonl 格式

df_train.to_json("glaive_train.jsonl", orient="records", lines=True)
df_eval.to_json("glaive_eval.jsonl", orient="records", lines=True)

• 4. 重新格式化数据集

可以看出，该数据集并不符合所需的函数调用格式，因此需要进行重新格式化。例如，应将 "from" 改名为 "user"，并移除多余的 "\n" 字符。对于这个数据集，你可以使用 ./utils/reformat_data_glaive.py：

cd $HOME/mistral-finetune
python -m utils.reformat_data_glaive $HOME/data/glaive_train.jsonl
python -m utils.reformat_data_glaive $HOME/data/glaive_eval.jsonl

运行此命令后，大多数样本应该会符合正确的格式。

注意：不可能编写适用于所有类型数据集的重新格式化脚本。如果你的数据尚未符合上述要求的格式，很可能需要自己编写重新格式化脚本（此时 mistral-chat 或 chat-gpt 就是你最好的帮手！）。

• 5. 验证数据集

现在可以在 example/7B.yaml 中将 data.instruct_data 和 data.eval_instruct_data 分别设置为 $HOME/data/glaive_train.jsonl 和 $HOME/data/glaive_eval.jsonl，以验证数据集。

经过重新格式化的数据集仍然存在一些错误，可以通过 --create_corrected 参数来修复。为此，请按如下方式添加 --create_corrected：

cd $HOME/mistral-finetune
python -m utils.validate_data --train_yaml example/7B.yaml --create_corrected

运行此命令后，系统会显示一些错误，并生成两个新的数据集 $HOME/data/glaive_train.jsonl.corrected 和 $HOME/data/glaive_eval.jsonl.corrected。请务必在 example/7B.yaml 中使用这两个数据集，然后再次运行命令。此时，数据集应该已经正确格式化了！

开始训练

在完成了数据集验证部分之后，我们现在可以开始训练了。为了加快训练速度，我们建议将max_steps设置为仅300步。请确保将run_dir定义为你实验的文件夹，并可选地将wandb_project设置为一个用于日志记录的Weights & Biases项目，例如：

max_steps: 300
run_dir: "/Users/johndoe/ultra_chat_test"
wandb.project: ultra_chat

你也可以选择性地设置wandb

保存训练配置并开始训练！请务必把--nproc-per-node设置为可用的GPU数量。

cd $HOME/mistral-finetune
torchrun --nproc-per-node 8 --master_port $RANDOM -m train example/7B.yaml

在ultra-chat数据集上进行训练，在一台配备8块H100显卡的节点上大约需要30分钟，最终得到的权重应该能在MT Bench上取得约6.3分的成绩。

而在glaive数据集上进行训练，则大约需要1小时，在同样的硬件条件下，生成的权重将非常适合用于函数调用任务。

自定义训练配置

示例配置mistral-finetune/examples/7B已经为学习率、权重衰减等参数设定了合理的值，但建议你根据自己的使用场景对这些设置进行调整。

一般来说，训练配置应包含以下参数：

• model_id_or_path：指定开始训练的基础模型。这可以是预训练模型的路径，也可以是本地模型目录。
• run_dir：指定存储训练检查点和指标的目录。
• seq_len：定义训练时的序列长度。这是模型能够处理的最大输入序列长度。为了提高训练效率，样本会被打包到seq_len的长度。
• batch_size：每张GPU使用的训练样本数。注意：所有GPU上的总有效批量大小（以token数计）等于num_gpus × batch_size × seq_len。
• max_steps：最大训练步数。这是训练过程将运行的总迭代次数。可以根据具体的训练需求进行调整。整个训练过程中看到的总token数为max_steps × num_gpus × batch_size × seq_len。
• optim.lr：学习率。这是优化器的初始学习率。
• optim.weight_decay：权重衰减。权重衰减是一种正则化技术，通过惩罚过大的权重来防止过拟合。我们建议将其保持在0.1。
• optim.pct_start：在学习率开始下降之前，用于学习率预热阶段的训练总步数百分比。它对应于PyTorch的OneCycleLR中的pct_start。
• lora.rank：LoRA（低秩适应）适配器的规模。我们推荐设置为64或更小，这会调整LoRA中使用的低秩分解的秩。
• seed：初始化以及数据打乱和采样的随机种子。设置种子可以确保结果的可重复性。
• log_freq：日志记录频率。这指定了每隔多少步记录一次训练指标。
• data.instruct_data：用于训练的指令数据路径。该字段必须填写一个或多个数据源，格式如上文所述。每个数据源可以是jsonl文件的路径，也可以是包含jsonl文件的目录路径，并在其后加上权重以定义该数据集的重要性：<path/to/data_source>:<weight>。例如：data.instruct_data: "/path/to/data1.jsonl:5.,/path/to/data2.jsonl:1.,/path/to/dir_of_jsonls:1."
• data.data：可选的额外预训练数据路径，格式同上。请注意，此字段可以留空。
• data.eval_instruct_data：可选的评估指令数据路径，用于每隔eval_freq步进行交叉验证。交叉验证指标将以loss和perplexity的形式显示。
• eval_freq：模型评估的频率。这指定了模型在验证集上进行评估的间隔。
• no_eval：中间评估的开关标志。将其设置为False即可在训练过程中定期进行评估。
• ckpt_freq：检查点保存频率。这指定了模型状态被保存的间隔。
• save_adapters：决定是仅保存训练好的LoRA检查点，还是将训练好的LoRA直接合并到基础模型中并保存。注意：当设置save_adapters=False时，请确保有足够的CPU和GPU内存来在一个进程中保存完整的模型（通常只有7B模型才可能做到这一点）。
• wandb.key：用于传递你的Weights & Biases（wandb）API密钥以便进行日志记录。这样你可以将训练指标记录到wandb仪表板上。
• wandb.project：指定wandb项目的名称。训练过程的所有信息都将被记录在这个项目中。

推理

一旦你的模型训练完成，你应该尝试对其进行推理测试。我们推荐使用mistral-inference。

请确保正确安装了mistral_inference：

pip install mistral_inference

假设你的lora.safetensors保存在$HOME/ultra_chat_test/checkpoints/checkpoint_000300/consolidated/lora.safetensors，那么你可以使用mistral_inference与模型对话，例如：

mistral-chat /mnt/slow/runs/patrick/mistral-finetune/7B/ --max_tokens 256 --temperature 1.0 --instruct --lora_path $HOME/ultra_chat_test/checkpoints/checkpoint_000300/consolidated/lora.safetensors

添加Weights and Biases（wandb）支持

我们已明确添加了对Weights and Biases的支持，以帮助你监控和可视化训练过程。这一集成使你可以轻松记录各种指标并跟踪实验。

设置Weights and Biases

要将Weights and Biases与mistral-finetune结合使用，请按照以下步骤操作：

1. 安装Weights and Biases：

   确保已安装wandb库。你可以通过pip进行安装：

   pip install wandb

查看你的日志

训练开始后，你可以通过访问你的wandb项目仪表板实时监控训练进度。所有的指标，包括训练损失、评估损失、学习率等，都会被记录并可视化。

有关如何使用wandb的更多详细信息，请参阅Weights and Biases文档。

模型扩展

重要提示：请注意，只能对兼容v3分词器的Mistral模型进行微调，这意味着这些模型的词汇表大小必须是32768，而不是32000。不过，你可以很容易地将旧版词汇表大小为32000的模型扩展到32768，方法如下：

python -m utils.extend_model_vocab --original_model_ckpt /folder/to/old/model --extended_model_ckpt /folder/to/extended/model

扩展完成后，你就可以使用新创建的模型检查点（位于/folder/to/extended/model）来进行微调了。

常见问题解答：

• 微调 MoE 模型的最佳实践是什么？

我们在微调 MoE 模型时观察到性能差异较大。使用不同随机种子对 MoE 模型进行微调，往往会导致性能出现显著波动。而在密集模型中，我们并未观察到如此大的差异。因此，我们建议对 MoE 模型运行多次相同的微调过程，并选择表现最佳的实例。

• 如何确定模型训练过程中使用的令牌数量？

您可以使用以下脚本进行查询：https://github.com/mistralai/mistral-finetune/blob/main/utils/validate_data.py。该脚本接受一个 .yaml 格式的训练配置文件作为输入，并输出模型正在训练的令牌总数。

• 如果遇到 CUDA 内存不足错误，该怎么办？

一种可能的解决方案是减少每个 GPU 的批次大小。批次大小等于 seq_len 乘以 batch_size。您可以尝试将 batch_size 设置为 1，并相应地减小 seq_len。您可以在 .yaml 配置文件中定义 batch_size 和 seq_len。

许可证

本库采用 Apache 2.0 许可证授权。更多信息请参阅 LICENCE 文件。

您不得以侵犯、盗用或以其他方式违反任何第三方权利（包括知识产权）的方式使用本库或我们的模型。

Mistral-finetune 快速上手指南

mistral-finetune 是 Mistral AI 官方提供的轻量级代码库，专为高效、低显存占用地微调 Mistral 系列模型（如 7B, Nemo, Large v2 等）而设计。它基于 LoRA 技术，仅训练少量参数，适合单卡或多卡单机环境。

环境准备

系统要求

• 操作系统: Linux (推荐) 或 macOS
• GPU:
  • 推荐：NVIDIA A100 或 H100 以获得最佳效率。
  • 最小配置：对于 7B 模型，单张消费级 GPU（如 RTX 3090/4090）即可运行。
  • 注意：微调 Mistral-Nemo (12B) 或 Mistral-Large (123B) 需要更大的显存。
• Python: 3.10 或更高版本

前置依赖

确保已安装以下基础工具：

• git
• pip
• cuda (驱动版本需与 PyTorch 兼容)

提示：国内用户建议在安装 Python 依赖时使用清华或阿里镜像源加速： pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

1. 克隆仓库

   cd $HOME && git clone https://github.com/mistralai/mistral-finetune.git
   

2. 进入目录并安装依赖

   cd mistral-finetune
   pip install -r requirements.txt
   

   (若需微调 Mistral-Nemo 模型，请额外执行：pip install --upgrade mistral-common)

3. 下载模型权重 从官方链接下载模型并解压。以 Mistral 7B Base V3 为例：

   mkdir -p ~/mistral_models
   cd ~
   wget https://models.mistralcdn.com/mistral-7b-v0-3/mistral-7B-v0.3.tar
   tar -xf mistral-7B-v0.3.tar -C mistral_models
   

   其他模型（如 Instruct 版、Nemo、Large v2）下载地址请参考项目 README 中的表格。

基本使用

1. 准备数据集

mistral-finetune 对数据格式有严格要求，必须为 jsonl 格式。

指令微调 (Instruct) 数据示例 (data.jsonl)：

{"messages": [{"role": "user", "content": "你好"}, {"role": "assistant", "content": "你好！有什么我可以帮你的吗？"}]}
{"messages": [{"role": "user", "content": "写一首诗"}, {"role": "assistant", "content": "春眠不觉晓..."}]}

注意：只有 role 为 assistant 的内容会参与损失计算。

2. 配置训练参数

复制示例配置文件并根据实际情况修改。主要需更改 model_id_or_path 和數據路径。

cp example/7B.yaml my_config.yaml

编辑 my_config.yaml：

model_id_or_path: "/root/mistral_models/7B"  # 替换为你下载的模型绝对路径
data:
  instruct_data: "/root/data/train.jsonl"    # 替换为你的训练数据路径
  eval_instruct_data: "/root/data/eval.jsonl" # 替换为你的评估数据路径（可选）
# 其他超参数可根据需求调整，如 learning_rate, seq_len 等

3. 验证数据格式（强烈推荐）

在开始训练前，先运行验证脚本检查数据格式并预估训练时间：

python -m utils.validate_data --train_yaml my_config.yaml

如果输出无报错且显示预估时间，则数据格式正确。

4. 启动微调

使用以下命令开始训练：

python -m train --config my_config.yaml

训练完成后，LoRA 适配器权重将保存在指定输出目录中，可配合原始模型进行推理。