4. TopsGraphBuilder 用户手册¶

4.1. 快速入门¶

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

概况来说，TopsGraphBuilder 是 TopsGraph 计算图优化和编译的 high-level IR 构图入口，通过提供 Builder, Op, Type 三个模块完成构图过程，承接上层 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,
// 用户调用 Op API 时需主动设置返回 Op 的 type,
// 或使用默认值，最终交由 TopsGraph ShapeInferencePass 进行推导.
builder->SetShapeInference(true);


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");
res = builder::Add(arg1, arg2);
res = builder::Add(arg0, res);
builder->SetOutput({res}, "foo");

builder->Dump();

The built IR is:

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 tops_graph as tg
from tops_graph import builder as tgb

tg.disable_dygraph()
builder = tgb.GetBuilder()
x = tgb.argument("main", tgb.Type([3, 4, 5], _tgb.PrimitiveType.F32()))
y = tgb.argument("main", tgb.Type([3, 4, 5], _tgb.PrimitiveType.F32()))
out = tgb.add(x, y)
print(builder.GetModuleStr())

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 可参考 TopsGraphBuilder C++ 文档：《TopsGraph C++ 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。

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);

4.3. 其他¶

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