示例应用

相关源文件

• common/arg.cpp
• common/common.cpp
• common/common.h
• common/sampling.cpp
• common/sampling.h
• examples/embedding/embedding.cpp
• examples/parallel/parallel.cpp
• examples/save-load-state/save-load-state.cpp
• examples/speculative/speculative.cpp
• src/llama-impl.h
• src/llama-sampling.cpp
• src/llama-sampling.h
• tests/test-sampling.cpp

此页面涵盖了 llama.cpp 存储库中提供的示例应用程序，这些应用程序演示了各种推理模式、模型使用场景和集成方法。这些应用程序可作为实现不同类型语言模型交互的实用参考，并展示了使用 llama.cpp 库的最佳实践。

有关核心 CLI 工具和服务器接口的信息，请参阅 命令行界面 和 HTTP 服务器。

目的和示例类别

llama.cpp 中的示例应用程序演示了四个主要的功能类别：

1. 推理模式 - 不同的 token 生成和模型交互方法
2. 性能优化 - 如投机性解码和并行处理等技术
3. 模型状态管理 - 保存、加载和操作模型状态
4. 专用用例 - 嵌入、测试和验证场景

所有示例都共享来自 common/ 目录的公共基础设施，并遵循一致的初始化、参数处理和资源管理模式。

公共基础设施架构

来源：common/common.h543-549 common/common.cpp888-1054 examples/embedding/embedding.cpp73-100 examples/speculative/speculative.cpp32-91

典型的示例应用程序流程

来源：examples/embedding/embedding.cpp73-83 examples/parallel/parallel.cpp155-200 common/common.cpp888-1054

嵌入示例

嵌入示例演示了如何使用具有不同池化策略的语言模型来计算文本嵌入。

主要功能

• 批处理：使用 llama_batch 高效处理多个输入文本
• 池化支持：支持不同的池化类型（LLAMA_POOLING_TYPE_NONE、LLAMA_POOLING_TYPE_RANK）
• 输出格式：提供多种输出格式（JSON、数组、余弦相似度矩阵）
• 内存优化：在嵌入之间清除 KV 缓存以提高内存效率

核心处理函数

batch_decode() 函数处理核心的嵌入计算

来源：examples/embedding/embedding.cpp36-71 examples/embedding/embedding.cpp114-117 examples/embedding/embedding.cpp56-69

投机性解码示例

投机性解码示例演示了一种高级推理技术，该技术使用一个较小的草稿模型生成候选 token，然后由一个较大的目标模型进行验证。

架构组件

• 目标模型：用于最终 token 决策的主要模型
• 草稿模型：用于生成候选的较小、较快的模型
• 序列管理：使用 seq_draft 结构处理多个草稿序列
• 验证逻辑：实现随机和贪婪的验证策略

投机性解码过程

来源：examples/speculative/speculative.cpp18-30 examples/speculative/speculative.cpp240-366 examples/speculative/speculative.cpp367-380

并行处理示例

并行示例模拟了一个具有多个并发客户端进行请求的服务器环境，以演示批处理推理功能。

客户端管理

每个客户端由一个 client 结构表示，该结构包含：

• 用于 KV 缓存管理的序列 ID
• 带 common_sampler 的采样上下文
• 请求状态和时间信息
• 输入提示和生成的响应

批处理架构

来源：examples/parallel/parallel.cpp105-131 examples/parallel/parallel.cpp275-300 examples/parallel/parallel.cpp250-268

状态管理示例

save-load-state 示例演示了如何序列化和还原完整的模型状态，包括 KV 缓存、RNG 状态和 logits。

状态操作

该示例执行三个关键操作：

1. 完整状态序列化：将完整上下文状态保存到文件
2. 状态还原：将状态加载到新上下文中
3. 序列状态管理：在序列 ID 之间复制 KV 缓存

状态管理流程

来源：examples/save-load-state/save-load-state.cpp62-71 examples/save-load-state/save-load-state.cpp108-125 examples/save-load-state/save-load-state.cpp188-209

测试与验证

采样测试框架提供了对采样算法及其数值属性的全面验证。

测试基础设施

名为 sampler_tester 的类提供了一个用于测试采样行为的框架。

• 使用具有已知概率的 token 分布进行初始化
• 通过 llama_sampler 接口应用采样算法
• 验证预期的概率分布

采样算法覆盖范围

来源：tests/test-sampling.cpp64-73 tests/test-sampling.cpp86-95 tests/test-sampling.cpp139-159 tests/test-sampling.cpp161-182

常见模式和最佳实践

参数管理

所有示例都使用 common_params_parse() 进行一致的参数处理，并使用 common_init_from_params() 进行模型初始化。这为应用程序提供了标准化的选项。

资源管理

示例遵循一致的资源清理模式

• 使用 common_sampler_free() 或 llama_sampler_free() 释放采样器
• 使用 llama_batch_free() 释放批次
• 在 common_init_result 中使用智能指针的 RAII 模式

错误处理

通用的错误处理模式包括

• 模型加载成功的验证
• 检查批次处理结果
• 验证分词和上下文限制

性能考量

示例展示了几种优化技术

• 批量处理多个序列
• KV 缓存管理和清除
• 内存高效的嵌入计算
• 投机解码以提高吞吐量

来源：common/common.cpp888-1054 common/common.h543-549 examples/embedding/embedding.cpp333-335 examples/parallel/parallel.cpp333-350