AI SDK

初始化 SDK

初始化方法请参考初始化 SDK。

app.ai

初始化后，可以使用挂载至 cloudbase 实例上的 ai 方法创建 AI 实例，用于后续模型创建。

使用示例

app = cloudbase.init({ env: "your-env" });
const ai = await app.ai();

类型声明

function ai(options?: AIInitOption): Promise<AI>;

参数

参数名	必填	类型	示例	说明
options	否	AIInitOption	{ env: "my-env" }	AI 初始化参数，大多数场景下不用传递。该参数传递的数据 SDK 都会自动获取，在特殊场景可按需传递覆盖。

返回值

Promise<AI>

返回新创建的 AI 实例。

AI

用于创建 AI 模型的类。

createModel()

创建指定的 AI 模型。

使用示例

const model = ai.createModel("hunyuan");

类型声明

function createModel(model: string): ChatModel;

返回一个实现了 ChatModel 抽象类的模型实例，该实例提供 AI 生成文本相关能力。

bot

挂载了 Bot 类的实例，上面集合了一系列与 Agent 交互的方法。具体可参考 Bot 类 的详细文档。

使用示例

const agentList = await ai.bot.list({ pageNumber: 1, pageSize: 10 });

ChatModel

这个抽象类描述了 AI 生文模型类提供的接口。

generateText()

调用大模型生成文本。

使用示例

const hy = ai.createModel("hunyuan"); // 创建模型
const res = await hy.generateText({
  model: "hunyuan-lite",
  messages: [{ role: "user", content: "你好，请你介绍一下李白" }],
});
console.log(res.text); // 打印生成的文本

类型声明

function generateText(data: BaseChatModelInput): Promise<{
  rawResponses: Array<unknown>;
  text: string;
  messages: Array<ChatModelMessage>;
  usage: Usage;
  error?: unknown;
}>;

参数

参数名	必填	类型	示例	说明
data	是	BaseChatModelInput	{model: "hunyuan-lite", messages: [{ role: "user", content: "你好，请你介绍一下李白" }]}	参数类型定义为 BaseChatModelInput ，作为基础的入参定义。实际上各家大模型还会有各自独特的输入参数，开发者可按需根据实际使用的大模型官方文档传入其他不在此类型中被定义的参数，充分利用大模型提供的能力。其他参数会被透传至大模型接口， SDK 侧不对它们不做额外处理。

返回值

属性名	类型	示例	说明
res.text	string	"李白是一位唐朝诗人。"	大模型生成的文本。
res.rawResponses	unknown[]	[{"choices": [{"finish_reason": "stop","message": {"role": "assistant", "content": "你好呀，有什么我可以帮忙的吗？"}}], "usage": {"prompt_tokens": 14, "completion_tokens": 9, "total_tokens": 23}}]	大模型的完整返回值，包含更多详细数据，如消息创建时间等等。由于各家大模型返回值互有出入，请根据实际情况使用。
res.messages	ChatModelMessage[]	[{role: 'user', content: '你好'},{role: 'assistant', content: '你好！很高兴与你交流。请问有什么我可以帮助你的吗？无论是关于生活、工作、学习还是其他方面的问题，我都会尽力为你提供帮助。'}]	本次调用的完整消息列表。
usage	Usage	{"completion_tokens":33,"prompt_tokens":3,"total_tokens":36}	本次调用消耗的 token。
error	unknown		调用过程中产生的错误。

streamText()

以流式调用大模型生成文本。流式调用时，生成的文本及其他响应数据会通过 SSE 返回，该接口的返回值对 SEE 做了不同程度的封装，开发者能根据实际需求获取到文本流和完整数据流。

使用示例

const hy = ai.createModel("hunyuan"); // 创建模型
const res = await hy.streamText({
  model: "hunyuan-lite",
  messages: [{ role: "user", content: "你好，请你介绍一下李白" }],
});

for await (let str of res.textStream) {
  console.log(str); // 打印生成的文本
}
for await (let data of res.dataStream) {
  console.log(data); // 打印每次返回的完整数据
}

类型声明

function streamText(data: BaseChatModelInput): Promise<StreamTextResult>;

参数

参数名	必填	类型	示例	说明
data	是	BaseChatModelInput	{model: "hunyuan-lite", messages: [{ role: "user", content: "你好，请你介绍一下李白" }]}	参数类型定义为 BaseChatModelInput ，作为基础的入参定义。实际上各家大模型还会有各自独特的输入参数，开发者可按需根据实际使用的大模型官方文档传入其他不在此类型中被定义的参数，充分利用大模型提供的能力。其他参数会被透传至大模型接口， SDK 侧不对它们不做额外处理。

返回值

StreamTextResult 属性名	类型	说明
textStream	ReadableStream<string>	以流式返回的大模型生成文本，可参考使用示例获取到生成的增量文本。
dataStream	ReadableStream<DataChunk>	以流式返回的大模型响应数据，可参考使用示例获取到生成的增量数据。由于各家大模型响应值互有出入，请根据实际情况合理使用。
messages	Promise<ChatModelMessage[]>	本次调用的完整消息列表。
usage	Promise<Usage>	本次调用消耗的 token。
error	unknown	本次调用产生的错误。

DataChunk 属性名	类型	说明
choices	Array<object>
choices[n].finish_reason	string	模型终止推断的原因。
choices[n].delta	ChatModelMessage	本次请求的消息。
usage	Usage	本次请求消耗的 token。
rawResponse	unknown	大模型返回的原始回复。

示例

const hy = ai.createModel("hunyuan");
const res = await hy.streamText({
  model: "hunyuan-lite",
  messages: [{ role: "user", content: "1+1结果是" }],
});

// 文本流
for await (let str of res.textStream) {
  console.log(str);
}
// 1
// 加
// 1
// 的结果
// 是
// 2
// 。

// 数据流
for await (let str of res.dataStream) {
  console.log(str);
}

// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}
// {created: 1723013866, id: "a95a54b5c5d2144eb700e60d0dfa5c98", model: "hunyuan-lite", version: "202404011000", choices: Array(1), …}

Bot

用于与 Agent 交互的类。

get()

获取某个 Agent 的信息。

使用示例

await ai.bot.get({ botId: "botId-xxx" });

类型声明

function get(props: { botId: string });

参数

参数名	必填	类型	说明
props.botId	是	string	要获取信息的 Agent 的 id

list()

批量获取多个 Agent 的信息。

使用示例

await ai.bot.list({
  pageNumber: 1,
  pageSize: 10,
  name: "",
  enable: true,
  information: "",
  introduction: "",
});

类型声明

function list(props: {
  name: string;
  introduction: string;
  information: string;
  enable: boolean;
  pageSize: number;
  pageNumber: number;
});

参数

参数名	必填	类型	说明
props.pageNumber	是	number	分页大小
props.pageSize	是	number	分页下标
props.enable	是	boolean	Agent 是否启用
props.name	是	string	Agent 名字，用于模糊查询
props.information	是	string	Agent 信息，用于模糊查询
props.introduction	是	string	Agent 简介，用于模糊查询

sendMessage()

与 Agent 进行对话。

使用示例

const res = await ai.bot.sendMessage({
  botId: "botId-xxx",
  history: [{ content: "你是李白。", role: "user" }],
  msg: "你好",
});
for await (let str of res.dataStream) {
  console.log(str);
}

类型声明

function sendMessage(props: {
  botId: string;
  msg: string;
  history: Array<{
    role: string;
    content: string;
  }>;
});

参数

参数名	必填	类型	说明
props.botId	是	number	Agent id
props.msg	是	number	此次对话要发送的消息
props.history	是	boolean	在此次对话前发生的聊天记录
props.history[n].role	是	string	本聊天信息的发送角色
props.history[n].content	是	string	本聊天信息的内容

getChatRecords()

获取聊天记录。

使用示例

await ai.bot.getChatRecords({
  botId: "botId-xxx",
  pageNumber: 1,
  pageSize: 10,
  sort: "asc",
});

类型声明

function getChatRecords(props: {
  botId: string;
  sort: string;
  pageSize: number;
  pageNumber: number;
});

参数

参数名	必填	类型	说明
props.botId	是	string	Agent id
props.sort	是	string	排序方式
props.pageSize	是	number	分页大小
props.pageNumber	是	number	分页下标

sendFeedback()

发送对某条聊天记录的反馈信息。

使用示例

const res = await ai.bot.sendFeedback({
  userFeedback: {
    botId: "botId-xxx",
    recordId: "recordId-xxx",
    comment: "非常棒",
    rating: 5,
    tags: ["优美"],
    aiAnswer: "落英缤纷",
    input: "来个成语",
    type: "upvote",
  },
});

类型声明

function sendFeedback(props: { userFeedback: IUserFeedback });

参数

参数名	必填	类型	说明
props.userFeedback	是	IUserFeedback	用户反馈，详见 IUserFeedback 类型定义
props.botId	是	string	将要获取聊天记录的 Agent 的 id
props.sort	是	string	排序方式
props.pageSize	是	number	分页大小
props.pageNumber	是	number	分页下标

getFeedBack()

获取已存在的反馈信息。

使用示例

const res = await ai.bot.getFeedBack({
  botId: "botId-xxx",
  from: 0,
  to: 0,
  maxRating: 4,
  minRating: 3,
  pageNumber: 1,
  pageSize: 10,
  sender: "user-a",
  senderFilter: "include",
  type: "upvote",
});

类型声明

function sendFeedback(props: {
  botId: string;
  type: string;
  sender: string;
  senderFilter: string;
  minRating: number;
  maxRating: number;
  from: number;
  to: number;
  pageSize: number;
  pageNumber: number;
});

参数

参数名	必填	类型	说明
props.botId	是	string	Agent id
props.type	是	string	用户反馈类型，点赞 upvote 点踩 downvote
props.sender	是	string	评论创建用户
props.senderFilter	是	string	评论创建用户过滤关系 include:包含 exclude:不包含 equal:等于 unequal:不等于 prefix:前缀
props.minRating	是	number	最低评分
props.maxRating	是	number	最高评分
props.from	是	number	开始时间戳
props.to	是	number	结束时间戳
props.pageSize	是	number	分页大小
props.pageNumber	是	number	分页下标

getRecommendQuestions()

获取推荐的问题。

使用示例

const res = ai.bot.getRecommendQuestions({
  botId: "botId-xxx",
  history: [{ content: "你是谁啊", role: "user" }],
  msg: "你好",
  agentSetting: "",
  introduction: "",
  name: "",
});

for await (let str of res.textStream) {
  console.log(str);
}

类型声明

function getRecommendQuestions(props: {
  botId: string;
  name: string;
  introduction: string;
  agentSetting: string;
  msg: string;
  history: Array<{
    role: string;
    content: string;
  }>;
});

参数

参数名	必填	类型	说明
props.botId	是	string	Agent id
props.name	是	string	Agent 名称
props.introduction	是	string	Agent 简介
props.agentSetting	是	string	Agent 设定
props.msg	是	string	用户发送信息
props.history	是	Array	历史对话信息
props.history[n].role	是	string	历史信息角色
props.history[n].content	是	string	历史信息内容

BaseChatModelInput

interface BaseChatModelInput {
  model: string
  messages: Array<ChatModelMessage>
  temperature?: number
  topP?: number
  tools?: Array<FunctionTool>
  toolChoice?: 'none' | 'auto' | 'custom'
  maxSteps?: number
  onStepFinish?: (prop: IOnStepFinish) => unknown
}

BaseChatModelInput 属性名	类型	说明
model	string	模型名称。
messages	Array<ChatModelMessage>	消息列表。
temperature	number	采样温度，控制输出的随机性。
topP	number	温度采样，即模型考虑概率质量为 top_p 的标记的结果。
tools	Array<FunctionTool>	大模型可用的工具列表。
toolChoice	string	指定大模型选择工具的方式。
maxSteps	number	请求大模型的最大次数。
onStepFinish	(prop: IOnStepFinish) => unknown	当对大模型的一次请求完成时，出发的回调函数。

BotInfo

interface BotInfo {
  botId: string;
  name: string;
  introduction: string;
  agentSetting: string;
  welcomeMessage: string;
  avatar: string;
  background: string;
  tags: Array<string>;
  isNeedRecommend: boolean;
  knowledgeBase: Array<string>;
  type: string;
  initQuestions: Array<string>;
  enable: true;
}

IUserFeedback

interface IUserFeedback {
  recordId: string;
  type: string;
  botId: string;
  comment: string;
  rating: number;
  tags: Array<string>;
  input: string;
  aiAnswer: string;
}

ChatModelMessage

type ChatModelMessage = UserMessage | SystemMessage | AssistantMessage | ToolMessage

UserMessage

type UserMessage = {
  role: 'user'
  content: string
}

SystemMessage

type SystemMessage = {
  role: 'system'
  content: string
}

AssistantMessage

type AssistantMessage = {
  role: 'assistant'
  content?: string
  tool_calls?: Array<ToolCall>
}

ToolMessage

type ToolMessage = {
  role: 'tool'
  tool_call_id: string
  content: string
}

ToolCall

export type ToolCall = {
  id: string
  type: string
  function: { name: string; arguments: string }
}

FunctionTool

工具定义类型。

type FunctionTool = {
  name: string
  description: string
  fn: CallableFunction
  parameters: object
}

FunctionTool 属性名	类型	说明
name	string	工具名称。
description	string	工具的描述。清楚的工具描述有助于大模型认识工具的通途。
fn	CallableFunction	工具的执行函数。当 AI SDK 解析出大模型的响应需要该工具调用时，会调用此函数，并将结果返回给大模型。
parameters	object	工具执行函数的入参。需要使用 JSON Schema 的格式定义入参。

IOnStepFinish

大模型响应后出发的回调函数的入参类型。

interface IOnStepFinish {
  messages: Array<ChatModelMessage>
  text?: string
  toolCall?: ToolCall
  toolResult?: unknown
  finishReason?: string
  stepUsage?: Usage
  totalUsage?: Usage
}

IOnStepFinish 属性名	类型	说明
messages	Array<ChatModelMessage>	到当前步骤为止所有的消息列表。
text	string	当前响应的文本。
toolCall	ToolCall	当前响应调用的工具。
toolResult	unknown	对应的工具调用结果。
finishReason	string	大模型推理结束的原因。
stepUsage	Usage	当前步骤所花费的 token。
totalUsage	Usage	到当前步骤为止所花费的总 token。

Usage

type Usage = {
  completion_tokens: number
  prompt_tokens: number
  total_tokens: number
}