https://secaumene.github.io/frame/Recent content in Frame 动手学教程 on SecaumeneHugo -- gohugo.iozh<a href="https://creativecommons.org/licenses/by-nc/4.0/" target="_blank" rel="noopener">CC BY-NC 4.0</a>https://secaumene.github.io/frame/01-quickstart/Mon, 01 Jan 0001 00:00:00 +0000https://secaumene.github.io/frame/01-quickstart/适用版本：Frame v1.3 M28，C++20；Python 绑定 0.1.0（可选） 最后更新：2026-07-25 本章是非规范性使用说明；C++ 安装包导出以构建与测试为准。 学习目标 在 Frame 仓库之外创建、配置、链接并运行最短的独立 C++ 项目。 前置 完成00 从源码安装，并在当前 shell 中保留 FRAME_PREFIX。项目目录可以与 &lt;frame-source&gt; 平级，也可以位于任意其他位置；它不得引用 Frame 的 src/、examples/ 或源码 include/ 路径。 可运行代码 先在 Frame 仓库之外创建目录： mkdir -p &#34;$HOME/frame-tutorial/frame-quickstart&#34; cd &#34;$HOME/frame-tutorial/frame-quickstart&#34; 然后创建两个文件： frame-quickstart/ ├── CMakeLists.txt └── main.cpp CMakeLists.txt： cmake_minimum_required(VERSION 3.24) project(frame_quickstart LANGUAGES CXX) find_package(frame CONFIG REQUIRED) add_executable(frame_quickstart main.cpp) target_compile_features(frame_quickstart PRIVATE cxx_std_20) target_link_libraries(frame_quickstart PRIVATE frame::frame) main.cpp： #include &lt;iostream&gt; #include &lt;frame/core/shape.h&gt; int main() { std::cout &lt;&lt; frame::Shape({2, 3}).https://secaumene.github.io/frame/02-core-concepts/Mon, 01 Jan 0001 00:00:00 +0000https://secaumene.github.io/frame/02-core-concepts/适用版本：Frame v1.3 M28，C++20；Python 绑定 0.1.0（可选） 最后更新：2026-07-24 本章是非规范性使用说明；语义以架构总览、执行模型和算子系统为准。 学习目标 区分运行期数据、图内符号和编译结果，并理解 Graph → compile → run 的静态图闭环。 前置 完成01 仓外 C++ 项目。仓内的 02_graph_compile 是完整图编译示例；它用于学习，不是外部工程的依赖。 可运行入口与核心代码 先在源码仓库运行完整 CPU 示例： cd &lt;frame-source&gt; cmake --preset dev cmake --build --preset dev --target frame_example_02_graph_compile ./build/dev/examples/frame_example_02_graph_compile cpu 示例先声明输入，再用 Graph::create_node 或 frame::ops::create_node_with_inferred_types 建立算子节点，最后编译和运行： #include &lt;frame/ops/graph_builder.h&gt; frame::ir::Graph graph(&#34;relu_graph&#34;); // 图输入和算子属性的具体参数以算子 schema 为准。 // 节点输出是 Value，不能把运行期 Tensor 当作图内接线。 auto relu = frame::ops::create_node_with_inferred_types(graph, &#34;relu&#34;, {input}).value(); graph.mark_output(relu, 0); auto executable = frame::runtime::compile(graph, frame::kCpuBackendName, {}).https://secaumene.github.io/frame/03-python-api/Mon, 01 Jan 0001 00:00:00 +0000https://secaumene.github.io/frame/03-python-api/适用版本：Frame v1.3 M28，C++20；Python 绑定 0.1.0（可选） 最后更新：2026-07-24 本章是非规范性使用说明；绑定实际接口以 Python 类型存根 和Python 绑定规范为准。 学习目标 用 PyTorch 的常见概念定位 Frame Python 绑定，并识别不能逐行迁移的 API。 前置 完成02 核心概念。Python 绑定是 C++ 核心的薄层入口；PyTorch 只是概念和代码对照基线，不是依赖或等价实现。 可运行代码 先确认扩展是否可用，再以 Graph 作为每个算子的第一个参数构图： import frame print(frame._core_available) if not frame._core_available: raise RuntimeError(&#34;frame C++ extension is unavailable&#34;) graph = frame.Graph(&#34;python_graph&#34;) x = graph.add_graph_input([2, 3], frame.DType.float32) y = frame.relu(graph, x) graph.mark_output(y) executable = frame.compile(graph, &#34;cpu&#34;) 真实映射总表 PyTorch 概念或写法 Frame Python 绑定 重要差异 torch.Tensor frame.Tensor、frame.from_numpy() Frame Tensor 是 C++ 运行期值；from_numpy 复制到 CPU。 torch.https://secaumene.github.io/frame/04-nn-and-data/Mon, 01 Jan 0001 00:00:00 +0000https://secaumene.github.io/frame/04-nn-and-data/适用版本：Frame v1.3 M28，C++20；Python 绑定 0.1.0（可选） 最后更新：2026-07-24 本章是非规范性使用说明；nn/data 语义以nn/data 架构为准。 学习目标 以 C++ 建立固定 batch 的 frame::nn 图，并用 DataLoader 提供批数据。 前置 完成02 核心概念。完整可运行流程见仓内示例 04。 可运行代码 先声明普通图输入，按确定顺序追加参数输入，再调用 Module 的 build()： frame::ir::Value* features = graph.add_graph_input(feature_type).value(); auto params = frame::nn::add_parameter_inputs(graph, model.parameters()).value(); frame::ir::Value* output = model.build(graph, {features}, params).value()[0]; graph.mark_output(output); Linear 的 weight 是 [in_dim, out_dim]。当 with_bias=true 时，bias 是 [batch, out_dim]，所以 batch 属于静态签名。TensorDataset 和 DataLoader 按列提供批数据；drop_last=true 可保持固定 batch。 预期输出 示例 04 会构建模型图并迭代 CPU 批数据。具体批次数和数值取决于示例输入；请以实际运行输出验收，而不是把本章描述当作已执行结果。 PyTorch 对照 PyTorch 的 nn.https://secaumene.github.io/frame/05-training/Mon, 01 Jan 0001 00:00:00 +0000https://secaumene.github.io/frame/05-training/适用版本：Frame v1.3 M28，C++20；Python 绑定 0.1.0（可选） 最后更新：2026-07-24 本章是非规范性使用说明；自动微分与训练语义以自动微分与训练架构为准。 学习目标 从 C++ 前向图派生反向图，并以独立 SGD 更新图完成 CPU 训练。 前置 完成04 nn 与数据。完整流程见仓内示例 05。 可运行代码 在训练循环前分别建立并编译训练图和更新图： auto training = frame::compiler::build_backward_graph(forward, 0, wrt_indices).value(); auto train_exec = frame::runtime::compile(training, frame::kCpuBackendName, {}).value(); auto update = frame::compiler::build_sgd_update_graph(param_types, 0.05).value(); auto update_exec = frame::runtime::compile(update, frame::kCpuBackendName, {}).value(); 训练图输出是前向输出后接所求参数的梯度；更新图输入为参数后接梯度，输出为新参数。循环只运行两个已编译对象，并将新参数 Tensor 传给下一步。 预期输出 示例 05 会在 CPU 反向链上报告训练过程中的数值。学习率、输入和迭代次数改变时输出也会改变；请以实际示例运行结果判断训练是否完成。 PyTorch 对照 PyTorch 常把 loss.backward() 与 torch.optim.SGD 放在 eager 训练循环中。Frame 的 build_backward_graph 与 build_sgd_update_graph 分别构造两张静态图，之后才各自编译与运行。前者是概念基线，后者不是与其逐行或运行时行为等价的 API。https://secaumene.github.io/frame/06-backends/Mon, 01 Jan 0001 00:00:00 +0000https://secaumene.github.io/frame/06-backends/适用版本：Frame v1.3 M28，C++20；Python 绑定 0.1.0（可选） 最后更新：2026-07-24 本章是非规范性使用说明；后端能力以后端支持矩阵和CUDA 后端为准。 学习目标 理解 Frame 的 device 契约，选择后端并验证 CUDA 静态图执行路径。 前置 完成02 核心概念。CPU 始终可用；NVIDIA GPU 的完整运行入口是仓内示例 02。 可运行代码 在具备 CUDA Toolkit 的环境中，可用 CUDA preset 构建并运行示例： export PATH=/usr/local/cuda/bin:$PATH export CUDAToolkit_ROOT=/usr/local/cuda cd &lt;frame-source&gt; cmake --preset cuda cmake --build --preset cuda --target frame_example_02_graph_compile ctest --preset cuda -R example_02_graph_compile_cuda --output-on-failure ./build/cuda/examples/frame_example_02_graph_compile cuda 构图、运行期 Tensor 与编译目标必须一致： const frame::Device device{frame::kCudaBackendName, 0}; auto executable = frame::runtime::compile(graph, frame::kCudaBackendName, {}).value(); auto outputs = frame::runtime::run_with_allocated_outputs( *executable, frame::kCudaBackendName, inputs).https://secaumene.github.io/frame/07-cpp-and-tools/Mon, 01 Jan 0001 00:00:00 +0000https://secaumene.github.io/frame/07-cpp-and-tools/适用版本：Frame v1.3 M28，C++20；Python 绑定 0.1.0（可选） 最后更新：2026-07-24 本章是非规范性使用说明；C++ 导出、DSL 和 ONNX 边界分别以 构建与测试、前端 DSL 和 ONNX 互操作接口为准。 学习目标 在已完成独立 C++ 项目的基础上，使用导出目标、JSON DSL 和 ONNX initializer 权重交换。 前置 安装和独立消费工程的完整步骤见00 从源码安装和01 仓外 C++ 项目，本章不重复这些内容。 可运行代码 消费工程继续使用导出的安装包和公共聚合目标： find_package(frame CONFIG REQUIRED) target_link_libraries(my_app PRIVATE frame::frame) frame/frame.h 是核心入口，但不包含 nn、data、autograd 或 interop 的专用头；使用这些功能时显式包含各自的公共头文件。 frame_dslc 的 --check、--run 和 --emit 面向 v0 JSON DSL。ONNX 接口仅交换具名 initializer 权重： const std::vector&lt;frame::interop::NamedTensor&gt; weights{{&#34;weight&#34;, weight_tensor}}; frame::interop::save_onnx_weights(&#34;weights.onnx&#34;, weights); auto loaded = frame::interop::load_onnx_weights(&#34;weights.onnx&#34;, *allocator).value(); 预期输出 独立消费工程的验收是 CMake 成功找到 frame 并链接 frame::frame。DSL 和 ONNX 命令或示例的具体输出取决于输入文件；请运行相应工具或示例后记录实际结果。https://secaumene.github.io/frame/08-development/Mon, 01 Jan 0001 00:00:00 +0000https://secaumene.github.io/frame/08-development/适用版本：Frame v1.3 M28，C++20；Python 绑定 0.1.0（可选） 最后更新：2026-07-23 本章是非规范性使用说明；冲突时以仓库 docs/ 为准。本章不修改、解释或替代治理规则。 学习目标 按 C++ core-first 路径定位实现、测试和权威文档入口。 运行入口 先阅读架构总览、执行模型和复用政策，再开始任何仓内改动。 核心概念与分步讲解 include/frame/ 提供公共 C++20 契约；src/ 实现 core、IR、ops、compiler、runtime、nn/data 与后端。 tests/ 是行为证据；docs/ 是规范、架构、后端与决策的单一事实来源。 Python 是 pybind11 薄绑定；后端专有实现位于 src/backends/ 并经公共 HAL 接入。 任务 → 阅读对应 docs/ → 查找复用 → 必要的设计门 → C++ 实现 → 测试 → 文档 → review 能力边界 本章只给出导航，不定义流程判据。复用、设计审查、测试、文档和 review 的要求以复用政策、C++ 编码规范和构建与测试规范为准。 本章小结 功能先在 C++ 核心实现。 文档规范和测试共同约束改动。 路由表决定额外流程门禁。 练习 为一个拟改模块找到其 include/、src/、tests/ 与权威 docs/ 入口。 在动手前为新增算子任务列出需要阅读的权威文档。 下一步 新算子继续09 添加算子；构建或环境失败时阅读10 排错。https://secaumene.github.io/frame/09-add-operator/Mon, 01 Jan 0001 00:00:00 +0000https://secaumene.github.io/frame/09-add-operator/适用版本：Frame v1.3 M28，C++20；Python 绑定 0.1.0（可选） 最后更新：2026-07-23 本章是非规范性使用说明；冲突时以算子系统和相关规范为准。 学习目标 通过可运行 C++ 示例理解算子的注册、构图、编译和执行，并区分实验与正式贡献。 运行入口 构建并运行 frame_example_03_custom_op；完整源码为03_custom_op。正式贡献前先完成08 开发者导览。 核心概念与分步讲解 FRAME_REGISTER_OP(&quot;scaled_relu&quot;) 声明 schema、静态 shape 推断与 trait。 CPU kernel 通过 dispatch_dtype 进行编译期类型分派，并以 FRAME_REGISTER_KERNEL 注册。 create_node_with_inferred_types 构图后，仍由 runtime::compile 形成执行计划。 外部可执行文件可保留自己的静态注册以验证应用自用算子；Python 绑定不是该核心实现的一部分。 能力边界 外部实验不等同于仓内支持。若要成为正式算子，必须按算子系统与权威规范完成复用搜索、schema、CPU reference、后端路线、梯度、测试、绑定和审查；本章不替代这些判据。 本章小结 schema 与 kernel 注册是不同职责。 示例走完整编译路径，不是 eager 替代。 正式贡献有额外测试和治理要求。 练习 运行示例 03，定位 schema 注册、kernel 注册和 compile 三处代码。 为一个假想算子列出需先搜索的同名实现、算子组合和后端能力。 下一步 提交仓内改动前回到08 开发者导览并执行其权威流程入口。https://secaumene.github.io/frame/10-troubleshooting/Mon, 01 Jan 0001 00:00:00 +0000https://secaumene.github.io/frame/10-troubleshooting/适用版本：Frame v1.3 M28，C++20；Python 绑定 0.1.0（可选） 最后更新：2026-07-23 本章是非规范性使用说明；冲突时以仓库 docs/ 为准。 学习目标 沿 C++ configure、build、run 顺序复现问题，并将 eager 习惯迁移为编译图。 运行入口 从示例 02的最小图开始，记录 preset、NVIDIA 驱动、Toolkit、backend、dtype、shape 和完整英文错误消息。CUDA 命令与缓存恢复见06 后端与设备。 核心概念与分步讲解 configure：Toolkit 不可见时按第 06 章设置环境变量；错误缓存时使用 cmake --fresh --preset cuda。 build：只构建相应示例 target，并以 CTest 验证示例 02 的 CUDA 路径。 run：核对图输入顺序，以及 Tensor 数量、shape、dtype、device；任一静态签名变化后重新编译。 症状 首先检查 CUDA 未生成、构建或运行失败 第 06 章的 Toolkit、preset、target 与 CTest 命令。 CUDA device mismatch 图输入 device、编译后端、运行 Tensor device 是否一致。 训练更新异常 训练图的 forward/gradient 顺序，以及更新图的 param/gradient 顺序。 期待 ONNX 整图导入 当前仅交换 initializer；图仍用 Frame API 或允许前端建立。 能力边界 训练示例是 CPU 反向链；DataLoader 产出 CPU columns；ONNX 仅 initializer。不能把 CUDA 编译 fallback、ONNX 权重交换或 eager 路径当作完整 CUDA 训练、完整模型导入或主执行路径。https://secaumene.github.io/frame/00-installation/Mon, 01 Jan 0001 00:00:00 +0000https://secaumene.github.io/frame/00-installation/适用版本：Frame v1.3 M28，C++20；Python 绑定 0.1.0（可选） 最后更新：2026-07-24 本章是非规范性使用说明；构建、安装和导出契约以构建与测试为准。 学习目标 从已有 Frame 源码构建 CPU 版本，并安装供独立 C++ 消费工程使用的安装包。 前置 CMake 源码构建需要 CMake 3.25 或更高版本，以及支持 C++20 的编译器。 消费方工程需要 CMake 3.24 或更高版本。 从公开仓库获取源码；以下用 &lt;frame-source&gt; 表示克隆后的源码目录。 Frame 官方只发布纯源码，不提供 wheel、系统包、容器或预编译库；本章全部编译 都在你的机器上完成。 可运行命令 先克隆公开源码，再使用最小的 cpu-only preset。选择用户可写的专用安装前缀： git clone https://github.com/Secaumene/frame-public.git &lt;frame-source&gt; export FRAME_PREFIX=&#34;$HOME/.local/frame/0.1.0&#34; cd &lt;frame-source&gt; bash scripts/install.sh --preset cpu-only --prefix &#34;$FRAME_PREFIX&#34; find &#34;$FRAME_PREFIX&#34; -name frame-config.cmake -print 便利脚本在尚未配置该 preset 时会先构建。等价的原生命令是： cd &lt;frame-source&gt; cmake --preset cpu-only cmake --build --preset cpu-only cmake --install build/cpu-only --prefix &#34;$FRAME_PREFIX&#34; 首次构建可能获取项目锁定的依赖；这取决于本机缓存和构建环境。安装结果应包含 frame-config.