[RFC] Add staged Huawei Ascend NPU support to vLLM Recipes

[robellliu-dev]

Summary

This RFC proposes adding Huawei Ascend NPU support to vLLM Recipes in three
incremental phases:

1. Establish the minimal shared Ascend foundation, following the existing
   Google TPU integration pattern.
2. Add and validate Ascend configurations for selected open models.
3. Expose verified Ascend hardware on model pages and in hardware discovery
   with UX comparable to NVIDIA and AMD.

Each phase will be delivered through separate, reviewable pull requests. The
first PR will only introduce the shared foundation and will not claim that any
model recipe has been validated on Ascend.

Motivation

vLLM Ascend is the
community-maintained hardware plugin for running vLLM on Huawei Ascend NPUs.
Its installation documentation
provides deployment paths and container images for Atlas A2 and Atlas A3.

vLLM Recipes already models NVIDIA, AMD, Google TPU, and Intel hardware.
Ascend should use the same shared recipe vocabulary and opt-in validation
semantics, without introducing a separate recipe format or duplicating the
command builder.

Goals

• Represent Atlas A2 and Atlas A3 as restricted hardware profiles.
• Support an ascend Docker-image brand key.
• Generate the device mappings and host mounts required by official vLLM
  Ascend containers.
• Allow model recipes to opt in through meta.hardware.
• Eventually display verified Ascend support on recipe pages and in hardware
  discovery.
• Preserve the existing NVIDIA, AMD, Google TPU, and Intel behavior.

Non-goals

• Do not mark any model as verified in the foundation PR.
• Do not make Ascend a default hardware selection.
• Do not change existing hardware profiles or deployment behavior.
• Do not refactor unrelated command-builder or browsing code.
• Do not treat "supported by vLLM Ascend" as equivalent to an end-to-end
  verified recipe.
• Do not hard-code one release-candidate version as a permanent global default.

Phase 1: Minimal Ascend foundation

The first PR will follow the existing Google TPU layout and introduce only the
shared plumbing required by later recipe PRs.

Scope

1. Add restricted Atlas A2 and Atlas A3 hardware profiles to taxonomy.yaml.
   They use restricted: true, so they remain hidden unless a recipe explicitly
   lists them in meta.hardware.
2. Extend Docker metadata resolution with an ascend brand key.
3. Support recipe- or variant-level Ascend image overrides through the existing
   docker_image structure.
4. Generate the Ascend Docker device arguments documented by vLLM Ascend:
   /dev/davinci0 through the profile-specific device count, the shared Ascend
   devices, and the required DCMI, driver, and npu-smi mounts.
5. Distinguish Atlas A2 and A3 image selection where official images use
   different tags.
6. Make only the smallest install-block changes required to render the correct
   Ascend Docker command.

Out of scope

• No model YAML changes or verified Ascend declarations.
• No Browse-page hardware filter or search synonyms.
• No broad model-page UX changes.
• No changes to existing Google TPU, NVIDIA, AMD, or Intel entries.
• No file-wide reformatting or line-ending conversion.

The shared implementation provides the mechanism for selecting an Ascend
image. A tested model recipe should pin the exact image tag used during
validation because vLLM and vLLM Ascend versions must remain compatible and
release tags change over time.

Acceptance criteria

• Existing hardware definitions and generated commands remain unchanged.
• Ascend profiles are hidden unless explicitly enabled by a recipe.
• Docker metadata resolves the ascend brand for Ascend profiles.
• Atlas A2 and A3 generate the expected image and device mappings.
• node scripts/build-recipes-api.mjs succeeds.
• Focused Docker metadata regression tests succeed.
• git diff --check succeeds.
• The PR contains no unrelated formatting or line-ending changes.

Phase 2: Model recipe enablement

After the shared foundation is merged, add Ascend support model by model.
Start with one small dense model as an end-to-end smoke test. Larger dense,
multimodal, and MoE models should follow in separate PRs after validation.

Candidate model families include Qwen, DeepSeek, GLM, Kimi, and MiniMax,
subject to the vLLM Ascend support matrix and available hardware validation.

Each model PR should record:

• tested Atlas hardware profile;
• exact vLLM and vLLM Ascend versions;
• tested Docker image;
• precision and parallelism configuration;
• required environment variables and model-specific arguments;
• successful startup and inference smoke test;
• known limitations.

Only configurations tested end to end should use:

meta:
  hardware:
    <ascend-profile>: verified

Phase 3: Website visibility and discovery

Once verified Ascend recipes exist, expose Ascend with semantics consistent
with NVIDIA and AMD:

• show Ascend hardware pills on eligible model pages;
• show verified only for tested model/hardware combinations;
• add Ascend to hardware filters;
• add Huawei, Ascend, NPU, and Atlas model names as search terms;
• render Ascend-specific Docker install and launch commands;
• keep Ascend hidden for recipes that have not opted in.

This phase should reuse the existing hardware and verification UI instead of
creating an Ascend-specific page flow.

Compatibility and review constraints

Every PR in this RFC must:

• preserve all existing provider and hardware entries;
• add new behavior through existing abstractions;
• avoid unrelated refactors;
• keep generated output unchanged for non-Ascend hardware;
• contain only the files required by its phase;
• use signed-off commits as required by DCO.

Proposed naming

• Display brand: Huawei
• Configuration and Docker key: ascend
• Initial profiles: atlas_800i_a2 and atlas_800i_a3
• Foundation install path: Docker-first; exact versions are pinned by validated
  model recipes.