Llamacpp 后端

Llamacpp 后端通过集成 llama.cpp（一个针对 CPU 和 GPU 计算优化的先进推理引擎）来促进大型语言模型（LLM）的部署。此后端是 Hugging Face 的 文本生成推理 (TGI) 套件的组成部分，专门用于简化 LLM 在生产环境中的部署。

主要功能

完全兼容 GGUF 格式和所有量化格式（GGUF 相关限制可在未来更新中通过动态即时生成来缓解）
在 CPU 和 GPU 架构上优化推理
容器化部署，消除依赖复杂性
与 Hugging Face 生态系统无缝互操作

模型兼容性

此后端利用 GGUF 格式的模型，在计算效率和模型精度之间提供最佳平衡。您可以在 Hugging Face 上找到最佳模型。

构建 Docker 镜像

为了获得最佳性能，Docker 镜像默认使用原生 CPU 指令进行编译。因此，强烈建议在与构建过程相同的宿主架构上运行容器。目前正在努力提高不同系统之间的可移植性，同时保持高计算效率。

要构建 Docker 镜像，请使用以下命令：

docker build \
    -t tgi-llamacpp \
    https://github.com/huggingface/text-generation-inference.git \
    -f Dockerfile_llamacpp

构建参数

参数（带 —build-arg）	描述
`llamacpp_version=bXXXX`	llama.cpp 的特定版本
`llamacpp_cuda=ON`	启用 CUDA 加速
`llamacpp_native=OFF`	禁用自动 CPU 检测
`llamacpp_cpu_arm_arch=ARCH[+FEATURE]...`	特定的 ARM CPU 和功能
`cuda_arch=ARCH`	定义目标 CUDA 架构

例如，在其他 ARM 架构上构建时以 Graviton4 为目标

docker build \
    -t tgi-llamacpp \
    --build-arg llamacpp_native=OFF \
    --build-arg llamacpp_cpu_arm_arch=armv9-a+i8mm \
    https://github.com/huggingface/text-generation-inference.git \
    -f Dockerfile_llamacpp

运行 Docker 镜像

基于 CPU 的推理

docker run \
    -p 3000:3000 \
    -e "HF_TOKEN=$HF_TOKEN" \
    -v "$HOME/models:/app/models" \
    tgi-llamacpp \
    --model-id "Qwen/Qwen2.5-3B-Instruct"

GPU 加速推理

docker run \
    --gpus all \
    -p 3000:3000 \
    -e "HF_TOKEN=$HF_TOKEN" \
    -v "$HOME/models:/app/models" \
    tgi-llamacpp \
    --n-gpu-layers 99
    --model-id "Qwen/Qwen2.5-3B-Instruct"

使用自定义 GGUF

GGUF 文件是可选的，如果 models 目录中不存在，则会在启动时自动生成。但是，如果默认的 GGUF 生成不适合您的用例，您可以使用 --model-gguf 提供您自己的 GGUF 文件，例如：

docker run \
    -p 3000:3000 \
    -e "HF_TOKEN=$HF_TOKEN" \
    -v "$HOME/models:/app/models" \
    tgi-llamacpp \
    --model-id "Qwen/Qwen2.5-3B-Instruct" \
    --model-gguf "models/qwen2.5-3b-instruct-q4_0.gguf"

请注意，--model-id 仍然是必需的。

高级参数

所有可配置参数的完整列表可在 --help 中查看

docker run tgi-llamacpp --help

下表总结了关键选项

参数	描述
`--n-threads`	用于生成的线程数
`--n-threads-batch`	用于批处理的线程数
`--n-gpu-layers`	存储在 VRAM 中的层数
`--split-mode`	在多个 GPU 上拆分模型
`--defrag-threshold`	如果孔洞/大小 > 阈值，则碎片整理 KV 缓存
`--numa`	启用 NUMA 优化
`--disable-mmap`	禁用模型的内存映射
`--use-mlock`	使用内存锁定以防止交换
`--disable-offload-kqv`	禁用将 KQV 操作卸载到 GPU
`--disable-flash-attention`	禁用闪存注意力
`--type-k`	K 缓存使用的数据类型
`--type-v`	V 缓存使用的数据类型
`--validation-workers`	用于负载验证和截断的分词器工作器数量
`--max-concurrent-requests`	最大并发请求数
`--max-input-tokens`	每个请求的最大输入 token 数
`--max-total-tokens`	每个请求的最大总 token 数（输入 + 输出）
`--max-batch-total-tokens`	批处理中的最大 token 数
`--max-physical-batch-total-tokens`	物理批处理中的最大 token 数
`--max-batch-size`	每个批处理的最大请求数

< > 在 GitHub 上更新