Gemini Function Calling 工具调用实战:用 OpenAI tools 接Itzyk

首页 / 文章 / 技术教程 / Gemini Function Calling 工具调用实战:用 OpenAI tools 接Itzyk

Itzyk API(api.itzyk.top)上 Gemini Function Calling:POST https://api.itzyk.top/v1/chat/completions,传 OpenAI 风格 tools;鉴权 Bearer sk-。

作者:智枢 ZhiShu · 发布:2026-10-19 · 更新:2026-11-09

一、为什么要做 Function Calling? 事实锚点:Itzyk API(api.itzyk.top)上 Function Calling 走 POST /v1/chat/completions + OpenAI 风格 tools ;Base URL https://api.itzyk.top/v1 。 对话接口只会「说」;真实业务往往要「做」:查订单、算运费、调内部 API、写数据库。Function Calling(工具调用)让模型在需要时返回结构化的函数名与参数,由你的代码真正执行,再把结果喂回模型生成最终答复。 Itzyk API(https://api.itzyk.top)提供 OpenAI Compatible 的 Gemini 入口。对客户端来说, tools / tool calls 的写法与 OpenAI 一致:把 base url 指到 https://api.itzyk.top/v1 ,换上平台 sk- Key 与模型 gemini-3.6-flash 即可。本文从协议讲到 Python / Node 完整循环、超时与安全边界、费用控制,以及上线检查表。 适合:要做智能客服、内部 Copilot、带检索/下单能力的 Agent 的后端工程师。若你还只会单轮对话,建议先看 五分钟上手:用 OpenAI SDK 调用 Gemini /articles/openai-sdk-call-gemini-api 。 --- 二、协议直觉:谁负责执行? 模型 不执行 你的函数。它只决定: 1. 要不要调工具; 2. 调哪个; 3. 参数是什么。 执行、鉴权、幂等、超时、审计全在你这边。一轮完整交互通常是: Itzyk网关负责鉴权、限流、按 Token 计费与转发上游 Gemini; 工具列表与执行逻辑不经过网关存储 。每次请求仍要把需要的 tools 定义带上。 准备: 在 https://api.itzyk.top/ 注册、创建 Key、充值少量余额,并确认模型权限包含 gemini-3.6-flash 。价格与限流见 /pricing https://api.itzyk.top/pricing 、 /services https://api.itzyk.top/services 。 --- 三、最小可运行:Python 查天气(示意) 下面用一个本地假函数演示循环。生产里把 get weather 换成真实 HTTP 调用即可。 要点: - tool choice="auto" :模型自行决定是否调用;强制某工具可用 {"type":"function","function":{"name":"..."}} 。 - arguments 是 JSON 字符串 ,务必 json.loads 并做字段校验。 - 循环加硬上限(如上例 4),避免模型反复调同一工具烧 Token。 --- 四、Node.js 同一套协议 前端不要直持 Key;用 BFF(Express / Nest)持 Key 并执行工具,前端只收最终文案或 SSE。Node 接入总览见 Node.js 接入 Gemini 对话接口 /articles/nodejs-gemini-chat-api-guide 。 --- 五、工具设计:少而精 5.1 命名与描述 - 名称用稳定的 snake case ,上线后勿随意改。 - description 写清「何时该调、何时不该调」。 - 参数宁少勿多;枚举用 enum ,减少幻觉。 5.2 权限与副作用 | 类型 | 建议 | |------|------| | 只读查询 | 默认可开,仍要鉴权当前用户 | | 写操作(下单、退款) | 二次确认或人工审核;工具内再验权限 | | 高费用外部 API | 设 QPS、缓存、熔断 | 永远不要把「任意 SQL / 任意 shell」暴露成工具。 5.3 返回值 工具返回给模型的应是 短 JSON ,不要把整页 HTML 塞回去。字段用业务语言: status 、 amount yuan 、 error 。错误也要结构化,方便模型解释给用户。 --- 六、与多轮会话、流式的关系 工具循环通常发生在 同一次用户回合 内:中间几跳对用户不可见,只展示最终答复。若你已有会话记忆层,把「用户可见」的 user/assistant 写入历史即可;中间的 tool 消息可按策略裁剪,避免上下文膨胀。会话拼装详见 多轮对话与会话记忆 /articles/gemini-multi-turn-session-memory 。 流式场景:首包可能是 tool calls 而非文本。UI 可显示「正在查询订单…」,等最终 content 再打字机输出。不要假设每个 chunk 都有 delta.content 。 --- 七、费用、超时与限流 - 一次用户问题可能触发 2~N 次 /v1/chat/completions ,每次都计输入+输出 Token。工具定义本身也占输入。 - 默认用 gemini-3.6-flash ;复杂规划再考虑 Pro。价格见 /pricing https://api.itzyk.top/pricing 。 - 工具执行设超时(如 3~8 秒),超时返回 {"error":"timeout"} ,让模型换话术或降级。 - 遇 429 做指数退避;402 提示充值。详见 费用与限流实战 /articles/gemini-api-billing-rate-limit-guide 。 打点建议:每次工具名、耗时、成败、关联 request id (若有),与Itzyk控制台用量对照。 --- 八、排错清单 | 现象 | 排查 | |------|------| | 从不调工具 | 检查 description、system 是否要求调用;试 tool choice 强制 | | arguments 解析失败 | 捕获异常,把错误作为 tool 结果回传,让模型重试 | | 无限循环 | 加轮次上限;同一工具连续失败则停止并道歉 | | 401/403 | Key 无效或模型未授权 | | 结果「像真的」但没调工具 | 加强 system:「禁止编造订单/天气数据」 | 联调先用 curl 验证鉴权,再跑工具循环: 更多错误码见 curl 排错手册 /articles/curl-debug-gemini-api-handbook 与 /docs https://api.itzyk.top/docs 。 --- 九、上线检查表 1. Key 只在服务端;按环境拆分开发/生产 Key。 2. 工具白名单 + 用户鉴权 + 写操作确认。 3. 循环上限、工具超时、失败降级文案。 4. 默认 Flash;usage 打点;429/402 可观测。 5. 评测集:10~20 条真实问法,统计「该调却未调 / 误调 / 参数错」。 LangChain Agent 也可走同一 Base URL,见 LangChain 接入 Gemini /articles/langchain-gemini-api-practice 。若你要的是「固定 JSON、不一定要调外部函数」,下一篇可看结构化输出教程。 --- --- 十一、生产封装:一个可复用的 ToolRunner 把「请求模型 → 执行工具 → 再请求」收成类,业务只注册函数: 这样 Code Review 时只需检查: dispatch 是否越权、是否有超时、日志是否含工具名。团队新人复制 ToolRunner 即可,不必每人重写循环。 --- 十二、参数校验:用 JSON Schema 挡在执行前 模型偶发漏字段或类型错。执行前用 jsonschema (或手写)校验: 校验失败时把 error 作为 tool 结果返回,让模型改参数再调,比直接 500 更友好。写操作工具务必校验「订单是否属于当前登录用户」,不能只信模型传入的 user id 。 --- 十三、并行 tool calls 怎么处理? 有时模型一次返回多个 tool calls (例如同时查天气和查日历)。协议允许你 并行执行 再一次性追加多条 role=tool 。注意: - 互相依赖的工具不要并行(先查库存再下单)。 - 并行时各自独立超时;一个失败不要拖死全部,失败的返回 error JSON。 - 打点时按 tool call id 关联,便于排查「哪一个慢」。 伪代码: --- 十四、产品文案与用户体验 用户不应看到原始 JSON。推荐状态机: 1. 收到问题 → UI:「思考中」 2. 出现 tool calls → 「正在查询订单 A10086…」(可用工具中文名映射表) 3. 最终 content → 打字机展示 4. 失败 → 「暂时查不到,请提供订单号或转人工」 映射表示例: lookup order →「查询订单」, get weather →「查询天气」。避免把内部函数名直接甩给用户。 --- 十五、测试策略 - 单测工具本身 :不经过模型,给定参数断言返回。 - 契约测 :固定 messages + tools,对沙箱 Key 跑快照(允许文案小差异,断言调用了正确工具名)。 - 回归集 :20 条「必须调工具」+ 10 条「禁止调工具」(闲聊)。统计误调率。 - 压测 :并发下工具 API 与Itzyk 429 的表现,确认退避与队列。 把回归集放进 CI 夜跑,模型或提示词一改就能发现回退。 --- 十六、与Itzyk平台能力对齐 - 控制台可

本文发布于 Itzyk API(AI API 网关,OpenAI 兼容)。更多: 文章中心 · 开发者文档 · API 服务 · 价格。

llms.txt · sitemap · robots · 文章

京ICP备19037501号-3