ONNX Runtime generate() C API

注意：此 API 处于预览阶段，可能会发生更改。

• 概述
• 模型 API
• 分词器 API
• 生成器参数 API
• 生成器 API
• 适配器 API
• 枚举和结构体
• 实用函数

概述

模型 API

创建模型

从给定目录创建模型。该目录应包含一个名为 genai_config.json 的文件，该文件对应于配置规范。

参数

• 输入：config_path 模型配置目录的路径。路径应以 UTF-8 编码。
• 输出：out 创建的模型。

返回值

OgaResult，如果模型创建失败，则包含错误消息。

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateModel(const char* config_path, OgaModel** out);

销毁模型

销毁给定的模型。

参数

• 输入：model 要销毁的模型。

返回值

void

OGA_EXPORT void OGA_API_CALL OgaDestroyModel(OgaModel* model);

生成

根据给定的生成器参数，从模型执行中生成标记数组的数组。

参数

• 输入：model 用于生成的模型。
• 输入：generator_params 用于生成的参数。
• 输出：out 生成的标记序列。调用者负责在使用完序列后使用 OgaDestroySequences 释放序列。

返回值

OgaResult，如果生成失败，则包含错误消息。

OGA_EXPORT OgaResult* OGA_API_CALL OgaGenerate(const OgaModel* model, const OgaGeneratorParams* generator_params, OgaSequences** out);

分词器 API

创建分词器

参数

• 输入：model。应为其创建分词器的模型

返回值

OgaResult，如果分词器创建失败，则包含错误消息。

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateTokenizer(const OgaModel* model, OgaTokenizer** out);

销毁分词器

OGA_EXPORT void OGA_API_CALL OgaDestroyTokenizer(OgaTokenizer*);

编码

编码单个字符串并将编码后的标记序列添加到 OgaSequences。当不再需要 OgaSequences 时，必须使用 OgaDestroySequences 释放它。

参数

返回值

OGA_EXPORT OgaResult* OGA_API_CALL OgaTokenizerEncode(const OgaTokenizer*, const char* str, OgaSequences* sequences);

解码

解码单个标记序列并返回以 null 结尾的 utf8 字符串。 out_string 必须使用 OgaDestroyString 释放

参数

返回值

OGA_EXPORT OgaResult* OGA_API_CALL OgaTokenizerDecode(const OgaTokenizer*, const int32_t* tokens, size_t token_count, const char** out_string);

批量编码

参数

• OGA_EXPORT OgaResult* OGA_API_CALL OgaTokenizerEncodeBatch(const OgaTokenizer*, const char** strings, size_t count, TokenSequences** out);
  

批量解码

OGA_EXPORT OgaResult* OGA_API_CALL OgaTokenizerDecodeBatch(const OgaTokenizer*, const OgaSequences* tokens, const char*** out_strings);

销毁分词器字符串

OGA_EXPORT void OGA_API_CALL OgaTokenizerDestroyStrings(const char** strings, size_t count);

创建分词器流

OgaTokenizerStream 用于增量解码标记字符串，一次一个标记。

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateTokenizerStream(const OgaTokenizer*, OgaTokenizerStream** out);

销毁分词器流

参数

OGA_EXPORT void OGA_API_CALL OgaDestroyTokenizerStream(OgaTokenizerStream*);

解码流

解码流中的单个标记。如果这导致生成单词，它将在“out”中返回。调用者负责将每个块连接在一起以生成完整的结果。“out”在下次调用 OgaTokenizerStreamDecode 或销毁 OgaTokenizerStream 之前有效

OGA_EXPORT OgaResult* OGA_API_CALL OgaTokenizerStreamDecode(OgaTokenizerStream*, int32_t token, const char** out);

生成器参数 API

创建生成器参数

从给定的模型创建 OgaGeneratorParams。

参数

• 输入：model 用于生成的模型。
• 输出：out 创建的生成器参数。

返回值

OgaResult，如果生成器参数创建失败，则包含错误消息。

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateGeneratorParams(const OgaModel* model, OgaGeneratorParams** out);

销毁生成器参数

销毁给定的生成器参数。

参数

• 输入：generator_params 要销毁的生成器参数。

返回值

void

OGA_EXPORT void OGA_API_CALL OgaDestroyGeneratorParams(OgaGeneratorParams* generator_params);

设置搜索选项（数字）

设置搜索选项，其中选项是数字

参数

• generator_params：要在其上设置参数的生成器参数对象
• name：参数的名称
• value：要设置的值

返回值

OgaResult，如果生成器参数创建失败，则包含错误消息。

OGA_EXPORT OgaResult* OGA_API_CALL OgaGeneratorParamsSetSearchNumber(OgaGeneratorParams* generator_params, const char* name, double value);

设置搜索选项（布尔值）

设置搜索选项，其中选项是布尔值。

参数

• generator_params：要在其上设置参数的生成器参数对象
• name：参数的名称
• value：要设置的值

返回值

OgaResult，如果生成器参数创建失败，则包含错误消息。

OGA_EXPORT OgaResult* OGA_API_CALL OgaGeneratorParamsSetSearchBool(OgaGeneratorParams* generator_params, const char* name, bool value);

尝试使用最大批次大小进行图捕获

图捕获将计算图的动态元素固定为常量值。它可以在某些环境中提供更高效的执行。要在图捕获模式下执行，需要预先知道最大批次大小。如果内存不足以分配指定的最大批次大小，则此功能可能会失败。

参数

• generator_params：要在其上设置参数的生成器参数对象
• max_batch_size：要分配的最大批次大小

返回值

OgaResult，如果无法使用指定的批次大小配置图捕获模式，则包含错误消息

OGA_EXPORT OgaResult* OGA_API_CALL OgaGeneratorParamsTryGraphCaptureWithMaxBatchSize(OgaGeneratorParams* generator_params, int32_t max_batch_size);

设置输入

为生成器参数设置输入 ID。输入 ID 用于播种生成。

参数

• 输入：generator_params 要在其上设置输入 ID 的生成器参数。
• 输入：input_ids 大小为 input_ids_count = batch_size * sequence_length 的输入 ID 数组。
• 输入：input_ids_count 输入 ID 的总数。
• 输入：sequence_length 输入 ID 的序列长度。
• 输入：batch_size 输入 ID 的批次大小。

返回值

OgaResult，如果输入 ID 设置失败，则包含错误消息。

OGA_EXPORT OgaResult* OGA_API_CALL OgaGeneratorParamsSetInputIDs(OgaGeneratorParams* generator_params, const int32_t* input_ids, size_t input_ids_count, size_t sequence_length, size_t batch_size);

设置输入序列

为生成器参数设置输入 ID 序列。输入 ID 序列用于播种生成。

参数

• 输入：generator_params 要在其上设置输入 ID 的生成器参数。
• 输入：sequences 输入 ID 序列。

返回值

OgaResult，如果输入 ID 序列设置失败，则包含错误消息。

OGA_EXPORT OgaResult* OGA_API_CALL OgaGeneratorParamsSetInputSequences(OgaGeneratorParams* generator_params, const OgaSequences* sequences);

设置模型输入

设置除 input_ids 之外的其他模型输入。

参数

• generator_params：要在其上设置输入的生成器参数
• name：要设置的参数的名称
• tensor：参数的值

返回值

OgaResult，如果输入设置失败，则包含错误消息。

OGA_EXPORT OgaResult* OGA_API_CALL OgaGeneratorParamsSetWhisperInputFeatures(OgaGeneratorParams*, OgaTensor* tensor);

生成器 API

创建生成器

从给定的模型和生成器参数创建生成器。

参数

• 输入：model 用于生成的模型。
• 输入：params 用于生成的参数。
• 输出：out 创建的生成器。

返回值

OgaResult，如果生成器创建失败，则包含错误消息。

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateGenerator(const OgaModel* model, const OgaGeneratorParams* params, OgaGenerator** out);

销毁生成器

销毁给定的生成器。

参数

• 输入：generator 要销毁的生成器。

返回值

void

OGA_EXPORT void OGA_API_CALL OgaDestroyGenerator(OgaGenerator* generator);

检查生成是否已完成

如果生成器已完成生成所有序列，则返回 true。

参数

• 输入：generator 要检查是否已完成生成所有序列的生成器。

返回值

如果生成器已完成生成所有序列，则为 True，否则为 False。

OGA_EXPORT bool OGA_API_CALL OgaGenerator_IsDone(const OgaGenerator* generator);

运行模型的单次迭代

根据输入 ID 和过去的状态计算模型的 logits。计算出的 logits 存储在生成器中。

参数

• 输入：generator 要为其计算 logits 的生成器。

返回值

OgaResult，如果 logits 计算失败，则包含错误消息。

OGA_EXPORT OgaResult* OGA_API_CALL OgaGenerator_ComputeLogits(OgaGenerator* generator);

生成下一个标记

使用配置的生成参数，根据计算出的 logits 生成下一个标记。

参数

• 输入：generator 要为其生成下一个标记的生成器。

返回值

OgaResult，如果下一个标记的生成失败，则包含错误消息。

OGA_EXPORT OgaResult* OGA_API_CALL OgaGenerator_GenerateNextToken(OgaGenerator* generator);

获取标记数

返回给定索引处序列中的标记数。

参数

• 输入：generator 用于获取给定索引处序列的标记计数的生成器。
• 输入：index。要返回标记的索引

返回值

给定索引处序列中的标记数。

OGA_EXPORT size_t OGA_API_CALL OgaGenerator_GetSequenceCount(const OgaGenerator* generator, size_t index);

获取序列

返回指向给定索引处序列数据的指针。序列中的标记数由 OgaGenerator_GetSequenceCount 给出。

参数

• 输入：generator 用于获取给定索引处序列的序列数据的生成器。指向给定索引处序列数据的指针。序列数据归 OgaGenerator 所有，并在 OgaGenerator 销毁时释放。如果需要在 OgaGenerator 销毁后使用数据，则调用者必须复制数据。
• 输入：index。要获取序列的索引。

返回值

指向标记序列的指针

OGA_EXPORT const int32_t* OGA_API_CALL OgaGenerator_GetSequenceData(const OgaGenerator* generator, size_t index);

设置运行时选项

用于设置运行时选项的 API，将向此通用 API 添加更多参数以支持运行时选项。使用此 API 终止当前会话的示例是使用键“terminate_session”和值“1”调用 SetRuntimeOption：OgaGenerator_SetRuntimeOption(generator, “terminate_session”, “1”)

有关当前运行时选项的更多详细信息，请访问 此处。

参数

• 输入：generator 需要在其上设置运行时选项的生成器
• 输入：key 用于设置运行时选项的键
• 输入：value 为提供的键的值

返回值

void

OGA_EXPORT void OGA_API_CALL OgaGenerator_SetRuntimeOption(OgaGenerator* generator, const char* key, const char* value);

适配器 API

此 API 用于加载和切换微调适配器，例如 LoRA 适配器。

创建适配器

创建管理适配器的对象。此对象用于加载所有模型适配器。它负责对加载的适配器进行引用计数。

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateAdapters(const OgaModel* model, OgaAdapters** out);

参数

• model：先前创建的 OgaModel

结果

• out：对创建的 OgaAdapters 列表的引用

加载适配器

从给定的适配器文件路径和适配器名称加载模型适配器。

OGA_EXPORT OgaResult* OGA_API_CALL OgaLoadAdapter(OgaAdapters* adapters, const char* adapter_file_path, const char* adapter_name);

参数

• adapters：要将适配器加载到其中的 OgaAdapters 对象。
• adapter_file_path：要加载的适配器的文件路径。
• adapter_name：适配器的唯一标识符，用于适配器查询

返回值

OgaResult，如果适配器加载失败，则包含错误消息。

卸载适配器

从先前加载的适配器集中卸载具有给定标识符的适配器。如果未找到适配器，或者无法卸载适配器（正在使用时），则返回错误。

OGA_EXPORT OgaResult* OGA_API_CALL OgaUnloadAdapter(OgaAdapters* adapters, const char* adapter_name);

参数

• adapters：要从中卸载适配器的 OgaAdapters 对象。
• adapter_name：要卸载的适配器的名称。

返回值

OgaResult，如果适配器卸载失败，则包含错误消息。 如果使用尚未加载或已被仍在使用的 OgaGenerator 标记为活动的适配器调用该方法，则可能会发生这种情况。

设置活动适配器

将具有给定适配器名称的适配器设置为给定 OgaGenerator 对象的活动适配器。

OGA_EXPORT OgaResult* OGA_API_CALL OgaSetActiveAdapter(OgaGenerator* generator, OgaAdapters* adapters, const char* adapter_name);

参数

• generator：要设置活动适配器的 OgaGenerator 对象。
• adapters：管理模型适配器的 OgaAdapters 对象。
• adapter_name：要设置为活动的适配器的名称。

返回值

OgaResult，如果适配器未能设置为活动状态，则包含错误消息。 如果使用尚未预先加载的适配器调用该方法，则可能会发生这种情况。

枚举和结构体

typedef enum OgaDataType {
  OgaDataType_int32,
  OgaDataType_float32,
  OgaDataType_string,  // UTF8 string
} OgaDataType;

typedef struct OgaResult OgaResult;
typedef struct OgaGeneratorParams OgaGeneratorParams;
typedef struct OgaGenerator OgaGenerator;
typedef struct OgaModel OgaModel;
typedef struct OgaBuffer OgaBuffer;

实用函数

设置 GPU 设备 ID

OGA_EXPORT OgaResult* OGA_API_CALL OgaSetCurrentGpuDeviceId(int device_id);

获取 GPU 设备 ID

OGA_EXPORT OgaResult* OGA_API_CALL OgaGetCurrentGpuDeviceId(int* device_id);

获取错误消息

参数

• 输入：result 包含错误消息的 OgaResult。

返回值

OgaResult 中包含的错误消息。 const char* 归 OgaResult 所有，将在 OgaResult 销毁时释放。

OGA_EXPORT const char* OGA_API_CALL OgaResultGetError(OgaResult* result);

销毁结果

参数

• 输入：result 要销毁的 OgaResult。

返回值

void

OGA_EXPORT void OGA_API_CALL OgaDestroyResult(OgaResult*);

销毁字符串

参数

• 输入：要销毁的字符串

返回值

OGA_EXPORT void OGA_API_CALL OgaDestroyString(const char*);

销毁缓冲区

参数

• 输入：要销毁的缓冲区

返回值

void

OGA_EXPORT void OGA_API_CALL OgaDestroyBuffer(OgaBuffer*);

获取缓冲区类型

参数

• 输入：缓冲区

返回值

缓冲区的类型

OGA_EXPORT OgaDataType OGA_API_CALL OgaBufferGetType(const OgaBuffer*);

获取缓冲区的维度数量

参数

• 输入：缓冲区

返回值

缓冲区中的维度数量

OGA_EXPORT size_t OGA_API_CALL OgaBufferGetDimCount(const OgaBuffer*);

获取缓冲区维度

获取缓冲区的维度

参数

• 输入：缓冲区
• 输出：维度数组

返回值

OgaResult

OGA_EXPORT OgaResult* OGA_API_CALL OgaBufferGetDims(const OgaBuffer*, size_t* dims, size_t dim_count);

获取缓冲区数据

从缓冲区获取数据

参数

返回值

void

OGA_EXPORT const void* OGA_API_CALL OgaBufferGetData(const OgaBuffer*);

创建序列

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateSequences(OgaSequences** out);

销毁序列

参数

• 输入：sequences 要销毁的 OgaSequences。

返回值

void

返回值

OGA_EXPORT void OGA_API_CALL OgaDestroySequences(OgaSequences* sequences);

获取序列数

返回 OgaSequences 中的序列数量

参数

• 输入：序列

返回

OgaSequences 中的序列数量

OGA_EXPORT size_t OGA_API_CALL OgaSequencesCount(const OgaSequences* sequences);

获取序列中的 token 数量

返回给定索引处的序列中的 token 数量

参数

• 输入：序列

返回

给定索引处的序列中的 token 数量

OGA_EXPORT size_t OGA_API_CALL OgaSequencesGetSequenceCount(const OgaSequences* sequences, size_t sequence_index);

获取序列数据

返回指向给定索引处序列数据的指针。序列中的 token 数量由 OgaSequencesGetSequenceCount 给出

参数

• 输入：序列

返回

指向给定索引处序列数据的指针。该指针在 OgaSequences 被销毁之前有效。

OGA_EXPORT const int32_t* OGA_API_CALL OgaSequencesGetSequenceData(const OgaSequences* sequences, size_t sequence_index);