【案例】Qwen 微调实战 · 合并、GPTQ 量化与 vLLM 上线

### LoRA / QLoRA 权重合并模板
### 用法：llamafactory-cli export merge_lora.template.yaml
### 合并时不要使用量化模型，也不要写 quantization_bit

### model
# TODO 1: 基座模型路径或 HuggingFace 模型 ID，必须与训练时用的基座完全一致
model_name_or_path: TODO-PATH-TO-BASE-MODEL
# TODO 2: 训练产出的 adapter 目录（checkpoint-xxx 那一层）
adapter_name_or_path: TODO-PATH-TO-LORA-CHECKPOINT
# 合并 Qwen2 系列时必须为 qwen
template: qwen
# 无论训练时用的是 LoRA 还是 QLoRA，这里一律填 lora
finetuning_type: lora

### export
# TODO 3: 合并后完整权重的落盘目录
export_dir: models/qwen2-7b-sft-lora-merged
# 单个权重分片的最大体积，单位 GB
export_size: 2
# 合并在 CPU 上做，显存不够也能完成；有充裕显存可改 cuda
export_device: cpu
# 是否导出为旧版 .bin 格式，false 表示使用 safetensors
export_legacy_format: false

"""用 OpenAI 客户端访问 vLLM 起的 api server，并顺手量一下输出速度。

服务端地址与凭据全部来自环境变量，脚本里不写死任何 key：
    export VLLM_BASE_URL="http://127.0.0.1:8000/v1"
    export VLLM_API_KEY="本地服务随便填一个占位串"
    export VLLM_MODEL="add1"      # 指定走哪个 LoRA；留空则走基座模型

依赖：pip install openai
运行：python vllm_client.py
"""

import os
import time

from openai import OpenAI


def build_client() -> OpenAI:
    base_url = os.environ.get("VLLM_BASE_URL", "http://127.0.0.1:8000/v1")
    # vLLM 本地服务不校验 key，但 openai SDK 要求这个字段非空，
    # 所以仍然从环境变量取，绝不在源码里写死真实凭据
    api_key = os.environ.get("VLLM_API_KEY")
    if not api_key:
        raise RuntimeError("未找到 VLLM_API_KEY，请先在环境变量里配置")
    return OpenAI(api_key=api_key, base_url=base_url)


def call_server(client: OpenAI, prompt: str) -> str:
    # model 传 LoRA 的挂载名就走那个 LoRA，传空字符串则走基座模型
    model = os.environ.get("VLLM_MODEL", "")
    result = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
        max_tokens=2048,
    )
    return result.choices[0].message.content


def main() -> None:
    client = build_client()
    prompt = "用一段话说明 PagedAttention 解决了什么问题。"

    start = time.time()
    answer = call_server(client, prompt)
    cost = time.time() - start

    print(answer)
    print("-" * 60)
    print(f"输出长度：{len(answer)} 字")
    print(f"耗时：{cost:.2f} 秒")
    print(f"输出速度：{len(answer) / cost:.2f} 字/秒")


if __name__ == "__main__":
    main()

"""vLLM 离线批量推理：一次把整批 prompt 喂进去，拿回全部结果。

离线模式不起 HTTP 服务，适合跑评测、批量刷数据。
依赖：pip install vllm
运行：python vllm_offline_infer.py --model <模型目录>
"""

import argparse

from vllm import LLM, SamplingParams


def build_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser("vLLM offline batch inference")
    parser.add_argument("--model", type=str, required=True,
                        help="模型目录，合并后的全量权重或 GPTQ 量化产物都行")
    parser.add_argument("--temperature", type=float, default=0.8,
                        help="采样温度，越大越发散")
    parser.add_argument("--top_p", type=float, default=0.95,
                        help="核采样阈值")
    parser.add_argument("--max_tokens", type=int, default=100,
                        help="单条输出的最大 token 数")
    return parser.parse_args()


def main() -> None:
    args = build_args()

    # 一次投喂多条，vLLM 内部会自己做连续批处理，不必等凑满一批
    prompts = [
        "总结下面这段文本的摘要：随着科技的飞速发展，我们的生活方式也在悄然改变。"
        "智能手机、人工智能、物联网等科技产品的出现，为我们的日常生活带来了更多便利和舒适。",
        "用三句话说明什么是 KV cache。",
    ]

    sampling_params = SamplingParams(
        temperature=args.temperature,
        top_p=args.top_p,
        max_tokens=args.max_tokens,
    )

    # trust_remote_code=True：Qwen 等带自定义建模代码的模型需要它
    llm = LLM(model=args.model, trust_remote_code=True)

    outputs = llm.generate(prompts, sampling_params)

    for output in outputs:
        print("=" * 60)
        print("Prompt:", output.prompt)
        print("Output:", output.outputs[0].text)


if __name__ == "__main__":
    main()

### LoRA / QLoRA 权重合并模板
### 用法：llamafactory-cli export merge_lora.template.yaml
### 合并时不要使用量化模型，也不要写 quantization_bit

### model
# TODO 1: 基座模型路径或 HuggingFace 模型 ID，必须与训练时用的基座完全一致
model_name_or_path: TODO-PATH-TO-BASE-MODEL
# TODO 2: 训练产出的 adapter 目录（checkpoint-xxx 那一层）
adapter_name_or_path: TODO-PATH-TO-LORA-CHECKPOINT
# 合并 Qwen2 系列时必须为 qwen
template: qwen
# 无论训练时用的是 LoRA 还是 QLoRA，这里一律填 lora
finetuning_type: lora

### export
# TODO 3: 合并后完整权重的落盘目录
export_dir: models/qwen2-7b-sft-lora-merged
# 单个权重分片的最大体积，单位 GB
export_size: 2
# 合并在 CPU 上做，显存不够也能完成；有充裕显存可改 cuda
export_device: cpu
# 是否导出为旧版 .bin 格式，false 表示使用 safetensors
export_legacy_format: false

"""用 AutoGPTQ 把合并后的 Qwen 模型量化到 4-bit。

三个阶段：把对话数据拼成 ChatML 校准样本 -> 逐层量化 -> 存成 safetensors。
所有路径都走命令行参数，脚本里不写死任何目录。

依赖：pip install auto-gptq optimum transformers torch
运行：python run_gptq.py --model_name_or_path <合并后的模型目录> \
                        --data_path <校准数据.json> \
                        --out_path <量化产物目录>
"""

import argparse
import json
import logging
from typing import Any, Dict, List

import torch
import transformers
from transformers import AutoTokenizer
from transformers.trainer_pt_utils import LabelSmoother
from auto_gptq import AutoGPTQForCausalLM, BaseQuantizeConfig

# 这个常量标记「不参与 loss 计算」的位置，值为 -100
IGNORE_TOKEN_ID = LabelSmoother.ignore_index


def preprocess(
    sources: List[Dict[str, Any]],
    tokenizer: transformers.PreTrainedTokenizer,
    max_len: int,
    system_message: str = "You are a helpful assistant.",
) -> List[Dict[str, torch.Tensor]]:
    """把原始对话拼成 Qwen 的 ChatML 格式，并切成 input_ids / attention_mask。

    拼出来的文本形如：
        <|im_start|>system\n你是一个助手<|im_end|>\n
        <|im_start|>user\n什么是 AI<|im_end|>\n
        <|im_start|>assistant\nAI 是……<|im_end|>\n
    """
    # 角色前缀：ChatML 用 <|im_start|>角色 开头，<|im_end|> 收尾
    roles = {"user": "<|im_start|>user", "assistant": "<|im_start|>assistant"}

    im_start = tokenizer.im_start_id          # <|im_start|> 的 token id
    im_end = tokenizer.im_end_id              # <|im_end|> 的 token id
    nl_tokens = tokenizer("\n").input_ids     # 换行符的 token id
    _system = tokenizer("system").input_ids + nl_tokens

    data: List[Dict[str, torch.Tensor]] = []

    for source in sources:
        source = source["conversations"]
        # 首句若不是用户发言就丢掉，保证对话从 user 开始
        if roles[source[0]["from"]] != roles["user"]:
            source = source[1:]

        input_id: List[int] = []
        target: List[int] = []

        # 先铺系统消息：input 里保留全文，target 里整段屏蔽掉
        system = [im_start] + _system + tokenizer(system_message).input_ids \
            + [im_end] + nl_tokens
        input_id += system
        target += [im_start] + [IGNORE_TOKEN_ID] * (len(system) - 3) \
            + [im_end] + nl_tokens
        assert len(input_id) == len(target)

        for sentence in source:
            role = roles[sentence["from"]]
            _input_id = tokenizer(role).input_ids + nl_tokens \
                + tokenizer(sentence["value"]).input_ids + [im_end] + nl_tokens
            input_id += _input_id

            if role == "<|im_start|>user":
                # 用户说的话不参与 loss，整段填 IGNORE_TOKEN_ID
                _target = [im_start] + [IGNORE_TOKEN_ID] * (len(_input_id) - 3) \
                    + [im_end] + nl_tokens
            elif role == "<|im_start|>assistant":
                # 助手回答要学，只屏蔽掉角色前缀那几个 token
                prefix_len = len(tokenizer(role).input_ids)
                _target = [im_start] + [IGNORE_TOKEN_ID] * prefix_len \
                    + _input_id[prefix_len + 1:-2] + [im_end] + nl_tokens
            else:
                raise NotImplementedError(f"未知角色：{role}")
            target += _target

        assert len(input_id) == len(target)

        # 超长直接截断到 max_len
        ids = torch.tensor(input_id[:max_len], dtype=torch.int)
        # 非 padding 位置为 1，让注意力跳过填充位
        attention_mask = ids.ne(tokenizer.pad_token_id)
        data.append(dict(input_ids=ids, attention_mask=attention_mask))

    return data


def build_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser("Model Quantization using AutoGPTQ")
    parser.add_argument("--model_name_or_path", type=str, required=True,
                        help="待量化的模型目录（LoRA 请先合并权重）")
    parser.add_argument("--data_path", type=str, required=True,
                        help="校准数据 JSON，几百条真实对话即可")
    parser.add_argument("--out_path", type=str, required=True,
                        help="量化产物输出目录")
    parser.add_argument("--max_len", type=int, default=8192,
                        help="单条校准样本的最大 token 数")
    parser.add_argument("--bits", type=int, default=4,
                        help="量化位宽，4 表示 int4")
    parser.add_argument("--group_size", type=int, default=128,
                        help="分组量化的组大小，每 128 个权重共享一组量化参数")
    return parser.parse_args()


def main() -> None:
    args = build_args()

    logging.basicConfig(
        format="%(asctime)s %(levelname)s [%(name)s] %(message)s",
        level=logging.INFO,
        datefmt="%Y-%m-%d %H:%M:%S",
    )

    quantize_config = BaseQuantizeConfig(
        bits=args.bits,
        group_size=args.group_size,   # 分组量化：组内共享缩放系数，组越小精度越好、体积越大
        damp_percent=0.01,            # 阻尼系数，调大可抑制量化带来的数值抖动
        desc_act=False,               # False 明显提速，困惑度会略微变差
        static_groups=False,          # False 表示分组在量化过程中可动态调整
        sym=True,                     # 对称量化，零点固定在 0，误差更小
        true_sequential=True,         # 按权重顺序逐个处理，精度更高
        model_name_or_path=None,
        model_file_base_name="model",
    )

    tokenizer = AutoTokenizer.from_pretrained(
        args.model_name_or_path, trust_remote_code=True)
    # Qwen 没有单独的 pad token，用结束符顶上
    tokenizer.pad_token_id = tokenizer.eod_id

    with open(args.data_path, encoding="utf-8") as f:
        raw = json.load(f)
    data = preprocess(raw, tokenizer, args.max_len)
    logging.info("校准样本数：%d", len(data))

    model = AutoGPTQForCausalLM.from_pretrained(
        args.model_name_or_path,
        quantize_config,
        device_map="auto",
        trust_remote_code=True,
    )

    # 真正的量化在这一行发生，日志会逐层打印 avg loss
    # cache_examples_on_gpu=False：校准中间结果放 CPU，省显存
    model.quantize(data, cache_examples_on_gpu=False)

    # use_safetensors=True：存成 safetensors，加载时不执行任意代码
    model.save_quantized(args.out_path, use_safetensors=True)
    tokenizer.save_pretrained(args.out_path)
    logging.info("量化完成，产物已写入：%s", args.out_path)


if __name__ == "__main__":
    main()

"""vLLM 离线批量推理：一次把整批 prompt 喂进去，拿回全部结果。

离线模式不起 HTTP 服务，适合跑评测、批量刷数据。
依赖：pip install vllm
运行：python vllm_offline_infer.py --model <模型目录>
"""

import argparse

from vllm import LLM, SamplingParams


def build_args() -> argparse.Namespace:
    parser = argparse.ArgumentParser("vLLM offline batch inference")
    parser.add_argument("--model", type=str, required=True,
                        help="模型目录，合并后的全量权重或 GPTQ 量化产物都行")
    parser.add_argument("--temperature", type=float, default=0.8,
                        help="采样温度，越大越发散")
    parser.add_argument("--top_p", type=float, default=0.95,
                        help="核采样阈值")
    parser.add_argument("--max_tokens", type=int, default=100,
                        help="单条输出的最大 token 数")
    return parser.parse_args()


def main() -> None:
    args = build_args()

    # 一次投喂多条，vLLM 内部会自己做连续批处理，不必等凑满一批
    prompts = [
        "总结下面这段文本的摘要：随着科技的飞速发展，我们的生活方式也在悄然改变。"
        "智能手机、人工智能、物联网等科技产品的出现，为我们的日常生活带来了更多便利和舒适。",
        "用三句话说明什么是 KV cache。",
    ]

    sampling_params = SamplingParams(
        temperature=args.temperature,
        top_p=args.top_p,
        max_tokens=args.max_tokens,
    )

    # trust_remote_code=True：Qwen 等带自定义建模代码的模型需要它
    llm = LLM(model=args.model, trust_remote_code=True)

    outputs = llm.generate(prompts, sampling_params)

    for output in outputs:
        print("=" * 60)
        print("Prompt:", output.prompt)
        print("Output:", output.outputs[0].text)


if __name__ == "__main__":
    main()

"""用 OpenAI 客户端访问 vLLM 起的 api server，并顺手量一下输出速度。

服务端地址与凭据全部来自环境变量，脚本里不写死任何 key：
    export VLLM_BASE_URL="http://127.0.0.1:8000/v1"
    export VLLM_API_KEY="本地服务随便填一个占位串"
    export VLLM_MODEL="add1"      # 指定走哪个 LoRA；留空则走基座模型

依赖：pip install openai
运行：python vllm_client.py
"""

import os
import time

from openai import OpenAI


def build_client() -> OpenAI:
    base_url = os.environ.get("VLLM_BASE_URL", "http://127.0.0.1:8000/v1")
    # vLLM 本地服务不校验 key，但 openai SDK 要求这个字段非空，
    # 所以仍然从环境变量取，绝不在源码里写死真实凭据
    api_key = os.environ.get("VLLM_API_KEY")
    if not api_key:
        raise RuntimeError("未找到 VLLM_API_KEY，请先在环境变量里配置")
    return OpenAI(api_key=api_key, base_url=base_url)


def call_server(client: OpenAI, prompt: str) -> str:
    # model 传 LoRA 的挂载名就走那个 LoRA，传空字符串则走基座模型
    model = os.environ.get("VLLM_MODEL", "")
    result = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
        max_tokens=2048,
    )
    return result.choices[0].message.content


def main() -> None:
    client = build_client()
    prompt = "用一段话说明 PagedAttention 解决了什么问题。"

    start = time.time()
    answer = call_server(client, prompt)
    cost = time.time() - start

    print(answer)
    print("-" * 60)
    print(f"输出长度：{len(answer)} 字")
    print(f"耗时：{cost:.2f} 秒")
    print(f"输出速度：{len(answer) / cost:.2f} 字/秒")


if __name__ == "__main__":
    main()

#!/usr/bin/env bash
# vLLM api server 启动骨架，改完 TODO 直接 bash serve_vllm.template.sh
set -euo pipefail

# TODO 1: 基座模型或量化产物目录
MODEL_PATH="TODO-PATH-TO-MODEL"
# TODO 2: 对外端口，容器/云平台上还要在控制台做端口映射
PORT="${PORT:-8000}"
# TODO 3: 用哪块卡
export CUDA_VISIBLE_DEVICES="${CUDA_VISIBLE_DEVICES:-0}"

# ---------- 写法一：模块入口，最通用 ----------
python -m vllm.entrypoints.openai.api_server \
  --model "${MODEL_PATH}" \
  --host 0.0.0.0 \
  --port "${PORT}" \
  --trust_remote_code True

# ---------- 写法二：同时挂多个 LoRA ----------
# 挂上去之后，客户端用 model 参数点名走哪个 LoRA，传空串则走基座模型。
# 去掉下面的注释并补上 TODO 路径即可启用（注意与写法一二选一）。
#
# vllm serve "${MODEL_PATH}" \
#   --host 0.0.0.0 \
#   --port "${PORT}" \
#   --enable-lora \
#   --lora-modules \
#     cot=TODO-PATH-TO-LORA-A/checkpoint-1250/ \
#     cat=TODO-PATH-TO-LORA-B/checkpoint-120/ \
#     spo=TODO-PATH-TO-LORA-C/checkpoint-375/

### LoRA / QLoRA 权重合并模板
### 用法：llamafactory-cli export merge_lora.template.yaml
### 合并时不要使用量化模型，也不要写 quantization_bit

### model
# TODO 1: 基座模型路径或 HuggingFace 模型 ID，必须与训练时用的基座完全一致
model_name_or_path: TODO-PATH-TO-BASE-MODEL
# TODO 2: 训练产出的 adapter 目录（checkpoint-xxx 那一层）
adapter_name_or_path: TODO-PATH-TO-LORA-CHECKPOINT
# 合并 Qwen2 系列时必须为 qwen
template: qwen
# 无论训练时用的是 LoRA 还是 QLoRA，这里一律填 lora
finetuning_type: lora

### export
# TODO 3: 合并后完整权重的落盘目录
export_dir: models/qwen2-7b-sft-lora-merged
# 单个权重分片的最大体积，单位 GB
export_size: 2
# 合并在 CPU 上做，显存不够也能完成；有充裕显存可改 cuda
export_device: cpu
# 是否导出为旧版 .bin 格式，false 表示使用 safetensors
export_legacy_format: false

#!/usr/bin/env bash
# vLLM api server 启动骨架，改完 TODO 直接 bash serve_vllm.template.sh
set -euo pipefail

# TODO 1: 基座模型或量化产物目录
MODEL_PATH="TODO-PATH-TO-MODEL"
# TODO 2: 对外端口，容器/云平台上还要在控制台做端口映射
PORT="${PORT:-8000}"
# TODO 3: 用哪块卡
export CUDA_VISIBLE_DEVICES="${CUDA_VISIBLE_DEVICES:-0}"

# ---------- 写法一：模块入口，最通用 ----------
python -m vllm.entrypoints.openai.api_server \
  --model "${MODEL_PATH}" \
  --host 0.0.0.0 \
  --port "${PORT}" \
  --trust_remote_code True

# ---------- 写法二：同时挂多个 LoRA ----------
# 挂上去之后，客户端用 model 参数点名走哪个 LoRA，传空串则走基座模型。
# 去掉下面的注释并补上 TODO 路径即可启用（注意与写法一二选一）。
#
# vllm serve "${MODEL_PATH}" \
#   --host 0.0.0.0 \
#   --port "${PORT}" \
#   --enable-lora \
#   --lora-modules \
#     cot=TODO-PATH-TO-LORA-A/checkpoint-1250/ \
#     cat=TODO-PATH-TO-LORA-B/checkpoint-120/ \
#     spo=TODO-PATH-TO-LORA-C/checkpoint-375/

"""用 OpenAI 客户端访问 vLLM 起的 api server，并顺手量一下输出速度。

服务端地址与凭据全部来自环境变量，脚本里不写死任何 key：
    export VLLM_BASE_URL="http://127.0.0.1:8000/v1"
    export VLLM_API_KEY="本地服务随便填一个占位串"
    export VLLM_MODEL="add1"      # 指定走哪个 LoRA；留空则走基座模型

依赖：pip install openai
运行：python vllm_client.py
"""

import os
import time

from openai import OpenAI


def build_client() -> OpenAI:
    base_url = os.environ.get("VLLM_BASE_URL", "http://127.0.0.1:8000/v1")
    # vLLM 本地服务不校验 key，但 openai SDK 要求这个字段非空，
    # 所以仍然从环境变量取，绝不在源码里写死真实凭据
    api_key = os.environ.get("VLLM_API_KEY")
    if not api_key:
        raise RuntimeError("未找到 VLLM_API_KEY，请先在环境变量里配置")
    return OpenAI(api_key=api_key, base_url=base_url)


def call_server(client: OpenAI, prompt: str) -> str:
    # model 传 LoRA 的挂载名就走那个 LoRA，传空字符串则走基座模型
    model = os.environ.get("VLLM_MODEL", "")
    result = client.chat.completions.create(
        model=model,
        messages=[{"role": "user", "content": prompt}],
        max_tokens=2048,
    )
    return result.choices[0].message.content


def main() -> None:
    client = build_client()
    prompt = "用一段话说明 PagedAttention 解决了什么问题。"

    start = time.time()
    answer = call_server(client, prompt)
    cost = time.time() - start

    print(answer)
    print("-" * 60)
    print(f"输出长度：{len(answer)} 字")
    print(f"耗时：{cost:.2f} 秒")
    print(f"输出速度：{len(answer) / cost:.2f} 字/秒")


if __name__ == "__main__":
    main()