Merge branch 'main' into fix/dep

Author: peachest

Dockerfile

@@ -22,5 +22,6 @@ FROM $BASE_IMAGE
 ENV LD_LIBRARY_PATH=/usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64/driver:/usr/local/Ascend/driver/lib64/common
 COPY --from=build /build/ascend-device-plugin /usr/local/bin/ascend-device-plugin
 COPY --from=build /build/lib/hami-vnpu-core/* /usr/local/hami-vnpu-core-assets/
+RUN chmod +x /usr/local/hami-vnpu-core-assets/limiter
 
 ENTRYPOINT ["ascend-device-plugin"]

README.md

@@ -4,28 +4,23 @@
 
 ## Introduction
 
-This Ascend device plugin is implemented for [HAMi](https://github.com/Project-HAMi/HAMi) and [volcano](https://github.com/volcano-sh/volcano) scheduling.
+This Ascend device plugin is implemented for NPU-Slicing for [HAMi](https://github.com/Project-HAMi/HAMi) and [volcano](https://github.com/volcano-sh/volcano). It supports two modes:
 
 #### 1. Template-based Hard Slicing (vNPU)
 
-Memory slicing is supported based on virtualization template, lease available template is automatically used. For detailed information, check [template](./ascend-device-configmap.yaml)
+Memory slicing is supported based on virtualization template, least available template is automatically used. For detailed information, check [template](https://github.com/Project-HAMi/ascend-device-plugin/blob/main/ascend-device-configmap.yaml)
 
 #### 2. Soft Slicing with Runtime Interception (hami-vnpu-core)
 
 This project implements  a soft slicing mechanism based on `libvnpu.so` interception and `limiter` token scheduling, enabling fine-grained resource sharing.  For detailed information, check [hami-vnpu-core](https://github.com/Project-HAMi/hami-vnpu-core)
 
-**Note:** `hami-vnpu-core` currently only supports ARM platforms.
+**Note 1:** `hami-vnpu-core` currently only supports ARM platforms.
+**Note 2:** `hami-vnpu-core` currently only supports HAMi scheduler.
 
 ## Prerequisites
 
 [ascend-docker-runtime](https://gitcode.com/Ascend/mind-cluster/tree/master/component/ascend-docker-runtime)
 
-update submodule:
-
-```bash
-git submodule update --init --recursive
-```
-
 hami-vnpu-core Soft Slicing Requirements:
 
 - **Ascend Driver Version**: ≥ 25.5
@@ -45,14 +40,14 @@ Below is the English translation of the instructions for enabling `device-share`
 
 ## Compile
 
+update submodule:
+
 ```bash
-make all
+git submodule update --init --recursive
 ```
 
-### Build
-
 ```bash
-docker buildx build -t $IMAGE_NAME .
+make all
 ```
 
 ## Deployment
@@ -63,35 +58,39 @@ docker buildx build -t $IMAGE_NAME .
 kubectl label node {ascend-node} ascend=on
 ```
 
-### Deploy ConfigMap
+### Deply RuntimeClass
 
 ```bash
-kubectl apply -f ascend-device-configmap.yaml
+kubectl apply -f https://raw.githubusercontent.com/Project-HAMi/ascend-device-plugin/main/ascend-runtimeclass.yaml
 ```
 
-#### **Node Custom Configuration Description**
-The `hami-device-node-config` is used to enable hami-vnpu-core for specific nodes within the cluster.
-* By setting `hami-vnpu-core: true`, the specified node will enable soft-partitioning based on `hami-vnpu-core`.
-* Specify the number of virtual devices reported to Kubernetes for each physical chip via the `vDeviceCount` field.
-* Nodes without specific configurations will default to template-based hard-partitioning.
+### Deploy ConfigMap
+
+This configMap is used for global configurations, like resourceName, mode, templates.
+* Under `vnpus`, set `hamiVnpuCore: true` so **all nodes** advertise soft-partitioning based on `hami-vnpu-core` to the scheduler (unless overridden per node in `hami-device-node-config`).
 
 ```bash
-kubectl apply -f ascend-device-node-configmap.yaml
+kubectl apply -f https://raw.githubusercontent.com/Project-HAMi/ascend-device-plugin/main/ascend-device-configmap.yaml
 ```
 
-### Deply RuntimeClass
+**Note:** You can choose to ignore this step if this configMap already exists.
+
+
+#### (Optional) **Node Custom Configuration Description**
+
+The `hami-device-node-config` is used to enable or override hami-vnpu-core for specific nodes within the cluster. Node-level settings take higher priority than the global `vnpus.hamiVnpuCore` switch.
 
 ```bash
-kubectl apply -f ascend-runtimeclass.yaml
+kubectl apply -f https://raw.githubusercontent.com/Project-HAMi/ascend-device-plugin/main/ascend-device-node-configmap.yaml
 ```
 
 ### Deploy `ascend-device-plugin`
 
 ```bash
-kubectl apply -f ascend-device-plugin.yaml
+kubectl apply -f https://raw.githubusercontent.com/Project-HAMi/ascend-device-plugin/main/ascend-device-plugin.yaml
 ```
 
-If scheduling Ascend devices in HAMi, simply set `devices.ascend.enabled` to true when deploying HAMi, and the ConfigMap and `ascend-device-plugin` will be automatically deployed. refer https://github.com/Project-HAMi/HAMi/blob/master/charts/hami/README.md#huawei-ascend
+## Usage
 
 If you require HAMi to automatically add the `runtimeClassName` configuration to Pods requesting Ascend resources (this is disabled by default), you should set `devices.ascend.runtimeClassName` value to **a non-empty string** in HAMi’s `values.yaml` file, ensuring it matches the name of the `RuntimeClass` resource. For example:
 
@@ -101,14 +100,18 @@ devices:
     runtimeClassName: ascend
 ```
 
-## Usage
-
 To exclusively use an entire card or request multiple cards, you only need to set the corresponding resourceName. If multiple tasks need to share the same NPU, you need to set the corresponding resource request to 1 and configure the appropriate ResourceMemoryName.
 
 ### Usage in HAMi
 
+**How HAMi chooses soft vs legacy vNPU:** The device plugin applies **soft slicing** (`libvnpu` / `hami-vnpu-core` mounts and environment) **only** when the Pod sets `huawei.com/vnpu-mode: hami-core`. Pods **without** this annotation still follow the **original vNPU** path (virtualization templates and `ASCEND_VNPU_SPECS`). These two paths are different. If your cluster effectively has **only** soft-slicing–oriented Ascend capacity (for example every node is configured for `hami-vnpu-core` and workloads are expected to use soft slicing), Pods that **omit** `vnpu-mode=hami-core` may remain **Pending** because they still request the legacy vNPU allocation model, which may not match what those nodes expose or how the scheduler pairs Pods to nodes.
+
 ```yaml
 ...
+metadata:
+  name: ascend-soft-slice-pod
+  annotations:
+    huawei.com/vnpu-mode: 'hami-core' # Enables hami-vnpu-core soft-segmentation for this pod
     containers:
     - name: npu_pod
       ...
@@ -119,10 +122,12 @@ To exclusively use an entire card or request multiple cards, you only need to se
           huawei.com/Ascend910B-memory: "4096"
 ```
 
-For more examples, see [examples](./examples/)
+For more examples, see [examples](https://github.com/Project-HAMi/ascend-device-plugin/tree/main/examples)
 
 ### Soft Slicing Configuration (HAMi)
 
+Use the annotation below whenever you intend **soft** slicing; omitting it keeps **template-based vNPU** behavior (see the note under [Usage in HAMi](#usage-in-hami)).
+
 ```yaml
 apiVersion: v1
 kind: Pod

README_cn.md

@@ -2,46 +2,47 @@
 
 ## 说明
 
-Ascend device plugin 是用来支持在 [HAMi](https://github.com/Project-HAMi/HAMi) 和 [volcano](https://github.com/volcano-sh/volcano) 中调度昇腾NPU设备.
+Ascend device plugin 是用来支持在 [HAMi](https://github.com/Project-HAMi/HAMi) 和 [volcano](https://github.com/volcano-sh/volcano) 中调度昇腾 NPU 设备，支持以下两种模式：
 
-**基于模板的硬切分 (vNPU)** 
+#### 1. 基于模板的硬切分 (vNPU)
 
-支持基于虚拟化模板的显存切分，系统会自动使用最小可用模板。详细信息请参阅 [template](https://www.google.com/search?q=链接)。
+支持基于虚拟化模板的显存切分，系统会自动使用最小可用模板。详细信息请参阅 [template](https://github.com/Project-HAMi/ascend-device-plugin/blob/main/ascend-device-configmap.yaml)。
 
-**基于运行时拦截的软切分 (hami-vnpu-core)** 
+#### 2. 基于运行时拦截的软切分 (hami-vnpu-core)
 
-实现了基于 `libvnpu.so` 拦截和limiter令牌调度的软切分机制，能够实现精细化的资源共享。详细信息请参阅 [hami-vnpu-core](https://www.google.com/search?q=链接)。
+实现了基于 `libvnpu.so` 拦截和 limiter 令牌调度的软切分机制，能够实现精细化的资源共享。详细信息请参阅 [hami-vnpu-core](https://github.com/Project-HAMi/hami-vnpu-core)。
 
-**注意:** `hami-vnpu-core`目前只支持ARM平台。
+**注意 1：** `hami-vnpu-core` 目前只支持 ARM 平台。
+**注意 2：** `hami-vnpu-core` 目前只支持 HAMi 调度器。
 
 ## 环境要求
 
 部署 [ascend-docker-runtime](https://gitcode.com/Ascend/mind-cluster/tree/master/component/ascend-docker-runtime)
 
-更新子模块 
-
-```bash
-git submodule update --init --recursive
-```
-
 **hami-vnpu-core 软切分要求：**
 
 - Ascend 驱动版本：≥ 25.5
 - 芯片模式：在昇腾芯片上开启 `device-share` 模式以支持虚拟化。
 
-**开启 `device-share`模式**
+**开启 `device-share` 模式**
 
 **npu-smi set -t device-share -i** *id* **-d** *value*  用于设置指定设备的所有芯片的容器共享模式。
 
 **参数说明**
 
 | 类型    | 描述                                                        |
 | ------- | ----------------------------------------------------------- |
-| *id*    | 设备ID。通过**npu-smi info -l**命令查出的NPU ID即为设备ID。 |
-| *value* | 容器使能状态：分为禁用、使能。默认禁用。0：禁用1：使能      |
+| *id*    | 设备 ID。通过 **npu-smi info -l** 命令查出的 NPU ID 即为设备 ID。 |
+| *value* | 容器使能状态：分为禁用、使能。默认禁用。<br>0：禁用<br>1：使能 |
 
 ## 编译
 
+更新子模块：
+
+```bash
+git submodule update --init --recursive
+```
+
 ```bash
 make all
 ```
@@ -60,34 +61,40 @@ docker buildx build -t $IMAGE_NAME .
 kubectl label node {ascend-node} ascend=on
 ```
 
-### 部署 ConfigMap
+### 部署 RuntimeClass
 
 ```bash
-kubectl apply -f ascend-device-configmap.yaml
+kubectl apply -f https://raw.githubusercontent.com/Project-HAMi/ascend-device-plugin/main/ascend-runtimeclass.yaml
 ```
 
-#### 节点自定义配置说明
-hami-device-node-config 用于对集群中特定节点的显卡虚拟化策略进行精细化控制。
-通过设置 hami-vnpu-core: true，指定节点将启用基于 hami-vnpu-core 的软切分，通过 vDeviceCount 字段，手动定义每个物理芯片上报给 Kubernetes 的虚拟设备数量；否则走基于模板的硬切分。
+### 部署 ConfigMap
+
+该 ConfigMap 用于全局配置，包括 resourceName、模式、模板等。
+* 在 `vnpus` 下设置 `hamiVnpuCore: true`，**所有节点**会向调度器声明基于 `hami-vnpu-core` 的软切分能力（可被 `hami-device-node-config` 按节点覆盖）。
+
 ```bash
-kubectl apply -f ascend-device-node-configmap.yaml
+kubectl apply -f https://raw.githubusercontent.com/Project-HAMi/ascend-device-plugin/main/ascend-device-configmap.yaml
 ```
 
-### 部署 RuntimeClass
+**注意：** 如果该 ConfigMap 已存在，可跳过此步骤。
+
+#### （可选）节点自定义配置说明
+
+`hami-device-node-config` 用于对集群中特定节点的 hami-vnpu-core 进行启用或覆盖。节点级配置的优先级高于全局 `vnpus.hamiVnpuCore` 开关。
 
 ```bash
-kubectl apply -f ascend-runtimeclass.yaml
+kubectl apply -f https://raw.githubusercontent.com/Project-HAMi/ascend-device-plugin/main/ascend-device-node-configmap.yaml
 ```
 
 ### 部署 `ascend-device-plugin`
 
 ```bash
-kubectl apply -f ascend-device-plugin.yaml
+kubectl apply -f https://raw.githubusercontent.com/Project-HAMi/ascend-device-plugin/main/ascend-device-plugin.yaml
 ```
 
-如果要在HAMi中使用升腾NPU, 在部署HAMi时设置 `devices.ascend.enabled` 为 true 会自动部署 ConfigMap 和 `ascend-device-plugin`。 参考 <https://github.com/Project-HAMi/HAMi/blob/master/charts/hami/README.md#huawei-ascend>
+如果要在 HAMi 中使用昇腾 NPU，在部署 HAMi 时设置 `devices.ascend.enabled` 为 true 会自动部署 ConfigMap 和 `ascend-device-plugin`。参考 <https://github.com/Project-HAMi/HAMi/blob/master/charts/hami/README.md#huawei-ascend>
 
-如果需要 HAMi 为申请 ascend 资源的 Pod 自动添加 runtimeClassName 配置（默认关闭），则应该在 HAMi 的 values.yaml 文件中配置 `deivces.ascend.runtimeClassName` 为**一个非空字符串**，并且与 RuntimeClass 资源名称保持一致。 例如：
+如果需要 HAMi 为申请 ascend 资源的 Pod 自动添加 runtimeClassName 配置（默认关闭），则应该在 HAMi 的 values.yaml 文件中配置 `devices.ascend.runtimeClassName` 为**一个非空字符串**，并且与 RuntimeClass 资源名称保持一致。例如：
 
 ```yaml
 devices:
@@ -97,10 +104,12 @@ devices:
 
 ## 使用
 
-如果要独占整卡或者申请多张卡只需要设置对应的 resourceName 即可。如果多个任务要共享同一张卡，需要将 resourceName 设置为1，并且设置对应的 ResourceMemoryName。
+如果要独占整卡或者申请多张卡只需要设置对应的 resourceName 即可。如果多个任务要共享同一张卡，需要将 resourceName 设置为 1，并且设置对应的 ResourceMemoryName。
 
 ### 在 HAMi 中使用
 
+**HAMi 与 vNPU 模式说明：** 只有为 Pod 配置了注解 `huawei.com/vnpu-mode: hami-core` 时，设备插件才会按 **软切分**（`libvnpu` / `hami-vnpu-core` 的挂载与环境变量）处理。**未添加**该注解的任务仍走 **原有 vNPU** 方案（虚拟化模板与 `ASCEND_VNPU_SPECS` 等）。两种路径不同。当集群里 Ascend 节点 **只有** 面向软切分的部署或调度预期（例如节点均按 `hami-vnpu-core` 配置、工作负载预期都使用软切分）时，**未**设置 `vnpu-mode=hami-core` 的任务可能一直处于 **Pending**，因为其仍按旧版 vNPU 申请与分配逻辑，可能与当前节点暴露的资源或调度匹配方式不一致。
+
 ```yaml
 ...
     containers:
@@ -109,35 +118,35 @@ devices:
       resources:
         limits:
           huawei.com/Ascend910B: "1"
-          # 如果不指定显存大小, 就会使用整张卡
+          # 如果不指定显存大小，就会使用整张卡
           huawei.com/Ascend910B-memory: "4096"
 ```
 
- For more examples, see [examples](./examples/)
+更多示例请参阅 [examples](https://github.com/Project-HAMi/ascend-device-plugin/tree/main/examples)
 
-#### 软切分配置 (HAMi)
+### 软切分配置 (HAMi)
 
-YAML
+需要 **软切分** 时请显式加上下文中的注解；不加则仍为 **模板硬切分 vNPU**（与上一节「在 HAMi 中使用」中的说明一致）。
 
 ```yaml
 apiVersion: v1
 kind: Pod
 metadata:
   name: ascend-soft-slice-pod
   annotations:
-    huawei.com/vnpu-mode: 'hami-core' # 添加该注解的走hami-vnpu-core软切分
+    huawei.com/vnpu-mode: 'hami-core' # 添加该注解的走 hami-vnpu-core 软切分
 spec:
   containers:
     - name: npu_pod
       ...
       resources:
         limits:
-          huawei.com/Ascend910B3: "1"          # 请求 1 块物理 NPU
+          huawei.com/Ascend910B3: "1"           # 请求 1 块物理 NPU
           huawei.com/Ascend910B3-memory: "28672" # 请求 28Gi 显存
           huawei.com/Ascend910B3-core: "40"      # 请求 40% 的算力
 ```
 
-软切分机制支持在单个 Pod 中申请多个虚拟设备，比如在进行多卡并行推理（如使用 vLLM）时，--gpu-memory-utilization 的值不能大于“容器总显存上限”占“所选卡物理显存总和”的比例。
+软切分机制支持在单个 Pod 中申请多个虚拟设备。在进行多卡并行推理（如使用 vLLM）时，`--gpu-memory-utilization` 的值不能大于"容器总显存上限"占"所选卡物理显存总和"的比例。
 
 **示例：使用 vLLM 开启 2 卡张量并行 (TP=2)**
 
@@ -155,26 +164,26 @@ spec:
     - name: vllm-container
       image: vllm-ascend:latest
       command: ["/bin/sh", "-c"]
-      args: 
+      args:
         - |
           vllm serve /model/Qwen3-0.6B \
           --host 0.0.0.0 \
           --port 8002 \
           --enforce-eager \
           --tensor-parallel-size 2 \
-          --gpu-memory-utilization 0.5   # 关键参数：总申请显存 64G / 总物理显存 128G = 0.5
+          --gpu-memory-utilization 0.5   # 关键参数：总申请显存 64Gi / 总物理显存 128Gi = 0.5
       resources:
         limits:
           huawei.com/Ascend910B3: "2"           # 申请 2 块虚拟设备进行并行计算
-          huawei.com/Ascend910B3-memory: "65536" # 容器可用的总显存上限（2卡合计 64GiB）
-          huawei.com/Ascend910B3-core: "50"       
+          huawei.com/Ascend910B3-memory: "65536" # 容器可用的总显存上限（2 卡合计 64GiB）
+          huawei.com/Ascend910B3-core: "50"
 ```
 
 ### 在 volcano 中使用
 
- 在 volcano 中使用时需要提前部署好 volcano, 更多信息请[参考这里](https://github.com/volcano-sh/volcano/tree/master/docs/user-guide/how_to_use_vnpu.md)
+在 volcano 中使用时需要提前部署好 volcano，更多信息请[参考这里](https://github.com/volcano-sh/volcano/tree/master/docs/user-guide/how_to_use_vnpu.md)
 
- ```yaml
+```yaml
 apiVersion: v1
 kind: Pod
 metadata:
@@ -189,5 +198,5 @@ spec:
       resources:
         limits:
           huawei.com/Ascend310P: "1"
-           huawei.com/Ascend310P-memory: "4096"
- ```
+          huawei.com/Ascend310P-memory: "4096"
+```