Closed
[Documentation|文档反馈]: 顶层核心入口 @asc.jit 及 asc.runtime 模块未包含在 docs/python-api/ 参考手册与 Sphinx 索引中 #55
XePWangAdd on  Sep 12Closed at  Sep 30
XePWang
XePWang
Sep 12 Create

Thanks for sending an issue! Please fill in the following template to help quickly solve your problem.

Issues Section / 问题文档片段 (Mandatory / 必填)

  1. docs/python-api/index.md 索引目录(第 9-16 行):
# Python API

* [asc.language.adv](language/adv.md)
* [asc.language.basic](language/basic.md)
* [asc.language.core](language/core.md)
* [asc.language.fwk](language/fwk.md)
* [asc.lib.host](lib/host.md)
  1. docs/index.rst 目录树(第 12-20 行):
.. toctree::
   :maxdepth: 1

   python-api/rst/language/adv
   python-api/rst/language/basic
   python-api/rst/language/core
   python-api/rst/language/fwk
   python-api/rst/lib/host
  1. 实际顶层导出代码 python/asc/__init__.py(第 9-27 行):
from .codegen.function_visitor import CodegenOptions
from .runtime.compiler import CompileOptions
from .runtime.jit import jit
from .runtime.launcher import LaunchOptions
from .language import *
__all__ = ["CodegenOptions", "CompileOptions", "jit", "LaunchOptions"]

Existing Issues / 存在的问题 (Optional / 选填)

根据华为 CANN 官方《Ascend C 算子开发指南》(核函数定义章节),在原生 C++ 中核函数必须通过 extern "C" __global__ __aicore__ 关键字声明。而在 PyAsc 项目的编程模型中,@asc.jit 是将 Python 函数转译为 Ascend C 核函数、并调用毕昇编译器生成执行二进制文件的唯一核心入口修饰器。
同时,控制编译器优化级别与同步机制的 CompileOptions(如 kernel_type, opt_level, auto_sync, always_compile)以及控制硬件核数分配的 LaunchOptions,均在 python/asc/__init__.py 顶层直接导出。

然而在官方 API 手册 docs/python-api/index.md 及 Sphinx 根目录 docs/index.rst 中:

  1. 仅收录了针对核函数内部算子的 5 个子目录(adv、basic、core、fwk、host)。
  2. 完全缺失关于 asc.runtime 与核心装饰器 @asc.jit 的任何 API 参考条目。
    用户在查阅官方 API 手册时,能查到算子函数(如 add),却查不到定义算子入口的核心函数 @asc.jit 的签名与参数说明。

改进建议 / Suggested Improvement (Optional / 选填)

  1. 在 docs/python-api/ 下创建运行时模块文档目录(如 docs/python-api/runtime/),为 asc.jit、asc.runtime.compiler.CompileOptions、asc.runtime.launcher.LaunchOptions 等核心接口编写规范的 API 参数说明。
  2. 在 docs/python-api/index.md 与 docs/index.rst 中增加对 asc.runtime 及 asc.jit 的导航链接。
likedislike
神里绫华的狗神里绫华的狗Collaborators
Sep 12 Assign wuzhenqing as responsible person
kong0808Collaborators
Sep 12 Comments:

您好!感谢关注和问题反馈。
我们将在docs/python-api/index.md补齐runtime/jit.md、runtime/compiler.md等缺失的内容;在docs/index.rst补齐python-api/rst/runtime/jit、python-api/rst/runtime/compiler等缺失内容,完整修复后进行合入。

likedislike
神里绫华的狗神里绫华的狗Collaborators
Sep 12 Associated pull request
NUAA_wqyNUAA_wqy
Sep 28 Associated pull request
CANN-robotCANN-robotCollaborators
Sep 30 Close issue