update docs

docs/source/Customization/新增数据集.md → docs/source/Customization/自定义数据集.md

@@ -1,23 +1,57 @@
-# 新增数据集
+# 自定义数据集
 
-## 本地数据集
+ms-swift的标准格式数据集可接受的keys包括: 'messages'、'rejected_response'、'label'、'images'、'videos'、'audios'、'tools'和'objects'。其中'messages'是必需的key，'rejected_response'用于DPO等RLHF训练，'label'用于KTO训练，'images'、'videos'、'audios'用于存储多模态数据的路径或者url，'tools' 用于Agent任务，'objects'用于grounding任务。
 
-### 预训练格式
+ms-swift中存在三种核心预处理器：`MessagesPreprocessor`、`AlpacaPreprocessor`、`ResponsePreprocessor`。MessagesPreprocessor用于将类messages和sharegpt格式的数据集转换为标准格式，AlpacaPreprocessor则转换alpaca格式的数据集，ResponsePreprocessor则转换类query/response格式的数据集。`AutoPreprocessor`则可以自动选择合适的Preprocessor进行处理。通常情况下`AutoPreprocessor`能覆盖90%以上的情况。
+
+以下四种格式在`AutoPreprocessor`处理下都会转换成ms-swift标准格式中的messages字段：
+
+messages格式:
+```jsonl
+{"messages": [{"role": "system", "content": "<system>"}, {"role": "user", "content": "<query1>"}, {"role": "assistant", "content": "<response1>"}, {"role": "user", "content": "<query2>"}, {"role": "assistant", "content": "<response2>"}]}
+```
+
+sharegpt格式:
+```jsonl
+{"system": "<system>", "conversation": [{"human": "<query1>", "assistant": "<resonse1>"}, {"human": "<query2>", "assistant": "<resonse2>"}]}
+```
+
+alpaca格式:
+```jsonl
+{"system": "<system>", "instruction": "<query-inst>", "input": "<query-input>", "output": "<response>"}
+```
+
+query-response格式：
+```jsonl
+{"system": "<system>", "query": "<query2>", "response": "<response2>", "history": [["<query1>", "<response1>"]]}
+```
+
+自定义数据集的接入方法有三种，对预处理函数的控制能力逐渐加强：
+1. 【推荐】直接使用`--dataset <dataset_id_or_path>`接入，使用AutoPreprocessor。支持csv、json、jsonl、txt、文件夹。
+2. 书写dataset_info.json文件。可以参考ms-swift内置的[dataset_info.json](https://github.com/modelscope/ms-swift/blob/main/swift/llm/dataset/data/dataset_info.json)。其中ms_dataset_id/hf_dataset_id/dataset_path必填其中的一项，通过`columns`字段进行列名转换。格式转换使用AutoPreprocessor。使用`--custom_dataset_info xxx.json`解析json文件。
+3. 手动注册数据集，具有最灵活的预处理函数定制能力，但难度较高。可以参考[examples](https://github.com/modelscope/swift/blob/main/examples/custom)中的样例，通过指定`--custom_register_path xxx.py`解析注册内容。
+
+
+## 推荐数据集格式
+
+以下给出ms-swift的推荐数据集格式：
+
+### 预训练
 
 ```jsonl
 {"messages": [{"role": "assistant", "content": "I love music"}]}
 {"messages": [{"role": "assistant", "content": "教练我要打篮球"}]}
 {"messages": [{"role": "assistant", "content": "西红柿鸡蛋盖饭和地三鲜盖饭哪个更权威"}]}
 ```
 
-### 微调格式
+### 监督微调
 
 ```jsonl
 {"messages": [{"role": "system", "content": "你是个有用无害的助手"}, {"role": "user", "content": "告诉我明天的天气"}, {"role": "assistant", "content": "明天天气晴朗"}]}
 {"messages": [{"role": "system", "content": "你是个有用无害的数学计算器"}, {"role": "user", "content": "1+1等于几"}, {"role": "assistant", "content": "等于2"}, {"role": "user", "content": "再加1呢"}, {"role": "assistant", "content": "等于3"}]}
 ```
 
-### 人类对齐格式
+### RLHF
 
 #### DPO/ORPO/CPO/SimPO
 
@@ -33,16 +67,20 @@
 {"messages": [{"role": "system", "content": "你是个有用无害的数学计算器"}, {"role": "user", "content": "1+1等于几"}, {"role": "assistant", "content": "等于2"}, {"role": "user", "content": "再加1呢"}, {"role": "assistant", "content": "等于3"}], "label": true}
 ```
 
-对于多模态数据集，和上述任务的格式相同。区别在于增加了`images`, `videos`, `audios`几个key，分别代表多模态资源，例如：
+### 多模态
+
+对于多模态数据集，和上述任务的格式相同。区别在于增加了`images`, `videos`, `audios`几个key，分别代表多模态资源：
 ```jsonl
-{"messages": [{"role": "system", "content": "你是个有用无害的助手"}, {"role": "user", "content": "<image>图片中是什么,<video>视频中是什么"}, {"role": "assistant", "content": "一个大象，一个狮子"}], 'images': ['/xxx/x.jpg'], 'videos': ['/xxx/x.mov']}
+{"messages": [{"role": "system", "content": "你是个有用无害的助手"}, {"role": "user", "content": "<image>图片中是什么,<video>视频中是什么"}, {"role": "assistant", "content": "一个大象，一个狮子"}], "images": ["/xxx/x.jpg"], "videos": ["/xxx/x.mp4"]}
 ```
-其中的`<image>` `<video>`标签代表了插入图片的位置。SWIFT的多模态训练支持多个资源多个模态混合使用。
+其中`<image>` `<video>` `<audio>`标签代表了插入图片/视频/音频的位置。
+
+#### grounding
 
 如果是grounding（物体检测）任务，SWIFT支持两种方式：
 1. 和上述多模态数据集格式保持一致，自行在数据集中添加特殊字符，例如：
 ```jsonl
-{"messages": [{"role": "system", "content": "你是个有用无害的助手"}, {"role": "user", "content": "<image>找到<ref>一只大象</ref>"}, {"role": "assistant", "content": "<box>(200,450),(500, 800)</box>"}], 'images': ['/xxx/x.jpg']}
+{"messages": [{"role": "system", "content": "你是个有用无害的助手"}, {"role": "user", "content": "<image>找到<ref>一只大象</ref>"}, {"role": "assistant", "content": "<box>(200,450),(500, 800)</box>"}], "images": ["/xxx/x.jpg"]}
 ```
 使用这种类型的数据需要您注意：
   - grounding任务往往需要特殊字符，您需要确定使用哪个模型，并阅读模型论文来确定该模型grounding任务的特殊字符，并拼合数据
@@ -72,27 +110,4 @@
 
 ### Agent格式
 
-Agent格式比较复杂，请参考[Agent文档](../Instruction/智能体的支持.md).
-
-## 注册hub数据集
-
-### 简单数据格式
-
-可以参考[swift内置的dataset_info.json](https://github.com/modelscope/swift/blob/main/swift/llm/dataset/data/dataset_info.json)进行数据集拓展. 你可以直接在内置的dataset_info.json中添加, 也可以通过`--custom_dataset_info 1.json`传入外置的dataset_info.json的路径、json字符串或者字典.
-
-```json
-[
-    {
-        "ms_dataset_id": "AI-ModelScope/xxx",
-        "hf_dataset_id": "my-group/xxx",
-        "columns": {
-            "question": "query",
-            "answer": "response"
-        }
-    }
-]
-```
-
-### 复杂数据格式
-
-请参考[examples](https://github.com/modelscope/swift/blob/main/examples/custom/dataset.py)中的样例. 你可以通过指定`--custom_register_path xxx.py`对注册的内容进行解析.
+Agent格式请参考[Agent文档](../Instruction/智能体的支持.md).

docs/source/Customization/自定义模型.md

@@ -0,0 +1,10 @@
+# 自定义模型
+
+ms-swift内置的模型，你可以直接通过指定model_id或者model_path来使用：`--model <model_id_or_path>`。ms-swift会根据model_id/model_path的后缀和`config.json`文件来判断model_type。每种model_type都有唯一的模型结构、template和加载方式。当然，你也可以手动传入`--model_type`、`--template`来进行覆盖。ms-swift已支持的model_type和template可以查看[支持的模型与数据集](../Instruction/支持的模型和数据集.md)。
+
+> [!TIP]
+> 在使用`swift sft`通过LoRA技术微调base模型为chat模型时，例如将Llama3.2-1B微调为chat模型，有时需要手动设置模板。通过添加`--template default`参数来避免base模型因未见过对话模板中的特殊字符而无法正常停止的情况。
+
+## 模型注册
+
+请参考[examples](https://github.com/modelscope/swift/blob/main/examples/custom)中示例代码。你可以通过指定`--custom_register_path xxx.py`对注册的内容进行解析。

docs/source/GetStarted/SWIFT安装.md

@@ -5,22 +5,22 @@
 可以使用pip进行安装：
 
 ```shell
-# 全量能力
-pip install 'ms-swift[all]' -U
-# 仅使用LLM
+# LLM和MLLM能力
 pip install 'ms-swift[llm]' -U
-# 仅使用评测
+# 使用评测
 pip install 'ms-swift[eval]' -U
 # 支持序列并行
 pip install 'ms-swift[seq_parallel]' -U
+# 全量能力
+pip install 'ms-swift[all]' -U
 ```
 
 ## 源代码安装
 
 ```shell
 git clone https://github.com/modelscope/ms-swift.git
 cd ms-swift
-pip install -e '.[all]'
+pip install -e '.[llm]'
 ```
 
 ## 旧版本

docs/source/GetStarted/快速开始.md

@@ -1,40 +1,31 @@
 # 快速开始
 
-SWIFT是集成了模型训练、推理部署、评测、量化一体的集成式框架，模型开发者可以在SWIFT框架里一站式完成围绕模型的各类需求。目前SWIFT的主要能力包含：
+ms-swift是魔搭社区提供的大模型与多模态大模型训练部署框架，现已支持400+大模型与100+多模态大模型的训练（预训练、微调、人类对齐）、推理、评测、量化与部署。模型开发者可以在ms-swift框架中一站式完成围绕大模型的各类需求。目前ms-swift的主要能力包含：
+
+- 模型类型：支持400+纯文本大模型、100+多模态大模型，All-to-All全模态模型的训练到部署全流程。
+- 数据集类型：内置150+预训练、微调、人类对齐、多模态等各种类型的数据集，并支持自定义数据集。
+- 硬件支持：CPU、RTX系列、T4/V100、A10/A100/H100、Ascend NPU等。
+- 轻量训练：支持了LoRA、QLoRA、DoRA、LoRA+、ReFT、RS-LoRA、LLaMAPro、Adapter、GaLore、Q-Galore、LISA、UnSloth、Liger-Kernel等轻量微调方式。
+- 分布式训练：支持分布式数据并行（DDP）、device_map简易模型并行、DeepSpeed ZeRO2 ZeRO3、FSDP等分布式训练技术。
+- 量化训练：支持对BNB、AWQ、GPTQ、AQLM、HQQ、EETQ量化模型进行训练。
+- RLHF训练：支持纯文本大模型和多模态大模型的DPO、CPO、SimPO、ORPO、KTO等人类对齐训练方法。
+- 多模态训练：支持对图像、视频和语音不同模态模型进行训练，支持VQA、Caption、OCR、Grounding任务的训练。
+- 界面训练：以界面的方式提供训练、推理、评测、量化的能力，完成大模型的全链路。
+- 插件化与拓展：支持自定义模型和数据集拓展，支持对loss、metric、trainer、loss-scale、callback、optimizer等组件进行自定义。
+- 推理加速：支持PyTorch、vLLM、LmDeploy等推理加速引擎，并提供OpenAI接口，为推理、部署和评测模块提供加速。
+- 模型评测：以EvalScope作为评测后端，支持100+评测数据集对纯文本和多模态模型进行评测。
+- 模型量化：支持AWQ、GPTQ和BNB的量化导出，导出的模型支持使用vLLM/LmDeploy推理加速，并支持继续训练。
 
-- 模型类型：涵盖了从纯文本大模型、多模态大模型到All-to-All全模态模型的训练和训练后支持
-- 数据集类型：涵盖了纯文本数据集、多模态数据集、文生图数据集等，适配不同任务
-- 任务类型：除通用的生成类型任务外，支持分类任务的训练
-- 轻量微调：支持了LoRA、QLoRA、DoRA、ReFT、LLaMAPro、Adapter、SCEdit、GaLore、Liger-Kernel等多种轻量微调方式
-- 训练stage：涵盖了预训练、微调、人类对齐的全stage
-- 训练并行：涵盖了单机单卡、单机多卡device_map、分布式数据并行（DDP）、多机多卡、DeepSpeed、FSDP、PAI DLC等
-- 推理部署：支持PyTorch、vLLM、LmDeploy等多推理框架的推理部署
-- 评测：支持以EvalScope为基本框架的纯文本和多模态评测能力，并支持自定义评测
-- 导出：支持awq、gptq、bnb等量化方式，并支持lora、llamapro的merge操作
-- 界面化：支持以gradio为基本框架的界面化操作，并支持仅部署单模型应用于space或demo环境中
-- 插件化：支持对loss、metric、trainer、loss-scale、callback、optimizer等部分的插件化定义，用户对训练过程的定制更加轻松
 
 ## 安装
 
-SWIFT的安装非常简易，请参考[安装文档](./SWIFT安装.md)。
-
-## 一些重要概念
-
-### model_type
-
-在SWIFT3.0中，model_type和2.0有所不同。3.x的model_type含义为具有以下相同特性的模型集合：
-1. 相同的模型结构 如典型的LLaMA结构
-2. 相同的template，如都使用chatml格式的template
-3. 相同的模型加载方式，例如都使用get_model_tokenizer_flash_attn加载
-
-在以上三点都相同的情况下，模型被归类为一个组，这个组的类型就是model_type。
+ms-swift的安装请参考[安装文档](./SWIFT安装.md)。
 
 ## 使用样例
 
-全量使用样例在[examples](https://github.com/modelscope/ms-swift/tree/main/examples)中，下面给出一些基本样例：
-
-命令行方式进行LoRA训练
+10分钟在单卡3090上对Qwen2.5-7B-Instruct进行自我认知微调：
 ```shell
+# 22GB
 CUDA_VISIBLE_DEVICES=0 \
 swift sft \
     --model Qwen/Qwen2.5-7B-Instruct \
@@ -63,68 +54,25 @@ swift sft \
     --model_name swift-robot
 ```
 
-代码方式进行训练的例子可以查看[examples/notebook](https://github.com/modelscope/ms-swift/tree/main/examples/notebook)
-
-命令行方式进行推理和部署
+训练完成后，使用以下命令对训练后的权重进行推理，这里的ckpt_dir需要替换成训练生成的last checkpoint文件夹：
 ```shell
-# 推理
-CUDA_VISIBLE_DEVICES=0 \
+# 使用交互式命令行进行推理
+NPROC_PER_NODE=0
 swift infer \
-    --model Qwen/Qwen2.5-7B-Instruct \
-    --infer_backend pt
-```
-
-```shell
-# 部署
-CUDA_VISIBLE_DEVICES=0 \
-swift deploy \
-    --model Qwen/Qwen2-7B-Instruct \
-    --infer_backend pt
-```
-
-```python
-# 部署client端代码
-from openai import OpenAI
-
-client = OpenAI(
-    api_key='EMPTY',
-    base_url='http://localhost:8000/v1',
-)
-model_type = client.models.list().data[0].id
-print(f'model_type: {model_type}')
-
-query = '浙江的省会在哪里?'
-messages = [{'role': 'user', 'content': query}]
-resp = client.chat.completions.create(model=model_type, messages=messages, seed=42)
-response = resp.choices[0].message.content
-print(f'query: {query}')
-print(f'response: {response}')
-
-# streaming
-messages.append({'role': 'assistant', 'content': response})
-query = '这有什么好吃的?'
-messages.append({'role': 'user', 'content': query})
-stream_resp = client.chat.completions.create(model=model_type, messages=messages, stream=True, seed=42)
-
-print(f'query: {query}')
-print('response: ', end='')
-for chunk in stream_resp:
-    print(chunk.choices[0].delta.content, end='', flush=True)
-print()
-```
+    --ckpt_dir output/vx-xxx/checkpoint-xxx \
+    --stream true
 
-## 评测
-```shell
-swift eval \
-    --model Qwen/Qwen2.5-7B-Instruct \
-    --eval_limit 10 \
-    --eval_dataset gsm8k
+# merge-lora并使用vLLM进行推理加速
+NPROC_PER_NODE=0
+swift infer \
+    --ckpt_dir output/vx-xxx/checkpoint-xxx \
+    --stream true \
+    --merge_lora true \
+    --infer_backend vllm \
+    --max_model_len 8192
 ```
 
-## 量化
-```shell
-swift export \
-    --model Qwen/Qwen2-7B-Instruct \
-    --quant_method bnb \
-    --quant_bits 8
-```
+> [!TIP]
+> 更多例子可以查看：[examples](https://github.com/modelscope/ms-swift/tree/main/examples)
+>
+> 以python方式进行训练和推理的例子可以查看[notebook](https://github.com/modelscope/ms-swift/tree/main/examples/notebook)

docs/source/Instruction/命令行参数.md

@@ -15,8 +15,8 @@
 
 ### 模型参数
 
-- 🔥model: 模型id或模型本地路径。如果是自定义模型请配合`model_type`和`template`使用
-- model_type: 模型类型。同样的模型架构、template、模型加载过程定义为一个模型类型
+- 🔥model: 模型id或模型本地路径。如果是自定义模型请配合`model_type`和`template`使用，具体可以参考[自定义模型](../Customization/自定义模型.md)
+- model_type: 模型类型。相同的模型架构、template、模型加载过程被定义为一个model_type
 - model_revision: 模型版本
 - 🔥torch_dtype: 模型权重的数据类型，支持`float16`,`bfloat16`,`float32`，默认从config文件中读取
 - attn_impl: attention类型，支持`flash_attn`, `sdpa`, `eager`，默认使用sdpa
@@ -25,7 +25,7 @@
 - local_repo_path: 部分模型在加载时依赖于github repo. 为了避免`git clone`时遇到网络问题, 可以直接使用本地repo. 该参数需要传入本地repo的路径, 默认为`None`
 
 ### 数据参数
-- 🔥dataset: 数据集id或路径。传入格式为：`数据集id or 数据集路径:子数据集#取样数量`，其中子数据集和取样数据可选。空格分割传递多个数据集。本地数据集支持jsonl、csv、json、文件夹等
+- 🔥dataset: 数据集id或路径。传入格式为：`数据集id or 数据集路径:子数据集#取样数量`，其中子数据集和取样数据可选。空格分割传递多个数据集。本地数据集支持jsonl、csv、json、文件夹等。自定义数据集可以参考[自定义数据集](../Customization/自定义数据集.md)
 - 🔥val_dataset: 验证集id或路径
 - 🔥split_dataset_ratio: 不指定val_dataset时如何拆分训练集和验证集，默认为0.01
 - data_seed: 数据集随机种子，默认为42
@@ -40,7 +40,7 @@
 - custom_dataset_info: 自定义简单数据集注册，参考[新增数据集](../Customization/新增数据集.md)
 
 ### 模板参数
-- 🔥template: 模板类型，默认使用model对应的template类型。如果为自定义模型，请参考[支持的模型和数据集](./支持的模型和数据集.md)手动传入这个字段
+- 🔥template: 对话模板类型，默认使用model对应的template类型。`swift pt`会将对话模版转为生成模板使用
 - 🔥system: 自定义system字段，默认为None，使用template的默认system
 - 🔥max_length: 单样本的tokens最大长度，默认为None，不做限制
 - truncation_strategy: 如果超长如何处理，支持`delete`和`left`，代表删除和左侧裁剪，默认为left