[XPU] add paddle.device.xpu.*** doc (#7363)

cqulilujia · web-flow · commit db2b9e352dc6 · 2025-08-05T10:08:23.000+08:00
diff --git a/docs/api/paddle/device/Overview_cn.rst b/docs/api/paddle/device/Overview_cn.rst
@@ -11,9 +11,10 @@ paddle.device
 -  :ref:`Stream 与 Event 辅助类 <cn_device_stream_event>`
 -  :ref:`Stream 与 Event 相关 API <cn_device_stream_event_api>`
 
-paddle.device 目录下包含 cuda 目录， cuda 目录中存放 CUDA 相关的 API。具体如下：
+paddle.device 目录下包含 cuda 目录和 xpu 目录， cuda 目录中存放 CUDA 相关的 API， xpu 目录中存放 XPU 相关的 API。具体如下：
 
 -  :ref:`CUDA 相关 <cn_device_cuda>`
+-  :ref:`XPU 相关 <cn_device_xpu>`
 
 .. _cn_device_setting:
 
@@ -114,3 +115,26 @@ CUDA 相关
     " :ref:`reset_max_memory_reserved <cn_api_paddle_device_cuda_reset_max_memory_reserved>` ", "重置给定设备上由 Allocator 管理的显存峰值统计"
     " :ref:`stream_guard <cn_api_paddle_device_cuda_stream_guard>` ", "切换当前的 CUDA stream 为输入指定的 stream，该 API 目前仅支持动态图模式"
     " :ref:`synchronize <cn_api_paddle_device_cuda_synchronize>` ", "等待给定的 CUDA 设备上的计算完成"
+
+
+.. _cn_device_xpu:
+
+XPU 相关
+::::::::::::::::::::
+
+.. csv-table::
+    :header: "API 名称", "API 功能"
+    :widths: 10, 30
+
+    " :ref:`device_count <cn_api_paddle_device_xpu_device_count>` ", "返回值是 int，表示当前程序可用的 XPU 数量"
+    " :ref:`empty_cache <cn_api_paddle_device_xpu_empty_cache>` ", "用于释放显存分配器中空闲的显存"
+    " :ref:`max_memory_allocated <cn_api_paddle_device_xpu_max_memory_allocated>` ", "返回给定设备上分配给 Tensor 的显存峰值统计"
+    " :ref:`max_memory_reserved <cn_api_paddle_device_xpu_max_memory_reserved>` ", "返回给定设备上由 Allocator 管理的显存峰值统计"
+    " :ref:`memory_allocated <cn_api_paddle_device_xpu_memory_allocated>` ", "返回给定设备上当前分配给 Tensor 的显存大小"
+    " :ref:`memory_reserved <cn_api_paddle_device_xpu_memory_reserved>` ", "返回给定设备上当前由 Allocator 管理的显存大小"
+    " :ref:`memory_used <cn_api_paddle_device_xpu_memory_used>` ", "返回给定设备上 XPU 运行时已使用的显存大小"
+    " :ref:`memory_total <cn_api_paddle_device_xpu_memory_total>` ", "返回给定设备上 XPU 的总显存大小"
+    " :ref:`reset_max_memory_allocated <cn_api_paddle_device_xpu_reset_max_memory_allocated>` ", "重置给定设备上分配给 Tensor 的显存峰值统计"
+    " :ref:`reset_max_memory_reserved <cn_api_paddle_device_xpu_reset_max_memory_reserved>` ", "重置给定设备上由 Allocator 管理的显存峰值统计"
+    " :ref:`set_debug_level <cn_api_paddle_device_xpu_set_debug_level>` ", "设置 XPU API DEBUG 功能的等级，打印算子的调用信息"
+    " :ref:`synchronize <cn_api_paddle_device_xpu_synchronize>` ", "等待给定的 XPU 设备上的计算完成"
diff --git a/docs/api/paddle/device/cuda/get_device_properties_cn.rst b/docs/api/paddle/device/cuda/get_device_properties_cn.rst
@@ -10,7 +10,7 @@ get_device_properties
 参数
 ::::::::
 
-**device** (paddle.CUDAPlace or int or str) - 设备、设备 ID 和类似于 ``gpu:x`` 的设备名称。如果 ``device`` 为空，则 ``device`` 为当前的设备。默认值为 None。
+    - **device** (paddle.CUDAPlace or int or str) - 设备、设备 ID 和类似于 ``gpu:x`` 的设备名称。如果 ``device`` 为空，则 ``device`` 为当前的设备。默认值为 None。
 
 
 返回
diff --git a/docs/api/paddle/device/cuda/max_memory_allocated_cn.rst b/docs/api/paddle/device/cuda/max_memory_allocated_cn.rst
@@ -13,7 +13,7 @@ max_memory_allocated
 参数
 ::::::::
 
-**device** (paddle.CUDAPlace|int|str，可选) - 设备、设备 ID 或形如 ``gpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+    - **device** (paddle.CUDAPlace|int|str，可选) - 设备、设备 ID 或形如 ``gpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
 
 
 返回
diff --git a/docs/api/paddle/device/cuda/max_memory_reserved_cn.rst b/docs/api/paddle/device/cuda/max_memory_reserved_cn.rst
@@ -10,7 +10,7 @@ max_memory_reserved
 参数
 ::::::::
 
-**device** (paddle.CUDAPlace|int|str，可选) - 设备、设备 ID 或形如 ``gpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+    - **device** (paddle.CUDAPlace|int|str，可选) - 设备、设备 ID 或形如 ``gpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
 
 
 返回
diff --git a/docs/api/paddle/device/cuda/memory_allocated_cn.rst b/docs/api/paddle/device/cuda/memory_allocated_cn.rst
@@ -13,7 +13,7 @@ memory_allocated
 参数
 ::::::::
 
-**device** (paddle.CUDAPlace|int|str，可选) - 设备、设备 ID 或形如 ``gpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+    - **device** (paddle.CUDAPlace|int|str，可选) - 设备、设备 ID 或形如 ``gpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
 
 
 返回
diff --git a/docs/api/paddle/device/cuda/memory_reserved_cn.rst b/docs/api/paddle/device/cuda/memory_reserved_cn.rst
@@ -10,7 +10,7 @@ memory_reserved
 参数
 ::::::::
 
-**device** (paddle.CUDAPlace|int|str，可选) - 设备、设备 ID 或形如 ``gpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+    - **device** (paddle.CUDAPlace|int|str，可选) - 设备、设备 ID 或形如 ``gpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
 
 
 返回
diff --git a/docs/api/paddle/device/cuda/reset_max_memory_allocated_cn.rst b/docs/api/paddle/device/cuda/reset_max_memory_allocated_cn.rst
@@ -10,7 +10,7 @@ reset_max_memory_allocated
 参数
 ::::::::
 
-**device** (paddle.CUDAPlace|int|str，可选) - 设备、设备 ID 或形如 ``gpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+    - **device** (paddle.CUDAPlace|int|str，可选) - 设备、设备 ID 或形如 ``gpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
 
 
 返回
diff --git a/docs/api/paddle/device/cuda/reset_max_memory_reserved_cn.rst b/docs/api/paddle/device/cuda/reset_max_memory_reserved_cn.rst
@@ -10,7 +10,7 @@ reset_max_memory_reserved
 参数
 ::::::::
 
-**device** (paddle.CUDAPlace|int|str，可选) - 设备、设备 ID 或形如 ``gpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+    - **device** (paddle.CUDAPlace|int|str，可选) - 设备、设备 ID 或形如 ``gpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
 
 
 返回
diff --git a/docs/api/paddle/device/xpu/device_count_cn.rst b/docs/api/paddle/device/xpu/device_count_cn.rst
@@ -0,0 +1,18 @@
+.. _cn_api_paddle_device_xpu_device_count:
+
+device_count
+-------------------------------
+
+.. py:function:: paddle.device.xpu.device_count()
+
+返回值是 int，表示当前程序可用的 XPU 数量。
+
+返回
+::::::::::::
+返回一个整数，表示当前程序可用的 XPU 数量。
+
+
+代码示例
+::::::::::::
+
+COPY-FROM: paddle.device.xpu.device_count
diff --git a/docs/api/paddle/device/xpu/empty_cache_cn.rst b/docs/api/paddle/device/xpu/empty_cache_cn.rst
@@ -0,0 +1,13 @@
+.. _cn_api_paddle_device_xpu_empty_cache:
+
+empty_cache
+-------------------------------
+
+.. py:function:: paddle.device.xpu.empty_cache()
+
+
+该函数用于释放显存分配器中空闲的显存，这样其他的 XPU 应用程序就可以使用释放出来的显存，并在 ``xpu-smi`` 中可见。大多数情况下您不需要使用该函数，当您删除 XPU 上的 Tensor 时，Paddle 框架并不会将显存释放，而是将显存保留起来，以便在下一次申明显存时可以更快的完成分配。
+
+代码示例
+:::::::::
+COPY-FROM: paddle.device.xpu.empty_cache
diff --git a/docs/api/paddle/device/xpu/max_memory_allocated_cn.rst b/docs/api/paddle/device/xpu/max_memory_allocated_cn.rst
@@ -0,0 +1,27 @@
+.. _cn_api_paddle_device_xpu_max_memory_allocated:
+
+max_memory_allocated
+-------------------------------
+
+.. py:function:: paddle.device.xpu.max_memory_allocated(device=None)
+
+返回给定设备上分配给 Tensor 的显存峰值统计。
+
+.. note::
+    Paddle 中分配给 Tensor 的显存块大小会进行 256 字节对齐，因此可能大于 Tensor 实际需要的显存大小。例如，一个 shape 为[1]的 float32 类型 Tensor 会占用 256 字节的显存，即使存储一个 float32 类型数据实际只需要 4 字节。
+
+参数
+::::::::
+
+    - **device** (paddle.XPUPlace|int|str，可选) - 设备、设备 ID 或形如 ``xpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+
+
+返回
+::::::::
+
+一个整数，表示给定设备上分配给 Tensor 的显存峰值统计，以字节为单位。
+
+代码示例
+::::::::
+
+COPY-FROM: paddle.device.xpu.max_memory_allocated
diff --git a/docs/api/paddle/device/xpu/max_memory_reserved_cn.rst b/docs/api/paddle/device/xpu/max_memory_reserved_cn.rst
@@ -0,0 +1,24 @@
+.. _cn_api_paddle_device_xpu_max_memory_reserved:
+
+max_memory_reserved
+-------------------------------
+
+.. py:function:: paddle.device.xpu.max_memory_reserved(device=None)
+
+返回给定设备上由 Allocator 管理的显存峰值统计。
+
+参数
+::::::::
+
+    - **device** (paddle.XPUPlace|int|str，可选) - 设备、设备 ID 或形如 ``xpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+
+
+返回
+::::::::
+
+一个整数，表示给定设备上当前由 Allocator 管理的显存峰值统计，以字节为单位。
+
+代码示例
+::::::::
+
+COPY-FROM: paddle.device.xpu.max_memory_reserved
diff --git a/docs/api/paddle/device/xpu/memory_allocated_cn.rst b/docs/api/paddle/device/xpu/memory_allocated_cn.rst
@@ -0,0 +1,27 @@
+.. _cn_api_paddle_device_xpu_memory_allocated:
+
+memory_allocated
+-------------------------------
+
+.. py:function:: paddle.device.xpu.memory_allocated(device=None)
+
+返回给定设备上当前分配给 Tensor 的显存大小。
+
+.. note::
+    Paddle 中分配给 Tensor 的显存块大小会进行 256 字节对齐，因此可能大于 Tensor 实际需要的显存大小。例如，一个 shape 为[1]的 float32 类型 Tensor 会占用 256 字节的显存，即使存储一个 float32 类型数据实际只需要 4 字节。
+
+参数
+::::::::
+
+    - **device** (paddle.XPUPlace|int|str，可选) - 设备、设备 ID 或形如 ``xpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+
+
+返回
+::::::::
+
+一个整数，表示给定设备上当前分配给 Tensor 的显存大小，以字节为单位。
+
+代码示例
+::::::::
+
+COPY-FROM: paddle.device.xpu.memory_allocated
diff --git a/docs/api/paddle/device/xpu/memory_reserved_cn.rst b/docs/api/paddle/device/xpu/memory_reserved_cn.rst
@@ -0,0 +1,24 @@
+.. _cn_api_paddle_device_xpu_memory_reserved:
+
+memory_reserved
+-------------------------------
+
+.. py:function:: paddle.device.xpu.memory_reserved(device=None)
+
+返回给定设备上当前由 Allocator 管理的显存大小。
+
+参数
+::::::::
+
+    - **device** (paddle.XPUPlace|int|str，可选) - 设备、设备 ID 或形如 ``xpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+
+
+返回
+::::::::
+
+一个整数，表示给定设备上当前由 Allocator 管理的显存大小，以字节为单位。
+
+代码示例
+::::::::
+
+COPY-FROM: paddle.device.xpu.memory_reserved
diff --git a/docs/api/paddle/device/xpu/memory_total_cn.rst b/docs/api/paddle/device/xpu/memory_total_cn.rst
@@ -0,0 +1,24 @@
+.. _cn_api_paddle_device_xpu_memory_total:
+
+memory_total
+-------------------------------
+
+.. py:function:: paddle.device.xpu.memory_total(device=None)
+
+返回给定设备上 XPU 的总显存大小。
+
+参数
+::::::::
+
+    - **device** (paddle.XPUPlace|int|str，可选) - 设备、设备 ID 或形如 ``xpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+
+
+返回
+::::::::
+
+一个整数，表示指定设备上 XPU 的总显存大小，以字节为单位。
+
+代码示例
+::::::::
+
+COPY-FROM: paddle.device.xpu.memory_total
diff --git a/docs/api/paddle/device/xpu/memory_used_cn.rst b/docs/api/paddle/device/xpu/memory_used_cn.rst
@@ -0,0 +1,27 @@
+.. _cn_api_paddle_device_xpu_memory_used:
+
+memory_used
+-------------------------------
+
+.. py:function:: paddle.device.xpu.memory_used(device=None)
+
+返回给定设备上 XPU 运行时已使用的显存大小。
+
+.. note::
+    这个 API 返回的显存使用量由 XPU RUNTIME 管理，因此可能比 Paddle 管理的显存使用量更大。
+
+参数
+::::::::
+
+    - **device** (paddle.XPUPlace|int|str，可选) - 设备、设备 ID 或形如 ``xpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+
+
+返回
+::::::::
+
+一个整数，表示指定设备上 XPU 运行时已使用的显存量，以字节为单位。
+
+代码示例
+::::::::
+
+COPY-FROM: paddle.device.xpu.memory_used
diff --git a/docs/api/paddle/device/xpu/reset_max_memory_allocated_cn.rst b/docs/api/paddle/device/xpu/reset_max_memory_allocated_cn.rst
@@ -0,0 +1,24 @@
+.. _cn_api_paddle_device_xpu_reset_max_memory_allocated:
+
+reset_max_memory_allocated
+-------------------------------
+
+.. py:function:: paddle.device.xpu.reset_max_memory_allocated(device=None)
+
+重置给定设备上分配给 Tensor 的显存峰值统计。
+
+参数
+::::::::
+
+    - **device** (paddle.XPUPlace|int|str，可选) - 设备、设备 ID 或形如 ``xpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+
+
+返回
+::::::::
+
+None
+
+代码示例
+::::::::
+
+COPY-FROM: paddle.device.xpu.reset_max_memory_allocated
diff --git a/docs/api/paddle/device/xpu/reset_max_memory_reserved_cn.rst b/docs/api/paddle/device/xpu/reset_max_memory_reserved_cn.rst
@@ -0,0 +1,24 @@
+.. _cn_api_paddle_device_xpu_reset_max_memory_reserved:
+
+reset_max_memory_reserved
+-------------------------------
+
+.. py:function:: paddle.device.xpu.reset_max_memory_reserved(device=None)
+
+重置给定设备上由 Allocator 管理的显存峰值统计。
+
+参数
+::::::::
+
+    - **device** (paddle.XPUPlace|int|str，可选) - 设备、设备 ID 或形如 ``xpu:x`` 的设备名称。如果 ``device`` 为 None，则 ``device`` 为当前的设备。默认值为 None。
+
+
+返回
+::::::::
+
+None
+
+代码示例
+::::::::
+
+COPY-FROM: paddle.device.xpu.reset_max_memory_reserved
diff --git a/docs/api/paddle/device/xpu/set_debug_level_cn.rst b/docs/api/paddle/device/xpu/set_debug_level_cn.rst
@@ -0,0 +1,24 @@
+.. _cn_api_paddle_device_xpu_set_debug_level:
+
+set_debug_level
+-------------------------------
+
+.. py:function:: paddle.device.xpu.set_debug_level(level=0)
+
+设置 XPU API DEBUG 功能的等级，打印算子调用信息。默认等级为 0，表示不打印任何调试信息。
+
+参数
+::::::::
+
+    - **level** (int) -  Debug 等级。0x1 ( trace )，打印算子调用信息。0x10 ( checksum )，打印张量校验和。0x100 ( dump )，将张量保存为 npy 格式的文件。0x1000 ( profiling )，记录每个算子的执行时间。
+
+
+返回
+::::::::
+
+None
+
+代码示例
+::::::::
+
+COPY-FROM: paddle.device.xpu.set_debug_level
diff --git a/docs/api/paddle/device/xpu/synchronize_cn.rst b/docs/api/paddle/device/xpu/synchronize_cn.rst
@@ -0,0 +1,22 @@
+.. _cn_api_paddle_device_xpu_synchronize:
+
+synchronize
+-------------------------------
+
+.. py:function:: paddle.device.xpu.synchronize(device=None)
+
+等待给定的 XPU 设备上的计算完成。
+
+
+参数
+::::::::::::
+
+    - **device** (paddle.XPUPlace()|int，可选) - 设备或者设备 ID。如果为 None，则为当前的设备。默认值为 None。
+
+返回
+::::::::::::
+None
+
+代码示例
+::::::::::::
+COPY-FROM: paddle.device.xpu.synchronize
