MAX 文档代码示例仓库解析docs/code/ 的 Bazel 测试体系与 DOC 同步机制【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo本文聚焦 Modular Platform 仓库含 MAX 与 Mojo中 docs/code/ 目录的设计与工程实践它为 MAX 开发者文档中的每一段代码示例提供可独立运行、由 CI 持续测试的活代码并通过# DOC:头部与文档页面建立双向同步约束。读完本文你将掌握如何用 Bazelbt/br运行单个或全量示例、理解示例在不同平台与 GPU 环境下的兼容性限制、弄清docs/code/与max/examples/的分工以及如何安全地为文档示例贡献代码。一、docs/code/ 是什么为文档而生、可独立测试的代码片段库MAX 开发者文档如 docs/max/ 下的各.mdx页面中嵌入了大量 Python / Mojo 代码块。如果这些代码块只以文本形式存在于文档中它们会随着 API 演进逐渐失效——也就是文档领域常说的 snippet 腐烂rot。docs/code/README.md 开篇即点明该目录的设计初衷This directory holds the code examples embedded in the MAX developer documentation, kept here as standalone, tested files so those snippets dont rot.也就是说docs/code/是文档内嵌代码块的源头文件库每个文件对应某个 MAX 文档页面中的一个代码块且每个文件都配套一个 Bazel 测试目标由 CI 持续执行确保示例永远可运行。仓库中该目录的实际结构如下节选自真实目录树docs/code/ ├── README.md ├── develop/ # Python 为主的示例对应 max/develop/* 文档 │ ├── basic-ops/ # 算术、张量运算、激活函数等13 个 .py BUILD.bazel │ ├── broadcasting/ # 自动/显式广播、mask 广播 │ ├── dtypes/ # 数据类型、dtype 转换、DLPack、PyTorch 互操作 │ ├── index/ # eager / graph 模式对比与工作流 │ ├── indexing/ # gather / scatter / where │ ├── layer-comparison/ # 逐层对比 │ ├── layers/ # 模块定义、RMSNorm 子类化、组合运行 │ ├── logit-comparison/ # 需 GPU 与大模型权重的手动测试 │ └── tensors/ # 张量创建与属性shape/rank/dtype/device ├── gpu/ # Mojo 示例对应 max/gpu/* 文档 │ ├── fundamentals/ # GPU 检测、设备信息、线程打印、标量加法 │ └── intro-tutorial/ # GPU 入门 └── tile-tensor/ # Mojo Pixi 示例对应 max/tile-tensor/* 文档 ├── layouts/ # 布局示例 basic_layouts / tiled_layouts └── tensors/ # TileTensor 使用示例CPU 与 GPU每个子目录都遵循同一套约定示例源码.py/.mojo旁边放一个 BUILD.bazel为每个示例定义可执行目标 同名_test测试目标。二、用 Bazel 运行与测试示例bt 与 br示例的测试与运行统一走 Bazel。仓库根目录的 bazelw 以及 Bazel 封装脚本bt/br测试/运行的缩写提供了便捷入口docs/code/README.md 给出了三类典型用法。2.1 运行单个示例的测试bt //oss/modular/docs/code/develop/basic-ops:arithmetic_testbt会构建并运行basic-ops目录下arithmetic示例对应的测试。_test后缀的目标是一个 modular_run_binary_test它把示例当作二进制程序执行并检查其能正常退出。2.2 按主题目录或全量运行bt //oss/modular/docs/code/develop/basic-ops/... bt //oss/modular/docs/code/...Bazel 的...通配符会匹配该包及其所有子包下的全部目标第一条命令验证基础运算整个主题第二条命令跑遍docs/code/下所有示例测试相当于文档代码的完整回归门禁。2.3 直接运行示例不走测试包装br //oss/modular/docs/code/develop/basic-ops:arithmeticbr直接构建并运行二进制目标适合本地手动观察示例输出例如验证张量加法打印结果是否符合文档描述。路径说明//oss/modular/docs/code/...是 README 中使用的完整标签形态对应 MAX 文档站点发布时仓库的挂载位置在本仓库独立检出场景下内部 BUILD 文件如 docs/code/develop/basic-ops/BUILD.bazel本身以//docs/code/...定义包、并以//max/python/max:tensor等相对根路径引用内部依赖因此两种前缀在语义上指向同一组目标。三、示例背后的 Bazel 构建结构源码印证文档只给出了命令用法深入 BUILD 文件可以看清这套体系的具体实现方式。3.1 Python 示例modular_py_binary modular_run_binary_test以 docs/code/develop/basic-ops/BUILD.bazel 为例每个.py文件被声明为一个modular_py_binary目标并配一个同名_test目标# arithmetic.py modular_py_binary( name arithmetic, srcs [arithmetic.py], imports [.], deps [ //max/python/max:tensor, ], ) modular_run_binary_test( name arithmetic_test, size large, binary arithmetic, # Incompatible with macOS: these doc-example tests time out on remote macOS CI workers; Linux CI provides equivalent coverage. target_compatible_with select({ platforms//os:macos: [platforms//:incompatible], //conditions:default: [], }), )要点deps指向 MAX 的 Python 前端库例如//max/python/max:tensor张量 API、//max/python/max/nn与//max/python/max/graphlayers 示例、//max/python/max/driver编译运行管线见 docs/code/develop/layers/BUILD.bazel。modular_run_binary_test通过binary字段挂接可执行目标size large声明该测试资源占用较大。target_compatible_with用select把 macOS 标记为不兼容这是平台约束的落地方式。示例本体也很直白arithmetic.py 展示了 MAX 张量 API 的四则运算# DOC: max/develop/basic-ops.mdx from max.experimental.tensor import Tensor a Tensor([1.0, 2.0, 3.0]) b Tensor([4.0, 5.0, 6.0]) addition a b subtraction a - b multiplication a * b division a / b print(addition) print(multiplication)3.2 Mojo 示例mojo_binary 与 glob 批量生成GPU 与 TileTensor 示例是 Mojo 程序使用mojo_binary目标。以 docs/code/gpu/fundamentals/BUILD.bazel 为例它用glob扫描全部.mojo文件并批量生成二进制与测试目标MOJO_SRCS glob([*.mojo]) [ mojo_binary( name src.split(.)[0], srcs [src], target_compatible_with [//:has_gpu] _EXTRA_CONSTRAINTS.get( src.split(.)[0], [], ), deps [ //max:max_mojo, mojo//:std, ], ) for src in MOJO_SRCS ] [ modular_run_binary_test( name src.split(.)[0] _test, size small, binary src.split(.)[0], tags [gpu], ) for src in MOJO_SRCS ]值得注意的两个细节所有 GPU 示例都被target_compatible_with [//:has_gpu]约束只有机器满足 GPU 条件才参与构建/测试测试目标带有tags [gpu]可在 CI 中通过标签过滤单独挑选 GPU 测试集。对应的 Mojo 示例代码detect_gpu.mojo展示了运行时 GPU 探测的惯用写法from std.sys import has_accelerator def main(): comptime if has_accelerator(): print(GPU detected) # Enable GPU processing else: print(No GPU detected) # Print error or fall back to CPU-only execution3.3 TileTensor 示例Pixi 任务封装docs/code/tile-tensor/下的示例除了 Bazel 目标还提供 pixi.toml 任务方便未接入 Bazel 的场景直接运行[tasks] tile_tensor mojo run tile_tensor_examples.mojo tile_tensor_gpu mojo run tile_tensor_gpu_examples.mojo tile_tensor_all mojo run tile_tensor_examples.mojo mojo run tile_tensor_gpu_examples.mojo安装 Pixi 后即可执行见 docs/code/tile-tensor/tensors/README.mdpixi run tile_tensor pixi run tile_tensor_gpu pixi run tile_tensor_all # 同时运行两组示例布局示例同理见 docs/code/tile-tensor/layouts/README.mdpixi run mojo basic_layouts pixi run mojo tiled_layouts四、平台与资源限制什么环境能跑哪些示例docs/code/README.md 明确提醒Not every example runs on every platform. 结合 BUILD 文件中的约束与注释可归纳为以下四类限制。4.1 macOS 不兼容远程 macOS CI 超时绝大多数示例测试被标记为与 macOS 不兼容platforms//os:macos→ incompatible只在 Linux 上运行。BUILD 注释给出的原因是Incompatible with macOS: these doc-example tests time out on remote macOS CI workers; Linux CI provides equivalent coverage.即远程 macOS CI worker 上这些示例测试会超时而 Linux CI 已提供等价覆盖因此在 Apple Silicon 上这些测试被直接跳过docs/code/develop/basic-ops/BUILD.bazel 中所有modular_run_binary_test目标都带此约束。4.2 Apple GPU 与 bf16Metal 编译器限制部分basic-ops测试在 Apple GPU 上额外被跳过注释统一标注为FIXME: MOCO-3605 — Metal AIR compiler doesnt support bf16 ...具体涉及tensor_math_opsMetal 不支持 bf16 sqrttensor_reductions不支持 bf16 convertfunctional_activations与compose_linear_layer不支持 bf16 fmax。这些示例使用了 bf16 数学内建函数而 Apple 的 Metal AIR 编译器尚未支持因此在 Apple GPU 上无法编译运行。4.3 GPU 门槛与 Apple Silicon 构建机问题GPU 主题的 Mojo 示例全部要求//:has_gpu平台约束。若本机没有兼容 GPUdocs/code/gpu/fundamentals/README.md 说明程序可以编译但运行时只会看到No GPU detected另外print_threads示例还额外加了//:apple_gpu不兼容约束注释记录了原因TODO(MSTDL-2569): MTLCompilerService crashes / Compute function exceeds available stack space compiling GPU kernels that callprint()in multi-block grids on Apple Silicon BuildBuddy workers.即 Apple Silicon BuildBuddy worker 上编译多 block grid 中调用print()的 GPU kernel 时会发生 MTLCompilerService 崩溃或栈空间超限。4.4 logit-comparison需要 GPU 与大模型权重的手动测试docs/code/develop/logit-comparison/BUILD.bazel 中logit_comparison_test被标记为tags [manual]不会进入常规 CImodular_run_binary_test( name logit_comparison_test, size enormous, binary logit_comparison, # This test downloads ~1.2GB of Qwen3-0.6B-Base weights from Hugging Face # and requires a GPU. Run manually with bt-b200 //oss/modular/docs/code/develop/logit-comparison:logit_comparison_test. tags [manual], target_compatible_with select({ platforms//os:macos: [platforms//:incompatible], //conditions:default: [], }), )原因在注释中写得很清楚该测试需要 GPU并会从 Hugging Face 下载约1.2GB 的 Qwen3-0.6B-Base 权重依赖torch、transformers、numpy以及 MAX 的pipelines模块因此声明为size enormous且仅在有人工在带 GPU 的机器上显式触发时才运行如bt-b200命令。五、文档与示例如何保持同步DOC 头与同步检查示例文件与文档页面之间不是松散对应而是有机械化的同步约束机制。5.1# DOC:头部示例指向文档页每个示例文件的第一行注释License 块之后都带一个# DOC:头指明它被哪个文档页面引用。例如 arithmetic.py 的第 13 行# DOC: max/develop/basic-ops.mdxGPU 示例同理detect_gpu.mojo 携带# DOC: max/gpu/fundamentals.mdx这些头指向的文档页面对应仓库中的docs/max/目录如docs/max/gpu/fundamentals.mdx、docs/max/tile-tensor/layouts.mdx、docs/max/tile-tensor/tensors.mdx。5.2 同步检查工作流与 DOCS_SYNC_SKIP按 docs/code/README.md 的描述仓库通过checkExampleDocSync工作流读取该头部当一个 PR 修改了docs/code/下的示例、却没有同步修改其指向的文档页面时检查会失败提醒作者补上文档改动。如果代码改动确实不影响文档文字例如仅重构、格式调整可以在 PR 描述中加入DOCS_SYNC_SKIP来跳过该检查。5.3 代码不会自动注入文档README 特别强调了一个容易误解的点The code in this directory isnotautomatically injected into the documentation. The docs page keeps its own copy of the snippet inline.即docs/code/中的代码不会在文档构建时自动注入到.mdx页面——文档页面内联保留着自己的一份代码副本。因此当你修改这里的示例时必须同时更新.mdx页面中对应的代码块以及周边的解释文字。这也正是checkExampleDocSync存在的原因它只负责提醒不负责替你做。说明本文撰写时当前仓库快照的 .github/workflows/ 目录下并未包含checkExampleDocSync工作流文件本身仅见 auto-labeler、build_and_test、check_pr_target、check_pr_title、cla、test_pre_commit 等上述行为描述以 docs/code/README.md 的文档说明为准。六、docs/code/ 与 max/examples/ 的分工两个目录都承载经过测试的 MAX 代码但服务对象与组织方式不同README 给出了清晰的对比维度docs/code/max/examples/归属方文档团队docs-owned工程师engineer-owned形态与所依附的文档页同置的短小片段聚焦阐释单一概念可独立运行的完整示例项目自成体系目的配合文档讲解随文档一起维护作为可运行的应用程序示范引用方式通过# DOC:头与文档页双向绑定部分项目在被文档页引用时也带# DOC:反向引用一个很实用的判断标准如果你想表达一段文档中的代码如何工作看docs/code/如果你想找一个能直接跑起来的完整应用或工程模板去max/examples/该目录下包含 custom_ops、diffusion、gpu-intro、pytorch_custom_ops 等 13 个以上独立示例项目。七、如何为文档示例做贡献docs/code/README.md 的 Contributing 一节欢迎社区修正文档或示例中的错误。结合前文贡献时需要遵循的核心流程是修改docs/code/下对应的示例文件保持# DOC:头不变或同步更新同时更新对应.mdx文档页面中内联的代码块与说明文字否则checkExampleDocSync会拦下 PR若改动纯粹是代码层面、不影响文档文字在 PR 描述中添加DOCS_SYNC_SKIP本地用bt //oss/modular/docs/code/...跑通相关测试后再提交如果涉及 GPU 示例确认目标机器的//:has_gpu约束与 Apple GPU 兼容性bf16 / print_threads 等已知限制。八、小结docs/code/是 MAX 文档工程化的一个缩影它把文档里的代码提升为一等公民通过Bazel 测试目标 # DOC:同步头 CI 检查三层机制确保文档示例在 API 演进中始终保持可编译、可运行、与文档一致。理解这套体系后你既能用bt/br快速验证任意示例也能在撰写 MAX/Mojo 文档时遵循同样的工程纪律——让每一段示例代码都成为经得起测试的活文档。延伸阅读docs/code/README.md本体系的总纲、docs/code/develop/basic-ops/BUILD.bazelPython 示例构建范式、docs/code/gpu/fundamentals/BUILD.bazelMojo 示例与 GPU 约束、docs/code/tile-tensor/tensors/pixi.tomlPixi 运行入口。【免费下载链接】mojoThe Modular Platform (includes MAX Mojo)项目地址: https://gitcode.com/GitHub_Trending/mo/mojo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考