离线版本SDK文档

SenseChatLiteSDK API文档

版本号	更新内容	备注
V1.0.0	初版
V1.0.1	新增在线版本SDK文档内容

SenseTime

1 结构体（structs）和类型别名（typedefs）说明

CMessage

一个CMessage对象表示一条大语言模型输入、输出的消息。

类型	成员名称	说明
Role	role	消息角色
char *	content	消息内容

ModelParameters

端侧模型的模型参数

类型	成员名称	说明
int	max_new_tokens	最大生成的token数量
float	repetition_penalty	重复惩罚系数
float	temperature	温度，控制随机性
float	top_p	最大token概率累加和阈值

LLMRuntimeStats

LLM对话状态统计

类型	成员名称	说明
float	prefill_toks_per_sec	Prefill速度（token/s）
float	decode_toks_per_sec	Decode速度（token/s）
float	prefill_time_last_round	上一轮Prefill时间
float	percentage_of_terminal_toks	端侧Token占比
int	prefill_toks_last_round	上一轮Prefill数量
int	decode_toks_last_round	上一轮Decode数量
int	historical_rounds	历史对话轮数

smart_handle_t

SmartLLM上下文handle，用于调用各个接口。

CStreamCompleteCallback

流式补全的回调函数，从SmartLLMStreamComplete调用。

回调函数参数列表：

类型	参数名称	说明
StreamStatus	status	流式补全运行状态
const char *	output	新增的token
void *	user_data	从SmartLLMStreamComplete的user_data参数转发。

回调函数返回值：

如果正常返回，返回0，否则返回非0。

CStreamChatCallback

流式对话的回调函数，从SmartLLMStreamChat调用。

回调函数参数列表：

类型	参数名称	说明
StreamStatus	status	流式对话运行状态
const char *	output _size	新增的token
void *	user_data	从SmartLLMStreamChat的user_data参数转发。

回调函数返回值：

如果正常返回，返回0，否则返回非0。

2 枚举（enums）

Error

表示接口调用的错误状态。

名称	值	说明
kSuccess	0	接口正常返回
kInvalidArgs	-1	参数错误
kInvalidHandle	-2	无效的handle
kOutOfMemory	-3	系统内存不足
kRunFailed	-4	模型运行失败
kUndefined	-5	未定义行为
kFileNotFound	-6	文件找不到
kInvalidModelFile	-7	模型文件错误
kTriggerSensitive	-8	触发敏感词
kExceededTokenLength	-9	超过最大的token长度
kInvalidNetwork	-10	网络异常
kFileAlreadyExists	-11	文件已经存在
kInvalidLicense	-12	License错误
kLanguageNotAllowed	-13	输入了不支持的语言
kModuleNotInitialized	-999	模块未被初始化
kUnsupported	-1000	不支持的操作

MemoryType

表示LLM中历史对话的存储类型。

名称	值	说明
kNone	0	不存储历史对话
kMemory	1	存储历史对话

Role

表示LLM的消息角色。

名称	值	说明
kUser	0	用户输入Prompt
kAssistant	1	LLM生成的输出
kSystem	2	系统Prompt
kTool	3	(Reserved)

StreamStatus

表示LLM流式生成的运行状态。

名称	值	说明
kRunning	0	流式
kEnd	1	存储历史对话
kSensetive	2	触发敏感词
kError	3	回调函数返回了错误
kLanguageError	4	触发不支持的语言

MemoryType

表示LLM中历史对话的存储类型。

名称	值	说明
kNone	0	不存储历史对话
kMemory	1	存储历史对话

3 函数接口

SmartLLMCreate

Error SmartLLMCreate(
    const char *model_path, 
    MemoryType mem_type,
    smart_handle_t *handle);

创建SmartLLM Handle

参数：

名称	类型	方向	描述
model_path	const char *	in	模型文件路径
mem_type	MemoryType	in	历史记录类型
handle	smart_handle_t ∗	out	创建的SmartLLM Handle

返回值：

成功返回kSuccess，失败详见第2节Error错误列表。

SmartLLMDestroy

SMART_C_API Error SmartLLMDestroy(smart_handle_t handle);

销毁SmartLLM Handle

参数：

名称	类型	方向	描述
handle	smart_handle_t	in	SmartLLM Handle

返回值：

成功返回kSuccess，失败详见第2节Error错误列表。

SmartLLMAddLicense

SMART_C_API Error SmartLLMAddLicense(
    const char* license_path
#if __ANDROID__
    , JNIEnv *env
    , jobject ctx
#endif // __ANDROID__
    );

添加License文件。

参数：

名称	类型	方向	描述
license_path	const char *	in	要销毁的文件信息数组，由SmartLLMListDocument返回。
env	JNIEnv *	in	(仅Android平台) Java JNI接口的JNIEnv对象指针。
ctx	jobject	in	(仅Android平台) android.Content.Context对象实例。

返回值：

成功返回kSuccess，失败详见1.2节Error错误列表

SmartLLMSetParams

SMART_C_API 
Error SmartLLMSetParams(
    smart_handle_t handle, 
    const void *params);

设置LLM参数。

参数：

名称	类型	方向	描述
handle	smart_handle_t	in	SmartLLM Handle
params	const void *	in	模型参数，根据不同的模型而不同。例如，可传入 ModelParams

返回值：

成功返回kSuccess，失败详见第2节Error错误列表。

SmartLLMSetMemoryType

SMART_C_API 
Error SmartLLMSetMemoryType(
    smart_handle_t handle, 
    MemoryType mem_type);

设置历史记录存储类型

参数：

名称	类型	方向	描述
handle	smart_handle_t	in	SmartLLM Handle
mem_type	MemoryType	in	历史记录类型

返回值：

成功返回kSuccess，失败详见第2节Error错误列表。

SmartLLMComplete

SMART_C_API 
Error SmartLLMComplete(
    smart_handle_t handle, 
    const char *prompt, 
    const char **stops,
    int stops_num, char **output);

使用LLM补全输入。

参数：

名称	类型	方向	描述
handle	smart_handle_t	in	SmartLLM Handle
prompt	const char*	in	输入的Prompt
stops	const char**	in	停止词列表，一个字符串数组
stop_num	int	in	停止词列表长度
output	char**	out	返回补全输出内容指针，需要调用SmartLLMReleaseCompleteOutput释放。

返回值：

成功返回kSuccess，失败详见第2节Error错误列表。

SmartLLMChat

SMART_C_API 
Error SmartLLMChat(
    smart_handle_t handle, 
    const CMessage *messages, 
    int messages_num,
    const char **stops, 
    int stops_num, 
    CMessage *output);

使用LLM进行非流式对话。

参数：

名称	类型	方向	描述
handle	smart_handle_t	in	SmartLLM Handle
messages	const CMessage*	in	输入的消息数组
message_num	int	in	输入的消息数组长度
stops	const char **	in	停止词列表，一个字符串数组
stops_num	int	in	停止词列表长度
output	CMessage *	out	LLM输出的消息，需要调用SmartLLMReleaseChatOutput释放内存

返回值：

成功返回kSuccess，失败详见1.2节Error错误列表

SmartLLMStreamComplete

SMART_C_API 
Error SmartLLMStreamComplete(
    smart_handle_t handle, 
    const char *prompt,
    const char **stops, int stops_num,
    CStreamCompleteCallback callback, 
    void *user_data);

使用LLM流式补全输入。

参数：

名称	类型	方向	描述
handle	smart_handle_t	in	SmartLLM Handle
prompt	const char*	in	输入的Prompt
stops	const char**	in	停止词列表，一个字符串数组
stop_num	int	in	停止词列表长度
callback	CStreamChatCallback	in	回调函数，在每一个Token生成时调用。
user_data	void *	in	任意内容，转发给回调函数。

返回值：

成功返回kSuccess，失败详见第2节Error错误列表。

SmartLLMStreamChat

SMART_C_API 
Error SmartLLMStreamChat(
    smart_handle_t handle, 
    const CMessage *messages,
    int messages_num, 
    const char **stops, 
    int stops_num,      
    CStreamChatCallback callback, 
    void *user_data);

使用LLM进行流式对话。

参数：

名称	类型	方向	描述
handle	smart_handle_t	in	SmartLLM Handle
messages	const CMessage*	in	输入的消息数组
message_num	int	in	输入的消息数组长度
stops	const char **	in	停止词列表，一个字符串数组
stops_num	int	in	停止词列表长度
callback	CStreamChatCallback	in	回调函数，在每一个Token生成时调用。
user_data	void *	in	任意内容，转发给回调函数。

返回值：

成功返回kSuccess，失败详见1.2节Error错误列表

SmartLLMReleaseCompleteOutput

SMART_C_API Error SmartLLMReleaseCompleteOutput(char *output);

销毁SmartLLMComplete接口的输出字符串。

参数：

名称	类型	方向	描述
output	char *	in	SmartLLMComplete接口的输出字符串

返回值：

成功返回kSuccess，失败详见1.2节Error错误列表

SmartLLMReleaseChatOutput

SMART_C_API Error SmartLLMReleaseChatOutput(CMessage *output);

销毁SmartLLMChat接口的输出消息。

参数：

名称	类型	方向	描述
output	CMessage *	in	SmartLLMComplete接口的输出消息。

返回值：

成功返回kSuccess，失败详见1.2节Error错误列表

SmartLLMGetRuntimeStats

SMART_API

SMART_API 
Error SmartLLMGetRuntimeStats(
    smart_handle_t handle, 
    LLMRuntimeStats *runtime_stats);

获取SmartLLM上一轮的运行时状态统计。

参数：

名称	类型	方向	描述
handle	smart_handle_t	in	SmartLLM Handle
runtime_stats	LLMRuntimeStats *	out	运行时状态统计结果

返回值：

成功返回kSuccess，失败详见1.2节Error错误列表

SmartLLMClearMemory

SMART_C_API Error SmartLLMClearMemory(smart_handle_t handle);

清除历史对话。

参数：

名称	类型	方向	描述
handle	smart_handle_t	in	SmartLLM Handle

返回值：

成功返回kSuccess，失败详见1.2节Error错误列表

4 调用示例代码

#include <string.h>
#include <stdio.h>

#include "core/common.h"
#include "smart_llm.h"
#include "smart_llm_common.h"

int CompleteCallback(StreamStatus status, const char *output, void *user_data) {
  printf("status is %d, output is %s\n", status, output);
  return 0;
}

int ChatCallback(StreamStatus status, const CMessage *output, void *user_data) {
  printf("status is %d, message.role is %d, message.content is %s\n", status, output->role,
         output->content);

  return 0;
}

void PrintRuntimeStats(LLMRuntimeStats &runtime_stats) {
  printf(
      "Runtime stats is:\n"
      "  prefill_toks_per_sec %.1f\n"
      "  decode_toks_per_sec %.1f\n"
      "  prefill_time_last_round %.1f\n"
      "  percentage_of_terminal_toks %.1f\n"
      "  historical_rounds %d\n",
      runtime_stats.prefill_toks_per_sec, runtime_stats.decode_toks_per_sec,
      runtime_stats.prefill_time_last_round, runtime_stats.percentage_of_terminal_toks,
      runtime_stats.historical_rounds);
}

int main(int argc, char **argv) {
  if (argc != 3) {
    printf("Using: %s license_file model_file\n", argv[0]);
    return -1;
  }

  Error err;
#if __ANDROID__
  err = SmartLLMAddLicense(argv[1], nullptr, nullptr);
#else
  err = SmartLLMAddLicense(argv[1]);
#endif // __ANDROID__
  if (kSuccess != err) {
    return -1;
  }

  smart_handle_t smart_handle;

  err = SmartLLMCreate(argv[2], kMemory, &smart_handle);
  if (kSuccess != err) {
    printf("SmartLLMCreate failed with %d\n", err);
    return -1;
  }
  printf("SmartLLMCreate done\n");

  ModelParameters terminal_params;
  terminal_params.max_new_tokens = 1024;
  terminal_params.repetition_penalty = 1.2f;
  terminal_params.temperature = 0.1f;
  terminal_params.top_p = 0.8f;

  err = SmartLLMSetParams(smart_handle, &terminal_params);
  if (kSuccess != err) {
    printf("SmartLLMSetParams failed with %d\n", err);
    return -1;
  }
  printf("SmartLLMSetParams done\n");


  err = SmartLLMSetMemoryType(smart_handle, kMemory);
  if (kSuccess != err) {
    printf("SmartLLMSetMemoryType failed with %d\n", err);
    return -1;
  }
  printf("SmartLLMSetMemoryType done\n");

  const char *stops[1] = {"aaa"};
  const int stops_num = 1;

  CMessage chat_in;
  const int messages_num = 1;
  chat_in.role = kUser;
  chat_in.content = "你好";

  CMessage chat_out;
  err = SmartLLMChat(smart_handle, &chat_in, messages_num, stops, stops_num, &chat_out);
  printf("chat done, ret is %d, role is %d, content is %s\n", err, chat_out.role, chat_out.content);

  err = SmartLLMReleaseChatOutput(&chat_out);
  if (kSuccess != err) {
    printf("SmartLLMReleaseChatOutput failed with %d\n", err);
    return -1;
  }

  LLMRuntimeStats runtime_stats;
  err = SmartLLMGetRuntimeStats(smart_handle, &runtime_stats);
  if (kSuccess != err) {
    printf("SmartLLMGetRuntimeStats failed with %d\n", err);
    return -1;
  }
  PrintRuntimeStats(runtime_stats);

  void *userdata;
  err = SmartLLMStreamChat(smart_handle, &chat_in, messages_num, stops, stops_num, ChatCallback,
                           userdata);
  printf("SmartLLMStreamChat done, ret is %d\n", err);

  err = SmartLLMGetRuntimeStats(smart_handle, &runtime_stats);
  if (kSuccess != err) {
    printf("SmartLLMGetRuntimeStats failed with %d\n", err);
    return -1;
  }
  PrintRuntimeStats(runtime_stats);

  err = SmartLLMClearMemory(smart_handle);
  if (kSuccess != err) {
    printf("SmartLLMClearMemory failed with %d\n", err);
    return -1;
  }
  printf("SmartLLMClearMemory done\n");

  err = SmartLLMDestory(smart_handle);
  if (kSuccess != err) {
    printf("SmartLLMDestory failed with %d\n", err);
    return -1;
  }

  printf("process done\n");

  return 0;
}

离线版本SDK文档

1 结构体（structs）和类型别名（typedefs）说明​

CMessage​

ModelParameters​

LLMRuntimeStats​

smart_handle_t​

CStreamCompleteCallback​

CStreamChatCallback​

2 枚举（enums）​

Error​

MemoryType​

Role​

StreamStatus​

MemoryType​

3 函数接口​

SmartLLMCreate​

SmartLLMDestroy​

SmartLLMAddLicense​

SmartLLMSetParams​

SmartLLMSetMemoryType​

SmartLLMComplete​

SmartLLMChat​

SmartLLMStreamComplete​

SmartLLMStreamChat​

SmartLLMReleaseCompleteOutput​

SmartLLMReleaseChatOutput​

SmartLLMGetRuntimeStats​

SmartLLMClearMemory​

4 调用示例代码​

1 结构体（structs）和类型别名（typedefs）说明

CMessage

ModelParameters

LLMRuntimeStats

smart_handle_t

CStreamCompleteCallback

CStreamChatCallback

2 枚举（enums）

Error

MemoryType

Role

StreamStatus

MemoryType

3 函数接口

SmartLLMCreate

SmartLLMDestroy

SmartLLMAddLicense

SmartLLMSetParams

SmartLLMSetMemoryType

SmartLLMComplete

SmartLLMChat

SmartLLMStreamComplete

SmartLLMStreamChat

SmartLLMReleaseCompleteOutput

SmartLLMReleaseChatOutput

SmartLLMGetRuntimeStats

SmartLLMClearMemory

4 调用示例代码