diff --git a/docs/zh_cn/get_started/installation.md b/docs/zh_cn/get_started/installation.md deleted file mode 100644 index 88e9dbc65..000000000 --- a/docs/zh_cn/get_started/installation.md +++ /dev/null @@ -1,52 +0,0 @@ -# 安装 - -本节中，我们将演示如何安装 XTuner。 - -## 安装流程 - -我们推荐用户参照我们的最佳实践安装 XTuner。 -推荐使用 Python-3.10 的 conda 虚拟环境安装 XTuner。 - -### 最佳实践 - -**步骤 0.** 使用 conda 先构建一个 Python-3.10 的虚拟环境 - -```shell -conda create --name xtuner-env python=3.10 -y -conda activate xtuner-env -``` - -**步骤 1.** 安装 XTuner。 - -方案 a：通过 pip 安装 XTuner： - -```shell -pip install -U xtuner -``` - -方案 b：集成 DeepSpeed 安装 XTuner： - -```shell -pip install -U 'xtuner[deepspeed]' -``` - -方案 c：从源码安装 XTuner： - -```shell -git clone https://github.com/InternLM/xtuner.git -cd xtuner -pip install -e '.[all]' -# "-e" 表示在可编辑模式下安装项目，因此对代码所做的任何本地修改都会生效，从而无需重新安装。 -``` - -## 验证安装 - -为了验证 XTuner 是否安装正确，我们将使用命令打印配置文件。 - -**打印配置文件：** 在命令行中使用 `xtuner list-cfg` 命令验证是否能打印配置文件。 - -```shell -xtuner list-cfg -``` - -你将为看到 XTuner 的配置文件列表，这与源码中 [xtuner/configs](https://github.com/InternLM/xtuner/tree/main/xtuner/configs) 对应。 diff --git a/docs/zh_cn/get_started/installation.rst b/docs/zh_cn/get_started/installation.rst new file mode 100644 index 000000000..90bd9468e --- /dev/null +++ b/docs/zh_cn/get_started/installation.rst @@ -0,0 +1,200 @@ +使用自定义的预训练数据集训练 (LLM) +================================== + +XTuner 支持使用自定义数据集进行增量预训练，为便于介绍，本节以 +`internlm2_7b_custom_pretrain_e1.py `__ +配置文件为基础进行介绍。 + +数据准备 +-------- + +用户若要在进行预训练，则需要将自定义的数据处理为以下格式： + +.. code:: json + + [ + { + "text": "xxx" + }, + { + "text": "xxx" + }, + ... + ] + +小贴士 + +- 每条 ``text`` 数据不要太长（分词个数应小于 + ``max_length``\ ），以避免在数据处理阶段被截断。 + +- 为保证数据上下文的一致性，请确保长文本数据在被切分为多个 ``text`` + 后，json 列表的顺序与实际上下文顺序一致。 + +训练 +---- + +Step 1, 导出 config +~~~~~~~~~~~~~~~~~~~ + +``xtuner/configs/custom_dataset/pretrain/`` 目录下有所有 XTuner +支持的模型在自定义数据集下执行预训练的模板 config。可以通过 +``xtuner list-cfg -p custom_pretrain`` 命令来查看候选 config。下面以 +`internlm2_7b_custom_pretrain_e1.py `__ +为例展开介绍。 + +可以通过以下命令将 ``internlm2_7b_full_custom_pretrain_e1.py`` +导出至当前目录下： + +.. code:: + + xtuner copy-cfg internlm2_7b_full_custom_pretrain_e1 . + +当前目录下会存在一个新 config +``internlm2_7b_full_custom_pretrain_e1_copy.py`` 。 + +Step 2, 修改 config +~~~~~~~~~~~~~~~~~~~ + +首先，需要修改数据集文件路径： + +.. code:: diff + + - data_files = ['/path/to/json/file.json'] + + data_files = ['/path/to/custom_dataset1.json', '/path/to/custom_dataset2.json', ...] + +若期望使用某个目录下所有的 json 文件作为训练数据集，可做如下修改： + +.. code:: diff + + ####################################################################### + # PART 1 Settings # + ####################################################################### + # Data + - data_files = ['/path/to/json/file.json'] + + data_dir = '/dir/to/custom_dataset' + + ####################################################################### + # PART 3 Dataset & Dataloader # + ####################################################################### + train_dataset = dict( + - dataset=dict(type=load_dataset, path='json', data_files=data_files), + + dataset=dict(type=load_dataset, path='json', data_dir=data_dir), + ...) + +若期望使用 LoRA 算法训练，可做如下修改： + +.. code:: diff + + ####################################################################### + # PART 2 Model & Tokenizer # + ####################################################################### + model = dict( + type=SupervisedFinetune, + use_varlen_attn=use_varlen_attn, + llm=dict( + type=AutoModelForCausalLM.from_pretrained, + pretrained_model_name_or_path=pretrained_model_name_or_path, + trust_remote_code=True), + + lora=dict( + + type=LoraConfig, + + r=64, + + lora_alpha=16, + + lora_dropout=0.1, + + bias='none', + + task_type='CAUSAL_LM')) + +若期望进行 QLoRA 算法训练，可做如下修改： + +.. code:: diff + + ####################################################################### + # PART 2 Model & Tokenizer # + ####################################################################### + model = dict( + type=SupervisedFinetune, + use_varlen_attn=use_varlen_attn, + llm=dict( + type=AutoModelForCausalLM.from_pretrained, + pretrained_model_name_or_path=pretrained_model_name_or_path, + trust_remote_code=True, + + quantization_config=dict( + + type=BitsAndBytesConfig, + + load_in_4bit=True, + + load_in_8bit=False, + + llm_int8_threshold=6.0, + + llm_int8_has_fp16_weight=False, + + bnb_4bit_compute_dtype=torch.float16, + + bnb_4bit_use_double_quant=True, + + bnb_4bit_quant_type='nf4') + ), + + lora=dict( + + type=LoraConfig, + + r=64, + + lora_alpha=16, + + lora_dropout=0.1, + + bias='none', + + task_type='CAUSAL_LM') + ) + +Step 3, 开始训练 +~~~~~~~~~~~~~~~~ + +.. code:: bash + + NPROC_PER_NODE=8 xtuner train internlm2_7b_full_custom_pretrain_e1_copy.py --deepspeed deepspeed_zero1 + +训得模型将默认保存在 ``./work_dirs/``\ ，用户可以通过命令 +``xtuner train --work-dir ${SAVE_PATH}`` 指定保存路径。 + +Step 4, 模型转换 +~~~~~~~~~~~~~~~~ + +模型训练后会自动保存成 PTH 模型（例如 ``iter_2000.pth``\ ，如果使用了 +DeepSpeed，则将会是一个文件夹），我们需要利用 +``xtuner convert pth_to_hf`` 将其转换为 HuggingFace +模型，以便于后续使用。具体命令为： + +.. code:: bash + + xtuner convert pth_to_hf ${FINETUNE_CFG} ${PTH_PATH} ${SAVE_PATH} + # 例如：xtuner convert pth_to_hf internlm2_7b_full_custom_pretrain_e1_copy.py ./iter_2000.pth ./iter_2000_hf + +对话 +---- + +用户可以利用 ``xtuner chat`` 实现与微调后的模型对话。 + +如果进行的是全量参数的微调： + +.. code:: bash + + xtuner chat ${PATH_TO_LLM} [optional arguments] + # 例如：xtuner chat ./iter_2000_hf --max-new-tokens 512 + +如果使用的是 LoRA 或 QLoRA 算法： + +.. code:: bash + + xtuner chat ${NAME_OR_PATH_TO_LLM} --adapter {NAME_OR_PATH_TO_ADAPTER} [optional arguments] + # 例如：xtuner chat internlm/internlm2-7b --adapter ./iter_2000_hf --max-new-tokens 512 + +.. _模型合并可选）: + +模型合并（可选） +---------------- + +如果您使用了 LoRA / QLoRA 微调，则模型转换后将得到 adapter +参数，而并不包含原 LLM +参数。如果您期望获得合并后的模型权重（例如用于后续评测），那么可以利用 +``xtuner convert merge`` ： + +.. code:: bash + + (LLM) xtuner convert merge ${LLM} ${LLM_ADAPTER} ${SAVE_PATH} + +评测 +---- + +推荐使用一站式平台 +`OpenCompass `__ +来评测大语言模型，其目前已涵盖 50+ 数据集的约 30 万条题目。 diff --git a/docs/zh_cn/get_started/overview.md b/docs/zh_cn/get_started/overview.md deleted file mode 100644 index 641020224..000000000 --- a/docs/zh_cn/get_started/overview.md +++ /dev/null @@ -1,123 +0,0 @@ -# 概述 - -本节将向您介绍 XTuner 的整体框架和工作流程，并提供详细的教程链接。 - -## 什么是 XTuner ？ - -- XTuner 是由 InternLM 团队开发的一个高效、灵活、全能的轻量化大模型微调工具库。 -- 主要用于多种大模型的高效微调，包括 InternLM 和多模态图文模型 LLaVa。 -- 支持 QLoRA、全量微调等多种微调训练方法，并可与 DeepSpeed 集成优化训练。 -- 提供模型、数据集、数据管道和算法支持，配备配置文件和快速入门指南。 -- 训练所得模型可无缝接入部署工具库 LMDeploy、大规模评测工具库 OpenCompass 及 VLMEvalKit。为大型语言模型微调提供一个全面且用户友好的解决方案。 - -## XTuner 的工作流程 - -我们可以通过以下这张图，简单的了解一下 XTuner 的整体运作流程。 -![image](https://github.com/Jianfeng777/xtuner/assets/108343727/d538dd88-20f7-49cf-a84a-62669c03cb79) - -整个工作流程分为以下四个步骤： - -1. **前期准备**： - - - 首先，根据任务的不同，我们需要明确微调目标，进行数据采集，并将数据转换为 XTuner 所支持的格式类型。 - - 然后我们还需要根据自己的硬件条件选择合适的微调方法和合适的基座模型。不同的基座模型对显存的需求都不太一样，模型参数越大，微调所需要显存就越多。而在微调方法中，对显存需求最小的就是 QLoRA（最少 8GB 即可运行），而显存需求最大的则是全量微调。 - -2. **配置文件的创建及修改**： - - - 首先，我们可以通过执行 `xtuner list-cfg` 命令列出所有配置文件。 - - 通过上面选择的微调方法和基座模型找到合适的配置文件，并使用 `xtuner copy-cfg ${CONFIG_NAME} ${SAVE_PATH}` 命令复制到本地端。 - - 复制完成后还需要根据自己的需求修改配置文件以更新模型路径和数据集路径。 - - 特定时候还需要调整模型参数和配置，更改 `load_dataset` 函数和 `dataset_map_fn` 函数。并根据模型选择合适的 `prompt_template`。 - -3. **模型训练**： - - - 修改配置文件后，我就可以使用 `xtuner train` 命令启动训练。 - - 除此之外我们还可以设置特定参数优化训练，如启用 deepspeed，以及设置训练文件的保存路径。 - - 假如意外的中断了训练，还可以通过加上 `--resume {checkpoint_path}` 的方式进行模型续训。 - -4. **模型转换、整合、测试及部署**： - - - 在完成训练后，找到对应的训练文件并执行 `xtuner convert pth_to_hf` 命令，就可以将转换模型格式为 huggingface 格式。 - - 对于 LoRA 类的模型而言，由于微调出来的是一个额外的 adapter 层而不是完整的模型，因此还需要执行 `xtuner convert merge` 命令将 adapter 层与原模型进行合并。对于全量微调模型而言，则只需要转换即可使用。 - - 转换完成后，我们就可以以转换后的文件路径并使用 `xtuner chat` 命令启动模型进行性能测试。 - - 除此之外，我们还可以在安装 LMDeploy 后通过 `python -m lmdeploy.pytorch.chat` 命令进行模型部署，即使用 TurboMind 进行推理。 - -以下是每一步具体的指令应用： -XTuner Flow - -## XTuner 的核心模块 - -1. **Configs**： - - - 存放着不同模型、不同数据集以及微调方法的配置文件。 - - 可以自行从 huggingface 上下载模型和数据集后进行一键启动。 - -2. **Dataset**： - - - 在 `map_fns` 下存放了支持的数据集的映射规则。 - - 在 `collate_fns` 下存放了关于数据整理函数部分的内容。 - - 提供了用于存放和加载不同来源数据集的函数和类。 - -3. **Engine**： - - - `hooks` 中展示了哪些信息将会在哪个阶段下在终端被打印出来。 - -4. **Tools**： - - - 这里面是 XTuner 中的核心工具箱，里面存放了我们常用的指令，包括了打印 config 文件 `list_cfg`、复制 config 文件 `copy_cfg`、训练 `train` 以及对话 `chat` 等等。 - - 在 `model_converters` 中也提供了模型转换、整合以及切分的脚本。 - - 在 `plugin` 中提供了部分工具调用的函数。 - -## XTuner 当前支持的模型、数据集及微调方法 - -### 支持的大语言模型 - -1. **支持的大语言模型** - - XTuner 目前支持以下大语言模型，可支持所有 huggingface 格式的大语言模型： - - - `baichuan` - - `chatglm` - - `internlm` - - `llama` - - `llava` - - `mistral` - - `mixtral` - - `qwen` - - `yi` - - `starcoder` - - `zephyr` - - ... - -2. **支持的数据集格式** - - XTuner 目前支持以下数据集格式： - - - `alpaca` - - `alpaca_zh` - - `code_alpaca` - - `arxiv` - - `colors` - - `crime_kg_assistant` - - `law_reference` - - `llava` - - `medical` - - `msagent` - - `oasst1` - - `openai` - - `openorca` - - `pretrain` - - `sql` - - `stack_exchange` - - `tiny_codes` - - `wizardlm` - - ... - -3. **支持的微调方法** - - XTuner 目前支持以下微调方法： - - - `QLoRA` - - `LoRA` - - `Full` - - ... diff --git a/docs/zh_cn/get_started/overview.rst b/docs/zh_cn/get_started/overview.rst new file mode 100644 index 000000000..24a7fa694 --- /dev/null +++ b/docs/zh_cn/get_started/overview.rst @@ -0,0 +1,212 @@ +概述 +==== + +本节将向您介绍 XTuner 的整体框架和工作流程，并提供详细的教程链接。 + +.. _什么是-xtuner-: + +什么是 XTuner ？ +---------------- + +- XTuner 是由 InternLM + 团队开发的一个高效、灵活、全能的轻量化大模型微调工具库。 + +- 主要用于多种大模型的高效微调，包括 InternLM 和多模态图文模型 LLaVa。 + +- 支持 QLoRA、全量微调等多种微调训练方法，并可与 DeepSpeed + 集成优化训练。 + +- 提供模型、数据集、数据管道和算法支持，配备配置文件和快速入门指南。 + +- 训练所得模型可无缝接入部署工具库 LMDeploy、大规模评测工具库 + OpenCompass 及 + VLMEvalKit。为大型语言模型微调提供一个全面且用户友好的解决方案。 + +XTuner 的工作流程 +----------------- + +我们可以通过以下这张图，简单的了解一下 XTuner 的整体运作流程。 + +.. raw:: html + +
+ +
+ + +整个工作流程分为以下四个步骤： + +1. **前期准备**\ ： + + - 首先，根据任务的不同，我们需要明确微调目标，进行数据采集，并将数据转换为 + XTuner 所支持的格式类型。 + + - 然后我们还需要根据自己的硬件条件选择合适的微调方法和合适的基座模型。不同的基座模型对显存的需求都不太一样，模型参数越大，微调所需要显存就越多。而在微调方法中，对显存需求最小的就是 + QLoRA（最少 8GB 即可运行），而显存需求最大的则是全量微调。 + +2. **配置文件的创建及修改**\ ： + + - 首先，我们可以通过执行 ``xtuner list-cfg`` 命令列出所有配置文件。 + + - 通过上面选择的微调方法和基座模型找到合适的配置文件，并使用 + ``xtuner copy-cfg ${CONFIG_NAME} ${SAVE_PATH}`` 命令复制到本地端。 + + - 复制完成后还需要根据自己的需求修改配置文件以更新模型路径和数据集路径。 + + - 特定时候还需要调整模型参数和配置，更改 ``load_dataset`` 函数和 + ``dataset_map_fn`` 函数。并根据模型选择合适的 + ``prompt_template``\ 。 + +3. **模型训练**\ ： + + - 修改配置文件后，我就可以使用 ``xtuner train`` 命令启动训练。 + + - 除此之外我们还可以设置特定参数优化训练，如启用 + deepspeed，以及设置训练文件的保存路径。 + + - 假如意外的中断了训练，还可以通过加上 + ``--resume {checkpoint_path}`` 的方式进行模型续训。 + +4. **模型转换、整合、测试及部署**\ ： + + - 在完成训练后，找到对应的训练文件并执行 + ``xtuner convert pth_to_hf`` 命令，就可以将转换模型格式为 + huggingface 格式。 + + - 对于 LoRA 类的模型而言，由于微调出来的是一个额外的 adapter + 层而不是完整的模型，因此还需要执行 ``xtuner convert merge`` 命令将 + adapter + 层与原模型进行合并。对于全量微调模型而言，则只需要转换即可使用。 + + - 转换完成后，我们就可以以转换后的文件路径并使用 ``xtuner chat`` + 命令启动模型进行性能测试。 + + - 除此之外，我们还可以在安装 LMDeploy 后通过 + ``python -m lmdeploy.pytorch.chat`` 命令进行模型部署，即使用 + TurboMind 进行推理。 + +| 以下是每一步具体的指令应用： +| + +XTuner 的核心模块 +----------------- + +1. **Configs**\ ： + + - 存放着不同模型、不同数据集以及微调方法的配置文件。 + + - 可以自行从 huggingface 上下载模型和数据集后进行一键启动。 + +2. **Dataset**\ ： + + - 在 ``map_fns`` 下存放了支持的数据集的映射规则。 + + - 在 ``collate_fns`` 下存放了关于数据整理函数部分的内容。 + + - 提供了用于存放和加载不同来源数据集的函数和类。 + +3. **Engine**\ ： + + - ``hooks`` 中展示了哪些信息将会在哪个阶段下在终端被打印出来。 + +4. **Tools**\ ： + + - 这里面是 XTuner + 中的核心工具箱，里面存放了我们常用的指令，包括了打印 config 文件 + ``list_cfg``\ 、复制 config 文件 ``copy_cfg``\ 、训练 ``train`` + 以及对话 ``chat`` 等等。 + + - 在 ``model_converters`` 中也提供了模型转换、整合以及切分的脚本。 + + - 在 ``plugin`` 中提供了部分工具调用的函数。 + +XTuner 当前支持的模型、数据集及微调方法 +--------------------------------------- + +支持的大语言模型 +~~~~~~~~~~~~~~~~ + +1. **支持的大语言模型** + + XTuner 目前支持以下大语言模型，可支持所有 huggingface + 格式的大语言模型： + + - ``baichuan`` + + - ``chatglm`` + + - ``internlm`` + + - ``llama`` + + - ``llava`` + + - ``mistral`` + + - ``mixtral`` + + - ``qwen`` + + - ``yi`` + + - ``starcoder`` + + - ``zephyr`` + + - ... + +2. **支持的数据集格式** + + XTuner 目前支持以下数据集格式： + + - ``alpaca`` + + - ``alpaca_zh`` + + - ``code_alpaca`` + + - ``arxiv`` + + - ``colors`` + + - ``crime_kg_assistant`` + + - ``law_reference`` + + - ``llava`` + + - ``medical`` + + - ``msagent`` + + - ``oasst1`` + + - ``openai`` + + - ``openorca`` + + - ``pretrain`` + + - ``sql`` + + - ``stack_exchange`` + + - ``tiny_codes`` + + - ``wizardlm`` + + - ... + +3. **支持的微调方法** + + XTuner 目前支持以下微调方法： + + - ``QLoRA`` + + - ``LoRA`` + + - ``Full`` + + - ... + +.. |image1| image:: https://github.com/Jianfeng777/xtuner/assets/108343727/d538dd88-20f7-49cf-a84a-62669c03cb79 diff --git a/docs/zh_cn/get_started/quickstart.md b/docs/zh_cn/get_started/quickstart.md deleted file mode 100644 index 1fa728cdf..000000000 --- a/docs/zh_cn/get_started/quickstart.md +++ /dev/null @@ -1,310 +0,0 @@ -# 快速上手 - -本节中，我们将演示如何使用 XTuner 微调模型，帮助您快速上手 XTuner。 - -在成功安装 XTuner 后，便可以开始进行模型的微调。在本节中，我们将演示如何使用 XTuner，应用 QLoRA 算法在 Colorist 数据集上微调 InternLM2-Chat-7B。 - -Colorist 数据集（[HuggingFace 链接](https://huggingface.co/datasets/burkelibbey/colors)；[ModelScope 链接](https://www.modelscope.cn/datasets/fanqiNO1/colors/summary)）是一个根据颜色描述提供颜色选择与建议的数据集，经过该数据集微调的模型可以做到根据用户对于颜色的描述，从而给出16进制下的颜色编码，如用户输入“宁静而又相当明亮的浅天蓝色，介于天蓝色和婴儿蓝之间，因其亮度而带有一丝轻微的荧光感。”，模型输出 ![#66ccff](https://img.shields.io/badge/%2366ccff-66CCFF)，该颜色很符合用户的描述。以下是该数据集的几条样例数据： - -| 英文描述 | 中文描述 | 颜色 | -| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -| Light Sky Blue: A calming, fairly bright color that falls between sky blue and baby blue, with a hint of slight fluorescence due to its brightness. | 浅天蓝色：一种介于天蓝和婴儿蓝之间的平和、相当明亮的颜色，由于明亮而带有一丝轻微的荧光。 | #66ccff: ![#66ccff](https://img.shields.io/badge/%2366ccff-66CCFF) | -| Bright red: This is a very vibrant, saturated and vivid shade of red, resembling the color of ripe apples or fresh blood. It is as red as you can get on a standard RGB color palette, with no elements of either blue or green. | 鲜红色： 这是一种非常鲜艳、饱和、生动的红色，类似成熟苹果或新鲜血液的颜色。它是标准 RGB 调色板上的红色，不含任何蓝色或绿色元素。 | #ee0000: ![#ee0000](https://img.shields.io/badge/%23ee0000-EE0000) | -| Bright Turquoise: This color mixes the freshness of bright green with the tranquility of light blue, leading to a vibrant shade of turquoise. It is reminiscent of tropical waters. | 明亮的绿松石色：这种颜色融合了鲜绿色的清新和淡蓝色的宁静，呈现出一种充满活力的绿松石色调。它让人联想到热带水域。 | #00ffcc: ![#00ffcc](https://img.shields.io/badge/%2300ffcc-00FFCC) | - -## 准备模型权重 - -在微调模型前，首先要准备待微调模型的权重。 - -### 从 HuggingFace 下载 - -```bash -pip install -U huggingface_hub - -# 拉取模型至 Shanghai_AI_Laboratory/internlm2-chat-7b -huggingface-cli download internlm/internlm2-chat-7b \ - --local-dir Shanghai_AI_Laboratory/internlm2-chat-7b \ - --local-dir-use-symlinks False \ - --resume-download -``` - -### 从 ModelScope 下载 - -由于从 HuggingFace 拉取模型权重，可能存在下载过程不稳定、下载速度过慢等问题。因此在下载过程遇到网络问题时，我们则可以选择从 ModelScope 下载 InternLM2-Chat-7B 的权重。 - -```bash -pip install -U modelscope - -# 拉取模型至当前目录 -python -c "from modelscope import snapshot_download; snapshot_download('Shanghai_AI_Laboratory/internlm2-chat-7b', cache_dir='.')" -``` - -在完成下载后，便可以开始准备微调数据集了。 - -此处附上 HuggingFace 链接与 ModelScope 链接： - -- HuggingFace 链接位于：https://huggingface.co/internlm/internlm2-chat-7b -- ModelScope 链接位于：https://modelscope.cn/models/Shanghai_AI_Laboratory/internlm2-chat-7b/summary - -## 准备微调数据集 - -接下来，我们需要准备微调数据集。 - -### 从 HuggingFace 下载 - -```bash -git clone https://huggingface.co/datasets/burkelibbey/colors -``` - -### 从 ModelScope 下载 - -由于相同的问题，因此我们可以选择从 ModelScope 下载所需要的微调数据集。 - -```bash -git clone https://www.modelscope.cn/datasets/fanqiNO1/colors.git -``` - -此处附上 HuggingFace 链接与 ModelScope 链接： - -- HuggingFace 链接位于：https://huggingface.co/datasets/burkelibbey/colors -- ModelScope 链接位于：https://modelscope.cn/datasets/fanqiNO1/colors - -## 准备配置文件 - -XTuner 提供了多个开箱即用的配置文件，可以通过 `xtuner list-cfg` 查看。我们执行如下指令，以复制一个配置文件到当前目录。 - -```bash -xtuner copy-cfg internlm2_7b_qlora_colorist_e5 . -``` - -配置文件名的解释： - -| 配置文件 | internlm2_7b_qlora_colorist_e5 | -| -------- | ------------------------------ | -| 模型名 | internlm2_7b | -| 使用算法 | qlora | -| 数据集 | colorist | -| 训练时长 | 5 epochs | - -此时该目录文件结构应如下所示： - -```bash -. -├── colors -│ ├── colors.json -│ ├── dataset_infos.json -│ ├── README.md -│ └── train.jsonl -├── internlm2_7b_qlora_colorist_e5_copy.py -└── Shanghai_AI_Laboratory - └── internlm2-chat-7b - ├── config.json - ├── configuration_internlm2.py - ├── configuration.json - ├── generation_config.json - ├── modeling_internlm2.py - ├── pytorch_model-00001-of-00008.bin - ├── pytorch_model-00002-of-00008.bin - ├── pytorch_model-00003-of-00008.bin - ├── pytorch_model-00004-of-00008.bin - ├── pytorch_model-00005-of-00008.bin - ├── pytorch_model-00006-of-00008.bin - ├── pytorch_model-00007-of-00008.bin - ├── pytorch_model-00008-of-00008.bin - ├── pytorch_model.bin.index.json - ├── README.md - ├── special_tokens_map.json - ├── tokenization_internlm2_fast.py - ├── tokenization_internlm2.py - ├── tokenizer_config.json - └── tokenizer.model -``` - -## 修改配置文件 - -在这一步中，我们需要修改待微调模型路径和数据路径为本地路径，并且修改数据集加载方式。 -此外，由于复制得到的配置文件是基于基座（Base）模型的，所以还需要修改 `prompt_template` 以适配对话（Chat）模型。 - -```diff -####################################################################### -# PART 1 Settings # -####################################################################### -# Model -- pretrained_model_name_or_path = 'internlm/internlm2-7b' -+ pretrained_model_name_or_path = './Shanghai_AI_Laboratory/internlm2-chat-7b' - -# Data -- data_path = 'burkelibbey/colors' -+ data_path = './colors/train.jsonl' -- prompt_template = PROMPT_TEMPLATE.default -+ prompt_template = PROMPT_TEMPLATE.internlm2_chat - -... -####################################################################### -# PART 3 Dataset & Dataloader # -####################################################################### -train_dataset = dict( - type=process_hf_dataset, -- dataset=dict(type=load_dataset, path=data_path), -+ dataset=dict(type=load_dataset, path='json', data_files=dict(train=data_path)), - tokenizer=tokenizer, - max_length=max_length, - dataset_map_fn=colors_map_fn, - template_map_fn=dict( - type=template_map_fn_factory, template=prompt_template), - remove_unused_columns=True, - shuffle_before_pack=True, - pack_to_max_length=pack_to_max_length) -``` - -因此在这一步中，修改了 `pretrained_model_name_or_path`、`data_path`、`prompt_template` 以及 `train_dataset` 中的 `dataset` 字段。 - -## 启动微调 - -在完成上述操作后，便可以使用下面的指令启动微调任务了。 - -```bash -# 单机单卡 -xtuner train ./internlm2_7b_qlora_colorist_e5_copy.py -# 单机多卡 -NPROC_PER_NODE=${GPU_NUM} xtuner train ./internlm2_7b_qlora_colorist_e5_copy.py -# slurm 情况 -srun ${SRUN_ARGS} xtuner train ./internlm2_7b_qlora_colorist_e5_copy.py --launcher slurm -``` - -正确输出的训练日志应类似如下所示： - -```text -01/29 21:35:34 - mmengine - INFO - Iter(train) [ 10/720] lr: 9.0001e-05 eta: 0:31:46 time: 2.6851 data_time: 0.0077 memory: 12762 loss: 2.6900 -01/29 21:36:02 - mmengine - INFO - Iter(train) [ 20/720] lr: 1.9000e-04 eta: 0:32:01 time: 2.8037 data_time: 0.0071 memory: 13969 loss: 2.6049 grad_norm: 0.9361 -01/29 21:36:29 - mmengine - INFO - Iter(train) [ 30/720] lr: 1.9994e-04 eta: 0:31:24 time: 2.7031 data_time: 0.0070 memory: 13969 loss: 2.5795 grad_norm: 0.9361 -01/29 21:36:57 - mmengine - INFO - Iter(train) [ 40/720] lr: 1.9969e-04 eta: 0:30:55 time: 2.7247 data_time: 0.0069 memory: 13969 loss: 2.3352 grad_norm: 0.8482 -01/29 21:37:24 - mmengine - INFO - Iter(train) [ 50/720] lr: 1.9925e-04 eta: 0:30:28 time: 2.7286 data_time: 0.0068 memory: 13969 loss: 2.2816 grad_norm: 0.8184 -01/29 21:37:51 - mmengine - INFO - Iter(train) [ 60/720] lr: 1.9863e-04 eta: 0:29:58 time: 2.7048 data_time: 0.0069 memory: 13969 loss: 2.2040 grad_norm: 0.8184 -01/29 21:38:18 - mmengine - INFO - Iter(train) [ 70/720] lr: 1.9781e-04 eta: 0:29:31 time: 2.7302 data_time: 0.0068 memory: 13969 loss: 2.1912 grad_norm: 0.8460 -01/29 21:38:46 - mmengine - INFO - Iter(train) [ 80/720] lr: 1.9681e-04 eta: 0:29:05 time: 2.7338 data_time: 0.0069 memory: 13969 loss: 2.1512 grad_norm: 0.8686 -01/29 21:39:13 - mmengine - INFO - Iter(train) [ 90/720] lr: 1.9563e-04 eta: 0:28:36 time: 2.7047 data_time: 0.0068 memory: 13969 loss: 2.0653 grad_norm: 0.8686 -01/29 21:39:40 - mmengine - INFO - Iter(train) [100/720] lr: 1.9426e-04 eta: 0:28:09 time: 2.7383 data_time: 0.0070 memory: 13969 loss: 1.9819 grad_norm: 0.9127 -``` - -在训练开始前，可以看到模型的输出如下所示： - -```text -2024/01/29 21:34:58 - mmengine - INFO - before_train in EvaluateChatHook. -2024/01/29 21:35:03 - mmengine - INFO - Sample output: -<|im_start|>system -You are a professional color designer. Please provide the corresponding colors based on the description of Human. -<|im_end|> -<|im_start|>user -请给我一个像天空一样清澈透明的蓝色。<|im_end|> -<|im_start|>assistant -为了匹配您所描述的“像天空一样清澈透明的蓝色”，我建议您选择一种名为“天蓝”（Cerulean）的颜色。这种颜色通常被用来代表天空、海洋和清澈的水域，它具有明亮 - -2024/01/29 21:35:07 - mmengine - INFO - Sample output: -<|im_start|>system -You are a professional color designer. Please provide the corresponding colors based on the description of Human. -<|im_end|> -<|im_start|>user -Please give me a clear blue like the sky.<|im_end|> -<|im_start|>assistant -The color you're describing is a clear, bright blue that resembles the color of the sky on a sunny day. This color is often referred to as "sky blue" or "cerulean blue." Here are some specific color codes and names that -``` - -而在训练完全完成后，可以观察到模型的输出如下所示： - -```text -2024/01/29 22:08:07 - mmengine - INFO - Sample output: -<|im_start|>system -You are a professional color designer. Please provide the corresponding colors based on the description of Human. -<|im_end|> -<|im_start|>user -请给我一个像天空一样清澈透明的蓝色。<|im_end|> -<|im_start|>assistant -#1099ee<|im_end|> - -2024/01/29 22:08:08 - mmengine - INFO - Sample output: -<|im_start|>system -You are a professional color designer. Please provide the corresponding colors based on the description of Human. -<|im_end|> -<|im_start|>user -Please give me a clear blue like the sky.<|im_end|> -<|im_start|>assistant -#0066dd<|im_end|> -``` - -模型输出的颜色如下所示： - -- 天空一样清澈透明的蓝色：![天空一样清澈透明的蓝色](https://img.shields.io/badge/天空一样清澈透明的蓝色-1099EE) -- A clear blue like the sky: ![A clear blue like the sky](https://img.shields.io/badge/A_clear_blue_like_the_sky-0066DD) - -不难发现，模型在经过训练后，其输出已经完全与数据集内容所对齐了。 - -## 模型转换 + LoRA 合并 - -在训练完成后，我们会得到几个 `.pth` 文件，这些文件存储了 QLoRA 算法训练过程所更新的参数，而**不是**模型的全部参数。因此我们需要将这些 `.pth` 文件转换为 HuggingFace 格式，并合并入原始的语言模型权重中。 - -### 模型转换 - -XTuner 已经集成好了将模型转换为 HuggingFace 格式的工具，我们只需要执行 - -```bash -# 创建存放 hf 格式参数的目录 -mkdir work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720_hf - -# 转换格式 -xtuner convert pth_to_hf internlm2_7b_qlora_colorist_e5_copy.py \ - work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720.pth \ - work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720_hf -``` - -该条转换命令将会根据配置文件 `internlm2_7b_qlora_colorist_e5_copy.py` 的内容，将 `work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720.pth` 转换为 hf 格式，并保存在 `work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720_hf` 位置。 - -### LoRA 合并 - -XTuner 也已经集成好了合并 LoRA 权重的工具，我们只需执行如下指令： - -```bash -# 创建存放合并后的参数的目录 -mkdir work_dirs/internlm2_7b_qlora_colorist_e5_copy/merged - -# 合并参数 -xtuner convert merge Shanghai_AI_Laboratory/internlm2-chat-7b \ - work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720_hf \ - work_dirs/internlm2_7b_qlora_colorist_e5_copy/merged \ - --max-shard-size 2GB -``` - -与转换命令类似，该条合并参数命令会读取原始参数路径 `Shanghai_AI_Laboratory/internlm2-chat-7b` 以及转换为 hf 格式的部分参数路径 `work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720_hf`，将两部分参数合并后保存于 `work_dirs/internlm2_7b_qlora_colorist_e5_copy/merged`，其中每个参数切片的最大文件大小为 2GB。 - -## 与模型对话 - -在合并权重后，为了更好地体会到模型的能力，XTuner 也集成了与模型对话的工具。通过如下命令，便可以启动一个与模型对话的简易 Demo。 - -```bash -xtuner chat work_dirs/internlm2_7b_qlora_colorist_e5_copy/merged \ - --prompt-template internlm2_chat \ - --system-template colorist -``` - -当然，我们也可以选择不合并权重，而是直接与 LLM + LoRA Adapter 进行对话，我们只需要执行如下指令： - -```bash -xtuner chat Shanghai_AI_Laboratory/internlm2-chat-7b - --adapter work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720_hf \ - --prompt-template internlm2_chat \ - --system-template colorist -``` - -其中 `work_dirs/internlm2_7b_qlora_colorist_e5_copy/merged` 是合并后的权重路径，`--prompt-template internlm2_chat` 指定了对话模板为 InternLM2-Chat，`--system-template colorist` 则是指定了与模型对话时的 System Prompt 为 Colorist 数据集所要求的模板。 - -以下是一个例子： - -```text -double enter to end input (EXIT: exit chat, RESET: reset history) >>> 宁静而又相当明亮的浅天蓝色，介于天蓝色和婴儿蓝之间，因其亮度而带有一丝轻微的荧光感。 - -#66ccff<|im_end|> -``` - -其颜色如下所示： - -宁静而又相当明亮的浅天蓝色，介于天蓝色和婴儿蓝之间，因其亮度而带有一丝轻微的荧光感。：![#66ccff](https://img.shields.io/badge/宁静而又相当明亮的浅天蓝色，介于天蓝色和婴儿蓝之间，因其亮度而带有一丝轻微的荧光感。-66CCFF) diff --git a/docs/zh_cn/get_started/quickstart.rst b/docs/zh_cn/get_started/quickstart.rst new file mode 100644 index 000000000..4bec2a5ac --- /dev/null +++ b/docs/zh_cn/get_started/quickstart.rst @@ -0,0 +1,415 @@ +快速上手 +======== + +本节中，我们将演示如何使用 XTuner 微调模型，帮助您快速上手 XTuner。 + +在成功安装 XTuner +后，便可以开始进行模型的微调。在本节中，我们将演示如何使用 XTuner，应用 +QLoRA 算法在 Colorist 数据集上微调 InternLM2-Chat-7B。 + +Colorist 数据集（\ `HuggingFace +链接 `__\ ；\ `ModelScope +链接 `__\ ）是一个根据颜色描述提供颜色选择与建议的数据集，经过该数据集微调的模型可以做到根据用户对于颜色的描述，从而给出16进制下的颜色编码，如用户输入“宁静而又相当明亮的浅天蓝色，介于天蓝色和婴儿蓝之间，因其亮度而带有一丝轻微的荧光感。”，模型输出 +|image1|\ ，该颜色很符合用户的描述。以下是该数据集的几条样例数据： + ++-----------------------+-----------------------+-------------------+ +| 英文描述 | 中文描述 | 颜色 | ++=======================+=======================+===================+ +| Light Sky Blue: A | 浅天蓝色 | #66ccff: |image8| | +| calming, fairly | ：一种介于天蓝和婴儿 | | +| bright color that | 蓝之间的平和、相当明 | | +| falls between sky | 亮的颜色，由于明亮而 | | +| blue and baby blue, | 带有一丝轻微的荧光。 | | +| with a hint of slight | | | +| fluorescence due to | | | +| its brightness. | | | ++-----------------------+-----------------------+-------------------+ +| Bright red: This is a | 鲜红色： | #ee0000: |image9| | +| very vibrant, | 这是一种非常鲜 | | +| saturated and vivid | 艳、饱和、生动的红色 | | +| shade of red, | ，类似成熟苹果或新鲜 | | +| resembling the color | 血液的颜色。它是标准 | | +| of ripe apples or | RGB | | +| fresh blood. It is as | 调色板上的红色，不含 | | +| red as you can get on | 任何蓝色或绿色元素。 | | +| a standard RGB color | | | +| palette, with no | | | +| elements of either | | | +| blue or green. | | | ++-----------------------+-----------------------+-------------------+ +| Bright Turquoise: | 明亮的绿松石 | #00ffcc: | +| This color mixes the | 色：这种颜色融合了鲜 | |image10| | +| freshness of bright | 绿色的清新和淡蓝色的 | | +| green with the | 宁静，呈现出一种充满 | | +| tranquility of light | 活力的绿松石色调。它 | | +| blue, leading to a | 让人联想到热带水域。 | | +| vibrant shade of | | | +| turquoise. It is | | | +| reminiscent of | | | +| tropical waters. | | | ++-----------------------+-----------------------+-------------------+ + +准备模型权重 +------------ + +在微调模型前，首先要准备待微调模型的权重。 + +.. _从-huggingface-下载-1: + +从 HuggingFace 下载 +~~~~~~~~~~~~~~~~~~~ + +.. code:: bash + + pip install -U huggingface_hub + + # 拉取模型至 Shanghai_AI_Laboratory/internlm2-chat-7b + huggingface-cli download internlm/internlm2-chat-7b \ + --local-dir Shanghai_AI_Laboratory/internlm2-chat-7b \ + --local-dir-use-symlinks False \ + --resume-download + +.. _从-modelscope-下载-1: + +从 ModelScope 下载 +~~~~~~~~~~~~~~~~~~ + +由于从 HuggingFace +拉取模型权重，可能存在下载过程不稳定、下载速度过慢等问题。因此在下载过程遇到网络问题时，我们则可以选择从 +ModelScope 下载 InternLM2-Chat-7B 的权重。 + +.. code:: bash + + pip install -U modelscope + + # 拉取模型至当前目录 + python -c "from modelscope import snapshot_download; snapshot_download('Shanghai_AI_Laboratory/internlm2-chat-7b', cache_dir='.')" + +在完成下载后，便可以开始准备微调数据集了。 + +此处附上 HuggingFace 链接与 ModelScope 链接： + +- HuggingFace + 链接位于：\ https://huggingface.co/internlm/internlm2-chat-7b + +- ModelScope + 链接位于：\ https://modelscope.cn/models/Shanghai_AI_Laboratory/internlm2-chat-7b/summary + +准备微调数据集 +-------------- + +接下来，我们需要准备微调数据集。 + +.. _从-huggingface-下载-2: + +从 HuggingFace 下载 +~~~~~~~~~~~~~~~~~~~ + +.. code:: bash + + git clone https://huggingface.co/datasets/burkelibbey/colors + +.. _从-modelscope-下载-2: + +从 ModelScope 下载 +~~~~~~~~~~~~~~~~~~ + +由于相同的问题，因此我们可以选择从 ModelScope 下载所需要的微调数据集。 + +.. code:: bash + + git clone https://www.modelscope.cn/datasets/fanqiNO1/colors.git + +此处附上 HuggingFace 链接与 ModelScope 链接： + +- HuggingFace + 链接位于：\ https://huggingface.co/datasets/burkelibbey/colors + +- ModelScope 链接位于：\ https://modelscope.cn/datasets/fanqiNO1/colors + +准备配置文件 +------------ + +XTuner 提供了多个开箱即用的配置文件，可以通过 ``xtuner list-cfg`` +查看。我们执行如下指令，以复制一个配置文件到当前目录。 + +.. code:: bash + + xtuner copy-cfg internlm2_7b_qlora_colorist_e5 . + +配置文件名的解释： + +======== ============================== +配置文件 internlm2_7b_qlora_colorist_e5 +======== ============================== +模型名 internlm2_7b +使用算法 qlora +数据集 colorist +训练时长 5 epochs +======== ============================== + +此时该目录文件结构应如下所示： + +.. code:: bash + + . + ├── colors + │ ├── colors.json + │ ├── dataset_infos.json + │ ├── README.md + │ └── train.jsonl + ├── internlm2_7b_qlora_colorist_e5_copy.py + └── Shanghai_AI_Laboratory + └── internlm2-chat-7b + ├── config.json + ├── configuration_internlm2.py + ├── configuration.json + ├── generation_config.json + ├── modeling_internlm2.py + ├── pytorch_model-00001-of-00008.bin + ├── pytorch_model-00002-of-00008.bin + ├── pytorch_model-00003-of-00008.bin + ├── pytorch_model-00004-of-00008.bin + ├── pytorch_model-00005-of-00008.bin + ├── pytorch_model-00006-of-00008.bin + ├── pytorch_model-00007-of-00008.bin + ├── pytorch_model-00008-of-00008.bin + ├── pytorch_model.bin.index.json + ├── README.md + ├── special_tokens_map.json + ├── tokenization_internlm2_fast.py + ├── tokenization_internlm2.py + ├── tokenizer_config.json + └── tokenizer.model + +修改配置文件 +------------ + +| 在这一步中，我们需要修改待微调模型路径和数据路径为本地路径，并且修改数据集加载方式。 +| 此外，由于复制得到的配置文件是基于基座（Base）模型的，所以还需要修改 + ``prompt_template`` 以适配对话（Chat）模型。 + +.. code:: diff + + ####################################################################### + # PART 1 Settings # + ####################################################################### + # Model + - pretrained_model_name_or_path = 'internlm/internlm2-7b' + + pretrained_model_name_or_path = './Shanghai_AI_Laboratory/internlm2-chat-7b' + + # Data + - data_path = 'burkelibbey/colors' + + data_path = './colors/train.jsonl' + - prompt_template = PROMPT_TEMPLATE.default + + prompt_template = PROMPT_TEMPLATE.internlm2_chat + + ... + ####################################################################### + # PART 3 Dataset & Dataloader # + ####################################################################### + train_dataset = dict( + type=process_hf_dataset, + - dataset=dict(type=load_dataset, path=data_path), + + dataset=dict(type=load_dataset, path='json', data_files=dict(train=data_path)), + tokenizer=tokenizer, + max_length=max_length, + dataset_map_fn=colors_map_fn, + template_map_fn=dict( + type=template_map_fn_factory, template=prompt_template), + remove_unused_columns=True, + shuffle_before_pack=True, + pack_to_max_length=pack_to_max_length) + +因此在这一步中，修改了 +``pretrained_model_name_or_path``\ 、\ ``data_path``\ 、\ ``prompt_template`` +以及 ``train_dataset`` 中的 ``dataset`` 字段。 + +启动微调 +-------- + +在完成上述操作后，便可以使用下面的指令启动微调任务了。 + +.. code:: bash + + # 单机单卡 + xtuner train ./internlm2_7b_qlora_colorist_e5_copy.py + # 单机多卡 + NPROC_PER_NODE=${GPU_NUM} xtuner train ./internlm2_7b_qlora_colorist_e5_copy.py + # slurm 情况 + srun ${SRUN_ARGS} xtuner train ./internlm2_7b_qlora_colorist_e5_copy.py --launcher slurm + +正确输出的训练日志应类似如下所示： + +.. code:: text + + 01/29 21:35:34 - mmengine - INFO - Iter(train) [ 10/720] lr: 9.0001e-05 eta: 0:31:46 time: 2.6851 data_time: 0.0077 memory: 12762 loss: 2.6900 + 01/29 21:36:02 - mmengine - INFO - Iter(train) [ 20/720] lr: 1.9000e-04 eta: 0:32:01 time: 2.8037 data_time: 0.0071 memory: 13969 loss: 2.6049 grad_norm: 0.9361 + 01/29 21:36:29 - mmengine - INFO - Iter(train) [ 30/720] lr: 1.9994e-04 eta: 0:31:24 time: 2.7031 data_time: 0.0070 memory: 13969 loss: 2.5795 grad_norm: 0.9361 + 01/29 21:36:57 - mmengine - INFO - Iter(train) [ 40/720] lr: 1.9969e-04 eta: 0:30:55 time: 2.7247 data_time: 0.0069 memory: 13969 loss: 2.3352 grad_norm: 0.8482 + 01/29 21:37:24 - mmengine - INFO - Iter(train) [ 50/720] lr: 1.9925e-04 eta: 0:30:28 time: 2.7286 data_time: 0.0068 memory: 13969 loss: 2.2816 grad_norm: 0.8184 + 01/29 21:37:51 - mmengine - INFO - Iter(train) [ 60/720] lr: 1.9863e-04 eta: 0:29:58 time: 2.7048 data_time: 0.0069 memory: 13969 loss: 2.2040 grad_norm: 0.8184 + 01/29 21:38:18 - mmengine - INFO - Iter(train) [ 70/720] lr: 1.9781e-04 eta: 0:29:31 time: 2.7302 data_time: 0.0068 memory: 13969 loss: 2.1912 grad_norm: 0.8460 + 01/29 21:38:46 - mmengine - INFO - Iter(train) [ 80/720] lr: 1.9681e-04 eta: 0:29:05 time: 2.7338 data_time: 0.0069 memory: 13969 loss: 2.1512 grad_norm: 0.8686 + 01/29 21:39:13 - mmengine - INFO - Iter(train) [ 90/720] lr: 1.9563e-04 eta: 0:28:36 time: 2.7047 data_time: 0.0068 memory: 13969 loss: 2.0653 grad_norm: 0.8686 + 01/29 21:39:40 - mmengine - INFO - Iter(train) [100/720] lr: 1.9426e-04 eta: 0:28:09 time: 2.7383 data_time: 0.0070 memory: 13969 loss: 1.9819 grad_norm: 0.9127 + +在训练开始前，可以看到模型的输出如下所示： + +.. code:: text + + 2024/01/29 21:34:58 - mmengine - INFO - before_train in EvaluateChatHook. + 2024/01/29 21:35:03 - mmengine - INFO - Sample output: + <|im_start|>system + You are a professional color designer. Please provide the corresponding colors based on the description of Human. + <|im_end|> + <|im_start|>user + 请给我一个像天空一样清澈透明的蓝色。<|im_end|> + <|im_start|>assistant + 为了匹配您所描述的“像天空一样清澈透明的蓝色”，我建议您选择一种名为“天蓝”（Cerulean）的颜色。这种颜色通常被用来代表天空、海洋和清澈的水域，它具有明亮 + + 2024/01/29 21:35:07 - mmengine - INFO - Sample output: + <|im_start|>system + You are a professional color designer. Please provide the corresponding colors based on the description of Human. + <|im_end|> + <|im_start|>user + Please give me a clear blue like the sky.<|im_end|> + <|im_start|>assistant + The color you're describing is a clear, bright blue that resembles the color of the sky on a sunny day. This color is often referred to as "sky blue" or "cerulean blue." Here are some specific color codes and names that + +而在训练完全完成后，可以观察到模型的输出如下所示： + +.. code:: text + + 2024/01/29 22:08:07 - mmengine - INFO - Sample output: + <|im_start|>system + You are a professional color designer. Please provide the corresponding colors based on the description of Human. + <|im_end|> + <|im_start|>user + 请给我一个像天空一样清澈透明的蓝色。<|im_end|> + <|im_start|>assistant + #1099ee<|im_end|> + + 2024/01/29 22:08:08 - mmengine - INFO - Sample output: + <|im_start|>system + You are a professional color designer. Please provide the corresponding colors based on the description of Human. + <|im_end|> + <|im_start|>user + Please give me a clear blue like the sky.<|im_end|> + <|im_start|>assistant + #0066dd<|im_end|> + +模型输出的颜色如下所示： + +- 天空一样清澈透明的蓝色：\ |image11| + +- A clear blue like the sky: |image12| + +不难发现，模型在经过训练后，其输出已经完全与数据集内容所对齐了。 + +.. _模型转换--lora-合并: + +模型转换 + LoRA 合并 +-------------------- + +在训练完成后，我们会得到几个 ``.pth`` 文件，这些文件存储了 QLoRA +算法训练过程所更新的参数，而\ **不是**\ 模型的全部参数。因此我们需要将这些 +``.pth`` 文件转换为 HuggingFace 格式，并合并入原始的语言模型权重中。 + +模型转换 +~~~~~~~~ + +XTuner 已经集成好了将模型转换为 HuggingFace 格式的工具，我们只需要执行 + +.. code:: bash + + # 创建存放 hf 格式参数的目录 + mkdir work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720_hf + + # 转换格式 + xtuner convert pth_to_hf internlm2_7b_qlora_colorist_e5_copy.py \ + work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720.pth \ + work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720_hf + +该条转换命令将会根据配置文件 ``internlm2_7b_qlora_colorist_e5_copy.py`` +的内容，将 +``work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720.pth`` 转换为 hf +格式，并保存在 +``work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720_hf`` 位置。 + +LoRA 合并 +~~~~~~~~~ + +XTuner 也已经集成好了合并 LoRA 权重的工具，我们只需执行如下指令： + +.. code:: bash + + # 创建存放合并后的参数的目录 + mkdir work_dirs/internlm2_7b_qlora_colorist_e5_copy/merged + + # 合并参数 + xtuner convert merge Shanghai_AI_Laboratory/internlm2-chat-7b \ + work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720_hf \ + work_dirs/internlm2_7b_qlora_colorist_e5_copy/merged \ + --max-shard-size 2GB + +与转换命令类似，该条合并参数命令会读取原始参数路径 +``Shanghai_AI_Laboratory/internlm2-chat-7b`` 以及转换为 hf +格式的部分参数路径 +``work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720_hf``\ ，将两部分参数合并后保存于 +``work_dirs/internlm2_7b_qlora_colorist_e5_copy/merged``\ ，其中每个参数切片的最大文件大小为 +2GB。 + +与模型对话 +---------- + +在合并权重后，为了更好地体会到模型的能力，XTuner +也集成了与模型对话的工具。通过如下命令，便可以启动一个与模型对话的简易 +Demo。 + +.. code:: bash + + xtuner chat work_dirs/internlm2_7b_qlora_colorist_e5_copy/merged \ + --prompt-template internlm2_chat \ + --system-template colorist + +当然，我们也可以选择不合并权重，而是直接与 LLM + LoRA Adapter +进行对话，我们只需要执行如下指令： + +.. code:: bash + + xtuner chat Shanghai_AI_Laboratory/internlm2-chat-7b + --adapter work_dirs/internlm2_7b_qlora_colorist_e5_copy/iter_720_hf \ + --prompt-template internlm2_chat \ + --system-template colorist + +其中 ``work_dirs/internlm2_7b_qlora_colorist_e5_copy/merged`` +是合并后的权重路径，\ ``--prompt-template internlm2_chat`` +指定了对话模板为 InternLM2-Chat，\ ``--system-template colorist`` +则是指定了与模型对话时的 System Prompt 为 Colorist 数据集所要求的模板。 + +以下是一个例子： + +.. code:: text + + double enter to end input (EXIT: exit chat, RESET: reset history) >>> 宁静而又相当明亮的浅天蓝色，介于天蓝色和婴儿蓝之间，因其亮度而带有一丝轻微的荧光感。 + + #66ccff<|im_end|> + +其颜色如下所示： + +宁静而又相当明亮的浅天蓝色，介于天蓝色和婴儿蓝之间，因其亮度而带有一丝轻微的荧光感。：\ |image13| + +.. |image1| image:: https://img.shields.io/badge/%2366ccff-66CCFF +.. |image2| image:: https://img.shields.io/badge/%2366ccff-66CCFF +.. |image3| image:: https://img.shields.io/badge/%23ee0000-EE0000 +.. |image4| image:: https://img.shields.io/badge/%2300ffcc-00FFCC +.. |image5| image:: https://img.shields.io/badge/%2366ccff-66CCFF +.. |image6| image:: https://img.shields.io/badge/%23ee0000-EE0000 +.. |image7| image:: https://img.shields.io/badge/%2300ffcc-00FFCC +.. |image8| image:: https://img.shields.io/badge/%2366ccff-66CCFF +.. |image9| image:: https://img.shields.io/badge/%23ee0000-EE0000 +.. |image10| image:: https://img.shields.io/badge/%2300ffcc-00FFCC +.. |image11| image:: https://img.shields.io/badge/天空一样清澈透明的蓝色-1099EE +.. |image12| image:: https://img.shields.io/badge/A_clear_blue_like_the_sky-0066DD +.. |image13| image:: https://img.shields.io/badge/宁静而又相当明亮的浅天蓝色，介于天蓝色和婴儿蓝之间，因其亮度而带有一丝轻微的荧光感。-66CCFF diff --git a/docs/zh_cn/index.rst b/docs/zh_cn/index.rst index bcf7769ef..d8be3ceb9 100644 --- a/docs/zh_cn/index.rst +++ b/docs/zh_cn/index.rst @@ -34,15 +34,15 @@ :maxdepth: 2 :caption: 开始使用 - get_started/overview.md - get_started/installation.md - get_started/quickstart.md + get_started/overview.rst + get_started/installation.rst + get_started/quickstart.rst .. toctree:: :maxdepth: 2 :caption: 准备 - preparation/pretrained_model.md + preparation/pretrained_model.rst preparation/custom_sft_dataset.md preparation/custom_pretrain_dataset.md preparation/custom_agent_dataset.md @@ -56,7 +56,7 @@ training/custom_sft_dataset.md training/custom_pretrain_dataset.md training/custom_agent_dataset.md - training/multi_modal_dataset.md + training/multi_modal_dataset.rst training/open_source_dataset.md training/accelerate.md diff --git a/docs/zh_cn/preparation/pretrained_model.md b/docs/zh_cn/preparation/pretrained_model.md deleted file mode 100644 index db6c104c5..000000000 --- a/docs/zh_cn/preparation/pretrained_model.md +++ /dev/null @@ -1,104 +0,0 @@ -# 准备预训练模型权重 - -`HuggingFace` 和 `ModelScope` 提供了多种下载预训练模型权重的方法，本节将以下载 internlm2-chat-7b 为例，介绍如何快速下载预训练模型的权重。 - -> \[!IMPORTANT\] -> 若 HuggingFace 访问受限，请优先考虑使用 ModelScope 进行下载 - -## \[推荐\] 方法 1：利用 `snapshot_download` - -### HuggingFace - -`huggingface_hub.snapshot_download` 支持下载特定的 HuggingFace Hub 模型权重，并且允许多线程。您可以利用下列代码并行下载模型权重： - -```python -from huggingface_hub import snapshot_download - -snapshot_download(repo_id='internlm/internlm2-chat-7b', local_dir='./internlm2-chat-7b', max_workers=20) -``` - -其中，`repo_id` 表示模型在 HuggingFace Hub 的名字、`local_dir` 表示期望存储到的本地路径、`max_workers` 表示下载的最大并行数。 - -**注意事项** - -1. 如果未指定 `local_dir`，则将下载至 HuggingFace 的默认 cache 路径中（`~/.cache/huggingface/hub`）。若要修改默认 cache 路径，需要修改相关环境变量： - - ```shell - export HF_HOME=XXXX # 默认为 `~/.cache/huggingface/` - ``` - -2. 如果觉得下载较慢（例如无法达到最大带宽等情况），可以尝试设置 `export HF_HUB_ENABLE_HF_TRANSFER=1` 以获得更高的下载速度。 - -3. 关于环境变量的更多用法，可阅读 [这里](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/environment_variables)。 - -### ModelScope - -`modelscope.snapshot_download` 支持下载指定的模型权重，您可以利用下列命令下载模型： - -```python -from modelscope import snapshot_download - -snapshot_download(model_id='Shanghai_AI_Laboratory/internlm2-chat-7b', cache_dir='./internlm2-chat-7b') -``` - -其中，`model_id` 表示模型在 ModelScope 模型库的名字、`cache_dir` 表示期望存储到的本地路径。 - -**注意事项** - -1. 如果未指定 `cache_dir`，则将下载至 ModelScope 的默认 cache 路径中（`~/.cache/huggingface/hub`）。 - - 若要修改默认 cache 路径，需要修改相关环境变量： - - ```shell - export MODELSCOPE_CACHE=XXXX # 默认为 ~/.cache/modelscope/hub/ - ``` - -2. `modelscope.snapshot_download` 不支持多线程并行下载。 - -## 方法 2：利用 Git LFS - -HuggingFace 和 ModelScope 的远程模型仓库就是一个由 Git LFS 管理的 Git 仓库。因此，我们可以利用 `git clone` 完成权重的下载： - -```shell -git lfs install -# From HuggingFace -git clone https://huggingface.co/internlm/internlm2-chat-7b -# From ModelScope -git clone https://www.modelscope.cn/Shanghai_AI_Laboratory/internlm2-chat-7b.git -``` - -## 方法 3：利用 `AutoModelForCausalLM.from_pretrained` - -`AutoModelForCausalLM.from_pretrained` 在初始化模型时，将尝试连接远程仓库并自动下载模型权重。因此，我们可以利用这一特性下载模型权重。 - -### HuggingFace - -```python -from transformers import AutoModelForCausalLM, AutoTokenizer - -model = AutoModelForCausalLM.from_pretrained('internlm/internlm2-chat-7b', trust_remote_code=True) -tokenizer = AutoTokenizer.from_pretrained('internlm/internlm2-chat-7b', trust_remote_code=True) -``` - -此时模型将会下载至 HuggingFace 的 cache 路径中（默认为`~/.cache/huggingface/hub`）。 - -若要修改默认存储路径，需要修改相关环境变量： - -```shell -export HF_HOME=XXXX # 默认为 `~/.cache/huggingface/` -``` - -### ModelScope - -```python -from modelscope import AutoModelForCausalLM, AutoTokenizer - -model = AutoModelForCausalLM.from_pretrained('Shanghai_AI_Laboratory/internlm2-chat-7b', trust_remote_code=True) -tokenizer = AutoTokenizer.from_pretrained('Shanghai_AI_Laboratory/internlm2-chat-7b', trust_remote_code=True) -``` - -此时模型将会下载至 ModelScope 的 cache 路径中（默认为`~/.cache/modelscope/hub`）。若要修改默认存储路径，需要修改相关环境变量： - -```shell -export MODELSCOPE_CACHE=XXXX # 默认为 ~/.cache/modelscope/hub/ -``` diff --git a/docs/zh_cn/preparation/pretrained_model.rst b/docs/zh_cn/preparation/pretrained_model.rst new file mode 100644 index 000000000..50aa39488 --- /dev/null +++ b/docs/zh_cn/preparation/pretrained_model.rst @@ -0,0 +1,138 @@ +准备预训练模型权重 +================== + +``HuggingFace`` 和 ``ModelScope`` +提供了多种下载预训练模型权重的方法，本节将以下载 internlm2-chat-7b +为例，介绍如何快速下载预训练模型的权重。 + + | 若 HuggingFace 访问受限，请优先考虑使用 ModelScope 进行下载 + +.. _推荐-方法-1利用-snapshotdownload: + +[推荐] 方法 1：利用 ``snapshot_download`` +----------------------------------------- + +.. _huggingface-1: + +HuggingFace +~~~~~~~~~~~ + +``huggingface_hub.snapshot_download`` 支持下载特定的 HuggingFace Hub +模型权重，并且允许多线程。您可以利用下列代码并行下载模型权重： + +.. code:: python + + from huggingface_hub import snapshot_download + + snapshot_download(repo_id='internlm/internlm2-chat-7b', local_dir='./internlm2-chat-7b', max_workers=20) + +其中，\ ``repo_id`` 表示模型在 HuggingFace Hub 的名字、\ ``local_dir`` +表示期望存储到的本地路径、\ ``max_workers`` 表示下载的最大并行数。 + +**注意事项** + +1. 如果未指定 ``local_dir``\ ，则将下载至 HuggingFace 的默认 cache + 路径中（\ ``~/.cache/huggingface/hub``\ ）。若要修改默认 cache + 路径，需要修改相关环境变量： + + .. code:: bash + + export HF_HOME=XXXX # 默认为 `~/.cache/huggingface/` + +2. 如果觉得下载较慢（例如无法达到最大带宽等情况），可以尝试设置 + ``export HF_HUB_ENABLE_HF_TRANSFER=1`` 以获得更高的下载速度。 + +3. 关于环境变量的更多用法，可阅读 + `这里 `__\ 。 + +.. _modelscope-1: + +ModelScope +~~~~~~~~~~ + +``modelscope.snapshot_download`` +支持下载指定的模型权重，您可以利用下列命令下载模型： + +.. code:: python + + from modelscope import snapshot_download + + snapshot_download(model_id='Shanghai_AI_Laboratory/internlm2-chat-7b', cache_dir='./internlm2-chat-7b') + +其中，\ ``model_id`` 表示模型在 ModelScope 模型库的名字、\ ``cache_dir`` +表示期望存储到的本地路径。 + +**注意事项** + +1. 如果未指定 ``cache_dir``\ ，则将下载至 ModelScope 的默认 cache + 路径中（\ ``~/.cache/huggingface/hub``\ ）。 + + 若要修改默认 cache 路径，需要修改相关环境变量： + + .. code:: bash + + export MODELSCOPE_CACHE=XXXX # 默认为 ~/.cache/modelscope/hub/ + +2. ``modelscope.snapshot_download`` 不支持多线程并行下载。 + +方法 2：利用 Git LFS +-------------------- + +HuggingFace 和 ModelScope 的远程模型仓库就是一个由 Git LFS 管理的 Git +仓库。因此，我们可以利用 ``git clone`` 完成权重的下载： + +.. code:: bash + + git lfs install + # From HuggingFace + git clone https://huggingface.co/internlm/internlm2-chat-7b + # From ModelScope + git clone https://www.modelscope.cn/Shanghai_AI_Laboratory/internlm2-chat-7b.git + +.. _方法-3利用-automodelforcausallmfrompretrained: + +方法 3：利用 ``AutoModelForCausalLM.from_pretrained`` +----------------------------------------------------- + +``AutoModelForCausalLM.from_pretrained`` +在初始化模型时，将尝试连接远程仓库并自动下载模型权重。因此，我们可以利用这一特性下载模型权重。 + +.. _huggingface-2: + +HuggingFace +~~~~~~~~~~~ + +.. code:: python + + from transformers import AutoModelForCausalLM, AutoTokenizer + + model = AutoModelForCausalLM.from_pretrained('internlm/internlm2-chat-7b', trust_remote_code=True) + tokenizer = AutoTokenizer.from_pretrained('internlm/internlm2-chat-7b', trust_remote_code=True) + +此时模型将会下载至 HuggingFace 的 cache +路径中（默认为\ ``~/.cache/huggingface/hub``\ ）。 + +若要修改默认存储路径，需要修改相关环境变量： + +.. code:: bash + + export HF_HOME=XXXX # 默认为 `~/.cache/huggingface/` + +.. _modelscope-2: + +ModelScope +~~~~~~~~~~ + +.. code:: python + + from modelscope import AutoModelForCausalLM, AutoTokenizer + + model = AutoModelForCausalLM.from_pretrained('Shanghai_AI_Laboratory/internlm2-chat-7b', trust_remote_code=True) + tokenizer = AutoTokenizer.from_pretrained('Shanghai_AI_Laboratory/internlm2-chat-7b', trust_remote_code=True) + +此时模型将会下载至 ModelScope 的 cache +路径中（默认为\ ``~/.cache/modelscope/hub``\ ）。若要修改默认存储路径，需要修改相关环境变量： + +.. code:: bash + + export MODELSCOPE_CACHE=XXXX # 默认为 ~/.cache/modelscope/hub/ diff --git a/docs/zh_cn/training/multi_modal_dataset.md b/docs/zh_cn/training/multi_modal_dataset.md deleted file mode 100644 index 36a180faf..000000000 --- a/docs/zh_cn/training/multi_modal_dataset.md +++ /dev/null @@ -1,231 +0,0 @@ -# 使用多模态数据集训练 (VLM) - -XTuner 支持 LLaVA 图文模型的微调，本文将以 [xtuner/llava-internlm2-7b](https://huggingface.co/xtuner/llava-internlm2-7b) 为例，讲解如何利用 XTuner 快速上手多模态数据集训练，及后续的对话、评测。 - -## 数据准备 - -XTuner 支持 LLaVA 格式数据集的多模态图文预训练、微调。本节将从「LLaVA 开源数据集准备」和「自定义数据集准备」两部分展开介绍。 - -### LLaVA 开源数据集准备 - -#### 数据文件结构 - -``` -./data/llava_data -├── LLaVA-Pretrain -│ ├── blip_laion_cc_sbu_558k.json -│ ├── blip_laion_cc_sbu_558k_meta.json -│ └── images -├── LLaVA-Instruct-150K -│ └── llava_v1_5_mix665k.json -└── llava_images - ├── coco - │ └── train2017 - ├── gqa - │ └── images - ├── ocr_vqa - │ └── images - ├── textvqa - │ └── train_images - └── vg - ├── VG_100K - └── VG_100K_2 -``` - -#### 预训练数据下载 - -LLaVA-Pretrain - -```shell -# Make sure you have git-lfs installed (https://git-lfs.com) -git lfs install -git clone https://huggingface.co/datasets/liuhaotian/LLaVA-Pretrain --depth=1 -``` - -#### 指令微调数据下载 - -1. 文本数据 - - 1. LLaVA-Instruct-150K - - ```shell - # Make sure you have git-lfs installed (https://git-lfs.com) - git lfs install - git clone https://huggingface.co/datasets/liuhaotian/LLaVA-Instruct-150K --depth=1 - ``` - -2. 图片数据 - - 1. COCO (coco): [train2017](http://images.cocodataset.org/zips/train2017.zip) - - 2. GQA (gqa): [images](https://downloads.cs.stanford.edu/nlp/data/gqa/images.zip) - - 3. OCR-VQA (ocr_vqa): [download script](https://drive.google.com/drive/folders/1_GYPY5UkUy7HIcR0zq3ZCFgeZN7BAfm_?usp=sharing) - - 1. ⚠️ OCR-VQA 所下载的图片命名需要利用如下脚本进行处理，以确保所有图片后缀为 `.jpg`！ - - ```shell - #!/bin/bash - ocr_vqa_path="" - - find "$target_dir" -type f | while read file; do - extension="${file##*.}" - if [ "$extension" != "jpg" ] - then - cp -- "$file" "${file%.*}.jpg" - fi - done - ``` - - 4. TextVQA (textvqa): [train_val_images](https://dl.fbaipublicfiles.com/textvqa/images/train_val_images.zip) - - 5. VisualGenome (VG): [part1](https://cs.stanford.edu/people/rak248/VG_100K_2/images.zip), [part2](https://cs.stanford.edu/people/rak248/VG_100K_2/images2.zip) - -### 自定义数据集准备 - -如果用户期望使用自定义数据集进行图文训练，可以参照 LLaVA 开源数据集格式进行准备，具体格式如下： - -```json -[ - { - "image": "xxx/xxx", - "conversations": [ - { - "from": "human", - "value": "\nHello! What's this?" - }, - { - "from": "gpt", - "value": "This is a dog!" - }, - { - "from": "human", - "value": "Is it cute?" - }, - { - "from": "gpt", - "value": "Yes." - } - ] - }, - ... -] -``` - -目前针对自定义数据有一些约束： - -1. `image` 字段表示图片路径，且仅能有一张图片 -2. `conversations` 字段第 0 条的 `value` 需要包括 `` ，以确保图片被正确嵌入。 - -## 训练 - -多模态图文训练一般分为两步：预训练（pretrain）、指令跟随微调（finetune）。`xtuner/llava-internlm2-7b` 对应的配置文件：[预训练](https://github.com/InternLM/xtuner/blob/main/xtuner/configs/llava/internlm2_chat_7b_clip_vit_large_p14_336/pretrain/llava_internlm2_chat_7b_clip_vit_large_p14_336_e1_gpu8_pretrain.py) / [指令跟随微调](https://github.com/InternLM/xtuner/blob/main/xtuner/configs/llava/internlm2_chat_7b_clip_vit_large_p14_336/finetune/llava_internlm2_chat_7b_qlora_clip_vit_large_p14_336_lora_e1_gpu8_finetune.py)，用户可以对其中的模型路径、数据路径进行自定义修改。 - -### 预训练 - -```bash -NPROC_PER_NODE=8 xtuner train llava_internlm2_chat_7b_clip_vit_large_p14_336_e1_gpu8_pretrain --deepspeed deepspeed_zero2 -``` - -训得模型将默认保存在 `./work_dirs/`，用户可以通过命令 `xtuner train --work-dir ${SAVE_PATH}` 指定保存路径。 - -### 指令跟随微调 - -指令跟随微调时，需要载入预训练阶段所得到的 `.pth` 模型，以提供良好的初始化，这一通过在配置文件中的 `pretrained_pth` 指定，用户可以自行修改。 - -```bash -NPROC_PER_NODE=8 xtuner train llava_internlm2_chat_7b_qlora_clip_vit_large_p14_336_lora_e1_gpu8_finetune --deepspeed deepspeed_zero2 -``` - -### 模型转换 - -模型训练后会自动保存成 PTH 模型（例如 `iter_5198.pth`），我们需要利用 `xtuner convert pth_to_hf` 将其转换为 HuggingFace 模型，以便于后续使用。具体命令为： - -```bash -xtuner convert pth_to_hf $FINETUNE_CFG $PTH_PATH $SAVE_PATH -# 例如：xtuner convert pth_to_hf llava_internlm2_chat_7b_qlora_clip_vit_large_p14_336_lora_e1_gpu8_finetune ./iter_5198.pth ./iter_5198_hf -``` - -此时，我们将获得所需要的模型。如果使用默认的微调范式，文件结构应与 [这里](https://huggingface.co/xtuner/llava-internlm2-7b/tree/main) 一致。 - -### 模型合并（可选） - -如果您使用了 LoRA / QLoRA 微调，则模型转换后将得到 adapter 参数，而并不包含原 LLM 参数。如果您期望获得合并后的模型权重，那么可以利用 `xtuner convert merge` ： - -```bash -(LLM) xtuner convert merge $LLM $LLM_ADAPTER $SAVE_PATH -(CLIP) xtuner convert merge $CLIP $CLIP_ADAPTER $SAVE_PATH --is-clip -``` - -## 对话 - -用户可以利用 `xtuner chat` 实现与微调后的多模态图文模型对话。假设模型转换阶段获得的模型路径为 `./iter_5198_hf`，则我们可以利用下列命令实现对话： - -```bash -xtuner chat internlm/internlm2-chat-7b \ - --visual-encoder openai/clip-vit-large-patch14-336 \ - --llava ./iter_5198_hf \ - --prompt-template internlm2_chat \ - --image $IMAGE_PATH -``` - -注意事项 - -- `xtuner chat` 的第一个参数为 LLM 路径或 HuggingFace Hub ID。如果训练阶段 LLM 使用的是 LoRA / QLoRA 微调，则此参数请传入基础 LLM，如 `internlm/internlm2-chat-7b`；如果使用的是全参数微调，则此参数请传入转换（`xtuner convert pth_to_hf`）所得到的模型权重，如 `./iter_5198_hf`。 - -## 评测 - -XTuner 的 LLaVA 模型可以利用 [VLMEvalKit](https://github.com/open-compass/VLMEvalKit) 进行评测，请参考 [这里](https://github.com/open-compass/VLMEvalKit/blob/main/Quickstart.md) 快速上手。 - -同时，为了方便使用，XTuner 内也集成了 MMBench 评测，您可以通过下列命令下载 MMBench 评测数据集： - -``` -wget https://opencompass.openxlab.space/utils/VLMEval/MMBench_DEV_EN.tsv -wget https://opencompass.openxlab.space/utils/VLMEval/MMBench_TEST_EN.tsv -wget https://opencompass.openxlab.space/utils/VLMEval/MMBench_DEV_CN.tsv -wget https://opencompass.openxlab.space/utils/VLMEval/MMBench_TEST_CN.tsv -wget https://opencompass.openxlab.space/utils/VLMEval/CCBench.tsv -``` - -之后，您可以利用下列命令实现评测： - -```bash -xtuner mmbench internlm/internlm2-chat-7b \ - --visual-encoder openai/clip-vit-large-patch14-336 \ - --llava ./iter_5198_hf \ - --prompt-template internlm2_chat \ - --data-path $DATA_PATH \ - --work-dir $RESULT_PATH -``` - -注意事项 - -- `xtuner mmbench` 的第一个参数为 LLM 路径或 HuggingFace Hub ID。如果训练阶段 LLM 使用的是 LoRA / QLoRA 微调，则此参数请传入基础 LLM，如 `internlm/internlm2-chat-7b`；如果使用的是全参数微调，则此参数请传入转换（`xtuner convert pth_to_hf`）所得到的模型权重，如 `./iter_5198_hf`。 -- `$DATA_PATH` 指上一步骤所下载的某一个 tsv 文件，如 `MMBench_DEV_EN.tsv`。 - -评测完成后，若为开发集则会直接打印出结果；若为测试集，则需将 `mmbench_result.xlsx` 提交至 [MMBench 官方](https://mmbench.opencompass.org.cn/home) 完成评测取得精度结果。 - -## FAQ - -### 如何更换 LLM？ - -修改 LLM 的方式与训练单模态的大语言模型类似。 - -1. 修改配置文件中的 `llm_name_or_path` 参数至您期望使用的 LLM，例如 `internlm/internlm2-chat-20b`等。 -2. 修改配置文件中的 `prompt_template` 参数，与您所选择的 LLM 保持对齐。具体选择可参考 [这里](https://github.com/InternLM/xtuner/blob/main/docs/zh_cn/preparation/prompt_template.md)。 - -### ValueError: `bos_token_id` has to be defined when no `input_ids` are provided. - -这是由于老版本 `transformers` 的 LLM `generate` 接口在接受 `inputs_embeds` 输入时，必须传入有效的 `bos_token_id`。结合 PR [transformers#29772](https://github.com/huggingface/transformers/pull/29772) 后可以解决这一问题。 - -在该 PR 被 merge 前，您可以安装 fork 版本的 transformers 来解决这一问题： - -```shell -pip install git+https://github.com/LZHgrla/transformers.git@lzh/fix_bos_token_id -``` - -该 PR 被 merge 后，您可以直接从源码安装主分支 transofmrers 来解决这一问题： - -```shell -pip install git+https://github.com/huggingface/transformers.git -``` diff --git a/docs/zh_cn/training/multi_modal_dataset.rst b/docs/zh_cn/training/multi_modal_dataset.rst new file mode 100644 index 000000000..df6965aa3 --- /dev/null +++ b/docs/zh_cn/training/multi_modal_dataset.rst @@ -0,0 +1,307 @@ +使用多模态数据集训练 (VLM) +========================== + +XTuner 支持 LLaVA 图文模型的微调，本文将以 +`xtuner/llava-internlm2-7b `__ +为例，讲解如何利用 XTuner 快速上手多模态数据集训练，及后续的对话、评测。 + +数据准备 +-------- + +XTuner 支持 LLaVA 格式数据集的多模态图文预训练、微调。本节将从「LLaVA +开源数据集准备」和「自定义数据集准备」两部分展开介绍。 + +LLaVA 开源数据集准备 +~~~~~~~~~~~~~~~~~~~~ + +数据文件结构 +^^^^^^^^^^^^ + +.. code:: + + ./data/llava_data + ├── LLaVA-Pretrain + │ ├── blip_laion_cc_sbu_558k.json + │ ├── blip_laion_cc_sbu_558k_meta.json + │ └── images + ├── LLaVA-Instruct-150K + │ └── llava_v1_5_mix665k.json + └── llava_images + ├── coco + │ └── train2017 + ├── gqa + │ └── images + ├── ocr_vqa + │ └── images + ├── textvqa + │ └── train_images + └── vg + ├── VG_100K + └── VG_100K_2 + +预训练数据下载 +^^^^^^^^^^^^^^ + +LLaVA-Pretrain + +.. code:: bash + + # Make sure you have git-lfs installed (https://git-lfs.com) + git lfs install + git clone https://huggingface.co/datasets/liuhaotian/LLaVA-Pretrain --depth=1 + +指令微调数据下载 +^^^^^^^^^^^^^^^^ + +1. 文本数据 + + 1. LLaVA-Instruct-150K + + .. code:: bash + + # Make sure you have git-lfs installed (https://git-lfs.com) + git lfs install + git clone https://huggingface.co/datasets/liuhaotian/LLaVA-Instruct-150K --depth=1 + +2. 图片数据 + + 1. COCO (coco): + `train2017 `__ + + 2. GQA (gqa): + `images `__ + + 3. OCR-VQA (ocr_vqa): `download + script `__ + + 1. ⚠️ OCR-VQA + 所下载的图片命名需要利用如下脚本进行处理，以确保所有图片后缀为 + ``.jpg``\ ！ + + .. code:: bash + + #!/bin/bash + ocr_vqa_path="" + + find "$target_dir" -type f | while read file; do + extension="${file##*.}" + if [ "$extension" != "jpg" ] + then + cp -- "$file" "${file%.*}.jpg" + fi + done + + 4. TextVQA (textvqa): + `train_val_images `__ + + 5. VisualGenome (VG): + `part1 `__, + `part2 `__ + +自定义数据集准备 +~~~~~~~~~~~~~~~~ + +如果用户期望使用自定义数据集进行图文训练，可以参照 LLaVA +开源数据集格式进行准备，具体格式如下： + +.. code:: json + + [ + { + "image": "xxx/xxx", + "conversations": [ + { + "from": "human", + "value": "\nHello! What's this?" + }, + { + "from": "gpt", + "value": "This is a dog!" + }, + { + "from": "human", + "value": "Is it cute?" + }, + { + "from": "gpt", + "value": "Yes." + } + ] + }, + ... + ] + +目前针对自定义数据有一些约束： + +1. ``image`` 字段表示图片路径，且仅能有一张图片 + +2. ``conversations`` 字段第 0 条的 ``value`` 需要包括 ```` + ，以确保图片被正确嵌入。 + +训练 +---- + +多模态图文训练一般分为两步：预训练（pretrain）、指令跟随微调（finetune）。\ ``xtuner/llava-internlm2-7b`` +对应的配置文件：\ `预训练 `__ +/ +`指令跟随微调 `__\ ，用户可以对其中的模型路径、数据路径进行自定义修改。 + +预训练 +~~~~~~ + +.. code:: bash + + NPROC_PER_NODE=8 xtuner train llava_internlm2_chat_7b_clip_vit_large_p14_336_e1_gpu8_pretrain --deepspeed deepspeed_zero2 + +训得模型将默认保存在 ``./work_dirs/``\ ，用户可以通过命令 +``xtuner train --work-dir ${SAVE_PATH}`` 指定保存路径。 + +指令跟随微调 +~~~~~~~~~~~~ + +指令跟随微调时，需要载入预训练阶段所得到的 ``.pth`` +模型，以提供良好的初始化，这一通过在配置文件中的 ``pretrained_pth`` +指定，用户可以自行修改。 + +.. code:: bash + + NPROC_PER_NODE=8 xtuner train llava_internlm2_chat_7b_qlora_clip_vit_large_p14_336_lora_e1_gpu8_finetune --deepspeed deepspeed_zero2 + +模型转换 +~~~~~~~~ + +模型训练后会自动保存成 PTH 模型（例如 +``iter_5198.pth``\ ），我们需要利用 ``xtuner convert pth_to_hf`` +将其转换为 HuggingFace 模型，以便于后续使用。具体命令为： + +.. code:: bash + + xtuner convert pth_to_hf $FINETUNE_CFG $PTH_PATH $SAVE_PATH + # 例如：xtuner convert pth_to_hf llava_internlm2_chat_7b_qlora_clip_vit_large_p14_336_lora_e1_gpu8_finetune ./iter_5198.pth ./iter_5198_hf + +此时，我们将获得所需要的模型。如果使用默认的微调范式，文件结构应与 +`这里 `__ +一致。 + +.. _模型合并可选）: + +模型合并（可选） +~~~~~~~~~~~~~~~~ + +如果您使用了 LoRA / QLoRA 微调，则模型转换后将得到 adapter +参数，而并不包含原 LLM +参数。如果您期望获得合并后的模型权重，那么可以利用 +``xtuner convert merge`` ： + +.. code:: bash + + (LLM) xtuner convert merge $LLM $LLM_ADAPTER $SAVE_PATH + (CLIP) xtuner convert merge $CLIP $CLIP_ADAPTER $SAVE_PATH --is-clip + +对话 +---- + +用户可以利用 ``xtuner chat`` +实现与微调后的多模态图文模型对话。假设模型转换阶段获得的模型路径为 +``./iter_5198_hf``\ ，则我们可以利用下列命令实现对话： + +.. code:: bash + + xtuner chat internlm/internlm2-chat-7b \ + --visual-encoder openai/clip-vit-large-patch14-336 \ + --llava ./iter_5198_hf \ + --prompt-template internlm2_chat \ + --image $IMAGE_PATH + +注意事项 + +- ``xtuner chat`` 的第一个参数为 LLM 路径或 HuggingFace Hub + ID。如果训练阶段 LLM 使用的是 LoRA / QLoRA 微调，则此参数请传入基础 + LLM，如 + ``internlm/internlm2-chat-7b``\ ；如果使用的是全参数微调，则此参数请传入转换（\ ``xtuner convert pth_to_hf``\ ）所得到的模型权重，如 + ``./iter_5198_hf``\ 。 + +评测 +---- + +XTuner 的 LLaVA 模型可以利用 +`VLMEvalKit `__ +进行评测，请参考 +`这里 `__ +快速上手。 + +同时，为了方便使用，XTuner 内也集成了 MMBench +评测，您可以通过下列命令下载 MMBench 评测数据集： + +.. code:: + + wget https://opencompass.openxlab.space/utils/VLMEval/MMBench_DEV_EN.tsv + wget https://opencompass.openxlab.space/utils/VLMEval/MMBench_TEST_EN.tsv + wget https://opencompass.openxlab.space/utils/VLMEval/MMBench_DEV_CN.tsv + wget https://opencompass.openxlab.space/utils/VLMEval/MMBench_TEST_CN.tsv + wget https://opencompass.openxlab.space/utils/VLMEval/CCBench.tsv + +之后，您可以利用下列命令实现评测： + +.. code:: bash + + xtuner mmbench internlm/internlm2-chat-7b \ + --visual-encoder openai/clip-vit-large-patch14-336 \ + --llava ./iter_5198_hf \ + --prompt-template internlm2_chat \ + --data-path $DATA_PATH \ + --work-dir $RESULT_PATH + +注意事项 + +- ``xtuner mmbench`` 的第一个参数为 LLM 路径或 HuggingFace Hub + ID。如果训练阶段 LLM 使用的是 LoRA / QLoRA 微调，则此参数请传入基础 + LLM，如 + ``internlm/internlm2-chat-7b``\ ；如果使用的是全参数微调，则此参数请传入转换（\ ``xtuner convert pth_to_hf``\ ）所得到的模型权重，如 + ``./iter_5198_hf``\ 。 + +- ``$DATA_PATH`` 指上一步骤所下载的某一个 tsv 文件，如 + ``MMBench_DEV_EN.tsv``\ 。 + +评测完成后，若为开发集则会直接打印出结果；若为测试集，则需将 +``mmbench_result.xlsx`` 提交至 `MMBench +官方 `__ 完成评测取得精度结果。 + +FAQ +--- + +如何更换 LLM？ +~~~~~~~~~~~~~~ + +修改 LLM 的方式与训练单模态的大语言模型类似。 + +1. 修改配置文件中的 ``llm_name_or_path`` 参数至您期望使用的 LLM，例如 + ``internlm/internlm2-chat-20b``\ 等。 + +2. 修改配置文件中的 ``prompt_template`` 参数，与您所选择的 LLM + 保持对齐。具体选择可参考 + `这里 `__\ 。 + +.. _valueerror-bostokenid-has-to-be-defined-when-no-inputids-are-provided: + +ValueError: ``bos_token_id`` has to be defined when no ``input_ids`` are provided. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +这是由于老版本 ``transformers`` 的 LLM ``generate`` 接口在接受 +``inputs_embeds`` 输入时，必须传入有效的 ``bos_token_id``\ 。结合 PR +`transformers#29772 `__ +后可以解决这一问题。 + +在该 PR 被 merge 前，您可以安装 fork 版本的 transformers +来解决这一问题： + +.. code:: bash + + pip install git+https://github.com/LZHgrla/transformers.git@lzh/fix_bos_token_id + +该 PR 被 merge 后，您可以直接从源码安装主分支 transofmrers +来解决这一问题： + +.. code:: bash + + pip install git+https://github.com/huggingface/transformers.git