文章目录
- [1. 模块概述](#1. 模块概述)
-
- [1.1 核心定位](#1.1 核心定位)
- [1.2 设计目标](#1.2 设计目标)
- [2. 整体架构设计](#2. 整体架构设计)
-
- [2.1 目录组织结构](#2.1 目录组织结构)
- [2.2 构建系统集成](#2.2 构建系统集成)
- [3. 核心示例程序深度分析](#3. 核心示例程序深度分析)
-
- [3.1 Simple 示例 - 入门级教程](#3.1 Simple 示例 - 入门级教程)
-
- [3.1.1. 概述](#3.1.1. 概述)
- [3.1.2. 核心代码结构](#3.1.2. 核心代码结构)
- [3.1.3. 教学价值分析](#3.1.3. 教学价值分析)
- [3.1.4. 性能优化技巧](#3.1.4. 性能优化技巧)
- [3.2 Batched 示例 - 批处理优化](#3.2 Batched 示例 - 批处理优化)
-
- [3.2.1. 技术亮点](#3.2.1. 技术亮点)
- [3.2.2. 核心架构设计](#3.2.2. 核心架构设计)
- [3.2.3. 性能优化策略](#3.2.3. 性能优化策略)
-
- [3.2.3.1. 内存复用](#3.2.3.1. 内存复用)
- [3.2.3.2. 动态批处理](#3.2.3.2. 动态批处理)
- [3.2.3.3. 并行化处理](#3.2.3.3. 并行化处理)
- [3.2.4. 应用场景](#3.2.4. 应用场景)
- [3.3 Embedding 示例 - 向量化服务](#3.3 Embedding 示例 - 向量化服务)
-
- [3.3.1. 功能完整性](#3.3.1. 功能完整性)
- [3.3.2. 核心功能实现](#3.3.2. 核心功能实现)
- [3.3.3. 高级特性支持](#3.3.3. 高级特性支持)
- [3.3.3.1. 重排序（Reranking）](#3.3.3.1. 重排序（Reranking）)
- [3.3.3.2. 分类任务支持](#3.3.3.2. 分类任务支持)
- [3.3.3.3. 输出格式支持](#3.3.3.3. 输出格式支持)
- [3.4 Speculative 示例 - 投机解码技术](#3.4 Speculative 示例 - 投机解码技术)
-
- [3.4.1. 技术原理](#3.4.1. 技术原理)
- [3.4.2. 架构设计](#3.4.2. 架构设计)
- [3.4.3. 投机解码算法](#3.4.3. 投机解码算法)
- [3.4.3. 性能分析](#3.4.3. 性能分析)
- [3.5 Server 示例 - HTTP API服务](#3.5 Server 示例 - HTTP API服务)
-
- [3.5.1. 生产就绪特性](#3.5.1. 生产就绪特性)
- [3.5.2. 架构设计](#3.5.2. 架构设计)
- [3.5.3. API端点实现](#3.5.3. API端点实现)
-
- [3.5.3.1. OpenAI兼容接口](#3.5.3.1. OpenAI兼容接口)
- [3.5.3.2. 流式响应支持](#3.5.3.2. 流式响应支持)
- [3.5.3.3. 多模态支持](#3.5.3.3. 多模态支持)
- [4. 使用场景分类分析](#4. 使用场景分类分析)
-
- [4.1 学习和教育场景](#4.1 学习和教育场景)
- [4.2 生产部署场景](#4.2 生产部署场景)
-
- [4.2.1. API服务开发](#4.2.1. API服务开发)
- [4.2.2. 批处理系统](#4.2.2. 批处理系统)
- [4.3 研究实验场景](#4.3 研究实验场景)
-
- [4.3.1. 技术验证平台](#4.3.1. 技术验证平台)
- [4.3.2. 投机解码实验](#4.3.2. 投机解码实验)
- [5. 教学价值评估](#5. 教学价值评估)
-
- [5.1 代码质量分析](#5.1 代码质量分析)
- [5.2 学习路径设计](#5.2 学习路径设计)
- [5.3 实用性评估](#5.3 实用性评估)
- [6. 最佳实践总结](#6. 最佳实践总结)
-
- [6.1 代码组织模式](#6.1 代码组织模式)
-
- [6.1.1. 标准模板结构](#6.1.1. 标准模板结构)
- [6.1.2. 错误处理模式](#6.1.2. 错误处理模式)
- [6.2 性能优化技巧](#6.2 性能优化技巧)
-
- [6.2.1. 内存优化](#6.2.1. 内存优化)
- [6.2.2. 计算优化](#6.2.2. 计算优化)
- [6.3 调试和监控技巧](#6.3 调试和监控技巧)
-
- [6.3.1. 性能监控](#6.3.1. 性能监控)
- [7. 总结](#7. 总结)
-
- [7.1 核心价值](#7.1 核心价值)
- [7.2 对项目的贡献](#7.2 对项目的贡献)
- [7.3 推荐使用策略](#7.3 推荐使用策略)
团队博客: 汽车电子社区
1. 模块概述
examples/ 目录是 llama.cpp 项目的示例程序集合，为开发者提供了从入门到专业级别的完整学习资源。该目录包含了50多个示例程序，涵盖了基础推理、高级优化、生产部署、研究实验等多个维度，是学习LLM推理技术的宝贵资源库。
1.1 核心定位
- 教学资源 ：从入门到专业的系统化学习路径
- 参考实现 ：生产就绪的代码示例和最佳实践
- 功能演示 ：展示llama.cpp的全部特性和能力
- 开发模板：可直接复用的代码模板和架构模式
1.2 设计目标
- 渐进式学习 ：从简单到复杂的学习曲线
- 完整性 ：每个示例都是可独立运行的完整程序
- 实用性 ：提供可直接用于生产的代码实现
- 前沿性：包含最新的研究成果和技术创新
2. 整体架构设计
2.1 目录组织结构
examples/
├── 核心推理示例 (Core Inference)
│ ├── simple/ # 基础推理示例 - 入门教程
│ ├── simple-chat/ # 简单聊天示例 - 交互式应用
│ ├── batched/ # 批处理推理 - 性能优化
│ ├── speculative/ # 投机解码 - 高级技术
│ ├── speculative-simple/ # 简化投机解码
│ ├── parallel/ # 并行推理 - 并发处理
│ └── eval-callback/ # 评估回调 - 底层理解
├── 专用功能示例 (Specialized Features)
│ ├── embedding/ # 文本嵌入 - 向量化服务
│ ├── retrieval/ # 检索增强 - RAG技术
│ ├── passkey/ # 长上下文测试
│ ├── lookahead/ # 前瞻解码技术
│ └── infill/ # 代码填充 - 补全功能
├── 工具和实用程序 (Tools & Utilities)
│ ├── save-load-state/ # 状态保存和加载
│ ├── idle/ # 空闲性能测试
│ ├── gguf/ # GGUF格式操作
│ ├── gguf-hash/ # GGUF文件哈希
│ ├── lookup/ # 查找表操作
│ └── perplexity/ # 困惑度计算 (tools/)
├── 高级特性示例 (Advanced Features)
│ ├── diffusion/ # 扩散模型支持
│ ├── training/ # 模型训练技术
│ ├── model-conversion/ # 模型格式转换
│ └── llm-bench/ # 性能基准测试
├── 跨平台示例 (Cross-Platform)
│ ├── llama.android/ # Android平台支持
│ ├── llama.swiftui/ # Swift UI支持
│ ├── batched.swift/ # Swift批处理
│ └── sycl/ # SYCL加速支持
├── 开发工具 (Development Tools)
│ ├── deprecation-warning/ # 废弃警告处理
│ ├── gen-docs/ # 文档生成工具
│ └── simple-cmake-pkg/ # CMake包示例
└── Python脚本工具 (Python Tools)
├── json_schema_to_grammar.py # JSON Schema转语法约束
├── pydantic_models_to_grammar.py # Pydantic模型转语法
├── convert_legacy_llama.py # 遗留格式转换
└── regex_to_grammar.py # 正则表达式转语法2.2 构建系统集成
cmake
# examples/CMakeLists.txt 核心配置
function(add_llama_example target_name source)
add_executable(${target_name} ${source})
# 依赖管理
target_link_libraries(${target_name} PRIVATE common llama ${CMAKE_THREAD_LIBS_INIT})
# 动态后端支持
if (BUILD_SHARED_LIBS)
set_target_properties(${target_name} PROPERTIES
COMPILE_DEFINITIONS "GGML_DL")
target_link_libraries(${target_name} PRIVATE ${CMAKE_DL_LIBS})
endif()
# GPU层配置
if (LLAMA_GPU)
target_link_libraries(${target_name} PRIVATE ggml-cpu ggml-base)
endif()
endfunction()
# 核心示例构建
add_llama_example(simple simple/simple.cpp)
add_llama_example(batched batched/batched.cpp)
add_llama_example(embedding embedding/embedding.cpp)
add_llama_example(speculative speculative/speculative.cpp)
# 条件构建 (EMSCRIPTEN平台支持)
if (NOT EMSCRIPTEN)
add_llama_example(save-load-state save-load-state/save-load-state.cpp)
endif()
# SYCL后端条件构建
if (GGML_SYCL)
add_subdirectory(sycl)
endif()3. 核心示例程序深度分析
3.1 Simple 示例 - 入门级教程
3.1.1. 概述
simple/ 是 llama.cpp 的入门示例，展示了最基础但完整的推理流程。仅221行代码，却涵盖了模型加载、分词、推理、生成的全过程。
3.1.2. 核心代码结构
cpp
// main函数 - 完整的推理流程
int main(int argc, char ** argv) {
// 1. 参数解析
common_params params;
if (!common_params_parse(argc, argv, params, LLAMA_EXAMPLE_COMMON)) {
return 1;
}
// 2. 初始化后端
common_init();
llama_backend_init();
llama_numa_init(params.numa);
// 3. 加载模型
llama_model * model = llama_load_model_from_file(params.model.c_str(),
common_model_params_to_llama(params));
// 4. 创建上下文
llama_context * ctx = llama_new_context_with_model(model,
common_context_params_to_llama(params));
// 5. 分词输入
std::vector<llama_token> tokens_list = common_tokenize(ctx, params.prompt, true);
// 6. 批处理设置
llama_batch batch = llama_batch_init(tokens_list.size(), 0, 1);
// 7. 推理循环
for (int32_t i = 0; i < params.n_predict; i++) {
// 清空KV缓存（对于第一个token）
if (i == 0) {
llama_kv_cache_clear(ctx);
}
// 设置批处理
llama_batch_set_batch(batch, tokens_list.data(), tokens_list.size(), 0, false);
// 执行推理
llama_decode(ctx, batch);
// 获取logits
llama_token new_token_id = common_sampler_sample(smpl, ctx, -1);
// 输出结果
printf("%s", common_token_to_piece(ctx, new_token_id).c_str());
fflush(stdout);
// 添加到序列
tokens_list.push_back(new_token_id);
// 检查结束条件
if (new_token_id == llama_token_eos(model) ||
tokens_list.size() > params.n_ctx) {
break;
}
}
// 8. 清理资源
llama_batch_free(batch);
llama_free(ctx);
llama_free(model);
llama_backend_free();
return 0;
}3.1.3. 教学价值分析
1. 概念清晰性 ⭐⭐⭐⭐⭐
- 展示了LLM推理的完整生命周期
- 每个步骤都有详细注释
- 错误处理完整且易懂
2. API使用规范 ⭐⭐⭐⭐⭐
- 演示了标准API调用序列
- 展示了资源管理的最佳实践
- 包含性能监控代码
3. 扩展性指导 ⭐⭐⭐⭐
- 为复杂应用提供了基础模板
- 易于修改和扩展
- 支持多种采样策略
3.1.4. 性能优化技巧
cpp
// 时间测量RAII类
struct simple_time_meas {
int64_t & t_acc;
int64_t t_start_us;
simple_time_meas(int64_t & t_acc) : t_acc(t_acc) {
t_start_us = ggml_time_us();
}
~simple_time_meas() {
t_acc += ggml_time_us() - t_start_us;
}
};
// 性能统计输出
printf("llama_print_timings:\n");
llama_print_timings(ctx);
printf("\n");3.2 Batched 示例 - 批处理优化
3.2.1. 技术亮点
batched/ 示例展示了如何高效处理多个并发生成请求，是生产环境中的关键优化技术。
3.2.2. 核心架构设计
cpp
// 批处理管理器
struct batch_manager {
int32_t n_parallel = 1; // 并行序列数
std::vector<std::vector<llama_token>> sequences; // 多个输入序列
std::vector<bool> is_finished; // 完成状态
std::vector<llama_pos> positions; // 位置编码
// 初始化批处理
void initialize(const common_params & params) {
n_parallel = params.n_parallel;
sequences.resize(n_parallel);
is_finished.resize(n_parallel, false);
positions.resize(n_parallel, 0);
}
// 构建批处理对象
llama_batch build_batch() {
int total_tokens = 0;
for (const auto & seq : sequences) {
total_tokens += seq.size();
}
llama_batch batch = llama_batch_init(total_tokens, 0, n_parallel);
int token_idx = 0;
for (int i = 0; i < n_parallel; ++i) {
if (is_finished[i]) continue;
for (size_t j = 0; j < sequences[i].size(); ++j) {
batch.token[token_idx] = sequences[i][j];
batch.pos[token_idx] = positions[i] + j;
batch.n_seq_id[token_idx] = 1;
batch.seq_id[token_idx][0] = i;
batch.logits[token_idx] = (j == sequences[i].size() - 1) ? 1 : 0;
token_idx++;
}
}
batch.n_tokens = token_idx;
return batch;
}
};3.2.3. 性能优化策略
3.2.3.1. 内存复用
cpp
// 重用KV缓存
if (params.kv_unified) {
// 统一KV缓存，所有序列共享
llama_kv_cache_set_unified(ctx, true);
}3.2.3.2. 动态批处理
cpp
// 自适应批大小
if (tokens_generated % 100 == 0) {
// 定期评估性能并调整批大小
evaluate_and_adjust_batch_size();
}3.2.3.3. 并行化处理
cpp
// 多线程处理序列准备
#pragma omp parallel for
for (int i = 0; i < n_parallel; ++i) {
prepare_sequence_data(i);
}3.2.4. 应用场景
- API服务器 ：处理多个并发请求
- 批量处理 ：大批量文本生成任务
- 数据管道：ETL处理中的文本生成
3.3 Embedding 示例 - 向量化服务
3.3.1. 功能完整性
embedding/ 示例提供了完整的文本向量化解决方案，支持多种池化方式和归一化策略。
3.3.2. 核心功能实现
cpp
// 嵌入配置
struct embedding_config {
enum pooling_type {
POOLING_NONE = 0,
POOLING_MEAN = 1,
POOLING_CLS = 2,
POOLING_LAST = 3,
POOLING_RANK = 4
} pooling = POOLING_MEAN;
enum normalization_type {
NORM_NONE = 0,
NORM_L1 = 1,
NORM_L2 = 2,
NORM_MAX = 3,
NORM_P_NORM = 4
} normalization = NORM_L2;
float p_norm = 2.0f; // p-norm参数
bool concatenate = false; // 是否拼接多层数据
int n_embd_target = -1; // 目标嵌入维度
};
// 向量化处理
std::vector<float> compute_embedding(llama_context * ctx,
const std::vector<llama_token> & tokens,
const embedding_config & config) {
// 1. 准备输入批处理
llama_batch batch = llama_batch_init(tokens.size(), 0, 1);
for (size_t i = 0; i < tokens.size(); ++i) {
llama_batch_add_seq(batch, tokens[i], i, i == tokens.size() - 1);
}
// 2. 执行推理
llama_decode(ctx, batch);
// 3. 提取隐藏状态
const float * hidden_states = llama_get_embeddings(ctx);
// 4. 应用池化策略
std::vector<float> pooled_embedding = apply_pooling(hidden_states, tokens.size(), config);
// 5. 应用归一化
apply_normalization(pooled_embedding, config);
return pooled_embedding;
}3.3.3. 高级特性支持
3.3.3.1. 重排序（Reranking）
cpp
// 余弦相似度计算
float cosine_similarity(const std::vector<float> & vec1,
const std::vector<float> & vec2) {
float dot_product = 0.0f;
float norm1 = 0.0f, norm2 = 0.0f;
for (size_t i = 0; i < vec1.size(); ++i) {
dot_product += vec1[i] * vec2[i];
norm1 += vec1[i] * vec1[i];
norm2 += vec2[i] * vec2[i];
}
return dot_product / (sqrt(norm1) * sqrt(norm2));
}3.3.3.2. 分类任务支持
cpp
// 文本分类
int classify_text(const std::vector<float> & embedding,
const std::vector<std::vector<float>> & class_prototypes) {
int best_class = 0;
float best_similarity = -INFINITY;
for (int i = 0; i < class_prototypes.size(); ++i) {
float similarity = cosine_similarity(embedding, class_prototypes[i]);
if (similarity > best_similarity) {
best_similarity = similarity;
best_class = i;
}
}
return best_class;
}3.3.3.3. 输出格式支持
cpp
// 多种输出格式
enum output_format {
FORMAT_JSON = 0,
FORMAT_ARRAY = 1,
FORMAT_RAW = 2,
FORMAT_BINARY = 3
};
void output_embedding(const std::vector<float> & embedding,
const std::string & input_text,
output_format format) {
switch (format) {
case FORMAT_JSON:
{
nlohmann::json result;
result["text"] = input_text;
result["embedding"] = embedding;
std::cout << result.dump() << std::endl;
}
break;
case FORMAT_ARRAY:
std::cout << "[";
for (size_t i = 0; i < embedding.size(); ++i) {
if (i > 0) std::cout << ", ";
std::cout << std::fixed << std::setprecision(6) << embedding[i];
}
std::cout << "]" << std::endl;
break;
case FORMAT_RAW:
std::cout.write(reinterpret_cast<const char*>(embedding.data()),
embedding.size() * sizeof(float));
break;
}
}3.4 Speculative 示例 - 投机解码技术
3.4.1. 技术原理
投机解码是一种创新的推理加速技术，通过使用小模型（draft）预测token，然后用大模型（target）验证，显著提高生成速度。
3.4.2. 架构设计
cpp
// 投机解码管理器
struct speculative_decoder {
llama_model * model_target; // 目标模型（大模型）
llama_model * model_draft; // 草稿模型（小模型）
llama_context * ctx_target;
llama_context * ctx_draft;
// 投机参数
int n_draft = 4; // 每次推测的token数
float p_accept = 0.5f; // 接受概率阈值
// 性能统计
int tokens_generated = 0;
int drafts_accepted = 0;
double speedup = 1.0;
bool initialize(const common_params & params) {
// 1. 加载目标模型
model_target = llama_load_model_from_file(params.model.c_str(),
common_model_params_to_llama(params));
ctx_target = llama_new_context_with_model(model_target,
common_context_params_to_llama(params));
// 2. 加载草稿模型
if (!params.draft_model.empty()) {
common_params draft_params = params;
draft_params.model = params.draft_model;
draft_params.n_ctx = std::min(params.n_ctx, 2048); // 限制草稿模型上下文
model_draft = llama_load_model_from_file(draft_params.model.c_str(),
common_model_params_to_llama(draft_params));
ctx_draft = llama_new_context_with_model(model_draft,
common_context_params_to_llama(draft_params));
}
return model_target && ctx_target;
}
};3.4.3. 投机解码算法
cpp
// 投机解码核心算法
llama_token speculative_decode_step(speculative_decoder & spec,
const std::vector<llama_token> & input_ids) {
std::vector<llama_token> draft_tokens;
std::vector<llama_token> accepted_tokens;
// 1. 草稿模型生成预测序列
draft_tokens = generate_draft_sequence(spec.ctx_draft, input_ids, spec.n_draft);
// 2. 目标模型并行验证
for (int i = 0; i <= draft_tokens.size(); ++i) {
// 构建验证批处理
std::vector<llama_token> verify_sequence = input_ids;
verify_sequence.insert(verify_sequence.end(),
draft_tokens.begin(),
draft_tokens.begin() + i);
// 目标模型计算概率
llama_batch batch = build_batch(verify_sequence);
llama_decode(spec.ctx_target, batch);
const float * logits = llama_get_logits(spec.ctx_target);
llama_token target_token = get_most_likely_token(logits);
if (i < draft_tokens.size()) {
// 验证草稿token
if (target_token == draft_tokens[i]) {
accepted_tokens.push_back(target_token);
spec.drafts_accepted++;
} else {
// 拒绝后续所有草稿token
break;
}
} else {
// 最后一个token总是来自目标模型
accepted_tokens.push_back(target_token);
}
}
// 3. 更新统计信息
spec.tokens_generated += accepted_tokens.size();
spec.speedup = double(spec.tokens_generated) / (input_ids.size() + 1);
// 4. 返回第一个接受的token用于流式输出
return accepted_tokens.empty() ?
llama_sample_token greedy(spec.ctx_target, logits) :
accepted_tokens[0];
}3.4.3. 性能分析
cpp
// 性能报告
void print_speculative_stats(const speculative_decoder & spec) {
printf("Speculative Decoding Performance:\n");
printf(" Tokens Generated: %d\n", spec.tokens_generated);
printf(" Drafts Accepted: %d\n", spec.drafts_accepted);
printf(" Accept Rate: %.2f%%\n",
100.0 * spec.drafts_accepted / spec.tokens_generated);
printf(" Speedup: %.2fx\n", spec.speedup);
printf(" Draft Ratio: %.2f\n", double(spec.n_draft));
}3.5 Server 示例 - HTTP API服务
3.5.1. 生产就绪特性
虽然 server 示例位于 tools/ 目录，但它是 examples 体系的重要组成部分，展示了如何构建生产级的LLM推理服务。
3.5.2. 架构设计
cpp
// HTTP服务器架构
class llama_http_server {
private:
struct http_handler {
std::string method;
std::string path;
std::function<bool(const httplib::Request&, httplib::Response&)> handler;
};
std::vector<http_handler> handlers_;
std::unique_ptr<llama_context> ctx_;
std::unique_ptr<llama_model> model_;
std::unique_ptr<common_sampler> sampler_;
// 请求管理
std::mutex request_mutex_;
std::queue<std::function<void()>> request_queue_;
std::condition_variable request_cv_;
std::thread worker_thread_;
public:
bool initialize(const common_params & params);
void start_server(const std::string & host, int port);
void register_handlers();
private:
void setup_openai_compatible_endpoints();
void setup_anthropic_compatible_endpoints();
void process_requests();
};3.5.3. API端点实现
3.5.3.1. OpenAI兼容接口
cpp
// /v1/completions 端点
void handle_completions(const httplib::Request& req, httplib::Response& res) {
try {
nlohmann::json request = nlohmann::json::parse(req.body);
// 解析参数
std::string prompt = request["prompt"];
int max_tokens = request.value("max_tokens", 100);
float temperature = request.value("temperature", 0.7f);
// 生成响应
nlohmann::json response;
response["id"] = generate_uuid();
response["object"] = "text_completion";
response["created"] = std::time(nullptr);
// 执行推理
std::string generated_text = generate_completion(prompt, max_tokens, temperature);
response["choices"] = nlohmann::json::array();
nlohmann::json choice;
choice["text"] = generated_text;
choice["finish_reason"] = "length";
response["choices"].push_back(choice);
response["usage"] = {
{"prompt_tokens", count_tokens(prompt)},
{"completion_tokens", count_tokens(generated_text)},
{"total_tokens", count_tokens(prompt) + count_tokens(generated_text)}
};
res.set_content(response.dump(), "application/json");
} catch (const std::exception& e) {
nlohmann::json error;
error["error"] = {
{"message", e.what()},
{"type", "invalid_request_error"},
{"code", "invalid_request"}
};
res.status = 400;
res.set_content(error.dump(), "application/json");
}
}3.5.3.2. 流式响应支持
cpp
// 流式生成
void handle_completions_stream(const httplib::Request& req, httplib::Response& res) {
res.set_header("Content-Type", "text/event-stream");
res.set_header("Cache-Control", "no-cache");
res.set_header("Connection", "keep-alive");
// 生成流式响应
auto generate_callback = [&](const std::string& chunk, bool finished) {
nlohmann::json event;
event["id"] = generate_uuid();
event["object"] = "text_completion";
event["created"] = std::time(nullptr);
nlohmann::json choice;
choice["text"] = chunk;
choice["finish_reason"] = finished ? "length" : nullptr;
event["choices"] = nlohmann::json::array();
event["choices"].push_back(choice);
std::string sse_data = "data: " + event.dump() + "\n\n";
res.write(sse_data);
if (finished) {
res.write("data: [DONE]\n\n");
}
};
// 执行流式生成
generate_completion_stream(prompt, max_tokens, temperature, generate_callback);
}3.5.3.3. 多模态支持
cpp
// 多模态输入处理
std::vector<llama_token> process_multimodal_input(const nlohmann::json& messages) {
std::vector<llama_token> tokens;
for (const auto& msg : messages) {
// 处理文本
if (msg.contains("content") && msg["content"].is_string()) {
auto text_tokens = common_tokenize(ctx_, msg["content"], true);
tokens.insert(tokens.end(), text_tokens.begin(), text_tokens.end());
}
// 处理多模态内容
if (msg.contains("content") && msg["content"].is_array()) {
for (const auto& part : msg["content"]) {
if (part["type"] == "text") {
auto text_tokens = common_tokenize(ctx_, part["text"], true);
tokens.insert(tokens.end(), text_tokens.begin(), text_tokens.end());
} else if (part["type"] == "image_url") {
// 处理图像
std::string image_data = base64_decode(part["image_url"]["url"]);
auto image_tokens = process_image(image_data);
tokens.insert(tokens.end(), image_tokens.begin(), image_tokens.end());
}
}
}
}
return tokens;
}4. 使用场景分类分析
4.1 学习和教育场景
入门级 (1-2周)
- simple/ : 理解LLM推理的基本流程
- simple-chat/ : 学习交互式应用开发
- embedding/: 掌握文本向量化技术
学习路径建议:
Day 1-3: simple/ - 理解基础API和流程
Day 4-7: simple-chat/ - 学习交互逻辑
Day 8-10: embedding/ - 掌握向量化
Day 11-14: 综合项目 - 构建简单应用进阶级 (2-3周)
- batched/ : 批处理优化技术
- parallel/ : 并发处理实现
- save-load-state/: 状态管理机制
高级 (3-4周)
- speculative/ : 投机解码技术
- lookahead/ : 前瞻解码算法
- eval-callback/: 深入理解模型计算
4.2 生产部署场景
4.2.1. API服务开发
cpp
// 基于server示例的生产架构
class production_llm_service {
private:
std::unique_ptr<llama_http_server> server_;
std::unique_ptr<common_model_cache> model_cache_;
std::unique_ptr<common_load_balancer> load_balancer_;
public:
bool deploy(const service_config& config) {
// 1. 初始化模型缓存
model_cache_ = std::make_unique<common_model_cache>();
// 2. 配置负载均衡
load_balancer_ = std::make_unique<common_load_balancer>();
// 3. 启动HTTP服务
server_ = std::make_unique<llama_http_server>();
return server_->initialize(config.llama_params);
}
};4.2.2. 批处理系统
cpp
// 高性能批处理管道
class batch_processing_pipeline {
private:
struct batch_job {
std::vector<llama_token> tokens;
std::string job_id;
std::function<void(const std::string&)> callback;
};
std::queue<batch_job> job_queue_;
std::mutex queue_mutex_;
std::thread processing_thread_;
public:
void submit_job(const std::string& text,
std::function<void(const std::string&)> callback) {
batch_job job;
job.tokens = common_tokenize(ctx_, text, true);
job.job_id = generate_job_id();
job.callback = callback;
{
std::lock_guard<std::mutex> lock(queue_mutex_);
job_queue_.push(job);
}
}
private:
void process_batch_jobs() {
while (running_) {
std::vector<batch_job> current_batch;
// 收集批处理任务
{
std::lock_guard<std::mutex> lock(queue_mutex_);
while (current_batch.size() < max_batch_size && !job_queue_.empty()) {
current_batch.push_back(job_queue_.front());
job_queue_.pop();
}
}
if (!current_batch.empty()) {
// 执行批处理
process_batch(current_batch);
} else {
std::this_thread::sleep_for(std::chrono::milliseconds(10));
}
}
}
};4.3 研究实验场景
4.3.1. 技术验证平台
cpp
// 实验框架基类
class experiment_framework {
protected:
std::map<std::string, double> metrics_;
std::vector<std::string> experiment_log_;
public:
virtual void setup_experiment() = 0;
virtual void run_experiment() = 0;
virtual void collect_metrics() = 0;
void execute_experiment() {
auto start_time = std::chrono::high_resolution_clock::now();
setup_experiment();
run_experiment();
collect_metrics();
auto end_time = std::chrono::high_resolution_clock::now();
auto duration = std::chrono::duration_cast<std::chrono::milliseconds>(end_time - start_time);
metrics_["execution_time_ms"] = duration.count();
// 生成实验报告
generate_experiment_report();
}
protected:
void log_event(const std::string& event) {
experiment_log_.push_back(event);
}
void record_metric(const std::string& name, double value) {
metrics_[name] = value;
}
private:
void generate_experiment_report() {
nlohmann::json report;
report["timestamp"] = std::time(nullptr);
report["metrics"] = metrics_;
report["events"] = experiment_log_;
std::string report_path = "experiment_report_" +
std::to_string(std::time(nullptr)) + ".json";
std::ofstream file(report_path);
file << report.dump(2);
}
};4.3.2. 投机解码实验
cpp
// 投机解码性能实验
class speculative_experiment : public experiment_framework {
private:
std::vector<std::string> test_prompts_;
std::vector<int> draft_ratios_ = {2, 4, 8, 16};
std::vector<float> acceptance_thresholds_ = {0.3f, 0.5f, 0.7f, 0.9f};
public:
void setup_experiment() override {
// 加载测试数据集
load_test_dataset();
log_event("Loaded " + std::to_string(test_prompts_.size()) + " test prompts");
}
void run_experiment() override {
for (int draft_ratio : draft_ratios_) {
for (float threshold : acceptance_thresholds_) {
run_single_experiment(draft_ratio, threshold);
}
}
}
void collect_metrics() override {
// 计算平均加速比
double total_speedup = 0.0;
int experiment_count = 0;
for (const auto& [name, value] : metrics_) {
if (name.find("speedup_") == 0) {
total_speedup += value;
experiment_count++;
}
}
record_metric("average_speedup", total_speedup / experiment_count);
}
private:
void run_single_experiment(int draft_ratio, float threshold) {
std::string experiment_name = "draft_" + std::to_string(draft_ratio) +
"_threshold_" + std::to_string(threshold);
log_event("Starting experiment: " + experiment_name);
double total_time_baseline = 0.0;
double total_time_speculative = 0.0;
for (const std::string& prompt : test_prompts_) {
// 基线测试
auto start = std::chrono::high_resolution_clock::now();
std::string result_baseline = generate_baseline(prompt, 100);
auto end = std::chrono::high_resolution_clock::now();
total_time_baseline += std::chrono::duration<double>(end - start).count();
// 投机解码测试
start = std::chrono::high_resolution_clock::now();
std::string result_speculative = generate_speculative(prompt, 100, draft_ratio, threshold);
end = std::chrono::high_resolution_clock::now();
total_time_speculative += std::chrono::duration<double>(end - start).count();
// 验证结果一致性
if (result_baseline != result_speculative) {
log_event("Warning: Results differ for prompt: " + prompt);
}
}
double speedup = total_time_baseline / total_time_speculative;
record_metric("speedup_" + experiment_name, speedup);
record_metric("time_baseline_" + experiment_name, total_time_baseline);
record_metric("time_speculative_" + experiment_name, total_time_speculative);
log_event("Experiment " + experiment_name + " completed. Speedup: " +
std::to_string(speedup) + "x");
}
};5. 教学价值评估
5.1 代码质量分析
一致性评分 ⭐⭐⭐⭐⭐
- 编码规范 : 所有示例遵循统一的编码标准
- 命名规范 : 函数和变量命名清晰一致
- 注释质量 : 关键代码段都有详细注释
- 错误处理: 统一的错误处理模式
完整性评分 ⭐⭐⭐⭐
- 功能完整 : 每个示例都是可运行的完整程序
- 依赖管理 : 明确的依赖关系和构建配置
- 文档齐全 : 每个示例都有详细的README
- 测试覆盖: 包含多种测试用例
可维护性评分 ⭐⭐⭐⭐
- 模块化设计 : 清晰的功能分离
- 接口清晰 : 简洁的公共API
- 扩展容易 : 易于添加新功能
- 调试友好: 包含调试和监控代码
5.2 学习路径设计
初学者路径 (评分: ⭐⭐⭐⭐⭐)
1. simple/ → 2. simple-chat/ → 3. embedding/ → 4. save-load-state/优势 :
- 循序渐进的复杂度
- 每个示例都有明确的学习目标
- 丰富的注释和文档支持
进阶开发者路径 (评分: ⭐⭐⭐⭐)
1. batched/ → 2. parallel/ → 3. speculative/ → 4. retrieval/优势 :
- 涵盖生产环境的关键技术
- 包含性能优化最佳实践
- 展示高级架构设计
研究者路径 (评分: ⭐⭐⭐⭐)
1. eval-callback/ → 2. lookahead/ → 3. diffusion/ → 4. training/优势 :
- 展示前沿研究成果
- 提供实验框架模板
- 支持自定义算法扩展
5.3 实用性评估
生产就绪度 ⭐⭐⭐⭐
- server/ : 可直接用于生产API服务
- batched/ : 适合大规模批处理任务
- embedding/: 完整的向量化解决方案
扩展性 ⭐⭐⭐⭐⭐
- 插件化架构 : 易于添加新功能
- 配置驱动 : 通过参数控制行为
- 模块化设计: 支持独立使用和组合
性能优化 ⭐⭐⭐⭐⭐
- 多种优化技术 : 批处理、投机解码、并行处理
- 性能监控 : 内置的性能分析和统计
- 内存管理: 高效的内存使用和复用
6. 最佳实践总结
6.1 代码组织模式
6.1.1. 标准模板结构
cpp
#include "common.h"
#include "llama.h"
int main(int argc, char ** argv) {
// 1. 参数解析
common_params params;
if (!common_params_parse(argc, argv, params, EXAMPLE_TYPE)) {
return 1;
}
// 2. 系统初始化
common_init();
llama_backend_init();
llama_numa_init(params.numa);
// 3. 模型加载
llama_model * model = llama_load_model_from_file(
params.model.c_str(), common_model_params_to_llama(params));
// 4. 上下文创建
llama_context * ctx = llama_new_context_with_model(
model, common_context_params_to_llama(params));
// 5. 核心逻辑
try {
run_inference_loop(params, model, ctx);
} catch (const std::exception & e) {
fprintf(stderr, "Error: %s\n", e.what());
return 1;
}
// 6. 资源清理
llama_free(ctx);
llama_free(model);
llama_backend_free();
return 0;
}6.1.2. 错误处理模式
cpp
// RAII资源管理
struct llama_context_guard {
llama_context * ctx;
llama_context_guard(llama_context * c) : ctx(c) {}
~llama_context_guard() {
if (ctx) llama_free(ctx);
}
llama_context* release() {
llama_context * tmp = ctx;
ctx = nullptr;
return tmp;
}
};
// 异常安全使用
void safe_inference(const common_params & params) {
llama_model * model = nullptr;
llama_context * ctx = nullptr;
try {
model = llama_load_model_from_file(...);
ctx = llama_new_context_with_model(model, ...);
// 核心推理逻辑
perform_inference(ctx);
} catch (const std::exception & e) {
// 记录错误并清理资源
fprintf(stderr, "Inference failed: %s\n", e.what());
}
// 确保资源释放
if (ctx) llama_free(ctx);
if (model) llama_free(model);
}6.2 性能优化技巧
6.2.1. 内存优化
cpp
// 内存池复用
class token_buffer_pool {
private:
std::vector<std::vector<llama_token>> pool_;
std::mutex pool_mutex_;
public:
std::vector<llama_token>* acquire(size_t size) {
std::lock_guard<std::mutex> lock(pool_mutex_);
for (auto& buffer : pool_) {
if (buffer.capacity() >= size) {
buffer.clear();
buffer.reserve(size);
return &buffer;
}
}
// 创建新缓冲区
pool_.emplace_back();
pool_.back().reserve(size);
return &pool_.back();
}
void release(std::vector<llama_token>* buffer) {
// 缓冲区自动回收到池中，无需显式释放
}
};6.2.2. 计算优化
cpp
// 批处理优化
void optimized_batch_decode(llama_context * ctx,
const std::vector<std::vector<llama_token>>& sequences) {
// 1. 预分配批处理对象
int total_tokens = 0;
for (const auto& seq : sequences) {
total_tokens += seq.size();
}
llama_batch batch = llama_batch_init(total_tokens, 0, sequences.size());
// 2. 高效填充批处理
int token_idx = 0;
for (int seq_id = 0; seq_id < sequences.size(); ++seq_id) {
for (size_t pos = 0; pos < sequences[seq_id].size(); ++pos) {
batch.token[token_idx] = sequences[seq_id][pos];
batch.pos[token_idx] = pos;
batch.n_seq_id[token_idx] = 1;
batch.seq_id[token_idx][0] = seq_id;
batch.logits[token_idx] = (pos == sequences[seq_id].size() - 1);
token_idx++;
}
}
batch.n_tokens = token_idx;
// 3. 批量解码
llama_decode(ctx, batch);
// 4. 清理
llama_batch_free(batch);
}6.3 调试和监控技巧
6.3.1. 性能监控
cpp
// 详细性能分析器
class performance_profiler {
private:
struct profile_entry {
std::string name;
std::chrono::high_resolution_clock::time_point start_time;
double total_time = 0.0;
int call_count = 0;
};
std::unordered_map<std::string, profile_entry> profiles_;
std::mutex profiles_mutex_;
public:
class profile_guard {
performance_profiler& profiler;
profile_entry& entry;
std::chrono::high_resolution_clock::time_point start;
public:
profile_guard(performance_profiler& p, profile_entry& e)
: profiler(p), entry(e), start(std::chrono::high_resolution_clock::now()) {}
~profile_guard() {
auto end = std::chrono::high_resolution_clock::now();
auto duration = std::chrono::duration<double>(end - start).count();
entry.total_time += duration;
entry.call_count++;
}
};
profile_guard profile_scope(const std::string& name) {
std::lock_guard<std::mutex> lock(profiles_mutex_);
return profile_guard(*this, profiles_[name]);
}
void print_report() {
printf("Performance Report:\n");
printf("%-30s %12s %12s %12s\n", "Function", "Total(s)", "Calls", "Avg(ms)");
printf("%-30s %12s %12s %12s\n", "--------", "--------", "-----", "-------");
for (const auto& [name, entry] : profiles_) {
printf("%-30s %12.3f %12d %12.3f\n",
name.c_str(),
entry.total_time,
entry.call_count,
(entry.total_time * 1000) / entry.call_count);
}
}
};
// 使用示例
void perform_inference() {
static performance_profiler profiler;
{
auto guard = profiler.profile_scope("tokenization");
// 分词代码
}
{
auto guard = profiler.profile_scope("model_decode");
// 模型解码代码
}
{
auto guard = profiler.profile_scope("sampling");
// 采样代码
}
}7. 总结
7.1 核心价值
Llama.cpp 的 examples 目录展现了卓越的工程设计：
1. 教学价值极高 ⭐⭐⭐⭐⭐
- 循序渐进的学习路径
- 丰富的注释和文档
- 从入门到专业的完整覆盖
2. 实用性强 ⭐⭐⭐⭐⭐
- 生产就绪的代码质量
- 直接可用的功能模板
- 最佳实践的集中体现
3. 技术深度 ⭐⭐⭐⭐
- 覆盖基础到前沿技术
- 多种优化技术演示
- 深入的底层实现展示
4. 扩展性优秀 ⭐⭐⭐⭐⭐
- 模块化的架构设计
- 插件化的功能扩展
- 灵活的配置系统
7.2 对项目的贡献
这些示例程序不仅为用户提供了学习资源，更为整个 llama.cpp 生态系统做出了重要贡献：
- 降低学习门槛 : 让新用户快速上手
- 提供最佳实践 : 展示标准的开发模式
- 促进技术创新 : 为新技术提供验证平台
- 构建社区生态: 培养开发者社区
7.3 推荐使用策略
对于初学者 ：
1. 从 simple/ 开始，理解基本概念
2. 逐步学习 simple-chat/ 和 embedding/
3. 尝试修改和扩展示例代码
对于开发者 ：
1. 参考 server/ 构建生产服务
2. 使用 batched/ 优化批量处理
3. 研究 speculative/ 了解前沿技术
对于研究者 ：
1. 基于 eval-callback/ 构建实验框架
2. 扩展 training/ 实现新算法
3. 利用 diffusion/ 探索多模态应用
这些示例程序是 llama.cpp 项目的重要财富，为LLM推理技术的发展和应用推广提供了坚实的基础。无论是学习、研究还是生产开发，都能在这里找到有价值的参考和灵感。