跳到主要内容
版本：2.8.1

TORQ-LLM C API 参考

概述​

TORQ-LLM C API 是在 TORQ Runtime 之上提供的大语言模型（LLM）推理接口，面向 LLaMA2、Qwen2、Qwen3、Qwen2.5-VL 等模型，支持预填充（Prefill）、分块预填充（Chunked Prefill）与解码（Decoding）三种阶段。

支持硬件平台​

A210

编译说明​

各硬件平台的 C API 支持情况​

序号TORQ-LLM C APIA210
1tllm_create_context√
2tllm_execute√
3tllm_kvcache_sync√
4tllm_decoding_update_kvcache√
5tllm_create_embd_input√
6tllm_create_embd_output√
7tllm_unwrap_output_buffer√
8tllm_get_top1√
9tllm_update_decoding_mask√
10tllm_get_output_from_runtime_ctx√

API 头文件与运行时库​

  • 头文件：tllm.h
  • 运行时库：依赖 TORQ Runtime，请参考 TORQ C API 参考 中的运行时库说明。

接口调用流程​

典型接口调用流程


API 说明​

主要功能介绍​


数据结构​

tllm_transformer_block​

描述

tllm_transformer_block 结构体用于描述单层 Transformer 模型在推理时各类核心张量及缓存的布局。每一层均包含旋转位置编码所需的 sin/cos 缓存、注意力 mask、序列位置，以及历史和当前步的 KV 缓存指针。通过 past/present 缓存的灵活切换，支持高效的自回归/解码流程。cache_k_buffer 和 cache_v_buffer 指向实际物理缓存空间，实现设备或主内存下的快速 KV 管理。

常用于模型各层推理/前向调用时，分层维护注意力和 KV 状态，便于上下文连续推理和流式解码。

请注意用户无需直接分配该结构体，仅在模型内部或低阶 API 用于缓存/输入输出处理。

定义

struct tllm_transformer_block {
    int layer_id;

    struct ucann_tensor *sin_cache;
    struct ucann_tensor *cos_cache;

    struct ucann_tensor *mask;
    struct ucann_tensor *position;

    /* history cache as input */
    struct ucann_tensor **past_value;
    struct ucann_tensor **past_key;

    /* current cache as output */
    struct ucann_tensor *present_value;
    struct ucann_tensor *present_key;

    /* cache memory space */
    void **cache_k_buffer;
    void **cache_v_buffer;
};

成员变量

成员变量数据类型描述
layer_idintTransformer 层编号（从 0 开始）。
sin_cachestruct ucann_tensor*旋转位置编码正弦缓存，与序列位置对齐。
cos_cachestruct ucann_tensor*旋转位置编码余弦缓存，与序列位置对齐。
maskstruct ucann_tensor*注意力 mask（含自回归/填充遮罩）。
positionstruct ucann_tensor*当前位置索引张量（用于位置编码）。
past_valuestruct ucann_tensor**历史缓存 V 列表（作为解码阶段输入）。
past_keystruct ucann_tensor**历史缓存 K 列表（作为解码阶段输入）。
present_valuestruct ucann_tensor*当前步输出的 V（更新 KV 缓存）。
present_keystruct ucann_tensor*当前步输出的 K（更新 KV 缓存）。
cache_k_buffervoid**K 缓存物理内存地址数组（设备侧/主存）。
cache_v_buffervoid**V 缓存物理内存地址数组（设备侧/主存）。

需求

头文件 tllm.h。


tllm_runtime_ctx​

描述

运行期上下文，包含 TORQ 上下文、输入/输出张量属性与内存、动态形状信息、embedding 输出等。

定义

struct tllm_runtime_ctx {
    torq_context torq_ctx;

    int fixed_seq_len;

    int n_input;
    torq_tensor_attr *in_attr;
    torq_tensor_mem **input_mem;

    int n_output;
    torq_tensor_attr *out_attr;
    torq_tensor_mem **output_mem;

    bool verbose_log;

    int mem_init_flag;
    torq_input_range **dyn_range;
    int dyn_index;

    void *emb_output_data;
    torq_tensor_attr *emb_output_attr;

    struct ucann_tensor *tok_embeddings;
    struct ucann_tensor *pos_embeddings;
    struct tllm_transformer_block **transformer_block;

#ifdef CONFIG_BUILD_A210
    void *kv_cache_buffer;

    void *input_buffer;
    void *input_buffer_addr;
    uint64_t input_buffer_size;
    void *output_buffer;
    void *output_buffer_addr;
    uint64_t output_buffer_size;
#endif

    // context for chunked prefill
    int chunked_prefill_index;
    struct tllm_context *chunked_prefill_ctx;
};

成员变量

成员变量数据类型描述
torq_ctxtorq_contextTORQ 运行时上下文句柄。
fixed_seq_lenint固定序列长度（0 表示由模型/输入决定）。
n_inputint输入张量个数。
in_attrtorq_tensor_attr*输入张量属性数组。
input_memtorq_tensor_mem**输入张量内存数组（与 in_attr 一一对应）。
n_outputint输出张量个数。
out_attrtorq_tensor_attr*输出张量属性数组。
output_memtorq_tensor_mem**输出张量内存数组（与 out_attr 一一对应）。
verbose_logbool是否启用详细日志。
mem_init_flagint内存初始化标志（避免重复分配/释放）。
dyn_rangetorq_input_range**动态形状输入范围数组（用于动态编译/运行）。
dyn_indexint当前动态形状索引（选择具体范围）。
emb_output_datavoid*embedding 输出数据指针。
emb_output_attrtorq_tensor_attr*embedding 输出张量属性。
tok_embeddingsstruct ucann_tensor*词嵌入张量。
pos_embeddingsstruct ucann_tensor*位置嵌入张量。
transformer_blockstruct tllm_transformer_block**各层 Transformer block 指针数组。
chunked_prefill_indexint分块预填充当前块索引。
chunked_prefill_ctxstruct tllm_context*分块预填充专用上下文。

需求

头文件 tllm.h。


tllm_context​

描述

高层上下文，串联 tllm_runtime_ctx、tllm_config 与阶段类型。

定义

struct tllm_context {
    int layers_num;

    struct tllm_uca_model *uca_model;

    struct tllm_runtime_ctx *runtime_ctx;

    struct tllm_config *config;

    enum tllm_phase_type phase_type;

    struct tllm_sampler *sampler;
};

成员变量

成员变量数据类型描述
layers_numint模型层数。
uca_modelstruct tllm_uca_model*UCANN 编译后的模型对象。
runtime_ctxstruct tllm_runtime_ctx*运行期上下文。
configstruct tllm_config*运行配置（模型与构建选项）。
phase_typeenum tllm_phase_type当前执行阶段类型。
samplerstruct tllm_sampler*采样器（用于 token 选择）。

需求

头文件 tllm.h。


tllm_input​

描述

输入结构体。

定义

struct tllm_input {
    /* real input length */
    int64_t n_tokens;
    int32_t *token;
    int32_t pos;
    int32_t output_token;
    struct mm_input *img_input;
    bool pre_embedded;
};

成员变量

成员变量数据类型描述
n_tokensint64_t输入 token 数。
tokenint32_t*token ID 数组。
posint32_t起始位置（相对序列）。
output_tokenint32_t上一步输出的 token（解码时可用）。
img_inputstruct mm_input*多模态图像输入（可选）。
pre_embeddedbool输入是否为预嵌入向量。

需求

头文件 tllm.h。


tllm_output​

描述

输出结构体。

定义

struct tllm_output {
    int32_t *token;
    int seq_len;
};

成员变量

成员变量数据类型描述
tokenint32_t*生成或回填的 token 序列。
seq_lenint当前输出序列长度。

需求

头文件 tllm.h。


tllm_config​

描述

运行配置，包含 hf_model 与 option。

定义

struct tllm_config {
    /*
     * hf_model: model from huggingface, only weights
     */
    struct tllm_model *hf_model;
    struct tllm_build_option *option;
};

成员变量

成员变量数据类型描述
hf_modelstruct tllm_model*HuggingFace 导出的权重模型。
optionstruct tllm_build_option*构建/编译选项。

需求

头文件 tllm.h。


tllm_create_context​

描述

初始化并创建指定阶段（Prefill/Chunked Prefill/Decoding）的上下文，串联 tllm_runtime_ctx、tllm_config 与阶段类型，内部完成 TORQ 初始化与模型信息查询。

定义

struct tllm_context *tllm_create_context(struct tllm_context *src_context, char *model_path,
                                     struct tllm_config *config, enum tllm_phase_type phase_type);

成员变量

成员变量数据类型描述
src_contextstruct tllm_context*可选，已有上下文（用于权重共享）。
model_pathchar*模型导出目录路径。
configstruct tllm_config*模型与构建选项配置。
phase_typeenum tllm_phase_type执行阶段类型。

返回值

  • 成功返回上下文指针 struct tllm_context*。
  • 失败返回 NULL。

需求

头文件 tllm.h。

注意事项

若启用权重共享，内部将进行系数一致性校验。

示例代码

struct tllm_context *prefill_ctx = tllm_create_context(NULL, model_dir, &config, TLLM_PHASE_TYPE_PREFILL);

tllm_create_embd_input​

描述

构建 embedding 输入结构体。

定义

struct tllm_input *tllm_create_embd_input(int64_t n_tokens, int32_t *token, int64_t fixed_seq_len);

成员变量

成员变量数据类型描述
n_tokensint64_t输入 token 数量。
tokenint32_t*指向输入 token ID 的指针。
fixed_seq_lenint64_t固定序列长度（用于分配/对齐，0 表示按输入推断）。

返回值

返回分配好的结构体指针，需由调用方在合适时机释放。

需求

头文件 tllm.h。


tllm_create_embd_output​

描述

构建 embedding 输出结构体。

定义

struct tllm_output *tllm_create_embd_output(int64_t n_tokens, int32_t *token, int64_t max_seq_len);

成员变量

成员变量数据类型描述
n_tokensint64_t期望输出 token 数量（初始容量）。
tokenint32_t*输出 token 缓冲区指针（由调用方管理生命周期）。
max_seq_lenint64_t输出序列最大长度上限。

返回值

返回分配好的结构体指针，需由调用方在合适时机释放。

需求

头文件 tllm.h。


tllm_architecture_enum​

描述

定义 TORQ-LLM 支持的模型架构类型枚举。用于标识不同的大语言模型架构，便于模型加载、解析与推理流程的适配。

语法

enum tllm_architecture_enum {
    TLLM_UNKNOWN = 0,
    TLLM_LLAMA2 = 1,
    TLLM_QWEN2,
    TLLM_QWEN2_5_VL_LM,
    TLLM_QWEN3,
    TLLM_GPT_OSS,
    TLLM_WHISPER,
};

参数

参数说明
TLLM_UNKNOWN未知架构。
TLLM_LLAMA2LLaMA2 架构。
TLLM_QWEN2Qwen2 架构。
TLLM_QWEN2_5_VL_LMQwen2.5-VL 语言模型分支。
TLLM_QWEN3Qwen3 架构。
TLLM_GPT_OSS开源 GPT 类架构。
TLLM_WHISPERWhisper 语音模型架构。

tllm_compile_mode​

描述

定义模型编译模式枚举。控制模型编译与执行的方式，图模式提供更好的整体优化，Eager 模式提供更灵活的算子级编译。

语法

enum tllm_compile_mode {
    TLLM_COMPILE_MODE_GRAPH = 0,
    TLLM_COMPILE_MODE_EAGER = 1,
};

参数

参数说明
TLLM_COMPILE_MODE_GRAPH图模式（完整静态图编译）。
TLLM_COMPILE_MODE_EAGEREager 模式（按算子为单位编译）。

tllm_phase_type​

描述

定义 LLM 推理执行阶段类型枚举。区分预填充、分块预填充与解码三个阶段，每个阶段具有不同的输入输出特征和 KV 缓存处理方式。

语法

enum tllm_phase_type {
    TLLM_PHASE_TYPE_PREFILL = 0,
    TLLM_PHASE_TYPE_CHUNKED_PREFILL,
    TLLM_PHASE_TYPE_DECODING,
};

参数

参数说明
TLLM_PHASE_TYPE_PREFILL预填充阶段。
TLLM_PHASE_TYPE_CHUNKED_PREFILL分块预填充阶段。
TLLM_PHASE_TYPE_DECODING解码阶段。

API 参考​

tllm_kvcache_sync​

描述

在预填充后将 KV 缓存同步至解码阶段上下文，使解码阶段可在已有上下文上继续生成。

语法

int tllm_kvcache_sync(struct tllm_context *prefill_ctx, struct tllm_context *decoding_ctx);

参数

参数数据类型描述
prefill_ctxstruct tllm_context*预填充上下文。
decoding_ctxstruct tllm_context*解码上下文。

返回值

  • TLLM_STATUS_OK 表示成功。
  • 失败返回负值。

需求

头文件: tllm.h。

示例代码

if (tllm_kvcache_sync(prefill_ctx, decoding_ctx) < 0) { /* handle error */ }

tllm_execute​

描述

执行一次预填充或解码推理。

执行一次模型推理。预填充/分块预填充阶段输入为完整序列。解码阶段输入为单步或少量 token，内部根据当前阶段更新/使用 KV 缓存。

语法

int tllm_execute(struct tllm_context *ctx, struct tllm_input *embd);

参数

参数数据类型描述
ctxstruct tllm_context*上下文。
embdstruct tllm_input*token 输入。

返回值

  • TLLM_STATUS_OK 表示成功。
  • 失败返回负值（如 TLLM_STATUS_ERROR）。

需求

头文件: tllm.h。

注意事项

A210 平台若使用统一内存/零拷贝，运行前后需进行 cache flush/invalidate。

示例代码

int ret = tllm_execute(prefill_ctx, input);
if (ret < 0) { /* handle error */ }

tllm_decoding_update_kvcache​

描述

解码阶段更新 KV 缓存。

语法

int tllm_decoding_update_kvcache(struct tllm_input *embd, struct tllm_context *ctx);

参数

参数数据类型描述
embdstruct tllm_input*本步输入 token（用于更新 K/V）。
ctxstruct tllm_context*解码阶段上下文。

返回值

  • TLLM_STATUS_OK 表示成功。
  • 失败返回负值（如 TLLM_STATUS_ERROR）。

需求

头文件: tllm.h。


tllm_update_decoding_mask​

描述

更新解码阶段的注意力 mask，根据当前位置生成自回归遮罩。用于解码推理时动态更新 mask 张量，确保每个位置只能看到之前的 token。

语法

void tllm_update_decoding_mask(float *mask, torq_tensor_attr mask_attr, int position);

参数

参数数据类型描述
maskfloat*注意力 mask 缓冲区指针（可写）。
mask_attrtorq_tensor_attrmask 张量属性（形状/步长/数据类型）。
positionint当前步位置（用于生成自回归遮罩）。

返回值

无返回值（void）。

需求

头文件: tllm.h。


tllm_get_output_from_runtime_ctx​

描述

获取输出 buffer。

语法

void *tllm_get_output_from_runtime_ctx(struct tllm_runtime_ctx *runtime_ctx);

参数

参数数据类型描述
runtime_ctxstruct tllm_runtime_ctx*运行期上下文，用于定位输出缓冲区。

返回值

  • 成功返回输出缓冲区指针（void*）。
  • 失败返回 NULL。

需求

头文件: tllm.h。


tllm_unwrap_output_buffer​

描述

取得当前步输出 buffer 指针。

语法

void *tllm_unwrap_output_buffer(struct tllm_runtime_ctx *runtime_ctx, int n_tokens);

参数

参数数据类型描述
runtime_ctxstruct tllm_runtime_ctx*运行期上下文。
n_tokensint当前步 token 数（决定返回视图大小）。

返回值

  • 成功返回当前步输出缓冲区指针（void*），指向大小为 n_tokens * vocab_size * sizeof(float) 的概率分布数据。
  • 失败返回 NULL。

需求

头文件: tllm.h。


tllm_get_top1​

描述

从概率分布中选取 Top-1 的 index 与概率。

语法

int tllm_get_top1(float *buf, int32_t size, float *prob, int32_t *index);

参数

参数数据类型描述
buffloat*概率分布缓冲区（长度为 size）。
sizeint32_t词表大小或分布长度。
probfloat*输出 Top-1 概率写入地址。
indexint32_t*输出 Top-1 索引写入地址。

返回值

  • 成功返回 TLLM_STATUS_OK。
  • 失败返回负值。

需求

头文件: tllm.h。


典型调用示例​

#include "tllm.h"

// 1) 准备模型与选项（示例中假设已有 model 与 option）
struct tllm_config config = {
    .hf_model = model,
    .option = option,
};

// 2) 创建预填充与解码上下文
struct tllm_context *prefill_ctx = tllm_create_context(NULL, model_path, &config, TLLM_PHASE_TYPE_PREFILL);
struct tllm_context *decoding_ctx = tllm_create_context(prefill_ctx, model_path, &config, TLLM_PHASE_TYPE_DECODING);

// 3) 创建输入并执行预填充
int32_t tokens[] = {1, 2, 3, 4, 5};
struct tllm_input *input = tllm_create_embd_input(5, tokens, 512);
tllm_execute(prefill_ctx, input);

// 4) 预填充与解码 KV 缓存同步
tllm_kvcache_sync(prefill_ctx, decoding_ctx);

// 5) 执行解码并获取输出
struct tllm_input *decode_input = tllm_create_embd_input(1, &tokens[4], 1);
tllm_execute(decoding_ctx, decode_input);
void *output = tllm_unwrap_output_buffer(decoding_ctx->runtime_ctx, 1);
float prob; int32_t next_token;
tllm_get_top1((float*)output, vocab_size, &prob, &next_token);

错误码​

TORQ-LLM 统一错误码定义见 tllm/status.h：

typedef enum tllm_status_enum {
    TLLM_STATUS_OK = 0,
    TLLM_STATUS_ERROR = -1,
    TLLM_STATUS_INVALID_ARGUMENT = -2,
    TLLM_STATUS_UNSUPPORTED = -3,
    TLLM_STATUS_OUT_OF_MEMORY = -4,
    TLLM_STATUS_IO_ERROR = -5,
    TLLM_STATUS_NOT_FOUND = -6,
    TLLM_STATUS_BUSY = -7,
    TLLM_STATUS_TIMEOUT = -8,
} tllm_status_t;

判定与转换：

  • 成功判定：TLLM_SUCCEEDED(st)。
  • 失败判定：TLLM_FAILED(st)。
  • 与 UCANN 兼容转换：tllm_from_ucann_bool(...) 与 tllm_to_ucann_bool(...)。