技术架构

总览

flowchart TB
    subgraph 离线["离线：数据、训练、评测"]
        LX[lexicon.py<br/>标注规范与语法词表] --> GEN[generate.py]
        OOD[ood_handwritten.txt] --> BUILD
        GEN --> BUILD[build.py<br/>清洗/去重/划分/泄漏检查]
        BUILD --> DS[(data/processed/*.jsonl)]
        DS --> TRAIN[train.py]
        BASE[(MiniMind 官方权重)] --> TRAIN
        TRAIN --> RUN[(runs/&lt;name&gt;/<br/>日志 检查点 best.pth)]
        RUN --> EVAL[evaluate.py]
        DS --> EVAL
        RULES[baseline_rules.py] --> EVAL
        EVAL --> RES[(eval/results/<br/>预测 指标 失败案例)]
        RUN --> PKG[package.py]
        RES --> PKG
        PKG --> MODEL[(models/feedlens-minimind-v0.1/<br/>权重 配置 说明卡)]
    end
    subgraph 在线["在线：网页应用"]
        WEB[浏览器<br/>原生 HTML/CSS/JS] <--> API[FastAPI<br/>app/server.py]
        API --> FM[FeedLensModel<br/>modeling.py]
        MODEL --> FM
        RES --> API
    end
    subgraph 上游["上游：MiniMind（只读引用）"]
        UP[model_minimind.py<br/>model_lora.py<br/>tokenizer]
    end
    UP --> TRAIN
    UP --> FM
    SCHEMA[schema.py<br/>标签/提示词/解析] --- GEN
    SCHEMA --- TRAIN
    SCHEMA --- EVAL
    SCHEMA --- API

目录结构

My Minimind Project/
├── feedlens/                 本项目的 Python 包
│   ├── schema.py             任务定义：标签、提示词、输出解析（唯一来源）
│   ├── modeling.py           对接上游模型；统一的提示词拼接与批量解码
│   ├── train.py              训练：LoRA / 全参 / 从零，支持续训
│   ├── evaluate.py           评测与报告生成
│   ├── metrics.py            指标实现（纯 Python）
│   ├── baseline_rules.py     关键词规则基线
│   ├── infer.py              命令行推理
│   ├── package.py            打包模型目录与说明卡
│   └── data/
│       ├── lexicon.py        标注规范 + 合成语法词表
│       ├── generate.py       合成数据生成器
│       ├── build.py          数据流水线
│       └── review.py         抽样人工复核
├── configs/                  训练配置（YAML）
├── data/raw | processed | reports
├── third_party/minimind/     上游源码，固定在提交 f659b55，未修改
├── weights/base/             上游官方权重（下载，不入库）
├── runs/                     每次训练的配置、日志、检查点
├── models/                   打包后的可发布模型
├── eval/                     系统定义、原始结果、自动生成的报告
├── app/                      网页应用（FastAPI + 静态前端）
├── site/                     项目介绍页与文档中心（由 docs/ 生成）
├── docs/                     本文档
├── scripts/                  批处理脚本
└── tests/                    流程级测试

模块说明

任务定义：schema.py

标签集合、输入长度限制、提示词模板、输出解析都只在这一个文件里定义。数据生成、训练、评测、规则基线、后端接口全部从这里读取。

这样做是为了防止一类很常见的错误：训练用的格式和评测或上线解析的格式悄悄不一致，导致指标虚低或虚高却难以发现。

与上游的边界：modeling.py

上游代码放在 third_party/minimind/，通过把该目录加入 sys.path 来导入，不复制、不改动。好处是升级上游时只需切换提交并重跑测试，也让“哪些是我写的”一目了然。

训练：train.py

上游提供了 train_full_sft.py 和 train_lora.py。本项目没有直接调用它们，而是重写了训练循环，原因如下：

学习率调度、权重保存格式（half 精度的 state dict）与上游保持一致，所以本项目训练出的全参数权重可以被上游的 eval_llm.py 直接加载。

评测：evaluate.py、metrics.py

• 参评系统在 eval/systems.yaml 里声明，评测代码对所有系统走同一条路径。
• 指标用纯 Python 实现，约 120 行，没有外部依赖，便于逐行核对。
• 每个系统、每个划分都保存三份文件：全部预测、汇总指标、失败案例。报告由这些文件生成，不手写数字。

网页应用：app/

文档站点：site/

scripts/build_site.py 把 docs/*.md、自动生成的数据报告、评测报告和模型说明卡转成静态 HTML。站点只使用相对路径，可以整个目录复制到任何静态托管位置，或挂在个人网站的子路径下。

关键技术决策

运行环境

依赖列表见仓库根目录 requirements.txt。

本页由 docs/06-architecture.md 生成。