ggml 机器学习张量库快速入门：从源码构建到矩阵乘法与多后端计算-北京尧图网络

ggml 机器学习张量库快速入门从源码构建到矩阵乘法与多后端计算【免费下载链接】ggmlTensor library for machine learning项目地址: https://gitcode.com/GitHub_Trending/gg/ggmlggml 是一个以简单、可移植、高效为核心目标的机器学习张量库采用纯 C/C 实现且不依赖任何第三方库是 llama.cpp、whisper.cpp 等流行推理引擎的底层计算基石。本文以仓库根目录 README.md 为骨架结合 examples/simple 中的完整示例代码与 include/ggml.h 的公开 API系统讲解 ggml 的源码构建流程、核心编程模型张量、上下文、计算图、矩阵乘法实现细节以及基于后端调度器Backend Scheduler在 CPU/GPU 间自动分配计算的方式。一、项目概览ggml 是什么ggml 是面向机器学习的张量库Tensor library for machine learning其设计目标可以归纳为以最小的配置成本获得简单、可移植、高效纯 C/C 实现零依赖整个核心库不依赖任何第三方运行时库编译和部署非常轻量跨平台支持 x86、ARM、RISC-V、LoongArch、PowerPC、s390x 以及 WebAssembly 等架构对应仓库中的 src/ggml-cpu/arch 目录分别包含 x86、arm、riscv、loongarch、powerpc、s390、wasm 等架构的优化实现SIMD 优化内核为 x86AVX/AVX2/AVX512 系列、ARM 和 RISC-V 提供 SIMD 优化的计算内核广泛的后端支持覆盖 CPU、GPU、NPU 以及浏览器端浏览器端通过 WebGPU 实现仓库 src 下包含ggml-cuda、ggml-metal、ggml-vulkan、ggml-sycl、ggml-opencl、ggml-webgpu、ggml-cann、ggml-openvino等多个后端目录丰富的量化格式支持 2-bit 到 8-bit 的整数量化Q2_K、Q3_K、Q4_0、Q5_0、Q8_0 等以及 MXFP4、NVFP4 等微缩放microscaling格式运行期零内存分配通过计算图内存缓冲区的设计在运行时避免动态内存分配带来的开销。从 CMakeLists.txt 可以看到当前仓库版本为 0.21.0GGML_VERSION_MAJOR 0、GGML_VERSION_MINOR 21、GGML_VERSION_PATCH 0构建系统会自动探测 git commit 并附加到版本信息中。二、从源码构建2.1 标准构建流程README 给出的标准构建流程如下git clone https://github.com/ggml-org/ggml cd ggml mkdir build cd build cmake .. cmake --build . --config Release -j 8几点值得注意顶层 CMakeLists.txt 声明cmake_minimum_required(VERSION 3.14...3.28)工程语言为C CXX ASM默认启用 C11 与 C17 标准CMAKE_C_STANDARD 11、CMAKE_CXX_STANDARD 17当未显式指定构建类型且不在 Xcode/MSVC 环境下时CMake 会强制默认使用Release构建类型作为独立工程构建时GGML_STANDALONE ON默认会构建测试与示例GGML_BUILD_TESTS、GGML_BUILD_EXAMPLES默认开启二进制输出到build/bin构建产物通过install(TARGETS ggml ...)安装同时生成ggml.pcpkg-config 文件与 CMake 包配置文件便于下游项目以find_package(ggml)的方式集成。2.2 常用构建选项CMakeLists.txt 中以option()声明了大量开关可在cmake ..时通过-D传入。下表列出与后端和优化相关的核心选项选项默认值说明GGML_NATIVE按平台自动为当前系统 CPU 做本地优化默认开启交叉编译时自动关闭GGML_CPUON是否启用 CPU 后端GGML_BLASApple 平台 ON其余 OFF是否使用 BLAS 加速矩阵乘法GGML_BLAS_VENDOR可选Generic、Apple等GGML_CUDAOFF是否使用 CUDA 后端NVIDIA GPUGGML_METALApple 平台 ON其余 OFF是否使用 Metal 后端macOS GPUGGML_VULKANOFF是否使用 Vulkan 后端跨平台 GPUGGML_SYCLOFF是否使用 SYCL 后端Intel GPU 等GGML_OPENCLOFF是否使用 OpenCL 后端GGML_OPENVINOOFF是否使用 OpenVINO 后端GGML_WEBGPUOFF是否使用 WebGPU 后端浏览器GGML_OPENMPON是否使用 OpenMP 多线程GGML_AVX/GGML_AVX2/GGML_AVX512按架构是否启用对应 x86 SIMD 指令集GGML_RVVON是否启用 RISC-V 向量扩展GGML_BUILD_TESTS/GGML_BUILD_EXAMPLES独立构建时 ON是否构建测试与示例GGML_STATICOFF是否静态链接库GGML_BACKEND_DLOFF是否将后端编译为动态库运行时加载例如需要 NVIDIA GPU 加速时可执行cmake .. -DGGML_CUDAON2.3 快速验证构建构建完成后build/bin下会生成大量示例与测试程序。例如simple-ctx与simple-backend直接输出一次矩阵乘法的结果可以作为构建成功与否的冒烟验证tests目录下tests/CMakeLists.txt的测试程序如test-backend-ops、test-quantize-fns则通过 CTest 运行用于验证各后端算子与量化函数的正确性。三、核心编程模型张量、上下文与计算图3.1 基本概念使用 ggml 编程需要理解三个核心概念张量struct ggml_tensor多维数组最多支持 4 维。每个张量包含各维度元素个数ne与步长nb以字节为单位的 stride因此可以表达非连续内存的转置、置换等操作。张量元素按行主序row-major存储数据存放在ggml_init()分配的缓冲区中。上下文struct ggml_context所有张量和计算图都从上下文分配内存。在调用ggml_init()时一次性指定内存大小mem_size后续所有张量创建都从这块缓冲区中切分从而避免运行期动态分配。计算图struct ggml_cgraph由张量算子节点组成的 DAG。先定义图再一次性执行图这与惰性求值的思路一致——定义阶段不产生任何实际计算。include/ggml.h头文件顶部给出了完整的最小示例其核心调用链为struct ggml_context * ctx ggml_init(params); // 1. 创建上下文 struct ggml_tensor * f /* 用 ggml_new_tensor_* 创建张量并组合算子 */; struct ggml_cgraph * gf ggml_new_graph(ctx); // 2. 创建计算图 ggml_build_forward_expand(gf, f); // 3. 把前向传播节点展开进图 ggml_graph_compute_with_ctx(ctx, gf, n_threads); // 4. 执行计算该头文件还特别强调每个算子都同时实现了前向forward与反向backward计算函数配合ggml_set_param()标记输入变量后即可用同一张图反复执行前向/反向传播实现自动微分与优化对应 include/ggml-opt.h 中的优化器接口。3.2 张量与上下文的典型用法以 examples/simple/simple-ctx.cpp 为例其load_model()展示了标准的内存预估与上下文初始化流程size_t ctx_size 0; { ctx_size rows_A * cols_A * ggml_type_size(GGML_TYPE_F32); // tensor a ctx_size rows_B * cols_B * ggml_type_size(GGML_TYPE_F32); // tensor b ctx_size 2 * ggml_tensor_overhead(), // 张量元数据开销 ctx_size ggml_graph_overhead(); // 计算图开销 ctx_size 1024; // 额外余量 } struct ggml_init_params params { /*.mem_size */ ctx_size, /*.mem_buffer */ NULL, /*.no_alloc */ false, // 传统 API 下必须为 false }; model.ctx ggml_init(params); // 创建 2D 张量ggml_new_tensor_2d(ctx, 类型, 列数, 行数) model.a ggml_new_tensor_2d(model.ctx, GGML_TYPE_F32, cols_A, rows_A); model.b ggml_new_tensor_2d(model.ctx, GGML_TYPE_F32, cols_B, rows_B); // 把主机内存拷贝进张量数据区 memcpy(model.a-data, a, ggml_nbytes(model.a)); memcpy(model.b-data, b, ggml_nbytes(model.b));关键 API 在 include/ggml.h 中的声明如下均为GGML_API导出ggml_type_size(enum ggml_type type)返回该类型一个 block 的字节数include/ggml.h#L748ggml_tensor_overhead()返回单个张量的元数据内存开销include/ggml.h#L805ggml_graph_overhead()返回计算图的内存开销include/ggml.h#L2826ggml_new_tensor_2d(ctx, type, ne0, ne1)创建二维张量ne0为列数第 0 维ne1为行数第 1 维include/ggml.h#L835ggml_nbytes(tensor)返回张量数据占用总字节数include/ggml.h#L744。3.3 构建计算图并执行build_graph()与compute()展示了定义图执行图的完整流程struct ggml_cgraph * build_graph(const simple_model model) { struct ggml_cgraph * gf ggml_new_graph(model.ctx); // result a * b^T 见下文矩阵乘法约定 struct ggml_tensor * result ggml_mul_mat(model.ctx, model.a, model.b); ggml_build_forward_expand(gf, result); return gf; } struct ggml_tensor * compute(const simple_model model) { struct ggml_cgraph * gf build_graph(model); int n_threads 1; // 参与多线程计算的线程数 ggml_graph_compute_with_ctx(model.ctx, gf, n_threads); // 本例中输出张量是图中的最后一个节点 return ggml_graph_node(gf, -1); }其中ggml_mul_mat(ctx, a, b)创建矩阵乘法算子节点include/ggml.h#L1428ggml_build_forward_expand(gf, result)把前向计算所需的全部节点展开进图include/ggml.h#L2796ggml_graph_compute_with_ctx(ctx, gf, n_threads)执行计算图ggml_graph_node(gf, -1)取图中最后一个节点即输出张量。主函数开头调用ggml_time_init()初始化计时子系统include/ggml.h#L730最后用ggml_free(model.ctx)释放上下文。值得注意的是张量a、b以F32类型创建但在 examples/gpt-2 等真实模型的示例中权重张量通常以量化类型创建以节省显存与带宽。四、矩阵乘法从数学约定到代码验证4.1 传统矩阵乘法传统做法是按行 × 按列相乘$$A \times B C$$例如$$ \begin{bmatrix} 2 8 \ 5 1 \ 4 2 \ 8 6 \ \end{bmatrix} \times \begin{bmatrix} 10 9 5 \ 5 9 4 \ \end{bmatrix}\begin{bmatrix} 60 90 42 \ 55 54 29 \ 50 54 28 \ 110 126 64 \ \end{bmatrix} $$4.2 ggml 的约定B 以转置形式传入ggml 中调用ggml_mul_mat(A, B)时第二个参数按转置后的 B传入乘法按行 × 行进行输出 C 也相应是转置的$$ggml_mul_mat(A, B^T) C^T$$$$ ggml_mul_mat( \begin{bmatrix} 2 8 \ 5 1 \ 4 2 \ 8 6 \ \end{bmatrix}, \begin{bmatrix} 10 5 \ 9 9 \ 5 4 \ \end{bmatrix} )\begin{bmatrix} 60 55 50 110 \ 90 54 54 126 \ 42 29 28 64 \ \end{bmatrix} $$这正是 examples/simple/README.md 中反复强调的约定在 ggml 中权重矩阵通常以转置形式存储ggml_mul_mat按行与行相乘这种布局更利于 SIMD 向量化和缓存友好访问。从源码结构看这也解释了为何各后端如 src/ggml-cuda/mmvq.cu、src/ggml-cpu/ops.cpp都围绕行主序 × 转置权重的布局做专门优化。4.3 用 simple-ctx 验证examples/simple/simple-ctx.cpp 中矩阵 A 为 4×2、矩阵 B 以转置形式3×2 存储语义为 2×3 矩阵的转置传入其输出期望值与上述数学推导完全一致mul mat (3 x 4) (transposed result): [ 60.00 55.00 50.00 110.00 90.00 54.00 54.00 126.00 42.00 29.00 28.00 64.00 ]运行build/bin/simple-ctx即可看到该输出。注意结果张量的形状是 3×4result-ne[0]3列、result-ne[1]4行正是 $C^T$ 的形状与输出也是转置的约定一致。五、多后端计算从 simple-ctx 到 simple-backend5.1 两种示例的定位examples/simple下有两个程序simple-ctx只使用上下文context CPU 计算代码最精简适合理解核心 API但不支持 GPU 加速simple-backend引入后端Backend抽象与后端调度器Backend Scheduler自动选用最优后端如 CUDA、Metal并演示了张量数据在后端内存与主机内存之间的搬运。5.2 simple-backend 的初始化流程examples/simple/simple-backend.cpp 的init_model()展示了标准的多后端初始化模式ggml_log_set(ggml_log_callback_default, nullptr); ggml_backend_load_all(); // 加载所有已编译的后端 model.backend ggml_backend_init_best(); // 初始化“最优”后端如 GPU model.cpu_backend ggml_backend_init_by_type(GGML_BACKEND_DEVICE_TYPE_CPU, nullptr); ggml_backend_t backends[2] { model.backend, model.cpu_backend }; model.sched ggml_backend_sched_new(backends, nullptr, 2, GGML_DEFAULT_GRAPH_SIZE, false, true);ggml_backend_load_all()include/ggml-backend.h#L259加载编译期启用的全部后端ggml_backend_init_best()include/ggml-backend.h#L252自动选择当前环境下最合适的后端例如有 CUDA 则用 CUDA否则回退 CPUggml_backend_sched_new(...)include/ggml-backend.h#L319创建后端调度器传入后端数组调度器负责把计算图中的每个节点分配到合适的后端执行op_offloadtrue表示允许算子级卸载到 GPU。5.3 计算与数据搬运compute()中使用调度器执行图并演示了主机与后端内存之间的数据搬运ggml_backend_sched_reset(model.sched); ggml_backend_sched_alloc_graph(model.sched, gf); // 在后端缓冲中为图分配内存 // 从主机内存拷贝数据到后端缓冲例如 GPU 显存 ggml_backend_tensor_set(model.a, matrix_A, 0, ggml_nbytes(model.a)); ggml_backend_tensor_set(model.b, matrix_B, 0, ggml_nbytes(model.b)); ggml_backend_sched_graph_compute(model.sched, gf); // 执行计算图[include/ggml-backend.h#L344](https://link.gitcode.com/i/a80301f5ad4f6cdebbab18d38c49e56f)执行完毕后再用ggml_backend_tensor_get(result, out_data.data(), 0, ggml_nbytes(result))把结果从后端内存拷回主机端打印。与simple-ctx不同simple-backend创建张量时no_alloc trueexamples/simple/simple-backend.cpp 中params0.no_alloc true即张量数据不落在上下文缓冲区而是由调度器在后端缓冲中统一分配这正是计算与存储解耦的现代用法。include/ggml-backend.h头文件同样给出了基于调度器的典型多后端使用流程注释ggml_backend_sched_new→ggml_backend_sched_graph_compute与示例代码一一对应。最后通过ggml_backend_sched_free、ggml_backend_free依次释放调度器与各后端。5.4 调度器背后的价值从ggml-backend的设计可以看出ggml的Broad backend support并非简单地把整个图塞进某个设备而是通过调度器按节点粒度分配图中有 GPU 友好的算子如矩阵乘法、卷积与 CPU 友好或仅 CPU 支持的算子调度器自动决定各节点在哪个后端执行必要时在设备间搬运数据。这为上层框架如 llama.cpp提供了统一的跨设备执行抽象而无需关心每个算子的具体设备实现。仓库 tests/test-backend-ops.cpp 正是围绕这一抽象对同一组算子在不同后端上做一致性验证。六、模型文件与生态GGUF 与更多示例6.1 GGUFggml 生态的模型文件格式ggml配套的模型文件格式为GGUF详见 docs/gguf.md它是 GGML、GGMF、GGJT 三个历史格式的后继者设计目标包括单文件部署无需任何外部附加文件即可加载完整模型可扩展以键值对元数据取代旧格式的无类型值列表新增元数据不会破坏旧模型的兼容性mmap友好张量按general.alignment未指定时默认 32 字节对齐可直接用mmap快速加载信息完备加载模型所需的全部信息架构、超参数、词表、张量信息都包含在文件内跨架构支持GGUF v3 起支持大端序。GGUF 文件结构依次为gguf_header_t魔数GGUF、版本号、张量数量、元数据键值对数量、tensor_infos每个张量的名字、维度、类型、数据偏移、对齐填充以及tensor_data各张量权重数据。模型通常先用 PyTorch 等框架训练再通过转换脚本仓库 examples 下各示例目录中的convert-*.py例如 examples/gpt-2/convert-h5-to-ggml.py转为 GGUF 供 ggml 推理使用。GGUF 还定义了标准的文件名命名约定[Sidecar]BaseNameSizeLabelFineTuneVersionEncodingTypeShard.gguf例如Mixtral-8x7B-v0.1-KQ2.gguf8 个专家的 7B 模型v0.1KQ2 编码与Grok-100B-v1.0-Q4_0-00003-of-00009.gguf第 3 个分片共 9 个便于人眼快速识别模型的关键信息。6.2 仓库中的更多示例仓库 examples 下提供了从入门到完整的真实模型示例examples/simple矩阵乘法本文主题适合入门examples/gpt-2GPT-2 的四种实现变体main-ctx.cpp、main-alloc.cpp、main-backend.cpp、main-sched.cpp、main-batched.cpp分别演示上下文、分配器ggml-alloc、后端、调度器与批处理编程模式并附quantize.cpp模型量化工具examples/gpt-jGPT-J 推理示例examples/mnistMNIST 手写数字识别包含mnist-train.cpp训练程序与 CNN/全连接两种 Python 训练脚本examples/samSAM 图像分割模型推理examples/yoloYOLOv3-tiny 目标检测支持通过yolo-image.cpp对图片进行检测examples/magika文件类型识别示例。这些示例均通过 examples/CMakeLists.txt 纳入构建GGML_BUILD_EXAMPLES开启时随标准构建流程一并产出。七、总结与进一步阅读通过本文可以掌握 ggml 的核心使用路径构建cmake .. cmake --build . --config Release -j 8按需通过-DGGML_CUDAON等选项启用目标后端编程模型ggml_init创建上下文 →ggml_new_tensor_*创建张量 → 算子组合 →ggml_new_graphggml_build_forward_expand构建计算图 →ggml_graph_compute_with_ctx执行矩阵乘法约定ggml_mul_mat(A, B)中 B 按转置传入输出也是转置结果利于 SIMD 优化多后端通过ggml_backend_init_bestggml_backend_sched_new建立调度器按节点粒度自动分配 CPU/GPU 执行生态衔接模型以 GGUF 格式单文件分发配合各示例的转换脚本即可把主流框架模型接入 ggml 推理。若想进一步深入推荐按顺序阅读examples/simple 的完整注释代码、examples/gpt-2 的四种编程模式变体、docs/gguf.md 的格式规范以及 include/ggml.h 头文件顶部的详细设计说明其中包含完整的自动微分用法示例与张量内存布局说明。【免费下载链接】ggmlTensor library for machine learning项目地址: https://gitcode.com/GitHub_Trending/gg/ggml创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

ggml 机器学习张量库快速入门：从源码构建到矩阵乘法与多后端计算

相关推荐

专科生AIGC工具对比：千笔与知文AI教学实测

DeepSeek V4.1 Flash落地踩坑实录：API校验、DSH工具链与多模态断点全解析

惠普Tank 1005打印机ER-08报错解析与解决方案

更多资讯

OpenClaw智能体安全实践：从部署到权限管理的完整防翻车指南

阿基米德优化算法在路径规划中的应用与原理

从Demo到生产：企业级Agent平台的核心能力与实践解析

基于光流法与MATLAB的视频关键帧提取方法与实践

用SBC2332替代西门子HMI：本地人机界面与PLC通讯实战指南

Qwen3-Coder 评测仓库实战：深度解读 DevQualityEval v0.5.0 的 Mixtral 8x7B Instruct 评测报告

今日更新

51单片机开环控制磁阻传感器的硬件匹配与代码实现

AI Agent安全操作数据库：SQL注入防御与参数化查询实战

Android逆向实战：还原激励类App签到接口的签名算法

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？