Skip to main content

Node SDK 调用

通过 @cloudbase/node-sdk 在 Node.js 服务端（如云函数、云托管）调用 CloudBase AI 大模型，支持文本生成、流式输出、图片生成等能力。

安装​

npm install @cloudbase/node-sdk
版本要求

Node SDK AI 功能需要 3.16.0 或更高版本。请检查版本：npm list @cloudbase/node-sdk

初始化​

云函数中使用​

const tcb = require("@cloudbase/node-sdk");
const app = tcb.init({ 
  env: "<YOUR_ENV_ID>",
  timeout: 60000 // AI 生成可能耗时较长，建议设置较长超时时间
});

exports.main = async (event, context) => {
  const ai = app.ai();
  // 使用 AI 功能
};

独立 Node.js 服务中使用​

const tcb = require("@cloudbase/node-sdk");

const app = tcb.init({
  env: "<YOUR_ENV_ID>",
  secretId: "<YOUR_SECRET_ID>",
  secretKey: "<YOUR_SECRET_KEY>",
  timeout: 60000 // 设置超时时间为 60 秒，AI 生成可能耗时较长
});

const ai = app.ai();

密钥获取地址：腾讯云 API 密钥管理

超时配置

AI 模型生成文本可能需要较长时间，建议将 timeout 设置为 60000（60 秒）或更高，避免请求超时。

文本生成​

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 使用量

图片生成​

仅 Node SDK 支持

图片生成功能仅在 Node SDK 中可用，Web SDK 和小程序均不支持。

const imageModel = ai.createImageModel("hunyuan-image");

const res = await imageModel.generateImage({
  model: "hunyuan-image",
  prompt: "一只可爱的猫咪在草地上玩耍",
  size: "1024x1024",
  version: "v1.9"
});

console.log(res.data[0].url);           // 图片 URL（24 小时有效）
console.log(res.data[0].revised_prompt); // 改写后的 prompt

图片生成参数​

参数类型必填说明
modelstring是模型名称，如 hunyuan-image
promptstring是图片描述
sizestring否图片尺寸，默认 1024x1024
versionstring否模型版本，v1.8.1 或 v1.9
negative_promptstring否负向提示词（仅 v1.9）
stylestring否风格（仅 v1.9）
reviseboolean否是否改写 prompt，默认 true
nnumber否生成数量，默认 1

返回值​

属性类型说明
idstring请求 ID
creatednumber时间戳
data[].urlstring图片 URL（24 小时有效）
data[].revised_promptstring改写后的 prompt

图生文（视觉理解）​

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

tip

需要先配置自定义模型 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);
}

完整示例​

云函数：AI 聊天接口​

const tcb = require("@cloudbase/node-sdk");
const app = tcb.init({ 
  env: "<YOUR_ENV_ID>",
  timeout: 60000 // AI 生成可能耗时较长
});

exports.main = async (event, context) => {
  const { messages } = event;
  
  const ai = app.ai();
  const model = ai.createModel("hunyuan-exp");

  try {
    const result = await model.generateText({
      model: "hunyuan-turbos-latest",
      messages
    });

    return {
      success: true,
      text: result.text,
      usage: result.usage
    };
  } catch (error) {
    return {
      success: false,
      error: error.message
    };
  }
};

云函数：流式响应（SSE）​

const tcb = require("@cloudbase/node-sdk");
const app = tcb.init({ 
  env: "<YOUR_ENV_ID>",
  timeout: 60000 // AI 生成可能耗时较长
});

exports.main = async (event, context) => {
  const { messages } = event;
  
  const ai = app.ai();
  const model = ai.createModel("hunyuan-exp");

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

  // 收集完整文本
  let fullText = "";
  for await (const text of res.textStream) {
    fullText += text;
  }

  const usage = await res.usage;

  return {
    text: fullText,
    usage
  };
};

云函数：图片生成​

const tcb = require("@cloudbase/node-sdk");
const app = tcb.init({ 
  env: "<YOUR_ENV_ID>",
  timeout: 60000 // 图片生成可能耗时较长
});

exports.main = async (event, context) => {
  const { prompt } = event;
  
  const ai = app.ai();
  const imageModel = ai.createImageModel("hunyuan-image");

  const res = await imageModel.generateImage({
    model: "hunyuan-image",
    prompt,
    size: "1024x1024",
    version: "v1.9"
  });

  return {
    url: res.data[0].url,
    revisedPrompt: res.data[0].revised_prompt
  };
};

与 Web SDK 的差异​

特性Node SDKWeb SDK
初始化tcb.init()cloudbase.init()
认证方式密钥或云函数环境Publishable Key + 登录
图片生成支持不支持
运行环境服务端浏览器

类型定义​

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

相关文档​