LeanLLM：一个简洁正确的层-wise大模型推理参考实现

LeanLLM是一款针对Google Gemma4模型的轻量级推理引擎，核心特点是通过层-wise加载策略实现极低内存占用，解决了主流推理引擎（如vLLM、llama.cpp）在适配Gemma4新架构时遇到的兼容性问题，提供了'简洁、正确'的参考实现，兼顾教育性与实用性。

2026年4月Google发布的Gemma4采用MatFormer架构、逐层嵌入及双注意力头机制等新设计，但主流推理引擎适配滞后：vLLM因无法处理异构注意力头维度导致性能骤降（RTX4090上仅9token/s）；llama.cpp硬编码final_logit_softcapping参数，引发退化性token循环（如重复<unused24>）。LeanLLM由此诞生，旨在提供Gemma4特性的正确实现。

LeanLLM定位为教育性参考实现，代码精简（不足2000行）、模块职责单一，采用测试驱动开发（67个测试用例全通过）。设计上优先保证正确性，细致处理Gemma4特性：实现双路径注意力机制、动态读取配置参数、过滤未使用token，避免硬编码问题。

LeanLLM采用层-wise推理策略：每次前向传播时逐层加载、计算、驱逐，峰值内存仅为单个层大小+激活值。代价是磁盘I/O开销，但通过后台预取缓解。MacBook Air M1（8GB内存）实测SmolLM2-135M模型：峰值内存124MB，吞吐量1.4token/s，权衡合理。

针对Gemma4异构注意力头（本地256维/全局512维），LeanLLM实现双路径注意力，动态选择局部/全局路径；在sampler.py中动态读取final_logit_softcapping参数，避免硬编码陷阱；还支持思考token预算配置，细粒度控制模型行为。

LeanLLM采用分层架构（core/models/server/cli），模块职责明确易维护，测试覆盖全面（单元+集成测试）。提供多接口（CLI/Python API/OpenAI兼容REST API）。MacBook M1实测SmolLM2-135M：吞吐量1.4token/s，峰值内存124MB，生成文本质量连贯，验证关键技术正确性。

LeanLLM当前局限：无KV缓存导致长序列生成成本线性增长，层-wise策略限制多GPU并行。未来路线图包括探索压缩前沿研究，在保持低内存的同时优化效率，逐步提升性能。

LeanLLM的价值在于提供'正确'的参考实现，填补主流引擎适配Gemma4的空白。对开发者而言，精简代码便于理解LLM推理原理；对资源受限场景，层-wise策略提供可行方案；其'先正确再优化'的理念为AI工程树立了务实榜样。