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 堆疊，專為讓開發者能輕鬆將 AI 模型整合至 Windows 上，並發揮最高效能而設計。此執行階段在 OS 層級將硬體加速抽象化，為開發者提供統一的介面。

graph TD App["Windows 應用程式 (C# / C++)"] --> API["Microsoft.Windows.AI APIs"] App --> ORT["ONNX Runtime"] API --> WCR["Windows Copilot Runtime (OS 層)"] WCR --> SLM["本機模型 (Phi-Silica 等)"] ORT --> DML["DirectML 執行提供者"] SLM --> DML DML --> DXCore["DXCore / DirectX 12"] DXCore --> NPU["NPU (神經處理單元)"] DXCore --> GPU["GPU (圖形處理單元)"] DXCore --> CPU["CPU"]

如上述架構圖所示，應用程式可以透過使用高階的 Microsoft.Windows.AI API，直接存取內建於 OS 中的小型語言模型（SLM：如 Phi-Silica 等）。此外，若使用自訂模型，也可以透過 ONNX Runtime 與 DirectML 明確地利用硬體加速。由於 OS 層會最佳化分配給 CPU、GPU 與 NPU 的工作負載，開發者無需深入了解硬體差異，即可建構高效能的 AI 應用程式。

3. 硬體加速與 NPU 的數學評估

最新的 Copilot+ PC 搭載了專門處理 AI 運算的處理器，即 NPU（神經處理單元）。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（乘積累加）單元數量
最後的 $2$ 是因為一次 MAC 運算包含乘法與加法兩個操作（FLOPs/OPs）。

例如，若 NPU 頻率為 1.5GHz、4 個核心、每個核心有 4096 個 MACs：

$$ 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，需要準備以下環境與工具鏈：

OS: 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. 【Deep Dive 1】使用 C# 活用本機語言模型（Phi-Silica）

Windows Copilot Runtime 中內建了由 Microsoft 開發的高效小型語言模型「Phi-Silica」作為 OS 標準元件。這使得我們無需從網路下載 GB 級別的模型，即可在離線環境下進行進階的自然語言處理（文章摘要、程式碼生成、聊天機器人）。

以下是使用 Microsoft.Windows.AI.Generative 命名空間，在 C# 中建構聊天 AI 的進階範例程式碼。支援串流回應，並能即時生成文字而不阻塞 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 傳回的區塊
 await foreach (var chunk in responseStream.WithCancellation(cancellationToken))
 {
 // 將生成的權杖（區塊）即時輸出至主控台
 // 若為 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 進行非同步串流。在 OS 背景運作的 Copilot Runtime 接收到此 API 呼叫後，會在內部啟動 ONNX Runtime，並根據系統設定選擇最佳的執行提供者（Execution Provider，在許多最新 PC 上為 DirectML + NPU）。

開發者完全無需考慮模型的張量形狀、分詞器實作、KV 快取的記憶體管理等細節，只需幾行 C# 程式碼即可將最先進的 AI 推論管線整合到應用程式中。

6. 【Deep Dive 2】透過 C++ 與 DirectML 進行自訂模型的高速推論

當處理 OS 標準語言模型無法涵蓋的特定領域（例如：專有影像分割、語音辨識、自訂物件偵測模型等）時，開發者需要直接操作位於 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 執行提供者 (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 執行提供者。" << 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++ 中記憶體管理與零拷貝推論的重要性

在 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 工具組

要發揮 NPU 的真正實力，將 AI 模型的權重與激勵值從 FP32（單精度浮點數）**量化（Quantization）**至 INT8 或 INT4 絕對是必要條件。NPU 的架構專為整數運算而設計，相較於 FP32，INT8 在理論上能達到 4 倍的吞吐量，並大幅節省耗電。

透過使用 Microsoft 提供的 Olive (ONNX Live) 工具鏈，可以將 PyTorch 等模型自動針對 Windows 環境進行最佳化。Olive 能強力支援對 Transformer 模型的特殊注意力最佳化，以及針對各種硬體的運算圖編譯。

7.2 批次處理 vs 互動式串流的權衡

在 API 呼叫中，將多個推論請求合併進行批次處理，可以提高 NPU 的利用率（Compute Utilization）。然而，在如聊天機器人這類互動式 UI 的情況下，決定使用者體驗（UX）的並非吞吐量，而是顯示第一個權杖所需的時間（TTFT: Time To First Token）。因此，在互動式 UI 中，最佳實務是將批次大小設為 1，並優先採用串流生成設計。

7.3 背景工作與 OS 的整合

AI 推論會大量消耗本機的電力與系統資源。必須與 Windows 的 App Lifecycle API 整合，當應用程式轉入背景執行時，實作暫停（Suspend）優先度較低的推論工作或限制資源消耗的機制。

sequenceDiagram participant User as "使用者" participant App as "Windows App (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 個權杖）" 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 內建於 OS: 不僅限於文字，還能無縫同時處理語音、影像，甚至是即時視訊來源，在 OS 層級標準提供跨模態的 AI 推論。
RAG (檢索增強生成) 的系統層級支援: 在 OS 安全的沙盒中，將本機 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充其量只扮演了「膠水」的角色。

那麼，為什麼我們需要特地排除Python，單獨用C++來打造AI推論引擎呢？這有幾個強而有力的理由。

極致的效能與低延遲：可以完全消除Python的GIL（全域直譯器鎖）以及動態型別帶來的開銷。特別是在需要即時性的系統中，毫秒級的延遲都是致命的。
部署的便利性：要在終端使用者的環境中建構Python環境（龐大的函式庫群、依賴關係的地獄）非常困難。如果是C++，只需要發布靜態連結的單一執行檔（.exe或ELF二進位檔）即可。
支援邊緣設備：在智慧型手機、嵌入式設備、Raspberry Pi等資源嚴重受限的環境中，沒有餘裕去執行會消耗數GB記憶體的Python執行階段（Runtime）。
硬體的直接控制：像是記憶體分配的時機、明確地使用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["輸出結果"] G --> H

張量（Tensor）管理：管理多維陣列的資料結構以及各維度的步幅（Stride）。
計算圖（Computation Graph）：將神經網路各層的運算，表示為有向無環圖（DAG）。
記憶體池（Memory Arena）：為了避免動態記憶體分配（malloc或new）的開銷，採用預先分配型的記憶體管理機制。
後端（Backend）：針對CPU或GPU等特定硬體最佳化的運算實作（Kernel）。

我們將運用C++的強大功能（樣板、指標運算、RAII等）將這些組裝起來。

3. 記憶體管理的奧秘：記憶體池與SIMD對齊

推論引擎中的記憶體管理，是直接關係到效能的最重要因素之一。在推論過程中，特別是通過Transformer模型的各層時，會產生數量龐大的中間張量。如果每次都用標準的malloc來分配與釋放，堆積（Heap）的碎片化以及作業系統的上下文切換將會導致致命的速度下降。

因此，我們採用了「記憶體池（Memory Arena）」的方法。這是在推論開始時計算（或寫死）所需的最大記憶體量並一次性分配，之後只需遞增指標就能切割出記憶體的手法。

3.1 對齊（Alignment）的重要性

現代CPU支援SIMD（Single Instruction, Multiple Data）指令。例如Intel/AMD的AVX2/AVX-512，以及ARM的NEON等。這些指令可以一次處理256位元（32位元組）或512位元（64位元組）的資料，但處理對象的資料記憶體必須對齊（Alignment）在特定的位元組邊界（通常是32位元組或64位元組）。

以下是考慮到對齊的記憶體池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)）
 }
};

像這樣，建立張量時必定透過這個記憶體池來取得記憶體。每次推論步驟（例如每次生成Token）結束後，只要呼叫 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; // 指向有效負載（Payload）的指標

 // 計算圖用
 enum OpType op;
 Tensor* src0;
 Tensor* src1;
};

步幅 nb[i] 代表在維度 i 中，相鄰元素之間在記憶體上的位元組距離。例如，元素數量為 $M \times N$ 的矩陣（FP32，1個元素4位元組），如果以列優先（Row-Major）儲存，其步幅如下：

nb[0] = 4 (位元組) ：往行（Column）方向移動
nb[1] = $N \times 4$ (位元組) ：往列（Row）方向移動

利用這一點，我們可以不用複製記憶體，只需交換步幅的數值，就能實現「轉置（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} $$

如果用樸素的三層迴圈來實作，會頻繁發生快取未命中（Cache Miss），完全發揮不出效能。

6.1 CPU上的快取區塊化與SIMD最佳化

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

迴圈平鋪（Loop Tiling/快取區塊化）：將矩陣分割成能放進L1/L2快取的小區塊來進行計算。
資料打包（Data Packing）：在內部重新排列資料，使記憶體存取模式變得連續。
活用SIMD：使用AVX-512中的 _mm512_fmadd_ps 等FMA（Fused Multiply-Add）指令，在一個時脈週期內完成大量乘加運算。

以下展示一個使用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個Token以上）來運行LLM等巨大模型，GPU的平行計算能力是不可或缺的。因此，我們在引擎中導入後端（Backend）的抽象層。

7.1 後端抽象化

利用C++的多型（Polymorphism），讓我們能切換運算的執行器（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++擴充功能來實作後端。雖然可以自己寫核心（Kernel），但關於矩陣乘法，活用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推論機非常優秀。其原因在於「統一記憶體（Unified Memory）」。由於CPU和GPU共享同一塊記憶體區域，因此完全不需要像前述CUDA那樣透過PCIe匯流排進行高成本的主機與設備間記憶體傳輸。

要從C++呼叫Metal，可以將Objective-C++（.mm 檔案）當作橋樑，或是利用metal-cpp函式庫。我們使用Metal的Compute Shader（在.metal檔案中以類似C++的語法撰寫）來編寫核心（Kernel）。

 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 Cache

像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）的Token生成中，必須保留過去Token的計算結果（Key與Value）。我們稱之為「KV快取（Key-Value Cache）」。

graph TD T["當前Token (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 Tokens）的記憶體空間，並採用類似環狀緩衝區（Ring Buffer）的方式來運作。這樣就能防止在每個生成步驟重新分配記憶體。

另外，針對位置編碼（Positional Encoding），我們將實作近年來成為主流的「RoPE（Rotary Position Embedding）」。這是一種將位置資訊作為複數空間旋轉向量嵌入的手法，在C++中對 sin 及 cos 函式呼叫的最佳化（例如建立尋找表 Lookup Table 等）是影響效能的關鍵。

9. 透過模型量化（Quantization）達成極限最佳化

如果將大型模型（例如70億參數的LLaMA模型）維持在FP32（32位元浮點數）載入，光是權重就會消耗約28GB的記憶體（VRAM）。再把KV快取和推論用緩衝區算進去，很容易就超過30GB，一般的消費級GPU根本無法執行。

因此，「量化（Quantization）」就成了不可或缺的技術。這也是GGML格式的精髓所在。

量化是指刻意降低權重精度的技術。

FP16 (16-bit): 大小減半。精度幾乎沒有下降。
INT8 (8-bit): 大小變成1/4。僅有微小下降。
INT4 (4-bit): 大小變成1/8。若使用獨特的區塊化（Blocking）與縮放因子（Scaling Factor），即可進行具實用性的推論。

在推論引擎端，會從記憶體讀出被壓縮為INT4（或INT8）的權重，在載入到CPU或GPU的暫存器後，立刻解壓縮（Dequantize）回FP16或FP32再進行計算。

令人驚訝的是，即使增加了計算量，減少從記憶體讀取的資料量反而能讓速度更快。這是因為在現代硬體中，推論任務的瓶頸不在於「計算力（Compute Bound）」，而在於「記憶體頻寬（Memory Bandwidth Bound）」。如果是實作了INT4量化的C++引擎，即使是只有8GB VRAM的MacBook Air等設備，也能流暢地運行本機端的LLM。

10. 效能調校：NUMA架構與執行緒池

當使用CPU進行推論時，多執行緒化是必須的。但如果只是單純啟動多個 std::thread，並不能算是最佳做法。

在現代的多插槽（Multi-socket）伺服器或Ryzen Threadripper等高階CPU上，採用了**NUMA（Non-Uniform Memory Access）**架構。從某個CPU核心存取實體上較近的記憶體（本地記憶體）速度很快，但存取綁定在其他處理器上的記憶體則會變得極慢。

在進階的C++推論引擎中，會靈活運用以下技巧：

執行緒綁定（Thread Pinning）：將各個執行緒固定在特定的CPU核心（設定親和性 Affinity），防止上下文切換導致快取失效。
感知NUMA的記憶體分配（NUMA-aware Allocation）：在處理資料的執行緒所在的同一個NUMA節點上分配記憶體。
工作竊取型執行緒池（Work-stealing Thread Pool）：將計算圖的各個節點分割成細小的任務，並實作能讓閒置執行緒自動奪取任務執行的有效率排程器。

透過活用這些技巧，能將CPU使用率緊緊貼在100%附近，跑出接近理論值的吞吐量。

11. 總結：用C++的「肌肉」驅動AI的樂趣

Python確實很方便。在研發和製作原型時，沒有任何語言能比得上它的生產力。然而，當完成的模型要轉移到「在真實世界中，有效率地、在各種設備上運行」的階段時，C++出場的時刻就到了。

直接操作記憶體的位元組陣列，用SIMD指令將暫存器操到極限，一邊與GPU的VRAM頻寬搏鬥一邊打造出的推論引擎，看著它在終端機上陸續生成自然的文字（Token）時，那種成就感，是呼叫Python框架中 model.generate() 時絕對無法體會到的「身為工程師純粹的喜悅」。

AI技術往往容易變成「黑盒子（Black Box）」，但透過自己親手用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」已成為業界的標準。

本文將提供非常詳細的開發步驟，解說如何從零開始建構（或深入理解現有 llama.cpp 的內部結構）一個使用 C++ 載入 TinyLLaMA 並進行文字生成的推論引擎。

1. 為什麼選擇C++與ggml？

在 AI 的訓練階段，擁有高靈活性與豐富生態系的 Python 佔有絕對的優勢。然而，在部署與「推論（Inference）」階段，基於以下理由，C++ 成為了強大的選擇：

減少額外負擔（Overhead）: 可以完全消除 Python 的全域直譯器鎖（GIL）以及執行時期的額外負擔。
記憶體效率與 Arena 分配（Arena Allocation）: 由於可以手動控制記憶體的配置與釋放，能防止垃圾回收（Garbage Collection）所造成無法預測的效能突波。
直接存取硬體: 能夠直接呼叫 AVX-512、AVX2、ARM NEON 等 SIMD 內建函式（Intrinsics），將 CPU 的運算能力發揮到極致。
排除依賴關係: ggml 是一個零依賴（Zero dependencies）的 C/C++ 函式庫，只要有編譯器，即使在 Windows 的 MSVC 環境下也能輕鬆編譯。

2. 架構全貌

推論管線（Pipeline）整體的流程如下方 Mermaid 圖表所示。這是一連串從使用者的輸入文字開始，直到最終生成下一個 Token 的過程。

graph TD A["使用者輸入文字"] --> B["BPE 分詞器"] B --> C["Token IDs 陣列"] 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 Cache）中，不會在使用者空間產生多餘的拷貝。
按需載入（Page Fault）: 只有在 CPU 實際存取該記憶體位址的瞬間，才會發生分頁錯誤（Page Fault），並僅將需要的區塊（通常是 4KB）載入到實體記憶體中。

在 Windows 環境中，我們使用 Win32 API 的 CreateFileMapping 和 MapViewOfFile 來取代 POSIX 的 mmap。

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)，是專為推論打造的終極格式。它具有以下嚴謹的二進位佈局（Binary Layout）：

Magic Bytes: 0x46554747 (GGUF)。
Version: 格式的版本號碼。
Tensor Count & Metadata Count: 張量數量與 Metadata 的鍵值對（Key-Value Pairs）數量。
Metadata (Key-Value Pairs): 帶有字串長度前綴的鍵（Key）以及具有型別的值（Value）。
Tensor Info: 每個張量的名稱、維度數、資料型別（如 FP16, Q4_K 等），以及在檔案內的偏移位置（Offset）。
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)

在一般的多頭注意力機制（Multi-Head Attention, MHA）中，Query、Key 和 Value 各自擁有相同數量的注意力頭（Head）。然而，TinyLLaMA 為了大幅減少記憶體頻寬與 KV Cache 的消耗，採用了 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 之前，必須先執行將 KV 張量依照 Query 數量進行廣播（Broadcast）的操作。

4.4 SwiGLU 激勵函式

在前饋神經網路（Feed-Forward Network, 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 Allocator

ggml 最獨特的一點在於「Arena Allocation」，它在推論迴圈內完全不進行動態的記憶體配置（如 malloc 或 new）。在初始化時，會先保留一塊巨大的連續記憶體區域（Arena），每當呼叫 ggml_new_tensor 等函式時，這塊區域的指標就會遞增。當推論的一個步驟完成後，只需將配置指標重設回初始位置，就能立即完成下一個推論步驟的記憶體配置準備。

5.2 計算圖建構的具體範例

在每個推論步驟中，都會在記憶體上組合出如下的計算圖。

graph TD A["Tokens 輸入 ID"] --> B["嵌入層查找"] B --> C["ggml_rms_norm"] C --> D["Q / K / V 投影"] D --> E["ggml_rope 位置編碼"] E --> F["儲存 KV Cache"] E --> G["載入 KV Cache"] 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 位元組）藉此能將局部異常值（Outlier）的影響降到最低。

6.2 利用 AVX2 加速內積計算

在針對 Windows 環境中最新的 x86 CPU 進行編譯時，可以善用 /arch:AVX2 等編譯器旗標，並透過以下流程進行 SIMD 處理：

載入 (Load): 從記憶體將 4 位元量子化資料載入至 256 位元的 AVX 暫存器中。
展開與解包 (Unpack): 利用位元遮罩（Bitmask）與移位運算，將 4 位元數值展開為 Int8 或 Int16。
反量子化 (Dequantize): 乘上縮放因子將其轉換為浮點數。
FMA 運算: 將結果與激勵值（Activation）使用 _mm256_fmadd_ps (Fused Multiply-Add) 平行執行乘加運算。

7. KV Cache的實作細節

在自迴歸生成中，為了省略過去 Token 的 Key 和 Value 計算，「KV Cache」是不可或缺的功能。

在 C++ 中實作的重點如下：

預先配置張量: 初始化一個對應最大上下文長度（例如：2048 Tokens）的巨大張量作為 KV Cache（建議使用 FP16）。
偏移拷貝 (Offset Copy): 當對位置 $N$ 的 Token 進行計算後，將該步驟得到的 K 和 V 向量，使用 ggml_cpy 等方式儲存到 KV Cache 張量的第 $N$ 列中。
注意力機制時建立視圖 (View): 在計算注意力時，建立一個只指向第 0 到第 $N$ 個 Token 部分的「視圖」，並將其傳遞給矩陣乘法操作。

8. BPE Tokenizer 與解碼

將輸入字串視為 UTF-8 位元組序列，並與預先定義好的詞彙表（Vocabulary）進行比對。在 C++ 中，為了加速詞彙表的搜尋，通常會實作 Trie 樹（前綴樹） 或使用優先權佇列（Priority Queue）的演算法。

從 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 Cache 等系統程式設計的精髓，一邊開拓邊緣 AI（Edge AI）的未來吧。

llama.cpp 使用方法與 C++ 客製化入門

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

近年來，大型語言模型 (LLM) 的進化非常驚人，其應用範圍每天都在擴大。然而，要在本機環境中運行具有數十億、數百億參數的模型，通常需要配備龐大 VRAM 的高階 GPU。打破這種「硬體壁壘」，並在一般 PC、Mac 甚至 Raspberry Pi 等設備上實現 LLM 實用推理的，正是 llama.cpp。

本文不僅介紹單純的命令列工具用法，還將針對工程師進行極為詳細的解說，內容涵蓋其基礎技術 ggml 的架構、Transformer 和量化的數學背景，以及如何利用 C++ API 將 LLM 嵌入到獨立應用程式中並進行客製化。

1. llama.cpp 與 ggml 概要

llama.cpp 是由 Georgi Gerganov 開發，使用 C/C++ 編寫的輕量級 LLM 推理引擎。它最初是為了在 Apple Silicon (M1/M2 Mac) 上高速運行 Meta 的 LLaMA 模型而誕生的，但現在已經支援各種架構和模型。

它最大的特點是無外部依賴的純 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}$，查詢 $Q$、鍵 $K$、值 $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["使用者輸入 (字串)"] --> B["llama.cpp Tokenizer"] B --> C["Token ID (int32 陣列)"] C --> D["上下文緩衝區 (KV Cache)"] D --> E["ggml 計算圖"] E --> F["Transformer 層"] subgraph "ggml 引擎" F --> G["Self-Attention (RoPE)"] G --> H["前饋神經網路"] 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 -. "自迴歸迴圈" .-> 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 必要最少的 Include 與設定

在自己的專案中使用 llama.cpp 時，請 Include 以下內容。

 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 Cache）。

 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 提示詞的 Token 化 (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 Cache 並預測下一個）
 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++ 端直接操作採樣前的 Logit (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)