Llamacpp 后端

llamacpp 后端通过集成 llama.cpp 来促进大型语言模型 (LLM) 的部署，llama.cpp 是一个为 CPU 和 GPU 计算优化的先进推理引擎。此后端是 Hugging Face 的 Text Generation Inference (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 生成不适合您的用例，您可以提供您自己的 GGUF 文件，使用 --model-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`	禁用 flash attention
`--type-k`	用于 K 缓存的数据类型
`--type-v`	用于 V 缓存的数据类型
`--validation-workers`	用于有效负载验证和截断的分词器工作程序数量
`--max-concurrent-requests`	最大并发请求数
`--max-input-tokens`	每个请求的最大输入 tokens 数
`--max-total-tokens`	每个请求的最大总 tokens 数（输入 + 输出）
`--max-batch-total-tokens`	一个批次中的最大 tokens 数
`--max-physical-batch-total-tokens`	一个物理批次中的最大 tokens 数
`--max-batch-size`	每个批次的最大请求数

< > 在 GitHub 上更新