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は、開発者がWindows上でAIモデルを簡単に統合し、かつ最高のパフォーマンスを引き出せるように設計された一連のAIスタックです。このランタイムは、OSレベルでハードウェアアクセラレーションを抽象化し、開発者に統一されたインターフェースを提供します。

graph TD App["Windows Application (C# / C++)"] --> API["Microsoft.Windows.AI APIs"] App --> ORT["ONNX Runtime"] API --> WCR["Windows Copilot Runtime (OS Layer)"] WCR --> SLM["Local Models (Phi-Silica, etc.)"] ORT --> DML["DirectML Execution Provider"] SLM --> DML DML --> DXCore["DXCore / DirectX 12"] DXCore --> NPU["NPU (Neural Processing Unit)"] DXCore --> GPU["GPU (Graphics Processing Unit)"] 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（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}}$ は1コアあたりのMAC（Multiply-Accumulate）ユニット数
最後の $2$ は、1回のMAC演算が乗算と加算の2つのオペレーション（FLOPs/OPs）としてカウントされるためです。

例えば、周波数1.5GHz、4コア、各コアが4096MACsを持つ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を利用するには、以下の環境とツールチェーンを整える必要があります。

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のピークパフォーマンスを引き出すことができます。以下は、ONNX形式のカスタムモデル（例：YOLOv8）をDirectMLを用いて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
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（Non-Maximum Suppression）やバウンディングボックスの描画処理を実装する
 }
};

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 Toolkit

NPUの真の力を発揮させるには、AIモデルの重みとアクティベーションをFP32（単精度浮動小数点）からINT8またはINT4へと**量子化（Quantization）**することが絶対条件です。NPUのアーキテクチャは整数演算に特化しており、FP32と比較してINT8では理論上4倍のスループットと大幅な省電力を実現します。

Microsoftが提供する Olive (ONNX Live) ツールチェーンを使用することで、PyTorch等のモデルをWindows環境向けに自動最適化できます。Oliveは、Transformerモデルに対する特殊なアテンション最適化や、ハードウェアごとのグラフコンパイルを強力に支援します。

7.2 バッチ処理 vs 対話型ストリーミングのトレードオフ

API呼び出しにおいて、複数の推論リクエストをまとめてバッチ処理することで、NPUの利用効率（Compute Utilization）を高めることができます。しかし、チャットボットのような対話型UIの場合、スループットよりも最初のトークンが表示されるまでの時間（TTFT: Time To First Token）がユーザー体験（UX）を決定づけます。したがって、対話型UIではバッチサイズを1に設定し、ストリーミング生成を優先する設計がベストプラクティスとなります。

7.3 バックグラウンドタスクとOSとの連携

AI推論はローカルの電力とシステムリソースを大量に消費します。Windowsの App Lifecycle API と連携し、アプリケーションがバックグラウンドに回った際は、優先度の低い推論タスクを一時停止（Suspend）するか、リソース消費を絞る実装が求められます。

sequenceDiagram participant User as "User" 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 Hardware" 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ネイティブ統合: テキストだけでなく、音声、画像、さらにはライブビデオフィードをシームレスに同時処理し、クロスモーダルなAI推論をOSレベルで標準提供。
RAG（Retrieval-Augmented Generation）のシステムレベル対応: ローカルPC内のパーソナルなドキュメント群やWindows SearchのインデックスとAIモデルをOSの安全なサンドボックス内で連携させ、ユーザーのプライバシーを完全に保護した状態での超高度なパーソナルAIアシスタントの構築。
NPUの動的リソーススケーリング: 複数のAIアプリケーション（例えば、バックグラウンドでのノイズキャンセリングと、フォアグラウンドでのコード生成）が同時に稼働する際、WindowsのカーネルスケジューラがNPUの実行コンテキストを動的に切り替え、QoS（Quality of Service）を保証する仕組み。

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（Global Interpreter Lock）や動的型付けによるオーバーヘッドを完全に排除できます。特にリアルタイム性が求められるシステムでは、ミリ秒単位の遅延が命取りになります。
デプロイの容易さ: Python環境（巨大なライブラリ群、依存関係の地獄）をエンドユーザーの環境に構築するのは非常に困難です。C++であれば、静的リンクされた単一の実行バイナリ（.exeやELFバイナリ）を配布するだけで済みます。
エッジデバイスへの対応: スマートフォンや組み込み機器、Raspberry Piのようなリソース制約の厳しい環境において、数ギガバイトものメモリを消費するPythonランタイムを動かす余裕はありません。
ハードウェアの直接制御: メモリアロケーションのタイミング、SIMD命令の明示的な利用、GPUとのメモリ転送の最適化など、低レイヤーの制御がC++なら可能です。

本記事では、Georgi Gerganov氏によって開発された「GGML」ライブラリのアーキテクチャに多大なインスピレーションを受けつつ、C++だけで大規模言語モデル（LLM）などを動かすための推論エンジンをスクラッチで構築していく過程を、技術的な深淵まで潜って解説します。

2. 推論エンジンのアーキテクチャ全体像

AIの推論処理は、本質的には「巨大な行列計算の連続」です。これを効率よく実行するためには、推論エンジンは以下のようなコンポーネントで構成される必要があります。

graph TD A["Input Data (Tokens/Images)"] --> B["Tensor Management"] B --> C["Computation Graph (DAG)"] C --> D["Memory Arena & Allocator"] C --> E["Scheduler & Thread Pool"] E --> F["CPU Backend (AVX2/ARM NEON)"] E --> G["GPU Backend (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で確保・解放していては、ヒープの断片化とOSのコンテキストスイッチによって致命的な速度低下を引き起こします。

そこで、「メモリアリーナ（Memory Arena）」というアプローチを採用します。これは推論開始時に必要な最大メモリ量を計算（または決め打ち）して一括確保し、ポインタのインクリメントだけでメモリを切り出していく手法です。

3.1 アライメントの重要性

現代のCPUは、SIMD（Single Instruction, Multiple Data）命令をサポートしています。Intel/AMDのAVX2/AVX-512や、ARMのNEONなどです。これらの命令は、256ビット（32バイト）や512ビット（64バイト）のデータを一度に処理しますが、処理対象のデータメモリが特定のバイト境界（通常は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)）
 }
};

このように、テンソル作成時には必ずこのアリーナ経由でメモリを取得します。推論の各ステップ（トークン生成ごとなど）が終わるたびに reset() を呼ぶだけで、瞬時にメモリを再利用できるのです。

4. テンソルデータ構造とストライドの魔法

テンソルはスカラー、ベクトル、行列を一般化した概念です。実装において重要なのは、実際のデータがメモリ上に1次元の連続した配列として配置されている一方で、それを多次元として解釈するための「ストライド（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、1要素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）も、突き詰めれば巨大な行列積です。

2つの行列 $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（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上ではそこそこ動きますが、LLMなどの巨大なモデルを実用的な速度（例：1秒間に20トークン以上生成）で動かすには、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["Append to KV Cache"] V --> VCache["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（Rotary Position Embedding）」を実装します。これは複素空間での回転ベクトルとして位置情報を埋め込む手法で、C++での sin および cos 関数の呼び出し最適化（ルックアップテーブル化など）がパフォーマンスの鍵を握ります。

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。独自のブロッキングとスケーリングファクターを用いれば実用的な推論が可能。

推論エンジン側では、メモリからINT4（またはINT8）で圧縮されたウェイトを読み出し、CPUまたはGPUのレジスタにロードした直後にFP16またはFP32に展開（Dequantize）して計算を行います。

驚くべきことに、計算量を増やしてでもメモリから読み込むデータ量を減らした方が速くなります。これは現代のハードウェアにおいて、推論タスクのボトルネックが「計算力（Compute Bound）」ではなく「メモリ帯域幅（Memory Bandwidth Bound）」にあるからです。INT4量子化を施したC++実装のエンジンであれば、8GB VRAMのMacBook AirなどでもサクサクとローカルLLMを動かすことが可能になります。

10. パフォーマンスチューニング：NUMAアーキテクチャとスレッドプール

CPUを用いた推論を行う場合、マルチスレッド化は必須です。しかし、単純に std::thread を多数起動するだけでは最適とは言えません。

現代のマルチソケットサーバーやRyzen ThreadripperのようなハイエンドCPUでは、NUMA（Non-Uniform Memory Access） アーキテクチャが採用されています。あるCPUコアから物理的に近いメモリ（ローカルメモリ）へのアクセスは高速ですが、別のプロセッサに紐付いたメモリへのアクセスは極端に遅くなります。

高度なC++推論エンジンでは、以下のテクニックを駆使します。

スレッドピンニング（Thread Pinning）: 各スレッドを特定のCPUコアに固定（Affinityを設定）し、コンテキストスイッチによるキャッシュ破棄を防ぐ。
NUMAアウェアなアロケーション: データを処理するスレッドと同じNUMAノード上にメモリを確保する。
ワークスティーリング型スレッドプール: 計算グラフの各ノードを細かなタスクに分割し、空いているスレッドが自動的にタスクを奪取して実行する効率的なスケジューラを実装。

これらを駆使することで、CPU使用率を100%付近にピタリと張り付かせ、理論値に近いスループットを叩き出すことができます。

11. まとめ：C++の「筋肉」でAIを駆動する楽しさ

Pythonは確かに便利です。研究開発やプロトタイピングにおいて、その生産性に敵う言語はありません。しかし、出来上がったモデルを「実世界で、効率よく、あらゆるデバイスで動かす」というフェーズに移行した瞬間、C++の出番がやってきます。

メモリのバイト列を直接操作し、SIMD命令でレジスタを限界まで叩き、GPUのVRAM帯域幅と格闘しながら作り上げた推論エンジンが、コンソール上に次々と自然な日本語のテキスト（トークン）を生成していくのを見た時の達成感は、Pythonのフレームワークで model.generate() を呼び出した時には決して得られない「エンジニアとしての純粋な喜び」があります。

「Black Box」となりがちな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パラメータ）のような小規模モデルは、限られたリソースのエッジデバイスや一般的なノートPC（Windows環境を含む）上でも実用的な速度で推論が可能です。PythonとPyTorchを用いた開発が主流である一方で、究極のパフォーマンスと省メモリ性を追求する場合、C++とC言語ベースのテンソルライブラリである「ggml」の組み合わせがデファクトスタンダードとなっています。

本記事では、C++を用いてTinyLLaMAをロードし、テキスト生成を行うための推論エンジンをゼロから構築（あるいは既存のllama.cppの内部構造を深く理解）するための非常に詳細な開発手順を解説します。

1. なぜC++とggmlなのか？

AIの学習段階においては、柔軟性と豊富なエコシステムを持つPythonが圧倒的に有利です。しかし、デプロイや「推論（Inference）」のフェーズにおいては、以下の理由からC++が強力な選択肢となります。

オーバーヘッドの削減: Pythonのグローバルインタプリタロック（GIL）やランタイムのオーバーヘッドを完全に排除できます。
メモリ効率とアリーナアロケーション: メモリの確保と解放をマニュアルで制御できるため、ガベージコレクションによる予測不能なスパイクを防げます。
ハードウェアへの直接アクセス: AVX-512、AVX2、ARM NEONなどのSIMD組み込み関数（Intrinsics）を直接呼び出し、CPUの演算能力を極限まで引き出せます。
依存関係の排除: ggmlは依存関係ゼロ（Zero dependencies）のC/C++ライブラリであり、コンパイラさえあればWindows上のMSVC環境でも容易にビルド可能です。

2. アーキテクチャの全体像

推論パイプライン全体の流れを以下のMermaidダイアグラムに示します。ユーザーの入力テキストから始まり、最終的に次のトークンが生成されるまでの一連のプロセスです。

graph TD A["User Input Text"] --> B["BPE Tokenizer"] B --> C["Token IDs Array"] C --> D["Embedding Layer Lookup"] D --> E["Transformer Blocks"] E --> F["RMSNorm"] F --> G["LM Head Layer"] G --> H["Logits Array"] H --> I["Sampler Module"] I --> J["Next Token ID"] J --> K["Detokenizer"] K --> L["Output Text Chunk"] J -.-> |"Append to Context"| C

自己回帰モデルであるため、出力されたトークンは再びコンテキストに追加され、次のトークン予測のための入力として循環します（図の点線部分）。

3. モデルフォーマットとメモリマッピング (mmap)

巨大なニューラルネットワークの重みを扱う上で最大の障壁となるのが、ディスクI/Oとメモリ消費です。C++実装ではこれを**メモリマッピング（mmap）**で解決します。

3.1 メモリマッピングの仕組みとWindowsでの実装

mmapを使用すると、ファイルの内容をプロセスの仮想メモリ空間に直接マッピングできます。

ゼロコピー（Zero-copy）: データはディスクから直接カーネルのページキャッシュに読み込まれ、ユーザー空間への余分なコピーが発生しません。
オンデマンド・ロード（Page Fault）: 実際にCPUがそのメモリアドレスにアクセスした瞬間に、ページフォールトが発生し、必要なチャンク（通常4KB）だけが物理メモリにロードされます。

Windows環境では、POSIXの mmap の代わりにWin32 APIの CreateFileMapping と MapViewOfFile を使用します。

sequenceDiagram participant OS["Windows OS"] participant RAM["Physical Memory"] participant App["C++ Application"] App->>OS: "CreateFileMapping / MapViewOfFile" OS-->>App: "Virtual Memory Address Pointer" App->>App: "Read Tensor Data at Pointer" OS->>RAM: "Page Fault / Load page from Disk" RAM-->>App: "Data ready for SIMD Compute"

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)

トークンの位置情報をテンソル空間における回転（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$はトークンの絶対的な位置インデックス、$\theta$は事前に計算された基本周波数です。ggmlでは、推論グラフの構築中に ggml_rope オペレータを追加するだけで並列実行されます。

4.3 Grouped-Query Attention (GQA)

通常のMulti-Head Attention (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ヘッドが1つのKey/Valueヘッドを共有します。C++実装では行列積 ggml_mul_mat を実行する前に、KVテンソルをQueryの数に合わせてブロードキャストする操作が必要になります。

4.4 SwiGLU 活性化関数

Feed-Forward Network (FFN) 層では、GELUの代わりにSwiGLUが用いられます。

$$ \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は、推論のための静的な計算グラフを構築し、それを後から評価（evaluate）する「Define-and-Run」のアプローチを取ります。

5.1 ggml_context とアリーナアロケータ

ggmlの最もユニークな点は、推論ループ内で動的なメモリ確保（malloc や new）を一切行わない「アリーナアロケーション」です。初期化時に巨大な連続したメモリ領域（アリーナ）を確保し、ggml_new_tensor などを呼び出すたびに、この領域のポインタがインクリメントされます。推論の1ステップが完了したら、アロケーションポインタを初期位置にリセットするだけで、次の推論ステップのメモリ確保が即座に完了します。

5.2 グラフ構築の具体例

推論ステップごとに、以下のような計算グラフをメモリ上に組み立てます。

graph TD A["Tokens Input ID"] --> B["Embed Lookup"] B --> C["ggml_rms_norm"] C --> D["Q / K / V Projections"] D --> E["ggml_rope Positional"] E --> F["KV Cache Store"] E --> G["KV Cache Load"] G --> H["Self Attention"] H --> I["Scale & Softmax"] I --> J["Attention Output"] J --> K["Out Projection"] K --> L["Add Residual"]

6. 量子化 (Quantization) と Windows / SIMD 最適化

TinyLLaMA (1.1B) をFP16で扱うと約2.2GBのメモリが必要ですが、4ビット量子化（Q4_Kなど）により約600MB程度まで劇的に圧縮できます。

6.1 ブロック量子化アーキテクチャ

ggmlはテンソル全体を一律に量子化するのではなく、「ブロック」単位で行います。 Q4_0 フォーマットでは、32個のFP16値を1つのブロックにまとめます。

スケールファクタ: 1つのFP16値（2バイト）
量子化データ: 32個の4ビット値（16バイト）これにより、局所的な外れ値の影響を最小限に抑えています。

6.2 AVX2によるドット積の高速化

Windows環境の最新のx86 CPU向けにビルドする場合、/arch:AVX2 などのコンパイラフラグを活用し、以下のようなフローでSIMD処理が行われます。

ロード: 256ビットのAVXレジスタに、メモリから4ビット量子化データをロード。
展開とアンパック: ビットマスクとシフト演算で、4ビット値をInt8またはInt16に展開。
逆量子化: スケールファクタを乗算して浮動小数点に変換。
FMA演算: アクティベーション値と _mm256_fmadd_ps（Fused Multiply-Add）で積和演算を並列実行。

7. KVキャッシュの実装詳細

自己回帰的生成において、過去のトークンのKeyとValueの計算を省略するための「KVキャッシュ」は必須機能です。

C++で実装する場合のポイントは以下の通りです。

テンソルの事前確保: 最大コンテキスト長（例: 2048トークン）分の巨大なテンソルをKVキャッシュ用に初期化します（FP16を推奨）。
オフセットコピー: トークン位置 $N$ に対する計算が行われると、そのステップで得られたKとVのベクトルをKVキャッシュテンソルの $N$ 行目に ggml_cpy 等を用いてストアします。
アテンション時のビュー作成: アテンションを計算する際は、0から $N$ 番目までのトークン部分だけを指し示す「ビュー」を作成して行列積に渡します。

8. BPE トークナイザーとデコーディング

入力文字列をUTF-8のバイト列として扱い、事前に定義されたボキャブラリーと照らし合わせます。C++では、ボキャブラリーの検索を高速化するために Trie木（プレフィックスツリー） や、優先度付きキューを用いたアルゴリズムを実装します。

LM Headから出力されるロジットからは、Temperatureパラメータを用いて確率をスケーリングし、Top-K抽出やTop-P（Nucleus Sampling）手法によって候補を絞り込み、乱数を用いて最終的な次のトークンを決定します。

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) の進化は凄まじく、その応用範囲は日々拡大しています。しかし、数十億、数百億のパラメータを持つモデルをローカル環境で動かすには、通常、膨大な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推論エンジンです。元々は Meta の LLaMA モデルを Apple Silicon (M1/M2 Mac) 上で高速に動作させることを目的として誕生しましたが、現在では様々なアーキテクチャやモデルをサポートしています。

最大の特徴は、外部依存関係を持たない純粋な C/C++ 実装 である点です。Python や PyTorch などの巨大なエコシステムを必要とせず、単一の実行ファイルとしてコンパイルできるため、デプロイが非常に容易です。

この llama.cpp の心臓部となっているのが、テンソル演算ライブラリ ggml です。ggmlは機械学習における行列演算をCPU（および一部GPU）上で極限まで最適化するためにゼロから設計されています。

1.1 なぜ llama.cpp は速いのか？

メモリマッピング (mmap) の活用: モデルの重みをメモリにロードする際、OSの 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$（生成フェーズでは1トークンずつ処理するため $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["User Input (String)"] --> B["llama.cpp Tokenizer"] B --> C["Token IDs (int32 array)"] C --> D["Context Buffer (KV Cache)"] D --> E["ggml Compute Graph"] E --> F["Transformer Layers"] subgraph "ggml Engine" F --> G["Self-Attention (RoPE)"] G --> H["Feed Forward Network"] H --> F end F --> I["Logits (Vocabulary Size)"] I --> J["Sampler (Temperature, Top-K, Top-P)"] J --> K["Selected Token ID"] K --> L["llama.cpp Detokenizer"] L --> M["Output String"] K -. "Auto-regressive loop" .-> D

テキスト生成は、1つのトークンが出力されるたびに、それが次の入力として 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; // 最大コンテキストサイズ (トークン数)
 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（トークン）の羅列として処理します。入力文字列をトークンに変換する必要があります。

 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); // 余裕を持たせたバッファサイズ

 // 特殊トークン（BOS: Begin of Sequence 等）を先頭に追加するかどうか
 bool add_special = true;
 // 文字列をトークン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 推論ループとサンプリング

トークンをモデルに入力し、次のトークンの確率分布（Logits）を取得し、そこからサンプリングを行って次のトークンを決定するループを構築します。

 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


 // 生成する最大トークン数
 const int max_gen_tokens = 100;

 // バッチ評価のための構造体を初期化
 llama_batch batch = llama_batch_init(512, 0, 1);

 // プロンプトのトークンをバッチに追加
 for (size_t i = 0; i < tokens_list.size(); i++) {
 llama_batch_add(batch, tokens_list[i], i, { 0 }, false);
 }
 // プロンプトの最後のトークンでのみロジット（予測結果）を出力するように設定
 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. サンプリング：現在のコンテキストに基づいて次のトークンを予測
 llama_token new_token_id = llama_sampler_sample(smpl, ctx, -1);

 // 2. トークンが EOS (End of Sequence) ならループ終了
 if (llama_token_is_eog(model, new_token_id)) {
 break;
 }

 // 3. トークンを文字列（テキスト）にデコードして表示
 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. 新しく生成されたトークンを次のバッチとして準備
 llama_batch_clear(batch);
 llama_batch_add(batch, new_token_id, n_cur, { 0 }, true);

 // 5. モデルの評価（KVキャッシュを更新し、次を予測）
 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 構造体を用いてトークン群を管理し、llama_decode でニューラルネットワークのフォワードパス（順伝播）を実行します。

6. 高度なカスタマイズ事例: C++ によるロジット操作とペナルティ制御

単純なテキスト生成にとどまらず、特定フォーマット（例えば JSON のみ）の出力を強制させたり、特定の禁止ワードを出力させないように制御したりする場合、サンプリング前の ロジット（Logits） を C++ 側で直接操作します。

モデルが各トークンを出力する直前の生のスコア（確率に変換される前の値）の配列を取得できます。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 推論直後、サンプリングを行う前に生のロジット配列を取得
float * logits = llama_get_logits_ith(ctx, batch.n_tokens - 1);
int n_vocab = llama_n_vocab(model);

// 禁止トークンのIDリスト（例として 1234, 5678）
std::vector<llama_token> forbidden_tokens = { 1234, 5678 };

// 禁止トークンの出現確率を 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 計算を高速化できます。長いコンテキスト（数万トークン）を扱う場合には必須の設定です。
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)