ONNX Runtime generate() C 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 终止当前会话的示例是调用 SetRuntimeOption，其中键为“terminate_session”，值为“1”：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 中的序列数量
参数
- 输入：sequences
返回值
OgaSequences 中的序列数量
OGA_EXPORT size_t OGA_API_CALL OgaSequencesCount(const OgaSequences* sequences);
获取序列中的令牌数量
返回给定索引处序列中的令牌数量
参数
- 输入：sequences
返回值
给定索引处序列中的令牌数量
OGA_EXPORT size_t OGA_API_CALL OgaSequencesGetSequenceCount(const OgaSequences* sequences, size_t sequence_index);
获取序列数据
返回指向给定索引处序列数据的指针。序列中的令牌数量由 OgaSequencesGetSequenceCount 提供。
参数
- 输入：sequences
返回值
指向给定索引处序列数据的指针。该指针在 OgaSequences 销毁之前有效。
OGA_EXPORT const int32_t* OGA_API_CALL OgaSequencesGetSequenceData(const OgaSequences* sequences, size_t sequence_index);