ai-model-nodejs
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseWhen to use this skill
何时使用该技能
Use this skill for calling AI models in Node.js backend or CloudBase cloud functions using .
@cloudbase/node-sdkUse it when you need to:
- Integrate AI text generation in backend services
- Generate images with Hunyuan Image model
- Call AI models from CloudBase cloud functions
- Server-side AI processing
Do NOT use for:
- Browser/Web apps → use skill
ai-model-web - WeChat Mini Program → use skill
ai-model-wechat - HTTP API integration → use skill
http-api
当您需要在Node.js后端或CloudBase云函数中通过调用AI模型时,可使用该技能。
@cloudbase/node-sdk适用场景:
- 在后端服务中集成AI文本生成功能
- 使用Hunyuan Image模型生成图像
- 从CloudBase云函数中调用AI模型
- 服务端AI处理
不适用场景:
- 浏览器/网页应用 → 使用技能
ai-model-web - 微信小程序 → 使用技能
ai-model-wechat - HTTP API集成 → 使用技能
http-api
Available Providers and Models
可用的服务商与模型
CloudBase provides these built-in providers and models:
| Provider | Models | Recommended |
|---|---|---|
| | ✅ |
| | ✅ |
CloudBase提供以下内置服务商与模型:
| 服务商 | 模型 | 推荐使用 |
|---|---|---|
| | ✅ |
| | ✅ |
Installation
安装
bash
npm install @cloudbase/node-sdk⚠️ AI feature requires version 3.16.0 or above. Check with .
npm list @cloudbase/node-sdkbash
npm install @cloudbase/node-sdk⚠️ AI功能需要3.16.0及以上版本,可通过查看当前版本。
npm list @cloudbase/node-sdkInitialization
初始化
In Cloud Functions
在云函数中
js
const tcb = require('@cloudbase/node-sdk');
const app = tcb.init({ env: '<YOUR_ENV_ID>' });
exports.main = async (event, context) => {
const ai = app.ai();
// Use AI features
};js
const tcb = require('@cloudbase/node-sdk');
const app = tcb.init({ env: '<YOUR_ENV_ID>' });
exports.main = async (event, context) => {
const ai = app.ai();
// 使用AI功能
};Cloud Function Configuration for AI Models
AI模型的云函数配置
⚠️ Important: When creating cloud functions that use AI models (especially and large language model generation), set a longer timeout as these operations can be slow.
generateImage()Using MCP Tool :
createFunctionSet the parameter in the object:
timeoutfunc- Parameter: (number)
func.timeout - Unit: seconds
- Range: 1 - 900
- Default: 20 seconds (usually too short for AI operations)
Recommended timeout values:
- Text generation (): 60-120 seconds
generateText - Streaming (): 60-120 seconds
streamText - Image generation (): 300-900 seconds (recommended: 900s)
generateImage - Combined operations: 900 seconds (maximum allowed)
⚠️ 重要提示:创建使用AI模型的云函数时(尤其是调用和大语言模型生成功能),需设置更长的超时时间,因为这些操作耗时可能较长。
generateImage()使用MCP工具:
createFunction在对象中设置参数:
functimeout- 参数:(数字类型)
func.timeout - 单位:秒
- 范围:1 - 900
- 默认值:20秒(通常对于AI操作来说过短)
推荐超时时间:
- 文本生成():60-120秒
generateText - 流式输出():60-120秒
streamText - 图像生成():300-900秒(推荐设置为900秒)
generateImage - 组合操作:900秒(允许的最大值)
In Regular Node.js Server
在常规Node.js服务器中
js
const tcb = require('@cloudbase/node-sdk');
const app = tcb.init({
env: '<YOUR_ENV_ID>',
secretId: '<YOUR_SECRET_ID>',
secretKey: '<YOUR_SECRET_KEY>'
});
const ai = app.ai();js
const tcb = require('@cloudbase/node-sdk');
const app = tcb.init({
env: '<YOUR_ENV_ID>',
secretId: '<YOUR_SECRET_ID>',
secretKey: '<YOUR_SECRET_KEY>'
});
const ai = app.ai();generateText() - Non-streaming
generateText() - 非流式文本生成
js
const model = ai.createModel("hunyuan-exp");
const result = await model.generateText({
model: "hunyuan-2.0-instruct-20251111", // Recommended model
messages: [{ role: "user", content: "你好,请你介绍一下李白" }],
});
console.log(result.text); // Generated text string
console.log(result.usage); // { prompt_tokens, completion_tokens, total_tokens }
console.log(result.messages); // Full message history
console.log(result.rawResponses); // Raw model responsesjs
const model = ai.createModel("hunyuan-exp");
const result = await model.generateText({
model: "hunyuan-2.0-instruct-20251111", // 推荐使用的模型
messages: [{ role: "user", content: "你好,请你介绍一下李白" }],
});
console.log(result.text); // 生成的文本字符串
console.log(result.usage); // { prompt_tokens, completion_tokens, total_tokens }
console.log(result.messages); // 完整的消息历史
console.log(result.rawResponses); // 模型原始响应streamText() - Streaming
streamText() - 流式文本生成
js
const model = ai.createModel("hunyuan-exp");
const res = await model.streamText({
model: "hunyuan-2.0-instruct-20251111", // Recommended model
messages: [{ role: "user", content: "你好,请你介绍一下李白" }],
});
// Option 1: Iterate text stream (recommended)
for await (let text of res.textStream) {
console.log(text); // Incremental text chunks
}
// Option 2: Iterate data stream for full response data
for await (let data of res.dataStream) {
console.log(data); // Full response chunk with metadata
}
// Option 3: Get final results
const messages = await res.messages; // Full message history
const usage = await res.usage; // Token usagejs
const model = ai.createModel("hunyuan-exp");
const res = await model.streamText({
model: "hunyuan-2.0-instruct-20251111", // 推荐使用的模型
messages: [{ role: "user", content: "你好,请你介绍一下李白" }],
});
// 方式1:遍历文本流(推荐)
for await (let text of res.textStream) {
console.log(text); // 增量文本片段
}
// 方式2:遍历数据流获取完整响应数据
for await (let data of res.dataStream) {
console.log(data); // 包含元数据的完整响应片段
}
// 方式3:获取最终结果
const messages = await res.messages; // 完整消息历史
const usage = await res.usage; // Token使用情况generateImage() - Image Generation
generateImage() - 图像生成
⚠️ Image generation is only available in Node SDK, not in JS SDK (Web) or WeChat Mini Program.
js
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); // Image URL (valid 24 hours)
console.log(res.data[0].revised_prompt);// Revised prompt if revise=true⚠️ 图像生成仅在Node SDK中可用,JS SDK(网页端)或微信小程序不支持该功能。
js
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);// 若revise=true,返回修改后的promptImage Generation Parameters
图像生成参数
ts
interface HunyuanGenerateImageInput {
model: "hunyuan-image"; // Required
prompt: string; // Required: image description
version?: "v1.8.1" | "v1.9"; // Default: "v1.8.1"
size?: string; // Default: "1024x1024"
negative_prompt?: string; // v1.9 only
style?: string; // v1.9 only
revise?: boolean; // Default: true
n?: number; // Default: 1
footnote?: string; // Watermark, max 16 chars
seed?: number; // Range: [1, 4294967295]
}
interface HunyuanGenerateImageOutput {
id: string;
created: number;
data: Array<{
url: string; // Image URL (24h valid)
revised_prompt?: string;
}>;
}ts
interface HunyuanGenerateImageInput {
model: "hunyuan-image"; // 必填
prompt: string; // 必填:图像描述
version?: "v1.8.1" | "v1.9"; // 默认值:"v1.8.1"
size?: string; // 默认值:"1024x1024"
negative_prompt?: string; // 仅v1.9版本支持
style?: string; // 仅v1.9版本支持
revise?: boolean; // 默认值:true
n?: number; // 默认值:1
footnote?: string; // 水印,最多16个字符
seed?: number; // 范围:[1, 4294967295]
}
interface HunyuanGenerateImageOutput {
id: string;
created: number;
data: Array<{
url: string; // 图片URL(24小时内有效)
revised_prompt?: string;
}>;
}Type Definitions
类型定义
ts
interface BaseChatModelInput {
model: string; // Required: model name
messages: Array<ChatModelMessage>; // Required: message array
temperature?: number; // Optional: sampling temperature
topP?: number; // Optional: nucleus sampling
}
type ChatModelMessage =
| { role: "user"; content: string }
| { role: "system"; content: string }
| { role: "assistant"; content: string };
interface GenerateTextResult {
text: string; // Generated text
messages: Array<ChatModelMessage>; // Full message history
usage: Usage; // Token usage
rawResponses: Array<unknown>; // Raw model responses
error?: unknown; // Error if any
}
interface StreamTextResult {
textStream: AsyncIterable<string>; // Incremental text stream
dataStream: AsyncIterable<DataChunk>; // Full data stream
messages: Promise<ChatModelMessage[]>;// Final message history
usage: Promise<Usage>; // Final token usage
error?: unknown; // Error if any
}
interface Usage {
prompt_tokens: number;
completion_tokens: number;
total_tokens: number;
}ts
interface BaseChatModelInput {
model: string; // 必填:模型名称
messages: Array<ChatModelMessage>; // 必填:消息数组
temperature?: number; // 可选:采样温度
topP?: number; // 可选:核采样参数
}
type ChatModelMessage =
| { role: "user"; content: string }
| { role: "system"; content: string }
| { role: "assistant"; content: string };
interface GenerateTextResult {
text: string; // 生成的文本
messages: Array<ChatModelMessage>; // 完整消息历史
usage: Usage; // Token使用情况
rawResponses: Array<unknown>; // 模型原始响应
error?: unknown; // 错误信息(若有)
}
interface StreamTextResult {
textStream: AsyncIterable<string>; // 增量文本流
dataStream: AsyncIterable<DataChunk>; // 完整数据流
messages: Promise<ChatModelMessage[]>;// 最终消息历史
usage: Promise<Usage>; // 最终Token使用情况
error?: unknown; // 错误信息(若有)
}
interface Usage {
prompt_tokens: number;
completion_tokens: number;
total_tokens: number;
}