跳到主要内容

工具调用

工具调用（Function Calling / Tool Use）允许大模型调用自定义函数，扩展模型能力，适用于信息检索、数据库操作、外部 API 调用等场景。

工作原理​

CloudBase AI SDK 自动处理上述流程，开发者只需定义工具并注册即可。

使用步骤​

1. 定义工具​

const getWeatherTool = {
  name: "get_weather",
  description: "查询指定城市的天气信息",
  fn: async ({ city }) => {
    // 实际场景中调用天气 API
    return `${city}：26°C，晴`;
  },
  parameters: {
    type: "object",
    properties: {
      city: {
        type: "string",
        description: "城市名称"
      }
    },
    required: ["city"]
  }
};

2. 注册工具​

ai.registerFunctionTool(getWeatherTool);

3. 调用模型​

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

const result = await model.generateText({
  model: "hunyuan-turbos-latest",
  tools: [getWeatherTool],
  messages: [{ role: "user", content: "北京天气怎么样？" }]
});

console.log(result.text);
// 输出：北京今天 26°C，晴天，适宜外出活动。

工具定义​

FunctionTool 类型​

interface FunctionTool {
  name: string;           // 工具名称，唯一标识
  description: string;    // 工具描述，帮助模型理解用途
  fn: Function;           // 执行函数
  parameters: object;     // 参数定义（JSON Schema 格式）
}

参数定义（JSON Schema）​

{
  type: "object",
  properties: {
    // 字符串参数
    city: {
      type: "string",
      description: "城市名称"
    },
    // 数字参数
    limit: {
      type: "number",
      description: "返回结果数量"
    },
    // 布尔参数
    detailed: {
      type: "boolean",
      description: "是否返回详细信息"
    },
    // 枚举参数
    unit: {
      type: "string",
      enum: ["celsius", "fahrenheit"],
      description: "温度单位"
    }
  },
  required: ["city"]  // 必填参数
}

多工具示例​

// 天气查询工具
const getWeatherTool = {
  name: "get_weather",
  description: "查询城市天气",
  fn: async ({ city }) => `${city}：26°C，晴`,
  parameters: {
    type: "object",
    properties: {
      city: { type: "string", description: "城市名称" }
    },
    required: ["city"]
  }
};

// 时间查询工具
const getTimeTool = {
  name: "get_time",
  description: "查询指定城市的当前时间",
  fn: async ({ city }) => {
    const now = new Date();
    return `${city}当前时间：${now.toLocaleTimeString()}`;
  },
  parameters: {
    type: "object",
    properties: {
      city: { type: "string", description: "城市名称" }
    },
    required: ["city"]
  }
};

// 注册多个工具
ai.registerFunctionTool(getWeatherTool);
ai.registerFunctionTool(getTimeTool);

// 调用时传入所有工具
const result = await model.generateText({
  model: "hunyuan-turbos-latest",
  tools: [getWeatherTool, getTimeTool],
  messages: [{ role: "user", content: "北京现在几点了？天气怎么样？" }]
});

高级配置​

toolChoice​

控制模型如何选择工具：

const result = await model.generateText({
  model: "hunyuan-turbos-latest",
  tools: [getWeatherTool],
  toolChoice: "auto",  // 模型自动决定是否使用工具
  messages: [{ role: "user", content: "北京天气怎么样？" }]
});
值说明
"auto"模型自动决定（默认）
"none"禁止使用工具
"custom"强制使用指定工具

maxSteps​

限制模型调用工具的最大次数：

const result = await model.generateText({
  model: "hunyuan-turbos-latest",
  tools: [getWeatherTool],
  maxSteps: 3,  // 最多调用 3 次工具
  messages: [{ role: "user", content: "对比北京和上海的天气" }]
});

onStepFinish​

监听每次工具调用完成：

const result = await model.generateText({
  model: "hunyuan-turbos-latest",
  tools: [getWeatherTool],
  onStepFinish: ({ toolCall, toolResult, text }) => {
    if (toolCall) {
      console.log("调用工具:", toolCall.function.name);
      console.log("工具结果:", toolResult);
    }
    if (text) {
      console.log("生成文本:", text);
    }
  },
  messages: [{ role: "user", content: "北京天气怎么样？" }]
});

流式调用​

工具调用也支持流式输出：

const result = await model.streamText({
  model: "hunyuan-turbos-latest",
  tools: [getWeatherTool],
  messages: [{ role: "user", content: "北京天气怎么样？" }]
});

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

实际应用示例​

数据库查询​

const queryDatabaseTool = {
  name: "query_database",
  description: "查询数据库中的用户信息",
  fn: async ({ userId }) => {
    const db = app.database();
    const result = await db.collection("users").doc(userId).get();
    return JSON.stringify(result.data);
  },
  parameters: {
    type: "object",
    properties: {
      userId: { type: "string", description: "用户 ID" }
    },
    required: ["userId"]
  }
};

外部 API 调用​

const searchWebTool = {
  name: "search_web",
  description: "搜索网络获取最新信息",
  fn: async ({ query }) => {
    const response = await fetch(`https://api.example.com/search?q=${query}`);
    const data = await response.json();
    return JSON.stringify(data.results.slice(0, 3));
  },
  parameters: {
    type: "object",
    properties: {
      query: { type: "string", description: "搜索关键词" }
    },
    required: ["query"]
  }
};

计算器​

const calculatorTool = {
  name: "calculator",
  description: "执行数学计算",
  fn: ({ expression }) => {
    try {
      // 注意：实际使用时应使用安全的表达式解析库
      return String(eval(expression));
    } catch {
      return "计算错误";
    }
  },
  parameters: {
    type: "object",
    properties: {
      expression: { type: "string", description: "数学表达式，如 2+2*3" }
    },
    required: ["expression"]
  }
};

类型定义​

IOnStepFinish​

interface IOnStepFinish {
  messages: ChatModelMessage[];  // 当前消息列表
  text?: string;                 // 生成的文本
  toolCall?: ToolCall;           // 工具调用信息
  toolResult?: unknown;          // 工具执行结果
  finishReason?: string;         // 结束原因
  stepUsage?: Usage;             // 当前步骤 token 使用量
  totalUsage?: Usage;            // 累计 token 使用量
}

ToolCall​

interface ToolCall {
  id: string;
  type: string;
  function: {
    name: string;
    arguments: string;  // JSON 字符串
  };
}

最佳实践​

  1. 清晰的工具描述 - 帮助模型准确理解工具用途
  2. 完整的参数说明 - 包含类型、描述、是否必填
  3. 错误处理 - 工具函数应处理异常情况
  4. 限制调用次数 - 使用 maxSteps 避免无限循环
  5. 异步函数 - 工具函数可以是异步的

相关文档​