LLM on kenji.blog

如何在本地环境中最快地微调 TinyLLaMA

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

1. 引言：为什么现在选择 TinyLLaMA 和本地部署？

大型语言模型（LLM）的演进正以惊人的速度推进，随之而来的是模型参数量也持续膨胀至数千亿规模。虽然像 GPT-4 和 Claude 3 这样的超大型模型拥有无与伦比的性能，但推理和训练所需的计算成本，以及使用外部 API 时存在的安全和数据隐私隐患，成为了企业面临的巨大障碍。特别是在处理高机密性的内部数据或个人信息的业务中，从合规性（如 GDPR、APPI 等）的角度来看，将数据发送到云端公开的 LLM API 往往是不可接受的。

因此，备受瞩目的是小型语言模型（SLM: Small Language Models）以及本地环境部署（On-Premises）。其中，“TinyLLaMA”以仅 1.1B（11亿）参数的紧凑尺寸，却拥有在约 3 万亿 Token 的庞大数据集上预训练的底蕴，与同级别的模型相比，展现出惊人的性能。

本文将提供一份完整指南，教你如何在本地环境（本地服务器或工作站）中，针对公司专属任务，以“最快且最高效”的方式对 TinyLLaMA 进行微调（Fine-Tuning）。从数学背景到最新的优化技术，再到具体的 PyTorch 实现代码，我们将进行全面的讲解。

2. TinyLLaMA 的架构与特点

TinyLLaMA 沿用了 Meta 公司开发的 LLaMA（Large Language Model Meta AI）架构。在将参数量控制在 1.1B 的同时，使用了与 LLaMA 2 相同的技术栈，因此其生态系统兼容性极高。

主要架构组件

RMSNorm (Root Mean Square Normalization): 省略了传统 LayerNorm 计算中减去均值的步骤，是一种提高了计算效率的归一化方法。它在保持训练稳定性的同时提升了吞吐量。
SwiGLU 激活函数: 在前馈神经网络 (FFN) 中，采用了 SwiGLU 替代传统的 ReLU 或 GELU。其数学表达式如下： $$ \text{SwiGLU}(x, W, V) = \text{Swish}(xW) \otimes (xV) $$ 这里，$\otimes$ 表示逐元素乘积（Hadamard 积），Swish 函数为 $\text{Swish}(z) = z \cdot \sigma(\beta z)$。这大幅提升了模型的表达能力。
RoPE (Rotary Position Embedding): 结合了绝对位置编码和相对位置编码优点的技术。即使在序列长度扩展时，也具有很高的泛化性能。
Grouped Query Attention (GQA): 介于多头注意力 (MHA) 和多查询注意力 (MQA) 之间的一种方法，通过将键 (Key) 和值 (Value) 的注意力头进行分组，节省了内存带宽并显著提高了推理速度。

下面的 Mermaid 图展示了 TinyLLaMA 的整体数据流和 Transformer 块的结构。

graph TD A["输入文本 (Input Text)"] --> B["分词器 (Tokenizer, BPE)"] B --> C["嵌入层 (Embedding Layer)"] C --> D["Transformer 块 (TinyLLaMA 为 22 层)"] D --> E["最终归一化 (RMSNorm, Final)"] E --> F["线性投影 (Linear Projection, 词表大小)"] F --> G["输出概率 (Output Probabilities, Softmax)"] subgraph "Transformer 块结构 (Transformer Block Anatomy)" D1["输入隐藏状态 (Input Hidden State)"] --> D2["RMSNorm"] D2 --> D3["分组查询注意力 (Grouped Query Attention, GQA)"] D3 --> D4["残差连接 (Residual Add)"] D4 --> D5["RMSNorm"] D5 --> D6["SwiGLU 前馈网络 (SwiGLU FFN)"] D6 --> D7["残差连接 (Residual Add)"] D7 --> D8["输出到下一层 (Output to Next Layer)"] D1 -.-> D4 D4 -.-> D7 end

3. 微调的突破口：LoRA 与 QLoRA

在本地环境中进行全参数微调，即使是 1.1B 的模型，为了保存优化器状态和梯度，也会消耗数十 GB 的 VRAM（显存）。为了在有限资源下高效地进行训练，必须使用 PEFT (Parameter-Efficient Fine-Tuning, 参数高效微调) 技术中的“LoRA”及其量化扩展版本“QLoRA”。

3.1 LoRA (Low-Rank Adaptation) 的数学背景

LoRA 是一种将预训练权重矩阵固定（冻结），并将其权重的更新量（$\Delta W$）近似为两个低秩小矩阵乘积的方法。

设预训练权重为 $W_0 \in \mathbb{R}^{d \times k}$。在全参数微调中，会直接更新 $W_0$ 得到 $W_0 + \Delta W$，而在 LoRA 中，更新矩阵 $\Delta W$ 被分解如下：

$$ \Delta W = B \times A $$

这里，$B \in \mathbb{R}^{d \times r}$，$A \in \mathbb{R}^{r \times k}$，而 $r$ 被称为秩 (Rank)，是一个超参数，它是一个非常小的值（通常为 8, 16, 32 等），满足 $r \ll \min(d, k)$。

前向传播的计算如下所示：

$$ h = W_0 x + \Delta W x = W_0 x + B A x $$

在初始状态下，矩阵 $A$ 会以正态分布（高斯分布）随机初始化，而矩阵 $B$ 则被初始化为零矩阵。因此，训练开始时的 $\Delta W$ 为零，这样就可以在完全保留基础模型输出的状态下开始训练。

graph LR X["输入向量 x (Input Vector x)"] --> W0["冻结的预训练权重 (Frozen Pre-trained Weight, W_0)"] X --> A["可训练的 LoRA 矩阵 A (Trainable LoRA Matrix A, r x k)"] A --> B["可训练的 LoRA 矩阵 B (Trainable LoRA Matrix B, d x r)"] W0 --> Add["向量加法 (Vector Addition)"] B --> Add Add --> Y["输出向量 h (Output Vector h)"]

3.2 QLoRA (Quantized LoRA) 的创新性

QLoRA 进一步推进了 LoRA 的方法，它将基础模型 $W_0$ 量化为 4-bit 精度（NormalFloat 4, NF4）加载到内存中。这极大地减少了 VRAM 的消耗。

QLoRA 融入了 3 项关键技术：

4-bit NormalFloat (NF4) 量化: 一种在理论上最优的数据类型，针对服从正态分布的权重进行了优化。
Double Quantization (双重量化): 对量化常数（缩放因子）本身再次进行量化，从而进一步节省内存。
Paged Optimizers: 利用 NVIDIA 的统一内存功能，在 VRAM 不足时，将优化器的状态暂时转移到 CPU 的 RAM 中。

通过这些技术，通常需要 16GB 到 24GB VRAM 的微调任务，现在即使在消费级显卡（如 RTX 3060 12GB 或 RTX 4070）上也能轻松运行。

4. 本地环境的硬件要求与环境搭建

使用 QLoRA 微调 TinyLLaMA (1.1B) 时的硬件要求可以控制得非常低。

软件环境搭建

以下是假设使用 Ubuntu 22.04 LTS 环境的搭建步骤。使用 Python 3.10 及以上版本。

1
2
3
4
5
6
7
8
9


# 创建并激活虚拟环境
python3 -m venv tinyllama_env
source tinyllama_env/bin/activate

# 安装 PyTorch (适用于 CUDA 12.1)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 安装 Transformer 相关的库
pip install transformers datasets peft trl accelerate bitsandbytes

5. 实现最快微调的优化技术

仅仅运行脚本是不够的，为了“最快”地完成微调，需要结合以下优化方法。

5.1 Flash Attention 2

标准的注意力机制的时间和空间复杂度相对于序列长度 $N$ 呈 $O(N^2)$ 增长。Flash Attention 2 通过优化 GPU 的 SRAM 和 HBM（高带宽内存）之间的内存访问，在不减少计算量的情况下消除了 I/O 瓶颈，将训练速度提升数倍，并大幅降低了内存消耗。

5.2 Gradient Checkpointing (梯度检查点)

在前向传播计算出的中间激活值并不全部保存在 VRAM 中，而是仅保存一部分，在反向传播需要时再重新计算。虽然计算时间会增加约 20%，但可以大幅减少内存消耗，从而可以设置更大的 Batch Size，最终提升整体吞吐量。

5.3 Mixed Precision Training (混合精度训练) 与 Bfloat16

为了充分利用 GPU 的 Tensor Core，在训练时使用 bfloat16 (Brain Floating Point) 进行计算。与 float16 相比，它的指数部分位数与 float32 相同，因此发生上溢或下溢的风险极低，训练过程更加稳定。

6. 实践：TinyLLaMA 的 QLoRA 微调代码

接下来，我们将讲解融合了上述所有优化技术的 PyTorch 脚本，以实现最快微调。这里使用 Hugging Face trl (Transformer Reinforcement Learning) 库中的 SFTTrainer。

6.1 准备数据集与加载模型

 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


import torch
from datasets import load_dataset
from transformers import (
 AutoModelForCausalLM,
 AutoTokenizer,
 BitsAndBytesConfig,
 TrainingArguments
)
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
from trl import SFTTrainer

# 1. 指定模型和分词器
model_id = "TinyLlama/TinyLlama-1.1B-Chat-v1.0"

# 2. QLoRA 的 4-bit 量化配置
bnb_config = BitsAndBytesConfig(
 load_in_4bit=True,
 bnb_4bit_use_double_quant=True,
 bnb_4bit_quant_type="nf4",
 bnb_4bit_compute_dtype=torch.bfloat16 # 使用 bfloat16 进行计算
)

# 3. 加载模型 (启用 Flash Attention 2)
print("Loading model...")
model = AutoModelForCausalLM.from_pretrained(
 model_id,
 quantization_config=bnb_config,
 device_map="auto",
 use_flash_attention_2=True # 实现最快速度的关键
)

# 4. 加载分词器
tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
tokenizer.pad_token = tokenizer.eos_token
tokenizer.padding_side = "right" # 设置为 right 以避免 fp16/bf16 训练时的 bug

6.2 应用 LoRA 适配器与格式化数据集

 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


# 5. 准备 k-bit 训练并启用梯度检查点
model.gradient_checkpointing_enable()
model = prepare_model_for_kbit_training(model)

# 6. LoRA 配置
peft_config = LoraConfig(
 r=16, # 秩
 lora_alpha=32, # 缩放因子
 lora_dropout=0.05,
 bias="none",
 task_type="CAUSAL_LM",
 target_modules=["q_proj", "k_proj", "v_proj", "o_proj", "gate_proj", "up_proj", "down_proj"] # 以所有 Linear 层为目标可以提升性能
)

model = get_peft_model(model, peft_config)
model.print_trainable_parameters()
# 输出示例: trainable params: 14,286,848 || all params: 1,114,335,232 || trainable%: 1.282%

# 7. 加载数据集 (此处以日语 Instruction 数据集为例)
# 实际操作中可加载本地环境下的私有 JSONL 文件等
dataset = load_dataset("kunishou/databricks-dolly-15k-ja", split="train")

def format_instruction(sample):
 """
 根据 ChatML 格式或提示词模板对字符串进行格式化
 """
 prompt = f"<|im_start|>user\n{sample['instruction']}"
 if sample.get("input", "") != "":
 prompt += f"\n{sample['input']}"
 prompt += f"<|im_end|>\n<|im_start|>assistant\n{sample['output']}<|im_end|>"
 return {"text": prompt}

dataset = dataset.map(format_instruction)

6.3 执行训练

 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


# 8. 设置训练参数
training_args = TrainingArguments(
 output_dir="./tinyllama-lora-output",
 per_device_train_batch_size=8, # 如果 VRAM 充足可以调高
 gradient_accumulation_steps=2, # 实际 Batch Size = 8 * 2 = 16
 optim="paged_adamw_32bit", # 使用 Paged Optimizer 节省 VRAM
 save_steps=100,
 logging_steps=10,
 learning_rate=2e-4,
 fp16=False,
 bf16=True, # 混合精度训练 (bfloat16)
 max_grad_norm=0.3,
 max_steps=500, # 用于测试的 500 步。正式训练时应指定 epoch 数
 warmup_ratio=0.03,
 group_by_length=True,
 lr_scheduler_type="cosine",
)

# 9. 使用 SFTTrainer 开始训练
trainer = SFTTrainer(
 model=model,
 train_dataset=dataset,
 peft_config=peft_config,
 dataset_text_field="text",
 max_seq_length=1024, # 根据预期的输入长度进行调整
 tokenizer=tokenizer,
 args=training_args,
)

print("Starting training...")
trainer.train()

# 10. 保存 LoRA 适配器
trainer.model.save_pretrained("./tinyllama-lora-final")
tokenizer.save_pretrained("./tinyllama-lora-final")
print("Training complete and model saved.")

7. 性能评估与故障排除

在本地环境中进行训练时，常遇到的问题及其解决方案如下：

发生 OOM (Out Of Memory):
- 将 per_device_train_batch_size 降至 1。
- 增加 gradient_accumulation_steps 以维持实际的 Batch Size。
- 将 max_seq_length 从 2048 缩短至 1024 或 512。
Loss 降不下来或发生发散:
- 学习率 (learning_rate) 可能设置过大。尝试将其从 2e-4 降低到 5e-5 左右。
- 如果使用的是 Float16 而不是 Bfloat16，可能会发生梯度下溢。请确保设置了 bf16=True。
推理时生成乱码字符:
- 请确认 padding_side="right" 是否设置正确。此外，还需检查数据集的格式（如 <|im_start|> 等特殊 Token）是否与基础模型预训练时保持一致。

8. 微调后的模型部署 (Deployment)

微调完成后，保存的并不是“整个基础模型”，而是仅有几 MB 到几十 MB 的“LoRA 适配器（权重差值）”。为了能够高速地进行推理，需要将这个 LoRA 权重与原始的基础模型合并，并导出为一个单一的模型。

模型合并脚本

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


import torch
from peft import AutoPeftModelForCausalLM
from transformers import AutoTokenizer

output_dir = "./tinyllama-lora-final"

# 以 FP16/BF16 精度加载模型和适配器
model = AutoPeftModelForCausalLM.from_pretrained(
 output_dir,
 device_map="auto",
 torch_dtype=torch.bfloat16
)
tokenizer = AutoTokenizer.from_pretrained(output_dir)

# 合并权重并保存
merged_model = model.merge_and_unload()
merged_model.save_pretrained("./tinyllama-merged", safe_serialization=True)
tokenizer.save_pretrained("./tinyllama-merged")
print("Model merged and saved successfully!")

使用 vLLM 启动极速推理服务器

在本地环境中进行部署时，为了最大化推理速度（Tokens per second），强烈建议不使用 Hugging Face 标准的 pipeline，而是使用 vLLM 或 TGI (Text Generation Inference)。vLLM 采用了 PagedAttention 技术，可防止 GPU 内存碎片化，从而大幅提升并发请求的处理能力。

下面的 Mermaid 图展示了从训练到部署推理服务器的流程。

graph TD A["原始私有数据 (Raw Private Data)"] --> B["预处理与格式化 (Preprocessing & Formatting, JSONL)"] B --> C["QLoRA 微调 (QLoRA Fine-Tuning, SFTTrainer)"] C --> D["LoRA 适配器权重 (LoRA Adapter Weights, .safetensors)"] D --> E["与基础 TinyLLaMA 1.1B 合并 (Merge with Base TinyLLaMA 1.1B)"] E --> F["合并后的模型 (Merged Model)"] F --> G["通过 vLLM 服务器部署 (Deploy via vLLM Server)"] G --> H["API 端点 / 用户界面 (API Endpoint / UI, 如聊天机器人)"]

使用 vLLM 启动 API 服务器只需以下一条命令即可完成。

1
2
3
4
5
6


python -m vllm.entrypoints.openai.api_server \
 --model ./tinyllama-merged \
 --host 0.0.0.0 \
 --port 8000 \
 --max-model-len 2048 \
 --dtype bfloat16

这样一来，就能够在本地环境中构建一个兼容 OpenAI API 的端点，让你能够安全且高速地利用本地 AI。

9. 总结

本文以参数量仅 1.1B 但性能强悍的“TinyLLaMA”为对象，详细解说了在本地环境中最快且内存高效地进行微调的方法。

借助 LoRA / QLoRA，即使在消费级 GPU 上也能进行正式的 LLM 微调。
充分利用 Flash Attention 2 和 Gradient Checkpointing，将训练时间和 VRAM 消耗优化到极致。
通过使用 vLLM 进行部署，在生产环境中也能实现高吞吐量。

在本地运行本地 LLM，不仅能保护数据的机密性，更是低成本构建特定领域（如法务、医疗、公司章程等）专用 AI 的最强武器。希望你能以此指南为参考，培养出专属于你公司的 TinyLLaMA。

使用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的未来。

【RAG入门指南】如何让本地AI读取你的专属文档

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

前言

近年来，大型语言模型（LLM）的进化引人瞩目，以ChatGPT和Claude等为首的众多AI已经渗透到我们的生活和工作中。然而，通用的LLM存在一个明显的弱点。那就是它们只知道“训练时的公开信息”。对于公司内部规定、个人笔记、未公开的项目资料等“私密文档”相关的问题，它们理所当然地无法回答。如果强行让它们回答，产生听起来很有道理但与事实不符的谎言（幻觉/Hallucination）的风险就会增加。

因此，目前在全世界爆发性普及的是**RAG（Retrieval-Augmented Generation：检索增强生成）**这一技术架构。通过使用RAG，可以动态地从外部数据库向LLM提供专有知识，并让其基于这些知识生成准确且有根据的回答。

此外，在处理企业领域或个人机密信息时，将数据发送到OpenAI等基于云的API在安全策略上往往是不被允许的。因此，我们需要构建结合了本地AI（在自己的PC或本地服务器上完全运行的LLM）的“本地RAG”。

本文将从RAG的基础理论开始，彻底解说使用Python构建本地RAG的具体实现方法、数学背景（向量检索的原理），以及使系统在生产环境中运行的高级技巧。

1. RAG的整体架构

RAG不是单一的AI模型，而是一个由多个组件协同工作的系统架构。它大致分为“摄取（数据导入）阶段”和“检索与生成（Retrieval & Generation）阶段”两部分。

以下Mermaid图展示了RAG系统的全貌。

graph TD subgraph "摄取阶段 (事前准备)" Doc["专属文档 (PDF, TXT, etc.)"] --> Loader["文档加载器"] Loader --> Splitter["文本分割 (分块/Chunking)"] Splitter --> EmbedModel1["嵌入模型 (Embedding)"] EmbedModel1 --> VectorDB["向量数据库"] end subgraph "推理阶段 (用户查询时)" User["来自用户的提问 (查询/Query)"] --> EmbedModel2["嵌入模型 (Embedding)"] EmbedModel2 --> QueryVector["查询向量"] QueryVector --> Search["相似度检索 (向量检索)"] VectorDB --> Search Search --> Context["相关分块提取 (上下文/Context)"] User --> PromptBuilder["构建提示词"] Context --> PromptBuilder PromptBuilder --> LocalLLM["本地LLM"] LocalLLM --> Answer["生成最终回答"] end

摄取阶段（事前准备）

加载文档：读取PDF、Word、文本文件等非结构化数据。
分块（文本分割）：为了适应LLM的输入限制（上下文窗口），并提高检索精度，将长文章分割成有意义的块（Chunk）。
嵌入（向量化）：将分割好的块输入到嵌入模型（Embedding Model）中，并将其转换为数百到数千维的数值数组（向量）。
保存到数据库：将转换后的向量与原始文本数据关联，并保存到向量数据库（Vector DB）中。

推理阶段（运行时）

查询的向量化：使用与事前准备相同的嵌入模型，将用户的提问文本向量化。
相似度检索：在查询向量和数据库中的文档向量之间进行相似度计算，获取几条语义上最接近（相关性最高）的文本块。
构建提示词：将获取的相关文本作为“上下文（背景知识）”与用户的提问文本结合，创建输入给LLM的提示词（Prompt）。
生成回答：接收到增强提示词的LLM，基于附加的上下文信息生成回答。

2. 深入理解向量检索与嵌入（Embeddings）

构成RAG核心的是“向量检索（语义检索）”。与传统的基于单词完全匹配或频率的关键字检索（如BM25）不同，向量检索基于“语义的相似性”。例如，“狗”和“小狗”、“PC”和“电脑”，即使是不同的单词，只要意思相近就会被检索到。

什么是嵌入模型（Embedding Model）？

嵌入模型是一种神经网络，它接收自然语言文本作为输入，并输出固定长度的稠密向量（Dense Vector）。一般的模型（例如 text-embedding-3-small 或开源的 multilingual-e5-large）会将文本映射为384维或1024维的实数向量。

在这个多维空间（潜在空间）中，模型被训练为：意思越相似的文章，在坐标空间上的距离越近。

相似度计算的数学背景：余弦相似度

当向量数据库检索相关文档时，最常用的距离指标是余弦相似度（Cosine Similarity）。与欧几里得距离（空间上的绝对距离）不同，余弦相似度关注“两个向量之间的夹角”。因为它不容易受文章长度（向量的范数）影响，所以非常适合计算文本的相似度。

用数学公式表示，向量 $\mathbf{A}$ 和 $\mathbf{B}$ 的余弦相似度如下所示：

$$ \text{Cosine Similarity}(\mathbf{A}, \mathbf{B}) = \cos(\theta) = \frac{\mathbf{A} \cdot \mathbf{B}}{\|\mathbf{A}\| \|\mathbf{B}\|} = \frac{\sum_{i=1}^{n} A_i B_i}{\sqrt{\sum_{i=1}^{n} A_i^2} \sqrt{\sum_{i=1}^{n} B_i^2}} $$

$\mathbf{A} \cdot \mathbf{B}$ 表示内积（Dot Product）。
$\|\mathbf{A}\|$ 表示向量 $\mathbf{A}$ 的L2范数（长度）。
$n$ 是向量的维数。

余弦相似度的取值范围是 -1 到 1。

接近 1：两个向量的方向几乎相同（意思非常相似）
接近 0：两个向量正交（无关）
接近 -1：两个向量方向完全相反（意思相反）

最近的向量数据库（Chroma, FAISS, Qdrant等）采用了被称为HNSW（Hierarchical Navigable Small World）的近似最近邻搜索（ANN）算法，经过优化，即使在数百万条向量数据中，也能在毫秒级内检索出余弦相似度高的文档。

3. 构建本地RAG的技术栈

为了构建完全不依赖云端的本地RAG，我们将利用开源生态系统。以下是推荐的技术栈。

语言模型 (LLM)
- 工具：Ollama 或 Llama.cpp
- 模型：Llama-3-8B-Instruct、Gemma-2-9B-It、Qwen2-7B-Instruct 等轻量且高性能的开源模型。对于日语任务，经过日语微调的 Llama-3-ELYZA-JP-8B 等较为合适。
嵌入模型 (Embedding)
- 模型：intfloat/multilingual-e5-large 或 BAAI/bge-m3。在本地运行时，通常从Hugging Face下载并使用Sentence-Transformers来执行。
向量数据库 (Vector DB)
- ChromaDB：基于Python，设置极其简单。非常适合本地开发。
- FAISS：Meta开发的高速向量检索库。
- Qdrant / Milvus：规模更大，面向生产环境。
编排框架
- LangChain：用于连接（Chain）各组件的事实标准。
- LlamaIndex：特别专注于RAG的数据连接框架。

这次我们将使用最容易导入的 LangChain + ChromaDB + Ollama + HuggingFaceEmbeddings 组合来进行实现。

4. 实现教程：使用Python构建完整的本地RAG

接下来，我们将实际编写Python代码来构建本地RAG。请预先在PC上安装Ollama并在后台启动它。另外，在Ollama上拉取模型（例如：ollama run llama3）。

Step 1: 安装必要的库

1
2


pip install langchain langchain-community langchain-huggingface
pip install chromadb sentence-transformers pypdf

Step 2: 实现代码全貌

以下是一个完整的Python脚本，用于读取PDF文件，将其向量化，并让本地LLM进行问答。

 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


import os
from langchain_community.document_loaders import PyPDFLoader
from langchain_text_splitters import RecursiveCharacterTextSplitter
from langchain_huggingface import HuggingFaceEmbeddings
from langchain_community.vectorstores import Chroma
from langchain_community.llms import Ollama
from langchain_core.prompts import PromptTemplate
from langchain.chains import RetrievalQA

def main():
 # 1. 加载文档
 print("正在加载文档...")
 # 指定要读取的PDF的路径
 file_path = "sample_company_policy.pdf"
 loader = PyPDFLoader(file_path)
 documents = loader.load()

 # 2. 文本分块（Text Splitting）
 # 在不破坏文章含义的前提下，分割成适当的大小
 text_splitter = RecursiveCharacterTextSplitter(
 chunk_size=500, # 每个分块的最大字符数
 chunk_overlap=50, # 前后分块的重叠字符数（防止上下文断裂）
 separators=["\n\n", "\n", "。", "、", " ", ""]
 )
 chunks = text_splitter.split_documents(documents)
 print(f"已分割成 {len(chunks)} 个块。")

 # 3. 初始化嵌入模型 (Local HuggingFace Model)
 # 使用支持多语言的强大模型
 print("正在加载嵌入模型...")
 embeddings = HuggingFaceEmbeddings(
 model_name="intfloat/multilingual-e5-large",
 model_kwargs={'device': 'cpu'} # 如果有GPU，使用 'cuda' 或 'mps'
 )

 # 4. 构建向量数据库 (Chroma)
 print("正在构建向量数据库...")
 persist_directory = "./chroma_db"
 vectorstore = Chroma.from_documents(
 documents=chunks,
 embedding=embeddings,
 persist_directory=persist_directory
 )
 # 创建检索器（Retriever）。设置为获取排名前3的相关文档
 retriever = vectorstore.as_retriever(search_kwargs={"k": 3})

 # 5. 初始化本地LLM (Ollama)
 print("正在连接本地LLM...")
 # 必须事先通过 'ollama pull llama3' 等命令获取模型
 llm = Ollama(model="llama3")

 # 6. 定义提示词模板
 prompt_template = """你是一位熟悉公司规定和内部信息的优秀助手。
请仅使用以下提供的上下文（背景信息），用中文详细回答用户的问题。
如果你在上下文中找不到答案，请不要随意猜测，而是诚实地回答“根据提供的信息无法得知”。

【上下文】
{context}

【问题】
{question}

【回答】:
"""
 PROMPT = PromptTemplate(
 template=prompt_template,
 input_variables=["context", "question"]
 )

 # 7. 构建RAG链
 qa_chain = RetrievalQA.from_chain_type(
 llm=llm,
 chain_type="stuff",
 retriever=retriever,
 return_source_documents=True, # 设置是否返回信息源
 chain_type_kwargs={"prompt": PROMPT}
 )

 # 8. 执行提问
 query = "请告诉我关于远程办公的交通费报销条件。"
 print(f"\n问题: {query}\n")

 result = qa_chain.invoke({"query": query})

 print("【回答】")
 print(result['result'])
 print("\n---")
 print("【参考的信息源】")
 for doc in result['source_documents']:
 print(f"- 第 {doc.metadata.get('page', '未知')} 页: {doc.page_content[:50]}...")

if __name__ == "__main__":
 main()

代码要点解说

RecursiveCharacterTextSplitter: 这是在自然语言分割中最被推荐的分割器。它会尝试按照段落(\n\n)、行(\n)、句号(。)的顺序进行分割，在尽可能保持语义完整性的同时，使其适应指定的 chunk_size。通过设置 chunk_overlap，可以防止由于上下文边界被切断而导致的信息丢失。
HuggingFaceEmbeddings: intfloat/multilingual-e5-large 是一款非常强大的支持多语言的开源嵌入模型。你可以不使用云端API（如OpenAI的 text-embedding-ada-002 等），在本地内存中离线地将文本向量化。
ChromaDB: 因为它在内存中或作为本地存储（基于SQLite）运行，所以不需要建立复杂的数据库服务器。通过指定 persist_directory，可以在重新运行时跳过向量化过程，直接从磁盘读取数据库。

5. 高级RAG技术（Advanced RAG Techniques）

虽然使用上述教程构建的基础RAG系统（Naive RAG）也能运行，但在生产环境中如果要求很高的回答精度，就需要引入以下高级技术。

5.1 混合检索 (Hybrid Search)

向量检索擅长捕捉“语义”，但有时不擅长精确的关键字检索，比如“特定的专有名词”、“产品型号”、“员工ID”等。因此，将基于向量检索的语义检索和基于BM25算法等的关键字检索并行执行，然后对两者的结果进行打分并合并（使用倒数排名融合；RRF等方法），可以大幅减少检索遗漏。

5.2 重排 (Re-ranking)

向量检索速度很快，但它并不一定能准确评估上下文的语义契合度。为了提高检索精度，一般的管道流程如下：

初次检索 (First-stage Retrieval): 从向量数据库中，广泛而浅层地获取约20~30个相关分块。
重新评估 (Re-ranking): 使用被称为Cross-Encoder的另一种参数量更大的机器学习模型（例如：bge-reranker 等），输入用户查询和获取到的分块的配对，重新计算语义契合度分数。
筛选: 仅挑选出分数最高的3~5个作为最终的上下文，传递给LLM的提示词中。

通过这种方法，可以防止无关的噪声信息传递给LLM，从而大幅提高回答的精度（Precision）。

graph LR Query["查询"] --> VSearch["向量检索 (前20名)"] VSearch --> Reranker["重排模型 (Cross-Encoder)"] Query --> Reranker Reranker --> TopK["高精度的前3名"] TopK --> LLM["LLM生成"]

5.3 语义分块与父文档检索

有一种名为“Semantic Chunking”的方法，它不是按照固定字符数机械地分割文本，而是使用AI检测文章语义的转折点来进行分割。此外，“Parent Document Retriever（父文档检索）”这种方法，在检索时以非常小的单位（如句子等）进行向量化以实现高精度的检索，而在传递给LLM时，则传递包含该句子的“原始大段落（父文档）”，从而为LLM提供充足的上下文（Context）。

6. 本地RAG运行时的挑战与对策

在本地环境中构建和运行RAG时，存在一些特有的障碍。

VRAM（显存）枯竭: 为了让本地LLM以实用的速度（每秒数十个Token）运行，必须将模型加载到GPU的VRAM中。以fp16（16位浮点数）运行8B级别的模型大约需要16GB的VRAM。但是，通过使用**量化（Quantization）**技术（如GGUF、AWQ格式等，将其压缩为4bit或8bit的技术），即使是8GB的VRAM（如一般的游戏PC等）也能足够高速地运行。Llama.cpp和Ollama原生支持这些量化格式。
上下文窗口的限制: 如果检索获取到的上下文数量过多，可能会超出LLM的输入上限（Token限制），或者导致模型忘记中间部分的信息（Lost in the middle现象）。调整提取的分块数量，以及通过上述重排技术进行严格筛选是不可或缺的。
数据的时效性管理: 当源文档被更新时，向量数据库中对应文档的向量也必须进行更新或删除（CRUD操作）。因为ChromaDB支持基于文档ID的更新，所以通过管理文件的哈希值，并编写仅同步差异的批处理程序是非常实用的做法。

总结

RAG（检索增强生成）是一种强大的范式，它将AI从通用的助手进化为“你的专属专家”或“专注于公司内部业务的专家”。

我们了解到，即使在无法使用云服务、保密性要求极高的情况下，通过组合Ollama、LangChain、ChromaDB等开源生态系统，也能相对容易地构建出完全的“本地RAG”环境。

基于本文解说的向量空间的数学原理，以及文本分块、重排等高级方法，请务必尝试使用您自己的数据来开发原创的AI系统。本地AI的进化速度非常惊人，今天构建的系统，明天只需替换为更聪明的轻量级模型，就能在瞬间完成性能的升级。

本博客今后将继续发布关于AI技术和RAG的深度文章。如果您有任何问题或反馈，请务必在评论区留言。

ChatGPT・Gemini・Claude的API深度对比！应该选择哪一个？

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

ChatGPT・Gemini・Claude的API深度对比！应该选择哪一个？

AI技术的演进令人瞩目，尤其是在大型语言模型（LLM: Large Language Model）领域，OpenAI的ChatGPT（GPT系列）、Google的Gemini和Anthropic的Claude正在展开激烈的三足鼎立的霸权争夺。截至2026年，各家公司以几个月甚至几周为单位发布新模型和API功能，对于开发者和企业IT架构师来说，“应该将哪个API集成到产品中”这一问题，已成为左右项目成功与否的极其重要的决策。

本文将从开发者的视角，对这三大AI提供商的API进行深度对比和解读。内容不仅限于简单的规格罗列，还将涵盖架构设计、详细的计费结构、延迟（Latency）的数学分析、使用Python和Node.js的具体实现示例，以及提示词缓存（Prompt Caching）等最新的成本优化方法。

旨在为读者提供一份完整的指南，帮助您为自己的用例选择最合适的LLM API，并构建可扩展且成本高效的AI应用程序。

1. 各LLM API的哲学与设计理念

在进行技术选型时，首先了解各家公司是基于何种理念来构建模型和API的，这一点非常重要。

1.1 OpenAI (ChatGPT)

OpenAI以“实现通用人工智能（AGI）”为使命，始终引领着行业的通用标准。它提供了适应不同用例的多样化模型，如GPT-4o、GPT-4o-mini，以及擅长推理的o1模型等。其生态系统最为成熟，无论官方还是非官方的库和文档都最为丰富。

1.2 Google (Gemini)

Google秉承“AI First”的理念，以最大限度利用其自有基础设施（TPU网络）的可扩展性为武器。Gemini 1.5 Pro/Flash的最大特点是拥有高达200万Token的压倒性上下文窗口（Context Window），能够一次性处理超长文档或数小时的音视频。此外，它与Google Cloud (Vertex AI) 的深度集成对企业级用户也极具吸引力。

1.3 Anthropic (Claude)

Anthropic是由前OpenAI成员创立的企业，采用了独特的“Constitutional AI（合宪AI）”安全机制。Claude 3.5 Sonnet和Opus凭借其强大的推理能力、代码生成能力，尤其是“像人类一样自然的对话”和“极少的幻觉（Hallucination）”，获得了众多开发者的狂热支持。

2. 模型家族的规格深度对比

以下是截至2026年主力模型的规格对比。

提供商	主力模型	最大上下文长度	主要优势	推荐用例
OpenAI	GPT-4o	128K	速度、视觉识别、语音支持	交互式应用、通用任务
OpenAI	o1-preview	128K	高级逻辑推理、数学、编程	复杂算法生成、研究用途
Google	Gemini 1.5 Pro	2,000K	超长文本处理、多模态（视频・音频）	庞大代码库分析、视频摘要
Google	Gemini 1.5 Flash	2,000K	低延迟、高吞吐量、绝对的低成本	实时处理、海量数据批量处理
Anthropic	Claude 3.5 Sonnet	200K	编程能力、自然的文本生成	软件开发辅助、高级客户支持
Anthropic	Claude 3.5 Haiku	200K	超极速响应、高性价比	边缘AI、实时聊天机器人

3. 架构深度剖析：API请求的幕后

调用LLM的API时，后端究竟在进行怎样的处理？为了优化性能，我们必须了解这一架构。

以下的Mermaid图表展示了从客户端发送API请求到以流式（Streaming）返回Token的全过程。

graph TD A["客户端应用程序"] -->|HTTP/REST 或 gRPC| B["API网关"] B --> C["负载均衡器"] C --> D["推理集群"] D --> E["分词器 (BPE / SentencePiece)"] E --> F["KV缓存与注意力机制"] F --> G["Transformer块 (前向传播)"] G --> H["输出层 (Logits)"] H --> I["采样器 (Temperature, Top-p, Top-k)"] I --> J["反分词器"] J -->|流式响应 (Chunk)| A

3.1 Tokenization（分词）的算法

输入到API的文本，在内部会被分割为名为“Token”的单位。

OpenAI (tiktoken): 采用 Byte-Pair Encoding (BPE)。特别是在英语方面压缩效率极高，但在日语等非字母语言中，Token数量往往会膨胀。
Google (Gemini): 采用 SentencePiece（Unigram Language Model）。在多语言处理上具有优势，即使是日语文本也能以相对较少的Token数量来表达。
Anthropic (Claude): 使用定制版的BPE。强化了多语言支持，Claude 3以后，日语的Token效率也得到了大幅提升。

4. 延迟与性能的数学分析

在实时应用程序中，延迟（Latency）直接影响用户体验（UX）。LLM API的延迟 $T_{total}$ 在数学上可以建立如下模型：

$$ T_{total} = T_{network} + T_{TTFT} + (N \times T_{TPOT}) $$

这里，各变量的含义如下：

$T_{network}$: 网络的往返时间（RTT）。
$T_{TTFT}$ (Time To First Token): 生成第一个字符所需的时间。它很大程度上取决于注意力计算的成本，该成本与提示词长度（输入Token数）的平方成正比。
$N$: 输出的Token总数。
$T_{TPOT}$ (Time Per Output Token): 每个Token的生成时间。因为是自回归（Autoregressive）模型，所以需要依赖之前的输出进行串行计算。

4.1 自注意力机制的计算复杂度

Transformer架构中的自注意力（Self-Attention）计算复杂度，相对于输入序列长度 $L$ 呈二次函数增长。

$$ \text{Complexity} = O(L^2 \cdot d) $$

这里的 $d$ 是嵌入向量的维度数。由于这一限制，通常当提示词变长时，$T_{TTFT}$ 会急剧恶化。然而，Google的Gemini 1.5采用了“Ring Attention”和“Block-wise Compute”等创新性的优化架构，即使输入200万Token的长文，也能成功在现实的时间内（几秒到几十秒）生成第一个Token。

5. 计费体系与成本优化策略

API的成本基本上是基于输入Token数和输出Token数来计算的。

$$ Cost = (Tokens_{in} \times Rate_{in}) + (Tokens_{out} \times Rate_{out}) $$

但是，最新的API引入了大幅降低成本的新机制。

5.1 提示词缓存 (Prompt Caching)

如果每次都发送超长的系统提示词或通过RAG检索到的大量文档，将会产生巨大的成本。为了解决这个问题，各家都提供了缓存功能。

在Anthropic (Claude) 和 Google (Gemini) 中，通过缓存特定的文本块，可以大幅削减（最高达90%）输入成本。

使用缓存时的成本模型如下：

$$ Cost_{cached} = (Tokens_{cache\_write} \times Rate_{cache\_write}) + (Tokens_{cache\_read} \times Rate_{cache\_read}) + (Tokens_{out} \times Rate_{out}) $$

这里的 $Rate_{cache\_read}$ 通常被设定为常规 $Rate_{in}$ 的10%〜25%左右。借此，我们可以将数万行的代码库始终作为背景知识保留，并以低廉的价格运营聊天机器人。

5.2 批处理API (Batch API)

对于不需要实时性的任务（如日志分析、海量数据分类等），OpenAI和Anthropic提供了批处理（Batch）API。您可以将请求打包发送，并在24小时内接收结果，作为交换，可以享受到正常API价格一半（50%折扣）的优惠。这是一种非常强大的机制。

6. 开发者体验（DX）与SDK对比

从开发效率的角度，我们来对比各家提供的SDK（Software Development Kit）。

6.1 OpenAI API

使用最广泛，第三方库（LangChain, LlamaIndex等）的支持也最快。此外，通过Structured Outputs（结构化输出）功能，保证了返回的响应能够100%精准地遵循JSON Schema，这使得系统集成变得异常简单。

6.2 Anthropic API (Claude)

SDK接口经过精心设计，TypeScript的类型定义等备受好评，非常易于使用。特别是Message API的结构非常直观，即使是包含多张图片的多模态请求也能通过简单的代码实现。

6.3 Google Gemini API

存在通过Google Cloud Vertex AI访问和通过AI Studio访问（Google Gen AI SDK）这两种途径，初学者可能会感到有些困惑。然而，面向企业的Vertex AI SDK与GCP的IAM（身份与访问管理系统）完全集成，可以构建出高度安全的开发环境。

7. 实战！使用Python实现多个API的集成测试

在这里，我们将使用Python编写一个脚本，同时向OpenAI、Anthropic和Gemini这三个API发送异步请求，以比较它们的延迟。

 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


import asyncio
import time
import os
from openai import AsyncOpenAI
from anthropic import AsyncAnthropic
import google.generativeai as genai

# 初始化客户端
openai_client = AsyncOpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
anthropic_client = AsyncAnthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))
genai.configure(api_key=os.environ.get("GEMINI_API_KEY"))

prompt = "请为初学者通俗易懂地讲解量子计算机的基础，以及它对现有密码技术的影响。"

async def fetch_openai():
 start_time = time.time()
 response = await openai_client.chat.completions.create(
 model="gpt-4o",
 messages=[{"role": "user", "content": prompt}],
 max_tokens=1024
 )
 elapsed = time.time() - start_time
 return "OpenAI (GPT-4o)", elapsed, response.choices[0].message.content

async def fetch_anthropic():
 start_time = time.time()
 response = await anthropic_client.messages.create(
 model="claude-3-5-sonnet-20240620",
 messages=[{"role": "user", "content": prompt}],
 max_tokens=1024
 )
 elapsed = time.time() - start_time
 return "Anthropic (Claude 3.5 Sonnet)", elapsed, response.content[0].text

async def fetch_gemini():
 start_time = time.time()
 model = genai.GenerativeModel('gemini-1.5-pro')
 # 使用Gemini Python SDK的异步方法
 response = await model.generate_content_async(prompt)
 elapsed = time.time() - start_time
 return "Google (Gemini 1.5 Pro)", elapsed, response.text

async def main():
 print("正在向各LLM API发送请求...")

 # 并行执行3个API
 results = await asyncio.gather(
 fetch_openai(),
 fetch_anthropic(),
 fetch_gemini()
 )

 for provider, latency, text in results:
 print(f"--- {provider} ---")
 print(f"Latency: {latency:.2f} seconds")
 print(f"Response (Excerpt): {text[:100]}...\n")

if __name__ == "__main__":
 asyncio.run(main())

通过运行这个脚本，可以很容易地测试出在实际网络环境中，哪个模型能够最快地（即 $T_{total}$ 最小化）做出响应。

8. 使用Node.js实现工具调用（Tool Calling / Function Calling）

为了让LLM不仅是一个聊天机器人，而是作为一个能与外部系统协同工作的“AI智能体（AI Agent）”发挥作用，工具调用（Tool Calling 或 Function Calling）是必不可少的。以下是使用Node.js（TypeScript）让OpenAI的API调用天气API的示例。

 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


import OpenAI from "openai";

const openai = new OpenAI({
 apiKey: process.env.OPENAI_API_KEY,
});

async function runAgent() {
 const tools = [
 {
 type: "function",
 function: {
 name: "get_weather",
 description: "获取指定城市的当前天气。",
 parameters: {
 type: "object",
 properties: {
 location: {
 type: "string",
 description: "城市名称（例如：东京，纽约）",
 },
 },
 required: ["location"],
 },
 },
 },
 ];

 const response = await openai.chat.completions.create({
 model: "gpt-4o",
 messages: [{ role: "user", "content": "今天东京的天气怎么样？需要带伞吗？" }],
 tools: tools,
 tool_choice: "auto",
 });

 const message = response.choices[0].message;

 if (message.tool_calls) {
 const toolCall = message.tool_calls[0];
 console.log(`LLM请求了工具调用: 函数名 = ${toolCall.function.name}`);

 const args = JSON.parse(toolCall.function.arguments);
 console.log(`参数: ${args.location}`);

 // 在这里实现调用实际天气API（例：OpenWeatherMap）的处理
 // const weather = await fetchWeatherFromAPI(args.location);

 // 将获取到的结果再次传递给LLM，以生成最终的回答
 }
}

runAgent().catch(console.error);

Claude 3.5 Sonnet和Gemini 1.5 Pro也具备同等的Tool Calling功能，虽然在Schema的定义方法上略有不同，但基本流程是相通的。

9. RAG vs 超长上下文窗口：应该采用哪一个？

目前，企业级AI架构中最大的争论之一是：“为了引入外部知识，应该使用RAG（检索增强生成），还是应该全权交给庞大的上下文窗口（Long Context）？”

RAG (Retrieval-Augmented Generation) 的优势与挑战

优势: 成本低（因为只将需要的块放入提示词中），回答的依据（来源）容易确定。
挑战: 依赖于语义搜索的准确度，因此对于那些上下文散落在多篇文档中的高级推理任务（例：“根据去年全年的会议记录，按时间序列分析A项目延期的根本原因”），表现并不理想。

超长上下文 (例如Gemini 1.5 Pro的200万Token)

优势: 不会因为检索而遗漏信息。在“大海捞针（Needle In A Haystack: NIAH）”测试中，Gemini 1.5 Pro和Claude 3.5 Sonnet也能以99%以上的准确率提取信息。
挑战: Token消耗量巨大，导致成本增加，延迟（$T_{TTFT}$）也会增加。

结论: 2026年的最佳实践是**“混合方案（Hybrid Approach）”**。日常的问答使用基于向量数据库的RAG，而在需要复杂分析或整体代码审查的特定任务中，则采用结合提示词缓存（Prompt Caching）的超长上下文设计，这已成为主流。

10. 多模态处理能力对比

下一代的AI应用程序，不仅需要理解文本，还被要求具备直接理解图像、语音和视频的能力。

sequenceDiagram participant User as "用户" participant Client as "前端应用" participant API as "LLM API (多模态)" User->>Client: 上传视频和文本提示 Client->>API: 发送视频字节/URI + 文本 Note over API: 视频分块与音频分离 Note over API: 多模态嵌入模型 API-->>Client: 返回文本摘要和时间戳 Client-->>User: 显示分析结果

OpenAI (GPT-4o): 图像识别精度极高，在读取手绘草图或复杂图表方面表现优异。此外，利用Realtime API实现超低延迟（几百毫秒级别）的原生语音对话也十分强大。
Google (Gemini 1.5 Pro): 在视频分析领域压倒性领先。 可以直接输入1小时的视频文件（视频帧+音频），并针对“12分45秒时屏幕右侧边缘的人物手里拿的资料标题是什么？”这类精准问题给出回答。
Anthropic (Claude 3.5 Sonnet): 图像识别（Vision）能力与GPT-4o处于同一水平，非常出色。在前端开发辅助方面（例如，递交UI截图并要求“生成该页面的React组件代码”），它展现出无可匹敌的优势。

11. 企业级安全与合规性

当企业在生产环境中使用LLM API时，最担心的往往是“我们公司的数据会不会被用来训练AI”以及“是否满足合规性要求”。

这三家公司都明确表示，通过API发送的数据（提示词和响应）不会被用于模型训练（Zero Data Retention / No Training on Customer Data）（※请注意，面向消费者的免费Web聊天界面除外）。

如果需要更高的安全级别：

OpenAI: 通过Azure OpenAI Service，可以利用Microsoft企业级的安全保障、SLA，以及基于Azure Private Link的内网专线连接。
Google: 通过Google Cloud Vertex AI，可以使用VPC Service Controls实现严格的网络隔离，以及CMEK（客户管理加密密钥）进行数据保护。
Anthropic: 通过AWS Bedrock或Google Cloud Vertex AI使用，可以依托云服务提供商坚固的安全基础设施。

12. 结论：按用例划分的终极选择指南

通过多角度的对比，针对“究竟应该选哪一个？”的最终结论，其实因用例而异。

复杂的软件开发・代码生成・高级推理: 👑 胜者: Claude 3.5 Sonnet (Anthropic) 在代码的上下文理解、重构以及生成自然像人类一样的文本方面，它目前展现出最佳的性能。API的易用性以及提示词缓存带来的成本效益也同样出类拔萃。
超长文档分析・视频/音频的批量处理: 👑 胜者: Gemini 1.5 Pro (Google) 200万Token的上下文窗口是它独一无二的武器。无论是解析几百页的PDF手册，还是对长时间会议录像进行摘要，这类需要把握数据全貌的任务，没有任何模型能出其右。
通用性・执行速度・稳定的结构化输出（JSON）: 👑 胜者: GPT-4o / GPT-4o-mini (OpenAI) 它能圆满完成各种任务，而且对第三方工具的支持也最为丰富。在需要使用Structured Outputs进行绝对可靠的JSON解析，或者需要使用o1模型进行超高级逻辑推理时，OpenAI生态系统是不可或缺的。

多模型路由推荐

在未来，不应仅仅依赖单一的API（避免供应商锁定），而是根据任务的难度和重要程度动态切换模型的**“LLM路由（LLM Routing）”**架构将成为趋势。例如，面对用户的简单提问，可以用便宜且高速的 GPT-4o-mini 或 Gemini 1.5 Flash 来回答；只有当系统判断需要进行复杂处理时，才将任务回退给 Claude 3.5 Sonnet。如此一来，便能在成本与性能之间取得最佳平衡。

AI的进化永不停息。请深入了解各API的优劣势和架构特性，从而构建出灵活且可扩展的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)

【2026年最新】在Windows环境下运行本地LLM的完全指南

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

1. 引言：为什么现在要在Windows上运行本地LLM？

2026年现在，生成式AI和大型语言模型（LLM）的发展正经历着一场巨大的范式转变，从云端庞大的API服务，转向在个人PC和本地（On-premises）环境中运行的“本地LLM”。虽然OpenAI的GPT-5和Anthropic的Claude 3.5等云端AI非常强大，但企业和个人并不能将所有数据都发送到云端。出于隐私、安全、延迟以及长期和可持续成本的考虑，对本地LLM的需求正在呈现前所未有的爆发式增长。

特别是在Windows环境中，本地LLM生态系统的演进令人瞩目。直到几年前，“AI开发和运行首选Linux”还是常识，但在2026年的今天，Windows已经转变为一个极其强大且易于使用的AI平台。

本文将基于2026年最新的技术趋势，为您提供在Windows环境中构建、运行和优化本地LLM的完整指南。从面向初学者的使用Ollama的简单构建，到面向高级用户的利用llama.cpp的极限优化，再到VRAM计算的数学方法、架构的深入解析，以及在本地进行的微调（Fine-tuning），我们将以压倒性的丰富内容进行彻底解说。

1.1 2026年围绕本地LLM的技术趋势

塑造当前本地LLM生态系统的主要趋势如下：

GGUF格式的全面普及: 将元数据和张量（Tensor）整合到单一文件中的GGUF（GPT-Generated Unified Format）已经完全成为事实上的标准。这使得只需从Hugging Face下载一个文件，就可以在任何环境中运行。
MoE（Mixture of Experts）架构的民主化: 发布了许多规模较小但性能卓越的MoE模型。通过在推理时仅激活部分专家网络，可以在控制消费级PC计算负载的同时，实现媲美巨大模型的性能。
推理引擎的高度抽象化和优化: Ollama、LM Studio、AnythingLLM等工具变得更加完善，用户无需再关注安装CUDA驱动等复杂的依赖关系。此外，随着FlashAttention 3原生支持Windows，推理速度得到了急剧提升。
NPU的应用和Windows Copilot+ PC的崛起: 即使是在没有GPU的笔记本电脑上，利用内置的NPU（神经网络处理单元）以低功耗运行小型LLM（SLM: Small Language Models）的技术也已经进入实用阶段。

2. 硬件要求与操作系统准备

为了以实用的速度（每秒15到30个Token以上）运行本地LLM，硬件的选择最为关键。

2.1 推荐硬件配置

随着AI PC的进化，所需的规格也在发生变化。

OS: Windows 11 Pro (24H2或更高版本)。这是利用WSL2的完整功能、高级内存管理以及DirectML最新API的必要条件。
CPU: Intel Core Ultra 200系列及以上，或AMD Ryzen 9000系列及以上。如果同时使用CPU进行推理，高带宽的内存通信是不可或缺的。
RAM: 最低32GB，推荐64GB或以上。主内存的带宽（MB/s）是CPU推理或卸载（Offloading）时的决定性瓶颈。DDR5-6000以上的快速内存是理想选择。
GPU: NVIDIA RTX 4000/5000系列。对于本地LLM来说，最重要的不是计算性能，而是“VRAM容量”。
- 入门级: RTX 4060 Ti (16GB版) - 性价比最高。非常适合8B至14B级别的模型。
- 中端: RTX 4070 Ti SUPER (16GB) / RTX 4080 SUPER (16GB)
- 高端: RTX 4090 (24GB) / RTX 5090 (32GB) - 运行30B至70B级别的量化模型所必需。
存储: PCIe Gen4或Gen5的NVMe SSD。可以极大地缩短加载数十GB模型所需的时间。

2.2 WSL2 (Windows Subsystem for Linux 2) 的设置

虽然许多GUI工具可以在Windows原生运行，但在使用Python进行开发、编译最新工具以及稍后将提到的LoRA微调中，WSL2非常方便。在最新的Windows 11环境中，只需在主机端安装NVIDIA驱动，即可从WSL2中透明地使用GPU（CUDA）。

以管理员权限打开PowerShell，并执行以下命令：

1
2
3
4
5


# 安装WSL2和最新的Ubuntu
wsl --install -d Ubuntu-24.04

# 更新内核
wsl --update

安装完成后，在WSL2终端中运行 nvidia-smi，如果能正常识别到GPU，即表示成功。

3. 本地LLM的架构与推理机制

了解模型在本地环境中是如何生成文本的内部结构，对于故障排除和优化非常有用。

以下Mermaid图展示了典型的本地LLM推理流水线（Pipeline）。

graph TD User["用户输入 (Prompt)"] --> Tokenizer["分词器 (Tokenizer)"] Tokenizer --> Embedding["嵌入层 (Embedding)"] subgraph "Transformer Block (x Layers)" Embedding --> Attn["自注意力机制 (Self-Attention)"] Attn --> KVCache["KV 缓存 (保留 Key/Value)"] Attn --> FFN["前馈神经网络 (FFN)"] end FFN --> Logits["Logits 计算 (Logits)"] Logits --> Sampler["采样器 (Temperature, Top-K, Top-P)"] Sampler --> OutputToken["输出 Token"] OutputToken --> |"自回归生成"| Tokenizer OutputToken --> Decoder["反分词器 (Detokenizer)"] Decoder --> FinalOutput["最终输出文本"]

3.1 两个阶段：Prefill 与 Decode

LLM的文本生成分为计算特性不同的两个阶段。

Prefill（提示词处理）阶段: 这是一个一次性处理和理解输入的完整提示词（Prompt）的阶段。由于可以进行并行计算，GPU的计算能力（FLOPS）直接影响速度。如果提示词很长，此阶段可能需要几秒钟的时间。
Decode（Token生成）阶段: 这是一个逐个预测Token，并将其作为下一次输入的（自回归）阶段。在这个阶段并行计算受到限制，因此GPU的VRAM带宽（Memory Bandwidth）成为了决定性的瓶颈。

4. VRAM消耗量的计算与模型大小的数学理解

为了准确判断“我的PC能运行哪个模型？”，必须理解VRAM的计算公式。如果由于VRAM不足而导致回退（Fallback）到系统内存（RAM），推理速度将会变慢10倍到100倍。

4.1 基于参数大小的基础VRAM

这是将模型的权重（Weights）加载到VRAM中所需的内存量。使用模型大小 $P$ （参数数量，单位：10亿 = 1B）和每个参数的字节数 $B$ 来计算。

$$ V_{base} = P \times B \quad \text{(GB)} $$

例如，要将8B（80亿）参数的模型以FP16（半精度浮点数，16位=2字节）加载时：

$$ V_{base} = 8 \times 2 = 16 \text{ GB} $$

也就是说，即使拥有16GB的VRAM的GPU，仅加载模型就几乎达到了极限。

4.2 量化（Quantization）的魔法

于是“量化”便登场了。通过降低参数的精度，能够显著缩小模型大小。在最常见的4bit量化（例如：Q4_K_M）的情况下，每个参数平均约占用0.55字节。

$$ V_{base\_4bit} = 8 \times 0.55 = 4.4 \text{ GB} $$

因此，如果有16GB的VRAM，就可以非常游刃有余地运行8B模型。

4.3 KV缓存的计算（支持GQA版）

在推理时，用于保存过去上下文的“KV缓存”会消耗VRAM。在Llama 3等最新模型中，为了节省内存，采用了GQA（Grouped Query Attention）。

KV缓存的消耗量 $V_{kv}$ （千兆字节，GB）可以通过以下公式表示：

$$ V_{kv} = 2 \times b \times s \times l \times \left( \frac{h_{kv}}{h_q} \right) \times h_q \times d \times B_{kv} \div 10^9 $$

整理后，可以使用Key和Value的注意力头数 $h_{kv}$ 简单地计算：

$$ V_{kv} = 2 \times b \times s \times l \times h_{kv} \times d \times B_{kv} \div 10^9 $$

其中：

$b$: 批处理大小（个人本地使用通常为1）
$s$: 序列长度（上下文长度，例如：8192）
$l$: 层数（例如：32）
$h_{kv}$: KV注意力头数（例如：8）
$d$: 每个头的维度数（例如：128）
$B_{kv}$: KV缓存的字节数（如果为FP16则为2）

计算示例（Llama 3 8B, 上下文8192, FP16缓存）： $V_{kv} = 2 \times 1 \times 8192 \times 32 \times 8 \times 128 \times 2 \div 10^9 \approx 1.07 \text{ GB}$

请注意，上下文长度 $s$ 越长，所需的VRAM就会呈线性增加。

5. 实践1：使用Ollama进行最快、最短的设置

了解了理论之后，让我们实际在Windows环境中运行LLM。在2026年，对用户最友好的工具是“Ollama”。它提供了一个类似于Docker的直观命令行界面（CLI）。

5.1 安装与运行

从 Ollama官网下载Windows版安装程序并运行。
打开PowerShell并输入以下命令。在这里，我们将使用支持日语的 llama3:8b。

1

ollama run llama3:8b

首次运行时会下载模型。下载完成后，就可以直接在终端上进行对话了。

5.2 使用Modelfile创建自定义AI

可以轻松创建具有特定人格（Persona）的AI。在任意位置创建一个 Modelfile。

1
2
3
4
5
6
7
8
9


FROM llama3:8b

SYSTEM """
你是一名极其优秀的资深软件工程师。
对于用户的提问，请务必结合代码示例，有逻辑且简明扼要地进行回答。
"""

PARAMETER temperature 0.3
PARAMETER num_ctx 8192

使用以下命令构建并运行自定义模型：

1
2


ollama create SeniorDev -f ./Modelfile
ollama run SeniorDev

5.3 从外部应用（AI编辑器）中使用

Ollama会在 http://localhost:11434 公开一个兼容OpenAI的API端点。在Cursor或Continue.dev等VS Code扩展插件的后端设置中，将URL指定为上述地址，并将模型名称指定为 SeniorDev 等，只需这样就能实现一个免费且强大的本地编程助手。

6. 实践2：使用llama.cpp进行极限性能调优

如果您想要进行细致的内存管理，或者想尽早尝试最新的格式（如EXL2或IQ量化等），可以直接操作核心引擎 llama.cpp。

6.1 llama.cpp 的构建步骤

在Windows环境中，最好的方式是使用CUDA Toolkit和CMake从源码进行构建。

1
2
3
4
5
6
7
8


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

# 配置为支持CUDA并进行编译
cmake .. -DLLAMA_CUBLAS=ON -DBUILD_SHARED_LIBS=OFF
cmake --build . --config Release -j 16

6.2 在服务器模式下进行高级启动

使用构建好的 llama-server.exe 来托管模型。

1
2
3
4
5
6
7


.\bin\Release\llama-server.exe `
 --model "C:\models\Llama-3-8B-Instruct.Q4_K_M.gguf" `
 --ctx-size 8192 `
 --n-gpu-layers 99 `
 --threads 8 `
 --flash-attn `
 --port 8080

--n-gpu-layers 99: 将尽可能多的层卸载到GPU VRAM中。
--flash-attn: 启用FlashAttention 3，以提升推理速度并减少KV缓存的VRAM消耗。

7. GUI前端：LM Studio与本地RAG的构建

如果您对命令行有抵触情绪，或者想要直观地进行RAG（检索增强生成），可以使用GUI。

7.1 LM Studio

LM Studio是一个将模型搜索、下载、系统要求预检查以及聊天UI等功能集于一身的优秀应用程序。只需点击应用内的“Local Server”按钮，就能启动兼容OpenAI的API。

7.2 使用AnythingLLM的RAG架构

这是一个让系统读取公司内部文档或个人笔记的RAG环境架构图。

graph LR Document["文档 (PDF, MD)"] --> Chunking["数据分块 (Chunking)"] Chunking --> EmbedModel["嵌入模型 (Embedding Model)"] EmbedModel --> VectorDB["向量数据库 (Vector DB)"] UserQuery["用户查询"] --> EmbedQuery["查询嵌入"] EmbedQuery --> VectorDB VectorDB --> |"相似度检索"| RetrievedDocs["提取相关文档"] UserQuery --> PromptBuilder["生成提示词"] RetrievedDocs --> PromptBuilder PromptBuilder --> LocalLLM["本地 LLM"] LocalLLM --> Answer["最终回答"]

使用AnythingLLM桌面版（Windows），只需在设置界面中指定Ollama（用于LLM和Embedding），并设置为使用本地VectorDB（LanceDB），几分钟内就能完成这个架构的搭建。一个完全不向外部发送任何数据的私有AI就此诞生。

8. 在Windows WSL2上进行微调 (LoRA)

除了在本地运行，如果您还想用自己的数据让模型变得更聪明，可以使用LoRA（低秩自适应）进行微调。在2026年，通过使用名为“Unsloth”的库，在Windows的WSL2环境中，即使只有16GB的VRAM，也能在几个小时内完成8B模型的训练。

在WSL2的Ubuntu中执行以下命令来构建环境：

1
2
3
4


conda create --name unsloth_env python=3.11
conda activate unsloth_env
pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"
pip install --no-deps trl peft accelerate bitsandbytes

Unsloth将CUDA内核优化到了极致，与标准的Hugging Face库相比，训练速度约为原来的2倍，而VRAM消耗量减少了一半左右。启动Jupyter Notebook并加载数据集（JSONL格式）后，即使是使用VRAM为12GB至16GB的RTX 4060 Ti等显卡，也可以完成几个Epoch的训练。

9. 性能与故障排除

以下是经常遇到的问题及其解决方案。

1. 推理速度极慢（1至2 tokens/s）

原因: 模型无法完全装入VRAM，被卸载到了系统内存（RAM）中。对策: 请在任务管理器中检查“专用GPU内存”。如果已达到极限，请减小上下文大小（-c），或者使用位数更低的量化模型（如Q4_K_M等）。

2. “CUDA out of memory” 错误

原因: VRAM完全枯竭。特别是当对话时间过长导致KV缓存不断膨胀时会发生这种情况。对策: 在Ollama中，有意地减小 num_ctx 的值；在llama.cpp中，减小 -c 的值以进行限制。

3. 生成的日语不正常

原因: 提示词模板不匹配，或者是使用了不支持的模型。对策: 请使用模型名称中包含 Instruct 的模型，并确认工具端是否选择了模型作者指定的正确模板，例如ChatML或Llama3格式。

10. 总结与未来展望

在2026年，在Windows环境中构建本地LLM已经不再是少数工程师的特权。随着GGUF格式成为事实上的标准、Ollama和LM Studio等完善生态系统的出现，以及以FlashAttention为首的硬件优化，任何人都可以轻松获得企业级的AI环境。

请务必活用本文中解说的以下几点：

使用VRAM的数学计算，逻辑性地选择最适合您PC规格的模型大小和量化级别。
使用Ollama以最快的速度搭建环境，并与AI编辑器联动，从而急剧提高生产力。
通过llama.cpp的高级参数控制，榨干硬件的极限性能。
使用AnythingLLM构建能够处理机密数据的安全的本地RAG系统。
活用Unsloth (WSL2)，培育出拥有专属于您专业知识的自定义AI。

AI的“民主化”已经不再是一个流行语，而是一个运行在您的Windows桌面上的真实系统。摆脱云端API的使用成本和信息泄露风险，现在就请迈入这个自由且强大的私有AI世界吧。