在從 Ollama 轉向生產級推理引擎 vLLM 的過程中，部署本地 GGUF 模型往往是開發者的噩夢。本文將總結常見的報錯陷阱，並提供一份在 RTX 4090 上實測通過的「終極版」Docker Compose 範本。

⚠️ 那些年我踩過的坑（常見報錯條列）

在成功啟動之前，你可能會遇到以下幾種令人崩潰的報錯：

1. vllm: error: unrecognized arguments

• 主因： vLLM v0.13 版後對 serve 指令極其嚴格，若將路徑直接放在 serve 後面卻沒宣告格式，解析器會崩潰。

2. Error retrieving safetensors: Repo id must be in the form...

• 主因： vLLM 誤將本地路徑 /models/xxx.gguf 當作 Hugging Face 的倉庫 ID。

3. huggingface_hub.errors.LocalEntryNotFoundError

• 主因： 開啟了離線模式（HF_HUB_OFFLINE=1）但本地快取中缺少 Tokenizer 的元數據文件。

4. RuntimeError: Failed to infer device type

• 主因： Docker 容器未正確掛載 NVIDIA Runtime，導致 vLLM 在啟動檢查時找不到 GPU。

🚀 終極解決方案：Docker Compose 範本

version: '3.8'

services:
  # 服務一：Qwen3-8B 推理後端
  vllm-qwen-8b:
    image: vllm/vllm-openai:latest
    container_name: vllm-qwen3-8b
    # 關鍵：必須分配 GPU 資源
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    ipc: host # 建議開啟，提升 GPU 通訊效能
    environment:
      - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN}
      - HF_HUB_OFFLINE=0 # 初次啟動建議設為 0 以抓取 Tokenizer
    volumes:
      - ./models:/models
      - ~/.cache/huggingface:/root/.cache/huggingface
    # 採用陣列格式傳遞參數，避開 Shell 解析錯誤
    command:
      - "--model"
      - "/models/Qwen3-8B-Q8_0.gguf"
      - "--tokenizer"
      - "Qwen/Qwen3-8B" 
      - "--quantization"
      - "gguf"
      - "--load-format"
      - "gguf"
      - "--max-model-len"
      - "2048"
      - "--gpu-memory-utilization"
      - "0.6" # 可依個人GPU VRAM而定，這是4090的建議配置
      - "--enable-auto-tool-choice"
      - "--tool-call-parser"
      - "openai"
    restart: unless-stopped

🛠️ 核心參數深度解析