跳到主要内容

Web SDK 调用

通过 @cloudbase/js-sdk 在 Web 应用中调用 CloudBase AI 大模型，支持文本生成、流式输出、图生文等能力。

安装​

npm install @cloudbase/js-sdk

初始化​

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "<YOUR_ENV_ID>",
  accessKey: "<YOUR_PUBLISHABLE_KEY>"  // 从控制台获取
});

// 获取 AI 实例
const ai = app.ai();

Publishable Key 获取地址：CloudBase 控制台 → 环境配置 → API Key

文本生成​

generateText() - 非流式​

一次性返回完整结果。

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

const result = await model.generateText({
  model: "hunyuan-turbos-latest",
  messages: [{ role: "user", content: "介绍一下李白" }],
});

console.log(result.text);     // 生成的文本
console.log(result.usage);    // Token 使用量
console.log(result.messages); // 完整消息历史

返回值​

属性类型说明
textstring生成的文本
messagesChatModelMessage[]完整消息历史
usageUsageToken 使用量
rawResponsesunknown[]原始模型响应
errorunknown错误信息（如有）

streamText() - 流式​

流式返回文本，适用于实时对话场景。

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

const res = await model.streamText({
  model: "hunyuan-turbos-latest",
  messages: [{ role: "user", content: "介绍一下李白" }],
});

// 方式一：迭代文本流（推荐）
for await (const text of res.textStream) {
  console.log(text);  // 增量文本
}

// 方式二：迭代数据流，获取完整响应数据
for await (const data of res.dataStream) {
  console.log(data);  // 包含 choices、usage 等完整信息
}

// 获取最终结果
const messages = await res.messages;
const usage = await res.usage;

返回值​

属性类型说明
textStreamAsyncIterable<string>增量文本流
dataStreamAsyncIterable<DataChunk>完整数据流
messagesPromise<ChatModelMessage[]>最终消息历史
usagePromise<Usage>最终 Token 使用量

图生文（视觉理解）​

使用支持视觉的模型（如 hunyuan-vision）理解图片内容。

提示

需要先配置自定义模型 hunyuan-custom，填写混元大模型的 BaseURL 和 API Key。

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

const res = await model.streamText({
  model: "hunyuan-vision",
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "这张图片的内容是什么？" },
        {
          type: "image_url",
          image_url: {
            url: "https://example.com/image.png"
          }
        }
      ]
    }
  ]
});

for await (const text of res.textStream) {
  console.log(text);
}

消息内容格式​

当使用图生文时，content 为数组格式：

文本内容：

interface TextContent {
  type: "text";
  text: string;
}

图片内容：

interface ImageContent {
  type: "image_url";
  image_url: {
    url: string;  // 图片 URL
  };
}

文生图​

注意

图片生成功能仅在 Node SDK 中可用，Web SDK 暂不支持。如需在 Web 应用中使用，请通过云函数调用。详见 Node SDK 调用 - 图片生成。

完整示例​

聊天应用​

import cloudbase from "@cloudbase/js-sdk";

const app = cloudbase.init({
  env: "<YOUR_ENV_ID>",
  accessKey: "<YOUR_PUBLISHABLE_KEY>"
});

async function chat(userInput, history = []) {
  const auth = app.auth();
  await auth.signInAnonymously();

  const ai = app.ai();
  const model = ai.createModel("hunyuan-exp");

  const messages = [
    ...history,
    { role: "user", content: userInput }
  ];

  const res = await model.streamText({
    model: "hunyuan-turbos-latest",
    messages
  });

  let fullText = "";
  for await (const text of res.textStream) {
    fullText += text;
    // 更新 UI
    document.getElementById("output").textContent = fullText;
  }

  return fullText;
}

类型定义​

BaseChatModelInput​

interface BaseChatModelInput {
  model: string;                      // 模型名称
  messages: ChatModelMessage[];       // 消息列表
  temperature?: number;               // 采样温度
  topP?: number;                      // 核采样
}

type ChatModelMessage =
  | { role: "user"; content: string | ContentPart[] }
  | { role: "system"; content: string }
  | { role: "assistant"; content: string };

Usage​

interface Usage {
  prompt_tokens: number;
  completion_tokens: number;
  total_tokens: number;
}

相关文档​