Docker 部署

警告

本页面记录了 LMCache 的进程内模式（已弃用）的行为。请考虑使用 LMCache MP 模式 以获得更好的功能支持和性能。有关此页面的 MP 模式等效内容，请参见 部署指南。

前提条件： Docker Engine 27.0+

请参阅 安装 以获取拉取镜像的信息。

运行容器

IMAGE=<IMAGE_NAME>:<TAG>
mkdir -p "$HOME/.cache/huggingface"
docker run --runtime nvidia --gpus all \
    --env "HF_TOKEN=<REPLACE_WITH_YOUR_HF_TOKEN>" \
    --env "LMCACHE_CHUNK_SIZE=256" \
    --env "LMCACHE_LOCAL_CPU=True" \
    --env "LMCACHE_MAX_LOCAL_CPU_SIZE=5" \
    --volume "$HOME/.cache/huggingface:/home/lmcache/.cache/huggingface" \
    --network host \
    $IMAGE \
    meta-llama/Llama-3.1-8B-Instruct --kv-transfer-config \
    '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'

有关更多详细信息，请参见 docker run 示例。

The official CUDA vLLM and standalone images run as lmcache (uid 1000). The bind mount above reuses the host's existing Hugging Face cache. Its directory and contents must be readable and writable by container uid 1000; configure host permissions or ACLs if the cache has different ownership.

For a separate Docker-managed cache, replace the mount with --volume hf-cache:/home/lmcache/.cache/huggingface. A new empty named volume inherits the image's pre-created cache directory ownership; existing volumes retain their permissions. It does not reuse models in the host's cache. To reuse an old /root cache, use --user 0 and retain its original mount path.

ROCm (AMD)

AMD Infinity hub 为 vLLM 提供了一个预构建的、优化的镜像，适用于 AMD Instinct™ MI300X。有关完整说明，请参见 LLM 推理性能验证在 AMD Instinct MI300X 上。

验证的环境：rocm/vllm-dev:nightly_0624_rc2_0624_rc2_20250620, MI300X, vLLM V1.

docker run -it \
    --network=host \
    --group-add=video \
    --ipc=host \
    --cap-add=SYS_PTRACE \
    --security-opt seccomp=unconfined \
    --device /dev/kfd \
    --device /dev/dri \
    -v <path_to_your_models>:/app/model \
    -e HF_HOME="/app/model" \
    --name lmcache_rocm \
    rocm/vllm-dev:nightly_0624_rc2_0624_rc2_20250620 \
    bash

XPU（英特尔）

Intel vLLM XPU hub 提供了一个预构建的、优化的 Docker 镜像，旨在验证在 Intel GPU 加速器（如 ARC770、B60/B70 及未来产品）上的推理性能。

验证环境：intel/vllm:0.17.0-xpu, Intel B60 GPU, vLLM V1。

docker run --privileged \
    -it --rm --name vllm-xpu \
    -u root \
    --ipc=host --net=host \
    --cap-add=ALL \
    --device /dev/dri:/dev/dri \
    -v /dev/dri/by-path:/dev/dri/by-path \
    --entrypoint /bin/bash intel/vllm:0.17.0-xpu