ascendc-operator-doc-gen

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AscendC 算子接口文档生成

AscendC Operator Interface Documentation Generation

从算子源代码提取接口信息，生成 PyTorch 官方文档风格 的中文 API 接口文档。

前置条件：编译测试通过（Phase 3 完成），以下文件均已就绪：

```
csrc/register.cpp
```
— 包含
```
m.def
```
注册的 Python 调用 schema
```
csrc/ops.h
```
— 包含 C++ 函数声明
```
csrc/ops/<op_name>/design.md
```
— 包含算法描述、参数说明、dtype 支持、约束条件
```
csrc/ops/<op_name>/op_host/<op_name>.cpp
```
— 包含 TORCH_CHECK 约束和实际参数处理逻辑
```
tests/test_<op_name>.py
```
— 包含可运行的调用示例

Extract interface information from operator source code to generate PyTorch official documentation-style Chinese API interface documentation.

Prerequisites: Compilation and testing completed (Phase 3 finished), all the following files are ready:

```
csrc/register.cpp
```
— Contains Python call schema registered with
```
m.def
```
```
csrc/ops.h
```
— Contains C++ function declarations
```
csrc/ops/<op_name>/design.md
```
— Contains algorithm description, parameter explanation, dtype support, constraint conditions
```
csrc/ops/<op_name>/op_host/<op_name>.cpp
```
— Contains TORCH_CHECK constraints and actual parameter processing logic
```
tests/test_<op_name>.py
```
— Contains runnable call examples

工作流程

Workflow

信息提取 → 文档结构组装 → 文件生成 → 聊天界面展示

Information Extraction → Documentation Structure Assembly → File Generation → Display in Chat Interface

阶段 1: 信息提取

Phase 1: Information Extraction

从以下源文件中提取接口文档所需的全部信息。MUST 逐一读取这些文件，不可跳过。

Extract all information required for interface documentation from the following source files. MUST read these files one by one, no skipping allowed.

1.1 从

csrc/register.cpp

提取 Python 调用签名

1.1 Extract Python Call Signature from

csrc/register.cpp

找到

m.def("<op_name>(...)

行，提取完整的 schema 字符串。

提取内容：

函数名
参数列表（含类型和默认值）
返回类型

示例：

m.def("acosh(Tensor self) -> Tensor");

→ 签名:

torch.ops.npu.acosh(self) → Tensor

Schema 类型到 Python 类型映射：

Schema 类型	Python 文档类型	示例
`Tensor`	Tensor	必选张量参数
`Tensor?`	Tensor, optional	可选张量参数
`Tensor(a!)`	Tensor	原地修改张量
`int`	int	整数参数
`int?`	int, optional	可选整数参数
`int[]`	list[int]	整数列表
`int[3]`	list[int]	固定长度整数列表
`float`	float	浮点参数
`bool`	bool	布尔参数
`str?`	str, optional	可选字符串参数

Locate the line

m.def("<op_name>(...)

and extract the complete schema string.

Extracted Content:

Function name
Parameter list (including type and default value)
Return type

Example:

m.def("acosh(Tensor self) -> Tensor");

→ Signature:

torch.ops.npu.acosh(self) → Tensor

Schema Type to Python Type Mapping:

Schema Type	Python Documentation Type	Example
`Tensor`	Tensor	Mandatory tensor parameter
`Tensor?`	Tensor, optional	Optional tensor parameter
`Tensor(a!)`	Tensor	In-place modified tensor
`int`	int	Integer parameter
`int?`	int, optional	Optional integer parameter
`int[]`	list[int]	Integer list
`int[3]`	list[int]	Fixed-length integer list
`float`	float	Floating-point parameter
`bool`	bool	Boolean parameter
`str?`	str, optional	Optional string parameter

1.2 从

csrc/ops.h

提取 C++ 函数声明

1.2 Extract C++ Function Declaration from

csrc/ops.h

找到

namespace ascend_kernel

中对应函数的完整 C++ 签名。

提取内容：

返回类型（
```
at::Tensor
```
、
```
void
```
等）
参数类型和参数名
参数是否为 const 引用 / optional

Locate the complete C++ signature of the corresponding function in the

namespace ascend_kernel

Extracted Content:

Return type (e.g.,
```
at::Tensor
```
,
```
void
```
)
Parameter types and parameter names
Whether parameters are const references / optional

1.3 从

design.md

提取算法和设计信息

1.3 Extract Algorithm and Design Information from

design.md

提取内容：

提取项	设计文档章节	文档用途
算法描述 / 数学公式	计算逻辑设计	功能描述段落
参数语义说明	算子接口定义	参数说明段落
支持的数据类型	算子接口定义	支持的数据类型段落
输入输出 shape 约束	Tiling策略 / 算子接口定义	Shape 段落
有效输入范围 / 约束	注意事项 / 接口定义	约束条件段落

Extracted Content:

Extraction Item	Design Document Section	Documentation Usage
Algorithm description / mathematical formula	Computational logic design	Function description paragraph
Parameter semantic explanation	Operator interface definition	Parameter explanation paragraph
Supported data types	Operator interface definition	Supported data types paragraph
Input and output shape constraints	Tiling strategy / Operator interface definition	Shape paragraph
Valid input range / constraints	Notes / Interface definition	Constraint conditions paragraph

1.4 从

op_host/<op_name>.cpp

提取运行时约束

1.4 Extract Runtime Constraints from

op_host/<op_name>.cpp

搜索所有

TORCH_CHECK(...)

语句，提取：

TORCH_CHECK 内容	文档用途
维度检查（ `dim() == N` ）	Shape 约束
dtype 检查（ `scalar_type() == kHalf` ）	支持的数据类型
值域检查（数值范围限制）	约束条件
参数互斥/依赖关系	约束条件 / 参数说明

Search all

TORCH_CHECK(...)

statements and extract:

TORCH_CHECK Content	Documentation Usage
Dimension check ( `dim() == N` )	Shape constraint
dtype check ( `scalar_type() == kHalf` )	Supported data types
Value range check (numerical range limit)	Constraint conditions
Parameter mutual exclusion/dependency	Constraint conditions / Parameter explanation

1.5 从

tests/test_<op_name>.py

提取使用示例

1.5 Extract Usage Examples from

tests/test_<op_name>.py

找到最简洁且完整的调用示例（优先选

run_simple_test

或

test_basic

中的代码），提取：

输入 tensor 构造方式
算子调用语句（
```
torch.ops.npu.<op_name>(...)
```
）
输出处理方式

Locate the most concise and complete call example (prefer code from

run_simple_test

test_basic

) and extract:

Input tensor construction method
Operator call statement (
```
torch.ops.npu.<op_name>(...)
```
)
Output processing method

阶段 2: 文档结构组装

Phase 2: Documentation Structure Assembly

按以下 固定结构 组装文档内容。格式严格参考 PyTorch 官方文档（如

torch.nn.RMSNorm

、

torch.abs

），文档正文使用中文。

Assemble the documentation content according to the following fixed structure. Strictly follow the format of PyTorch official documentation (e.g.,

torch.nn.RMSNorm

torch.abs

), the main body of the documentation should be in Chinese.

文档模板

Documentation Template

markdown

undefined

markdown

undefined

torch.ops.npu.<op_name>

torch.ops.npu.<op_name>(<param1>, <param2>, ..., <paramN>) → <ReturnType>

<功能描述：1-3句中文说明算子做什么。如果有数学公式，用 LaTeX 行内公式展示。>

<如有数学公式，用独立公式块展示：>

$$ <公式> $$

torch.ops.npu.<op_name>(<param1>, <param2>, ..., <paramN>) → <ReturnType>

$$ <Formula> $$

参数说明

Parameter Explanation

<param1> (<type>) – <中文描述>
<param2> (<type>) – <中文描述>
<param3> (<type>, optional) – <中文描述>。默认值:
```
<默认值>
```

<param1> (<type>) – <Chinese description>
<param2> (<type>) – <Chinese description>
<param3> (<type>, optional) – <Chinese description>. Default value:
```
<default value>
```

支持的数据类型

Supported Data Types

torch.float16

torch.bfloat16

torch.float32

torch.float16

torch.bfloat16

torch.float32

Shape

输入: <shape描述，使用数学符号如 (N, *), (S, N, D) 等>
输出: <shape描述>

<如有额外 shape 规则，以列表形式补充>

Input: <Shape description, use mathematical symbols such as (N, *), (S, N, D), etc.>
Output: <Shape description>

约束条件

Constraint Conditions

<约束条件1>
<约束条件2>

<Constraint condition 1>
<Constraint condition 2>

使用示例

Usage Examples

python

>>> import torch
>>> import torch_npu
>>> import ascend_kernel
>>> <构造输入>
>>> <调用算子>
>>> <展示输出>

python

>>> import torch
>>> import torch_npu
>>> import ascend_kernel
>>> <Construct input>
>>> <Call operator>
>>> <Display output>

返回值

Return Value

<返回类型> – <中文返回值描述>

undefined

<Return type> – <Chinese description of return value>

undefined

各段落详细规范

Detailed Specifications for Each Paragraph

标题签名

Title Signature

格式：

torch.ops.npu.<op_name>(<参数列表>) → <返回类型>

参数列表从
```
register.cpp
```
的 schema 提取，仅保留参数名（不带类型）
有默认值的参数写为
```
<name>=<default>
```
返回类型：
```
Tensor
```
、
```
tuple[Tensor, ...]
```
、
```
None
```
（对应 C++
```
void
```
）

Format:

torch.ops.npu.<op_name>(<parameter list>) → <return type>

Parameter list is extracted from the schema in
```
register.cpp
```
, only parameter names are retained (without types)
Parameters with default values are written as
```
<name>=<default>
```
Return type:
```
Tensor
```
,
```
tuple[Tensor, ...]
```
,
```
None
```
(corresponding to C++
```
void
```
)

功能描述

Function Description

使用中文撰写
第一句话概括算子功能
如有数学公式，用 LaTeX 展示
如有多种工作模式（由参数控制），分别说明

Written in Chinese
The first sentence summarizes the operator's function
If there are mathematical formulas, display them using LaTeX
If there are multiple working modes (controlled by parameters), explain them separately

参数说明

Parameter Explanation

每个参数一行，格式：

- **<name>** (*<type>*) – <中文描述>

可选参数标注

optional

：

- **<name>** (*<type>, optional*) – <中文描述>。默认值: \

<value>``

参数描述应包含：语义说明、shape 要求（如适用）、有效值范围（如适用）
Tensor 参数说明 shape 格式，如 "形状:
```
(S, N, D)
```
"
布尔/枚举参数说明各取值的含义

One parameter per line, format:

- **<name>** (*<type>*) – <Chinese description>

Optional parameters are marked with

optional

- **<name>** (*<type>, optional*) – <Chinese description>. Default value: \

<value>``

Parameter description should include: semantic explanation, shape requirements (if applicable), valid value range (if applicable)
Tensor parameters should explain the shape format, e.g., "Shape:
```
(S, N, D)
```
"
Explain the meaning of each value for boolean/enumeration parameters

支持的数据类型

Supported Data Types

列出算子支持的所有 PyTorch dtype

格式：

`torch.float16`, `torch.bfloat16`, `torch.float32`

从 op_host 的 TORCH_CHECK 和 design.md 交叉验证

List all PyTorch dtypes supported by the operator

Format:

`torch.float16`, `torch.bfloat16`, `torch.float32`

Cross-verify from op_host TORCH_CHECK and design.md

Shape

使用中文标签（输入、输出）
描述输入输出 tensor 的 shape 语义
使用大写字母表示各维度含义，如
```
(N, C, H, W)
```
— N: 批大小, C: 通道数, ...
如果 shape 随参数变化，分情况说明

Use Chinese labels (Input, Output)
Describe the shape semantics of input and output tensors
Use uppercase letters to represent the meaning of each dimension, e.g.,
```
(N, C, H, W)
```
— N: batch size, C: channel count, ...
If the shape changes with parameters, explain separately

约束条件

Constraint Conditions

使用中文撰写
列出所有 TORCH_CHECK 中检查的约束条件
列出 design.md 中提到的有效输入范围
如果存在参数之间的互斥/依赖关系，明确说明

Written in Chinese
List all constraint conditions checked in TORCH_CHECK
List the valid input ranges mentioned in design.md
If there are mutual exclusion/dependency relationships between parameters, explain clearly

使用示例

Usage Examples

提供可直接在 NPU 上运行的完整代码片段
包含
```
import
```
语句
使用
```
>>>
```
前缀（doctest 风格）
输入数据使用小尺寸（便于展示）
展示至少 1 个典型用例
如果有多种使用模式，各展示 1 个

Provide complete code snippets that can be directly run on NPU
Include
```
import
```
statements
Use
```
>>>
```
prefix (doctest style)
Use small-size input data (for easy display)
Show at least 1 typical use case
If there are multiple usage modes, show 1 for each

返回值

Return Value

使用中文描述
格式：
```
*<type>* – <中文描述>
```
说明返回 tensor 的 shape 和 dtype（如与输入一致则注明"与输入 dtype 一致"）
如返回多个值（tuple），逐一说明

Described in Chinese
Format:
```
*<type>* – <Chinese description>
```
Explain the shape and dtype of the returned tensor (note "consistent with input dtype" if it matches the input)
If multiple values are returned (tuple), explain each one

阶段 3: 文件生成

Phase 3: File Generation

将组装好的文档写入：

ascend-kernel/csrc/ops/<op_name>/README.md

文件写入规则：

如果 README.md 已存在，覆盖旧内容
使用 UTF-8 编码
数学公式使用标准 LaTeX 语法（
```
$...$
```
行内，
```
$$...$$
```
块级）

Write the assembled documentation to:

ascend-kernel/csrc/ops/<op_name>/README.md

File Writing Rules:

If README.md already exists, overwrite the old content
Use UTF-8 encoding
Use standard LaTeX syntax for mathematical formulas (
```
$...$
```
for inline,
```
$$...$$
```
for block-level)

阶段 4: 在交互界面展示文档（MANDATORY）

Phase 4: Display Documentation in Interactive Interface (MANDATORY)

文件生成后，MUST 将完整的 README.md 内容直接输出到聊天界面中。

展示格式：

undefined

After file generation, MUST directly output the complete content of README.md to the chat interface.

Display Format:

undefined

接口文档已生成

Interface Documentation Generated

文件路径:

ascend-kernel/csrc/ops/<op_name>/README.md

<完整 README.md 内容>


**要求**：
1. 展示完整文档内容，不要截断
2. 展示文件路径供用户查看
3. 如果某个段落因信息不足无法填写，用 `[TODO: ...]` 标注并提醒用户补充

---

File Path:

ascend-kernel/csrc/ops/<op_name>/README.md

<Complete README.md content> ```

Requirements:

Display the complete documentation content without truncation
Display the file path for users to check
If a paragraph cannot be filled due to insufficient information, mark it with
```
[TODO: ...]
```
and remind the user to supplement it

完整示例

Complete Example

以下是一个假设的

acosh

算子的接口文档示例，展示最终生成效果：

说明：此示例仅用于展示文档格式，实际生成时所有信息均从源代码提取。

markdown

undefined

The following is a hypothetical interface documentation example for the

acosh

operator, showing the final generated effect:

Note: This example is only used to demonstrate the documentation format. All information is extracted from source code during actual generation.

markdown

undefined

torch.ops.npu.acosh

torch.ops.npu.acosh(self) → Tensor

逐元素计算输入张量的反双曲余弦值。

$$ \text{out}_i = \cosh^{-1}(\text{input}_i) = \ln(\text{input}_i + \sqrt{\text{input}_i^2 - 1}) $$

torch.ops.npu.acosh(self) → Tensor

Calculate the inverse hyperbolic cosine value of each element in the input tensor.

$$ \text{out}_i = \cosh^{-1}(\text{input}_i) = \ln(\text{input}_i + \sqrt{\text{input}_i^2 - 1}) $$

参数说明

Parameter Explanation

self (Tensor) – 输入张量，元素值必须 $\geq 1$。支持任意形状。

self (Tensor) – Input tensor, element values must be $\geq 1$. Supports any shape.

支持的数据类型

Supported Data Types

torch.float16

torch.float32

torch.float16

torch.float32

Shape

输入: $(*)$，支持任意形状
输出: $(*)$，与输入形状相同

Input: $(*)$, supports any shape
Output: $(*)$, same shape as input

约束条件

Constraint Conditions

仅支持
```
float16
```
和
```
float32
```
数据类型
输入张量的所有元素必须 $\geq 1$，否则结果为
```
NaN
```

Only supports
```
float16
```
and
```
float32
```
data types
All elements of the input tensor must be $\geq 1$, otherwise the result is
```
NaN
```

使用示例

Usage Examples

python

>>> import torch
>>> import torch_npu
>>> import ascend_kernel
>>> x = torch.tensor([1.0, 2.0, 3.0, 10.0], dtype=torch.float32, device="npu:0")
>>> output = torch.ops.npu.acosh(x)
>>> output
tensor([0.0000, 1.3170, 1.7627, 2.9932], device='npu:0')

python

>>> import torch
>>> import torch_npu
>>> import ascend_kernel
>>> x = torch.tensor([1.0, 2.0, 3.0, 10.0], dtype=torch.float32, device="npu:0")
>>> output = torch.ops.npu.acosh(x)
>>> output
tensor([0.0000, 1.3170, 1.7627, 2.9932], device='npu:0')

返回值

Return Value

Tensor – 反双曲余弦计算结果，形状与输入相同，dtype 与输入一致。

---

Tensor – Result of inverse hyperbolic cosine calculation, same shape as input, consistent dtype with input.

---

检查清单

Checklist

文档生成后按以下清单逐项验证：

签名一致性:
```
torch.ops.npu.<op_name>(...)
```
的参数列表与
```
register.cpp
```
的
```
m.def
```
完全一致
参数完整性: 每个参数都有类型标注和中文语义描述
默认值正确: 有默认值的参数在签名和参数说明中都标注了默认值
dtype 准确: 支持的数据类型与 op_host TORCH_CHECK 和 design.md 一致
Shape 清晰: 输入输出 shape 描述使用了有语义的维度符号
约束完整: 所有 TORCH_CHECK 的检查条件都已体现
示例可运行: 使用示例中的代码是从 test 文件中提炼的可执行代码
返回值明确: 返回类型、shape、dtype 都已说明
中文表述: 功能描述、参数说明、约束条件、返回值均使用中文
文件已生成: README.md 已写入
```
csrc/ops/<op_name>/README.md
```
已在聊天界面展示完整文档内容

After documentation generation, verify item by item according to the following checklist:

Signature Consistency: The parameter list of
```
torch.ops.npu.<op_name>(...)
```
is completely consistent with the
```
m.def
```
in
```
register.cpp
```
Parameter Completeness: Each parameter has a type annotation and Chinese semantic description
Correct Default Values: Parameters with default values are marked with default values in both the signature and parameter explanation
Accurate dtype: Supported data types are consistent with op_host TORCH_CHECK and design.md
Clear Shape: Input and output shape descriptions use dimension symbols with semantics
Complete Constraints: All check conditions of TORCH_CHECK are reflected
Runnable Examples: The code in usage examples is executable code extracted from test files
Clear Return Value: Return type, shape, and dtype are all explained
Chinese Expression: Function description, parameter explanation, constraint conditions, and return value are all in Chinese
File Generated: README.md has been written to
```
csrc/ops/<op_name>/README.md
```
Complete Documentation Content Displayed in Chat Interface

反模式清单

Anti-Pattern Checklist

NEVER 编造参数或 dtype 信息，所有信息必须从源代码提取
NEVER 跳过 TORCH_CHECK 约束的提取
NEVER 使用与 register.cpp schema 不一致的参数名或类型
NEVER 省略使用示例段落
NEVER 仅输出文件路径而不在聊天界面展示完整文档内容
NEVER 修改算子源代码，本 skill 是只读文档生成
NEVER 使用英文撰写文档正文（标题签名、代码、数学公式除外）

NEVER fabricate parameter or dtype information, all information must be extracted from source code
NEVER skip extracting TORCH_CHECK constraints
NEVER use parameter names or types inconsistent with the register.cpp schema
NEVER omit the usage examples paragraph
NEVER only output the file path without displaying the complete documentation content in the chat interface
NEVER modify operator source code, this skill is for read-only documentation generation
NEVER write the main body of the documentation in English (except title signature, code, and mathematical formulas)

可读取文件范围

Readable File Scope

文件	读取内容
`csrc/register.cpp`	Python 调用 schema（ `m.def` ）
`csrc/ops.h`	C++ 函数声明
`csrc/ops/<op_name>/design.md`	算法描述、参数说明、dtype、约束
`csrc/ops/<op_name>/op_host/<op_name>.cpp`	TORCH_CHECK 约束、参数处理逻辑
`tests/test_<op_name>.py`	使用示例

File	Read Content
`csrc/register.cpp`	Python call schema ( `m.def` )
`csrc/ops.h`	C++ function declarations
`csrc/ops/<op_name>/design.md`	Algorithm description, parameter explanation, dtype, constraints
`csrc/ops/<op_name>/op_host/<op_name>.cpp`	TORCH_CHECK constraints, parameter processing logic
`tests/test_<op_name>.py`	Usage examples