xiruilink-llm 使用说明

author: li xingyuan

latest-time: 2024-05-17

xiruilink-llm，封装了对大模型调用的相关代码。功能包将对外暴露的功能函数统一封装成为了class，并使用了单例模式对class进行管理，保证在大模型流式生成的生产环境下的行为一致性，对各种可能出现的问题进行的预防。

下面介绍如何使用XiruiModel api

0 安装和引入

目前，XiruiModel通过NPM包的形式对外暴露，通过：

npm install xiruilink-llm

获取最新的NPM包。

然后，在项目中，使用：

import XiruiModel from 'xiruilink-llm'

即可将class引入需要使用的地方。

1.初始化和销毁实例

XiruiModel使用单例模式，在使用前需要对实例进行初始化。

使用下述代码，即可初始化一个XiruiModel实例。

new XiruiModel({
  app_id: '',
  app_secret: '',
  app_key: ''
})

其中：

// 应用ID
app_id

// 应用公钥
app_secret

// 应用私钥
app_key

XiruiModel api默认设置了若干属性，如果您有需要，可以根据需求，在初始化的同时传入对应字段，修改默认配置。

// 可选输入

//是否启用历史问题关联，开启后将携带历史提问一同发出请求。注意，该功能将额外消耗大量的tokens.
use_history: false | true,

// 历史栈长度，无论是否开启use_history，历史栈都会记录提问，历史栈默认长度为20。注意，该值只能为大于1的偶数.
history_length: num

// 请求地址，输入为一个ws(s)协议的地址
request_url: ws(s)://url

// 是否输出LOG
show_log: true | false

// 指定底层socket类型。 默认为空，即不指定类型
socket_type: '' | 'h5' | 'uniapp'

// 单次回答tokens限制
tokens_limit： 32 <= num <= 2048

// 是否启用稳流器，默认开启，平缓输出
use_retarder: true || false

// 稳流器输出时间步长
retarder_step: 50

// 容错配置, 由于星火大模型做了严格限制，domain字段必须符合一定格式，为了确保模型调通，设置了此配置，一般无需处理
general: 'generalv3'

// 是否输出原始数据
output_origin: true | false

// url函数
url_method: funciton

// url函数发生错误的回调
onurlError: function

其中，socket_type 属性的相关逻辑较为复杂，将在 [第四节] 进行详细说明。

下面是一份完整的配置，您可以直接复制使用：

const setting = {
  // 必备信息
  app_id: '', app_key: '', app_secret: '',
  // 是否启用历史记录
  use_history: true,
  // 历史队列长度
  history_length: 20,
  // 请求地址
  request_url: 'wss://spark-api.xf-yun.com/v3.1/chat',
  // 是否显示log信息
  show_log: true,
  // 使用哪一种socket： h5 uniapp 两种可选, 默认为空，根据环境自动选择
  socket_type: '',
  // 单次回答最大token用量
  tokens_limit: 30,
  // 启用缓流器, 优化输出效果
  use_retarder: true,
  // 缓流器步长，开启环流器后才生效
  retarder_step: 30,
  // 模板函数，调试用，无需处理
  prompt: function,
}

初始化后，您可以接收和保存new方法后返回的实例对象来使用该实例。或者，通过下面方法在任意地方获取该实例。

XiruiModel.getInstance()

警告：在调用该方法前，您必须保证实例已经被初始化。否则，将会抛出错误：

[xiruilink-llm]: instance are not initialized.

注意，您只需要初始化一次实例即可。如果重复初始化，旧的实例将会被释放，同时会在控制台输出警告。

[xiruilink-llm]: existing instance has been rebuild.

如果您想要释放实例，调用下述静态方法即可：

XiruiModel.destroy()

此外，关于历史栈， 历史栈会自动记录用户提问和大模型生成的回答，但如果大模型生成失败，那么本次用户的提问也将不会被记录。

2.发送请求和接收数据

XiruiModel对外暴露了 sendToServer() 方法来对服务器发送请求，具体的参数如下。

XiruiModel.sendToServer(
  // 必要输入
  target,
  // 可选
  callback,
  // 可选
  endback
)

其中，target为一个对象，当前包括两个字段：

{
  // 问题内容
  content,
  // 用户ID（非必要）
  uuid
}

而 callback 和 endback 是function，传入将会进行校验，如果为非函数类型，将会抛出错误：

[xiruilink-llm]: callback or endback is not a function.

callback 将会在大模型回答生成过程中被 连续调用 ，并传入Text对象。

{
  // 状态码，成功为0
  code: 0,
  // 生成内容。单次返回内容不完整，需要自行进行拼接
  content: '',
  // 角色，固定为assistant
  role:"assistant",
  // 队列号
  seq:'',
  // 指示码，0 生成开始，1 生成中，2 生成结束
  status:0
}

endback为生成结束后的回调，只会调用一次。endback会接受一个对象，包含：

{
  // 状态码, 成功为0
  code: 0,
  // WebSocket结束事件
  event,
  // 生成的完整回答
  full_text,
  // 提示信息
  message,
  // token用量
  usage
}

下面是vue中的一个示例：

XiruiModel.sendToServer(
  {
    content: this.postMessage,
    uuid: 'test'
  },
  this.handleAnswerStream,
  this.handleAnswerStreamOver
)
.then(res => {
  // do something
})
.catch(err => {
  // do something
})

handleAnswerStream(t) {
  console.log(t)
}

handleAnswerStreamOver(t) {
  console.log(t)
}

通过上面的示例，您可以注意到，sendToServer() 方法可以使用 then() 方法。

为了更方便开发人员处理业务，我们对核心方法 sendToServer() 进行了 Promise 对象的包装。该方法实际将返回一个Promise对象，并在对象内部对 resolve 和 reject 进行了处理。所以， sendToServer() 允许您不传入回调函数，使用 then() 和 catch() 方法来处理业务和异常。

在大模型场景下，模型生成回答需要消耗较多算力，在多用户场景下，无法快速为用户生成完整回答。因此，更建议您使用 callback 流式处理数据，减少用户等待时间，优化用户体验。使用 then() 方法返回的全量回答进行后续的处理将会是更好的选择。

需要注意，callback 和 endback 调用的时机均在 Promise 对象 resolve 或 reject 之前。

3.其他功能函数

除了核心的 sendToServer() 方法，XiruiModel还提供了若干功能函数来辅助处理业务。

• terminate() 该方法将会中断生成.
• getHistory() 该方法将会返回XiruiModel记录的历史回答.
• clearHistory() 该方法将会清空XiruiModel保存的历史栈.
• setHistory(t) t 为array, 该方法将会用传入的 array 覆盖原有的历史栈。如果超出历史栈设置的长度，将会从尾部截取长度内的数组元素。需要用户保证数组中元素格式正确, 否则将会抛出错误。
• setProperties(t) t 为array, 该方法将传入的属性数组批量应用到现有实例中。该方法 不会 造成实例的释放。用户需保证 参数类型 正确，否则会抛出警告，同时类型错误的属性将会设置失败。

下面为上述方法的几个示例：

// 停止生成
shutDown() {
  XiruiModel.terminate()
}


// 用户更改配置
save(settings = {}) {
  const {
    use_history = false,
    tokens_limit = 128
  } = settings

  XiruiModel.setProperties([
    { key: 'use_history', value: use_history },
    { key: 'tokens_limit', value: tokens_limit }
  ])
}

// 用户更改对话窗口
changeChatWindow(chatList) {
  // expect
  chatList = [
    ...
    {role: 'assitant', content: ''},
    {role: 'user', content: ''},
    {role: 'assitant', content: ''},
    {role: 'user', content: ''},
    ...
  ]
  //

  XiruiModel.setHistory(chatList)
}

XiruiModel 对方法的调用均提供了两种方式：

// 静态方法方式
XiruiModel.XXX()

// 实例方式
let XiruiModel = XiruiModel.getInstance()
XiruiModel.XXX()

我们更推荐您使用静态的方式进行调用，更简洁且更高效。

4. 对UNIAPP的支持

移动应用端，UNIAPP当前得到了较为广泛的应用，我们也追加了对UNIAPP的支持。

但是，对于WebSocket的使用，Web端和APP端存在差异。对于本JS包，Web端调用的是window对象中的WebSocket，来实现核心功能。

但在UNIAPP的移动端环境中，UNIAPP官方对WebSocket做了单独的封装，并不支持H5原生的WebSocket。并且，封装后，调用方式等都和Web端产生了较大差异。

在这种情况下，为了抹平差异，本JS包对uniapp的websocket进行了二次封装。经过封装，保证本JS包对外暴露的能力在 H5端 和 uniapp APP端 的使用上保持完全一致。于此同时，本JS包对底层调用的差异化处理对使用者完全透明，使用者只需专注于业务逻辑即可。

默认情况下，程序会按照顺序，匹配当前环境可用的WebSocket对象，顺序为 H5原生 > uniapp封装 ， 即优先使用h5，如果您有需要，也可以在初始化实例的时候，通过 socket_type 来指定您要使用的WebSocket类型。

更新日志

2.0.4

optimized: 优化角色模板

2.0.3

add: 新增url函数相关逻辑. optimized: 优化错误处理

2.0.2

add: 开放模板自定义.

2.0.1

change: 修改底层设计和结构，极大优化中断函数效果. add: 新增若干功能.

1.8.0

optimized: 优化一些问题

1.7.5

fixed：微信小程序正式环境调用问题

1.7.4

fixed: 修复中断方法BUG

1.7.3

fixed: 修复多环境支持bug

1.7.2

替换btoa函数，提供多环境支持

1.7.1

fixed: FULL_TEXT输出为空的问题

1.7.0

支持多版本调用

1.6.1

追加对错误的展示，现在会把错误数据返回

1.6.0

追加配置，支持原始数据输出

1.5.3

追加对格式化输出的支持

1.5.2

优化稳流器输出

1.5.1

1. 新增补偿机制 fixed: 模型配置设置

1.5.0

1. 补充稳流器支持
2. 优化实例配置方式

1.4.6

追加最大tokens限制校验 fixed: uni-socket close()方法缺失的问题

1.4.5

更新文档

1.4.4

优化输出

1.4.3

补充属性设置功能 补充历史栈设置功能

1.4.2

优化WS建立逻辑 [test] 追加若干属性设置选项

1.4.1

完成对UNI-APP websocket 的统一封装和支持

1.3.4

[test] 修复若干bug

1.3.3

[test] 新增接口支持

1.3.2

[test] 追加对uni-app的支持

1.3.1

更新文档

1.2.3

优化错误信息输出逻辑

1.2.2

优化初始化实例的相关代码逻辑

1.2.1

函数回调和返回值将会同时返回操作code码

1.2.0

新增停止生成功能函数

1.1.5

优化log逻辑

fixed: 状态码为零不能赋值问题

1.1.4

1.新增返回信息追加status状态

2.fixed：isConnedted函数不能正常指示连接状态

1.1.3

追加错误返回信息提示

1.1.2

fixed：队列不能按照限定长度运行

1.1.1

补充history length校验相关逻辑

1.1.0

新增查询历史栈相关功能