上一篇写的用模型量化自己的教程一塌糊涂，而且量化出来的也不太能够使用，会有严重的胡说八道的现象。
大概是处于一个既不是我，又不是Qwen的状态。——反正就是离人很远

Q: 为什么你喜欢我
A: 因为我们有共同的语言，能分享生活中的点点滴滴，还有你的支持与陪伴让我感到很温暖。

Q: 你在做什么
A: 我在聊天呢
Q: 聊什么
A: 没什么，就是随意聊聊
Q: 和谁聊
A: 你呀

所以又开了一个新的GPU实例，配置了48G显存的RTX4090，这次可以量化的模型参数量可以配置的高一些了。
希望能量化出可以使用的模型。

拿到新系统的第一刻，还是无卡启动进行配置更新，安装conda，git，fnm，安装pytorch，node，cmake……
让这个系统到一个可以被使用的地步。

环境配置

更新系统软件源

1
2

sudo apt update
sudo apt upgrade -y

安装Git

1
2

sudo apt install git -y
git --version

使用Miniforge配置Python 3.11环境

1
2
3
4
5
6
7

wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh
source ~/.bashrc
conda config --set auto_activate_base false
conda create -n llama python=3.11 -y
conda activate llama
python --version

执行最后一项验证后，终端输出将为Python 3.11.x。Miniforge默认配置conda-forge源并集成mamba，后续进入该环境执行conda activate llama即可。

安装Node.js

使用fnm安装并配置Node.js 24

1
2
3
4
5
6
7

curl -fsSL https://fnm.vercel.app/install | bash
source ~/.bashrc
fnm install 24
fnm use 24
fnm default 24
node --version
npm --version

安装训练框架LLaMA-Factory

LLaMA-Factory是一站式微调平台，封装了数据处理、LoRA训练、权重合并与导出全流程。

1
2
3
4
5
6
7
8
9
10

# 激活训练环境
conda activate llama

# 克隆仓库
git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory

# 安装依赖
pip install -e ".[torch,metrics]"
pip install flash-attn --no-build-isolation

锁定与框架兼容的依赖版本：

1
2

pip install "huggingface_hub<2.0,>=1.5.0"
pip check

验证：pip check无冲突输出；执行llamafactory-cli --help能正常显示帮助信息。

说明：huggingface-hub 2.x版本与transformers、gradio、tokenizers存在依赖冲突，锁定在1.x可保证WebUI与训练流程正常。

下载基座模型

推荐基座：OpenPipe/Qwen3-14B-Instruct

该版本已移除Qwen3默认的<think>思维链输出，回归直接问答模式，对微调友好，契合微信聊天中碎片化、短句、快速接梗的表达特征。

版本选择三条准则

• 选择带-Instruct后缀的指令对齐版，不使用-Base预训练底模（Base未做对话对齐，只会续写不会问答）。
• 不使用带-Thinking的版本（会先输出大段思维链，破坏随性对话节奏）。
• 不使用带-AWQ/-GPTQ的版本（这类是量化推理专用包，不用于训练）。

模型完整权重约29GB，下载到本地目录，训练时直接指定本地路径。

1
2
3
4
5

# 国内网络建议启用镜像加速
export HF_ENDPOINT=https://hf-mirror.com

hf download OpenPipe/Qwen3-14B-Instruct \
    --local-dir ./models/Qwen3-14B-Instruct

验证：进入./models/Qwen3-14B-Instruct目录，确认存在以下文件：

• config.json
• tokenizer.json、tokenizer_config.json、vocab.json、merges.txt
• model-00001-of-00006.safetensors等多个权重分卷
• model.safetensors.index.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

(base) ubuntu@10-60-22-134:~/models$ ls -alh
total 25G
drwxrwxr-x  2 ubuntu ubuntu 4.0K Oct 17 20:03 .
drwxr-x--- 17 ubuntu ubuntu 4.0K Oct 17 20:06 ..
-rw-rw-r--  1 ubuntu ubuntu  381 Oct 17 20:03 Modelfile
-rw-rw-r--  1 ubuntu ubuntu 2.7K Oct 17 20:03 chat_template.jinja
-rw-rw-r--  1 ubuntu ubuntu 1.7K Oct 17 20:01 config.json
-rw-rw-r--  1 ubuntu ubuntu  213 Oct 17 20:01 generation_config.json
-rw-------  1 ubuntu ubuntu 4.7G Oct 17 20:02 model-00001-of-00006.safetensors
-rw-------  1 ubuntu ubuntu 4.6G Oct 17 20:02 model-00002-of-00006.safetensors
-rw-------  1 ubuntu ubuntu 4.7G Oct 17 20:02 model-00003-of-00006.safetensors
-rw-------  1 ubuntu ubuntu 4.6G Oct 17 20:02 model-00004-of-00006.safetensors
-rw-------  1 ubuntu ubuntu 4.7G Oct 17 20:03 model-00005-of-00006.safetensors
-rw-------  1 ubuntu ubuntu 4.5G Oct 17 20:03 model-00006-of-00006.safetensors
-rw-rw-r--  1 ubuntu ubuntu  36K Oct 17 20:03 model.safetensors.index.json
-rw-rw-r--  1 ubuntu ubuntu  11M Oct 17 20:03 tokenizer.json
-rw-rw-r--  1 ubuntu ubuntu  719 Oct 17 20:03 tokenizer_config.json

说明：上文4个分词相关文件在后续转换GGUF时必需，请确认目录完整。

微信聊天记录处理

导出聊天记录

使用WeFlow导出微信私聊记录，得到JSON文件。导出格式说明：

说明：私聊场景中isSend: 1恒为你本人，与聊天对象无关，因此批量处理多个联系人的逻辑完全通用。

建议导出多个联系人的私聊记录，合并为统一训练集，样本越丰富风格覆盖越完整。

语料规模建议

1,000 ~ 5,000条高质量多轮 / 单轮样本，足以让LoRA捕捉稳定的语言偏置。

转换脚本

目的：把原始导出文件转换为ShareGPT格式的多轮训练数据。核心处理是时间窗口合并——把你在连续几分钟内发出的多条短句用换行符拼接成一条完整回复，保留真实的断句节奏。

创建process_weflow.py：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128

import json
import re
from pathlib import Path

# 配置待处理的文件列表（WeFlow 导出的各联系人 JSON）
INPUT_FILES = [
    "私聊_***-7a31c*****.json",  # 示范文件
]
OUTPUT_FILE = "persona_sft_dataset_all.json"

TIME_THRESHOLD = 180   # 3 分钟（180 秒）内的连续发言合并为一轮
MAX_TURNS = 6          # 每个多轮对话样本包含 6 轮问答（12 条消息）


def clean_content(msg: dict) -> str | None:
    """清洗单条消息，返回纯文本；无效消息返回 None"""
    msg_type = msg.get("type", "")
    content = msg.get("content", "")

    # 只保留文本消息与引用消息
    if msg_type not in ["文本消息", "引用消息"]:
        return None
    if not content:
        return None

    # 过滤纯占位符
    ignore_list = ["[图片]", "[表情包]", "[视频]", "[语音通话]", "[视频通话]",
                   "[位置]", "[名片]", "[炸弹]", "[OK]"]
    if content.strip() in ignore_list:
        return None

    # 剥离引用消息自动附加的后缀标签
    content = re.sub(r"\[\s*引用[^\]]*\]", "", content)

    # 清理未配对的右中括号
    content = re.sub(r"(?<!\[)\]", "", content)

    # 手机号脱敏
    content = re.sub(r"1\d{10}", "13800000000", content)

    content = content.strip()
    return content if content else None


def process_single_file(file_path: str) -> list[dict]:
    """处理单个聊天文件，返回样本列表"""
    if not Path(file_path).exists():
        print(f"未找到文件: {file_path}，跳过")
        return []

    with open(file_path, "r", encoding="utf-8") as f:
        data = json.load(f)

    # 步骤 1：筛选清洗出有效文本序列
    clean_msgs = []
    for m in data.get("messages", []):
        text = clean_content(m)
        if text:
            clean_msgs.append({
                "isSend": m.get("isSend"),
                "time": m.get("createTime", 0),
                "text": text,
            })

    if not clean_msgs:
        return []

    # 步骤 2：滑动时间窗口，合并同一角色的连续发言
    merged_blocks = []
    current_block = {
        "role": "gpt" if clean_msgs[0]["isSend"] == 1 else "human",
        "texts": [clean_msgs[0]["text"]],
        "last_time": clean_msgs[0]["time"],
    }
    for m in clean_msgs[1:]:
        role = "gpt" if m["isSend"] == 1 else "human"
        if role == current_block["role"] and (m["time"] - current_block["last_time"] <= TIME_THRESHOLD):
            current_block["texts"].append(m["text"])
            current_block["last_time"] = m["time"]
        else:
            merged_blocks.append(current_block)
            current_block = {
                "role": role,
                "texts": [m["text"]],
                "last_time": m["time"],
            }
    merged_blocks.append(current_block)

    # 步骤 3：规范为 human -> gpt 严格交替
    dialogue = []
    for block in merged_blocks:
        content = "\n".join(block["texts"])
        if block["role"] == "human":
            dialogue.append({"from": "human", "value": content})
        elif block["role"] == "gpt":
            if dialogue and dialogue[-1]["from"] == "human":
                dialogue.append({"from": "gpt", "value": content})

    # 步骤 4：按固定轮次切分为多个样本
    samples = []
    temp = []
    for i in range(0, len(dialogue) - 1, 2):
        if dialogue[i]["from"] == "human" and dialogue[i + 1]["from"] == "gpt":
            temp.extend([dialogue[i], dialogue[i + 1]])
            if len(temp) >= MAX_TURNS * 2:
                samples.append({"conversations": temp})
                temp = []
    if temp:
        samples.append({"conversations": temp})

    return samples


def main():
    total_dataset = []
    for f in INPUT_FILES:
        samples = process_single_file(f)
        print(f"文件 {f} 生成有效样本: {len(samples)} 组")
        total_dataset.extend(samples)

    with open(OUTPUT_FILE, "w", encoding="utf-8") as out:
        json.dump(total_dataset, out, ensure_ascii=False, indent=2)

    print(f"\n全部合并完成，总计生成 {len(total_dataset)} 组微调样本，已保存至 {OUTPUT_FILE}")


if __name__ == "__main__":
    main()

运行转换

1

python process_weflow.py

验证：生成persona_sft_dataset_all.json，结构如下。注意value中的\n完整保留了连发消息的节奏感：

1
2
3
4
5
6
7
8
9
10

[
  {
    "conversations": [
      {"from": "human", "value": "我早饭是不吃的 午饭是没有的 晚饭是现做的\n能熬到天亮"},
      {"from": "gpt",   "value": "我还好，只有早饭不吃\n但我要89点就起来"},
      {"from": "human", "value": "毕竟人还没睡醒 就来房间通知我她要出去打麻将了\n午饭是根本不用烧的"},
      {"from": "gpt",   "value": "她这何尝不是一种自律呢？\n那你吃什么？"}
    ]
  }
]

说明：原始导出文件通常有几十MB，转换后仅几百KB到几MB，属于正常现象。原始文件包含大量渲染用元数据（内部ID、XML签名、头像CDN链接、表情下载URL等），且大量表情包与图片消息已被过滤，连续短句也被合并压缩。

清洗与隐私脱敏

目的：剔除噪音与敏感信息。训练数据中的隐私会被模型记忆并在外部对话中复述，脱敏是必经步骤。

需处理的内容：

• 表情标签未闭合（如[捂脸缺少右括号）
• 引用消息残留的孤立右中括号
• 真实姓名、私密信息、手机号、登录密码

创建clean_dataset_all.py：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

import json
import re

INPUT_FILE = "persona_sft_dataset_all.json"
OUTPUT_FILE = "persona_sft_dataset_all_clean.json"


def sanitize_text(text: str) -> str:
    # 1. 敏感信息脱敏（按你自己的实际情况调整替换规则）
    text = re.sub(re.escape("1112***"), "11125000", text)          # 学号
    text = re.sub(re.escape("你的真实姓名"), "***", text)          # 真实姓名
    text = re.sub(re.escape("南苑******"), "某宿舍楼101", text)    # 宿舍地址
    text = re.sub(re.escape("密码abc123456"), "密码******", text)  # 明文密码

    # 2. 手机号统一脱敏
    text = re.sub(r"1\d{10}", "13800000000", text)

    # 3. 补全未闭合的微信表情标签
    emoji_names = [
        "坏笑", "捂脸", "流汗", "抱拳", "恐惧", "OK", "握手", "色", "大哭", "玫瑰",
        "害羞", "裂开", "发抖", "发呆", "得意", "调皮", "让我看看", "胜利", "骷髅",
        "转圈", "奸笑", "惊讶", "强", "打脸", "破涕为笑", "憨笑", "合十", "傲慢",
        "凋谢", "生病", "白眼", "快哭了", "微笑", "机智", "偷笑", "困", "衰",
    ]
    for name in emoji_names:
        text = re.sub(rf"\[{name}(?!\])", f"[{name}]", text)

    # 4. 清理多余空行
    text = re.sub(r"\n{3,}", "\n\n", text)
    return text.strip()


with open(INPUT_FILE, "r", encoding="utf-8") as f:
    data = json.load(f)

cleaned_data = []
for item in data:
    new_conversations = []
    skip_item = False
    for conv in item.get("conversations", []):
        val = conv.get("value", "")

        cleaned_val = sanitize_text(val)
        if not cleaned_val:
            skip_item = True
            break
        new_conversations.append({"from": conv["from"], "value": cleaned_val})

    if not skip_item and len(new_conversations) >= 2:
        cleaned_data.append({"conversations": new_conversations})

with open(OUTPUT_FILE, "w", encoding="utf-8") as f:
    json.dump(cleaned_data, f, ensure_ascii=False, indent=2)

print(f"清洗完成！共处理样本 {len(cleaned_data)} 组，已保存至 {OUTPUT_FILE}")

运行清洗：

1

python clean_dataset_all.py

验证：统计有效回复轮数。

1

grep -c '"from": "gpt"' persona_sft_dataset_all_clean.json

输出 ≥ 1000即数据量充裕，可直接进入训练。

注册数据集

放置文件

1

cp persona_sft_dataset_all_clean.json LLaMA-Factory/data/

注册配置

编辑LLaMA-Factory/data/dataset_info.json，在最外层{内添加：

1
2
3
4
5
6
7
8
9
10
11

"my_persona": {
  "file_name": "persona_sft_dataset_all_clean.json",
  "formatting": "sharegpt",
  "columns": { "messages": "conversations" },
  "tags": {
    "role_tag": "from",
    "content_tag": "value",
    "user_tag": "human",
    "assistant_tag": "gpt"
  }
},

校验配置

1
2

cd LLaMA-Factory
python -c "import json; json.load(open('data/dataset_info.json'))"

无输出即JSON语法正确。

在界面中确认（使用WebUI时）

在LLaMA-Factory仓库根目录启动界面：

1
2

cd LLaMA-Factory
nohup llamafactory-cli webui > webui.log 2>&1 &

启动后：

1. 在「数据集」下拉框勾选my_persona。
2. 点击「预览数据集」，确认能看到human与gpt交替的多轮对话。

说明：务必在LLaMA-Factory仓库目录内启动，程序会在当前目录的./data下查找配置。若在其它目录启动，界面将读不到任何数据集。修改配置后需重启界面进程并强制刷新浏览器（Mac：Cmd + Shift + R）。

启动LoRA微调

参数配置表（48GB显存优化值）

三条参数纪律

• 对话模板必须选qwen3_nothink（或qwen），不能用default。default不带千问专属角色标识符，模型无法区分对话双方。
• 学习率必须设在1e-4 ~ 2e-4。1e-5是全参数微调的量级，对LoRA过小，训练后仍会保留基座的通用AI腔。
• LoRA作用模块填all。留空时框架默认只训练注意力层的q/v投影，风格还原不彻底。

启动训练

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

cd LLaMA-Factory
conda activate llama

CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \
    --stage sft \
    --do_train \
    --model_name_or_path /你的绝对路径/models/Qwen3-14B-Instruct \
    --dataset my_persona \
    --dataset_dir ./data \
    --template qwen3_nothink \
    --finetuning_type lora \
    --lora_target all \
    --lora_rank 32 \
    --lora_alpha 64 \
    --lora_dropout 0.05 \
    --output_dir ./saves/persona_14b_lora \
    --overwrite_output_dir \
    --cutoff_len 2048 \
    --preprocessing_num_workers 4 \
    --per_device_train_batch_size 2 \
    --gradient_accumulation_steps 8 \
    --lr_scheduler_type cosine \
    --logging_steps 5 \
    --save_steps 50 \
    --learning_rate 1.5e-4 \
    --num_train_epochs 4.0 \
    --plot_loss \
    --bf16

训练过程观察

说明：训练启动阶段显存被占满而GPU利用率接近0% 属正常现象，此时正在加载权重与分词。正式训练开始后功耗升至400W、利用率达100%。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Every 1.0s: nvidia-smi                                                          10-60-22-134: Sat Oct 17 19:43:50 2026

Sat Oct 17 19:43:50 2026
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 615.71.09              KMD Version: 615.71.09     CUDA UMD Version: 13.4     |
+-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA GeForce RTX 4090        On  |   00000000:00:06.0 Off |                  Off |
|100%   67C    P2            432W /  450W |   48507MiB /  49140MiB |     100%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|    0   N/A  N/A            1427      C   ...ge3/envs/llama/bin/python3.11        386MiB |
|    0   N/A  N/A            1513      C   ...ge3/envs/llama/bin/python3.11      48106MiB |
+-----------------------------------------------------------------------------------------+

合并导出完整模型

目的：把LoRA增量权重合并进基座，得到独立可用的完整模型，后续部署不再依赖适配器。

1
2
3
4
5
6
7
8
9
10
11
12

cd LLaMA-Factory
conda activate llama

llamafactory-cli export \
    --model_name_or_path /你的绝对路径/models/Qwen3-14B-Instruct \
    --adapter_name_or_path ./saves/persona_14b_lora \
    --template qwen3_nothink \
    --finetuning_type lora \
    --export_dir /你的绝对路径/models/my_persona_14b_merged \
    --export_size 4 \
    --export_device cpu \
    --export_legacy_format False

验证：导出目录包含多个.safetensors分卷（14B约25~29GB）、config.json、tokenizer.json、tokenizer_config.json。

转换为GGUF并量化

为什么选择GGUF

量化格式按部署平台选择：

Mac部署使用GGUF。AWQ与GPTQ面向CUDA架构设计，在Apple Silicon的Metal统一内存上无法发挥硬件加速；GGUF深度整合Metal，省内存、发热低、速度快。

编译llama.cpp

1
2
3
4
5
6
7
8
9

# 安装编译工具
sudo apt install cmake -y

# 拉取并编译
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp
cmake -B build
cmake --build build --config Release -j
pip install -r requirements.txt

说明：cmake必须在llama.cpp目录内执行，该目录才包含CMakeLists.txt。

确认分词器配置

目的：确保合并模型的分词配置符合llama.cpp转换脚本的读取要求。

检查合并模型目录（如my_persona_14b_merged）中的tokenizer_config.json，确认extra_special_tokens字段为字典（键值对）格式：

1
2
3
4

"extra_special_tokens": {
  "<|im_start|>": "<|im_start|>",
  "<|im_end|>": "<|im_end|>"
}

若为列表格式（如下），请改为上面的字典格式：

1

"extra_special_tokens": ["<|im_start|>", "<|im_end|>"]

同时确认目录内分词文件齐全：tokenizer.json、tokenizer_config.json、vocab.json、merges.txt。缺失时从基座模型目录复制补齐：

1
2
3
4

cp /你的绝对路径/models/Qwen3-14B-Instruct/tokenizer.json       /你的绝对路径/models/my_persona_14b_merged/
cp /你的绝对路径/models/Qwen3-14B-Instruct/tokenizer_config.json /你的绝对路径/models/my_persona_14b_merged/
cp /你的绝对路径/models/Qwen3-14B-Instruct/vocab.json            /你的绝对路径/models/my_persona_14b_merged/
cp /你的绝对路径/models/Qwen3-14B-Instruct/merges.txt            /你的绝对路径/models/my_persona_14b_merged/

说明：Qwen使用BPE词表，本身不含SentencePiece的tokenizer.model文件。转换脚本会先尝试SentencePiece再回退到GPT2词表路径，属正常流程，无需额外补充tokenizer.model。

转换为GGUF

1
2
3

python /你的绝对路径/llama.cpp/convert_hf_to_gguf.py /你的绝对路径/models/my_persona_14b_merged \
    --outfile /你的绝对路径/models/my_persona_14b_f16.gguf \
    --outtype f16

量化

推荐Q6_K_M：精度接近无损，体积比浮点小一半以上，适合内存充裕的Mac。若追求更小体积选Q4_K_M（约8.5GB）。

1
2
3
4

/你的绝对路径/llama.cpp/build/bin/llama-quantize \
    /你的绝对路径/models/my_persona_14b_f16.gguf \
    /你的绝对路径/models/my_persona_14b_Q6_K_M.gguf \
    Q6_K_M

验证：生成my_persona_14b_Q6_K_M.gguf，Q6_K_M约11~12GB，Q4_K_M约8.5GB。

可在服务器上量化完成后再传回Mac：原始浮点模型近30GB，量化后体积缩减约70%，传输大幅加快。中间产物my_persona_14b_f16.gguf与导出目录的分卷权重可在确认成品无误后清理。

1
2
3

(llama) ubuntu@10-60-22-134:~$ ls -lh /home/ubuntu/models/
-rw-rw-r-- 1 ubuntu ubuntu  28G Oct 17 20:32 my_persona_14b_f16.gguf
-rw-rw-r-- 1 ubuntu ubuntu  12G Oct 17 20:35 my_persona_14b_Q6_K_M.gguf

服务器端加载测试

目的：在传回Mac前确认「转换 → 量化」整条链路成功。

单次推理测试

1
2
3
4

/你的绝对路径/llama.cpp/build/bin/llama-cli \
    -m /你的绝对路径/models/my_persona_14b_Q6_K_M.gguf \
    -p "你好，请介绍一下你自己。" \
    -n 128 -ngl 99 -c 4096

参数说明：

• -ngl 99：全部网络层卸载到GPU。显存不足时会自动回退部分层到CPU，日志显示实际卸载层数。
• -c：上下文长度。Q6_K模型本体约11.3GB，更长上下文需额外数GB显存放KV Cache；若显卡已被其它进程占用较多，先用-c 4096测试。

验证：输出正常、无乱码、无重复，即链路完全成功。

附录 · 关键参数速查

附录 · 全流程命令速查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

llamafactory-cli train \
    --stage sft \
    --do_train \
    --model_name_or_path /home/ubuntu/models/Qwen3-14B-Instruct \
    --preprocessing_num_workers 16 \
    --finetuning_type lora \
    --template qwen3_nothink \
    --flash_attn fa2 \
    --dataset_dir data \
    --dataset my_persona \
    --cutoff_len 2048 \
    --learning_rate 1.5e-4 \
    --num_train_epochs 4.0 \
    --max_samples 100000 \
    --seed 42 \
    --per_device_train_batch_size 2 \
    --gradient_accumulation_steps 8 \
    --lr_scheduler_type cosine \
    --max_grad_norm 1.0 \
    --logging_steps 5 \
    --save_steps 100 \
    --warmup_steps 0 \
    --packing False \
    --enable_thinking False \
    --report_to none \
    --output_dir saves/persona_14b_lora \
    --bf16 \
    --plot_loss \
    --trust_remote_code True \
    --ddp_timeout 180000000 \
    --include_num_input_tokens_seen True \
    --optim adamw_torch \
    --lora_rank 32 \
    --lora_alpha 64 \
    --lora_dropout 0.05 \
    --lora_target all

那就做吧！

去年做blender渲染，找了一下能用的，便宜的云显卡。今年刚好能用上。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

(py310) root@10-23-218-65:~# lscpu | grep -E 'Model name|^CPU\(s\)|Core\(s\) per socket|Socket\(s\)'
CPU(s):                             16
Model name:                         AMD EPYC 7642 48-Core Processor
Core(s) per socket:                 8
Socket(s):                          2
(py310) root@10-23-218-65:~# free -h
               total        used        free      shared  buff/cache   available
Mem:            62Gi       1.9Gi        59Gi       0.0Ki       1.5Gi        60Gi
Swap:             0B          0B          0B
(py310) root@10-23-218-65:~# nvidia-smi
Thu Oct 15 17:20:42 2026
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 595.80                 Driver Version: 595.80         CUDA Version: 13.2     |
+-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA GeForce RTX 4090        Off |   00000000:00:03.0 Off |                  Off |
| 45%   36C    P8             10W /  450W |       1MiB /  24564MiB |      0%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+

哎呀！怎么都涨价了？已经翻三倍了
草草用用吧。

1. 服务器基线确认

1.1 前置条件

已从算力平台获得：IP、SSH端口、root密码、已选镜像（PyTorch 2.1.2 / Python 3.10 / CUDA 12.1）。

1.2 登录与系统确认

1
2

# 从本地 Mac 连接；-p 23 为平台分配的 SSH 端口，非默认 22
ssh -p 23 root@106.75.240.167

可验证结果：

1
2
3
4
5

The authenticity of host '[106.75.240.167]:23 ([106.75.240.167]:23)' can't be established.
ED25519 key fingerprint is: SHA256:BbzgCQAzNbffEbv62JMv73XMooEY1edca97CJtjO27o
...
Welcome to Ubuntu 22.04.3 LTS (GNU/Linux 5.15.0-113-generic x86_64)
(py310) root@10-23-218-65:~#

提示符(py310)说明conda已自动激活预置环境py310，路径在/usr/local/miniconda3/envs/py310。这一步决定了后续第2节的坑。

1.3 GPU与驱动确认

1
2
3

nvidia-smi                       # 预期：驱动版本 + CUDA Version + 23.5GB 显存 + 0 占用
watch -n 1 nvidia-smi            # 训练期间盯 Memory-Usage 与 Volatile GPU-Util
nvtop                            # 彩色曲线版，未预装时 apt install nvtop

可验证结果：nvidia-smi输出中Memory-Usage初始接近0 MiB；训练开始后应稳定在 16~21 GB区间，Volatile GPU-Util维持90~100%。低于50%说明数据加载或 batch配置存在瓶颈。

1.4 磁盘确认

1
2

df -h            # 系统盘通常 30~50GB，模型与产物必须放数据盘
du -sh ~/.cache/modelscope    # 基座模型缓存，7B bf16 约 15GB

7B模型会产出三份大文件：基座缓存（~15GB）+ 合并模型（~15GB）+ GGUF（4~8GB）。系统盘放不下时必须切数据盘（AutoDL为/root/autodl-tmp）。

2. 安装LLaMA-Factory

2.1 操作目的

获得训练 / 合并导出 / 格式转换的统一入口llamafactory-cli。

1
2
3

git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e .[metrics]        # -e 可编辑安装；[metrics] 附带评估指标依赖

2.2 报错 1：Python版本不满足

触发命令：pip install -e .[metrics]（在默认py310环境中）

错误原文：

1
2
3

INFO: pip is looking at multiple versions of llamafactory to determine which version is compatible with
other requirements. This could take a while.
ERROR: Package 'llamafactory' requires a different Python: 3.10.16 not in '>=3.11.0'

排查定位：报错直指llamafactory==0.9.6.dev0的元数据约束。从同一段日志可看到该版本的依赖收敛范围：

1
2
3
4

Collecting transformers!=4.57.0,!=5.6.0,<=5.8.0,>=4.55.0 (from llamafactory==0.9.6.dev0)
Collecting trl<=0.24.0,>=0.18.0 (from llamafactory==0.9.6.dev0)
Collecting peft<=0.18.1,>=0.18.0 (from llamafactory==0.9.6.dev0)
Collecting accelerate<=1.11.0,>=1.3.0 (from llamafactory==0.9.6.dev0)

即：0.9.6.dev0强制Python ≥ 3.11，与镜像预置的3.10.16冲突。选型阶段推荐的「Python 3.10依赖冲突最少」在此版本上已失效。

解决过程：新建conda环境后重装。

1
2
3
4

conda create -n py311 python=3.11 -y
conda activate py311
cd ~/LLaMA-Factory
pip install -e .[metrics]

可验证结果：

1
2
3

python -V                        # Python 3.11.x
pip show llamafactory | head -3  # Version: 0.9.6.dev0
llamafactory-cli --version       # 命令可用

实测装到的关键版本：torch 2.14.1、transformers 5.8.0、peft 0.18.1、trl 0.24.0、accelerate 1.11.0、gradio 5.50.0、modelscope 1.40.2。

版本号核验（重要）：日志中的llamafactory==0.9.6.dev0不是发布版本。核验结果：

1
2

gh api repos/hiyouga/LLaMA-Factory/tags --jq '.[].name' | head -5   # v0.9.5 v0.9.4 v0.9.3 ...
curl -s https://pypi.org/pypi/llamafactory/json                     # latest: 0.9.5

PyPI与GitHub tag最新均为 v0.9.5，不存在0.9.6。0.9.6.dev0是pip install -e .从master源码安装时，setuptools_scm基于最新tag自动推断出的开发态版本号（即v0.9.5之后的未发布快照）。

影响：凡本文引用src/llamafactory/...源码作为依据处，均指master分支当前代码，与v0.9.5正式版可能存在差异；与0.9.6.dev0快照的差异未做逐commit比对。

结论：镜像选择应直接选Python 3.11，可省掉这一轮重建。CUDA版本仍选12.1（预编译wheel的最大公约数，避免云端源码编译）。

3. 数据集构造与注册

3.1 前置条件

语料为微信聊天记录，由WeFlow导出为JSON，字段含type（消息类型）、content（文本）、createTime（秒级时间戳）、isSend（0=对方 / 1=我）。

3.2 操作目的

把「一问一答」升级为「多轮对话」，保留真实的上下文抛接结构。

关键参数（脚本内）：

• 静默阈值 30分钟：双方无消息超过该值即切分新的Session；
• 阵营合并：Session内同一人的连续消息合并为单条，直到对方插话；
• 入库约束：首条必须human、末条必须gpt、至少2轮。

可验证结果：脚本输出重构完成！共提炼出1729个高质量多轮对话局，已保存至 sharegpt_train_data.json。

3.3 注册数据集

编辑data/dataset_info.json，把配置插在最外层{下面（不是追加到文件末尾）：

1
2
3
4
5
6
7
8
9
10
11

"personal_style_sharegpt": {
  "file_name": "sharegpt_train_data.json",   // 放 data/ 目录下
  "formatting": "sharegpt",                  // 多轮格式，区别于 alpaca 单轮
  "columns": { "messages": "conversations", "system": "system" },
  "tags": {
    "role_tag": "from",                      // 角色字段名
    "content_tag": "value",                  // 内容字段名
    "user_role": "human",                    // 对方
    "bot_role": "gpt"                        // 我
  }
},

3.4 验证方式

WebUI Train页点击 预览数据集，弹窗第一条应是完整的多轮微信对话；命令行侧以训练日志Num examples = 1,729为准。

3.5 报错 2：样本被丢弃

触发命令：首次训练启动

错误原文：

1

[WARNING|2026-10-11 13:19:54] llamafactory.data.processor.supervised:149 >> Dropped invalid example: []

排查定位：日志中Dropped invalid example:后的列表为空[]，说明被丢弃的样本内容为空——即数据集注册格式与文件格式不匹配（alpaca格式配置去读 sharegpt文件，或反之），解析出的对话列表为空。该WARNING不中断训练，但会静默减少有效样本量。

解决过程：核对dataset_info.json的formatting与tags是否与JSON文件实际字段一致。修正后重跑，日志显示Num examples = 1,729（无 dropped）。

结论：Dropped invalid example必须用Num examples交叉验证，不能只看「训练跑起来了」。

4. 训练

4.1 参数选择依据

先量化数据长度分布，再定cutoff_len

1
2
3
4
5
6
7
8
9
10
11
12

import json
with open("sharegpt_train_data.json", "r", encoding="utf-8") as f:
    dataset = json.load(f)
max_chars = exceed_count = total_chars = 0
for item in dataset:
    item_chars = sum(len(t.get("value", "")) for t in item.get("conversations", []))
    total_chars += item_chars
    max_chars = max(max_chars, item_chars)
    if item_chars > 500:
        exceed_count += 1
print(len(dataset), total_chars / len(dataset), max_chars, exceed_count)
# 1 汉字 ≈ 1.5~2 Token；1024 Token ≈ 500~650 汉字

实测输出：1729条 / 平均265.7字符 / 最大5313字符 / 超500字符的242条。

4.2 报错 3/4/5：三次CUDA OOM

触发配置与结果：

错误原文（第 1 次）：

1
2
3
4
5
6

torch.OutOfMemoryError: CUDA out of memory. Tried to allocate 2.38 GiB. GPU 0 has a total capacity of
23.52 GiB of which 2.20 GiB is free. Process 312 has 386.00 MiB memory in use. Including non-PyTorch
memory, this process has 20.92 GiB memory in use. Of the allocated memory 18.82 GiB is allocated by
PyTorch, and 1.64 GiB is reserved by PyTorch but unallocated. If reserved but unallocated memory is
large try setting PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True to avoid fragmentation.
0%| | 0/165 [00:06<?, ?it/s]

第 2、3 次报错同构，仅数字变化：Tried to allocate 2.32 GiB ... of which 2.08 GiB is free ... this process has 21.04 GiB memory in use。

排查定位：

• 崩溃点固定在transformers/loss/loss_utils.py:37 fixed_cross_entropy→torch._C._nn.cross_entropy_loss，即反向传播起点，不是前向；
  -18.82 GiB is allocated by PyTorch说明基座权重 + 激活值已吃满，剩余2.20 GiB不够分配logits的梯度（batch×seq×152064词表）；
• 关键：第3次已开gradient_checkpointing仍崩 → 说明单样本峰值由最长序列决定，而数据中存在5,313字符的样本。cutoff_len 2048下该样本的 logits 张量本身就是显存炸弹。

解决过程：把cutoff_len从2048降到1024、batch降到1、梯度累积升到32保持等效batch size不变。

1

export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True   # 可选：缓解碎片，非必需

4.3 报错 6：输出目录已存在

触发命令：第二次启动训练（沿用相同--output_dir）

错误原文：

1

ValueError: Output directory already exists and is not empty. Please set`overwrite_output_dir`.

排查定位：安全拦截——目录下已有上一次的checkpoint。

解决过程：二选一。

1
2
3
4

# 方案 A：显式允许覆盖（会清掉旧 checkpoint）
--overwrite_output_dir True
# 方案 B：换目录名保留历史（推荐，便于对比不同超参）
--output_dir saves/Qwen2.5-7B-Instruct/lora/train_2026-10-11-12-57-43-v2

4.4 最终可用命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

llamafactory-cli train \
  --stage sft --do_train True \
  --model_name_or_path Qwen/Qwen2.5-7B-Instruct \
  --preprocessing_num_workers 16 \
  --finetuning_type lora --template qwen --flash_attn auto \
  --dataset_dir data --dataset personal_style_sharegpt \
  --cutoff_len 1024 \                      # 截断长度：实测 242 条超长样本会在此处被切尾
  --learning_rate 2e-05 --num_train_epochs 3.0 --max_samples 100000 --seed 42 \
  --per_device_train_batch_size 1 \        # 单卡单样本，规避 OOM
  --gradient_accumulation_steps 32 \        # 1×32 = 等效 batch size 32
  --lr_scheduler_type cosine --max_grad_norm 1.0 \
  --logging_steps 5 --save_steps 100 --warmup_steps 0 \
  --packing False --enable_thinking True --report_to none \
  --output_dir saves/Qwen2.5-7B-Instruct/lora/train_2026-10-11-12-57-43-v2 \
  --overwrite_output_dir True \
  --bf16 True --plot_loss True --trust_remote_code True \
  --ddp_timeout 180000000 --include_num_input_tokens_seen True \
  --optim adamw_torch --gradient_checkpointing True \   # 重算激活值，显存换时间
  --lora_rank 8 --lora_alpha 16 --lora_dropout 0 --lora_target all

可验证结果：

1
2
3
4
5
6
7

Num examples = 1,729 | Num Epochs = 3 | Num update steps per epoch = 55
Instantaneous batch size per device = 1 | Gradient Accumulation steps = 32
Total train batch size (w. parallel, distributed & accumulation) = 32
Total optimization steps = 165
Fine-tuning method: LoRA
Found linear modules: k_proj,down_proj,gate_proj,q_proj,up_proj,o_proj,v_proj
trainable params: 20,185,088 | all params: 7,635,801,600 | trainable%: 0.2643

Loss轨迹：5.7270 → 4.0200（约40步）→ 3.8~4.0 横盘 → 4.3965（第165步末端反弹），train_loss 4.4711。

末端反弹原因：lr_scheduler_type cosine把学习率压到1.8125e-09，优化器失去修正能力，同时shuffle末尾撞上风格突变样本。该解释基于日志推断，非官方结论，标注为待验证。

5. 合并导出（LoRA → 完整HF模型）

5.1 前置条件

第4节训练完成，产出saves/Qwen2.5-7B-Instruct/lora/train_2026-10-11-12-57-43-v2。

5.2 操作目的

把LoRA低秩矩阵吸收进基座权重，产出独立的、不依赖adapter的标准HF目录——这是量化的必需前置，量化工具不接受分离的adapter。

1
2
3
4
5
6
7
8
9

llamafactory-cli export \
  --model_name_or_path Qwen/Qwen2.5-7B-Instruct \
  --adapter_name_or_path saves/Qwen2.5-7B-Instruct/lora/train_2026-10-11-12-57-43-v2 \
  --template qwen \
  --finetuning_type lora \
  --export_dir models/chenxinyu-qwen2.5-7b-chat \
  --export_size 2 \                 # 分片大小，单位 GB；源码默认 5
  --export_device cuda \
  --export_legacy_format False      # False = 输出 safetensors；True = 旧式 .bin

参数依据（src/llamafactory/hparams/model_args.py）：

1
2
3
4
5

export_size: int = field(default=5, metadata={"help": "The file shard size (in GB) of the exported model."})
export_device: Literal["cpu", "auto"] = field(default="cpu",
    metadata={"help": "The device used in model export, use`auto`to accelerate exporting."})
export_legacy_format: bool = field(default=False,
    metadata={"help": "Whether or not to save the`.bin`files instead of`.safetensors`."})

⚠️ 版本差异：main分支的export_device只接受cpu/auto，而本文实测在0.9.6.dev0上传cuda被正常接受并完成导出。以实际版本的llamafactory-cli export --help为准。

5.3 可验证结果

1
2
3
4

Loading checkpoint shards: 100%|██████████| 4/4 [00:00<00:00, 91.87it/s]
[INFO] llamafactory.model.adapter:144 >> Merged 1 adapter(s).
[INFO] llamafactory.model.adapter:144 >> Loaded adapter(s): saves/.../train_2026-10-11-12-57-43-v2
[INFO] llamafactory.model.loader:144 >> all params: 7,615,616,512

目录内容：

1
2
3
4
5

ls LLaMA-Factory/models/chenxinyu-qwen2.5-7b-chat
# added_tokens.json  chat_template.jinja  config.json  generation_config.json
# merges.txt  model-00001-of-00004.safetensors  ...  model-00004-of-00004.safetensors
# model.safetensors.index.json  special_tokens_map.json
# tokenizer.json  tokenizer_config.json  vocab.json

注意：导出目录缺少tokenizer.model（Qwen2.5使用tokenizer.json现代词表，非SentencePiece.model）。这直接导致第6节的报错9。

6. 量化：四条路径的实测结果

路径结论汇总（先看结果）

唯一可达成目标的路径是C。 B的失败见6.2，C的完整做法见6.3，D的定位见6.4。

6.1 路径A：LLaMA-Factory直接导出GGUF —— 失败

操作：Export页面选择「导出量化等级」，或命令行--export_quantization_bit。

现象：WebUI中「导出量化等级」下拉框置灰不可选；命令行方式同样未产出GGUF。

源码级排查（克隆hiyouga/LLaMA-Factorymain分支，src/llamafactory/webui/components/export.py）：

1
2
3
4
5
6
7
8
9
10

GPTQ_BITS = ["8", "4", "3", "2"]                      # 第 37 行

# 下拉框的全部可选项 —— 注意：没有 q4_k_m / q8_0
export_quantization_bit = gr.Dropdown(choices=["none"] + GPTQ_BITS, value="none")   # 第 121 行

def can_quantize(checkpoint_path: str | list[str]) -> "gr.Dropdown":                # 第 40 行
    if isinstance(checkpoint_path, list) and len(checkpoint_path) != 0:
        return gr.Dropdown(value="none", interactive=False)      # ← 置灰的确切条件
    else:
        return gr.Dropdown(interactive=True)

置灰根因（已定位，非"环境缺组件"）：当checkpoint_path是非空 list（即在检查点选择框里选了多个checkpoint目录）时，can_quantize()直接返回interactive=False。与llama.cpp组件、GGUF依赖无关。

该选项的真实语义（已定位，不是GGUF）：

1
2
3
4
5
6
7
8
9

# src/llamafactory/model/model_utils/quantization.py:143
elif model_args.export_quantization_bit is not None:  # gptqmodel
    if model_args.export_quantization_bit not in [8, 4, 3, 2]:
        raise ValueError("AutoGPTQ only accepts 2/3/4/8-bit quantization.")
    check_version("optimum>=1.24.0", mandatory=True)
    check_version("gptqmodel>=2.0.0", mandatory=True)
    ...
    init_kwargs["quantization_config"] = GPTQConfig(bits=..., dataset=...)
    logger.info_rank0(f"Quantizing model to {model_args.export_quantization_bit} bit with GPTQModel.")

结论：

1. 「导出量化等级」= GPTQ位数量化（2/3/4/8 bit），依赖optimum+gptqmodel，产出的是 GPTQ量化的safetensors模型，与GGUF的q4_k_m是两条完全不同的技术路线；
2. 置灰触发条件是多选了checkpoint，不是环境缺组件；
3. GPTQ路线还要求必填校准数据集（__post_init__中export_quantization_dataset is None直接raise ValueError），且GPTQ + LoRA adapter组合被WebUI显式禁止（err_gptq_lora）；
4. LLaMA-Factory README（main）全文无GGUF/llama.cpp/--export_quantization关键词，GGUF导出无官方文档依据。

判定：LLaMA-Factory 无法产出q4_k_m GGUF，不作为量化路径。

6.2 路径B：llama.cpp脚本一步转q4_k_m —— 失败（三次不同报错）

报错 7：脚本不存在

触发命令：

1

python llama.cpp/convert_hf_to_gguf.py models/chenxinyu-qwen2.5-7b-chat --outfile models/chenxinyu-q4_k_m.gguf --outtype q4_k_m

错误原文：

1

python: can't open file '/root/llama.cpp/convert_hf_to_gguf.py': [Errno 2] No such file or directory

排查定位：llama.cpp目录根本不存在——此前只执行了pip install -r llama.cpp/requirements.txt，从未git clone仓库。

解决过程：

1
2
3
4
5

cd ~
git clone https://github.com/ggml-org/llama.cpp.git
# 实测输出：remote: Total 138682 (delta 57), reused 48 (delta 48), pack-reused 138573
#          Receiving objects: 100% (138682/138682), 446.28 MiB | 11.08 MiB/s, done.
cd llama.cpp && pip install -r requirements.txt && cd ~

致命副作用（本次实操最大的坑）：pip install -r requirements.txt会卸载GPU版PyTorch并替换为CPU版，同时降级transformers。详见报错10。

报错 8：脚本文件名混淆

错误原文：

1

python: can't open file '/root/llama.cpp/convert-hf-to-gguf.py': [Errno 2] No such file or directory

排查定位：尝试用横线版文件名convert-hf-to-gguf.py，实际文件是下划线版。中间一度被建议改用横线名，属于误判——ls确认实际文件名后应以ls结果为准。

1

ls ~/llama.cpp/convert*.py    # 以实际输出为准，不要凭记忆写文件名

报错 9：词表写入失败（本次最核心的失败）

触发命令：

1
2

python llama.cpp/convert_hf_to_gguf.py LLaMA-Factory/models/chenxinyu-qwen2.5-7b-chat \
  --outfile models/chenxinyu-f16.gguf --outtype f16

现象：权重转换阶段完全正常，逐层输出：

1
2
3
4
5
6

INFO:hf-to-gguf:token_embd.weight, torch.bfloat16 --> F16, shape = {3584, 152064}
INFO:hf-to-gguf:blk.0.attn_norm.weight, torch.bfloat16 --> F32, shape = {3584}
...
INFO:hf-to-gguf:gguf: context length = 32768
INFO:hf-to-gguf:Set model quantization version
INFO:hf-to-gguf:Set model tokenizer        <-- 在此处崩溃

错误原文（完整因果链，三层异常）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

Traceback (most recent call last):
  File "/root/llama.cpp/conversion/qwen.py", line 63, in set_vocab
    self._set_vocab_sentencepiece()
  File "/root/llama.cpp/conversion/base.py", line 2262, in _set_vocab_sentencepiece
    tokens, scores, toktypes = self._create_vocab_sentencepiece()
  File "/root/llama.cpp/conversion/base.py", line 2279, in _create_vocab_sentencepiece
    raise FileNotFoundError(f"File not found: {tokenizer_path}")
FileNotFoundError: File not found: LLaMA-Factory/models/chenxinyu-qwen2.5-7b-chat/tokenizer.model

During handling of the above exception, another exception occurred:
  ...
  File "/usr/local/miniconda3/envs/py310/lib/python3.10/site-packages/torch/_inductor/runtime/hints.py", line 40, in <module>
    import triton.backends.compiler
ModuleNotFoundError: No module named 'triton.backends'

The above exception was the direct cause of the following exception:
  ...
ModuleNotFoundError: Could not import module 'AutoTokenizer'. Are this object's requirements defined correctly?

排查定位（三层因果）：

1. 第一层：qwen.py:63先尝试SentencePiece路径_set_vocab_sentencepiece()，去找tokenizer.model；Qwen2.5导出目录只有tokenizer.json，故FileNotFoundError。
2. 第二层：代码捕获该异常后 fallback到_set_vocab_gpt2()（qwen.py:65），其内部执行from transformers import AutoTokenizer（base.py:1756）。
3. 第三层：此时transformers 4.57.6加载链generation/utils.py→torch._dynamo→torch._inductor→import triton.backends.compiler失败，抛出No module named 'triton.backends'，最终包装成Could not import module 'AutoTokenizer'。

根因不是「缺AutoTokenizer」，而是torch与triton版本不匹配。

报错 10：环境被 requirements.txt污染

触发命令：pip install -r llama.cpp/requirements.txt（在训练环境py310中）

错误原文：

1
2
3
4
5
6
7
8
9

Uninstalling aiohttp-3.14.5: Successfully uninstalled aiohttp-3.14.5
Attempting uninstall: transformers
Found existing installation: transformers 5.8.0
Uninstalling transformers-5.8.0: Successfully uninstalled transformers-5.8.0
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed.
This behaviour is the source of the following dependency conflicts.
torchvision 0.29.1 requires torch>=2.14.0, but you have torch 2.11.0+cpu which is incompatible.
Successfully installed aiohttp-3.9.5 distro-1.9.0 gguf-0.19.0 huggingface-hub-0.36.2 ...
torch-2.11.0+cpu transformers-4.57.6 ...

排查定位：llama.cpp的转换依赖声明了torch==2.11.0（CPU版）与transformers==4.57.6，pip为满足约束卸载了GPU版torch，装上CPU版。后果：训练/推理GPU不可用，且triton 2.1.0与新torch不匹配，直接触发报错9。

解决过程（恢复 GPU 环境）：

1
2

pip uninstall -y torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

结论（本文最重要的一条）：绝不在训练环境里pip install -r llama.cpp/requirements.txt。 GGUF转换必须在独立venv中进行。

6.3 路径C：独立venv + 官方两步法（唯一可行路径）

依据：llama.cpptools/quantize/README.md原文 —— 「Quantization is done in two phases: Convert the original model to GGUF format. Quantize the converted GGUF file.」

关键事实（源码级核验，convert_hf_to_gguf.pyargparse定义）：

1
2
3

"--outtype", type=str,
choices=["f32", "f16", "bf16", "q8_0", "tq1_0", "tq2_0", "auto"], default="auto",
help="output format - use f32 for float32, f16 for float16, bf16 for bfloat16, q8_0 for Q8_0, tq1_0 or tq2_0 for ternary, and auto for the highest-fidelity 16-bit float type"

--outtype不接受任何K-quant类型（无 q2_k / q3_k / q4_k_m / q5_k_m / q6_k）。K-quant必须交给llama-quantize。

对原流程的修正：原对话中建议的python convert_hf_to_gguf.py ... --outtype q4_k_m会被argparse直接以invalid choice拒绝，不可能产出q4_k_m。该建议错误。

第一步：HF → F16 GGUF（在独立venv中执行）

1
2
3
4
5
6
7
8
9
10
11
12

# 1) 建独立环境——llama.cpp 的 requirements 会装 CPU 版 torch，绝不能进训练 env
python -m venv ~/ggufenv
source ~/ggufenv/bin/activate
pip install -r ~/llama.cpp/requirements.txt
# 官方说明：requirements 默认装 transformers 4；新模型可能需要 transformers 5，可安全升级
pip install -U transformers

# 2) 转换（只转 dtype，不做 K-quant）
python ~/llama.cpp/convert_hf_to_gguf.py \
  ~/LLaMA-Factory/models/chenxinyu-qwen2.5-7b-chat \
  --outfile ~/models/chenxinyu-f16.gguf \
  --outtype f16

可验证结果：日志末行Model successfully exported to ...；此前会输出INFO:hf-to-gguf:gguf: context length = 32768。第6.2节的报错9就发生在Set model tokenizer之后、write()完成之前——即在venv中仍需保证transformers能正常import（见报错10）。

第二步：F16 → Q4_K_M（llama-quantize二进制）

官方命令形态（tools/quantize/README.md原文示例）：

1
2

# 二进制路径为 cmake 编译产物；也可下载 release 预编译包
./build/bin/llama-quantize gemma-4-E2B-it-bf16.gguf gemma-4-E2B-it-Q4_K_M.gguf Q4_K_M

对应到本文路径：

1
2
3
4
5
6

cd ~/llama.cpp
cmake -B build && cmake --build build --config Release -j $(nproc)   # 产出 build/bin/llama-quantize
./build/bin/llama-quantize \
  ~/models/chenxinyu-f16.gguf \
  ~/models/chenxinyu-Q4_K_M.gguf \
  Q4_K_M                                    # 类型名大小写不敏感，官方文档两种写法均出现

常用选项（官方清单）：

1
2
3
4
5

--imatrix imatrix.gguf                       # 重要性矩阵，官方称可降低 ppl/KLD 损失
--leave-output-tensor                        # output.weight 不量化，增大体积换质量
--pure                                       # 禁用 k-quant 混合，全张量同一类型
--output-tensor-type q5_k --token-embedding-type q3_k   # 分张量指定精度
--keep-split                                 # 按输入分片输出，便于大模型

可验证结果：

1
2
3
4

ls -lh ~/models/*.gguf
# 用 gguf 包读元数据，确认架构与量化类型写入正确
python -c "from gguf import GGUFReader; r=GGUFReader('chenxinyu-Q4_K_M.gguf'); \
print(r.fields['general.architecture'], r.fields['general.file_type'])"

体积依据（官方tools/quantize/README.md，Llama-3.1-8B实测表）：

7B Qwen2.5词表152064（大于Llama-3的128256），embedding层更大，Q4_K_M实际体积预计略高于4.58 GiB，约4.7~5.0 GiB。该数字为外推估算，待实测验证。

6.4 路径D：Ollama直接导入 —— 可作为部署手段，但不能产出量化模型

官方依据（ollama/ollama``docs/import.mdx）明确支持两种导入：

1
2
3
4
5
6

# 方式一：Safetensors 目录
FROM /path/to/safetensors/directory
# 方式二：单文件 GGUF
FROM /path/to/file.gguf
# 方式三：分片 GGUF（保留原始分片名，用通配符）
FROM /path/to/model-*.gguf

同一文档中的决定性一句：

"Ollama does not quantize GGUF models during import. Prepare and quantize them first with a GGUF tool such as llama.cpp'sllama-quantize."

结论：Ollama在ollama create阶段不做任何量化。导入safetensors目录只会得到bf16精度的可运行模型，不满足本文「量化模型版本」的目标。

因此路径D的正确定位：验证合并模型推理效果的快速手段，而非量化路径。

1
2
3
4
5
6

# 在含 Modelfile 的目录下（Modelfile 由 LLaMA-Factory 导出时自动生成）
# Changelog 依据：hiyouga/LLaMA-Factory "[25/02/11] We supported saving the Ollama modelfile
# when exporting the model checkpoints."
cd ~/LLaMA-Factory/models/chenxinyu-qwen2.5-7b-chat
ollama create chenxinyu -f Modelfile      # 内部等价于 FROM ./safetensors 目录
ollama run chenxinyu

若要得到量化版 Ollama 模型，必须先在6.3产出GGUF，再改写 Modelfile：

1

FROM /path/to/chenxinyu-Q4_K_M.gguf

7. 量化产物的验证方法

本次的最终状态：第4、5节成功；第6节量化未产出成品GGUF，即目标产物未达成。已完成的验证止于「合并模型可加载推理」。

未通过项（如实记录）：合并模型实际对话时「说话不像本人」。已定位的四类嫌疑（按可能性排序）：

1. 清洗阶段误删口癖/标点习惯等风格指纹；
   2.lora_rank 8对强风格拟合偏保守；
2. 推理temperature 0.7偏低、max_new_tokens 512过长，把语气拉回「助手腔」；
3. 1,729条数据中长对话被cutoff_len 1024切尾。

8. 核验依据清单（8.1已核验 / 8.2待验证）

8.1 已核验（含依据来源）

8.2 待验证

9. 报错总表与关键认知修正

附：本文相对原流程的三处硬修正（均有源码/官方文档依据）

1.--outtype q4_k_m不可行——convert_hf_to_gguf.py的合法值仅f32/f16/bf16/q8_0/tq1_0/tq2_0/auto。
2. LLaMA-Factory的「导出量化等级」不是GGUF——它是GPTQ位数量化，选项只有none/8/4/3/2。
3.ollama create不量化——官方原句："Ollama does not quantize GGUF models during import."

上学期间，每学期都会产生很多docx、pptx、pdf等，或许是结课论文，或许是课堂汇报ppt，或许是要交的材料文件，总爱做一份备份。
既是记录生活，也是存下过去。

由于我有两台电脑，而且手机也是也需要查看，所以云端必不可少。
往往还需要发给别人看，需要发送链接。

国内那些云盘有多难用，我就没必要赘述了。

过去一直用的OneDrive。但只有5GB免费空间，同步又需要走微软服务器，需要常驻后台进程，还会有延迟和强占带宽。

如果两台电脑同时开着同一个docx更麻烦。同步回来多出一个名字带(2)的副本，哪个是新的得自己判断。

最好的记录方式当然是git实在是小题大做。

但是既然可取，何不试试？
私有仓库，564个文件，711.1MiB，12个提交。

拦截大文件

由于GitHub的限制，单文件不可以超过100MB，所以做了一个钩子来避免上传超过100MB的文件。

1

/your/path/cloud-storage/.git/hooks/pre-commit

1
2
3
4
5
6
7
8

MAX_SIZE=$((100 * 1024 * 1024))   # 100MB
git diff --cached --name-only --diff-filter=ACM | while read f; do
  size=$(stat -f%z "$f")
  if [ "$size" -gt "$MAX_SIZE" ]; then
    git restore --staged "$f"     # 移出暂存区，不阻止提交
  fi
done
exit 0

文件组成

那么高清好看的壁纸居然不可以作为动态壁纸播放！太糟糕了！

市面上有很多动态壁纸的软件，但是他们大多软件功能复杂，操作繁琐，价格高昂，语言不便，并且自带下载视频，而不是播放系统壁纸视频。

项目已在GitHub开源，地址：Lumina

9个Swift文件，2995行，Xcode Command Line Tools编译，无需引第三方库。

同步发布软件包，可以直接下载使用。

第一次运行会自动寻找系统自带的Aerial素材，在~/Library/Application Support/com.apple.wallpaper/aerials/videos/下面，缓存的壁纸文件mov路径，也可以自备视频。

软件制作困难

遮挡

视频壁纸并未直接替代原壁纸图片，而是选择新建图层覆盖。

macOS的桌面有多层窗口。用CGWindowListCopyWindowInfodump出来如下：

动态壁纸层需要位于系统壁纸层与桌面图标层之间。最终取值为-2147483610，比图标层低7层。

设置中存在名为“壁纸盖住桌面图标”的开关。

4K视频持续解码，需要在电池供电时暂停。电池状态通过IOKit获取：调用IOPSCopyPowerSourcesInfo获取电源信息列表，读取kIOPSPowerSourceStateKey；若其值等于kIOPSBatteryPowerValue，则判定为电池供电。

全屏模式检测不使用辅助功能。改为遍历窗口列表中layer == 0的窗口，取叠放顺序最靠前的窗口，计算其与屏幕的交集面积；若覆盖面积超过98.5%，则判定为全屏。

遮挡检测同样遍历窗口列表，但选项不同。窗口列表按叠放顺序提供，索引越靠前表示层级越高。因此需要查找位于壁纸窗口之前、layer >= 0且覆盖面积超过98%的窗口。此处不能添加.excludeDesktopElements；添加后会将壁纸窗口本身过滤掉，导致遮挡检测始终返回未被遮挡。全屏检测可以添加该选项，因为该场景本应忽略桌面层。

锁屏和屏幕休眠通过通知处理。在DistributedNotificationCenter上监听com.apple.screenIsLocked和com.apple.screenIsUnlocked，并在NSWorkspace上监听screensDidSleep和screensDidWake；事件到达时立即置位。电池和全屏状态每2秒轮询一次，仅在状态实际翻转时回调。

满足暂停条件时，日志记录一行“暂停播放（全屏应用 / 电池供电）”，并并列列出原因。

每块屏幕对应一个独立的NSWindow，通过遍历NSScreen.screens完成创建。插拔显示器或更改分辨率会发送didChangeScreenParametersNotification，且一次操作会连续发送多次；因此增加0.6秒防抖后再重建。

切换Space或激活其他应用后，偶尔会出现窗口不在当前Space的情况。在didActivateApplicationNotification和activeSpaceDidChangeNotification之后延迟0.35秒再次调用orderFrontRegardless。该数值经实验确定；若延迟更短，系统尚未完成窗口位置调整。

倍速

AVPlayer在2×以上存在硬性上限。使用macOS自带Aerial航拍素材测试（3840x2160、HEVC Main 10、239.76 fps），2.0×可稳定达到120帧/秒；调整至2.2×后降至每秒0至1帧，AVPlayerItem.canPlayFastForward也为false。仅相差0.2×即完全停止。

规避方法是将倍速预置到时间轴。使用AVMutableComposition将整段视频scaleTimeRange压缩至1/倍速 的时长，播放器仅以1×播放。

1
2

let compressed = CMTimeMultiplyByFloat64(asset.duration, multiplier: 1.0 / speed)
track.scaleTimeRange(full, toDuration: compressed)

时间轴压缩后，修改倍速必须重建内容，而重建会导致播放进度归零。修正方法是在重建前记录源视频进度（currentTime × bakedSpeed），重建后seek到position / factor。

另有一个较不显著的问题：将“是否需要预置倍速”表示为布尔值并纳入配置指纹。3×、4×、5×均对应true，配置签名不变，因此不触发重建，始终按首次的3×播放。改为比较实际倍速值后行为正确。

重建还会导致短暂黑屏。replaceCurrentItem会清空图层缓冲。先移除旧层再创建新层，期间必然出现黑屏。使用旧层快照进行遮挡也不可行，因为AVPlayerLayer.contents恒为空，播放器不通过该通道输出。

最终采用双缓冲。保持两个(AVPlayer, AVPlayerLayer)实例，在不可见实例上更换item、执行seek并开始播放，轮询直到isReadyForDisplay为真且时间轴推进（最多等待1秒），然后交换可见性；此时才暂停旧实例并调用replaceCurrentItem(with: nil)释放解码器。轮播切换复用同一路径，手动“下一幅”同样不会出现黑屏。

另有一处与倍速相关的问题：AVPlayer.play()等价于rate = 1.0，因此先设置rate再调用play()会覆盖速度。表现为初始速度正确，但暂停后恢复时速度变为1×。所有起播路径统一改为playImmediately(atRate:)。

高倍速下卡顿是另一类问题。4×下出现周期性卡顿。最初认为由解码能力不足导致，但实测时间推进准确，CPU占用仅2.3%。实际原因是帧生成速率与上屏速率不匹配：30 fps素材在4×下需要120帧/秒，而AppKit窗口默认不以ProMotion的120 Hz满速运行，需要显式申请。macOS不提供CALayer.preferredFrameRateRange，该API属于iOS；只能使用NSView.displayLink。声明后可通过回调频率验证，日志可输出display link实测120.5 Hz。

5×属于物理限制。30 fps素材在5×下需要150帧/秒，120 Hz屏幕最多显示120帧/秒，必然丢帧。设置界面按“屏幕刷新率 ÷ 源帧率”计算该素材的最高无损倍速，超过该值时以橙色标记，无需逐档测试。

开机自启

开机自启配置写入~/Library/LaunchAgents/com.chenxinyu.lumina.plist。其中ProgramArguments包含--autostart，设置RunAtLoad，并将LimitLoadToSessionType设为Aqua。执行bootstrap前先执行一次bootout；否则重复切换自启开关时会返回service already loaded。

应用采用ad-hoc签名（codesign --sign -），不包含开发者证书。用户下载并解压后，Gatekeeper会拦截。处理方式有两种：在“系统设置 → 隐私与安全性”中选择“仍要打开”；或执行xattr -dr com.apple.quarantine /Applications/Lumina.app。该操作应在构建脚本中一并执行。

此外，将.app组装在mktemp创建的临时目录中，项目内仅保留zip文件。macOS 26的App库依据LaunchServices注册表收录bundle；只要项目目录中曾出现.app，就会与/Applications中的副本共同注册，导致显示两个图标。

「一份 RLE 指北」

Real Life Experience实际生活体验。

欢迎大家来到 RLE.wiki. 这是一份给跨性别者与性别多元群体的 RLE 指南。更多帮助正在路上，敬请期待……

笔者从X得知的这个项目。在翻它的校园栏目的时候。有着一百七十多个学校，大部分城市都能翻出几条。但是没有我的大学。

怎么可以没有大农专！我写！

写了docs/campus/NJAU.md，162行。开头一张总览表，规则是情况正面用✓、负面用✗、不确定用?、视情况而定用-。

PR挂上去没多久，Twinsherry在下面留了句话，说LS-KR之前已经从这里撤过一次南京农业大学的条目，作为数据遗产资料的继承人，她希望把旧版本里LGBT相关的部分补进来。

我当天问了旧内容能在哪个commit或者归档仓库里查到，她给了个链接，PR 586，标题「doc: rm NJAU」，2025年5月合并的，改一个文件，纯删85行。

我一开始就是知道的，那是学姐。只是她后来想不开了，走之前rm了南农相关的文章。git历史我也是看到了的

旧版本能找到的东西就是那段差分里剩下的全部。

其中的LGBT内容和校内医疗相关的说法挑出来，一部分并进正文，部分核实不了的用::: details 旧版资料折叠起来挂在对应小节下面，标注了是上一版投稿人的描述。

::: details旧版资料：上一版投稿人对宿舍搜查的描述（笔者没遇到过，认为是特殊情况，予以保留）

辅导员或学院或学校会定期秘密地搜查学生的宿舍，频率为一个学期至少两次。同班所有人的物品均有被翻动的痕迹。
笔者从医院回到宿舍时发现自己的电脑已经是只剩一次机会否则全盘加密锁定的状态。
没有藏好的糖（还需要吃的那些）也被收走。
带锁是必须的，不要用密码锁。

:::

我没法验证。校医院能不能测六项、益丰大药房有没有可能出现二十多块一盒的补子。

第二个提交f33b805改了59行删了24行，把那张总览表重新排版对齐，另外补了几处我当时想起来的细节：军训16天、后半程有晚训、每天三个时段分性别训等等。

审稿尺度

投稿指南里定的尺子很具体。

1. 不得修改模板中的二级标题，如果认为不需要填写该项目，请注释掉。markdown的注释语法为<!-- -->，例如<!-- ## 其他信息 -->。
2. 如有必要，可以自由添加多级标题。
3. 为了观察方便，英文与汉字之间需要添加空格，例如例子 example 例子。
4. 专有名词缩写注意大小写，例如MtF，具体可以参考https://mtf.wiki/zh-cn/docs/useful-info/abbreviation/。
5. 主观内容请使用引用格式，例如> 引用内容。
6. 句末需要加上中文句号。。
7. 如果有引用到静态文件，例如图片视频等，请在docs/assets目录下上传图片（以文档名开头），并在markdown文件中使用相对路径的方式引用。例如我的文档名为example.md，在其中引用一张名为Test.png的图片，那么我需要将Test.png改名为example_Test.png，上传在docs/assets目录下，然后在markdown里面使用![](/assets/example_Test.png)的方式引用。
8. 对于过时内容的处理：
   • 影响力持续至今的事情，尽管其已经结束，但为了因果关系完整，仍应予以保留。（举例：2020年，某校因为COVID-19疫情防控措施而取消了某政策，至今没有恢复，但由于2022年12月的防控措施变化，而在近期存在恢复可能的，在等待两年（至2024年12月）、排除其恢复可能后，将“以前的政策”和“受COVID-19疫情防控措施影响”这两句按下方处理）
   • 已无影响力，但影响力消失不足两年的，予以折叠、标注过时（使用:::details :::语法）。
   • 已无影响力，影响力消失满两年的，予以删除。

部署

PR一开就有bot来贴预览地址，，每个PR独占一个Cloudflare Pages部署，改完刷新就能看到修改完的界面是什么样。

好高级！我都不知道GitHub居然还能这样

想练SQL一直卡在环境上。在线基本只有长文教程，本地装个数据库又麻烦，适配性不强。不如自己写一个：纯静态页面，双击HTML就能用，离线使用。

现在有50关，从SELECT一路排到递归CTE。每题写真正的SQL，由SQLite执行后比对结果集，对了才放行。

仓库在u2tt/sql-quest，在线版https://u2tt.github.io/sql-quest/。

底子

sql.js把SQLite编译成了WebAssembly，查询全在浏览器本地跑，数据不出机器。

麻烦在分发。常规做法是一个index.html加一堆js再加个640KB的.wasm，还得起HTTP服务——file://下fetch拿不到本地文件。我把wasm转成base64塞进js，npm run build出一个1.2MB的sql-quest.html，依赖全在里面。base64会让体积涨三分之一，换来的是不用起服务，值。

题库

基础篇是书店业务：作者、书籍、客户、订单、订单明细五张表，25本书、30笔订单。数据里埋了几个坑。有个客户从没下过单，练LEFT JOIN的时候正好拿来分辨COUNT(o.id)和COUNT(*)——后者会把没订单的那行数成1。有本书的genre是NULL，IS NULL和相关子查询里的IS（不是=）都得用它。订单有已完成、已取消、待付款三种状态，聚合之前不先过滤就算错。

进阶篇换成校园选课，也是五张表，但courses.prereq_id指向同一张表的id，自连接和递归CTE有真实的层级能展开。另外特意留了5个一节课都没选的学生，不然NOT EXISTS这类题没有正确答案。

进阶关不难在语法，难在组合。表一多，得自己想清楚从哪张出发、怎么连过去；而且多半要拆两步，先算中间结果再基于它算答案。

判题

答案写法定不下来，没法做文本比对。每关存一份参考SQL，运行时现场算出期望结果，再和你的结果比。四种比法：columns是列名加无序行集合，ordered要求行顺序也对，set只看行集合，scalar比单个数值带浮点容差。

不通过时给差异清单。测COUNT(*)那个坑的时候，面板直接列出「冯磊0」和「冯磊1」两行，比说一句答案错误有用得多。

另外加了关键字约束。题目要求用LEFT JOIN，你写死WHERE name = '冯磊'凑答案会被拦下。结果对了，但这题就白做了。

编辑器

一开始就是个textarea。后来想加高亮和补全，发现两个都不好办。

高亮最后做成了「文字透明的textarea叠在一层<pre>上面」。选区、光标、输入法都还是textarea的原生行为，看到的高亮来自底下那层。两层必须像素对齐，否则文字会重影，所以排版规则只写一处、两层共用，另外textarea用scrollbar-gutter: stable常驻预留滚动条槽位，高亮层补上同样的右内边距，两层的内容盒才等宽。测试里卡的是内容盒宽度、scrollHeight和13项排版属性全等。

补全要贴着光标弹，得先知道光标在textarea里的像素坐标。用了个镜像div：复刻textarea的计算样式，把光标之前的文本灌进去，再插一个span量它的位置。好处是字号改了自动跟随，不用改代码。

排序按光标位置分。语句开头给关键字（sel → SELECT），FROM或JOIN后面给表名（bo → books），查询中段给列名（st → stock），打了b.就只给books的列。别名也认：写了COUNT(*) AS book_count，后面打book_co能补出来；WITH city_stat AS (...)之后能补CTE名；派生表后面打b.ti，能从内层SELECT推出title。

格式化用sql-formatter。全量包312KB，带20多种方言，这项目只用SQLite，就写了个esbuild插件把方言注册表换成只含sqlite的版本，压到57KB。

几个坑

WASM实例那块最要命。切关卡要恢复到该关的初始状态，我最初的写法是这样：

1
2
3

const old = this.db;
this.db = new this.SQL.Database(snapshot);
old.close();

this.db平时就是数据集注册表里的常驻实例，把旧的关掉，那套数据就永久废了——之后任何查询都抛ErrnoError: FS error，而且不可恢复。这个bug只在反复跨数据集切换时才触发，只做一套库的话永远碰不到。改成原地替换注册表引用就好了：新实例顶上，注册表指向新的，再关旧的。

CSS表格一次踩了仨。

max-width对table cell不生效。我给td设了max-width: 320px想截断长文本，实测宽度360px。CSS 2.1里这个属性对表格单元格就是没用，最后把截断压在内层元素上。

数值列右对齐好看，但表头默认左对齐，两者能差50px以上。得先按列判断是不是数值列（该列所有非空值都是数字），给th和td加同一个class才对齐。这个问题之前一直没被测出来，因为我的几何断言只比了单元格盒子的坐标——盒子当然对得齐，但文字能差一大截。后来改用Range量文字的实际位置，按对齐方式比对应边缘。

还有width: 100%会把多余空间按比例摊给每一列。id列内容只要40px，被撑到90px，看着间距很怪。改成让最后一个文本列吸收剩余宽度——文本列变宽只有好处，数值列变宽只会让数字贴着右边、中间空一大截。

还有个正则在补全里作祟。在FROM orders o JOIN o后面打下去，候选里给的是order_date（一个列名）、ON、OR、ORDER BY，偏偏没有orders。

原因是我用一条正则从第一个FROM开始匹配：

1
2

FROM orders o JOIN o
└──── 整段被吞掉 ────┘

JOIN落在被吞掉的部分里，被当成「这个子句里已经有别的关键字了」，于是判定失败、退化成列名上下文。改成取最后一个引导词再往后看就行。顺带把表名位置的候选也收干净了——那儿本来就只有表名合法，现在JOIN order_d干脆什么都不给，而不是递上一个order_date误导人。

测试

这类工具有个麻烦：错了不一定看得出来。所以写了一套脚本，改完必跑。verify检查50关的参考答案能不能过自己的校验、起始代码会不会被误判成通关；e2e是浏览器端到端的46项；editor管格式化、补全、高亮那56项；fullplay把50关在浏览器里逐个打通；offline验单文件版在file://加断网下能不能跑。

最后一个是这次新加的：live，部署完实测线上站点能不能真答题。之前只看HTTP 200就以为发布成功了，其实接口通了不代表页面能跑。

仓库

代码、题库、两套示例库都在u2tt/sql-quest。不构建也能用，dist/sql-quest.html下载下来双击就开，放U盘或者发给别人都行。两套库也单独导出了dist/bookstore.sql和dist/campus.sql，可以拖进DBeaver自己练。MIT协议。

主题做了深浅两套，浅色不是简单反色，强调色压暗到#9a6200，六类语法色在白底上的对比度都在4.8:1以上。

拿它做点能跑起来的东西，配了一块1.8寸屏：屏幕、电池、主控、充电板。

项目开在u2tt/rp2040-txt-reader，接线表在hardware/PINOUT.md，带图的分步制作指南在docs/BUILD_GUIDE.zh-CN.md。

选型

对于板子的选择：

选RP2040最为方便：插上线就是U盘，驱动装一次就识别、不用开热点、不用编译器。

物料清单

自己焊接的话，主控要买未焊接排针的散件版，屏幕需要焊接好的，不能是裸板。

结构

屏幕（最底层，屏面朝外）→ 缓冲层 + 电池（中层）→YD-RP2040 + TP4056（顶层）

主控53.3 × 22.9 mm能放在约56 × 34 mm的屏幕背后，电池夹在中间。

缓冲层

屏幕背面有LDO、贴片阻容，有的批次还带SD卡座，凸起1–2mm。软包锂电池皮很薄，不能直接压上去。需要垫一些软的中层。

焊接

先拆掉排针

如果收到板子后者屏幕是已经焊好排针的版本，需要先拆下排针：

1. 用斜口钳或尖嘴钳夹碎排针底部的黑色塑料座，让金属针彼此独立。
2. 一手镊子夹住一根针，一手用电烙铁加热背面的焊点；锡化啦就轻轻往外抽。
3. 吸锡器吸净孔内残锡，或者用牙签趁热捅穿——孔必须通透，后面要穿线。

屏幕接线

剪8根约5cm的30AWG硅胶线，分别穿过屏幕底板那8个孔（VCC、GND、SCL、SDA、RES、DC、CS、BLK）焊死。

电源链路

电池红线焊TP4056的B+，黑线焊B−。这两根正负极不能接反或短接。

接着OUT+出来先过拨动开关再过主控Vin，OUT−接主控GND。

飞线对接

把屏幕上焊接的8根线从电池侧边翻上来，一根一根焊到主控对应引脚上。每焊一根都先比划长度：剪掉多余的、重新剥皮再焊，保证线贴着电池边缘走、不拱起来。

全部接完就是文章开头那张图的样子。

按键

两个按键各自的一个引脚并联起来接GND，另一个引脚分别接GP16 / GP17。主控内部上拉，按下即拉低触发，不占地方也不用额外元件。

接线表

屏幕（1.8寸ST7735，走硬件SPI1）

板上通常只引出一个3V3孔，接两根线不方便。做法是在屏幕端把VCC和BLK短接，并联后共用一根飞线接到3V3，最整洁。

电源链路（电池 → 充电板 → 开关 → 主控）

翻页按键

通电前检查

拨开关之前确认这几处：

• 剪断的金属废线头全部清理干净，没有掉进任何板子缝隙里。
• 从底板翻上来的导线外皮完好，没有被板边锋利焊盘割破露铜。
• 电池与任何金属针脚、焊点之间都有绝缘（双面胶或硬塑料片），没有被刺穿的可能。
• 有条件就上万用表蜂鸣档：该通的关键引脚确实通，相邻引脚没有意外短路。

上电

接线正确、固件也烧好之后拨开关，屏幕会亮起来打印启动信息——这台跑的是CircuitPython 10.3.0，画面里的提示文字是固件自带的拼音化中文。

屏幕上出现字，说明SPI那五根线、复位、片选和供电正确。

屏幕是彩屏，能显示标准24位BMP图片，仓库里examples/image_viewer.py可做测试。

放文件：插上线就是U盘

1. Type-C线插设备连电脑，会弹出一块名叫CIRCUITPY的U盘。
2. 把UTF-8编码的book.txt拖进盘根目录，拔线。
3. 拨开关开机，按「下一页」从第一页开始读。

充电时线要插在TP4056的Type-C口，插主控口是直接给主控供电，不走充电板。

固件

板子跑的是CircuitPython（仓库：adafruit/circuitpython）。屏幕驱动、中文字体、翻页逻辑一共216行，另外依赖三个库，都在Adafruit的仓库里：

• Adafruit_CircuitPython_ST7735R — 屏幕底层驱动
• Adafruit_CircuitPython_Display_Text — 文本排版
• Adafruit_CircuitPython_Bitmap_Font — 加载点阵字体
• 想一次拿齐，用官方合集Adafruit_CircuitPython_Bundle

中文用的是BDF点阵字体，文泉驿点阵宋体有现成的中文字形可以转。

注意：

• CircuitPython 9.x起FourWire从displayio拆成了独立的fourwire模块，照8.x教程写会报AttributeError，表现是背光亮但屏幕全黑——很容易误判成焊接问题。
• 这块屏的色序是BGR，建display时要显式bgr=True，不设颜色会反。

仓库

完整制作指南（选型 → 烧录 → 组装 → 排障）在docs/BUILD_GUIDE.zh-CN.md，接线表在hardware/PINOUT.md，代码与示例在仓库根目录。MIT协议，欢迎照抄。

第一版：Hugo

Hugo用Go编写，安装是一个二进制文件，放进PATH即可使用，不需要Node环境。全站一个配置文件，文章按目录组织，主题放在themes目录（直接放或用git submodule管理）。front-matter支持TOML、YAML、JSON三种格式。当时用的版本是0.165.0。本地预览是hugo server，生成是hugo，输出在public目录。

1
2
3
4
5
6

content/
  posts/
    2026-09-08-hello-world.md
themes/
  PaperMod/
config.yml

主题是PaperMod，自带排版、深色模式、目录（TOC）、代码高亮和搜索。星空背景、鼠标点击特效、访问统计不在主题里，需要自己写CSS和JS挂在主题外面。这几个效果要维护的代码量接近主题本身。所以换掉了。

第二版：Astro

Astro属于Node生态，用npm装依赖，配置文件是astro.config.mjs，构建输出到dist目录。

1
2
3
4
5
6
7
8

src/
  content/
    blog/
      hello.md
  layouts/
    BlogPost.astro
astro.config.mjs
package.json

内容集合是它的一个机制：文章的front-matter字段在TypeScript文件里定义，不符合schema的字段会在构建时报错。输出默认不含前端框架的JavaScript，需要交互的组件单独声明。本地预览是npm run dev。

日常使用上，改配置后要重新执行npm install和npm run build，node_modules目录装下来几百兆。所以换到了Hexo。

第三版：Hexo

Hexo属于Node生态，当前版本8.1.2，主题是开源的安知鱼（anzhiyu），版本1.7.0。

1
2
3
4
5
6
7

source/
  _posts/
    2026-09-08-hello-world.md
themes/
  anzhiyu/
_config.yml              # 站点配置
_config.anzhiyu.yml      # 主题配置（站点级覆盖）

配置两层：站点_config.yml管生成与目录参数，_config.anzhiyu.yml管外观和功能开关。新建文章用hexo new，本地预览用hexo server，生成用hexo generate，输出在public目录。主题自带星空背景、鼠标点击特效、首页打字机、本地搜索、字数统计、访客统计、深色模式、繁简转换、版权声明、音乐页、分类标签归档页、图片灯箱、相对时间，都在主题配置里开关，不用自己写代码。其中本地搜索由生成search.xml、前端检索实现，不依赖外部服务。

默认字体是霞鹜文楷，文章支持封面图、置顶、分类和标签。背景粒子和首页头图自写脚本放置。定制放在_config.anzhiyu.yml里，主题更新不受影响。

三个引擎的产物都是纯静态文件，HTML加CSS加JS，不需要服务端。

120台为早期CPU节点，双路32核Xeon 8358P，单机64核 / 500G内存，承载日常主要算力。数台胖节点为四路24核Xeon 8360H，单机96核 / 2T内存，供大内存作业使用。最新批次为GPU节点，单机96核 / 1T内存、8张H20，另有一台配2块4090。另有2台国产K100异构节点，自五月末起持续offline。

平台另有二十余台GPU机器未纳入SLURM节点列表；登录、管理、监控类机器同样不计入调度器口径，sinfo不显示。

主要用户方向为生物信息与计算化学，module avail提供87个模块，blast、bwa、vasp、gromacs占多数。

登录节点仅承担登录与作业提交，计算须下发至计算节点。调度系统版本SLURM 23.11.10，以下数据均在登录节点实测采集。

节点详情

1
2
3
4

sinfo -s                             # 分区概览：节点数、状态分布
sinfo -N -o "%N %P %c %m %G %t"      # 逐节点：核数、内存、加速卡、状态
squeue -o "%.8i %.8P %.18j %.8t %.10M %R"    # 自己的作业
sacct -u $USER --starttime=now-2hours        # 自己的历史作业与资源用量

sinfo -s输出：

1
2
3
4
5
6
7
8
9
10
11

PARTITION AVAIL  TIMELIMIT   NODES(A/I/O/T) NODELIST
cpu96        up   infinite          1/4/0/5   fat[01-05]
cpu64*       up   infinite        25/95/0/120 node[01-120]
test96       up   infinite          0/2/0/2   node[121-122]
soy-com      up   infinite          0/22/0/22   sri-com-[01-22]
sri-com      up   infinite      13/1/0/14     sri-com-[23-36]
sri-mem      up   infinite          0/2/0/2   sri-mem-[01-02]
sri-ghz      up   infinite          0/2/0/2   sri-ghz-[01-02]
sri-gpu      up   infinite          0/1/0/1   sri-gpu-01
sri-gnm      up   infinite          0/1/0/1   sri-gnm-01
dcu          up   infinite          0/0/2/2   dk-gpu[01-02]

带星号的cpu64为默认分区，不指定-p时作业落入此分区。中间四列为allocated / idle / other / total。

分区

十个分区合计171台、12352核。cpu64中118台为500G内存，其余两台384G。

sri-*一组绑定专属QoS，普通账号提交返回Invalid qos specification，CPU型号无法读取；dcu两台offline，同样无法读取。

cpu64的120台为主力：空闲95台时可直接提交；25台在跑时backfill仍可插入空闲窗口。调度器记录内存500G，节点内free -g实测503G。

DCU两台装国产K100，sinfo中为down*，scontrol show node给出的原因为Not responding，自五月底持续至今。另两台带加速卡的节点——sri-gpu的H20与sri-gnm的4090——位于上述受限QoS组内。

系统代际存在差异：早期CPU节点为CentOS 8.2 / 内核4.18，后加的GPU与内存节点为RHEL 9.5 / 内核5.14。/hpc/software下gcc覆盖4.8.5至14.1.0，glibc保留2.29与2.36两套，对应两代系统各留一版。自行编译的二进制跨分区搬运存在兼容风险。

作业提交

交互式调试用srun：

1

srun -p cpu64 -N1 -n1 --time=00:30:00 --pty bash

实测分配到node08，grep -m1 'model name' /proc/cpuinfo为Xeon Platinum 8358P。进入后nproc返回1而非64——srun该步仅分配1个CPU，确认整机规格需读/proc/cpuinfo或使用lscpu。

正式任务写脚本交sbatch：

1
2
3
4
5
6
7
8
9
10
11

#!/bin/bash
#SBATCH -J quant-backtest
#SBATCH -p cpu96
#SBATCH --cpus-per-task=32
#SBATCH --mem=256G
#SBATCH --time=08:00:00
#SBATCH -o /hpc/home/%u/logs/%j.out
#SBATCH -e /hpc/home/%u/logs/%j.err

cd ~/quant
python backtest.py

申请加速卡加一行#SBATCH --gres=gpu:1，具体型号见分区Gres字段。

集群SelectTypeParameters为CR_CORE，调度按核数分配，内存不参与资源分配——作业不写--mem亦可运行，节点AllocMem恒为0。以两个1核作业验证，运行期间所在节点AllocMem均为0。同节点多作业之间互不可见实际内存占用，先占满内存的作业会影响其余作业，故提交时须显式指定--mem。sacct中ReqMem显示500000M，为未填该字段时按节点总内存回填的显示值，不代表实际申请整机。

数组作业上限MaxArraySize为1001，单次最多提交1001个子任务，更大规模需分批提交。

调度器按什么排

PriorityType = priority/multifactor，SchedulerType = sched/backfill。前者按作业年龄、份额、队列权重计算优先级，后者负责插空——作业若能在一个空闲窗口内跑完，即可提前启动。

该组合利于短作业，反向亦然：为一个5分钟的任务写--time=72:00:00，backfill找不到足够长的窗口，作业只能排队。

所有分区时间上限均为infinite，MaxTime无系统级限制，时限交由使用者自行声明，长时作业可长期占用节点。

squeue -a在普通账号下不显示其他用户作业：实测squeue -a -h | wc -l返回0，同一时刻sinfo显示25个节点处于alloc状态。判断集群负载只能依据sinfo的节点状态分布。

存储：23P与5000亿inode

df -hT中容量最大的一行：

1
2

Filesystem      Type      Size  Used Avail Use% Mounted on
/hpc             dpc        23P  1.1P   22P   5% /hpc

23PB并行文件系统，已用1.1PB。文件系统类型为dpc，属分布式存储客户端挂载，与本地盘行为不同——小文件随机读性能与顺序读写相差量级，登录节点禁用du / find即源于此。

inode容量见df -i /hpc：总量5000亿，已用2.33亿。元数据按目录树铺开、查询需走网络，是该量级的成因。

另两个挂载点：

• /usr/local/globle/softs为NFS，191G、59%已用，存放slurm二进制与公共软件，所有节点共享同一份。
• /dev/shm为252G内存盘。数据管道中间结果置于此处，读写不落盘；重启即清空。

家目录位于/hpc/home/<用户名>。以本账号为例，占用接近48TB，主要为从ModelScope拉取的49个模型，其余为量化日线数据。

环境与启动速度

公共软件通过module加载，module avail挂载87个：生信类（blast、bwa、hmmer、canu、megahit、gtdbtk、metawrap）、计算化学类（vasp、gromacs、amber、autodock）、gcc/4.8.5至gcc/14.1.0、openmpi 3.1至5.0.5、cuda/11.7与12.4、Python 3.7/3.8、R三个版本、singularity两个版本。使用前module load gcc/14.1.0 openmpi/5.0.5即可，优于在home内自行编译。

Python环境采用miniconda，按用途拆为四个：myenv放通用工具，quant放baostock相关依赖，agent与agent-gpu分开的原因是GPU侧依赖锁定在另一cuda版本。

zsh启动时间做过专项优化。原始耗时约15秒，成因是oh-my-zsh及插件每次登录重新source，而home挂在分布式存储上，网络文件系统随机读延迟高。处理办法是把omz与历史文件缓存到/dev/shm，并将"重新加载配置"改写为跳过omz重复加载的函数。优化后约0.8秒，多终端窗口并发打开时差异明显。

长任务用tmux托管

登录节点直接运行长任务，网络断开即进程终止，改用tmux托管：

1
2
3

tmux new -s pull        # 建会话
# Ctrl-b d 脱离
tmux attach -t pull     # 重新接上

集群tmux版本为2.7。小时级以上的任务交sbatch；tmux用于托管数据拉取循环与监控进程。