Xikapi 接入文档

函数调用 ​

函数调用让 Gemini 在需要外部数据或业务动作时请求调用函数。模型负责判断是否需要函数、生成函数参数；你的服务端负责执行函数、校验权限，并把结果返回给 Gemini。

什么是函数调用 ​

函数调用适合以下场景：

  • 查询订单
  • 查询数据库
  • 搜索知识库
  • 调用内部 API
  • 获取实时信息
  • 执行受控业务操作

函数定义结构 ​

函数通常包含名称、描述和参数 schema。

json
{
  "name": "get_order_status",
  "description": "Check order shipping status",
  "parameters": {
    "type": "OBJECT",
    "properties": {
      "order_id": {
        "type": "STRING",
        "description": "Order ID"
      }
    },
    "required": ["order_id"]
  }
}

函数调用流程 ​

  1. 服务端在请求中传入 tools.functionDeclarations
  2. 用户提出需要外部信息的问题
  3. Gemini 返回 functionCall
  4. 服务端读取函数名称和参数
  5. 服务端执行真实函数
  6. 服务端把 functionResponse 返回给 Gemini
  7. Gemini 根据函数结果生成最终回复

模型什么时候会调用函数 ​

当用户问题需要实时数据、私有数据或系统操作时，Gemini 可能选择调用函数。

json
{
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_order_status",
          "description": "Check order status",
          "parameters": {
            "type": "OBJECT",
            "properties": {
              "order_id": { "type": "STRING" }
            },
            "required": ["order_id"]
          }
        }
      ]
    }
  ],
  "contents": [
    {
      "parts": [
        { "text": "Check where order A1001 is now" }
      ]
    }
  ]
}

服务端如何执行函数 ​

服务端应只执行白名单内的函数，并对参数进行校验。

javascript
const functionHandlers = {
  async get_order_status(input) {
    if (!/^[A-Z0-9-]+$/.test(input.order_id)) {
      throw new Error("Invalid order_id");
    }

    return await queryOrderStatus(input.order_id);
  },
};

如何把函数结果返回给 Gemini ​

服务端执行函数后，把结果作为 functionResponse 放回下一轮消息。

json
{
  "contents": [
    {
      "role": "user",
      "parts": [
        { "text": "Check where order A1001 is now" }
      ]
    },
    {
      "role": "model",
      "parts": [
        {
          "functionCall": {
            "name": "get_order_status",
            "args": {
              "order_id": "A1001"
            }
          }
        }
      ]
    },
    {
      "role": "user",
      "parts": [
        {
          "functionResponse": {
            "name": "get_order_status",
            "response": {
              "status": "Order A1001 has arrived at the Shanghai distribution center and is expected to be delivered tomorrow."
            }
          }
        }
      ]
    }
  ]
}

多函数场景 ​

多函数适合同时提供订单查询、用户资料、知识库搜索、工单创建等能力。

设计多函数时要注意：

  • 函数名称清晰，不要语义重叠
  • 每个函数只做一类明确动作
  • 高风险动作必须二次确认
  • 函数结果尽量返回结构化数据
  • 不要把内部密钥、SQL 或敏感配置暴露给模型

函数调用最佳实践 ​

  • 函数执行必须在服务端
  • 所有参数都要做 schema 校验和业务校验
  • 函数调用要记录日志，便于排查
  • 写操作要增加权限控制和确认流程
  • 给函数写清楚能力边界，避免模型误用
  • 函数结果中只返回回答所需的信息