Llamacpp 後端

Llamacpp 後端透過整合 llama.cpp（一個針對 CPU 和 GPU 運算進行優化的進階推論引擎），促進了大型語言模型 (LLMs) 的部署。此後端是 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 產生方式不符合您的使用需求，您可以使用 `--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`	使用記憶體鎖定以防止交換 (swapping)
`--disable-offload-kqv`	停用將 KQV 運算卸載至 GPU
`--disable-flash-attention`	停用 Flash Attention
`--type-k`	用於 K 快取的資料類型
`--type-v`	用於 V 快取的資料類型
`--validation-workers`	用於負載驗證與截斷的 Tokenizer 工作執行緒數量
`--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 上更新