Skip to main content

​
Gemini 工具调用示例

以下示例展示如何使用Gemini的Function Calling功能，让AI能够调用外部工具来获取信息或执行操作。

​
快速开始

只需要替换 <API-KEY> 为你的实际API密钥即可运行。 
curl -X POST "https://model-api.skyengine.com.cn/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API-KEY>" \
  -d '{
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "text": "计算一下 (25 + 15) * 3 - 20 等于多少？"
          }
        ]
      }
    ],
    "tools": [{
      "functionDeclarations": [
        {
          "name": "calculate_math",
          "description": "执行数学计算，支持基本的四则运算和括号",
          "parameters": {
            "type": "object",
            "properties": {
              "expression": {
                "type": "string",
                "description": "要计算的数学表达式，如 '2+3*4' 或 '(10+5)/3'"
              }
            },
            "required": [
              "expression"
            ]
          }
        }
      ]
    }]
  }'

​
Gemini工具调用的特点

​
1. 工具定义格式

Gemini使用 functionDeclarations 数组来定义工具： 
{
  "tools": [{
    "functionDeclarations": [
      {
        "name": "function_name",
        "description": "函数描述",
        "parameters": {
          "type": "object",
          "properties": {
            "param": {
              "type": "string",
              "description": "参数描述"
            }
          },
          "required": ["param"]
        }
      }
    ]
  }]
}

​
2. 响应结构

Gemini的工具调用响应格式： 
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "function_name",
              "args": {
                "param": "value"
              }
            }
          }
        ]
      }
    }
  ]
}

​
3. 工作流程

  1. 用户发送带有工具定义的消息
  2. Gemini分析是否需要使用工具
  3. Gemini返回包含 functionCall 的响应
  4. 客户端执行对应的函数
  5. 客户端将结果作为 functionResponse 发送回Gemini
  6. Gemini基于工具结果生成最终回复

​
结果示例

200
{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "calculate_math",
              "args": {
                "expression": "(25 + 15) * 3 - 20"
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 150,
    "candidatesTokenCount": 50,
    "totalTokenCount": 200
  }
}

​
Google Search 工具

Gemini 支持内置的 Google Search 工具，可以让模型搜索实时信息来回答问题。与自定义函数调用不同，Google Search 是由 Gemini 自动执行的，无需客户端处理搜索逻辑。 
curl -X POST "https://model-api.skyengine.com.cn/v1beta/models/gemini-2.5-flash:generateContent" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API-KEY>" \
  -d '{
    "contents": [
      {
        "parts": [
          {"text": "2024年欧洲杯冠军是谁？"}
        ]
      }
    ],
    "tools": [
      {
        "googleSearch": {}
      }
    ]
  }'

​
Google Search 工具特点

  • 自动执行: 模型会自动调用 Google Search 获取信息，无需客户端处理
  • 实时信息: 可以获取最新的新闻、事件、数据等实时信息
  • 简单配置: 只需在 tools 中添加 {"googleSearch": {}} 即可启用

​
注意事项

  1. 消息角色: 多轮对话时，所有消息都需要指定 role 字段（user 或 model）
  2. 字段命名: API 使用 camelCase 命名（functionCall、functionResponse），而不是 snake_case
  3. 函数响应: 函数执行结果需要以 role: "user" 的消息发送回模型
  4. 错误处理: 建议在函数执行中添加完善的错误处理机制