用户界面

相关源文件

• .gitignore
• CMakeLists.txt
• Makefile
• README.md
• common/chat-parser.cpp
• common/chat-parser.h
• common/chat.cpp
• common/chat.h
• common/json-partial.cpp
• common/json-partial.h
• examples/CMakeLists.txt
• models/templates/Qwen-Qwen3-0.6B.jinja
• models/templates/README.md
• tests/test-chat.cpp
• tools/server/README.md
• tools/server/server.cpp
• tools/server/tests/unit/test_template.py
• tools/server/tests/unit/test_tool_call.py
• tools/server/tests/utils.py
• tools/server/utils.hpp

本文档涵盖了 llama.cpp 提供的用于与语言模型交互的用户界面。这些界面包括用于直接模型交互的命令行工具，以及提供 OpenAI 兼容 API 的 HTTP 服务器。有关底层核心库架构的信息，请参阅 核心库架构。有关模型管理和转换工具的详细信息，请参阅 模型管理。

概述

llama.cpp 项目提供了几类用户界面：

• 主要 CLI 工具：用于交互式文本生成和对话的 llama-cli
• HTTP 服务器：提供具有 OpenAI 兼容性的 REST API 端点的 llama-server
• 专用工具：用于基准测试、困惑度测量和模型分析的实用工具
• 示例应用程序：演示库使用模式的参考实现

用户界面架构

来源：README.md303-513 Makefile6-49 examples/CMakeLists.txt14-43

命令行界面

llama-cli

主要的命令行界面通过 llama-cli 二进制文件提供了对 llama.cpp 功能的全面访问。它支持交互式对话模式和单次文本补全。

主要功能

• 根据对话模板自动检测对话模式
• 通过 --chat-template 参数支持自定义对话模板
• 使用 GBNF 文件进行语法约束生成
• 交互式和批量处理模式
• 可配置的采样参数

使用模式

CLI 与对话模板系统集成，以一致地格式化对话，并支持直接从 HuggingFace 仓库下载模型。

来源：README.md303-364 tools/main/README.md

专用 CLI 工具

llama-perplexity：在文本数据集上测量模型质量指标

llama-bench：用于推理速度测量的性能基准测试工具

llama-run：具有 RamaLama 集成的综合运行器

llama-simple：演示基本库用法的最小示例

来源：README.md436-513 Makefile6-49

HTTP 服务器

llama-server

HTTP 服务器提供了一个生产级的、与 OpenAI 兼容的 REST API，支持多个并发用户和函数调用、多模态处理等高级功能。

核心服务器组件

• server_slot：管理具有状态跟踪的独立推理会话 tools/server/server.cpp46-52
• server_queue：处理任务调度和并发请求管理
• server_task：表示具有参数解析的独立推理请求 tools/server/server.cpp193-221

关键端点

端点	目的	OpenAI 兼容
/v1/chat/completions	基于聊天的文本生成	✓
/v1/completions	原始文本补全	✓
/v1/embeddings	文本嵌入	✓
/v1/models	模型信息	✓
/v1/rerank	文档重排序	自定义
/health	服务器健康检查	自定义
/metrics	性能指标	自定义

使用示例

请求处理流程

服务器支持流式和非流式响应，并自动应用对话模板和 OpenAI 兼容的响应格式。

来源：tools/server/server.cpp1-100 tools/server/README.md1-50 tools/server/utils.hpp1-50

与核心系统的集成

对话模板处理

用户界面集成了对话模板系统，以实现一致的消息格式化。

聊天系统支持多种格式，包括通用模板、Llama 3.x、Mistral Nemo 和自定义 Jinja 模板，并根据模型元数据自动检测格式。

参数管理

用户界面通过 common_params 系统共享通用的参数处理。

• 模型参数：路径、量化、上下文大小
• 采样参数：温度、top-k、top-p、惩罚项
• 生成参数：Token 限制、停止序列
• 硬件参数：GPU 层数、批处理大小、线程数

服务器通过 HTTP 特定的参数（如槽位管理和 API 密钥）扩展了这一点，同时保持与核心参数系统的兼容性。

来源：common/chat.h115-139 common/chat.cpp1-50 tools/server/server.cpp223-300

测试与验证

用户界面包含全面的测试框架

• 服务器测试：HTTP 端点验证，OpenAI 兼容性测试 tools/server/tests/utils.py1-50
• 对话模板测试：模板处理和工具调用验证 tests/test-chat.cpp1-100
• 集成测试：使用真实模型进行端到端工作流测试

测试框架支持对单个组件的单元测试和对完整工作流的集成测试，确保在不同部署场景下的可靠性。

来源：tools/server/tests/utils.py35-50 tools/server/tests/unit/test_template.py1-50 tests/test-chat.cpp1-50