【Bug已解决】LLaMA 3.1 Fine-tuning with QLoRA - CUDA Out of Memory Error 解决方案一、现象长什么样你用QLoRA微调Llama 3.1本应省显存却仍报CUDA out of memory. Tried to allocate ... GB. GPU has X MiB remaining.具体困扰你以为 QLoRA 4-bit 就一定装得下结果还是炸你per_device_train_batch_size4直接 OOM你max_seq_length设了 4096长序列极吃显存你没开 gradient checkpointing激活值占满显存你不确定load_in_4bit是否真生效可能偷偷按 fp16 加载你优化器状态Adam也占不少你只有一张 24G 卡想微调 8B 模型。一句话QLoRA 确实把权重压到 4-bit但显存还被三块吃① 激活值随 batch_size×seq_len 增长、② 优化器状态、③ 注意力/中间 buffer。OOM 多半是 batch_size 或 max_seq_length 太大、没开梯度检查点、或 4-bit 没真生效。解法是系统性降显存小 batch梯度累积、短序列、开 gradient_checkpointing、确认 4-bit 加载、必要时优化器/计算 dtype 调低。二、背景QLoRA 省显存的原理基座权重用 4-bit NF4 存储与计算借助 bitsandbytes只训练 LoRA 适配器少量 fp16 参数。但显存 ≠ 只有权重显存消耗项说明4-bit 权重已被压缩QLoRA 核心激活值前向/反向的中间张量随batch×seq_len×hidden涨优化器状态Adam 的 m/v按可训练参数量LoRA 虽小但仍有些注意力 buffer长序列的 attention 矩阵seq×seq计算 dtype 副本4-bit 权重前向时会反量化为计算 dtype如 bf16的临时副本所以即便权重小batch 大、序列长、不开检查点激活值照样撑爆。关键杠杆**降 batch、降 seq_len、开 gradient_checkpointing用时间换显存、确认 4-bit 真生效、用bnb_4bit_compute_dtype选 bf16。三、根因根因用代码说明from transformers import AutoModelForCausalLM, BitsAndBytesConfig # 反例4-bit 没配对或没开检查点且 batch/seq 过大 model AutoModelForCausalLM.from_pretrained( meta-llama/Llama-3.1-8B, # 忘记 load_in_4bit / BitsAndBytesConfig - 按默认 fp16 加载直接爆 ) # TrainingArguments(per_device_train_batch_size8, max_seq_length4096, # gradient_checkpointingFalse) - OOM显存 4bit权重 激活(batch×seq) 优化器 attention(seq×seq) OOM 多因: batch大 / seq长 / 未开gradient_checkpointing / 4bit未生效四、最小可运行复现用 QLoRA 正确配置跑 Llama 3.14-bit 检查点 小 batchimport torch from transformers import (AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig, TrainingArguments) from peft import prepare_model_for_kbit_training, LoraConfig, get_peft_model base meta-llama/Llama-3.1-8B tok AutoTokenizer.from_pretrained(base) # 1) 正确的 4-bit 配置QLoRA 核心 bnb BitsAndBytesConfig( load_in_4bitTrue, bnb_4bit_quant_typenf4, bnb_4bit_compute_dtypetorch.bfloat16, bnb_4bit_use_double_quantTrue, ) model AutoModelForCausalLM.from_pretrained( base, quantization_configbnb, device_mapauto) model prepare_model_for_kbit_training(model) # 让 4-bit 模型可训练 # 2) LoRA 适配器 lora LoraConfig(r16, lora_alpha32, lora_dropout0.05, target_modules[q_proj,k_proj,v_proj,o_proj], task_typeCAUSAL_LM) model get_peft_model(model, lora) # 3) 显存友好的训练参数 args TrainingArguments( output_dir./out, per_device_train_batch_size1, # 小 batch gradient_accumulation_steps8, # 用累积补回有效 batch max_seq_length1024, # 别一上来 4096 gradient_checkpointingTrue, # 用时间换显存 bf16True, optimpaged_adamw_8bit, # 分页优化器省显存 )运行前确认model.is_loaded_in_4bit为真4-bit 真生效。这样 8B 在 24G 卡上通常可跑。五、解决方案第一层最小直接修复最小修复是系统性降显存# 1) 确认 4-bit 生效 assert model.is_loaded_in_4bit # 2) 小 batch 梯度累积 per_device_train_batch_size1 gradient_accumulation_steps8 # 有效 batch 1*8 # 3) 缩短序列 max_seq_length1024 # 先验证能跑再按需加 # 4) 开梯度检查点 gradient_checkpointingTrue # 5) 用省显存优化器 optimpaged_adamw_8bit要点① 先确认load_in_4bit生效否则按 fp16 加载必爆②gradient_checkpointingTrue大幅降激活显存代价是速度③max_seq_length是隐形大户先短后长④paged_adamw_8bit把优化器状态分页到 CPU省 GPU⑤prepare_model_for_kbit_training是 4-bit 训练必要步骤。六、解决方案第二层结构化改进把QLoRA 显存预算固化成策略用一个 dataclass 作为单一事实来源from dataclasses import dataclass, field import torch from transformers import BitsAndBytesConfig dataclass(frozenTrue) class QloraMemoryPolicy: Llama 3.1 QLoRA 显存策略单一事实来源。 规则 - 必须 load_in_4bit 且 compute_dtypebf16确认真省显存 - 小 per_device_batch 梯度累积补有效 batch - 开 gradient_checkpointingmax_seq_length 受控 - 优化器用 paged_adamw_8bit batch_size: int 1 grad_accum: int 8 max_seq_length: int 1024 compute_dtype: str bf16 def bnb_config(self) - BitsAndBytesConfig: return BitsAndBytesConfig( load_in_4bitTrue, bnb_4bit_quant_typenf4, bnb_4bit_compute_dtypegetattr(torch, self.compute_dtype), bnb_4bit_use_double_quantTrue, ) def effective_batch(self) - int: return self.batch_size * self.grad_accum def demo() - None: policy QloraMemoryPolicy() assert policy.bnb_config().load_in_4bit is True assert policy.effective_batch() 8 print(QLoRA 显存策略自洽:, policy.effective_batch()) if __name__ __main__: demo()这样① 4-bit 配置集中且强制开启② 有效 batch batch×累积调参只需改两个字段③max_seq_length受控避免悄悄拉爆④ 优化器/检查点约定统一。七、解决方案第三层断言 / CI 守护用 pytest 守住QLoRA 显存配置正确import torch import pytest from your_module import QloraMemoryPolicy def test_4bit_enabled(): p QloraMemoryPolicy() assert p.bnb_config().load_in_4bit is True def test_compute_dtype_bf16(): p QloraMemoryPolicy() assert p.bnb_config().bnb_4bit_compute_dtype torch.bfloat16 def test_effective_batch(): p QloraMemoryPolicy(batch_size2, grad_accum4) assert p.effective_batch() 8 def test_batch_size_positive(): p QloraMemoryPolicy(batch_size1) assert p.batch_size 1 def test_seq_length_reasonable(): p QloraMemoryPolicy(max_seq_length1024) assert 0 p.max_seq_length 4096 def test_double_quant_on(): p QloraMemoryPolicy() assert p.bnb_config().bnb_4bit_use_double_quant is TrueCI 里这 6 条断言守住4-bit 生效、计算 dtype 正确、有效 batch 计算、序列受控一旦有人把load_in_4bit关掉或把 batch 调大到爆显存测试立刻红。八、排查清单是否确认load_in_4bitTrue真生效model.is_loaded_in_4bit应为真否则按 fp16 加载必炸。per_device_train_batch_size是否太大先设 1用梯度累积补有效 batch。是否开了gradient_checkpointing这是降激活显存的关键。max_seq_length是否过长先 1024 验证再按需加。优化器是否用paged_adamw_8bit省 GPU 显存。是否调了bnb_4bit_compute_dtypebf16匹配你的硬件。是否用了prepare_model_for_kbit_training4-bit 训练必要。是否有显存配置测试守护没有就补一条 CI。九、小结QLoRA 微调 Llama 3.1 仍 OOM是因为显存不只被 4-bit 权重占——激活值、优化器状态、注意力 buffer 同样吃显存尤其 batch 大、序列长、没开梯度检查点时。最小修复是确认 4-bit 真生效、小 batch梯度累积、缩短序列、开gradient_checkpointing、用paged_adamw_8bit结构化做法是抽成QloraMemoryPolicy统一显存预算最后用 pytest 守护配置。这样既在单卡跑起 8B又避免盲目加大 batch 反复 OOM。 【Bug已解决】LLaMA 3.1 Fine-tuning with QLoRA - CUDA Out of Memory Error 解决方案
【Bug已解决】LLaMA 3.1 Fine-tuning with QLoRA - CUDA Out of Memory Error 解决方案一、现象长什么样你用QLoRA微调Llama 3.1本应省显存却仍报CUDA out of memory. Tried to allocate ... GB. GPU has X MiB remaining.具体困扰你以为 QLoRA 4-bit 就一定装得下结果还是炸你per_device_train_batch_size4直接 OOM你max_seq_length设了 4096长序列极吃显存你没开 gradient checkpointing激活值占满显存你不确定load_in_4bit是否真生效可能偷偷按 fp16 加载你优化器状态Adam也占不少你只有一张 24G 卡想微调 8B 模型。一句话QLoRA 确实把权重压到 4-bit但显存还被三块吃① 激活值随 batch_size×seq_len 增长、② 优化器状态、③ 注意力/中间 buffer。OOM 多半是 batch_size 或 max_seq_length 太大、没开梯度检查点、或 4-bit 没真生效。解法是系统性降显存小 batch梯度累积、短序列、开 gradient_checkpointing、确认 4-bit 加载、必要时优化器/计算 dtype 调低。二、背景QLoRA 省显存的原理基座权重用 4-bit NF4 存储与计算借助 bitsandbytes只训练 LoRA 适配器少量 fp16 参数。但显存 ≠ 只有权重显存消耗项说明4-bit 权重已被压缩QLoRA 核心激活值前向/反向的中间张量随batch×seq_len×hidden涨优化器状态Adam 的 m/v按可训练参数量LoRA 虽小但仍有些注意力 buffer长序列的 attention 矩阵seq×seq计算 dtype 副本4-bit 权重前向时会反量化为计算 dtype如 bf16的临时副本所以即便权重小batch 大、序列长、不开检查点激活值照样撑爆。关键杠杆**降 batch、降 seq_len、开 gradient_checkpointing用时间换显存、确认 4-bit 真生效、用bnb_4bit_compute_dtype选 bf16。三、根因根因用代码说明from transformers import AutoModelForCausalLM, BitsAndBytesConfig # 反例4-bit 没配对或没开检查点且 batch/seq 过大 model AutoModelForCausalLM.from_pretrained( meta-llama/Llama-3.1-8B, # 忘记 load_in_4bit / BitsAndBytesConfig - 按默认 fp16 加载直接爆 ) # TrainingArguments(per_device_train_batch_size8, max_seq_length4096, # gradient_checkpointingFalse) - OOM显存 4bit权重 激活(batch×seq) 优化器 attention(seq×seq) OOM 多因: batch大 / seq长 / 未开gradient_checkpointing / 4bit未生效四、最小可运行复现用 QLoRA 正确配置跑 Llama 3.14-bit 检查点 小 batchimport torch from transformers import (AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig, TrainingArguments) from peft import prepare_model_for_kbit_training, LoraConfig, get_peft_model base meta-llama/Llama-3.1-8B tok AutoTokenizer.from_pretrained(base) # 1) 正确的 4-bit 配置QLoRA 核心 bnb BitsAndBytesConfig( load_in_4bitTrue, bnb_4bit_quant_typenf4, bnb_4bit_compute_dtypetorch.bfloat16, bnb_4bit_use_double_quantTrue, ) model AutoModelForCausalLM.from_pretrained( base, quantization_configbnb, device_mapauto) model prepare_model_for_kbit_training(model) # 让 4-bit 模型可训练 # 2) LoRA 适配器 lora LoraConfig(r16, lora_alpha32, lora_dropout0.05, target_modules[q_proj,k_proj,v_proj,o_proj], task_typeCAUSAL_LM) model get_peft_model(model, lora) # 3) 显存友好的训练参数 args TrainingArguments( output_dir./out, per_device_train_batch_size1, # 小 batch gradient_accumulation_steps8, # 用累积补回有效 batch max_seq_length1024, # 别一上来 4096 gradient_checkpointingTrue, # 用时间换显存 bf16True, optimpaged_adamw_8bit, # 分页优化器省显存 )运行前确认model.is_loaded_in_4bit为真4-bit 真生效。这样 8B 在 24G 卡上通常可跑。五、解决方案第一层最小直接修复最小修复是系统性降显存# 1) 确认 4-bit 生效 assert model.is_loaded_in_4bit # 2) 小 batch 梯度累积 per_device_train_batch_size1 gradient_accumulation_steps8 # 有效 batch 1*8 # 3) 缩短序列 max_seq_length1024 # 先验证能跑再按需加 # 4) 开梯度检查点 gradient_checkpointingTrue # 5) 用省显存优化器 optimpaged_adamw_8bit要点① 先确认load_in_4bit生效否则按 fp16 加载必爆②gradient_checkpointingTrue大幅降激活显存代价是速度③max_seq_length是隐形大户先短后长④paged_adamw_8bit把优化器状态分页到 CPU省 GPU⑤prepare_model_for_kbit_training是 4-bit 训练必要步骤。六、解决方案第二层结构化改进把QLoRA 显存预算固化成策略用一个 dataclass 作为单一事实来源from dataclasses import dataclass, field import torch from transformers import BitsAndBytesConfig dataclass(frozenTrue) class QloraMemoryPolicy: Llama 3.1 QLoRA 显存策略单一事实来源。 规则 - 必须 load_in_4bit 且 compute_dtypebf16确认真省显存 - 小 per_device_batch 梯度累积补有效 batch - 开 gradient_checkpointingmax_seq_length 受控 - 优化器用 paged_adamw_8bit batch_size: int 1 grad_accum: int 8 max_seq_length: int 1024 compute_dtype: str bf16 def bnb_config(self) - BitsAndBytesConfig: return BitsAndBytesConfig( load_in_4bitTrue, bnb_4bit_quant_typenf4, bnb_4bit_compute_dtypegetattr(torch, self.compute_dtype), bnb_4bit_use_double_quantTrue, ) def effective_batch(self) - int: return self.batch_size * self.grad_accum def demo() - None: policy QloraMemoryPolicy() assert policy.bnb_config().load_in_4bit is True assert policy.effective_batch() 8 print(QLoRA 显存策略自洽:, policy.effective_batch()) if __name__ __main__: demo()这样① 4-bit 配置集中且强制开启② 有效 batch batch×累积调参只需改两个字段③max_seq_length受控避免悄悄拉爆④ 优化器/检查点约定统一。七、解决方案第三层断言 / CI 守护用 pytest 守住QLoRA 显存配置正确import torch import pytest from your_module import QloraMemoryPolicy def test_4bit_enabled(): p QloraMemoryPolicy() assert p.bnb_config().load_in_4bit is True def test_compute_dtype_bf16(): p QloraMemoryPolicy() assert p.bnb_config().bnb_4bit_compute_dtype torch.bfloat16 def test_effective_batch(): p QloraMemoryPolicy(batch_size2, grad_accum4) assert p.effective_batch() 8 def test_batch_size_positive(): p QloraMemoryPolicy(batch_size1) assert p.batch_size 1 def test_seq_length_reasonable(): p QloraMemoryPolicy(max_seq_length1024) assert 0 p.max_seq_length 4096 def test_double_quant_on(): p QloraMemoryPolicy() assert p.bnb_config().bnb_4bit_use_double_quant is TrueCI 里这 6 条断言守住4-bit 生效、计算 dtype 正确、有效 batch 计算、序列受控一旦有人把load_in_4bit关掉或把 batch 调大到爆显存测试立刻红。八、排查清单是否确认load_in_4bitTrue真生效model.is_loaded_in_4bit应为真否则按 fp16 加载必炸。per_device_train_batch_size是否太大先设 1用梯度累积补有效 batch。是否开了gradient_checkpointing这是降激活显存的关键。max_seq_length是否过长先 1024 验证再按需加。优化器是否用paged_adamw_8bit省 GPU 显存。是否调了bnb_4bit_compute_dtypebf16匹配你的硬件。是否用了prepare_model_for_kbit_training4-bit 训练必要。是否有显存配置测试守护没有就补一条 CI。九、小结QLoRA 微调 Llama 3.1 仍 OOM是因为显存不只被 4-bit 权重占——激活值、优化器状态、注意力 buffer 同样吃显存尤其 batch 大、序列长、没开梯度检查点时。最小修复是确认 4-bit 真生效、小 batch梯度累积、缩短序列、开gradient_checkpointing、用paged_adamw_8bit结构化做法是抽成QloraMemoryPolicy统一显存预算最后用 pytest 守护配置。这样既在单卡跑起 8B又避免盲目加大 batch 反复 OOM。