llama-cpp

llama.cpp 运维

将每个启动方案视为针对特定构建版本、模型、主机和工作负载的假设。通过已安装的二进制文件了解其功能，检查模型和启动日志，然后测量所需边界。

运维约定

1. 记录确切的 llama.cpp 版本或提交、安装方式、操作系统和架构、CPU 和 RAM、加速器及其内存、驱动程序／工具包、可用设备、模型来源和量化方式、预期上下文长度、并发量及工作负载。
2. 使用文档中的某个标志前，先阅读已安装命令的 --help。llama.cpp 的标志、默认值、二进制文件名称和 REST 行为经常变化。
3. 操作前确认目标、范围和回滚路径。只读探查无需确认即可进行。
4. 根据 --list-devices 和模型加载日志确认后端。构建成功或接受了 GPU 标志，并不能证明加速已启用。
5. 先在回环地址或使用本地输入进行有界 CLI 冒烟测试。调整线程数、批次、上下文长度、缓存类型、卸载或拆分模式前，先建立实测基线。
6. 仅在达到所需边界时才算完成：二进制文件、模型加载、生成输出、API 响应、基准测试对比，或有证据支持的故障诊断结果。

何时不应使用

模型训练、微调、广泛的量化方法论、评估设计，或在 llama.cpp、vLLM、TGI 和其他引擎之间进行选择时，请使用 ml-engineering。使用 Ollama、LM Studio 或 LlamaIndex 时，请使用相应产品的技能。对于 llama-cpp-python、node-llama-cpp 或其他语言封装，请查阅对应绑定的文档。

只读预检

仅运行已安装构建版本中存在的命令：

llama-cli --version
llama-cli --help
llama-cli --list-devices
llama-server --version
llama-server --help
llama-bench --help

同时使用原生操作系统／供应商工具检查主机内存和加速器状态。将结果记录在运维记录中。如果不存在二进制文件，请先阅读安装与后端，再选择安装路径。

选择任务路径

需求	优先阅读
安装、构建、选择 CPU/Metal/CUDA/HIP/Vulkan/SYCL、Docker，或验证后端是否启用	安装与后端
获取、转换、检查或许可核查 GGUF 模型，对其进行量化，或评估其是否适用	模型、GGUF 与内存
运行 llama-cli、提供 llama-server 服务、调用兼容 API、使用模板、结构化输出、嵌入、重排或工具	推理与服务
调整线程数、批次、上下文长度、缓存、卸载、并发或多 GPU，并比较结果	性能与基准测试
诊断加载、后端、OOM、速度、上下文、模板、输出或 API 故障	故障排除
核查某项声明所依据的证据、研究日期、上游修订版本或刷新规则	来源索引

批量推理与交互式聊天

对于将该前端与交互式 llama-cli 分离的构建版本，请使用 llama-completion 执行无人值守的原始补全。已安装的 CLI 可能会在帮助信息中列出共用标志，但在运行时仍拒绝该标志；仅凭存在 --no-conversation 不能证明支持批处理。如果缺少补全目标，切勿回退到交互式前端。使用 scripts/llama_batch.py 前，请先阅读有界批量推理。其 plan 命令会执行有界的只读能力检查；run 会写入新的私有输出目录并占用 GPU 资源。该辅助工具目前支持采用完整模型卸载的 POSIX CUDA0；其他后端应使用经过单独验证的工作流。

限制进程的墙钟时间和 stdout/stderr 合计字节数，传入 EOF 标准输入，保留失败日志，并且只停止由你启动的进程组。仅设置 token 预算无法限制交互式提示词循环。不要将运行时输出累积到无界的 capture_output=True 缓冲区中。切勿隐瞒 GPU 回退，也不要把已准备好的计划称为已执行的推理流程。

安全工作流

1. 选择并验证安装方式

如果受支持的软件包或发布二进制文件所编译的后端与目标匹配，优先使用它们。当后端选项、可移植性或可复现性有要求时，应从固定版本修订构建。需要隔离主机且已了解设备直通时，可使用 Docker。安装后，在宣称成功前，应记录版本、帮助信息、设备列表和模型加载日志。

2. 选择并检查模型

接受用户指定的本地 GGUF 路径或 Hugging Face 仓库。下载前，记录仓库、修订版本、文件、大小、模型卡、许可证、基础模型沿袭信息，以及量化器（若可用）。检查 GGUF 元数据和模型加载输出，确认架构、量化、上下文、分词器、聊天模板和附属文件。根据实际文件大小，以及 KV 缓存、上下文、批次/并发、计算缓冲区和后端开销来规划容量；仅凭参数量不足以进行规划。

不要声称某一种量化方式在任何情况下都是最佳选择。应从工作负载的质量和容量限制出发；若有更高精度的来源模型可用，应避免对已量化模型再次量化，并使用相同的任务质量和性能工作负载比较候选量化版本。

3. 验证本地推理

使用简短且固定的提示词，并限制 token 数量。记录确切命令、种子或采样设置、启动日志、输出、耗时，以及预期后端是否已加载。如果模型有聊天模板，应测试目标工作负载所需的模板路径，而不要将纯补全视为聊天能力的证明。

4. 验证服务

首次启动时绑定到 127.0.0.1。等待 /health 报告就绪，查询 /v1/models，然后使用报告的模型标识符发起有代表性的请求。进程正在监听，或浅层端点返回 HTTP 200，都不能证明推理正常。对外开放服务前，必须明确决定绑定地址、API 密钥、TLS 或反向代理、防火墙、CORS、速率限制、日志记录，以及是否禁用实验性的内置工具。

5. 一次调整一个维度

在更改上下文大小、生成和批处理线程数、逻辑或物理批次大小、GPU 层数、KV 缓存类型/卸载、Flash Attention、并行槽位或多 GPU 拆分前，先保留基线。使用 llama-bench 比较提示词处理和 token 生成性能，并使用端到端客户端或服务端基准测试测量 TTFT 和请求延迟。每次比较都记录在基准测试模板中。

严格边界

• 不要仅凭命令行推断是否使用了加速器；必须有设备和负载日志证据。
• 不要意外将未经身份验证的服务暴露在回环地址之外。身份验证不能替代网络和 TLS 控制。
• 不要打印或使用 tee 输出未经脱敏的单元定义、进程环境、环境文件内容、API 密钥或其他包含凭据的配置。优先使用脱敏元数据；切勿仅为留存证据而保留密钥。如果要精确回滚必须备份包含密钥的内容，请将其临时保存在仓库之外，权限设为 0600，尽可能缩短保留时间，并明确清理。
• 不要发布原始密钥哈希或熵较低的密钥哈希。
• 不要在不可信环境中启用 llama-server 内置的文件系统或 shell 工具。
• 检查模型元数据、原始模型卡和渲染后的行为之前，不要覆盖聊天模板。
• 对于 finish_reason: "length"、reasoning_content 有内容而 content 为空的情况，请检查受访问控制的原始响应，但仅报告脱敏后的字段状态、长度、finish_reason 和 usage。基于同一基线，分别进行只改变一个变量的探测：适度提高输出预算；如果确切的模板支持，则设置 chat_template_kwargs.enable_thinking: false。对于流式响应，请检查文档所述的 choices[].delta.reasoning_content、choices[].delta.content 和终止项 choices[].finish_reason 的结构；逐项记录为缺失、null、空或有内容，不要假设它们必定存在。将 reasoning_effort: "none" 和服务端推理标记视为依赖版本且需经源代码验证的替代方案，而非通用默认设置。
• 不要把来自不同模型、量化版本、提交、后端、上下文、批次、热状态或工作负载的基准数据，当作只改变了一个变量的数据进行比较。
• 不要将 llama-bench 的每秒 token 数视为 TTFT；其测量不包括分词和采样。
• 除非模型及其缩放行为支持，否则不要声称配置更大的上下文能保持质量；并且必须对工作负载进行评估。

完成标准

当请求的边界有证据支持时，任务即告完成：已观察到预期的二进制文件和后端；已记录所选模型的来源和适用性；有界提示词返回了可用输出；服务已就绪并完成了有代表性的 API 请求；调优更改在匹配条件下优于或维持了声明的指标；或者已将故障缩小到有依据的原因，并确定了安全的后续操作。列出任何未测试的更高边界。