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<{
  rawResponse: any;
  text: string;
}>;

参数

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

返回值

属性名	类型	示例	说明
res.text	string	"李白是一位唐朝诗人。"	大模型生成的文本。
res.rawResponse	object	{"choices": [{"finish_reason": "stop","message": {"role": "assistant", "content": "你好呀，有什么我可以帮忙的吗？"}}], "usage": {"prompt_tokens": 14, "completion_tokens": 9, "total_tokens": 23}}	大模型的完整返回值，包含更多详细数据，如 token 使用情况相关字段。由于各家大模型返回值互有出入，请根据实际情况使用。

streamText()

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

使用示例

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(str); // 打印每次返回的数据
}
for await (let event of res.eventSourceStream) {
  console.log(event); // 打印 SSE 数据
}

类型声明

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

参数

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

返回值

属性名	类型	说明
res.textStream	ReadableStream<string>	以流式返回的大模型生成文本，可参考使用示例获取到生成的增量文本。
res.dataStream	ReadableStream<object>	以流式返回的大模型响应数据，可参考使用示例获取到生成的增量数据。由于各家大模型响应值互有出入，请根据实际情况合理使用。
res.eventSourceStream	ReadableStream<object>	以流式返回的完整 SSE 数据，可参考使用示例获取到每个 SSE 响应。由于各家大模型响应值互有出入，请根据实际情况合理使用。

示例

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), …}

// SSE 流
for await (let str of res.eventSourceStream) {
  console.log(str);
}
// {type: "event", id: undefined, event: undefined, data: "{"created":1723013866,"id":"a95a54b5c5d2144eb700e6…okens":6,"completion_tokens":1,"total_tokens":7}}"}
// {type: "event", id: undefined, event: undefined, data: "{"created":1723013866,"id":"a95a54b5c5d2144eb700e6…okens":6,"completion_tokens":2,"total_tokens":8}}"}
// {type: "event", id: undefined, event: undefined, data: "{"created":1723013866,"id":"a95a54b5c5d2144eb700e6…okens":6,"completion_tokens":3,"total_tokens":9}}"}
// {type: "event", id: undefined, event: undefined, data: "{"created":1723013866,"id":"a95a54b5c5d2144eb700e6…kens":6,"completion_tokens":4,"total_tokens":10}}"}
// {type: "event", id: undefined, event: undefined, data: "{"created":1723013866,"id":"a95a54b5c5d2144eb700e6…kens":6,"completion_tokens":5,"total_tokens":11}}"}
// {type: "event", id: undefined, event: undefined, data: "{"created":1723013866,"id":"a95a54b5c5d2144eb700e6…kens":6,"completion_tokens":6,"total_tokens":12}}"}
// {type: "event", id: undefined, event: undefined, data: "{"created":1723013866,"id":"a95a54b5c5d2144eb700e6…kens":6,"completion_tokens":7,"total_tokens":13}}"}
// {type: "event", id: undefined, event: undefined, data: "{"created":1723013866,"id":"a95a54b5c5d2144eb700e6…kens":6,"completion_tokens":7,"total_tokens":13}}"}
// {type: "event", id: undefined, event: undefined, data: "[DONE]"}

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 {
  messages: {
    role: "user" | "system" | "assistant";
    content: string;
  }[];
  model: string;
  temperature?: number;
  top_p?: number;
}

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;
}