mekayelanik/vllm-cpu

vLLM CPU推理引擎 Docker镜像文档

概述

用于在纯CPU系统上运行vLLM的预构建Docker镜像，针对不同CPU指令集进行了优化。

特性：OpenAI兼容API、CPU优化（AVX512、VNNI、BF16、AMX）、多架构支持、健康检查、PUID/PGID用户映射。

要求：4GB+内存（推荐16GB+）、4+ CPU核心、Docker 20.10+、2GB+共享内存。

镜像变体

根据CPU指令集支持选择合适的变体：

可用标签

每个变体有两种标签格式：

• 版本特定：<variant>-<version>（如 avx512bf16-0.12.0）
• 最新版：<variant>-latest（如 avx512bf16-latest）

检查CPU支持

bash
# 检查可用指令集
lscpu | grep -E "avx512|vnni|amx"

# 或使用标志检查
grep -o 'avx512[a-z_]*\|amx[a-z_]*' /proc/cpuinfo | sort -u

快速开始

Docker CLI

bash
# 拉取镜像
docker pull mekayelanik/vllm-cpu:noavx512-latest

# 运行小型模型
docker run -d \
  --name vllm-cpu \

  --restart unless-stopped \
  --cap-add SYS_NICE \
  --security-opt seccomp=unconfined \
  --shm-size 4g \
  -p 8000:8000 \
  -v vllm-data:/data \
  -e VLLM_MODEL=Qwen/Qwen3-0.6B \
  -e VLLM_SERVER_HOST=0.0.0.0 \
  -e VLLM_SERVER_PORT=8000 \
  mekayelanik/vllm-cpu:noavx512-latest \
  --max-model-len 8192

# 查看日志
docker logs -f vllm-cpu

# 测试API
curl http://localhost:8000/v1/models

API端点

Docker Compose示例

标准桥接网络（推荐）

最简单且最具可移植性的配置，适用于大多数部署场景。

yaml
# docker-compose.yml - 标准桥接网络
# 保存此文件后运行：docker compose up -d

services:
  vllm-cpu:
    image: mekayelanik/vllm-cpu:noavx512-latest
    container_name: vllm-cpu
    hostname: vllm-cpu
    domainname: local
    restart: unless-stopped

    # CPU优化所需的权限
    cap_add:
      - SYS_NICE
    security_opt:
      - seccomp=unconfined

    # 模型加载共享内存
    shm_size: 4g

    # 端口映射
    ports:
      - "8000:8000"

    # 持久化存储
    volumes:
      - vllm-data:/data
      - vllm-cache:/data/cache
      # 可选：挂载本地HuggingFace缓存
      # - ${HOME}/.cache/huggingface:/data/models

    # 环境配置
    environment:
      # 用户/组映射（可选）
      - PUID=1000
      - PGID=1000
      - TZ=UTC

      # 模型配置
      - VLLM_MODEL=Qwen/Qwen3-0.6B
      # - HF_TOKEN=your_huggingface_token  # 用于 gated 模型

      # 服务器配置
      - VLLM_SERVER_HOST=0.0.0.0
      - VLLM_SERVER_PORT=8000
      # - VLLM_API_KEY=your_api_key  # 可选API密钥

      # 日志
      - VLLM_LOGGING_LEVEL=INFO
      - VLLM_CONFIGURE_LOGGING=1

      # 内存优化
      - MALLOC_TRIM_THRESHOLD_=100000

      # CPU特定优化（根据系统调整）
      # KV缓存大小（GB）- 增加以支持更多并发请求
      # 默认4GB。公式：(内存 - 模型大小 - 8GB)/2
      - VLLM_CPU_KVCACHE_SPACE=8

    # vLLM参数（传递给入口点）
    command:
      - "--max-model-len"
      - "8192"
      - "--dtype"
      - "auto"

    # 健康检查已内置于Docker镜像（30秒间隔，120秒启动期）

    # 资源限制（可选）
    deploy:
      resources:
        limits:
          memory: 16G
        reservations:
          memory: 4G

# 持久化命名卷
volumes:
  vllm-data:
    driver: local
  vllm-cache:
    driver: local

部署：

bash
# 启动服务
docker compose up -d

# 查看日志
docker compose logs -f vllm-cpu

# 检查状态
docker compose ps

# 停止服务
docker compose down

MACVLAN网络（高级）

MACVLAN为容器提供本地网络上的独立IP地址，使其表现为独立物理设备。适用于：

• 无需端口转发的直接LAN访问
• 运行多个具有唯一IP的vLLM实例
• 与需要专用IP的网络服务集成

前提条件：

• Linux主机（MACVLAN不适用于Mac/Windows的Docker Desktop）
• 知道网络接口名称（如 eth0、ens18、enp0s3）
• 网络范围内的可用IP地址
• 网络接口启用混杂模式（某些设置需要）

yaml
# docker-compose-macvlan.yml - MACVLAN网络配置
# 保存此文件后运行：docker compose -f docker-compose-macvlan.yml up -d

services:
  vllm-cpu:
    image: mekayelanik/vllm-cpu:avx512bf16-latest
    container_name: vllm-cpu
    hostname: vllm-cpu
    domainname: local
    restart: unless-stopped

    # 所需权限
    cap_add:
      - SYS_NICE
    security_opt:
      - seccomp=unconfined

    # 共享内存
    shm_size: 4g

    # MAC地址（为网络生成唯一地址）
    mac_address: "02:42:c0:a8:01:64"

    # 带静态IP的MACVLAN网络
    networks:
      vllm-macvlan:
        ipv4_address: 192.168.1.100

    # 持久化存储
    volumes:
      - vllm-data:/data
      - vllm-cache:/data/cache
      # 挂载本地模型目录
      - /path/to/models:/data/models:ro

    # 环境配置
    environment:
      # 用户/组映射
      - PUID=1000
      - PGID=1000
      - TZ=UTC

      # 模型配置
      - VLLM_MODEL=Qwen/Qwen3-0.6B
      - HF_HOME=/data/models
      # - HF_TOKEN=your_huggingface_token

      # 服务器配置（绑定到所有接口）
      - VLLM_SERVER_HOST=0.0.0.0
      - VLLM_SERVER_PORT=8000

      # 日志
      - VLLM_LOGGING_LEVEL=INFO
      - VLLM_CONFIGURE_LOGGING=1

      # 性能调优
      - MALLOC_TRIM_THRESHOLD_=100000
      - OMP_NUM_THREADS=8
      - MKL_NUM_THREADS=8

      # CPU特定优化
      # KV缓存大小（GB）- 根据内存调整
      - VLLM_CPU_KVCACHE_SPACE=12

    # vLLM参数
    command:
      - "--max-model-len"
      - "16384"
      - "--dtype"
      - "bfloat16"
      - "--cpu-offload-gb"
      - "0"

    # 健康检查已内置于Docker镜像（30秒间隔，120秒启动期）

    # 资源限制
    deploy:
      resources:
        limits:
          memory: 32G
        reservations:
          memory: 8G

# MACVLAN网络定义
networks:
  vllm-macvlan:
    driver: macvlan
    driver_opts:
      # 更改为您的网络接口名称
      parent: eth0
    ipam:
      driver: default
      config:
        # 根据网络配置调整
        - subnet: 192.168.1.0/24
          gateway: 192.168.1.1
          # 容器IP范围（可选，限制可分配IP）
          ip_range: 192.168.1.100/30

# 命名卷
volumes:
  vllm-data:
    driver: local
  vllm-cache:
    driver: local

使用MACVLAN部署：

bash
# 查找网络接口：ip link show
# 创建并启动
docker compose -f docker-compose-macvlan.yml up -d

# 通过专用IP访问
curl http://192.168.1.100:8000/v1/models

注意：使用MACVLAN时，主机无法直接访问容器。如需访问，需在主机上创建macvlan shim接口。

高性能生产服务器

此配置针对高负载、高并发生产环境优化，旨在实现最大吞吐量。适用于高端Intel Xeon或AMD EPYC服务器上的企业部署。

目标硬件：

• 32+ CPU核心（64+线程）
• 128+ GB内存（内存越大，KV缓存越大，支持并发请求越多）
• NVMe存储用于模型文件
• 10GbE+网络

关键优化：VLLM_CPU_KVCACHE_SPACE

CPU推理最重要的设置是KV缓存大小。默认4GB对于生产环境太小。此配置将其设置为40GB以支持高并发。

使用场景：

• 支持数百并发用户的生产API服务
• 高吞吐量批处理
• 企业LLM部署
• 多租户推理服务

yaml
# docker-compose-high-performance.yml - 高负载生产配置
# 针对最大吞吐量和并发优化
# 运行：docker compose -f docker-compose-high-performance.yml up -d

services:
  vllm-cpu-prod:
    image: mekayelanik/vllm-cpu:amxbf16-latest
    container_name: vllm-cpu-prod
    hostname: vllm-prod
    domainname: local
    restart: always

    # 使用主机网络以获得最大网络性能
    network_mode: host

    # 扩展权限以优化性能
    cap_add:
      - SYS_NICE
      - IPC_LOCK
    security_opt:
      - seccomp=unconfined

    # 大共享内存用于并发请求处理
    shm_size: 16g

    # CPU固定用于NUMA优化（根据拓扑调整）
    # cpuset: "0-31"

    # 带性能优化的持久化存储
    volumes:
      # 使用快速NVMe存储存放模型
      - /mnt/nvme/vllm-data:/data
      - /mnt/nvme/vllm-cache:/data/cache
      - /mnt/nvme/models:/data/models:ro
      # tmpfs用于临时文件
      - type: tmpfs
        target: /tmp
        tmpfs:
          size: 4G
          mode: 1777

    # 生产环境配置
    environment:
      # 以root运行以获得最大性能（或设置特定用户）
      # - PUID=0
      # - PGID=0
      - TZ=UTC

      # 模型配置 - 使用功能强大的模型
      - VLLM_MODEL=Qwen/Qwen3-8B
      - HF_HOME=/data/models
      - HF_HUB_OFFLINE=1
      # - HF_TOKEN=your_token

      # 服务器配置
      - VLLM_SERVER_HOST=0.0.0.0
      - VLLM_SERVER_PORT=8000
      - VLLM_API_KEY=${VLLM_API_KEY:-}

      # ============================================================
      # CPU特定vLLM优化（性能关键）
      # ============================================================
      # KV缓存大小（GB）- 关键：默认仅4GB！
      # 根据可用内存和模型大小设置
      # 公式：(总内存 - 模型大小 - 8GB余量)/2
      # 示例：128GB内存，16GB模型 = (128-16-8)/2 = 52GB
      - VLLM_CPU_KVCACHE_SPACE=40

      # OpenMP线程绑定用于CPU亲和性
      # "auto" = 自动绑定，或指定核心如"0-31"
      # 提高缓存局部性并减少上下文切换
      - VLLM_CPU_OMP_THREADS_BIND=0-31

      # 为框架开销保留CPU核心（调度器、HTTP服务器）
      # 这些核心不会用于推理，减少竞争
      - VLLM_CPU_NUM_OF_RESERVED_CPU=2
      # ============================================================

      # 高负载扩展超时
      - VLLM_HTTP_TIMEOUT_KEEP_ALIVE=30
      - VLLM_ENGINE_ITERATION_TIMEOUT_S=300
      - VLLM_RPC_TIMEOUT=30000

      # 日志 - 降低详细度以提高性能
      - VLLM_CONFIGURE_LOGGING=1
      - VLLM_LOGGING_LEVEL=WARNING
      - VLLM_LOG_STATS_INTERVAL=60

      # 内存优化 - 激进设置
      - MALLOC_TRIM_THRESHOLD_=65536
      - MALLOC_MMAP_THRESHOLD_=***
      - MALLOC_MMAP_MAX_=65536

      # 线程 - 设置为（物理核心数 - 保留核心数）
      # 如果有32个核心并保留2个，设置为30
      - OMP_NUM_THREADS=30
      - MKL_NUM_THREADS=30
      - OMP_PROC_BIND=close
      - OMP_PLACES=cores

      # NUMA优化（GNU OpenMP）
      - GOMP_CPU_AFFINITY=0-29

      # 使用tcmalloc获得更好的内存性能
      - LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libtcmalloc_minimal.so.4

      # 禁用使用统计以保护隐私/提高性能
      - VLLM_NO_USAGE_STATS=1
      - VLLM_DO_NOT_TRACK=1

    # 高性能vLLM参数
    command:
      # 上下文长度
      - "--max-model-len"
      - "32768"
      # Intel AMX的数据类型
      - "--dtype"
      - "bfloat16"
      # 高