Skip to content

fix(i18n): sync zh protocol documentation with english source (#542) #719

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ApurveKaranwal wants to merge 3 commits into
base: master
Choose a base branch
from
Open

fix(i18n): sync zh protocol documentation with english source (#542) #719

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
5bc8103
fix(i18n): sync zh protocol documentation with english source (#542)
ApurveKaranwal Aug 4, 2026
e21f73f
fix(i18n): address CodeRabbit review — complete MLU record, fix headi…
ApurveKaranwal Aug 5, 2026
cf4f378
fix(docs): correct grammar in EN v2.6.0 and v2.7.0 protocol snapshots
ApurveKaranwal Aug 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/developers/protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ An example is shown below:
```text
hami.io/node-handshake-nvidia: Reported 2024-01-23 04:30:04.434037031 +0000 UTC m=+1104711.777756895
hami.io/node-handshake-mlu: Requesting_2024.01.10 04:06:57
hami.io/node-mlu-register: MLU-45013011-2257-0000-0000-000000000000,10,23308,0,MLU-MLU370-X4,0,false:MLU-54043011-2257-0000-0000-000000000000,10,23308,0,
hami.io/node-mlu-register: MLU-45013011-2257-0000-0000-000000000000,10,23308,0,MLU-MLU370-X4,0,false:MLU-54043011-2257-0000-0000-000000000000,10,23308,0,MLU-MLU370-X4,0,false:
hami.io/node-nvidia-register: GPU-00552014-5c87-89ac-b1a6-7b53aa24b0ec,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:GPU-0fc3eda5-e98b-a25b-5b0d-cf5c855d1448,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:

```
Expand Down
38 changes: 21 additions & 17 deletions i18n/zh/docusaurus-plugin-content-docs/current/developers/protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,33 +5,37 @@ translated: true

## 设备注册

为了进行更准确的调度，HAMi 调度器需要在设备注册时感知设备的规格，包括 UUID、显存、计算能力、型号、numa 数量等。
<img src="/img/docs/common/developers/protocol/protocol-register.png" width="600px" alt="HAMi 设备注册协议图，显示节点注解过程" />

然而，device-plugin 设备注册 API 并未提供相应的参数获取，因此 HAMi-device-plugin 在注册时将这些补充信息存储在节点的注释中，以供调度器读取，如下图所示：
HAMi 需要了解集群中每个 AI 设备的规格信息以进行准确调度。在设备注册期间，device-plugin 需要每隔 30 秒将每个设备的规格持续更新（Patch）到节点注解（Node Annotation）中，格式如下：

<img src="/img/docs/common/developers/protocol/device-registration.png" width="600px" alt="HAMi 设备注册协议图，显示节点注解过程" />
```text
hami.io/node-handshake-\{device-type\}: Reported_\{device_node_current_timestamp\}
hami.io/node-\{device-type\}-register: \{Device 1\}:\{Device2\}:...:\{Device N\}
```

这里需要使用两个注释，其中一个是时间戳，如果超过指定的阈值，则认为对应节点上的设备无效。另一个是设备注册信息。一个具有 2 个 32G-V100 GPU 的节点可以注册如下所示：
每个设备的定义格式如下：

```yaml
hami.io/node-handshake: Requesting_2024.05.14 07:07:33
hami.io/node-nvidia-register: "GPU-00552014-5c87-89ac-b1a6-7b53aa24b0ec,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:GPU-0fc3eda5-e98b-a25b-5b0d-cf5c855d1448,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:"
```text
\{Device UUID\},\{device split count\},\{device memory limit\},\{device core limit\},\{device type\},\{device numa\},\{healthy\}
```

### 调度决策
示例如下：

kube-scheduler 在 `bind` 过程中调用 device-plugin 挂载设备，但仅向 device-plugin 提供设备的 `UUID`。因此，在设备共享的场景中，device-plugin 无法获取任务请求的相应设备规格，如 `设备显存` 和 `计算核心`。
```text
hami.io/node-handshake-nvidia: Reported 2024-01-23 04:30:04.434037031 +0000 UTC m=+1104711.777756895
hami.io/node-handshake-mlu: Requesting_2024.01.10 04:06:57
hami.io/node-mlu-register: MLU-45013011-2257-0000-0000-000000000000,10,23308,0,MLU-MLU370-X4,0,false:MLU-54043011-2257-0000-0000-000000000000,10,23308,0,MLU-MLU370-X4,0,false:
hami.io/node-nvidia-register: GPU-00552014-5c87-89ac-b1a6-7b53aa24b0ec,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:GPU-0fc3eda5-e98b-a25b-5b0d-cf5c855d1448,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:

因此，有必要开发一个协议，使调度器层与 device-plugin 进行通信以传递任务调度信息。调度器通过将调度结果补丁到 Pod 的注释中并在 device-plugin 中读取它来传递此信息，如下图所示：
```

<img src="/img/docs/common/developers/protocol/task-dispatch.png" width="600px" alt="HAMi 任务分发流程图" />
在此示例中，该节点包含两种不同的 AI 设备：2 张 NVIDIA-V100 GPU 和 2 张寒武纪 (Cambricon) 370-X4 MLU。

在此过程中，需要设置 3 个注释，分别是 `时间戳`、`待分配设备` 和 `已分配设备`。调度器创建时，`待分配设备` 和 `已分配设备` 的内容相同，但 device-plugin 将根据 `待分配设备` 的内容确定当前设备分配情况，当分配成功时，相应设备将从注释中移除，因此当任务成功运行时，`待分配设备` 的内容将为空。
设备节点可能因硬件或网络故障而变得不可用。如果节点在过去 5 分钟内未注册，调度器会将其标记为“不可用”（unavailable）。

一个请求 3000M 设备显存的 GPU 任务的示例将生成如下的相应注释：
由于调度器节点与“设备”节点上的系统时钟可能未准确对齐，调度器节点每 30 秒会 Patch 以下设备节点注解：

```yaml
hami.io/bind-time: 1716199325
hami.io/vgpu-devices-allocated: GPU-0fc3eda5-e98b-a25b-5b0d-cf5c855d1448,NVIDIA,3000,0:;
hami.io/vgpu-devices-to-allocate: ;
```text
hami.io/node-handshake-\{device-type\}: Requesting_{scheduler_node_current_timestamp}
```
38 changes: 21 additions & 17 deletions i18n/zh/docusaurus-plugin-content-docs/version-v2.6.0/developers/protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,33 +7,37 @@ translated: true

### 设备注册

为了进行更准确的调度，HAMi 调度器需要在设备注册时感知设备的规格，包括 UUID、显存、计算能力、型号、numa 数量等。
<img src="/img/docs/common/developers/protocol/protocol-register.png" width="600px" alt="HAMi 项目图" />

然而，device-plugin 设备注册 API 并未提供相应的参数获取，因此 HAMi-device-plugin 在注册时将这些补充信息存储在节点的注释中，以供调度器读取，如下图所示：
HAMi 需要了解集群中每个 AI 设备的规格信息以进行准确调度。在设备注册期间，device-plugin 需要每隔 30 秒将每个设备的规格持续更新（Patch）到节点注解（Node Annotation）中，格式如下：

<img src="/img/docs/common/developers/protocol/device-registration.png" width="600px" alt="HAMi 设备注册协议图，显示节点注解过程" />
```text
hami.io/node-handshake-\{device-type\}: Reported_\{device_node_current_timestamp\}
hami.io/node-\{device-type\}-register: \{Device 1\}:\{Device2\}:...:\{Device N\}
```

这里需要使用两个注释，其中一个是时间戳，如果超过指定的阈值，则认为对应节点上的设备无效。另一个是设备注册信息。一个具有 2 个 32G-V100 GPU 的节点可以注册如下所示：
每个设备的定义格式如下：

```yaml
hami.io/node-handshake: Requesting_2024.05.14 07:07:33
hami.io/node-nvidia-register: 'GPU-00552014-5c87-89ac-b1a6-7b53aa24b0ec,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:GPU-0fc3eda5-e98b-a25b-5b0d-cf5c855d1448,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:'
```text
\{Device UUID\},\{device split count\},\{device memory limit\},\{device core limit\},\{device type\},\{device numa\},\{healthy\}
```

### 调度决策
示例如下：

kube-scheduler 在 `bind` 过程中调用 device-plugin 挂载设备，但仅向 device-plugin 提供设备的 `UUID`。因此，在设备共享的场景中，device-plugin 无法获取任务请求的相应设备规格，如 `设备显存` 和 `计算核心`。
```text
hami.io/node-handshake-nvidia: Reported 2024-01-23 04:30:04.434037031 +0000 UTC m=+1104711.777756895
hami.io/node-handshake-mlu: Requesting_2024.01.10 04:06:57
hami.io/node-mlu-register: MLU-45013011-2257-0000-0000-000000000000,10,23308,0,MLU-MLU370-X4,0,false:MLU-54043011-2257-0000-0000-000000000000,10,23308,0,MLU-MLU370-X4,0,false:
hami.io/node-nvidia-register: GPU-00552014-5c87-89ac-b1a6-7b53aa24b0ec,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:GPU-0fc3eda5-e98b-a25b-5b0d-cf5c855d1448,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:

因此，有必要开发一个协议，使调度器层与 device-plugin 进行通信以传递任务调度信息。调度器通过将调度结果补丁到 Pod 的注释中并在 device-plugin 中读取它来传递此信息，如下图所示：
```

<img src="/img/docs/common/developers/protocol/task-dispatch.png" width="600px" alt="HAMi 任务分发流程图" />
在此示例中，该节点包含两种不同的 AI 设备：2 张 Nvidia-V100 GPU 和 2 张寒武纪 (Cambricon) 370-X4 MLU。

在此过程中，需要设置 3 个注释，分别是 `时间戳`、`待分配设备` 和 `已分配设备`。调度器创建时，`待分配设备` 和 `已分配设备` 的内容相同，但 device-plugin 将根据 `待分配设备` 的内容确定当前设备分配情况，当分配成功时，相应设备将从注释中移除，因此当任务成功运行时，`待分配设备` 的内容将为空。
设备节点可能因硬件或网络故障而变得不可用。如果节点在过去 5 分钟内未注册，调度器会将其标记为"不可用"（unavailable）。

一个请求 3000M 设备显存的 GPU 任务的示例将生成如下的相应注释：
由于调度器节点与"设备"节点上的系统时钟可能未准确对齐，调度器节点每 30 秒会 Patch 以下设备节点注解：

```yaml
hami.io/bind-time: 1716199325
hami.io/vgpu-devices-allocated: GPU-0fc3eda5-e98b-a25b-5b0d-cf5c855d1448,NVIDIA,3000,0:;
hami.io/vgpu-devices-to-allocate: ;
```text
hami.io/node-handshake-\{device-type\}: Requesting_{scheduler_node_current_timestamp}
```
Comment on lines +41 to 43

@coderabbitai coderabbitai Bot Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟠 Major | ⚡ Quick win

关闭三个版本文档中的最后一个代码围栏。

这些文件打开了最后一个 text 代码块，但没有显示关闭围栏。请在每个文件的 Line 41 添加 `````。

  • i18n/zh/docusaurus-plugin-content-docs/version-v2.6.0/developers/protocol.md#L39-L41: 添加关闭围栏。
  • i18n/zh/docusaurus-plugin-content-docs/version-v2.7.0/developers/protocol.md#L39-L41: 添加关闭围栏。
  • i18n/zh/docusaurus-plugin-content-docs/version-v2.8.0/developers/protocol.md#L39-L41: 添加关闭围栏。
📍 Affects 3 files
  • i18n/zh/docusaurus-plugin-content-docs/version-v2.6.0/developers/protocol.md#L39-L41 (this comment)
  • i18n/zh/docusaurus-plugin-content-docs/version-v2.7.0/developers/protocol.md#L39-L41
  • i18n/zh/docusaurus-plugin-content-docs/version-v2.8.0/developers/protocol.md#L39-L41
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@i18n/zh/docusaurus-plugin-content-docs/version-v2.6.0/developers/protocol.md`
around lines 39 - 41, Close the final text code fence by adding the missing
closing fence at the end of the protocol snippet in
i18n/zh/docusaurus-plugin-content-docs/version-v2.6.0/developers/protocol.md
lines 39-41,
i18n/zh/docusaurus-plugin-content-docs/version-v2.7.0/developers/protocol.md
lines 39-41, and
i18n/zh/docusaurus-plugin-content-docs/version-v2.8.0/developers/protocol.md
lines 39-41.

38 changes: 21 additions & 17 deletions i18n/zh/docusaurus-plugin-content-docs/version-v2.7.0/developers/protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,33 +7,37 @@ translated: true

### 设备注册

为了进行更准确的调度，HAMi 调度器需要在设备注册时感知设备的规格，包括 UUID、显存、计算能力、型号、numa 数量等。
<img src="/img/docs/common/developers/protocol/protocol-register.png" width="600px" alt="HAMi 项目图" />

然而，device-plugin 设备注册 API 并未提供相应的参数获取，因此 HAMi-device-plugin 在注册时将这些补充信息存储在节点的注释中，以供调度器读取，如下图所示：
HAMi 需要了解集群中每个 AI 设备的规格信息以进行准确调度。在设备注册期间，device-plugin 需要每隔 30 秒将每个设备的规格持续更新（Patch）到节点注解（Node Annotation）中，格式如下：

<img src="/img/docs/common/developers/protocol/device-registration.png" width="600px" alt="HAMi 设备注册协议图，显示节点注解过程" />
```text
hami.io/node-handshake-\{device-type\}: Reported_\{device_node_current_timestamp\}
hami.io/node-\{device-type\}-register: \{Device 1\}:\{Device2\}:...:\{Device N\}
```

这里需要使用两个注释，其中一个是时间戳，如果超过指定的阈值，则认为对应节点上的设备无效。另一个是设备注册信息。一个具有 2 个 32G-V100 GPU 的节点可以注册如下所示：
每个设备的定义格式如下：

```yaml
hami.io/node-handshake: Requesting_2024.05.14 07:07:33
hami.io/node-nvidia-register: 'GPU-00552014-5c87-89ac-b1a6-7b53aa24b0ec,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:GPU-0fc3eda5-e98b-a25b-5b0d-cf5c855d1448,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:'
```text
\{Device UUID\},\{device split count\},\{device memory limit\},\{device core limit\},\{device type\},\{device numa\},\{healthy\}
```

### 调度决策
示例如下：

kube-scheduler 在 `bind` 过程中调用 device-plugin 挂载设备，但仅向 device-plugin 提供设备的 `UUID`。因此，在设备共享的场景中，device-plugin 无法获取任务请求的相应设备规格，如 `设备显存` 和 `计算核心`。
```text
hami.io/node-handshake-nvidia: Reported 2024-01-23 04:30:04.434037031 +0000 UTC m=+1104711.777756895
hami.io/node-handshake-mlu: Requesting_2024.01.10 04:06:57
hami.io/node-mlu-register: MLU-45013011-2257-0000-0000-000000000000,10,23308,0,MLU-MLU370-X4,0,false:MLU-54043011-2257-0000-0000-000000000000,10,23308,0,MLU-MLU370-X4,0,false:
hami.io/node-nvidia-register: GPU-00552014-5c87-89ac-b1a6-7b53aa24b0ec,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:GPU-0fc3eda5-e98b-a25b-5b0d-cf5c855d1448,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:

因此，有必要开发一个协议，使调度器层与 device-plugin 进行通信以传递任务调度信息。调度器通过将调度结果补丁到 pod 的注释中并在 device-plugin 中读取它来传递此信息，如下图所示：
```

<img src="/img/docs/common/developers/protocol/task-dispatch.png" width="600px" alt="HAMi 任务分发流程图" />
在此示例中，该节点包含两种不同的 AI 设备：2 张 Nvidia-V100 GPU 和 2 张寒武纪 (Cambricon) 370-X4 MLU。

在此过程中，需要设置 3 个注释，分别是 `时间戳`、`待分配设备` 和 `已分配设备`。调度器创建时，`待分配设备` 和 `已分配设备` 的内容相同，但 device-plugin 将根据 `待分配设备` 的内容确定当前设备分配情况，当分配成功时，相应设备将从注释中移除，因此当任务成功运行时，`待分配设备` 的内容将为空。
设备节点可能因硬件或网络故障而变得不可用。如果节点在过去 5 分钟内未注册，调度器会将其标记为"不可用"（unavailable）。

一个请求 3000M 设备显存的 GPU 任务的示例将生成如下的相应注释：
由于调度器节点与"设备"节点上的系统时钟可能未准确对齐，调度器节点每 30 秒会 Patch 以下设备节点注解：

```yaml
hami.io/bind-time: 1716199325
hami.io/vgpu-devices-allocated: GPU-0fc3eda5-e98b-a25b-5b0d-cf5c855d1448,NVIDIA,3000,0:;
hami.io/vgpu-devices-to-allocate: ;
```text
hami.io/node-handshake-\{device-type\}: Requesting_{scheduler_node_current_timestamp}
```
38 changes: 21 additions & 17 deletions i18n/zh/docusaurus-plugin-content-docs/version-v2.8.0/developers/protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,33 +5,37 @@ translated: true

## 设备注册

为了进行更准确的调度，HAMi 调度器需要在设备注册时感知设备的规格，包括 UUID、显存、计算能力、型号、numa 数量等。
<img src="/img/docs/common/developers/protocol/protocol-register.png" width="600px" alt="HAMi 设备注册协议图，显示节点注解过程" />

然而，device-plugin 设备注册 API 并未提供相应的参数获取，因此 HAMi-device-plugin 在注册时将这些补充信息存储在节点的注释中，以供调度器读取，如下图所示：
HAMi 需要了解集群中每个 AI 设备的规格信息以进行准确调度。在设备注册期间，device-plugin 需要每隔 30 秒将每个设备的规格持续更新（Patch）到节点注解（Node Annotation）中，格式如下：

<img src="/img/docs/common/developers/protocol/device-registration.png" width="600px" alt="HAMi 设备注册协议图，显示节点注解过程" />
```text
hami.io/node-handshake-\{device-type\}: Reported_\{device_node_current_timestamp\}
hami.io/node-\{device-type\}-register: \{Device 1\}:\{Device2\}:...:\{Device N\}
```

这里需要使用两个注释，其中一个是时间戳，如果超过指定的阈值，则认为对应节点上的设备无效。另一个是设备注册信息。一个具有 2 个 32G-V100 GPU 的节点可以注册如下所示：
每个设备的定义格式如下：

```yaml
hami.io/node-handshake: Requesting_2024.05.14 07:07:33
hami.io/node-nvidia-register: 'GPU-00552014-5c87-89ac-b1a6-7b53aa24b0ec,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:GPU-0fc3eda5-e98b-a25b-5b0d-cf5c855d1448,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:'
```text
\{Device UUID\},\{device split count\},\{device memory limit\},\{device core limit\},\{device type\},\{device numa\},\{healthy\}
```

### 调度决策
示例如下：

kube-scheduler 在 `bind` 过程中调用 device-plugin 挂载设备，但仅向 device-plugin 提供设备的 `UUID`。因此，在设备共享的场景中，device-plugin 无法获取任务请求的相应设备规格，如 `设备显存` 和 `计算核心`。
```text
hami.io/node-handshake-nvidia: Reported 2024-01-23 04:30:04.434037031 +0000 UTC m=+1104711.777756895
hami.io/node-handshake-mlu: Requesting_2024.01.10 04:06:57
hami.io/node-mlu-register: MLU-45013011-2257-0000-0000-000000000000,10,23308,0,MLU-MLU370-X4,0,false:MLU-54043011-2257-0000-0000-000000000000,10,23308,0,MLU-MLU370-X4,0,false:
hami.io/node-nvidia-register: GPU-00552014-5c87-89ac-b1a6-7b53aa24b0ec,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:GPU-0fc3eda5-e98b-a25b-5b0d-cf5c855d1448,10,32768,100,NVIDIA-Tesla V100-PCIE-32GB,0,true:

因此，有必要开发一个协议，使调度器层与 device-plugin 进行通信以传递任务调度信息。调度器通过将调度结果补丁到 pod 的注释中并在 device-plugin 中读取它来传递此信息，如下图所示：
```

<img src="/img/docs/common/developers/protocol/task-dispatch.png" width="600px" alt="HAMi 任务分发流程图" />
在此示例中，该节点包含两种不同的 AI 设备：2 张 Nvidia-V100 GPU 和 2 张寒武纪 (Cambricon) 370-X4 MLU。

在此过程中，需要设置 3 个注释，分别是 `时间戳`、`待分配设备` 和 `已分配设备`。调度器创建时，`待分配设备` 和 `已分配设备` 的内容相同，但 device-plugin 将根据 `待分配设备` 的内容确定当前设备分配情况，当分配成功时，相应设备将从注释中移除，因此当任务成功运行时，`待分配设备` 的内容将为空。
设备节点可能因硬件或网络故障而变得不可用。如果节点在过去 5 分钟内未注册，调度器会将其标记为"不可用"（unavailable）。

一个请求 3000M 设备显存的 GPU 任务的示例将生成如下的相应注释：
由于调度器节点与"设备"节点上的系统时钟可能未准确对齐，调度器节点每 30 秒会 Patch 以下设备节点注解：

```yaml
hami.io/bind-time: 1716199325
hami.io/vgpu-devices-allocated: GPU-0fc3eda5-e98b-a25b-5b0d-cf5c855d1448,NVIDIA,3000,0:;
hami.io/vgpu-devices-to-allocate: ;
```text
hami.io/node-handshake-\{device-type\}: Requesting_{scheduler_node_current_timestamp}
```
Loading