Mojo/MAX Llama3 流水线测试数据全解析从 tiny checkpoint 生成到 Golden Values 注册【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo导读本文以 max/tests/integration/architectures/llama3/testdata/README.md 为骨架系统讲解 Modular PlatformMAX Mojo中 Llama3 架构集成测试的测试数据体系如何用脚本随机生成极小的 llama checkpointtiny llama以加速本地开发迭代、如何用evaluate_llama计算 golden values黄金基准值、如何运行 CPU/GPU 集成测试以及如何通过 S3 http_archive将新的 golden 文件注册进 Bazel 依赖。读完本文你将掌握一套完整的测试数据生成—基准值校验—归档上传工作流并能独立为该测试套件新增数据与用例。一、测试数据目录速览在继续之前先了解llama3测试数据的物理布局。testdata目录是整套 Llama3 集成测试的数据源由 testdata/BUILD.bazel 通过filegroup将*.json与*.gguf文件统一打包供上层测试目标依赖max/tests/integration/architectures/llama3/ ├── testdata/ │ ├── BUILD.bazel # filegroup 打包 *.json 与 *.gguf │ ├── README.md # 本文依据的文档 │ ├── config.json # tiny llama 模型配置 │ ├── config_nvfp4.json # NVFP4 量化场景配置 │ ├── special_tokens_map.json # tokenizer 特殊 token 映射 │ ├── tiny_llama.gguf # float32 微型 checkpoint │ ├── tiny_llama_bf16.gguf # bfloat16 微型 checkpoint │ ├── tokenizer.json # tokenizer 数据 │ └── tokenizer_config.json # tokenizer 配置 ├── BUILD.bazel # 声明 tests_gpu 等测试目标 ├── conftest.py # pytest fixturessession、testdata 路径 ├── test_llama3_attention_fp4_gpu.py ├── test_llama3_linear_fp4_gpu.py └── test_rms_norm_gpu.py其中tiny_llama.gguf与tiny_llama_bf16.gguf就是本文要重点讲解的微型 llama 检查点它们体积极小、加载迅速专门服务于本地开发时的高频测试循环。二、生成 tiny llama checkpoint2.1 为什么需要 tiny llama完整的 Llama-3.1-8B 权重体积庞大跑一次集成测试耗时极长无法支撑改一行代码—跑一次测试的本地开发节奏。为此仓库在完整权重之外配套了一个极小的 llama 测试权重用gen_tiny_llama目标随机生成保证测试逻辑覆盖到位的同时把单次运行时间压缩到毫秒级。2.2 生成命令与参数首先生成 float32 版本TESTDATA_DIR$MODULAR_PATH/max/tests/integration/architectures/llama3/testdata # 生成 float32 checkpoint ./bazelw run //ModularFramework/utils:gen_tiny_llama --\ --output$TESTDATA_DIR/tiny_llama.gguf \ --quantization-encodingfloat32 \ --n-layers1 \ --n-heads1 \ --n-kv-heads1 \ --hidden-dim16再生成 bfloat16 版本# 生成 bfloat16 checkpoint ./bazelw run //ModularFramework/utils:gen_tiny_llama --\ --output$TESTDATA_DIR/tiny_llama_bf16.gguf \ --quantization-encodingbfloat16 \ --n-layers1 \ --n-heads1 \ --n-kv-heads1 \ --hidden-dim16各参数含义如下参数含义示例值--output生成的 GGUF 文件输出路径$TESTDATA_DIR/tiny_llama.gguf--quantization-encoding量化编码格式float32/bfloat16--n-layersTransformer 层数1--n-heads注意力头数量1--n-kv-headsKV 头数量GQA 场景下可与 n-heads 不同1--hidden-dim隐藏层维度162.3 一个关键约束hidden-dim 必须为 8 的倍数文档中特别注明Hidden dim must be a multiple of 8 (required forfused_qkv_matmulkernel alignment)即隐藏维度必须是 8 的倍数这是fused_qkv_matmul内核的对齐要求。fused_qkv_matmul是 MAX 中把 Q/K/V 三个投影矩阵的矩阵乘法融合进单个内核的实现融合内核通常依赖向量化的内存访问而向量宽度如 AVX/NEON 下的 8 元素对齐要求张量最内层维度对齐到 8。如果违背该约束内核对齐失败可能导致性能回退或运行时错误。因此示例中--hidden-dim16正是满足该约束的最小可用取值之一。三、用 evaluate_llama 生成 Golden Valuescheckpoint 生成之后需要使用evaluate_llama计算 golden values——即模型在已知输入下期望输出的基准值后续测试运行时将实际输出与 golden 值对比以此判断推理结果是否正确。3.1 CLI 参数evaluate_llama的 CLI 支持两类参数encoding量化编码q4_k、float32、bfloat16缺省时默认all即全部编码model模型tinyllama、llama3_1缺省时默认all由于两个参数缺省均为all典型的用法是只指向 modular 仓库根目录让 CLI 为每一组编码 × 模型组合把 golden 文件写入测试数据文件夹./bazelw run //max/tests/integration/architectures/llama3:evaluate_llama --\ --modular-path /path/to/modular \ --encoding q4_k \ # float32, q4_k, bfloat16, or all (default) --model tinyllama # llama3_1, tinyllama, or all (default)其中--modular-path指向 modular 仓库根目录CLI 依据该路径定位测试数据目录并落盘 golden 文件--encoding与--model可单独指定以缩小生成范围如只需q4_k编码下的tinyllama也可省略以覆盖全部组合。3.2 与测试的衔接从测试侧看conftest.py 提供了两个关键 fixture 来衔接生成与校验modular_path读取环境变量MODULAR_PATH即 BUILD 中注入的MODULAR_PATH .返回 modular 根目录路径testdata_directory读取环境变量PIPELINES_TESTDATA返回测试数据目录路径BUILD 中设置为max/tests/integration/architectures/llama3/testdata。同时llama3/BUILD.bazel 中 GPU 测试目标tests_gpu通过data [//max/tests/integration/architectures/llama3/testdata]把整个 testdata 目录打包进测试运行环境并在env中注入上述两个环境变量——这构成了生成 golden → 测试读取 golden的完整链路。四、Tokenizer 数据说明testdata中的special_tokens_map.json、tokenizer_config.json与tokenizer.json并非随机生成而是直接复制自 HuggingFace 上的meta-llama/Llama-3.1-8B-Instruct模型。这意味着即使测试用的是 tiny llama 权重tokenizer 仍保持与真实 Llama-3.1-8B-Instruct 完全一致的词表与特殊 token 行为从而保证测试场景与生产推理在文本编解码层面的一致性。五、运行 Llama3 集成测试5.1 CPU 测试CPU 测试的目标是//max/tests/integration:tests./bazelw test //max/tests/integration:tests5.2 只跑 tiny llama本地开发推荐整套集成测试规模很大本地开发时建议用 pytest 的-k过滤器只挑选 tiny llama 相关用例例如./bazelw test //max/tests/integration:tests --test_arg-k test_llama[tiny-float32-llama3_1]-k表达式test_llama[tiny-float32-llama3_1]精确匹配tiny 模型 float32 编码 llama3_1 架构这一参数化用例配合 tiny checkpoint 的毫秒级加载速度可实现非常快的本地迭代反馈。5.3 GPU 测试GPU 测试使用独立目标//max/tests/integration:tests_gpu./bazelw test //max/tests/integration:tests_gpu从 llama3/BUILD.bazel 可以看到该目标的特征size enormous属于超大测试通过exec_properties声明test.resources:gpu-memory: 2为测试预留 GPU 显存通过gpu_constraints限制仅在具备 GPU 的机器上运行并暂时排除 Apple GPU 平台依赖torch、transformers、numpy、hypothesis等 Python 包覆盖max/driver、max/engine、max/graph、max/nn、max/pipelines/architectures/llama3等 MAX 核心模块用于验证 fp4 量化下的 attention 与线性层对应test_llama3_attention_fp4_gpu.py、test_llama3_linear_fp4_gpu.py以及 RMS Normtest_rms_norm_gpu.py。六、注册新的 Golden 测试数据测试用到的 golden 值并非直接存放在源码树中而是通过 Bazel 的http_archive从 S3 拉取。当需要新增 golden 文件时按下述六步操作下载现有归档通过cat MODULE.bazel | grep test_llama_golden找到 s3 URL文档写作时的示例为https://modular-bazel-artifacts-public.s3.amazonaws.com/artifacts/test_llama_golden/3/90811d3fff2b4d88390fb193bb545651529126729c6af2626c68341640c2d62b/test_llama_golden.tar.gz用wget等工具下载到本地解包归档tar -xvf test_llama_golden.tar.gz放入新文件把需要注册的额外文件加入解包后的目录打包并上传运行./utils/upload-public-bazel-artifact.sh test_llama_golden 3 *golden.json其中3是当前归档版本号*golden.json是要纳入归档的文件模式获取结果片段脚本会输出一段可直接粘贴的http_archive定义形如http_archive( name test_llama_golden, build_file_content filegroup( name test_llama_golden, srcs glob([**]), visibility [//visibility:public], ), sha256 SOME_SHA, url https://modular-bazel-artifacts-public.s3.amazonaws.com/artifacts/test_llama_golden/VERSION/SOME_SHA/test_llama_golden.tar.gz, )注意其中build_file_content用filegroupglob([**])将归档内所有文件以公共可见性暴露给 Bazel更新 MODULE.bazel在仓库根目录 MODULE.bazel 中找到test_llama_golden对应的旧http_archive段落删除并替换为第 5 步生成的新定义。上传脚本会在打包时重新计算sha256并把它连同新的版本 URL 一起写入http_archive从而保证 Bazel 拉取的归档内容可校验、可复现。整个流程的核心思路是测试数据与源码分离、用不可变对象存储托管、用哈希锁版本。七、注册 Torch Golden Logits除 MAX 自身推理产出的 golden 外还有一套独立于 MAX 的基准用 PyTorch 跑出参考 logits用于交叉验证 MAX 的推理结果与业界标准框架一致。7.1 生成新的 torch golden目前仅针对 GPU 上的 bfloat16 生成 torch golden命令为./bazelw run max/tests/integration/architectures/llama3/testdata:run_torch_llama_gpu \ -- --model llama3_1 --encoding bfloat16 --verbose其中--model llama3_1指定基准模型当前主要覆盖llama3_1--encoding bfloat16指定量化编码--verbose输出详细日志。7.2 上传新的 golden与上一节的归档流程基本一致只是归档名换成了torch_llama_golden从cat MODULE.bazel | grep torch_llama_golden报告的 URL 下载 tar 文件解包tar -xvf torch_llama_golden.tar.gz在文件清单中加入新的 golden 文件运行./utils/upload-public-bazel-artifact.sh torch_llama_golden 3 torch_*golden.jsontorch_*golden.json是 torch golden 文件的命名模式用脚本输出的http_archive片段更新 MODULE.bazel 中对应段落。可以看到MAX golden 与 torch golden 共用同一套版本化 S3 归档 http_archive引用机制只是归档名与文件命名模式不同便于在测试中区分两类基准来源。八、小结一套可复现的基准测试数据工作流综合全文Llama3 集成测试的数据体系遵循清晰的三段式工作流生成gen_tiny_llama随机生成微型 checkpoint注意hidden-dim为 8 的倍数evaluate_llama为各编码 × 模型组合计算 golden valuestorch 侧用run_torch_llama_gpu产出参考 logits消费CPU 测试走//max/tests/integration:testsGPU 测试走//max/tests/integration:tests_gpu本地开发用-k过滤器聚焦test_llama[tiny-float32-llama3_1]等微型用例conftest.py 与 BUILD.bazel 负责把 testdata 目录与路径注入测试环境归档golden 文件不直接入库而是经upload-public-bazel-artifact.sh打包上传 S3再以带sha256的http_archive形式写回根目录 MODULE.bazel实现可校验、可复现的版本化分发。这套设计既保证了开发期毫秒级的快速反馈tiny llama又保证了发布期对完整模型llama3_1与多种量化编码float32 / bfloat16 / q4_k的严格回归覆盖是 MAX 集成测试基础设施中值得借鉴的样板。【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考