From bb506a1c9989a9f99738cb2f2f5470e6e6327759 Mon Sep 17 00:00:00 2001
From: NJX <3771829673@qq.com>
Date: Sat, 14 Mar 2026 22:38:25 +0800
Subject: [PATCH] [Doc][Installation] Clarify SOC_VERSION for CPU-only source
 builds (#7278)

### What this PR does / why we need it?
- Clarify that `SOC_VERSION` must be set when building from source in a
CPU-only environment where `npu-smi` is unavailable.
- Add concrete `SOC_VERSION` examples (A2/A3/300I/A5) and point users to
`Dockerfile*` defaults.
- Improve the `setup.py` error message so users get actionable guidance
when `SOC_VERSION` is missing.

Fixes #6816.

### Does this PR introduce _any_ user-facing change?
- Yes. Documentation is updated and the build-time error message is more
informative.

### How was this patch tested?
- (Local) Syntax check: `python -m compileall setup.py`.

- vLLM version: v0.17.0
- vLLM main:
https://github.com/vllm-project/vllm/commit/4034c3d32e30d01639459edd3ab486f56993876d

Signed-off-by: NJX-njx <3771829673@qq.com>
---
 docs/source/faqs.md         | 20 ++++++++++++++++++++
 docs/source/installation.md |  7 +++++++
 setup.py                    |  7 ++++++-
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/docs/source/faqs.md b/docs/source/faqs.md
index cf4b77f5..46ef7bc1 100644
--- a/docs/source/faqs.md
+++ b/docs/source/faqs.md
@@ -270,3 +270,23 @@ bash tools/install_flash_infer_attention_score_ops_a2.sh
 
 **NOTE**: Don't set `additional_config.pa_shape_list` when using this method; otherwise, it will lead to another attention operator.
 **Important**: Please make sure you're using the **official image** of `vllm-ascend`; otherwise, you **must change** the directory `/vllm-workspace` in `tools/install_flash_infer_attention_score_ops_a2.sh` or `tools/install_flash_infer_attention_score_ops_a3.sh` to your own, or create one. If you're not the root user, you need `sudo` **privileges** to run this script.
+
+### 23. How to set `SOC_VERSION` when building from source on a CPU-only machine?
+
+When building from source (e.g. `pip install -e .`), the build may try to infer the target chip via `npu-smi`. If `npu-smi` is not available (common in CPU-only build environments), you must set `SOC_VERSION` manually before installation.
+
+You can use the defaults from `Dockerfile*` as a reference. For example:
+
+```bash
+# Atlas A2
+export SOC_VERSION="ascend910b1"
+
+# Atlas A3
+export SOC_VERSION="ascend910_9391"
+
+# Atlas 300I
+export SOC_VERSION="ascend310p1"
+
+# Atlas A5 (Ascend 950 series)
+export SOC_VERSION="<value starting with ascend950>"
+```
diff --git a/docs/source/installation.md b/docs/source/installation.md
index eb01cad2..9ab8888e 100644
--- a/docs/source/installation.md
+++ b/docs/source/installation.md
@@ -177,6 +177,13 @@ If you are building custom operators for Atlas A3, you should run `git submodule
 ```{note}
 To build custom operators, gcc/g++ higher than 8 and C++17 or higher are required. If you are using `pip install -e .` and encounter a torch-npu version conflict, please install with `pip install --no-build-isolation -e .` to build on system env.
 If you encounter other problems during compiling, it is probably because an unexpected compiler is being used, you may export `CXX_COMPILER` and `C_COMPILER` in the environment to specify your g++ and gcc locations before compiling.
+
+If you are building in a CPU-only environment where `npu-smi` is unavailable, you need to set `SOC_VERSION` before `pip install -e .` so the build can target the correct chip. You can refer to `Dockerfile*` defaults, for example:
+
+- Atlas A2: `export SOC_VERSION=ascend910b1`
+- Atlas A3: `export SOC_VERSION=ascend910_9391`
+- Atlas 300I: `export SOC_VERSION=ascend310p1`
+- Atlas A5: `export SOC_VERSION=<value starting with "ascend950">`
 ```
 
 ## Set up using Docker
diff --git a/setup.py b/setup.py
index 461f76ec..af175864 100644
--- a/setup.py
+++ b/setup.py
@@ -120,7 +120,12 @@ if not envs.SOC_VERSION:
         raise RuntimeError(
             "Could not determine chip type automatically via 'npu-smi'. "
             "This can happen in a CPU-only environment. "
-            "Please set the 'SOC_VERSION' environment variable to specify the target chip."
+            "Please set the 'SOC_VERSION' environment variable to specify the target chip, for example:\n"
+            '  - Atlas A2: export SOC_VERSION="ascend910b1"\n'
+            '  - Atlas A3: export SOC_VERSION="ascend910_9391"\n'
+            '  - Atlas 300I: export SOC_VERSION="ascend310p1"\n'
+            '  - Atlas A5: export SOC_VERSION="<value starting with ascend950>"\n'
+            "You can also refer to the SOC_VERSION defaults in Dockerfile*."
         )
     envs.SOC_VERSION = soc_version
 else: