4. TopsGraphBuilder 用户手册¶

4.1. 快速入门¶

TopsGraphBuilder 是燧原科技开放给用户的构图接口，能够将上层 AI 框架的计算图/算子转换为 TopsGraph Opset 对应的 Op。

概况来说，TopsGraphBuilder 是 TopsGraph 计算图优化和编译的 high-level IR 构图入口，通过提供 Builder, Op, Type, Attribute 四个模块完成构图过程，承接上层 AI 框架计算图模型/算子。目前已在 TopsInference, Pytorch, TensorFlow, PaddlePaddle 等众多框架中使用，我们期待更多的 TopsGraphBuilder 用户。

TopsGraphBuilder 支持 C++/Python 两种构图方式，主要需要的步骤为：

创建全局 builder 对象: auto builder = std::make_shared<builder::Builder>();
创建全局 hlir module 的输入 op: auto input = builder->CreateInput(builder::Type(shape, dtype));
依次调用 Op API，对接 AI 框架 Op，例如对接 abs: auto op = builder::Abs(input);
设置模型返回 Op: builder->SetOutput({op});

下面分别列举了 C++/Python 构图示例：

C++ 构图示例¶

#include "gcu/hlir/builder/hlir_builder.h"

// Step1: 创建全局 builder 对象
auto builder = std::make_shared<builder::Builder>();

// 开启 op 的 shape inference
builder->SetShapeInference(true);
// 默认构图阶段关闭 op 的 shape inference，
// 此时用户调用 Op API 时需主动设置返回 Op 的 type 或使用默认值，
// 最终交由 TopsGraph ShapeInferencePass 进行推导

auto shape = std::vector<int64_t>({3, 2});
auto dtype = builder::PrimitiveType::F32();
builder::Type type(shape, dtype);

// Step2: 创建 hlir module 的输入 op
auto arg0 = builder->CreateInput(type);
auto arg1 = builder->CreateInput(type);
auto arg2 = builder->CreateInput(type);

// Step3: 调用 Op API，对接 AI 框架 Op
auto op1 = builder::Mul(arg1, arg2);
auto op2 = builder::Add(arg0, op1);
auto ret = op2;
// 也可采用运算符重载接口，如下所示：
// auto ret = arg0 + arg1 * arg2;
builder->SetOutput({ret});

// 创建 foo 函数
builder->AddFunc("foo");
arg0 = builder->CreateInput(type, "foo");
arg1 = builder->CreateInput(type, "foo");
arg2 = builder->CreateInput(type, "foo");
ret = builder::Add(arg1, arg2);
ret = builder::Add(arg0, ret);
builder->SetOutput({ret}, "foo");

builder->Dump();

生成的 IR 如下所示：

module @hlir_module {
  func @foo(%arg0: tensor<3x2xf32>, %arg1: tensor<3x2xf32>, %arg2: tensor<3x2xf32>) -> tensor<3x2xf32> {
    %0 = "dtu_hlir.add"(%arg1, %arg2) : (tensor<3x2xf32>, tensor<3x2xf32>) -> tensor<3x2xf32>
    %1 = "dtu_hlir.add"(%arg0, %0) : (tensor<3x2xf32>, tensor<3x2xf32>) -> tensor<3x2xf32>
    "dtu_hlir.return"(%1) : (tensor<3x2xf32>) -> ()
  }
  func @main(%arg0: tensor<3x2xf32>, %arg1: tensor<3x2xf32>, %arg2: tensor<3x2xf32>) -> tensor<3x2xf32> {
    %0 = "dtu_hlir.mul"(%arg1, %arg2) : (tensor<3x2xf32>, tensor<3x2xf32>) -> tensor<3x2xf32>
    %1 = "dtu_hlir.add"(%arg0, %0) : (tensor<3x2xf32>, tensor<3x2xf32>) -> tensor<3x2xf32>
    return %1 : tensor<3x2xf32>
  }
}

Python 构图示例¶

import numpy as np
import topsgraph as tg
import topsgraph.builder as tgb

builder = tgb.GetBuilder()
type = tgb.Type([3,2], tgb.PrimitiveType.F32())
arg0 = builder.CreateInput(type)
arg1 = builder.CreateInput(type)
arg2 = builder.CreateInput(type)

add1 = tgb.add(arg0, arg1)
add2 = tgb.add(add1, arg2)
builder.SetOutput([add2])

builder.AddFunc("foo")
arg0 = builder.CreateInput(type, "foo")
arg1 = builder.CreateInput(type, "foo")
arg2 = builder.CreateInput(type, "foo")
add1 = tgb.add(arg0, arg1)
add2 = tgb.add(add1, arg2)
builder.SetOutput([add2], "foo")

builder.Dump()

生成的 IR 如下所示：

module @hlir_module attributes {dtu_hlir.module_id = 1 : i64} {
  func.func @foo(%arg0: tensor<3x2xf32>, %arg1: tensor<3x2xf32>, %arg2: tensor<3x2xf32>) -> tensor<3x2xf32> {
    %0 = "dtu_hlir.add"(%arg0, %arg1) {track_symbol = "131075"} : (tensor<3x2xf32>, tensor<3x2xf32>) -> tensor<3x2xf32>
    %1 = "dtu_hlir.add"(%0, %arg2) {track_symbol = "131076"} : (tensor<3x2xf32>, tensor<3x2xf32>) -> tensor<3x2xf32>
    "dtu_hlir.return"(%1) : (tensor<3x2xf32>) -> ()
  }
  func.func @main(%arg0: tensor<3x2xf32>, %arg1: tensor<3x2xf32>, %arg2: tensor<3x2xf32>) -> tensor<3x2xf32> {
    %0 = "dtu_hlir.add"(%arg0, %arg1) {track_symbol = "131073"} : (tensor<3x2xf32>, tensor<3x2xf32>) -> tensor<3x2xf32>
    %1 = "dtu_hlir.add"(%0, %arg2) {track_symbol = "131074"} : (tensor<3x2xf32>, tensor<3x2xf32>) -> tensor<3x2xf32>
    return %1 : tensor<3x2xf32>
  }
}

4.2. 用户使用说明¶

TopsGraphBuilder 简介¶

TopsGraphBuilder 主要包括四个模块：

Builder: 全局 Graph 管理模块，作为构图过程中全局唯一的句柄，管理构图过程中的上下文信息；
Op: 用于对接 AI 框架算子，对应有上百个 Op API 接口，用于建立 AI 框架算子和 TopsGraph opset 映射关系；
Type: 记录 Op 的 shape 和 dtype；
Attribute: 绑定到 HLIR IR 对应的 HLIR Module, func, Op 上，作用与 MLIR Attribute 一致。

Builder¶

Builder 是构图的全局句柄，对外提供以下功能：

开启或关闭调用 Op API 时，是否自动推导 shape, dtype；
创建函数，默认创建 main 函数，即创建 builder 对象之后，此时处于 main 函数作用范围，后续调用 Builder::CreateInput，以及 Op API 均是插入到 main 函数内；
创建某个函数的输入输出：CreateInput & SetOutput，即给某个函数设置输入 op，以及输出返回 op；
打印构图 IR，以及控制打印级别；
构图完成后，获取 hlir::Module，交由 TopsGraphCompiler 进行编译。

对应的 C++ API 接口如下：

void SetShapeInference(bool enable_flag);
void AddFunc(const char* name);
builder::Op CreateInput(const builder::Type& type, const char* func_name = "main");
void SetOutput(const std::vector<builder::Op>& outputs, const char* func_name = "main");
void Dump() const;
void Print(std::ostream& out, uint32_t flags = PrintingFlags::None) const;
std::shared_ptr<hlir::Module> GetModule();

Op¶

Op 是 Operator 的缩写，即算子，上层 AI 框架算子最终会转化为 HLIR Op。

TopsGraphBuilder 提供两种类型 Op：

meta op: 与 TopsGraph Opset 一一对应，语义参考 XLA；
client op: 贴近上层 AI 框架算法层 Op，采用 meta op 组合实现。

目前，TopsGraphBuilder 提供有 200 多个 Op API，已基本满足上层 AI 框架常用需求。Op 类还提供辅助接口，用于操作 HLIR Op，如下所示，详细 Op API 可参考《TopsGraph C++ API参考》和《TopsGraph Python API参考》。

std::shared_ptr<Builder> GetBuilder() const;
void SetAttribute(const char* name, const Attribute& value, const char* mode = "");
void SetAttribute(const char* name, const std::vector<Attribute>& value);
bool IsConstant() const;
bool IsDynamic() const;
Type GetType() const;

Type¶

Type 代表 Op 的类型，封装了 shape 和 data_type, 同时提供了一些 API 用于操作 shape 和 data_type。

Note

builder::kUnknownDim 或 -1 表示动态 shape, 例如：{-1, 3, 224, 224} 中 -1 表示未知的动态 dim;

builder::kUnknownRank 或 -2 表示未知 rank, 例如：{-2} 中 -2 表示该 shape 的 rank 未知;

Attribute¶

Attribute 代表编译期已知的属性信息，用在 module, op, function 上，对应 MLIR Attribute，主要包含布尔类型，整型，字符串类型，浮点类型，如下所示。

explicit Attribute(const char* value);
explicit Attribute(bool value);
explicit Attribute(int32_t value);
explicit Attribute(int64_t value);
explicit Attribute(float value);
explicit Attribute(double value);

示例如下：

#include "gcu/hlir/builder/hlir_builder.h"

auto builder = std::make_shared<builder::Builder>();
auto ptype = builder::PrimitiveType::S64();
std::vector<int64_t> shape = {3, 2};
builder::Type type(shape, ptype);
auto arg0 = builder->CreateInput(type);
auto arg1 = builder->CreateInput(type);
auto res = arg0 + arg1;
// set attributes of op
res.SetAttribute("op_name", builder::Attribute("sum"));
res.SetAttribute("op_type", builder::Attribute("Add"));
builder->SetOutput({res});
// construct an Array Attribute
std::vector<builder::Attribute> min_shape_dim;
std::vector<int64_t> min_shape_0 = {1, 2};
auto dtype_i64 = builder::PrimitiveType::S64();
auto attr_0 = builder::Attribute(builder::Type({2}, dtype_i64),
                                 min_shape_0.data());
min_shape_dim.push_back(attr_0);
std::vector<int64_t> min_shape_1 = {1, 2};
auto attr_1 = builder::Attribute(builder::Type({2}, dtype_i64),
                                 min_shape_1.data());
min_shape_dim.push_back(attr_1);
// set attributes of function
builder->SetFuncAttribute("main", "input_min_shape_dim", min_shape_dim);
// set attributes of module
builder->SetModuleAttribute("module_id", builder::Attribute(int32_t(20)));
builder->Dump();

生成的 IR 如下所示，包含了 op_name, op_type 属性:

module @hlir_module attributes {module_id = 20 : i32} {
  func @main(%arg0: tensor<3x2xi64>, %arg1: tensor<3x2xi64>) -> tensor<3x2xi64> attributes {input_min_shape_dim = [dense<[1, 2]> : tensor<2xi64>, dense<[1, 2]> : tensor<2xi64>]} {
    %0 = "dtu_hlir.add"(%arg0, %arg1) {op_name = "sum", op_type = "Add"} : (tensor<3x2xi64>, tensor<3x2xi64>) -> tensor<3x2xi64>
    return %0 : tensor<3x2xi64>
  }
}

4.3. 其他¶

如需要更为详尽的 API 参考信息，请参考《TopsGraphBuilder C++ API参考》和《TopsGraphBuilder Python API参考》。