A high-throughput and memory-efficient inference and serving engine for LLMs
Mirrored from https://github.com/tduncan-lum/Nvidia-Optimization-Stack---VLLM.git
Synced Nov 9, 16:00 UTC
[CPU] Improve CPU Docker build (#30953)
Signed-off-by: Maryam Tahhan <mtahhan@redhat.com> Co-authored-by: Li, Jiang <jiang1.li@intel.com>
Maryam Tahhan committed
Jan 24, 2026 at 17:08 UTC
203d0bc0c29bfb02e682505fd3813c9b3cd3da55
3 files changed
+123
-17
cmake/cpu_extension.cmake
+12
@@ -13,6 +13,8 @@ endif()
13
#
14
# Define environment variables for special configurations
15
#
16
+set(ENABLE_AVX2 $ENV{VLLM_CPU_AVX2})
17
+set(ENABLE_AVX512 $ENV{VLLM_CPU_AVX512})
18
set(ENABLE_AVX512BF16 $ENV{VLLM_CPU_AVX512BF16})
19
set(ENABLE_AVX512VNNI $ENV{VLLM_CPU_AVX512VNNI})
20
set(ENABLE_AMXBF16 $ENV{VLLM_CPU_AMXBF16})
@@ -103,6 +105,16 @@ else()
105
find_isa(${CPUINFO} "bf16" ARM_BF16_FOUND) # Check for ARM BF16 support
106
find_isa(${CPUINFO} "S390" S390_FOUND)
107
find_isa(${CPUINFO} "v" RVV_FOUND) # Check for RISC-V RVV support
108
+
109
+ # Support cross-compilation by allowing override via environment variables
110
+ if (ENABLE_AVX2)
111
+ set(AVX2_FOUND ON)
112
+ message(STATUS "AVX2 support enabled via VLLM_CPU_AVX2 environment variable")
113
+ endif()
114
+ if (ENABLE_AVX512)
115
+ set(AVX512_FOUND ON)
116
+ message(STATUS "AVX512 support enabled via VLLM_CPU_AVX512 environment variable")
117
+ endif()
118
endif()
119
120
if (AVX512_FOUND AND NOT AVX512_DISABLED)
docker/Dockerfile.cpu
+50
-11
@@ -15,9 +15,11 @@
15
# Build arguments:
16
# PYTHON_VERSION=3.13|3.12 (default)|3.11|3.10
17
# VLLM_CPU_DISABLE_AVX512=false (default)|true
18
-# VLLM_CPU_AVX512BF16=false (default)|true
19
-# VLLM_CPU_AVX512VNNI=false (default)|true
20
-# VLLM_CPU_AMXBF16=false |true (default)
18
+# VLLM_CPU_AVX2=false (default)|true (for cross-compilation)
19
+# VLLM_CPU_AVX512=false (default)|true (for cross-compilation)
20
+# VLLM_CPU_AVX512BF16=false (default)|true (for cross-compilation)
21
+# VLLM_CPU_AVX512VNNI=false (default)|true (for cross-compilation)
22
+# VLLM_CPU_AMXBF16=false (default)|true (for cross-compilation)
23
#
24
25
######################### COMMON BASE IMAGE #########################
@@ -54,9 +56,12 @@ ENV PIP_EXTRA_INDEX_URL=${PIP_EXTRA_INDEX_URL}
56
ENV UV_EXTRA_INDEX_URL=${PIP_EXTRA_INDEX_URL}
57
ENV UV_INDEX_STRATEGY="unsafe-best-match"
58
ENV UV_LINK_MODE="copy"
59
+
60
+# Copy requirements files for installation
61
+COPY requirements/common.txt requirements/common.txt
62
+COPY requirements/cpu.txt requirements/cpu.txt
63
+
64
RUN --mount=type=cache,target=/root/.cache/uv \
58
- --mount=type=bind,src=requirements/common.txt,target=requirements/common.txt \
59
- --mount=type=bind,src=requirements/cpu.txt,target=requirements/cpu.txt \
65
uv pip install --upgrade pip && \
66
uv pip install -r requirements/cpu.txt
67
@@ -88,6 +93,12 @@ ARG GIT_REPO_CHECK=0
93
# Support for building with non-AVX512 vLLM: docker build --build-arg VLLM_CPU_DISABLE_AVX512="true" ...
94
ARG VLLM_CPU_DISABLE_AVX512=0
95
ENV VLLM_CPU_DISABLE_AVX512=${VLLM_CPU_DISABLE_AVX512}
96
+# Support for cross-compilation with AVX2 ISA: docker build --build-arg VLLM_CPU_AVX2="1" ...
97
+ARG VLLM_CPU_AVX2=0
98
+ENV VLLM_CPU_AVX2=${VLLM_CPU_AVX2}
99
+# Support for cross-compilation with AVX512 ISA: docker build --build-arg VLLM_CPU_AVX512="1" ...
100
+ARG VLLM_CPU_AVX512=0
101
+ENV VLLM_CPU_AVX512=${VLLM_CPU_AVX512}
102
# Support for building with AVX512BF16 ISA: docker build --build-arg VLLM_CPU_AVX512BF16="true" ...
103
ARG VLLM_CPU_AVX512BF16=0
104
ENV VLLM_CPU_AVX512BF16=${VLLM_CPU_AVX512BF16}
@@ -100,18 +111,19 @@ ENV VLLM_CPU_AMXBF16=${VLLM_CPU_AMXBF16}
111
112
WORKDIR /workspace/vllm
113
114
+# Copy build requirements
115
+COPY requirements/cpu-build.txt requirements/build.txt
116
+
117
RUN --mount=type=cache,target=/root/.cache/uv \
104
- --mount=type=bind,src=requirements/cpu-build.txt,target=requirements/build.txt \
118
uv pip install -r requirements/build.txt
119
120
COPY . .
108
-RUN --mount=type=bind,source=.git,target=.git \
109
- if [ "$GIT_REPO_CHECK" != 0 ]; then bash tools/check_repo.sh ; fi
121
+
122
+RUN if [ "$GIT_REPO_CHECK" != 0 ]; then bash tools/check_repo.sh ; fi
123
124
RUN --mount=type=cache,target=/root/.cache/uv \
125
--mount=type=cache,target=/root/.cache/ccache \
126
--mount=type=cache,target=/workspace/vllm/.deps,sharing=locked \
114
- --mount=type=bind,source=.git,target=.git \
127
VLLM_TARGET_DEVICE=cpu python3 setup.py bdist_wheel --dist-dir=dist --py-limited-api=cp38
128
129
######################### TEST DEPS #########################
@@ -119,9 +131,11 @@ FROM base AS vllm-test-deps
131
132
WORKDIR /workspace/vllm
133
134
+# Copy test requirements
135
+COPY requirements/test.in requirements/cpu-test.in
136
+
137
# TODO: Update to 2.9.0 when there is a new build for intel_extension_for_pytorch for that version
123
-RUN --mount=type=bind,src=requirements/test.in,target=requirements/test.in \
124
- cp requirements/test.in requirements/cpu-test.in && \
138
+RUN \
139
sed -i '/mamba_ssm/d' requirements/cpu-test.in && \
140
remove_packages_not_supported_on_aarch64() { \
141
case "$(uname -m)" in \
@@ -200,4 +214,29 @@ RUN --mount=type=cache,target=/root/.cache/uv \
214
--mount=type=bind,from=vllm-build,src=/workspace/vllm/dist,target=dist \
215
uv pip install dist/*.whl
216
217
+# Add labels to document build configuration
218
+LABEL org.opencontainers.image.title="vLLM CPU"
219
+LABEL org.opencontainers.image.description="vLLM inference engine for CPU platforms"
220
+LABEL org.opencontainers.image.vendor="vLLM Project"
221
+LABEL org.opencontainers.image.source="https://github.com/vllm-project/vllm"
222
+
223
+# Build configuration labels
224
+ARG TARGETARCH
225
+ARG VLLM_CPU_DISABLE_AVX512
226
+ARG VLLM_CPU_AVX2
227
+ARG VLLM_CPU_AVX512
228
+ARG VLLM_CPU_AVX512BF16
229
+ARG VLLM_CPU_AVX512VNNI
230
+ARG VLLM_CPU_AMXBF16
231
+ARG PYTHON_VERSION
232
+
233
+LABEL ai.vllm.build.target-arch="${TARGETARCH}"
234
+LABEL ai.vllm.build.cpu-disable-avx512="${VLLM_CPU_DISABLE_AVX512:-false}"
235
+LABEL ai.vllm.build.cpu-avx2="${VLLM_CPU_AVX2:-false}"
236
+LABEL ai.vllm.build.cpu-avx512="${VLLM_CPU_AVX512:-false}"
237
+LABEL ai.vllm.build.cpu-avx512bf16="${VLLM_CPU_AVX512BF16:-false}"
238
+LABEL ai.vllm.build.cpu-avx512vnni="${VLLM_CPU_AVX512VNNI:-false}"
239
+LABEL ai.vllm.build.cpu-amxbf16="${VLLM_CPU_AMXBF16:-false}"
240
+LABEL ai.vllm.build.python-version="${PYTHON_VERSION:-3.12}"
241
+
242
ENTRYPOINT ["vllm", "serve"]
docs/getting_started/installation/cpu.x86.inc.md
+61
-6
@@ -164,21 +164,76 @@ uv pip install dist/*.whl
164
[https://gallery.ecr.aws/q9t5s3a7/vllm-cpu-release-repo](https://gallery.ecr.aws/q9t5s3a7/vllm-cpu-release-repo)
165
166
!!! warning
167
- If deploying the pre-built images on machines without `avx512f`, `avx512_bf16`, or `avx512_vnni` support, an `Illegal instruction` error may be raised. It is recommended to build images for these machines with the appropriate build arguments (e.g., `--build-arg VLLM_CPU_DISABLE_AVX512=true`, `--build-arg VLLM_CPU_AVX512BF16=false`, or `--build-arg VLLM_CPU_AVX512VNNI=false`) to disable unsupported features. Please note that without `avx512f`, AVX2 will be used and this version is not recommended because it only has basic feature support.
167
+ If deploying the pre-built images on machines without `avx512f`, `avx512_bf16`, or `avx512_vnni` support, an `Illegal instruction` error may be raised. See the build-image-from-source section below for build arguments to match your target CPU capabilities.
168
169
# --8<-- [end:pre-built-images]
170
# --8<-- [start:build-image-from-source]
171
172
+## Building for your target CPU
173
+
174
+vLLM supports building Docker images for x86 CPU platforms with automatic instruction set detection.
175
+
176
+### Basic build command
177
+
178
+```bash
179
+docker build -f docker/Dockerfile.cpu \
180
+ --build-arg VLLM_CPU_DISABLE_AVX512=<false (default)|true> \
181
+ --build-arg VLLM_CPU_AVX2=<false (default)|true> \
182
+ --build-arg VLLM_CPU_AVX512=<false (default)|true> \
183
+ --build-arg VLLM_CPU_AVX512BF16=<false (default)|true> \
184
+ --build-arg VLLM_CPU_AVX512VNNI=<false (default)|true> \
185
+ --build-arg VLLM_CPU_AMXBF16=<false|true (default)> \
186
+ --tag vllm-cpu-env \
187
+ --target vllm-openai .
188
+```
189
+
190
+!!! note "Instruction set auto-detection"
191
+ By default, vLLM will auto-detect CPU instruction sets (AVX512, AVX2, etc.) from the build system's CPU flags. Build arguments like `VLLM_CPU_AVX2`, `VLLM_CPU_AVX512`, `VLLM_CPU_AVX512BF16`, `VLLM_CPU_AVX512VNNI`, and `VLLM_CPU_AMXBF16` are primarily used for **cross-compilation** or for building container images on systems that don't have the target platforms ISA:
192
+
193
+ - Set `VLLM_CPU_{ISA}=true` to force-enable an instruction set (for cross-compilation to target platforms with that ISA)
194
+ - Set `VLLM_CPU_{ISA}=false` to rely on auto-detection
195
+ - When an ISA build arg is set to `true`, vLLM will build with that instruction set regardless of the build system's CPU capabilities
196
+
197
+### Build examples
198
+
199
+**Example 1: Auto-detection (native build)**
200
+
201
+Build on a machine with the same CPU as your target deployment:
202
+
203
```bash
204
+# Auto-detects all CPU features from the build system
205
docker build -f docker/Dockerfile.cpu \
174
- --build-arg VLLM_CPU_AVX512BF16=false (default)|true \
175
- --build-arg VLLM_CPU_AVX512VNNI=false (default)|true \
176
- --build-arg VLLM_CPU_AMXBF16=false|true (default) \
177
- --build-arg VLLM_CPU_DISABLE_AVX512=false (default)|true \
206
--tag vllm-cpu-env \
207
--target vllm-openai .
208
+```
209
+
210
+**Example 2: Cross-compilation for AVX512 deployment**
211
181
-# Launching OpenAI server
212
+Build an AVX512 image on any x86_64 system (even without AVX512):
213
+
214
+```bash
215
+docker build -f docker/Dockerfile.cpu \
216
+ --build-arg VLLM_CPU_AVX512=true \
217
+ --build-arg VLLM_CPU_AVX512BF16=true \
218
+ --build-arg VLLM_CPU_AVX512VNNI=true \
219
+ --tag vllm-cpu-avx512 \
220
+ --target vllm-openai .
221
+```
222
+
223
+**Example 3: Cross-compilation for AVX2 deployment**
224
+
225
+Build an AVX2 image for older CPUs:
226
+
227
+```bash
228
+docker build -f docker/Dockerfile.cpu \
229
+ --build-arg VLLM_CPU_AVX2=true \
230
+ --tag vllm-cpu-avx2 \
231
+ --target vllm-openai .
232
+```
233
+
234
+## Launching the OpenAI server
235
+
236
+```bash
237
docker run --rm \
238
--security-opt seccomp=unconfined \
239
--cap-add SYS_NICE \