MiniMind 的软件工程视图：把 LLM 当"版本化组件"来管

定位声明：本文所有关于 MiniMind 的具体版本号、许可证条款、参数量与性能数字，一律以官方仓库与读者实测为准；文中出现的示例数字均标注"示意"。我们不评价"哪个模型最强"，只回答一个工程问题：当你手里有一个 LLM 组件时，你怎么像管软件依赖一样管它？

阅读路径：§1 为什么选它（选型逻辑），§2–§3 仓库分解与版本流水线（组件视角），§4–§5 配置管理与接口契约（管理视角），§6–§8 版本清单与换版影响（交付物视角），§9 失败模式，§10 与 pr13/pr15 的接口约定。

1. 为什么选 MiniMind

案例库需要一个"麻雀五脏俱全、但一天能看懂"的 LLM。用四个工程判据筛一遍：

• 完整性：3B 级（更小版本可缩到几百 M，以仓库为准）完整链路——pretrain、SFT、LoRA、DPO、Toolcall 全有独立训练脚本，覆盖模型构造的各环节。
• 可及性：单卡消费级 GPU（4060Ti / 3090 级别）可跑通全链路，实验室与宿舍都能复现。
• 可读性：核心代码约千行级（以仓库实际为准），读者 3 天能通读——Llama / Qwen 官方仓库做不到，它们的抽象层级是为生产服务的。
• 可管理性：权重与训练代码开放，能算哈希、diff 配置、换 checkpoint。闭源 API 正相反：版本由供应商说了算，"回滚"这个动作根本不存在。

许可证方面，MiniMind 采用宽松开源许可（Apache / MIT 类，务必以仓库 LICENSE 文件实际内容为准），教育与二次分发约束少，适合进实践清单。

工程提示：选型判据本身就是实践要点——"完整性 / 可及性 / 可读性 / 可管理性"四条，换成选任何第三方 AI 组件（embedding 模型、OCR 服务、翻译 API）都成立。让读者用这四条去评一个自己项目里真实用过的组件。

2. 仓库结构 = 工程件分解

把 MiniMind 仓库摊开，它不是一坨"模型代码"，而是一份标准的工程件分解：每个文件恰好扮演一个工程角色。

MiniMind/
├── model/
│   └── model_config.py      # 【组件规格书】结构超参的唯一真相源
├── train_full.py            # 【构建脚本 1】pretrain：从语料造基座
├── train_sft.py             # 【构建脚本 2】SFT：指令对齐
├── train_lora.py            # 【构建脚本 3】LoRA：低成本补丁式变体
├── train_dpo.py             # 【构建脚本 4】DPO：偏好对齐
├── train_toolcall.py        # 【构建脚本 5】Toolcall：工具调用能力注入
├── evaluate.py              # 【验收测试】基准评测 = 组件质量门禁
├── chat.py                  # 【冒烟测试】交互式对话 = 人工验收入口
├── openai_api.py            # 【对外接口】OpenAI 兼容服务 = 组件 API 门面
├── requirements.txt         # 【依赖清单】环境锁定
└── out/                     # 【构建产物】各阶段 checkpoint 目录（版本工件）

注意读法：train_*.py 不是"五种算法"，而是五道构建工序；evaluate / chat / openai_api 不是"三个入口"，而是验收测试、人工冒烟、对外契约三层设施。这个读法一旦建立，读者看任何开源模型仓库都会自动做同样的分解：结构定义在哪？工序几道？产物怎么命名？接口承诺是什么？

工程提示：动手练习——让读者给仓库里每个文件写一行"工程角色卡"（规格书 / 构建脚本 / 版本工件 / 质量门禁 / 接口门面），不许出现任何 ML 术语。写不出来 = 还没读懂这个仓库的工程结构。

3. 分阶段 checkpoint = 版本流水线

MiniMind 每跑完一道工序，就在 out/ 下沉淀一个权重目录：out/pretrain、out/fine-web（SFT 产物，命名以仓库为准）、out/lora、out/dpo、out/tool。这正是软件构建流水线里 dist/ 目录的翻版——每个阶段产物都是一个版本工件，前一个工件是后一个工件的输入依赖。

传统软件里，构建产物靠 Git tag + CI artifact 管理；LLM 的权重文件动辄 GB 级，进不了 Git，于是"版本指纹表"就是权重世界的 lockfile。下面这段脚本读三个 checkpoint 目录，生成机器可读的指纹 CSV——它就是你版本清单（§6）的数据源：

"""fingerprint.py — 扫 out/ 下各阶段 checkpoint，产出版本指纹表 CSV。"""
import hashlib, json, os, csv, subprocess
from pathlib import Path

STAGES = ["pretrain", "fine-web", "lora", "dpo", "tool"]  # 目录名以仓库实际为准
ROOT = Path(os.getenv("MINIMIND_OUT", "out"))

def sha256_of(path: Path, limit_mb: int = 0) -> str:
    """大权重取前 limit_mb MB 做'轻指纹'（练习用）；正式清单建议整文件哈希。"""
    h = hashlib.sha256
    with open(path, "rb") as f:
        h.update(f.read(1024 * 1024 * (limit_mb or 10**6)))
    return h.hexdigest[:16]

def n_params(ckpt_dir: Path) -> str:
    bins = sorted(ckpt_dir.glob("*.pth")) + sorted(ckpt_dir.glob("*.safetensors"))
    if not bins:
        return "MISSING"
    try:
        import torch
        sd = torch.load(bins[0], map_location="cpu")
        sd = sd.get("model", sd) if isinstance(sd, dict) else sd
        total = sum(v.numel for v in sd.values if hasattr(v, "numel"))
        return f"{total/1e6:.1f}M"
    except Exception as e:                        # 结构不同也不崩，记录原因
        return f"UNREADABLE({type(e).__name__})"

def upstream_commit -> str:
    try:
        return subprocess.check_output(
            ["git", "rev-parse", "--short", "HEAD"], text=True).strip
    except Exception:
        return "UNKNOWN"                          # 诚实记录"取不到"，不要编

def data_tag(ckpt_dir: Path) -> str:
    """约定：训练脚本把语料标识写进 ckpt 同级 meta.json；没有就标 UNKNOWN。"""
    meta = ckpt_dir / "meta.json"
    return json.loads(meta.read_text(encoding="utf-8")).get("data", "UNKNOWN") \
        if meta.exists else "UNKNOWN"

rows = []
for stage in STAGES:
    d = ROOT / stage
    if not d.is_dir:
        continue
    bins = list(d.glob("*.pth")) + list(d.glob("*.safetensors"))
    rows.append({"stage": stage, "artifact": str(d),
        "weight_hash": sha256_of(bins[0]) if bins else "MISSING",
        "params": n_params(d), "data_version": data_tag(d),
        "src_commit": upstream_commit,
        "built_at": __import__("datetime").datetime.now.isoformat(timespec="seconds")})

with open("fingerprints.csv", "w", newline="", encoding="utf-8") as f:
    wtr = csv.DictWriter(f, fieldnames=list(rows[0].keys))
    wtr.writeheader; wtr.writerows(rows)
print(f"fingerprints.csv 写出 {len(rows)} 行 —— 进 CI 前先人工核对 MISSING/UNKNOWN")

工程提示：这段代码故意保留 MISSING / UNREADABLE / UNKNOWN 三种"丑"状态——真实清单里最危险的不是缺数据，而是有人为了让表格好看去编数据。CI 门禁可以容忍 UNKNOWN，但不能容忍"看起来对但没人核实过"的值。

4. 配置管理：model_config.py 的启示

MiniMind 把所有结构超参——hidden_dim / layers / head / dropout / rope_theta / vocab_size 等——集中在一个 model_config.py 里，训练与推理共享同一份定义。这是很多"玄学调参"团队最先丢掉的一条纪律，也是配置管理里最便宜的正面教材：

• 参数外置：结构决策从散落的魔法数字变成一处声明，天然可 diff。
• 可 A/B：同一份训练代码 + 两份 config = 两个组件候选版本，实验变量被约束在配置层。
• 改一个字段 = 换一个组件版本：layers 从 8 改到 16，权重与旧 checkpoint 就不再二进制兼容——这不是"调个参数"，这是一次组件变更，要走版本号。

表内数值为示意，展示的是"变更类型分类法"，不是 MiniMind 任何真实版本的字段值。

工程提示：让读者给 config 的每个字段标注"兼容等级"（不变 / 仅训练期 / 行为变更 / 二进制不兼容），并规定：出现任何"不兼容"级字段变化，工件的语义版本号主号必须进位。配置 diff 是免费的变更日志，不利用是浪费。

5. evaluate 与 chat 是"组件对外接口"

软件组件之所以可插拔，靠的不是"代码写得好"，而是契约稳定。MiniMind 的三层接口设施对应三种契约：

• chat.py —— 人机冒烟契约：同一 prompt 进去，输出风格是否还像"那个模型"；
• evaluate.py —— 质量门禁契约：基准数据集 + 打分函数固定，换版必须过同一把尺子；
• openai_api.py —— 机器间契约：OpenAI 兼容 HTTP 服务，/v1/chat/completions 的请求/响应结构就是接口签名。

第三条最有实战味：只要契约不破，上游调用方根本不知道也不关心背后是 MiniMind、Qwen 还是别的什么。pr03 里的 Hermes 指过来，它就是一枚普通的"模型依赖"。下面是把这两个案例拼起来的完整操作：

# ── 终端 1：把 MiniMind 最新工件挂成 OpenAI 兼容服务 ──────────────
cd MiniMind
# ckpt_dir 指向 §3 流水线里你验收通过的那个 out/ 目录
python openai_api.py \
  --ckpt_dir out/dpo \
  --host 127.0.0.1 --port 8000
# 冒烟：直接 curl 一下，确认契约可用
curl -s http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"MiniMind","messages":[{"role":"user","content":"你好"}]}' \
  | head -c 400; echo

# ── 终端 2：让 pr03 的 Hermes 把 MiniMind 当成一个普通 provider ──
export HERMES_LLM_BASE_URL="http://127.0.0.1:8000/v1"
export HERMES_LLM_API_KEY="***"          # 本地服务通常不校验，字段仍要占位
export HERMES_LLM_MODEL="MiniMind"          # 与 §6 清单里的 model_name 对齐

# Hermes 侧配置文件（示意，以 pr03 实际字段为准）：
#   provider: openai-compatible
#   base_url: ${HERMES_LLM_BASE_URL}
#   model:    ${HERMES_LLM_MODEL}
#   timeout_s: 60        # 本地小模型延迟高，超时给足

# 换版演练：把 ckpt_dir 从 out/dpo 换成 out/tool 重启服务，
# Hermes 一行配置都不用改 —— 这就是"契约稳定 ⇒ 组件可插拔"。

工程提示："Hermes 不感知模型换了"既是优点也是风险：优点是可插拔，风险是调用方也失去了对变更的知情权。所以版本清单（§6）与换版影响分析（§7）必须存在——接口契约屏蔽了实现细节，但不能屏蔽实现换人了这个事实。

6. 模型版本清单模板

清单（model manifest）是这一篇要交付的第一份产出，也是 pr13（清单与合规审计）要建立、pr15（CI/CD）要消费的同一份数据。完整字段约定如下（先给 schema，再给示例表）：

model_name        组件名（与部署配置里的 model 字段一致）
source_repo       上游仓库 URL
source_commit     构建时的上游 commit（UNKNOWN 需人工补齐或注明原因）
license           许可证（以仓库 LICENSE 为准；训练数据许可另行注明）
quantization      fp16 / int8 / int4 / 未量化 —— 直接决定显存与精度
context_length    对外承诺的最大上下文（不是"能塞进去"，是"测过可用"）
eval_benchmark    基准名 + 得分 + 尺子版本（evaluate.py 的版本要一起记）
tool_call_sr      工具调用成功率（对接 pr09 的 SR 口径，schema 见 §10）
deploy_date       本次部署日期
owner             对"这个工件在生产里出事"负责的人
notes             缺什么、没验什么、已知风险

表内 MiniMind 行仅为"每栏该长什么样"的格式示例，commit 与 SR 均为占位示意；真实值由读者按 §3 脚本自产。DeepSeek / Qwen 行故意全部留白待核查——"不知道"填 UNKNOWN 并写核查路径，是清单的合法状态；编一个像模像样的数字才是事故。

工程提示（/ pr13 预告）：清单字段里最容易被糊弄的是 eval_benchmark 和 context_length：分数必须绑定"尺子的版本"（evaluate 脚本自身的 commit），长度必须绑定"验证方式"（是截断塞满过，还是真做过长文检索）。不带测量条件的指标不是数据，是广告。

7. 换版影响分析

清单管"现在有什么"，影响分析管"换一版会动什么"。典型场景：基座从 v1 升到 v2，哪些下游指标遭殃？先给一张示意的影响矩阵，再给可运行的 diff 生成器：

所有数字为示意，用于演示"影响矩阵怎么读"，不代表任何真实模型版本的实测值。

"""impact.py — 读两份 manifest JSON，产出换版影响报告（pr15 CI 可消费）。"""
import json
from pathlib import Path

# 换版时必须核对的字段：落在这些字段上的变化 = 需要人看一眼
WATCHLIST = ["source_commit", "license", "quantization", "context_length"]
# 数值指标：(key, 方向, 红线阈值)。方向 +1 越大越好，-1 越小越好
METRICS = [("tool_call_sr", +1, 5.0),   # 掉超 5pp 即红线
           ("halluc_rate", -1, 2.0),
           ("tokens_per_s", +1, 20.0),
           ("peak_vram_gb", -1, 20.0),
           ("gsm8k",        +1, 0.03),
           ("mmlu",         +1, 0.02)]

def impact_report(old: dict, new: dict) -> dict:
    out = {"from": old.get("model_name"), "to": new.get("model_name"),
           "field_changes": [], "metric_changes": [], "verdict": "PASS",
           "reasons": []}
    for k in WATCHLIST:
        o, n = old.get(k, "UNKNOWN"), new.get(k, "UNKNOWN")
        if o != n:
            out["field_changes"].append({"field": k, "old": o, "new": n})
            if k in ("license", "quantization"):     # 合规/精度属性质变
                out["verdict"] = "REVIEW"
                out["reasons"].append(f"{k} 变更需合规与精度复核")
    for key, sign, redline in METRICS:
        o, n = old["metrics"].get(key), new["metrics"].get(key)
        if o is None or n is None:
            out["verdict"] = "REVIEW"
            out["reasons"].append(f"{key} 缺一侧测量值，无法对比")
            continue
        delta = n - o
        entry = {"metric": key, "old": o, "new": n, "delta": round(delta, 4),
                 "worse": bool(delta * sign < 0)}      # 朝坏方向动了多少
        if abs(delta) >= redline and entry["worse"]:
            entry["breach"] = True
            out["verdict"] = "BLOCK"
            out["reasons"].append(f"{key} 劣化 {abs(delta):.4g} ≥ 红线 {redline}")
        out["metric_changes"].append(entry)
    return out

if __name__ == "__main__":
    old = json.loads(Path("manifest_v1.json").read_text(encoding="utf-8"))
    new = json.loads(Path("manifest_v2.json").read_text(encoding="utf-8"))
    rep = impact_report(old, new)
    Path("impact_report.json").write_text(
        json.dumps(rep, ensure_ascii=False, indent=2), encoding="utf-8")
    print(f"verdict={rep['verdict']}")
    for r in rep["reasons"]:
        print("  !", r)
    # pr15 的 CI 直接读 impact_report.json 的 verdict 决定放行/拦截

工程提示（/ 15 预告）：报告的 verdict 三态 PASS / REVIEW / BLOCK 是本讲义与 pr15 的接口约定：红线阈值必须写进清单仓库、由团队评审定值，禁止散落在个人脚本里。另外注意方向 sign 的作用——同一张表，SR 跌 5pp 是红线，GSM8K 涨 0.05 不是"奖励"，两者不该用同一条判断逻辑。

8. 与其他开源模型并列入清单

真实项目里清单很少只有一行。MiniMind / Qwen3.8 / DeepSeek V4 三份并列时，写法上有三个坑必须在 pr13 展开前先点名：

• 许可证不是一个字段装得下的：权重许可、训练数据许可、代码许可可能三者不同；"权重开放"≠"数据开放"，更≠"可商用"。至少拆成 license(weights/data/code) 三栏，拿不准填 UNKNOWN 并贴 model card 链接。
• 量化版本是两个工件，不是一个：同一模型的 fp16 / int4 版应各占一行——权重哈希不同、显存与精度不同。混成一行是 pr15 换版检测漏报的头号原因。
• 可比性要显式声明：MiniMind 与旗舰模型的 GSM8K，题集、few-shot 模板、评测脚本都可能不同。并排的那一刻就有义务注明"两行各自的尺子版本"，否则这张表在暗示一个没人测过的排名。

本文刻意不给 Qwen3.8 / DeepSeek V4 的具体版本号、分数和日期——这些信息以官方仓库 / 官方 model card 为准，由读者核查后填入 §6 的预留行。讲义编不出错数据，读者核查出的数据才有价值。

工程提示（供应链 / pr13）：让读者交叉检查他人清单里"来源最可疑"的一个字段，并写出自己的核查路径（打开了哪个链接、看到了什么、抄了什么）。清单文化的核心不是表格，是可追溯。

9. 失败模式速写

把 §2–§7 的机制反着推，就是 MiniMind 类工程的五张失败速写（对接 pr09 的失败归因与编码方法）：

五条失败有共同结构：单看每一环都"能跑"，坏在环与环的版本假设不一致——F1 是 config 与权重、F2 是 LoRA 与母工件、F3 是分数与尺子、F4/F5 是调用方与模型输出之间的版本假设。对策也只有一个：把每对关系里"对方的版本"记成数据，并在加载/部署时刻程序化核对。

工程提示：这五类失败在 pr09（运行时失败归因）和 pr12（评测体系）里各有更细的展开。此处点到为止的意义在于让读者看到：模型层失败大多是"版本管理缺失"的下游症状——上游清单做得好，下游归因表会短很多。

10. 实验接口预留

最后把本文产出的东西"钉"进系列工程的接口，避免各写各的：

• fingerprints.csv / manifest.json（§3、§6）落盘进 Git：pr13 合规审计直接在清单上做差集；字段名以 §6 schema 为准，扩展只增不改。
• impact_report.json（§7）走三态约定：pr15 流水线用 jq '.verdict' 做门禁——PASS 放行、REVIEW 转人工、BLOCK 拒绝部署。红线阈值存于清单仓库 thresholds.yaml，改动走 MR 评审。
• 训练/评测轨迹沿用 pr03 的 traces.csv schema：evaluate / toolcall 每条样本的 prompt、原始输出、解析结果、命中工具、耗时按同一套列名写入，使 tool_call_sr 等指标可从轨迹重算而非手填。
• 失败编码沿用 §9 的 F1–F5 前缀段：与 pr09 运行时失败编码表拼接时，本段占用 F1–F5（版本/配置类），避免两套表撞号。

工程提示：接口的价值在于"提前钉死"——文件名、字段名、verdict 三态、F1–F5 号段，都是后面两个系列文章要消费的东西。先约定 schema 再动手写数据，反向做就会得到两份互相读不懂的清单。

一页纸总结：MiniMind 的价值不在"训了个模型"，而在于它是最小可管理的完整 LLM 标本——仓库结构 = 工程件分解（§2），out/* = 版本工件 + 指纹四件套（§3），model_config = 可 diff 的组件规格书（§4），openai_api = 稳定契约与可插拔（§5），manifest + impact_report = 交给 pr13/pr15 的机器可读接口（§6–§7、§10），F1–F5 = 版本管理缺失的下游症状（§9）。把 LLM 当"版本化组件"管，从这份标本开始。