Programming on kenji.blog

Microsoft.Windows.AI最新API应用案例与示例代码

Fri, 11 Sep 2026 18:00:00 +0900

Microsoft.Windows.AI最新API应用案例与示例代码：探索Windows Copilot Runtime的深渊

1. 引言：AI原生融入Windows的新时代

近年来，AI技术的发展日新月异，正从基于云端的大型语言模型（LLM）应用，快速向边缘设备（本地PC）上的AI推演发生范式转变。在这一过程中起核心作用的，正是Microsoft为Windows 11提供的“Windows Copilot Runtime”以及用于操作它的“Microsoft.Windows.AI”API。

利用云端API（如OpenAI或Azure OpenAI等）开发应用程序虽然容易，但始终伴随着延迟、隐私以及持续性成本等问题。另一方面，通过在本地运行AI模型，数据无需离开设备即可确保机密性，并能实现离线可用的超低延迟应用。

本文将针对未来Windows应用开发中必不可少的本地AI功能实现方法，结合C#和C++的实战示例代码，从架构到性能调优进行极为详细的全面解析。我们不仅停留在简单调用API的层面，还会深入探讨背后硬件（NPU或GPU）的利用、与DirectML的协同等高级技术细节。

2. Windows Copilot Runtime与架构全貌

Windows Copilot Runtime是一套AI技术栈，旨在让开发者能够轻松在Windows上集成AI模型，并发挥出最高性能。该运行时在操作系统层面抽象了硬件加速，并为开发者提供了统一的接口。

graph TD App["Windows应用程序 (C# / C++)"] --> API["Microsoft.Windows.AI APIs"] App --> ORT["ONNX Runtime"] API --> WCR["Windows Copilot Runtime (操作系统层)"] WCR --> SLM["本地模型 (Phi-Silica等)"] ORT --> DML["DirectML执行提供程序 (Execution Provider)"] SLM --> DML DML --> DXCore["DXCore / DirectX 12"] DXCore --> NPU["NPU (神经网络处理单元)"] DXCore --> GPU["GPU (图形处理单元)"] DXCore --> CPU["CPU"]

如上述架构图所示，应用程序通过使用高级的 Microsoft.Windows.AI API，可以直接访问内置于操作系统的较小规模语言模型（SLM：如Phi-Silica等）。此外，如果使用自定义模型，也可以通过ONNX Runtime和DirectML显式地利用硬件加速。操作系统层会优化工作负载在CPU、GPU和NPU之间的分配，因此开发者无需深入关注硬件差异，即可构建高性能的AI应用。

3. 硬件加速与NPU的数学评估

最新的Copilot+ PC搭载了专为AI处理而设计的处理器——NPU（Neural Processing Unit）。NPU的性能通常以TOPS（Tera Operations Per Second，每秒万亿次运算）来评估。

在AI模型推理中，特别是矩阵乘法（GEMM: General Matrix Multiply）的计算能力决定了吞吐量。硬件的理论最大性能 $P_{\text{peak}}$ 可以通过以下公式估算。

$$ P_{\text{peak}} = f \times N_{\text{cores}} \times N_{\text{MACs/core}} \times 2 $$

这里：

$f$ 是NPU的时钟频率（Hz）
$N_{\text{cores}}$ 是NPU内的核心数
$N_{\text{MACs/core}}$ 是每核心的MAC（Multiply-Accumulate，乘加）单元数
最后的 $2$ 是因为1次MAC运算包含了乘法和加法两个操作（FLOPs/OPs）。

例如，对于频率为1.5GHz、4核心、每核拥有4096个MACs的NPU，

$$ P_{\text{peak}} = 1.5 \times 10^9 \times 4 \times 4096 \times 2 \approx 49.15 \text{ TOPS} $$

这就从数学上证明了其性能足以满足Windows 11对于Copilot+ PC的40 TOPS的要求。

此外，AI模型尤其是LLM的推理（解码阶段）往往会受限于内存带宽（Memory-Bound）。系统内存的理论带宽 $BW$ 计算如下。

$$ BW = f_{\text{mem}} \times W_{\text{bus}} \times \frac{2}{8} $$

如果是LPDDR5x-8533内存（$f_{\text{mem}} = 8533 \text{ MT/s}$）、128位总线（$W_{\text{bus}} = 128$），其带宽约为 $136 \text{ GB/s}$。在AI应用的优化中，如何节约这些带宽是至关重要的，这也是后文将提到的模型量化（Quantization）不可或缺的原因。

4. 开发环境搭建

要使用最新的Windows AI API，必须配置以下环境与工具链。

操作系统: Windows 11 版本 24H2 或更高版本（强烈推荐满足Copilot+ PC要求、搭载NPU的设备）
SDK: Windows App SDK (v1.5或以上，支持AI扩展版本)
开发环境: Visual Studio 2022 (v17.10或更高)，安装C++桌面开发工作负载与.NET桌面开发工作负载
包管理: 通过NuGet安装 Microsoft.Windows.AI 和 Microsoft.ML.OnnxRuntime.DirectML

1
2
3
4
5
6


<!-- .csproj 配置示例 -->
<ItemGroup>
 <PackageReference Include="Microsoft.Windows.AI" Version="1.0.0-preview1" />
 <PackageReference Include="Microsoft.WindowsAppSDK" Version="1.5.240311000" />
 <PackageReference Include="Microsoft.ML.OnnxRuntime.DirectML" Version="1.17.1" />
</ItemGroup>

5. 【深度解析 1】使用C#调用本地语言模型（Phi-Silica）

Windows Copilot Runtime内置了由Microsoft开发的高效小规模语言模型“Phi-Silica”作为操作系统的标准组件。借此，无需从网络下载以GB计的模型，即可在离线环境下实现高级的自然语言处理（文章摘要、代码生成、聊天机器人）。

以下是使用 Microsoft.Windows.AI.Generative 命名空间在C#中构建聊天AI的高级示例代码。该代码支持流式响应（Streaming Response），可以在不阻塞UI线程的情况下实时生成文本。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84


using System;
using System.Text;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Windows.AI.Generative;

namespace WindowsAI.Sample
{
 public class LocalLanguageModelService
 {
 private LanguageModel _languageModel;
 private bool _isInitialized = false;

 /// <summary>
 /// 执行语言模型的初始化。检查NPU的可用性，并将模型加载到最优设备上。
 /// </summary>
 public async Task InitializeAsync()
 {
 if (_isInitialized) return;

 Console.WriteLine("正在检查本地AI模型（Phi-Silica）的系统要求与可用性...");

 // 检查模型在系统上是否可用 (如果不兼容可能会提示下载)
 var availability = await LanguageModel.CheckAvailabilityAsync();
 if (availability != LanguageModelAvailability.Available)
 {
 throw new InvalidOperationException($"当前无法使用本地AI模型。状态: {availability}");
 }

 // 创建模型实例（此时将映射到内存空间并初始化NPU）
 _languageModel = await LanguageModel.CreateAsync();
 _isInitialized = true;

 Console.WriteLine("语言模型初始化完成。已激活通过DirectML的硬件加速。");
 }

 /// <summary>
 /// 接收用户提示词，并以流式生成响应。
 /// </summary>
 public async Task GenerateResponseStreamAsync(string prompt, CancellationToken cancellationToken)
 {
 if (!_isInitialized) await InitializeAsync();

 Console.WriteLine($"\n[用户输入]: {prompt}\n[AI助手]: ");

 // 设置生成时的超参数
 var options = new LanguageModelOptions
 {
 Temperature = 0.7f,
 TopP = 0.9f,
 MaxTokens = 2048,
 RepetitionPenalty = 1.1f
 };

 // 构建对话上下文
 var context = new LanguageModelContext();
 context.AddSystemMessage("你是一个直接运行在Windows本地NPU上的高级AI助手。请逐步进行逻辑思考，并简明扼要地回答。");
 context.AddUserMessage(prompt);

 try
 {
 // 调用流式推理API
 var responseStream = _languageModel.GenerateResponseStreamAsync(context, options);

 // 异步迭代作为IAsyncEnumerable返回的块(chunk)
 await foreach (var chunk in responseStream.WithCancellation(cancellationToken))
 {
 // 将生成的token（块）实时输出到控制台
 // 如果是UI应用，可在此使用DispatcherQueue将其反映到TextBox等控件中
 Console.Write(chunk.Text);
 }
 Console.WriteLine();
 }
 catch (OperationCanceledException)
 {
 Console.WriteLine("\n[用户或系统已取消生成]");
 }
 catch (Exception ex)
 {
 Console.WriteLine($"\n[发生致命错误: {ex.Message}]");
 }
 }
 }
}

5.1 C#实现中的架构解析

这段代码的核心在于通过 LanguageModel.CheckAvailabilityAsync() 进行执行前验证，以及通过 GenerateResponseStreamAsync 实现异步流式处理。在操作系统后台运行的Copilot Runtime接收到此API调用后，会在内部启动ONNX Runtime，并根据系统配置选择最优的执行提供程序（Execution Provider，在许多最新的PC上是DirectML + NPU）。

开发者完全不需要考虑模型的张量形状、分词器（Tokenizer）实现、KV Cache的内存管理等问题，仅用几行C#代码就能将最前沿的AI推理流水线集成到应用程序中。

6. 【深度解析 2】通过C++与DirectML实现自定义模型的高速推理

当处理操作系统标准语言模型无法覆盖的特定领域（如自定义的图像分割、语音识别、自定义目标检测模型等）时，开发者需要直接操作位于 Microsoft.Windows.AI 底层的ONNX Runtime和DirectML。

使用C++可以将内存分配优化到极限，并激发NPU/GPU的峰值性能。以下是使用DirectML在C++中执行ONNX格式自定义模型（例如：YOLOv8）的高级初始化与推理流水线的核心实现。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99


#include <iostream>
#include <vector>
#include <string>
#include <stdexcept>
#include <onnxruntime_cxx_api.h>
#include <dml_provider_factory.h>

class CustomVisionAIProcessor {
private:
 Ort::Env env;
 Ort::Session session{nullptr};
 Ort::AllocatorWithDefaultOptions allocator;

public:
 CustomVisionAIProcessor(const std::wstring& modelPath)
 : env(ORT_LOGGING_LEVEL_WARNING, "VisionAIProcessor") {

 Ort::SessionOptions sessionOptions;
 // 线程数优化
 sessionOptions.SetIntraOpNumThreads(1);
 // 将图优化级别设为最大
 sessionOptions.SetGraphOptimizationLevel(GraphOptimizationLevel::ORT_ENABLE_ALL);

 // 1. 添加 DirectML Execution Provider (DML EP)
 // device_id = 0 是系统默认推荐适配器（NPU或高性能GPU）
 const OrtApi& ortApi = Ort::GetApi();
 OrtDmlApi* dmlApi = nullptr;
 OrtStatus* status = ortApi.GetExecutionProviderApi("DML", ORT_API_VERSION, reinterpret_cast<void**>(&dmlApi));

 if (status == nullptr && dmlApi != nullptr) {
 Ort::ThrowOnError(dmlApi->SessionOptionsAppendExecutionProvider_DML(sessionOptions, 0));
 std::cout << "[Info] 已成功附加 DirectML Execution Provider。" << std::endl;
 } else {
 std::cerr << "[Warning] 获取 DirectML API 失败。将以 CPU 回退模式运行。" << std::endl;
 if (status != nullptr) ortApi.ReleaseStatus(status);
 }

 // 2. 加载模型并创建会话
 try {
 session = Ort::Session(env, modelPath.c_str(), sessionOptions);
 std::cout << "[Info] 成功加载ONNX模型，并编译了计算图。" << std::endl;
 } catch (const Ort::Exception& e) {
 std::cerr << "[Error] 模型加载失败: " << e.what() << std::endl;
 throw;
 }
 }

 void RunInference(const std::vector<float>& imageTensor, const std::vector<int64_t>& inputShape) {
 // 3. 创建输入张量的缓冲区
 Ort::MemoryInfo memoryInfo = Ort::MemoryInfo::CreateCpu(OrtArenaAllocator, OrtMemTypeDefault);
 Ort::Value inputTensor = Ort::Value::CreateTensor<float>(
 memoryInfo,
 const_cast<float*>(imageTensor.data()),
 imageTensor.size(),
 inputShape.data(),
 inputShape.size()
 );

 // 4. 动态获取输入输出节点名称
 auto inputNamePtr = session.GetInputNameAllocated(0, allocator);
 auto outputNamePtr = session.GetOutputNameAllocated(0, allocator);
 const char* inputNames[] = { inputNamePtr.get() };
 const char* outputNames[] = { outputNamePtr.get() };

 // 5. 执行推理 (将通过DirectML卸载到NPU/GPU)
 std::cout << "[Info] 开始执行推理引擎..." << std::endl;
 auto startTime = std::chrono::high_resolution_clock::now();

 auto outputTensors = session.Run(Ort::RunOptions{nullptr}, inputNames, &inputTensor, 1, outputNames, 1);

 auto endTime = std::chrono::high_resolution_clock::now();
 auto duration = std::chrono::duration_cast<std::chrono::milliseconds>(endTime - startTime);

 // 6. 获取并解析结果张量
 float* outputData = outputTensors.front().GetTensorMutableData<float>();
 size_t outputSize = outputTensors.front().GetTensorTypeAndShapeInfo().GetElementCount();

 std::cout << "[Result] 推理完成: " << duration.count() << " ms" << std::endl;
 std::cout << "[Result] 输出张量的元素数量: " << outputSize << std::endl;
 // ※此后将对输出张量实现NMS（非极大值抑制）及绘制边界框等处理
 }
};

int main() {
 try {
 // 要执行的ONNX模型路径
 CustomVisionAIProcessor processor(L"models/yolov8n_quantized.onnx");

 // 推理用的虚拟图像数据 (批大小1 x 3通道 x 640 x 640)
 std::vector<int64_t> inputShape = {1, 3, 640, 640};
 std::vector<float> dummyImage(1 * 3 * 640 * 640, 0.5f);

 processor.RunInference(dummyImage, inputShape);
 } catch (const std::exception& e) {
 std::cerr << "程序异常终止: " << e.what() << std::endl;
 return -1;
 }
 return 0;
}

6.1 C++中的内存管理与零拷贝（Zero-Copy）推理的重要性

在C++中使用DirectML的最大优势在于能够与DirectX 12 (DX12) 进行紧密集成。上述代码出于教学目的，包含了标准CPU内存的数据拷贝，但在实际的游戏引擎或视频处理应用中，很多时候我们已经通过DX12将图像（纹理）保留在GPU或NPU的内存空间上了。

在这种情况下，可以利用 OrtDmlApi 的高级绑定功能，将DX12资源直接映射为ONNX Runtime的张量，从而实现“零拷贝推理 (Zero-Copy Inference)”。这彻底消除了PCIe总线间的数据传输开销（即消耗前文提到的带宽 $BW$），能够极大提升实时视频处理的帧率。

7. 性能优化与最佳实践

在使用Windows AI API和DirectML开发顶级AI应用时，以下是必不可少的优化策略总结。

7.1 模型量化 (Quantization) 与 Olive Toolkit

要发挥NPU的真正实力，将AI模型的权重和激活从FP32（单精度浮点数）**量化（Quantize）**为INT8或INT4是绝对前提。NPU的架构专为整数运算优化，与FP32相比，INT8理论上能实现4倍的吞吐量，并大幅节省功耗。

使用Microsoft提供的 Olive (ONNX Live) 工具链，可以将PyTorch等模型针对Windows环境进行自动优化。Olive强力支持对Transformer模型的特殊注意力优化以及针对不同硬件的图编译。

7.2 批处理 vs 交互式流的权衡

在API调用中，将多个推理请求汇总进行批处理，可以提高NPU的利用率（Compute Utilization）。然而，在聊天机器人等交互式UI中，影响用户体验（UX）的决定性因素往往不是吞吐量，而是显示第一个token所需的时间（TTFT: Time To First Token）。因此，对于交互式UI，最佳实践是将批量大小设置为1，并优先考虑流式生成设计。

7.3 与后台任务及操作系统的协同

AI推理会大量消耗本地电力和系统资源。应用应与Windows的 App Lifecycle API 协同，当应用程序转入后台时，需实现暂停（Suspend）低优先级的推理任务或限制资源消耗的机制。

sequenceDiagram participant User as "用户" participant App as "Windows应用 (C#)" participant API as "Microsoft.Windows.AI" participant OS as "Windows Copilot Runtime" participant ORT as "ONNX Runtime (DML)" participant NPU as "NPU硬件" User->>App: "输入提示词" App->>API: "GenerateResponseStreamAsync()" API->>OS: "分派推理作业" OS->>ORT: "计算图执行请求" ORT->>NPU: "通过DirectML执行命令列表" NPU-->>ORT: "计算完成（生成1个token）" ORT-->>OS: "张量结果" OS-->>API: "已解码的文本" API-->>App: "IAsyncEnumerable 数据块" App-->>User: "向UI实时绘制字符" Note over ORT,NPU: "在完成前高速重复此循环"

该序列图展示了在毫不阻塞UI线程的情况下，数据从最底层的NPU硬件如流水般传输至应用的展示层，呈现了异步处理的美感。

8. 未来展望与Windows AI的进化

Microsoft.Windows.AI API与Copilot Runtime目前正处于快速演进之中。在面向开发者的未来更新中，预计将出现以下范式转变：

多模态API的系统原生集成：不仅是文本，还将在操作系统级别原生提供对语音、图像乃至实时视频流的无缝同步处理及跨模态AI推理。
系统级RAG（检索增强生成）支持：在操作系统安全沙盒内，将本地PC中的个人文档和Windows Search索引与AI模型协同，构建在完全保护用户隐私下的超高级个人AI助手。
NPU资源动态伸缩：当多个AI应用（例如后台运行的降噪和前台运行的代码生成）同时运行时，Windows内核调度程序将动态切换NPU的执行上下文，以保证服务质量（QoS）。

9. 结论：本地AI正在改变应用的未来

Windows 11的Copilot Runtime和 Microsoft.Windows.AI API为所有Windows开发者带来了一件极为强大的武器——“本地AI”。我们再也不必完全依赖云端API了。现在可以消除延迟，坚守隐私，为用户提供哪怕在离线状态下也能完美运行的下一代AI体验。

请活用本文所讲解的利用C#集成系统标准语言模型的知识、数学层面的性能评估，以及通过C++与DirectML进行的极限硬件优化，亲手创造次世代的“AI原生”Windows应用。AI带来的无限可能，就在你编写的代码的前方。

※注意事项：本文是基于2026年9月当前的预览版API及最新规范撰写。由于Windows更新可能会更改API规范或硬件要求，在实际应用时，请务必参考Microsoft Learn的官方文档。

无需Python！仅用C++构建AI推理引擎

Fri, 11 Sep 2026 17:00:00 +0900

1. 引言：为什么要抛弃Python，用C++构建AI推理引擎？

在现代AI开发中，Python是事实上的标准。得益于PyTorch和TensorFlow等强大的框架，只需几行代码就能构建、训练和推理复杂的神经网络。然而，在这些框架的背后，是C++和CUDA等底层语言在承担着繁重的计算处理。Python只不过是发挥了“胶水（Glue）”的作用。

那么，为什么非要排除Python，单独使用C++来构建AI推理引擎呢？这有几个强有力的理由。

极致的性能和低延迟: 可以完全消除Python的GIL（全局解释器锁）和动态类型带来的开销。特别是在需要实时性的系统中，毫秒级的延迟是致命的。
部署的便利性: 在最终用户的环境中构建Python环境（庞大的库、依赖地狱）非常困难。如果是C++，只需分发静态链接的单个可执行二进制文件（.exe或ELF二进制）即可。
支持边缘设备: 在智能手机、嵌入式设备、Raspberry Pi等资源受限的环境中，没有余力运行消耗数GB内存的Python运行时。
硬件的直接控制: 内存分配的时机、显式使用SIMD指令、优化与GPU的内存传输等底层控制，在C++中是可以实现的。

本文深受Georgi Gerganov开发的“GGML”库架构的启发，将深入技术深渊，解说如何从零开始仅使用C++构建运行大型语言模型（LLM）等推理引擎的过程。

2. 推理引擎的架构全貌

AI的推理处理本质上是“巨大的矩阵计算的连续”。为了高效执行这一操作，推理引擎需要由以下组件构成。

graph TD A["输入数据 (Tokens/Images)"] --> B["张量管理 (Tensor Management)"] B --> C["计算图 (DAG)"] C --> D["内存分配池与分配器 (Memory Arena & Allocator)"] C --> E["调度器与线程池 (Scheduler & Thread Pool)"] E --> F["CPU后端 (AVX2/ARM NEON)"] E --> G["GPU后端 (CUDA/Metal)"] F --> H["输出结果 (Output Results)"] G --> H

张量（Tensor）管理: 管理多维数组的数据结构和各个维度的步长（Stride）。
计算图（Computation Graph）: 将神经网络各层的运算表示为有向无环图（DAG）。
内存分配池（Memory Arena）: 预先分配型内存管理机制，以避免动态内存分配（malloc或new）的开销。
后端（Backend）: 针对CPU或GPU等特定硬件优化的运算实现（内核）。

我们将利用C++的强大功能（模板、指针运算、RAII等）来组装这些组件。

3. 内存管理的奥秘：内存分配池与SIMD对齐

推理引擎中的内存管理是直接影响性能的最重要因素之一。在推理过程中，特别是在通过Transformer模型的各层时，会生成大量的中间张量。如果每次都使用标准的malloc来分配和释放，堆的碎片化和操作系统的上下文切换将导致致命的速度下降。

因此，我们采用“内存分配池（Memory Arena）”的方法。这是一种在推理开始时计算（或固定）所需的最大内存量并一次性分配，之后仅通过递增指针来切分内存的手法。

3.1 对齐的重要性

现代CPU支持SIMD（单指令多数据流）指令。如Intel/AMD的AVX2/AVX-512，以及ARM的NEON等。这些指令能够一次处理256位（32字节）或512位（64字节）的数据，但处理目标的数据内存必须在特定的字节边界（通常是32字节或64字节）对齐（Alignment）。

以下是考虑了对齐的内存分配池的C++实现示例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


#include <cstdint>
#include <cstddef>
#include <stdexcept>
#include <iostream>

struct MemoryArena {
 size_t size;
 size_t offset;
 uint8_t* data;

 MemoryArena(size_t size) : size(size), offset(0) {
 // POSIX系统使用 posix_memalign，Windows使用 _aligned_malloc
#ifdef _WIN32
 data = static_cast<uint8_t*>(_aligned_malloc(size, 64));
#else
 if (posix_memalign(reinterpret_cast<void**>(&data), 64, size) != 0) {
 throw std::bad_alloc();
 }
#endif
 }

 ~MemoryArena() {
#ifdef _WIN32
 _aligned_free(data);
#else
 free(data);
#endif
 }

 void* allocate(size_t bytes, size_t alignment = 64) {
 // 计算对齐（求填充字节）
 size_t pad = (alignment - (offset % alignment)) % alignment;
 if (offset + pad + bytes > size) {
 throw std::runtime_error("OOM: MemoryArena out of memory");
 }
 offset += pad;
 void* ptr = data + offset;
 offset += bytes;
 return ptr;
 }

 void reset() {
 offset = 0; // 释放内存只需重置指针即可（O(1)）
 }
};

这样，在创建张量时始终通过此内存分配池获取内存。在推理的每个步骤（如每次生成令牌）结束后，只需调用 reset() 就可以瞬间重用内存。

4. 张量数据结构与步长的魔法

张量是标量、向量和矩阵的广义概念。在实现中最重要的一点是，虽然实际数据在内存中是作为一维连续数组排列的，但它具有将其解释为多维的“步长（Stride）”概念。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


enum class DataType {
 FP32,
 FP16,
 INT8, // 用于量化
 INT4 // 用于量化
};

struct Tensor {
 int n_dims; // 维度数
 int64_t ne[4]; // 各维度的元素数 (Number of Elements)
 size_t nb[4]; // 各维度的步长 (Number of Bytes)
 DataType type; // 数据类型
 void* data; // 指向有效载荷的指针

 // 用于计算图
 enum OpType op;
 Tensor* src0;
 Tensor* src1;
};

步长 nb[i] 表示在维度 i 中相邻元素之间在内存上的字节距离。例如，当元素数为 $M \times N$ 的矩阵（FP32，每个元素4字节）按Row-Major（行优先）存储时，步长如下：

nb[0] = 4 (字节) ：列方向的移动
nb[1] = $N \times 4$ (字节) ：行方向的移动

利用这一点，在不伴随内存复制的情况下，只需交换步长的数值就能实现“转置（Transpose）”或“视图（View）”等操作。非常优雅且高速。

5. 计算图（DAG）的构建与延迟评估

与PyTorch等类似，我们的推理引擎也采用接近“Define-by-Run”的延迟评估（Lazy Evaluation）。也就是说，在调用运算函数时并不执行计算，而是仅构建图（节点间的依赖关系）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


Tensor* tensor_add(MemoryArena& arena, Tensor* a, Tensor* b) {
 Tensor* out = create_tensor(arena, a->type, a->n_dims, a->ne);
 out->op = OpType::ADD;
 out->src0 = a;
 out->src1 = b;
 return out;
}

Tensor* tensor_mul_mat(MemoryArena& arena, Tensor* a, Tensor* b) {
 // b 通常是已转置的
 int64_t ne[2] = { a->ne[0], b->ne[1] };
 Tensor* out = create_tensor(arena, a->type, 2, ne);
 out->op = OpType::MUL_MAT;
 out->src0 = a;
 out->src1 = b;
 return out;
}

推理处理的流程如下所示。

graph LR A["定义张量 (Define Tensors)"] --> B["通过运算构建图 (Build Graph via Ops)"] B --> C["拓扑排序 (Topological Sort)"] C --> D["为输出分配内存 (Allocate Memory for Outputs)"] D --> E["按顺序执行节点 (Execute Nodes In Order)"]

在评估图（前向传递）时，使用拓扑排序从没有依赖关系的节点开始依次执行处理。由于仅进行推理，不需要保留用于反向传播的梯度，因此内存管理变得非常简单。

6. 数学与优化的核心：矩阵乘法 (GEMM)

AI推理计算量的90%以上都花费在矩阵乘法（GEMM: General Matrix Multiply）上。Transformer模型核心的注意力机制和前馈网络（FFN），归根结底都是巨大的矩阵乘积。

两个矩阵 $A$ (大小为 $M \times K$) 和 $B$ (大小为 $K \times N$) 的乘积 $C = A B$ (大小为 $M \times N$) 用公式表示如下。

$$ C_{i,j} = \sum_{k=0}^{K-1} A_{i,k} \cdot B_{k,j} $$

如果用朴素的三重循环来实现这个公式，会频繁发生缓存未命中，毫无性能可言。

6.1 CPU上的缓存分块与SIMD优化

在CPU上加速GEMM的基本策略如下：

循环分块（缓存分块）: 将矩阵分割成能够放入L1/L2缓存的小块来进行计算。
数据打包: 内部重新排列数据，使内存访问模式连续。
利用SIMD: 使用AVX-512中如 _mm512_fmadd_ps 这样的FMA（融合乘加）指令，在一个时钟周期内完成大量的乘加运算。

以下是使用C++和SIMD Intrinsics实现的简化向量内积（Dot Product）示例。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


#include <immintrin.h> // 用于AVX指令

// 使用AVX2的FP32高速内积
float dot_product_avx2(const float* a, const float* b, int n) {
 __m256 sum256 = _mm256_setzero_ps();
 int i = 0;

 // 一次处理8个元素（256位 = 32字节 = 8 * 4字节）
 for (; i <= n - 8; i += 8) {
 __m256 va = _mm256_loadu_ps(a + i);
 __m256 vb = _mm256_loadu_ps(b + i);
 // FMA指令: sum256 = va * vb + sum256
 sum256 = _mm256_fmadd_ps(va, vb, sum256);
 }

 // 将SIMD寄存器内的值水平相加
 float result[8];
 _mm256_storeu_ps(result, sum256);
 float dot = result[0] + result[1] + result[2] + result[3] +
 result[4] + result[5] + result[6] + result[7];

 // 处理剩余部分
 for (; i < n; ++i) {
 dot += a[i] * b[i];
 }
 return dot;
}

仅凭这一点小小的巧思，就能获得比朴素实现快几倍至十几倍的速度提升。

7. 跨越硬件壁垒：CUDA与Metal后端的集成

虽然纯C++实现在CPU上能跑得还凑合，但要在实际可用的速度（例如：每秒生成20个令牌以上）下运行LLM等庞大的模型，GPU的并行计算能力是不可或缺的。因此，我们要在引擎中引入后端抽象层。

7.1 后端抽象

利用C++的多态性，使运算执行器（Executor）可以被切换。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


class Backend {
public:
 virtual ~Backend() = default;
 virtual void alloc_buffer(Tensor* t) = 0;
 virtual void free_buffer(Tensor* t) = 0;
 virtual void copy_to_device(Tensor* t) = 0;
 virtual void copy_to_host(Tensor* t) = 0;

 // 各类运算的执行
 virtual void compute_add(Tensor* src0, Tensor* src1, Tensor* dst) = 0;
 virtual void compute_mul_mat(Tensor* src0, Tensor* src1, Tensor* dst) = 0;
};

7.2 NVIDIA CUDA 后端实现

为了充分利用NVIDIA的GPU，我们使用CUDA C++扩展来实现后端。虽然可以编写自己的内核，但对于矩阵乘法来说，利用NVIDIA提供的顶级库“cuBLAS”是最好的选择。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


#include <cublas_v2.h>
#include <cuda_runtime.h>

class CUDABackend : public Backend {
private:
 cublasHandle_t handle;

public:
 CUDABackend() {
 cublasCreate(&handle);
 }

 ~CUDABackend() {
 cublasDestroy(handle);
 }

 void compute_mul_mat(Tensor* src0, Tensor* src1, Tensor* dst) override {
 // CUDA默认是Column-Major，因此参数需要注意
 const float alpha = 1.0f;
 const float beta = 0.0f;

 int m = src0->ne[0];
 int k = src0->ne[1];
 int n = src1->ne[1]; // 前提是 src1 已转置

 cublasSgemm(handle, CUBLAS_OP_T, CUBLAS_OP_N,
 m, n, k,
 &alpha,
 (const float*)src0->data, k,
 (const float*)src1->data, k,
 &beta,
 (float*)dst->data, m);
 cudaDeviceSynchronize();
 }
};

由于CUDA内存和主机（CPU）内存之间的数据传输（cudaMemcpy）开销非常大，在推理过程中，尽量将所有的权重（权重张量）和中间张量保留在VRAM上的设计变得至关重要。

7.3 Apple Silicon (Metal) 后端

近年来，Mac的M1/M2/M3芯片（Apple Silicon）作为AI推理机非常优秀。其原因在于“统一内存”。由于CPU和GPU共享同一内存区域，因此完全不需要像前面提到的CUDA那样，通过PCIe总线进行高成本的主机-设备间内存传输。

要从C++调用Metal，可以使用Objective-C++（.mm文件）作为桥梁，或者使用metal-cpp库。利用Metal的Compute Shader（在.metal文件中以类似C++的方式编写）来编写内核。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


// Metal着色器 (kernel.metal)
#include <metal_stdlib>
using namespace metal;

kernel void mul_mat_kernel(
 device const float* A [[buffer(0)]],
 device const float* B [[buffer(1)]],
 device float* C [[buffer(2)]],
 constant uint3& dims [[buffer(3)]],
 uint2 gid [[thread_position_in_grid]]
) {
 uint m = dims.x; uint k = dims.y; uint n = dims.z;
 uint row = gid.y; uint col = gid.x;

 if (row < m && col < n) {
 float sum = 0.0;
 for (uint i = 0; i < k; ++i) {
 sum += A[row * k + i] * B[i * n + col]; // 简化
 }
 C[row * n + col] = sum;
 }
}

在Apple Silicon环境下，还提供了称为MPS（Metal Performance Shaders）的矩阵乘法优化库，在实际运用中通过使用它，可以获得惊人的推理速度。

8. Transformer模型特有的处理：Attention与KV缓存

像LLaMA 2/3或GPT这样最先进的LLM是基于Transformer架构的。要在C++中实现它，必须构建以下公式表示的“缩放点积注意力 (Scaled Dot-Product Attention)”。

$$ \text{Attention}(Q, K, V) = \text{softmax}\left(\frac{QK^T}{\sqrt{d_k}}\right)V $$

另外，在自回归（Autoregressive）令牌生成中，必须保留过去令牌的计算结果（Key和Value）。这被称为“KV缓存（Key-Value Cache）”。

graph TD T["当前令牌 (Current Token)"] --> Q["查询 (Query)"] T --> K["键 (Key)"] T --> V["值 (Value)"] K --> KCache["追加到KV缓存 (Append to KV Cache)"] V --> VCache["追加到KV缓存 (Append to KV Cache)"] Q --> Dot1["Q * K_Cache^T"] KCache --> Dot1 Dot1 --> Scale["缩放 (Scale (1/sqrt(d)))"] Scale --> Softmax["Softmax"] Softmax --> Dot2["SoftmaxOut * V_Cache"] VCache --> Dot2 Dot2 --> Out["上下文向量 (Context Vector)"]

在KV缓存的内存分配方面，也要像环形缓冲区一样进行操作，预先在内存分配池中分配最大上下文长度（例如4096或8192个令牌）的内存空间。这可以防止每次生成步骤都进行重新分配。

此外，对于位置编码（Positional Encoding），将实现近年来成为主流的“RoPE（旋转位置嵌入）”。这是一种将位置信息作为复数空间中的旋转向量嵌入的方法，在C++中优化 sin 和 cos 函数的调用（如使用查找表等）是性能的关键。

9. 模型量化（Quantization）带来的极致优化

如果将大型模型（例如70亿参数的LLaMA模型）原封不动地以FP32（32位浮点数）加载，仅权重就会消耗约28GB的内存（VRAM）。再加上KV缓存和推理用的缓冲区，很容易就会超过30GB，一般的消费级GPU根本无法运行。

因此，“量化（Quantization）”就变得不可或缺了。这也是GGML格式的精髓所在。

量化是有意降低权重精度的技术。

FP16 (16位): 大小减半。精度几乎没有衰减。
INT8 (8位): 大小1/4。轻微的衰减。
INT4 (4位): 大小1/8。使用独特的分块和比例因子，可进行实用的推理。

在推理引擎端，从内存中读取被压缩为INT4（或INT8）的权重，在加载到CPU或GPU的寄存器后，立即展开（反量化）为FP16或FP32进行计算。

令人惊讶的是，即使增加了计算量，减少从内存中读取的数据量反而会更快。这是因为在现代硬件中，推理任务的瓶颈不在于“计算力（Compute Bound）”，而在于“内存带宽（Memory Bandwidth Bound）”。如果是实现了INT4量化的C++引擎，即便是8GB VRAM的MacBook Air等设备也能非常流畅地运行本地LLM。

10. 性能调优：NUMA架构与线程池

在使用CPU进行推理时，多线程化是必须的。但是，如果仅仅启动大量的 std::thread，并不能说是最优的。

在现代的多插槽服务器或如Ryzen Threadripper这样的高端CPU中，采用了**NUMA（非一致性内存访问）**架构。从某个CPU核心访问物理上较近的内存（本地内存）速度很快，但访问绑定到其他处理器的内存时，速度会急剧下降。

在高级C++推理引擎中，会充分运用以下技巧：

线程绑定（Thread Pinning）: 将每个线程固定到特定的CPU核心（设置亲和性），以防止上下文切换导致缓存失效。
感知NUMA的分配: 在处理数据的线程所在的同一NUMA节点上分配内存。
工作窃取型线程池: 将计算图的各个节点分割成细小的任务，实现空闲线程自动夺取并执行任务的高效调度器。

通过运用这些技巧，可以让CPU利用率紧贴100%，爆发出接近理论值的吞吐量。

11. 总结：用C++的“肌肉”驱动AI的乐趣

Python确实很方便。在研究开发和原型制作方面，它的生产力是任何语言都无法比拟的。但是，当我们过渡到将完成的模型“在现实世界中高效地、在各种设备上运行”这一阶段时，C++登场的时刻就到了。

直接操作内存的字节流，用SIMD指令将寄存器压榨到极限，与GPU的VRAM带宽搏斗，最终完成的推理引擎在控制台上源源不断地生成自然语言文本（令牌）——当你看到这一切时所体会到的成就感，是你在Python框架中调用 model.generate() 时绝对无法体验到的“纯粹的工程师之喜悦”。

虽然AI技术很容易成为“黑盒”，但通过用C++亲手从张量运算到内存分配编写一切，可以深刻理解LLM究竟是如何“思考”的，领悟其真正的机制。

如果你具备C++的基础知识，并对当下的AI技术有着浓厚的兴趣，请务必尝试挑战开发自己的推理引擎。GGML和llama.cpp的源代码，绝对是最好的活教材。

现在，让我们抛弃Python沉重的运行时，用C++的肌肉让最前沿的AI跑起来吧！

使用C++开发小规模AI模型（如TinyLLaMA）的步骤

Fri, 11 Sep 2026 14:00:00 +0900

使用C++开发小规模AI模型（如TinyLLaMA）的步骤

近年来，在本地环境运行大型语言模型（LLM）的关注度急剧上升。特别是像TinyLLaMA（1.1B参数）这样的小规模模型，即使在资源有限的边缘设备或普通笔记本电脑（包括Windows环境）上，也能以实用的速度进行推理。虽然使用Python和PyTorch进行开发是主流，但在追求极致性能和内存节省时，C++和基于C语言的张量库“ggml”的组合成为了事实上的标准。

本文将非常详细地讲解如何从零开始构建一个使用C++加载TinyLLaMA并进行文本生成的推理引擎（或者说，深入理解现有的llama.cpp内部结构）的开发步骤。

1. 为什么选择C++和ggml？

在AI的训练阶段，具有灵活性和丰富生态系统的Python具有压倒性的优势。然而，在部署和“推理（Inference）”阶段，基于以下理由，C++成为了强大的选择。

减少开销：可以完全消除Python的全局解释器锁（GIL）和运行时的开销。
内存效率和Arena分配：可以手动控制内存的分配和释放，从而防止垃圾回收带来的不可预测的峰值。
直接访问硬件：直接调用AVX-512、AVX2、ARM NEON等SIMD内置函数（Intrinsics），将CPU的运算能力发挥到极致。
零依赖：ggml是一个零依赖（Zero dependencies）的C/C++库，只要有编译器，即使在Windows上的MSVC环境中也很容易编译。

2. 架构全景图

整个推理流水线的流程如以下Mermaid图表所示。这是一系列从用户输入文本开始，到最终生成下一个Token为止的过程。

graph TD A["用户输入文本"] --> B["BPE 分词器"] B --> C["Token ID 数组"] C --> D["嵌入层查找"] D --> E["Transformer 块"] E --> F["RMSNorm"] F --> G["LM Head 层"] G --> H["Logits 数组"] H --> I["采样器模块"] I --> J["下一个 Token ID"] J --> K["去分词器"] K --> L["输出文本块"] J -.-> |"追加到上下文"| C

由于它是自回归模型，输出的Token会再次被添加到上下文中，作为预测下一个Token的输入进行循环（图中虚线部分）。

3. 模型格式与内存映射 (mmap)

处理庞大的神经网络权重时，最大的障碍是磁盘I/O和内存消耗。在C++实现中，通过**内存映射（mmap）**来解决这个问题。

3.1 内存映射的原理及在Windows中的实现

使用mmap，可以将文件的内容直接映射到进程的虚拟内存空间中。

零拷贝（Zero-copy）：数据直接从磁盘加载到内核的页面缓存中，不会发生向用户空间的多余拷贝。
按需加载（Page Fault）：只有当CPU实际访问该内存地址的瞬间，才会发生缺页中断（Page Fault），并且仅将需要的块（通常为4KB）加载到物理内存中。

在Windows环境中，不使用POSIX的 mmap，而是使用Win32 API的 CreateFileMapping 和 MapViewOfFile。

sequenceDiagram participant OS["Windows 操作系统"] participant RAM["物理内存"] participant App["C++ 应用程序"] App->>OS: "CreateFileMapping / MapViewOfFile" OS-->>App: "虚拟内存地址指针" App->>App: "在指针处读取张量数据" OS->>RAM: "缺页中断 / 从磁盘加载页面" RAM-->>App: "数据已准备好进行 SIMD 计算"

3.2 GGUF 格式的二进制结构

从Hugging Face等的 .safetensors 格式转换而来的 GGUF (GPT-Generated Unified Format) 是用于推理的终极格式。它具有以下严格的二进制布局：

Magic Bytes: 0x46554747 (GGUF)。
Version: 格式的版本号。
Tensor Count & Metadata Count: 张量数量和元数据的键值对数量。
Metadata (Key-Value Pairs): 带有字符串长度前缀的键和带有类型的值。
Tensor Info: 每个张量的名称、维度数、数据类型（如FP16，Q4_K等），以及在文件中的偏移位置。
Padding: 插入的填充物，用于将张量数据对齐到特定边界（通常为32字节或64字节）。这对使用SIMD指令（特别是AVX）进行高速内存访问至关重要。
Tensor Data: 已对齐的实际权重数据数组。

4. TinyLLaMA的数学基础与C++算法

TinyLLaMA为了提高效率，引入了一些高级的架构设计。为了在C++中正确实现这些，以下是它们的数学公式表示。

4.1 RMSNorm (Root Mean Square Normalization)

省略了LayerNorm中的均值中心化，仅进行方差的缩放，从而降低了计算成本。

$$ \text{RMSNorm}(x) = \frac{x}{\sqrt{\frac{1}{d}\sum_{i=1}^{d} x_i^2 + \epsilon}} \odot \gamma $$

其中 $d$ 是维度数，$\gamma$ 是训练好的缩放张量。在C++中实现时，首先使用AVX2的 _mm256_fmadd_ps 等快速计算数组的平方和，然后乘以平方根的倒数（如 _mm256_rsqrt_ps 指令）来进行优化。

4.2 RoPE (Rotary Position Embedding)

这是一种将Token的位置信息作为张量空间中的旋转（Rotate）来应用的技术。可以将其视为复平面上的旋转，对向量 $x$ 的相邻维度对 $(x_1, x_2)$ 应用以下旋转：

$$ \text{RoPE}(x, m) = \begin{pmatrix} x_{1} \cos(m\theta) - x_{2} \sin(m\theta) \\ x_{1} \sin(m\theta) + x_{2} \cos(m\theta) \end{pmatrix} $$

在这里，$m$ 是Token的绝对位置索引，$\theta$ 是预先计算好的基频。在ggml中，只需在构建推理图时添加 ggml_rope 算子即可并行执行。

4.3 Grouped-Query Attention (GQA)

在常规的多头注意力机制（MHA）中，Query、Key和Value各具有相同数量的头。然而，TinyLLaMA为了大幅减少内存带宽和KV缓存的消耗，采用了 Grouped-Query Attention (GQA)。

$$ \text{Attention}(Q, K, V) = \text{softmax}\left(\frac{Q K^T}{\sqrt{d_k}}\right) V $$

在GQA中，多个Query头共享一个Key/Value头。在C++实现中，在执行矩阵乘法 ggml_mul_mat 之前，需要根据Query的数量将KV张量进行广播（Broadcast）操作。

4.4 SwiGLU 激活函数

在前馈网络（FFN）层中，使用SwiGLU代替GELU。

$$ \text{SwiGLU}(x) = \text{Swish}(x W_{\text{gate}}) \otimes (x W_{\text{up}}) $$ $$ \text{Swish}(z) = z \cdot \sigma(z) = z \cdot \frac{1}{1 + e^{-z}} $$

在计算图中，通过组合 ggml_silu 算子和 ggml_mul 来表示。

5. 使用ggml构建计算图与内存管理

ggml采用“Define-and-Run”的方法，先构建用于推理的静态计算图，然后再进行评估（evaluate）。

5.1 ggml_context 与 Arena 分配器

ggml最独特的地方在于，推理循环内完全不进行动态内存分配（如 malloc 或 new）的“Arena 分配（Arena Allocation）”。初始化时分配一大块连续的内存区域（Arena），每次调用 ggml_new_tensor 等函数时，都会递增这个区域的指针。当完成一个推理步骤后，只需将分配指针重置到初始位置，即可立即完成下一个推理步骤的内存分配。

5.2 构建图的具体示例

在每个推理步骤中，会在内存中组装如下的计算图。

graph TD A["Token 输入 ID"] --> B["嵌入查找"] B --> C["ggml_rms_norm"] C --> D["Q / K / V 投影"] D --> E["ggml_rope 位置编码"] E --> F["KV 缓存存储"] E --> G["KV 缓存加载"] G --> H["自注意力机制"] H --> I["缩放与 Softmax"] I --> J["注意力输出"] J --> K["输出投影"] K --> L["残差连接相加"]

6. 量化 (Quantization) 与 Windows / SIMD 优化

如果用FP16处理TinyLLaMA (1.1B)，大约需要2.2GB的内存，但通过4位量化（如Q4_K），可以将其大幅压缩至约600MB左右。

6.1 块量化架构

ggml并不是对整个张量进行统一量化，而是以“块（Block）”为单位进行的。在 Q4_0 格式中，将32个FP16值组合成一个块。

缩悉因子（Scale factor）：1个FP16值（2字节）
量化数据：32个4位值（16字节）通过这种方式，将局部异常值的影响降至最低。

6.2 利用AVX2加速点积运算

当在Windows环境中为最新的x86 CPU进行编译时，可以利用 /arch:AVX2 等编译器标志，SIMD处理流程如下：

加载：将4位量化数据从内存加载到256位的AVX寄存器中。
展开与解包：通过位掩码和移位运算，将4位值展开为Int8或Int16。
反量化：乘以缩放因子，转换为浮点数。
FMA运算：使用激活值和 _mm256_fmadd_ps（融合乘加）并行执行乘累加运算。

7. KV缓存的实现细节

在自回归生成中，为了省略计算过去Token的Key和Value，必须使用“KV缓存（KV Cache）”。

在C++中实现时的要点如下：

预先分配张量：为KV缓存初始化一个能够容纳最大上下文长度（例如：2048个Token）的巨大张量（推荐使用FP16）。
偏移复制：当执行针对Token位置 $N$ 的计算时，将该步骤中得到的K和V向量使用 ggml_cpy 等方法存储到KV缓存张量的第 $N$ 行。
注意力计算时的视图（View）创建：在计算注意力时，创建一个仅指向从第0个到第 $N$ 个Token部分的“视图”，并将其传递给矩阵乘法。

8. BPE 分词器与解码

将输入字符串视为UTF-8的字节流，并与预先定义的词汇表进行匹配。在C++中，为了加速词汇表的搜索，通常会实现 Trie树（前缀树） 或使用优先队列的算法。

从LM Head输出的Logits，使用Temperature参数缩放概率，通过Top-K提取或Top-P（Nucleus Sampling）方法缩小候选范围，并使用随机数决定最终的下一个Token。

9. 搭建C++项目（Windows / PowerShell 环境）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


cmake_minimum_required(VERSION 3.14)
project(TinyLLaMACpp)

set(CMAKE_CXX_STANDARD 17)

# 面向 Windows (MSVC) 的优化和 AVX2 标志的设置
if(MSVC)
 add_compile_options(/O2 /arch:AVX2 /fp:fast)
 add_link_options(/STACK:8388608)
else()
 add_compile_options(-O3 -march=native -ffast-math)
endif()

add_library(ggml OBJECT ggml/ggml.c ggml/ggml-alloc.c)
target_compile_definitions(ggml PRIVATE GGML_USE_AVX2 GGML_USE_F16C GGML_USE_FMA)

add_executable(main main.cpp)
target_link_libraries(main ggml)

PowerShell 中的构建命令示例：

1
2
3
4


mkdir build
cd build
cmake .. -G "Visual Studio 17 2022" -A x64
cmake --build . --config Release

10. 总结

使用C++和ggml从零开始实现像TinyLLaMA这样的小规模AI模型的推理引擎，是揭开深度学习黑盒、学习底层硬件控制之美的绝佳机会。在充分体会利用内存映射进行零拷贝加载、SIMD优化、KV缓存构建等系统编程精髓的同时，让我们共同开拓边缘AI的未来。

llama.cpp使用方法与C++定制入门

Fri, 11 Sep 2026 11:00:00 +0900

近年来，大型语言模型（LLM）的进化非常迅猛，其应用范围每天都在扩大。然而，要在本地环境中运行拥有数十亿、数百亿参数的模型，通常需要配备海量显存的高端GPU。打破这种“硬件壁垒”，让在普通PC、Mac甚至像Raspberry Pi这样的设备上进行LLM的实用推理成为可能的，就是 llama.cpp。

本文不仅将介绍仅仅作为命令行工具的使用方法，还将面向工程师极其详细地解析其底层技术 ggml 的架构、Transformer与量化的数学背景，以及如何利用 C++ API 将 LLM 嵌入到自有应用程序并进行定制。

1. llama.cpp 与 ggml 概述

llama.cpp 是由 Georgi Gerganov 开发的、使用 C/C++ 编写的轻量级 LLM 推理引擎。它最初的目的是为了让 Meta 的 LLaMA 模型在 Apple Silicon (M1/M2 Mac) 上高速运行，但现在已支持各种架构和模型。

它最大的特点在于它是纯粹的 C/C++ 实现，没有外部依赖。由于不需要 Python 或 PyTorch 这种庞大的生态系统，它可以编译为单个可执行文件，因此部署极其简单。

作为 llama.cpp 核心的是张量运算库 ggml。ggml 是从零开始设计的，旨在将机器学习中的矩阵运算在 CPU（以及部分 GPU）上优化到极致。

1.1 为什么 llama.cpp 这么快？

利用内存映射 (mmap)：在将模型权重加载到内存时，利用操作系统的 mmap，可以避免全部加载到 RAM 中，实现快速启动并节省内存。
彻底的 SIMD 指令优化：利用 AVX2, AVX-512, ARM NEON, Apple AMX 等 CPU 特有的指令集，实现了矩阵乘法的超高速化。
量化 (Quantization)：将 16-bit 浮点数 (FP16) 的权重压缩为 4-bit, 5-bit, 8-bit 的整数，从而消除内存带宽的瓶颈（详情后述）。

2. 数学背景: Transformer 与量化 (Quantization)

为了深入理解 llama.cpp，有必要了解它计算的数学公式，以及它是如何对计算进行近似的。

2.1 Transformer 的推理过程

LLaMA 等模型采用了自回归 (Auto-regressive) 的 Transformer 解码器架构。文本生成的核心是 Self-Attention（自注意力）机制。

对于作为输入的隐藏状态矩阵 $X \in \mathbb{R}^{N \times d}$，Query $Q$、Key $K$、Value $V$ 是通过与权重矩阵相乘计算得出的。

$$ Q = X W_Q, \quad K = X W_K, \quad V = X W_V $$

这里，Attention 的输出定义如下：

$$ \text{Attention}(Q, K, V) = \text{softmax}\left(\frac{QK^T}{\sqrt{d_k}}\right)V $$

在 llama.cpp 的推理循环中，成为瓶颈的是这些巨大的矩阵 $W_Q, W_K, W_V$ 以及前馈神经网络 (FFN) 的权重矩阵与向量 $X$（在生成阶段因为一次只处理一个 Token，所以 $N=1$）的乘积，也就是 GEMV (General Matrix-Vector Multiplication)。

2.2 量化 (Quantization) 的数学基础

在内存访问带宽成为瓶颈的推理过程中，使用较少位数来表示权重参数的量化是必不可少的。下面说明在 llama.cpp 中被广泛使用的块级量化（例如 Q4_K 或 Q4_0）的基本原理。

例如，考虑 FP16 权重矩阵 $W$ 的一部分，长度为 $B$（通常为 32 或 64）的块 $w = [w_1, w_2, \dots, w_B]$。我们将这个块近似表示为一个 4-bit 整数 $q_i \in [-8, 7]$ 与一个单一的缩放因子 $\Delta$（FP16 或 FP32）的乘积。

$$ w_i \approx \Delta \times q_i $$

$\Delta$ 是根据块内的最大绝对值决定的。

$$ \Delta = \frac{\max_i |w_i|}{7} $$

使用量化后的权重计算点积 $y = w \cdot x$ 时，将输入向量 $x$ 也进行同样的量化 $x_i \approx \Delta_x \times q_{x, i}$，可得：

$$ y = \sum_{i=1}^{B} w_i x_i \approx \Delta \Delta_x \sum_{i=1}^{B} q_i q_{x, i} $$

这其中的 $\sum q_i q_{x, i}$ 部分就变成了纯粹的整数运算，可以使用 SIMD 指令非常高速地进行并行计算。这就是 llama.cpp 在 CPU 上创造出惊人速度的数学奥秘。

3. 架构与推理流程

为了理解 llama.cpp 的内部运作方式，下面的 Mermaid 图表展示了整个系统的架构和数据流向。

graph TD A["用户输入 (String)"] --> B["llama.cpp Tokenizer"] B --> C["Token IDs (int32 array)"] C --> D["上下文缓冲区 (KV Cache)"] D --> E["ggml 计算图"] E --> F["Transformer 层"] subgraph "ggml 引擎" F --> G["Self-Attention (RoPE)"] G --> H["前馈神经网络 (Feed Forward Network)"] H --> F end F --> I["Logits (词表大小)"] I --> J["采样器 (Temperature, Top-K, Top-P)"] J --> K["选中的 Token ID"] K --> L["llama.cpp Detokenizer"] L --> M["输出字符串"] K -. "自回归循环 (Auto-regressive loop)" .-> D

文本生成是一个自回归的循环，每输出一个 Token，它就会作为下一个输入被添加到 KV Cache 中，并再次穿过计算图。

4. 环境搭建与编译方法

在将 llama.cpp 集成到 C++ 项目中之前，让我们先尝试编译其源代码。

4.1 克隆仓库

1
2


git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

4.2 使用 CMake 编译

将其作为 C++ 项目集成到其他应用中时，使用 CMake 是最标准的方式。通过启用各平台的加速器（后端），可以加速计算。

仅 CPU（基本编译）:

1
2
3


mkdir build && cd build
cmake ..
cmake --build . --config Release -j 8

使用 NVIDIA GPU (CUDA) 时:

1
2
3


mkdir build && cd build
cmake .. -DGGML_CUDA=ON
cmake --build . --config Release -j 8

使用 Apple Silicon (Metal) 时:

1
2
3


mkdir build && cd build
cmake .. -DGGML_METAL=ON
cmake --build . --config Release -j 8

编译成功后，在 build/bin/ 目录下将生成 llama-cli 等可执行文件，以及用于在后文所述的 C++ API 中链接的 llama 库（以及 ggml 库）。

5. C++ 定制入门: 使用 llama.cpp API

接下来，我们将讲解本文的主题，即如何通过 C++ 代码控制 llama.cpp。如果你不仅想使用命令行工具，还想将 LLM 嵌入到你自己的应用程序（例如游戏引擎、桌面应用、嵌入式系统等）中，就需要直接调用 C++ API。

llama.cpp 主要通过一个名为 llama.h 的头文件提供 C 语言接口。在 C++ 中调用时，也使用此接口。

5.1 必要的包含与配置

在自己的项目中使用 llama.cpp 时，包含以下内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


#include "llama.h"
#include <iostream>
#include <vector>
#include <string>
#include <stdexcept>

// 错误处理宏
#define LLAMA_ASSERT(x) \
 do { \
 if (!(x)) { \
 std::cerr << "Assertion failed: " << #x << std::endl; \
 std::terminate(); \
 } \
 } while (0)

5.2 加载模型与初始化上下文

首先，加载 .gguf 格式的模型文件，并为推理分配上下文（内存空间和 KV 缓存）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


int main(int argc, char ** argv) {
 if (argc < 2) {
 std::cerr << "Usage: " << argv[0] << " <model.gguf>" << std::endl;
 return 1;
 }
 std::string model_path = argv[1];

 // 1. 初始化后端（配置 CPU/GPU 等环境）
 llama_backend_init();

 // 2. 获取模型参数的默认设置
 llama_model_params model_params = llama_model_default_params();
 model_params.n_gpu_layers = 35; // 卸载到 GPU 的层数

 // 3. 加载模型
 llama_model * model = llama_load_model_from_file(model_path.c_str(), model_params);
 if (model == nullptr) {
 std::cerr << "Failed to load model" << std::endl;
 return 1;
 }

 // 4. 设置上下文参数
 llama_context_params ctx_params = llama_context_default_params();
 ctx_params.n_ctx = 2048; // 最大上下文大小 (Token数)
 ctx_params.n_threads = 8; // 推理使用的 CPU 线程数

 // 5. 创建上下文
 llama_context * ctx = llama_new_context_with_model(model, ctx_params);
 if (ctx == nullptr) {
 std::cerr << "Failed to create context" << std::endl;
 llama_free_model(model);
 return 1;
 }

 std::cout << "Model and context loaded successfully!" << std::endl;
 // ... 后续处理

5.3 提示词的分词 (Tokenization)

LLM 并不能直接理解文本，而是将其作为整数 ID（Token）的序列进行处理。需要将输入字符串转换为 Token。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


 std::string prompt = "Q: 日本的首都是哪里？\nA:";
 std::vector<llama_token> tokens_list;
 tokens_list.resize(prompt.length() + 4); // 预留余量的缓冲区大小

 // 是否在开头添加特殊 Token（如 BOS: Begin of Sequence 等）
 bool add_special = true;
 // 将字符串转换为 Token ID 数组
 int n_tokens = llama_tokenize(
 model,
 prompt.c_str(),
 prompt.length(),
 tokens_list.data(),
 tokens_list.size(),
 add_special,
 false // parse_special
 );

 if (n_tokens < 0) {
 // 缓冲区不足时需要重新分配并重试（为简化省略）
 std::cerr << "Failed to tokenize prompt" << std::endl;
 return 1;
 }
 tokens_list.resize(n_tokens);

5.4 推理循环与采样

将 Token 输入模型，获取下一个 Token 的概率分布 (Logits)，然后从中进行采样以决定下一个 Token，构建这样的循环。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72


 // 要生成的最大 Token 数
 const int max_gen_tokens = 100;

 // 初始化用于批处理评估的结构体
 llama_batch batch = llama_batch_init(512, 0, 1);

 // 将提示词的 Token 添加到批次中
 for (size_t i = 0; i < tokens_list.size(); i++) {
 llama_batch_add(batch, tokens_list[i], i, { 0 }, false);
 }
 // 设置为仅在提示词的最后一个 Token 处输出 Logit（预测结果）
 batch.logits[batch.n_tokens - 1] = true;

 // 首次评估（将提示词送入模型）
 if (llama_decode(ctx, batch) != 0) {
 std::cerr << "llama_decode() failed" << std::endl;
 return 1;
 }

 int n_cur = batch.n_tokens; // 当前上下文长度
 int n_decode = 0;

 std::cout << "\nOutput: ";

 // 初始化采样器上下文（设置 Temperature, Top-K, Top-P 等）
 llama_sampler * smpl = llama_sampler_chain_init(llama_sampler_chain_default_params());
 llama_sampler_chain_add_top_k(smpl, 40);
 llama_sampler_chain_add_top_p(smpl, 0.9f, 1);
 llama_sampler_chain_add_temp(smpl, 0.7f);
 llama_sampler_chain_add_dist(smpl, 1234); // 随机种子

 while (n_decode < max_gen_tokens) {
 // 1. 采样：根据当前上下文预测下一个 Token
 llama_token new_token_id = llama_sampler_sample(smpl, ctx, -1);

 // 2. 如果 Token 是 EOS (End of Sequence)，则结束循环
 if (llama_token_is_eog(model, new_token_id)) {
 break;
 }

 // 3. 将 Token 解码为字符串（文本）并显示
 char buf[128];
 int n_chars = llama_token_to_piece(model, new_token_id, buf, sizeof(buf), 0, false);
 if (n_chars > 0) {
 std::cout << std::string(buf, n_chars) << std::flush;
 }

 // 4. 将新生成的 Token 作为下一个批次准备就绪
 llama_batch_clear(batch);
 llama_batch_add(batch, new_token_id, n_cur, { 0 }, true);

 // 5. 模型评估（更新 KV 缓存，预测下一个 Token）
 if (llama_decode(ctx, batch) != 0) {
 std::cerr << "Failed to evaluate" << std::endl;
 break;
 }

 n_cur += 1;
 n_decode += 1;
 }

 std::cout << std::endl;

 // 清理资源
 llama_sampler_free(smpl);
 llama_batch_free(batch);
 llama_free(ctx);
 llama_free_model(model);
 llama_backend_free();

 return 0;
}

这段代码是使用 llama.cpp 的基本 API 实现的自定义推理循环。它使用 llama_batch 结构体来管理 Token 群组，并通过 llama_decode 执行神经网络的前向传播 (Forward Pass)。

6. 高级定制案例: 使用 C++ 操作 Logit 与控制惩罚

如果不仅仅停留在简单的文本生成，而是想强制其输出特定格式（例如仅限 JSON），或者防止其输出特定的违禁词，可以在 C++ 端直接在采样前操作 Logits。

可以获取模型输出每个 Token 之前的原始分数（在转换为概率之前的值）数组。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 推理刚刚结束，在进行采样前获取原始的 logit 数组
float * logits = llama_get_logits_ith(ctx, batch.n_tokens - 1);
int n_vocab = llama_n_vocab(model);

// 违禁 Token 的 ID 列表（例如 1234, 5678）
std::vector<llama_token> forbidden_tokens = { 1234, 5678 };

// 将违禁 Token 的出现概率降为 0（将 Logit 设置为负无穷大）
for (llama_token bad_tok : forbidden_tokens) {
 logits[bad_tok] = -INFINITY;
}

像这样直接操作 C++ API，就可以实现 LangChain 或 Python 难以做到或者开销极大的 “在微秒级别对每个推理周期进行干预”。

7. 性能调优秘籍

在使用 C++ 完成实现后，为了面向实际生产环境最大程度地提升速度，下面介绍几个检查点。

批处理优化: 在同时处理来自多个用户的请求时，在 llama_batch 中包含多个序列并一次性调用 llama_decode（Continuous Batching，连续批处理）。这样可以合并内存访问，从而显著提高吞吐量。
启用 Flash Attention: 通过在上下文参数中设置 ctx_params.flash_attn = true;，可以在减少内存使用量的同时加速 Attention 的计算。在处理较长上下文（数万 Token）时，这是必不可少的设置。
支持 NUMA: 在多插槽服务器环境中，在调用 llama_backend_init() 之前正确配置 NUMA 设置，可以降低内存访问的延迟。

8. 结语

本文从 llama.cpp 的数学背景开始，详细解析了其架构，并讲解了如何运用 C++ API 构建自定义推理引擎。

虽然 Python 生态系统对于原型开发非常方便，但在要求部署到边缘设备、集成到游戏中或需要进行实时处理的生产环境中，基于 C/C++ 的 llama.cpp 的直接控制将展现出压倒性的优势。

希望大家也务必尝试亲手编写 C++ 代码，体验在本地环境中自由驾驭 LLM 的乐趣。

参考链接集

llama.cpp Official Repository

ggml - Tensor Library

Attention Is All You Need (Vaswani et al., 2017)