在线版本SDK文档

SenseChatLiteSDK API文档

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

SenseTime

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

CMessage

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

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

ModelParameters

LLM的模型参数

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

SensenovaParams

LLM的模型参数

类型	成员名称	说明
char *	authorization	Sensenova API Authorization
char *	model_name	Sensenova模型名称
ModelParameters	model_params	模型参数
int	stream	是否使用流式接口
int	web_search_enable	是否启用在线检索

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，用于调用各个接口。

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 函数接口

SmartCloudLLMCreate

SMART_C_API 
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错误列表。

SmartCloudLLMDestroy

SMART_C_API Error SmartCloudLLMDestroy(smart_handle_t handle);

销毁SmartLLM Handle

参数：

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

返回值：

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

SmartCloudLLMAddLicense

SMART_C_API Error SmartCloudLLMAddLicense(  
    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，失败详见第2节Error错误列表

SmartCloudLLMSetSensenovaParams

SMART_C_API
Error SmartCloudLLMSetSensenovaParams(
    smart_handle_t handle,
    const SensenovaParams *sensenova_params);

设置Sensenova云端LLM参数。

参数：

名称	类型	方向	描述
handle	smart_handle_t	in	SmartLLM Handle
Sensenova_params	const SensenovaParams*	in	Sensenova云端LLM参数

返回值：

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

SmartCloudLLMSetMemoryType

SMART_C_API
Error SmartCloudLLMSetMemoryType(
    smart_handle_t handle,
    MemoryType mem_type);

设置历史记录存储类型

参数：

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

返回值：

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

SmartCloudLLMChat

SMART_C_API 
Error SmartCloudLLMChat(
    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，失败详见第2节Error错误列表

SmartCloudLLMStreamChat

SMART_C_API 
Error SmartCloudLLMStreamChat(
    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，失败详见第2节Error错误列表

SmartCloudLLMReleaseChatOutput

SMART_C_API Error SmartCloudLLMReleaseChatOutput(CMessage *output);

销毁SmartLLMChat接口的输出消息。

参数：

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

返回值：

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

SmartCloudLLMGetRuntimeStats

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

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

参数：

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

返回值：

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

SmartCloudLLMClearMemory

SMART_C_API Error SmartCloudLLMClearMemory(smart_handle_t handle);

清除历史对话。

参数：

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

返回值：

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

4 调用示例代码

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

#include "core/common.h"
#include "smart_cloud_llm.h"
#include "smart_cloud_llm_common.h"

#if __ANDROID__
#define SmartCloudLLMAddLicense(a) SmartCloudLLMAddLicense(a, nullptr, nullptr)
#else
#define SmartCloudLLMAddLicense(a) SmartCloudLLMAddLicense(a)
#endif

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 != 2) {
    printf("Using: %s license_file\n", argv[0]);
    return -1;
  }

  if (kSuccess != SmartCloudLLMAddLicense(argv[1])) {
    return -1;
  }

  smart_handle_t smart_handle;

  Error err = SmartCloudLLMCreate(kMemory, &smart_handle);
  if (kSuccess != err) {
    printf("SmartCloudLLMCreate failed with %d\n", err);
    return -1;
  }
  printf("SmartCloudLLMCreate 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;

  SensenovaParams nova_params;
  nova_params.authorization = ""; // edit to your nova authorization
  nova_params.model_name = ""; // edit to your nova model_name
  nova_params.model_params = terminal_params;
  nova_params.stream = 1;
  nova_params.web_search_enable = 1;

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

  err = SmartCloudLLMSetMemoryType(smart_handle, kMemory);
  if (kSuccess != err) {
    printf("SmartCloudLLMSetMemoryType failed with %d\n", err);
    return -1;
  }
  printf("SmartCloudLLMSetMemoryType 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 = SmartCloudLLMChat(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 = SmartCloudLLMReleaseChatOutput(&chat_out);
  if (kSuccess != err) {
    printf("SmartCloudLLMReleaseChatOutput failed with %d\n", err);
    return -1;
  }

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

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

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

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

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

  printf("process done\n");

  return 0;
}

在线版本SDK文档

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

CMessage​

ModelParameters​

SensenovaParams​

LLMRuntimeStats​

smart_handle_t​

CStreamChatCallback​

2 枚举（enums）​

Error​

MemoryType​

Role​

StreamStatus​

MemoryType​

3 函数接口​

SmartCloudLLMCreate​

SmartCloudLLMDestroy​

SmartCloudLLMAddLicense​

SmartCloudLLMSetSensenovaParams​

SmartCloudLLMSetMemoryType​

SmartCloudLLMChat​

SmartCloudLLMStreamChat​

SmartCloudLLMReleaseChatOutput​

SmartCloudLLMGetRuntimeStats​

SmartCloudLLMClearMemory​

4 调用示例代码​

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

CMessage

ModelParameters

SensenovaParams

LLMRuntimeStats

smart_handle_t

CStreamChatCallback

2 枚举（enums）

Error

MemoryType

Role

StreamStatus

MemoryType

3 函数接口

SmartCloudLLMCreate

SmartCloudLLMDestroy

SmartCloudLLMAddLicense

SmartCloudLLMSetSensenovaParams

SmartCloudLLMSetMemoryType

SmartCloudLLMChat

SmartCloudLLMStreamChat

SmartCloudLLMReleaseChatOutput

SmartCloudLLMGetRuntimeStats

SmartCloudLLMClearMemory

4 调用示例代码