手把手教你用Xtuner微调Qwen模型从KeyError到成功训练的3种配置文件修改技巧1. 环境准备与常见错误排查在开始Qwen模型的微调之前确保你的环境配置正确至关重要。许多初学者常犯的错误就是直接使用最新版本的PyTorch和Transformers这往往会导致兼容性问题。典型环境配置问题PyTorch版本冲突最新版PyTorch如2.6可能与bitsandbytes不兼容Transformers版本不匹配Qwen特定版本可能需要特定Transformers版本CUDA驱动问题CUDA版本与PyTorch版本不匹配提示建议使用conda创建独立环境避免依赖冲突# 创建conda环境 conda create -n qwen_finetune python3.10 conda activate qwen_finetune # 安装推荐版本的PyTorch pip install torch2.5.1 torchvision0.15.2 torchaudio2.5.1 --index-url https://download.pytorch.org/whl/cu118常见错误排查表错误类型可能原因解决方案No module named triton.opsPyTorch版本过高降级到PyTorch 2.5.1KeyError: qwenTransformers版本不支持修改model_type或升级TransformersCUDA out of memory显存不足使用QLoRA或减小batch sizeRuntimeError: Expected all tensors on same device设备不匹配检查.cuda()调用位置2. 配置文件修改的三种核心技巧2.1 模型类型适配修改当遇到KeyError: qwen错误时这通常是因为Transformers库无法识别配置文件中的model_type。Qwen系列模型随着版本迭代其model_type可能发生变化。解决方案检查模型官方文档确认支持的Transformers版本如果无法升级Transformers可以修改配置文件中的model_type字段# 修改前 model_type qwen # 修改后根据实际情况选择 model_type qwen2 # 或qwen1.5等兼容类型版本兼容性对照表Qwen版本推荐Transformers版本兼容model_typeQwen1.54.48.0qwen1.5Qwen24.51.0qwen2Qwen2.54.52.0qwen22.2 量化参数调整QLoRA微调时经常遇到量化相关错误如RuntimeError: Failed to import transformers.integrations.bitsandbytes。这时需要检查量化配置# 在配置文件中确保量化设置正确 quantization_config dict( typeBitsAndBytesConfig, load_in_4bitTrue, bnb_4bit_compute_dtypetorch.bfloat16, bnb_4bit_use_double_quantTrue, bnb_4bit_quant_typenf4 )关键参数说明load_in_4bit: 启用4bit量化bnb_4bit_compute_dtype: 计算时使用的数据类型bnb_4bit_use_double_quant: 是否使用双重量化bnb_4bit_quant_type: 量化类型nf4通常效果最好2.3 数据结构适配当使用自定义数据集时需要确保数据格式与Xtuner要求一致。常见错误是数据格式不匹配导致训练无法开始。标准数据格式示例[ { conversation: [ { system: 你是一个专业的AI助手, input: 什么是酮咯酸滴眼液, output: 酮咯酸滴眼液是一种用于治疗过敏性眼痒的药物... } ] }, { conversation: [ { system: 你是一个专业的AI助手, input: 什么药物会升高血糖, output: 某些非糖尿病药物可能会升高血糖水平... } ] } ]数据转换Python脚本import pandas as pd import json def convert_excel_to_jsonl(input_file, output_file): df pd.read_excel(input_file) output_data [] for _, row in df.iterrows(): conversation { system: 你是一个专业的AI助手, input: row[问题], output: row[答案] } output_data.append({conversation: [conversation]}) with open(output_file, w, encodingutf-8) as f: for item in output_data: f.write(json.dumps(item, ensure_asciiFalse) \n) # 使用示例 convert_excel_to_jsonl(MedQA2019.xlsx, MedQA2019.jsonl)3. 实战Qwen模型微调全流程3.1 准备配置文件Xtuner提供了多种预设配置模板我们可以基于这些模板进行修改# 列出所有可用配置 xtuner list-cfg | grep qwen # 复制配置文件到当前目录 xtuner copy-cfg qwen_7b_qlora_oasst1_e3 . mv qwen_7b_qlora_oasst1_e3_copy.py qwen_7b_qlora_medqa_e3.py关键配置修改点模型路径修改数据路径设置训练参数调整量化配置# 修改示例 - pretrained_model_name_or_path qwen/qwen-7b pretrained_model_name_or_path ./qwen-7b - data_path timdettmers/openassistant-guanaco data_path ./MedQA2019.jsonl # 调整训练参数 max_length 2048 # 根据显存情况调整 batch_size 8 # 根据显存情况调整 accumulative_counts 4 # 梯度累积3.2 启动训练配置完成后可以使用以下命令启动训练# 普通训练 xtuner train qwen_7b_qlora_medqa_e3.py # 使用Deepspeed加速 xtuner train qwen_7b_qlora_medqa_e3.py --deepspeed deepspeed_zero2训练过程监控使用nvidia-smi监控GPU使用情况检查训练日志中的loss变化注意显存使用情况避免OOM3.3 模型测试与部署训练完成后可以使用Xtuner内置的chat功能测试模型# 测试原始模型 xtuner chat ./qwen-7b --prompt-template qwen_chat # 测试微调后的模型 xtuner chat ./qwen-7b --adapter ./work_dir --prompt-template qwen_chatWeb Demo部署安装streamlit准备web_demo.py脚本修改模型路径和端口配置# 简化版web_demo.py示例 import streamlit as st from transformers import AutoModelForCausalLM, AutoTokenizer model_path ./qwen-7b adapter_path ./work_dir tokenizer AutoTokenizer.from_pretrained(model_path, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( model_path, trust_remote_codeTrue, device_mapauto ) model.load_adapter(adapter_path) st.title(Qwen医学问答助手) user_input st.text_input(请输入您的问题:) if user_input: response, _ model.chat(tokenizer, user_input, history[]) st.write(response)4. 高级技巧与问题解决4.1 处理序列长度问题当遇到Qwen2RotaryEmbedding.forward() got an unexpected keyword argument seq_len错误时这通常与旋转位置编码的实现有关。解决方案更新Xtuner到最新版本在配置文件中显式设置rope_scaling参数# 在模型配置中添加 rope_scaling dict( typelinear, factor2.0 # 根据需求调整 )4.2 混合精度训练优化为了提升训练效率并减少显存占用可以配置混合精度训练# 在配置文件中添加 fp16 dict( enabledTrue, loss_scale512, initial_scale_power16, min_loss_scale1 ) # 或者使用bf16 bf16 dict(enabledTrue)精度选择建议精度类型适用场景优势限制FP32小模型/调试精度最高显存占用大FP16大多数情况平衡精度和速度可能溢出BF16Ampere架构GPU动态范围大需要硬件支持4.3 自定义提示模板不同的模型需要不同的提示模板才能发挥最佳性能。Xtuner支持自定义提示模板# 在配置文件中定义 prompt_template dict( system你是一个专业的医学AI助手请用准确、专业的语言回答问题。, user{input}, assistant{output}, system_prefix, system_suffix\n, user_prefix问, user_suffix\n, assistant_prefix答, assistant_suffix\n, stop_words[\n, /s] )模板设计原则明确区分系统提示、用户输入和助手回复保持风格一致性包含适当的停止词考虑多轮对话场景
手把手教你用Xtuner微调Qwen模型：从KeyError到成功训练的3种配置文件修改技巧
手把手教你用Xtuner微调Qwen模型从KeyError到成功训练的3种配置文件修改技巧1. 环境准备与常见错误排查在开始Qwen模型的微调之前确保你的环境配置正确至关重要。许多初学者常犯的错误就是直接使用最新版本的PyTorch和Transformers这往往会导致兼容性问题。典型环境配置问题PyTorch版本冲突最新版PyTorch如2.6可能与bitsandbytes不兼容Transformers版本不匹配Qwen特定版本可能需要特定Transformers版本CUDA驱动问题CUDA版本与PyTorch版本不匹配提示建议使用conda创建独立环境避免依赖冲突# 创建conda环境 conda create -n qwen_finetune python3.10 conda activate qwen_finetune # 安装推荐版本的PyTorch pip install torch2.5.1 torchvision0.15.2 torchaudio2.5.1 --index-url https://download.pytorch.org/whl/cu118常见错误排查表错误类型可能原因解决方案No module named triton.opsPyTorch版本过高降级到PyTorch 2.5.1KeyError: qwenTransformers版本不支持修改model_type或升级TransformersCUDA out of memory显存不足使用QLoRA或减小batch sizeRuntimeError: Expected all tensors on same device设备不匹配检查.cuda()调用位置2. 配置文件修改的三种核心技巧2.1 模型类型适配修改当遇到KeyError: qwen错误时这通常是因为Transformers库无法识别配置文件中的model_type。Qwen系列模型随着版本迭代其model_type可能发生变化。解决方案检查模型官方文档确认支持的Transformers版本如果无法升级Transformers可以修改配置文件中的model_type字段# 修改前 model_type qwen # 修改后根据实际情况选择 model_type qwen2 # 或qwen1.5等兼容类型版本兼容性对照表Qwen版本推荐Transformers版本兼容model_typeQwen1.54.48.0qwen1.5Qwen24.51.0qwen2Qwen2.54.52.0qwen22.2 量化参数调整QLoRA微调时经常遇到量化相关错误如RuntimeError: Failed to import transformers.integrations.bitsandbytes。这时需要检查量化配置# 在配置文件中确保量化设置正确 quantization_config dict( typeBitsAndBytesConfig, load_in_4bitTrue, bnb_4bit_compute_dtypetorch.bfloat16, bnb_4bit_use_double_quantTrue, bnb_4bit_quant_typenf4 )关键参数说明load_in_4bit: 启用4bit量化bnb_4bit_compute_dtype: 计算时使用的数据类型bnb_4bit_use_double_quant: 是否使用双重量化bnb_4bit_quant_type: 量化类型nf4通常效果最好2.3 数据结构适配当使用自定义数据集时需要确保数据格式与Xtuner要求一致。常见错误是数据格式不匹配导致训练无法开始。标准数据格式示例[ { conversation: [ { system: 你是一个专业的AI助手, input: 什么是酮咯酸滴眼液, output: 酮咯酸滴眼液是一种用于治疗过敏性眼痒的药物... } ] }, { conversation: [ { system: 你是一个专业的AI助手, input: 什么药物会升高血糖, output: 某些非糖尿病药物可能会升高血糖水平... } ] } ]数据转换Python脚本import pandas as pd import json def convert_excel_to_jsonl(input_file, output_file): df pd.read_excel(input_file) output_data [] for _, row in df.iterrows(): conversation { system: 你是一个专业的AI助手, input: row[问题], output: row[答案] } output_data.append({conversation: [conversation]}) with open(output_file, w, encodingutf-8) as f: for item in output_data: f.write(json.dumps(item, ensure_asciiFalse) \n) # 使用示例 convert_excel_to_jsonl(MedQA2019.xlsx, MedQA2019.jsonl)3. 实战Qwen模型微调全流程3.1 准备配置文件Xtuner提供了多种预设配置模板我们可以基于这些模板进行修改# 列出所有可用配置 xtuner list-cfg | grep qwen # 复制配置文件到当前目录 xtuner copy-cfg qwen_7b_qlora_oasst1_e3 . mv qwen_7b_qlora_oasst1_e3_copy.py qwen_7b_qlora_medqa_e3.py关键配置修改点模型路径修改数据路径设置训练参数调整量化配置# 修改示例 - pretrained_model_name_or_path qwen/qwen-7b pretrained_model_name_or_path ./qwen-7b - data_path timdettmers/openassistant-guanaco data_path ./MedQA2019.jsonl # 调整训练参数 max_length 2048 # 根据显存情况调整 batch_size 8 # 根据显存情况调整 accumulative_counts 4 # 梯度累积3.2 启动训练配置完成后可以使用以下命令启动训练# 普通训练 xtuner train qwen_7b_qlora_medqa_e3.py # 使用Deepspeed加速 xtuner train qwen_7b_qlora_medqa_e3.py --deepspeed deepspeed_zero2训练过程监控使用nvidia-smi监控GPU使用情况检查训练日志中的loss变化注意显存使用情况避免OOM3.3 模型测试与部署训练完成后可以使用Xtuner内置的chat功能测试模型# 测试原始模型 xtuner chat ./qwen-7b --prompt-template qwen_chat # 测试微调后的模型 xtuner chat ./qwen-7b --adapter ./work_dir --prompt-template qwen_chatWeb Demo部署安装streamlit准备web_demo.py脚本修改模型路径和端口配置# 简化版web_demo.py示例 import streamlit as st from transformers import AutoModelForCausalLM, AutoTokenizer model_path ./qwen-7b adapter_path ./work_dir tokenizer AutoTokenizer.from_pretrained(model_path, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( model_path, trust_remote_codeTrue, device_mapauto ) model.load_adapter(adapter_path) st.title(Qwen医学问答助手) user_input st.text_input(请输入您的问题:) if user_input: response, _ model.chat(tokenizer, user_input, history[]) st.write(response)4. 高级技巧与问题解决4.1 处理序列长度问题当遇到Qwen2RotaryEmbedding.forward() got an unexpected keyword argument seq_len错误时这通常与旋转位置编码的实现有关。解决方案更新Xtuner到最新版本在配置文件中显式设置rope_scaling参数# 在模型配置中添加 rope_scaling dict( typelinear, factor2.0 # 根据需求调整 )4.2 混合精度训练优化为了提升训练效率并减少显存占用可以配置混合精度训练# 在配置文件中添加 fp16 dict( enabledTrue, loss_scale512, initial_scale_power16, min_loss_scale1 ) # 或者使用bf16 bf16 dict(enabledTrue)精度选择建议精度类型适用场景优势限制FP32小模型/调试精度最高显存占用大FP16大多数情况平衡精度和速度可能溢出BF16Ampere架构GPU动态范围大需要硬件支持4.3 自定义提示模板不同的模型需要不同的提示模板才能发挥最佳性能。Xtuner支持自定义提示模板# 在配置文件中定义 prompt_template dict( system你是一个专业的医学AI助手请用准确、专业的语言回答问题。, user{input}, assistant{output}, system_prefix, system_suffix\n, user_prefix问, user_suffix\n, assistant_prefix答, assistant_suffix\n, stop_words[\n, /s] )模板设计原则明确区分系统提示、用户输入和助手回复保持风格一致性包含适当的停止词考虑多轮对话场景
