第9章: 微调课：从 SFT 到 LoRA/QLoRA 的理论与实战

# 检查 torch 是否能看到 GPU
python -c "import torch; print('cuda:', torch.cuda.is_available()); print('device:', torch.cuda.get_device_name(0) if torch.cuda.is_available() else None)"

# accelerate 配置（单卡也建议做）
accelerate config

# 建议新建一个独立目录（示例名称：ft-demo）
ft-demo/
  data/
    train.jsonl
    eval.jsonl
  scripts/
    train_lora.py
    infer.py
  models/
    base/              # 预下载的 base 模型（推荐，避免训练时临时下载失败）
  outputs/
    adapter/            # 训练后产物（LoRA 适配器）
    logs/               # 训练日志（可选）

# 示例：先选一个能跑通流程的小模型（你也可以换成任何可用模型）
export BASE_MODEL="Qwen/Qwen2.5-1.5B-Instruct"

# 可选：把 HF 缓存放到项目目录，方便迁移与复现
export HF_HOME="$(pwd)/.hf"

pip install -U huggingface_hub

# 下载模型到 models/base
huggingface-cli download "$BASE_MODEL" --local-dir ./models/base --local-dir-use-symlinks False

# 下载完快速自检
ls -lh models/base | head
python -c "from transformers import AutoTokenizer; AutoTokenizer.from_pretrained('models/base'); print('tokenizer ok')"

# 训练/推理时使用“本地目录”作为 base（重点看这里）
BASE_MODEL="models/base" python scripts/train_lora.py
BASE_MODEL="models/base" python scripts/infer.py

# 这等价于代码里的：
# AutoTokenizer.from_pretrained("models/base")
# AutoModelForCausalLM.from_pretrained("models/base")

# data/train.jsonl（示例，至少几条就能跑通）
{"messages": [{"role": "system", "content": "你是售后助手，输出必须是 JSON"}, {"role": "user", "content": "我想退货"}, {"role": "assistant", "content": "{\"label\":\"售后\",\"next_step\":\"引导用户在订单页点击退货\"}"}]}
{"messages": [{"role": "system", "content": "你是售后助手，输出必须是 JSON"}, {"role": "user", "content": "怎么查物流"}, {"role": "assistant", "content": "{\"label\":\"查询\",\"next_step\":\"引导用户在订单页查看物流\"}"}]}

# data/eval.jsonl（示例，放 2-5 条也能先跑通流程）
{"messages": [{"role": "system", "content": "你是售后助手，输出必须是 JSON"}, {"role": "user", "content": "包装拆了还能退吗"}, {"role": "assistant", "content": "{\"label\":\"售后\",\"next_step\":\"解释规则并引导申请\"}"}]}

import os
from datasets import load_dataset
from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import LoraConfig, get_peft_model
from trl import SFTTrainer


def main():
    # 1) 选择 base 模型（最关键：你只需要改这里）
    # model_id 支持 2 种写法：
    # - HuggingFace 模型名（会自动下载/走缓存）
    #   示例："Qwen/Qwen2.5-1.5B-Instruct"
    # - 本地模型目录（推荐先预下载到本地，更稳定/更可复现）
    #   示例："./models/base"  或  "/data/models/Qwen2.5-1.5B-Instruct"
    #
    # 你可以在命令行里用环境变量覆盖：
    #   BASE_MODEL="Qwen/Qwen2.5-1.5B-Instruct" python scripts/train_lora.py
    #   BASE_MODEL="models/base" python scripts/train_lora.py
    model_id = os.environ.get("BASE_MODEL", "Qwen/Qwen2.5-1.5B-Instruct")

    # 2) 读 tokenizer
    # tokenizer 负责把文本变成 token id。
    tokenizer = AutoTokenizer.from_pretrained(model_id)
    # 一些模型没有 pad_token（尤其是类 LLaMA 系），训练/对齐 batch 时可能报错。
    # 简单做法：把 pad_token 设成 eos_token。
    if tokenizer.pad_token is None:
        tokenizer.pad_token = tokenizer.eos_token

    # 3) 读 base 模型（两条路线：LoRA / QLoRA）
    # LoRA：普通加载（显存够用时推荐）
    # device_map="auto"：让 transformers 自动把模型放到可用 GPU 上。
    model = AutoModelForCausalLM.from_pretrained(model_id, device_map="auto")

    # QLoRA：如果显存不够，改用 4-bit 加载（需 bitsandbytes）
    # 你只需要：把上面那行 LoRA 加载注释掉，然后启用下面这一行。
    # model = AutoModelForCausalLM.from_pretrained(model_id, load_in_4bit=True, device_map="auto")
    # model = AutoModelForCausalLM.from_pretrained(model_id, load_in_4bit=True, device_map="auto")

    # 4) 配置 LoRA（核心：你训练的就是这里的 A/B，不动 base 的 W）
    # target_modules：决定“哪些线性层”加 LoRA。入门阶段可以先只加 attention 的投影层。
    # r/alpha/dropout：先用默认即可；效果不够再调大 r。
    lora_config = LoraConfig(
        r=8,  # rank（秩/容量）：越大越“能学”，但参数量与显存/算力也越高；入门常用 8/16
        lora_alpha=16,  # 缩放系数：控制 ΔW 的“强度”（常见取 16/32）；通常与 r 搭配一起调
        lora_dropout=0.05,  # dropout：只作用在 LoRA 分支上，防过拟合；数据少时可稍微调大
        bias="none",  # 是否训练 bias：none 最常见；如果你不清楚就保持默认
        task_type="CAUSAL_LM",  # 任务类型：自回归语言模型（大多数开源 LLM 微调都是这个）
        target_modules=["q_proj", "k_proj", "v_proj", "o_proj"],  # 注入 LoRA 的层：注意力投影层是最常见起点
    )
    # 把 LoRA 适配器“挂”到模型上：从此以后训练的参数主要就是 LoRA 的那部分。
    model = get_peft_model(model, lora_config)

    # 5) 读数据
    # 这里读的是 JSONL（每行一个 JSON）。示例格式：
    # {"messages": [{"role":"system","content":"..."},{"role":"user","content":"..."},{"role":"assistant","content":"..."}]}
    dataset = load_dataset(
        "json",
        data_files={"train": "data/train.jsonl", "eval": "data/eval.jsonl"},
    )

    # 6) 训练
    # SFTTrainer：把 messages 格式的数据组装成模型可训练的文本序列。
    # max_seq_length：越大越吃显存；如果 OOM，先把它降到 512/256。
    trainer = SFTTrainer(
        model=model,
        tokenizer=tokenizer,
        train_dataset=dataset["train"],
        eval_dataset=dataset["eval"],
        max_seq_length=1024,
    )

    trainer.train()

    # 7) 保存产物：LoRA adapter
    # 注意：这里保存的是 adapter（增量权重），不是完整 base。
    # 推理时要用：base + adapter 组合加载。
    os.makedirs("outputs/adapter", exist_ok=True)
    trainer.save_model("outputs/adapter")
    print("\n✅ saved adapter to: outputs/adapter")


if __name__ == "__main__":
    main()

# 方式A：直接运行（最简单）
BASE_MODEL="your-base-model" python scripts/train_lora.py

# 方式B：用 accelerate（更贴近工程，多卡/混合精度更容易扩展）
BASE_MODEL="your-base-model" accelerate launch scripts/train_lora.py

import os
from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel


def generate(model, tokenizer, prompt: str):
    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
    out = model.generate(**inputs, max_new_tokens=200)
    return tokenizer.decode(out[0], skip_special_tokens=True)


def main():
    model_id = os.environ.get("BASE_MODEL", "your-base-model")

    tokenizer = AutoTokenizer.from_pretrained(model_id)
    if tokenizer.pad_token is None:
        tokenizer.pad_token = tokenizer.eos_token

    base = AutoModelForCausalLM.from_pretrained(model_id, device_map="auto")

    prompt = "你是售后助手，输出必须是 JSON。用户：我想退货"

    print("\n=== Base only ===")
    print(generate(base, tokenizer, prompt))

    model = PeftModel.from_pretrained(base, "outputs/adapter")
    print("\n=== Base + LoRA adapter ===")
    print(generate(model, tokenizer, prompt))


if __name__ == "__main__":
    main()

# 运行推理验证
BASE_MODEL="your-base-model" python scripts/infer.py

# scripts/merge_lora.py
import os
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel

BASE_MODEL = os.getenv("BASE_MODEL", "models/base")
ADAPTER = os.getenv("ADAPTER", "outputs/adapter")
OUT_DIR = os.getenv("OUT_DIR", "outputs/merged_model")

def main():
    tokenizer = AutoTokenizer.from_pretrained(BASE_MODEL, trust_remote_code=True)
    model = AutoModelForCausalLM.from_pretrained(
        BASE_MODEL,
        torch_dtype=torch.float16,
        device_map="auto",
        trust_remote_code=True,
    )
    model = PeftModel.from_pretrained(model, ADAPTER)
    model = model.merge_and_unload()  # 把 ΔW 合并进 W

    os.makedirs(OUT_DIR, exist_ok=True)
    model.save_pretrained(OUT_DIR)
    tokenizer.save_pretrained(OUT_DIR)
    print(f"merged model saved to: {OUT_DIR}")

if __name__ == "__main__":
    main()

# 执行合并
BASE_MODEL="models/base" ADAPTER="outputs/adapter" OUT_DIR="outputs/merged_model" python scripts/merge_lora.py

# 1) 在服务器创建虚拟环境并安装 vLLM（建议 Python 3.10/3.11 + CUDA）
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip

# 2) 安装 vLLM（CUDA 机器上）
pip install "vllm>=0.4"

# 3) 启动服务（路线 A：merged_model）
vllm serve outputs/merged_model \
  --host 0.0.0.0 --port 8000 \
  --served-model-name my-ft-model

# 路线 B：启动 base，并启用 LoRA
# 说明：--lora-modules 的写法是“逻辑名=adapter目录”，逻辑名用于 API 调用时的 model 字段。
vllm serve models/base \
  --host 0.0.0.0 --port 8000 \
  --served-model-name my-base \
  --enable-lora \
  --lora-modules my-ft=outputs/adapter

# systemd 示例：/etc/systemd/system/vllm.service
[Unit]
Description=vLLM Inference Server
After=network.target

[Service]
User=ubuntu
WorkingDirectory=/home/ubuntu/ft
Environment=PATH=/home/ubuntu/ft/.venv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin
ExecStart=/home/ubuntu/ft/.venv/bin/vllm serve /home/ubuntu/ft/outputs/merged_model --host 0.0.0.0 --port 8000 --served-model-name my-ft-model
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

# 启用与启动
sudo systemctl daemon-reload
sudo systemctl enable vllm
sudo systemctl start vllm
sudo systemctl status vllm

# Nginx 反代示例（HTTPS 建议用 certbot 配好证书）
# /etc/nginx/sites-enabled/ft-model.conf
server {
  listen 80;
  server_name ft-api.yourdomain.com;

  location / {
    proxy_pass http://127.0.0.1:8000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    # 最低限度：加一个简单的 token（更严谨可用网关/鉴权服务）
    # if ($http_authorization != "Bearer YOUR_TOKEN") { return 401; }
  }
}

sudo nginx -t
sudo systemctl reload nginx

# 任何语言都行：只要能发 HTTP POST
curl https://ft-api.yourdomain.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "model": "my-ft-model",
    "messages": [
      {"role": "system", "content": "你是企业内部知识助手"},
      {"role": "user", "content": "把这段文本提取成 JSON：..."}
    ],
    "temperature": 0.2
  }'