.agents/skills/paddle-op-dev/references/python-api.md
Python API 是用户直接使用的接口(如 paddle.trace()),底层调用 C++ 算子。API 需要完成:参数检查与处理、调用底层 C++ 算子、编写规范的 docstring。
python/paddle/ 目录下的相应子目录trace 属于数学运算,放在 python/paddle/tensor/math.pydef xxx(input, param1, param2=default_value, name=None):
in_dynamic_or_pir_mode() 判断_C_ops.xxx(args...)LayerHelper,使用 helper.create_variable_for_type_inference() 和 helper.append_op()from paddle import _C_ops
# 动态图模式直接调用
if in_dynamic_or_pir_mode():
return _C_ops.op_name(args...)
# 静态图模式
helper = LayerHelper('op_name', **locals())
out = helper.create_variable_for_type_inference(dtype=input.dtype)
helper.append_op(
type='op_name',
inputs={'X': input},
outputs={'Out': out},
attrs={'attr1': value1}
)
return out
文件:python/paddle/tensor/math.py
def trace(x, offset=0, axis1=0, axis2=1, name=None):
"""
Computes the sum along diagonals of the input tensor x.
If ``x`` is 2D, returns the sum of diagonal.
If ``x`` has larger dimensions, then returns an tensor of diagonals sum, diagonals be taken from
the 2D planes specified by axis1 and axis2.
Args:
x (Tensor): The input tensor x. Must be at least 2-dimensional. The input data type should be
float32, float64, int32, int64.
offset (int, optional): Which diagonals in input tensor x will be taken. Default: 0 (main diagonals).
axis1 (int, optional): The first axis with respect to take diagonal. Default: 0.
axis2 (int, optional): The second axis with respect to take diagonal. Default: 1.
name (str, optional): Name for the operation. Default: None.
Returns:
Tensor: the output data type is the same as input data type.
Examples:
.. code-block:: python
>>> import paddle
>>> x = paddle.to_tensor([[1, 2, 3],
... [4, 5, 6],
... [7, 8, 9]])
>>> out = paddle.trace(x)
>>> print(out)
Tensor(shape=[], dtype=int64, place=Place(cpu), stop_gradient=True,
15)
"""
if in_dynamic_or_pir_mode():
return _C_ops.trace(x, offset, axis1, axis2)
else:
inputs = {'Input': [x]}
attrs = {'offset': offset, 'axis1': axis1, 'axis2': axis2}
helper = LayerHelper('trace', **locals())
out = helper.create_variable_for_type_inference(dtype=x.dtype)
helper.append_op(
type='trace',
inputs={'Input': x},
outputs={'Out': out},
attrs=attrs,
)
return out
API 实现后,需在 python/paddle/__init__.py 或对应模块的 __init__.py 中导出,使用户可以通过 paddle.xxx() 调用。
注意事项:
name 参数在所有 API 中均为可选,用于调试