Stransformers 算法库¶

REVISION HISTORY¶

Revision No.	Description	Date
1.0	First version	01/06/2026
1.1	新增abort和callback功能，支持多角色输入	04/23/2026
1.2	新增设置function tools 功能	10/06/2026
1.3	新增cache_user_prefix功能，多模态前缀KV复用	07/24/2026
---

1. 概述¶

1.1. Stransformers功能介绍¶

Stransformers运行库是适配SGS Offline模型的推理运行库，其核心功能为：加载由IPU Toolchain转换得到的SGS Offline模型，在端侧通过调用IPU硬件实现推理加速。针对SGS Offline模型的推理过程，用户可自主设置推理参数，配置差异化的文本生成方式，并实时获得模型的推理结果。

1.2. 配置文件说明 ¶

运行库依赖以下配置文件实现模型初始化和推理控制，各文件功能如下:

配置文件	说明
tokenizer.json	存储词表映射关系、分词规则、字符编码格式等核心参数
tokenizer_config.json	存储chat模板、tokenizer class类型
generation_config.json	文本生成推理参数配置
ipu.json	IPU硬件、模型路径配置
vocab.json	存储基础词表映射
merges.txt	存储BPE分词合并规则

其中，tokenizer.json、tokenizer_config.json、generation_config.json、vocab.json、config.json、merges.txt为从Hugging Face官网下载的模型相关文件，详情请参考Hugging Face官方文档；ipu.json跟sgs ipu硬件平台相关，具体参数如下（实际使用参数需根据模型转换结果配置，未使用到的参数需删除）：

参数	描述
ipu_model_class	模型名称，比如"qwen3"
cos	预生成好的cos_weight.npy路径
sin	预生成好的sin_weight.npy路径
local_cos	预先生成的local_cos_weight.npy路径
local_sin	预先生成的local_sin_weight.npy路径
head_model	head模型路径
vision_model	视觉模型路径
encoder_model	语言编码模型路径
decoder_model	语言解码模型路径
embedding_model	embedding_weight文件路径
embedding_position	embedding_position文件路径

2. API参考¶

运行库提供以下API:

API名称	功能
ALGO_STS_Init	模型初始化
ALGO_STS_GetInputAttr	模型输入属性获取
ALGO_STS_CallBack	设置debug的回调函数
ALGO_STS_SetParams	多模态模型参数配置
ALGO_STS_Generate	模型推理
ALGO_STS_LoadPromptCache	加载提示词文件
ALGO_STS_SetFunctionTools	设置function tools
ALGO_STS_Abort	中途退出推理
ALGO_STS_ClearKVCache	历史上下文清除
ALGO_STS_Deinit	释放模型资源

2.1. ALGO_STS_Init¶

功能

创建句柄，初始化模型。
语法

MI_S32 ALGO_STS_Init(STSHandle* handle, STSInit_t init);
形参

参数名称描述输入/输出

handle 句柄输入

init 大模型配置文件路径、硬件资源参数输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
相关结构体

STSInit_t、IpuConfig_t
依赖
- 头文件：sgs_sts_api.h、sgs_algo_datatype.h
- 库文件：libsgsalgo_stransformers.a / libsgsalgo_stransformers.so

2.2. ALGO_STS_GetInputAttr¶

功能

获取模型输入属性（分辨率、数据类型：1->NV12，7->ARGB888）

语法

MI_S32 ALGO_STS_GetInputAttr(STSHandle handle, ModelConfig_t- model_attr);

形参

参数名称描述输入/输出

handle 句柄输入

model_attr 保存属性信息指针输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
相关结构体

ModelConfig_t
依赖
- 头文件：sgs_sts_api.h、sgs_algo_datatype.h
- 库文件：libsgsalgo_stransformers.a / libsgsalgo_stransformers.so

2.3. ALGO_STS_CallBack¶

功能

用于设置debug的回调函数

语法

MI_S32 ALGO_STS_CallBack(STSHandle handle, STSCallBack callback);

形参

参数名称描述输入/输出

handle 句柄输入

STSCallBack 回调函数结构体输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
相关结构体

STSCallBack
依赖
- 头文件：sgs_sts_api.h、sgs_algo_datatype.h
- 库文件：libsgsalgo_stransformers.a / libsgsalgo_stransformers.so

2.4. ALGO_STS_SetParams¶

功能

设置多模态模型视觉token的起止位置和占位符。

语法

MI_S32 ALGO_STS_SetParams(STSHandle handle, STSParams_t params);

形参

参数名称描述输入/输出

handle 句柄输入

params 多模态模型相关参数,详见[STSParams_t] 输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
相关结构体

STSParams_t
依赖
- 头文件：sgs_sts_api.h
- 库文件：libsgsalgo_stransformers.a / libsgsalgo_stransformers.so

2.5. ALGO_STS_Generate¶

功能

执行模型推理，输出token结果。

语法

MI_S32 ALGO_STS_Generate(STSHandle handle, STSInput_t* input, STSOutput_t* output);

形参

参数名称描述输入/输出

handle 句柄输入

input prompt输入及回调输入

output 模型输出输出
返回值

返回值描述

0 成功

其它失败(详见错误码)
相关结构体

STSInput_t、STSOutput_t
依赖
- 头文件：sgs_sts_api.h、sgs_algo_datatype.h
- 库文件：libsgsalgo_stransformers.a / libsgsalgo_stransformers.so

2.6. ALGO_STS_LoadPromptCache¶

功能

加载预先生成的提示词cache文件。

语法

MI_S32 ALGO_STS_LoadPromptCache(STSHandle handle,MI_U8* cache_path);

形参

参数名称描述输入/输出

handle 句柄输入

cache_path 提示词cache文件输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
相关结构体
依赖
- 头文件：sgs_sts_api.h、sgs_algo_datatype.h
- 库文件：libsgsalgo_stransformers.a / libsgsalgo_stransformers.so

2.7. ALGO_STS_SetFunctionTools¶

功能

设置function tools，以支持调用工具的能力。

语法

MI_S32 ALGO_STS_SetFunctionTools(STSHandle handle, MI_U8* tools);

形参

参数名称描述输入/输出

handle 句柄输入

tools 工具字符串，当再次调用会覆盖上一次设置的tools,当设置string tools=""时，会清理掉工具输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
相关结构体
依赖
- 头文件：sgs_sts_api.h、sgs_algo_datatype.h
- 库文件：libsgsalgo_stransformers.a / libsgsalgo_stransformers.so

2.8. ALGO_STS_Abort¶

功能

中途退出模型推理

语法

MI_S32 ALGO_STS_Abort(STSHandle handle);

形参

参数名称描述输入/输出

handle 句柄输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
相关结构体
依赖
- 头文件：sgs_sts_api.h
- 库文件：libsgsalgo_stransformers.a / libsgsalgo_stransformers.so

2.9. ALGO_STS_ClearKVCache¶

功能

清除历史上下文，支持多轮对话重置。

语法

MI_S32 ALGO_STS_ClearKVCache(STSHandle handle, MI_BOOL keep_system_prompt, MI_U32 cache_pos_start, MI_U32 cache_pos_end);

形参

参数名称	描述	输入/输出
handle	句柄	输入
keep_system_prompt	是否保存系统提示词（包含tools）	输入
cache_pos_start	cache的起始位置,暂不起作用	输入
cache_pos_end	cache的结束位置,暂不起作用	输入

返回值

返回值描述

0 成功

其它失败(详见错误码)
相关结构体
依赖
- 头文件：sgs_sts_api.h
- 库文件：libsgsalgo_stransformers.a / libsgsalgo_stransformers.so

2.10. ALGO_STS_Deinit¶

功能

销毁句柄，释放模型所有资源。

语法

MI_S32 ALGO_STS_Deinit(STSHandle handle);

形参

参数名称描述输入/输出

handle 句柄输入
返回值

返回值描述

0 成功

其它失败(详见错误码)
相关结构体
依赖
- 头文件：sgs_sts_api.h
- 库文件：libsgsalgo_stransformers.a / libsgsalgo_stransformers.so

3. 结构体说明¶

3.1 IpuConfig_t¶

说明

IPU硬件配置。

定义

typedef struct IpuConfig
{
    MI_BOOL create_device;
    MI_BOOL destroy_device;
    MI_U32 max_variable_size;
    char ipu_firmware_path[128];
}IpuConfig_t;

成员

成员名称	描述
create_device	是否在算法库内创建IPUDevice，默认为true, 即在库内创建；多库调用时，可设置为false并在外部手动创建IPUDevice
destroy_device	是否在算法库内销毁IPUDevice，默认为true, 即在库内销毁；多库调用时，可设置为false并在外部手动销毁IPUDevice
max_variable_size	创建device需要申请的最大buffsize，填0即可
ipu_firmware_path[128]	ipu_firmware_path路径

相关数据类型及接口

ALGO_STS_Init

3.2 STSInit_t¶

说明

模型初始化配置。

定义

typedef struct
{
    MI_U8 model_path[MAX_STS_STRLEN];
    IpuConfig_t ipu_config;
}STSInit_t;

成员

成员名称描述

model_path[MAX_STS_STRLEN] 模型配置文件路径

ipu_config IPU硬件资源配置
相关数据类型及接口

ALGO_STS_Init

3.3 STSParams_t¶

说明

语言模型、多模态模型参数配置。

定义

typedef struct
{
    MI_U32 img_start_token;
    MI_U32 img_end_token;
    MI_U8 img_pad_token[MAX_INPUT_NUM];
    MI_U8 video_pad_token[MAX_INPUT_NUM];
    MI_BOOL set_config;
    GenerationConfig_t generation_config;
}STSParams_t;

成员

成员名称	描述
img_start_token	图片token的起始位置
img_end_token	图片token的结束位置
img_pad_token[MAX_INPUT_NUM]	图片token的占位符
video_pad_token[MAX_INPUT_NUM]	视频token的占位符
set_config	是否设置generation_config 参数
generation_config	generation 参数

相关数据类型及接口

ALGO_STS_SetParams

3.4 STSInput_t¶

说明

推理输入参数配置。

定义

typedef struct
{
    ImageTensor_t image;
    AudioTensor_t audio;
    VideoTensor_t video;
    MI_U8 role[MAX_ROLE_NUM][MAX_INPUT_NUM];
    MI_U8 prompt[MAX_ROLE_NUM][MAX_INPUT_NUM];
    MI_U8 role_prompt_num;
    MI_BOOL stream;
    MI_BOOL enable_thinking;
    MI_BOOL cache_user_prefix;
    STSPromptCacheParams_t system_prompt_cache;
    void (*streamer)(const char* token,bool is_end);
}STSInput_t;

成员

成员名称	描述
image	图像输入buffer
audio	语音输入buffer
vidio	视频输入buffer
role[MAX_ROLE_NUM][MAX_INPUT_NUM]	聊天模板的角色标识符
prompt[MAX_ROLE_NUM][MAX_INPUT_NUM]	用户提问或者系统提示
role_prompt_num	角色的数量
stream	是否打开流式推理功能，设置为True，每次解码完一个token立即输出；设置为false，解码完一整句话后才输出
enable_thinking	是否开启thinking模式，只有支持thinking的模型开启才生效
cache_user_prefix	是否缓存首个视觉token之前的固定前缀，仅多模态输入有效，开启后多轮多模态对话可复用前缀KV
system_prompt_cache	提示词cache 参数
(*streamer)(const char- token, bool is_end)	流式输出回调函数

备注：当设置了系统提示词时，第一次generate对系统提示词进行缓存，下次调用generate，算法库会自动判断系统提示词是否发生改变，如果没有发生则使用缓存信息，不会重复推理系统提示词，发生改变了则会重头开始推理，并缓存新的系统提示词。如果没有设置新的系统提示词，则默认使用前面的系统提示词。

相关数据类型及接口

ALGO_STS_Generate

3.5 STSOutput_t¶

说明

模型推理输出结果获取。

定义

typedef struct
{
    MI_U8 output_string[MAX_OUTPUT_NUM];
    MI_U32 output_tokens[MAX_OUTPUT_NUM];
    ImageTensor_t embedding;
}STSOutput_t;

成员

成员名称	描述
output_string[MAX_OUTPUT_NUM]	非流式推理，输出模型所有回答
output_tokens[MAX_OUTPUT_NUM]	非流式推理，输出模型字符串对应的token id
embedding	输出embedding buffer

相关数据类型及接口

ALGO_STS_Generate

3.6 STSPromptCacheParams_t¶

说明

提示词cache参数

定义

typedef struct
{
    MI_BOOL save_cache;
    MI_U8 save_cache_path[MAX_STS_STRLEN];
}STSPromptCacheParams_t;

成员

成员名称描述

save_cache 是否保存cache

save_cache_path 保存cache的文件路径,保存系统提示词时，如果设置了tools，tools也会保存在cache中
相关数据类型及接口

ALGO_STS_Generate

3.7 ImageTensor_t¶

说明

图像输入数据配置。

定义

typedef struct ImageTensor
{
    void* p_vir_addr;
    MI_U64 phy_addr;
    MI_U32 buf_size;
    MI_U64 pts;
    uint16_t width;
    uint16_t height;
}ImageTensor_t;

成员

成员名称	描述
p_vir_addr	输入buffer的虚拟地址
phy_addr	输入buffer的物理地址
buf_size	输入buffer的长度
pts	输入buffer时间戳
width	图像宽度
height	图像高度

相关数据类型及接口

ALGO_STS_Generate

3.8 AudioTensor_t¶

说明

语音输入数据配置。

定义

typedef struct AudioTensor
{
    void* p_vir_addr;
    MI_U64 phy_addr;
    MI_U32 buf_size;
} AudioTensor_t;

成员

成员名称描述

p_vir_addr 输入buffer的虚拟地址

phy_addr 输入buffer的物理地址

buf_size 输入buffer的长度
相关数据类型及接口

ALGO_STS_Generate

3.9 VideoTensor_t¶

说明

视频输入数据配置。
定义

typedef struct VideoTensor { void* p_vir_addr; MI_U64 phy_addr; MI_U32 buf_size; uint16_t width; uint16_t height; uint16_t frame_num; uint16_t internal_frames; uint16_t fps; }VideoTensor_t;

成员

成员名称	描述
p_vir_addr	输入buffer的虚拟地址
phy_addr	输入buffer的物理地址
buf_size	输入buffer的长度
width	宽
height	高
frame_num	帧数
internal_frames	帧间隔
fps	帧率

相关数据类型及接口

ALGO_STS_Generate

3.10 ModelConfig_t¶

说明

模型输入属性获取。

定义

typedef struct ModelConfig
{
    MI_IPU_ELEMENT_FORMAT format;
    MI_U32 width;
    MI_U32 height;
}ModelConfig_t;

成员

成员名称描述

width 模型输入数据的宽

height 模型输入数据的高

format 模型输入数据的类型
相关数据类型及接口

ALGO_STS_GetInputAttr

3.11 GenerationConfig_t¶

说明

文本推理控制参数配置。

定义

typedef struct GenerationConfig
{
    bool do_sample;
    int top_k;
    float top_p;
    float temperature;
    float repetition_penalty;
    bool stream;
    int eos_token_id[MAX_EOS_NUM];
    int eos_num;
    bool use_cache;
    int max_length;
    int max_new_tokens;
}GenerationConfig_t;

成员

成员名称	描述
do_sample	采样策略：true=随机采样，false=确定性策略
top_k	从概率最高的前k个token中采样，仅do_sample=true生效
top_p	从累计概率达到p的最小token集合中采样，仅do_sample=true生效
temperature	温度系数，值>1增加随机性，值<1降低随机性，仅do_sample=true生效
repetition_penalty	重复惩罚系数，仅当值>1及do_sample=true时生效
stream	是否启用流式推理
eos_token_id[MAX_EOS_NUM]	结束符标志位
eos_num	eos 的个数
use_cache	是否启用KV缓存，用于多轮对话
max_length	kv_cache的最大长度
max_new_tokens	单次推理最大生成token数

相关数据类型及接口

ALGO_STS_GetInputAttr

3.12 STSCallBack¶

说明

回调函数结构体

定义

typedef void (*TokenizerCallBack)(char* text, int32_t* tokens, uint64_t num_tokens);
typedef void (*ModelCallBack)(void* tensor, int tensor_size,uint32_t* tensor_shape,int tensor_dims, MI_IPU_ELEMENT_FORMAT format,char* model_name, char* layer_name);

typedef struct
{
    TokenizerCallBack tokenizer_callback;
    ModelCallBack     model_callback;
}STSCallBack;

成员

成员名称描述

tokenizer_callback tokenizer的回调函数

model_callback 模型输入输出的回调函数
相关数据类型及接口

ALGO_STS_CallBack

4. 进阶功能与配置说明¶

4.1. kv cache管理¶

功能描述

在进行多轮对话时，支持手动清除指定区间的kv_cache[cache_pos_start, cache_pos_end]，将kv cache重置。
关键特性

清除缓存时可通过keep_system_prompt参数选择是否保留系统提示词缓存，避免重复推理:
- keep_system_prompt=1，保留系统提示词的kv cache；
- keep_system_prompt=0，清空所有缓存。
相关接口/结构体

ALGO_STS_ClearKVCache

4.2. 历史上下文管理¶

功能描述

在进行多轮对话时，当历史保存的总token长度（system tokens + prompt tokens + generate tokens）大于（max_length-max_new_tokens）时，运行库会自动删除最早的历史内容。
注意事项

自动清理历史内容耗时较高，建议配合ALGO_STS_ClearKVCache手动管理缓存。
相关接口/结构体

ALGO_STS_ClearKVCache、ALGO_STS_Generate

GenerationConfig_t

4.3. chat_template管理¶

功能描述

文本输入场景下，大模型运行库会自动解析tokenizer_config.json中的chat_template字段，获取提示词模板。如果用户需要自己设定提示词模板可以通过结构体STSInput_t配置"role"进行重置。

多模态输入场景下，需要按照规范配置"prompt"才可以从tokenizer_config.json自动获取提示词模板。示例如下：
```
STSInput_t.prompt = R"(
    [
        {"type":"text", "text":"请分析这张图片："},
        {"type":"image", "url":"https://example.com/img.png"}
    ]
)";
```
相关接口/结构体

ALGO_STS_Generate

STSInput_t

4.4. 流式推理回调设置¶

功能描述

流式推理支持逐token实时输出推理结果，启用时需将STSInput_t.stream或GenerationConfig_t.stream设置为true，并实现STSInput_t.streamer回调函数，该函数会在每个token生成完成后被触发，可通过回调参数获取当前生成的token及是否为最后一个token的标识，从而实现推理结果的实时接收与处理。
相关接口/结构体

ALGO_STS_Generate

STSInput_t

4.5. pcie多板级联设置¶

待补充

4.6. lora模型管理¶

待补充

5. 错误码 ¶

错误码	数值	描述
E_ALGO_SUCCESS	0	操作成功
E_ALGO_HANDLE_NULL	1	算法句柄为空
E_ALGO_INVALID_PARAM	2	无效的输入参数
E_ALGO_DEVICE_FAULT	3	硬件错误
E_ALGO_LOADMODEL_FAIL	4	加载模型失败
E_ALGO_INIT_FAIL	5	算法初始化失败
E_ALGO_NOT_INIT	6	算法尚未初始化
E_ALGO_INPUT_DATA_NULL	7	算法输入数据为空
E_ALGO_INVALID_INPUT_SIZE	8	无效的算法输入数据维度
E_ALGO_INVALID_LICENSE	9	无效的license许可
E_ALGO_MEMORY_OUT	10	内存不足
E_ALGO_FILEIO_ERROR	11	文件读写操作错误
E_ALGO_INVALID_OUTPUT_SIZE	12	无效的算法输出数据维度

数据类型	定义
IpuConfig_t	IPU硬件相关结构体
STSInit_t	模型初始化结构体
STSParams_t	多模态模型输入参数结构体
STSInput_t	模型推理输入参数结构体
STSOutput_t	模型推理输出结构体
STSPromptCacheParams_t	提示词cache参数
ImageTensor_t	图像输入相关结构体
AudioTensor_t	语音输入相关结构体
VideoTensor_t	视频输入相关结构体
ModelConfig_t	模型输入属性结构体
GenerationConfig_t	文本推理控制参数结构体
STSCallBack	回调函数结构体

成员名称	描述
model_path[MAX_STS_STRLEN]	模型配置文件路径
ipu_config	IPU硬件资源配置

成员名称	描述
save_cache	是否保存cache
save_cache_path	保存cache的文件路径,保存系统提示词时，如果设置了tools，tools也会保存在cache中

成员名称	描述
width	模型输入数据的宽
height	模型输入数据的高
format	模型输入数据的类型

成员名称	描述
tokenizer_callback	tokenizer的回调函数
model_callback	模型输入输出的回调函数

返回值	描述
0	成功
其它	失败(详见错误码)

返回值	描述
0	成功
其它	失败(详见错误码)

返回值	描述
0	成功
其它	失败(详见错误码)

返回值	描述
0	成功
其它	失败(详见错误码)