LLM Pitfall Lab

围绕固定模型与硬件，学习 LLM 推理和后训练，建立观测、诊断与优化能力，并通过规模迁移验证经验的适用边界。

项目目标与范围

• 一期：在 Apple M4 / 24 GiB Mac 上完成 Qwen3.5-4B 的推理、SFT/LoRA、受控在线强化学习、诊断优化和本地部署。
• 二期：迁移到 Qwen3.5-9B，重建基线，验证代表性方法和资源适配。
• 第三阶段：多请求调度、离线偏好优化，以及 MoE 真实推理观察和后训练专题。
• 可解释性持续观察贯穿各阶段，当前只要求方法操作与结果记录。

推理与后训练投入相当。仅开展文本模型实践，不纳入多模态或大规模分布式执行。贯穿任务为中文结构化抽取，不以训练通用助手为目标。

实现与实践方式

正式实现使用 C++23 + MLX：MLX 提供张量计算、自动微分与已有算子，C++ 组织固定模型的推理与训练流程。Metal 局部扩展通过项目计算接口接入，Python 和 MLX-LM 用于辅助对照、数据准备和分析。

按学习需要组合最小机制实验、真实链路观测、针对性修改与优化。复用成熟计算组件与参考实现，不要求从零重写框架，也不以启动成功或训练 loss 下降作为学习完成依据。

项目占用上限 20 GiB，所在卷至少保留 30 GiB；目标运行流程须支持安全暂停、退出释放资源和显式恢复。具体实现边界与资源要求见 文档总入口 指向的专题规范。

构建与使用

当前已建立原生构建、严格离线任务评估、资源预检、受控检查点和合成暂停恢复，以及固定 4B 语言模型的短前向参考对照；尚未提供正式自然语言生成、训练或目标模型暂停恢复命令。实际能力与下一步见 仓库现状。

首次使用先按 构建与检查 完成资源预检、辅助环境准备和 CMake 构建。默认构建目录下可执行：

./runs/d0/build/pitfall-lab --help
./runs/d0/build/pitfall-lab --version
ctest --test-dir runs/d0/build --output-on-failure --no-tests=error

GPU 测试需要本机 Metal 访问能力。依赖版本、SDK 定位、完整构建步骤和检查范围统一由构建指南维护。

文档与学习

docs/README.md 是正式文档唯一总入口，按任务导航到学习规格、模型路线、设计和操作指南。学习笔记 使用 HTML 格式整理提问与讨论中的知识点，并按要求积累有价值的真实问题案例，便于复习和复现。

Agent 接手先读取 AGENTS.md 与文档总入口，再查看仓库现状，按需展开相关专题。