概述

版本：0.1.0
适用平台：Linux
目标读者：熟悉 C++、Python 与模型推理流程的开发者

本手册提供 LACInfer C++ 与 Python 接口参考，适用于模型加载、编译、执行、量化和程序持久化。

LACInfer 简介

LACInfer（Loongson Accelerated Compute Inference Engine）是龙芯公司推出的一款加速计算推理引擎，该引擎面向模型推理场景，提供模型加载、量化、编译与执行能力。

LACInfer 支持 gpu 和 ref 两种编译目标：gpu 目标用于 GPU 加速推理，ref 目标提供参考实现（使用CPU运行）用于调试验证。LACInfer 可以加载并推理 ONNX 格式模型，也可以加载LIR格式模型（msgpack编码）进行推理。

API 使用流程

LACInfer 的典型调用顺序如下：

使用 parse_onnx或 load 接口得到程序。
如有需要，在编译前执行 INT8 量化。
使用 target（C++）或 get_target()（Python）选择 gpu、ref 目标进行编译。
构造输入参数并执行推理。
读取输出。

C++ 快速开始

公共 C++ 包装 API 位于：

#include <lacinfer/lacinfer.hpp>

下面的示例加载 ONNX 模型、为 GPU 编译并执行一次推理：

#include <lacinfer/lacinfer.hpp>

int main()
{
    auto program = lacinfer::parse_onnx("model.onnx");

    lacinfer::compile_options options;
    options.set_offload_copy();
    program.compile(lacinfer::target{"gpu"}, options);

    lacinfer::program_parameters params;
    auto input_shapes = program.get_parameter_shapes();
    for(auto&& name : input_shapes.names())
    {
        auto s = input_shapes[name];
        params.add(name, lacinfer::argument::generate(s));
    }

    auto outputs = program.eval(params);
    return outputs.empty() ? 1 : 0;
}

Python 快速开始

import lacinfer

program = lacinfer.parse_onnx("model.onnx")
program.compile(lacinfer.get_target("gpu"))

params = {
    name: lacinfer.generate_argument(shape)
    for name, shape in program.get_parameter_shapes().items()
}
outputs = program.run(params)

for output in outputs:
    print(output.get_shape(), output.tolist())

示例使用参数形状生成类型匹配的测试输入。传入实际数据时，输入对象必须实现 Python 缓冲区协议（Buffer Protocol）¹，且数据类型、维度和内存布局必须与程序参数形状匹配。

核心对象关系

对象	作用
`shape`	描述张量的数据类型、各维长度、步长或动态维度
`argument`	将 `shape` 与实际数据缓冲区关联
`operation` / `op`	描述一项操作及其属性
`instruction` / `instruction_ref`	模块中的一条指令
`module`	模块，保存指令构成的计算图
`program`	保存一个或多个模块，并负责编译和执行
`target`	指定编译与执行目标

目标名称

名称	用途
`gpu`	GPU 目标
`ref`	参考实现，适合功能验证

当前发布版本提供 gpu 和 ref 目标。传入其他目标名称会导致 API 报错。

静态形状与动态形状

静态形状的每个维度在解析或建图时已经确定。动态形状用最小值、最大值和可选的优化值描述维度范围。

动态形状相关的类型、构造、查询和解析选项在当前版本中均属于 [实验性] 功能。

C++：

lacinfer::dynamic_dimension batch{1, 8, lacinfer::optimals{1, 4, 8}};
lacinfer::dynamic_dimensions dims{batch,
                                   lacinfer::dynamic_dimension{3, 3},
                                   lacinfer::dynamic_dimension{224, 224},
                                   lacinfer::dynamic_dimension{224, 224}};
lacinfer::shape input_shape{lacinfer_shape_float_type, dims};

Python：

batch = lacinfer.shape.dynamic_dimension(1, 8, {1, 4, 8})
input_shape = lacinfer.shape(
    type="float_type",
    dyn_dims=[
        batch,
        lacinfer.shape.dynamic_dimension(3, 3),
        lacinfer.shape.dynamic_dimension(224, 224),
        lacinfer.shape.dynamic_dimension(224, 224),
    ],
)

内存与生命周期

C++ argument(shape, void*) 和 Python argument(buffer)/argument_from_pointer() 默认引用调用方提供的内存，不表示取得该内存的所有权。
在程序执行及输出消费完成前，调用方必须保证外部缓冲区仍然有效。
Python 应优先直接保存 NumPy 数组变量，避免只把临时数组传给零拷贝接口。
当 GPU 编译启用 offload_copy 时，编译器会插入主机与设备之间的必要复制。关闭该选项后，输入和输出的内存位置由调用方负责。
run_async 返回时工作可能尚未完成；复用或释放缓冲区之前必须在对应流上同步。

文档约定

C++ 声明默认位于 lacinfer 命名空间。
Python 声明默认位于 lacinfer 模块。
标有“修改程序”的量化和排序 API 会原地修改传入的 program。
标有“[实验性]”的内容尚未经过充分验证，属于试验阶段的方案；未来版本可能进一步完善，也可能移除。
示例中的文件名、输入名和张量尺寸需要替换为实际模型信息。

¹. Python 定义的标准对象协议，用于向 Python 或 C 扩展公开底层内存、元素格式、维度和步长等信息，以便直接访问数据而无须进行中间复制。 ↩

概述

概述