OpenAI 工具调用与内置工具
本文档详细说明通过 UniGateway 调用 OpenAI 规范端点时的工具定义、函数调用(Function Calling)、官方内置工具集(Web Search、代码解释器、文件搜索等)、Schema 兼容性修复、命名空间一致性与选择策略。
章节导引
本篇为 OpenAI API 参考文档的第 5 章节:
- Responses 概述与快速开始
- 请求参数与输入格式
- 扩展推理与会话状态
- 结构化输出与采样参数
- 工具调用与内置工具(当前章节)
- 响应、流式与错误处理
工具调用代际支持与智能协议升级
UniGateway 同时支持自定义函数工具(function)、自定义无 Schema 工具(custom)、MCP 远程工具(mcp)以及 OpenAI 官方内置工具集。
| 参数 / 场景 | OpenAI 官方规范与 Migration Guide | UniGateway 处理规则 |
|---|---|---|
/v1/chat/completions 仅支持 Responses 工具调用的模型 | Migration Guide:gpt-6.1-sol、gpt-6-astra、gpt-5.5-pro、gpt-5.4-pro、gpt-5.3-codex、gpt-5、gpt-5-pro 不支持在 /v1/chat/completions 下携带 tools(官方要求使用 /v1/responses)。 | 智能协议升级与规范校验:当所选上游账号支持 /v1/responses 时,网关自动在内部将该 /v1/chat/completions 请求升级转换为 /v1/responses 转发并将响应转回 Chat Completions 格式;在仅支持原生 /v1/chat/completions 的通道上,网关直接返回官方格式的 400 invalid_request_error 并提示切换到 /v1/responses。 |
/v1/chat/completions 仅在 effort: "none" 下支持工具调用的模型 | Migration Guide:gpt-6.1-terra、gpt-6-sol、gpt-6-luna、gpt-5.6、gpt-5.5、gpt-5.4、gpt-5.2、gpt-5.1 仅在 reasoning_effort: "none" 时允许在 /v1/chat/completions 下使用 tools;开启推理(effort != "none")后需使用 /v1/responses。 | 按推理状态升级或校验:开启推理且携带 tools 时,若上游支持 /v1/responses 则自动升级协议转发;若通道仅支持原生 /v1/chat/completions,网关返回官方格式的 400 invalid_request_error,明确提示切换到 /v1/responses 或将 reasoning_effort 设为 "none"。 |
工具定义格式规范化
1. 结构差异与自动转换
| 规范差异 | Chat Completions 格式 | Responses API 格式 | UniGateway 处理说明 |
|---|---|---|---|
| 工具定义层级 | 嵌套在 function 对象下:{"type": "function", "function": {"name": "...", "description": "...", "parameters": {...}}} | 扁平结构:{"type": "function", "name": "...", "description": "...", "parameters": {...}} | 在 /v1/responses 端点,网关自动展平传入的 Chat 风格嵌套定义;反之在转往 Chat Completions 时自动补齐嵌套层。 |
| 工具选择策略 | 嵌套对象:{"type": "function", "function": {"name": "X"}} | 扁平对象:{"type": "function", "name": "X"} | 自动互转并对齐当前端点标准。 |
| 消息级动态工具 | 挂载在消息体中:messages[].tools | 不支持,仅在顶层声明 | 网关在入站阶段自动提取合并提升至顶层 tools,并执行 Schema 冲突校验。 |
旧版 functions 声明 | 顶层 functions 与 function_call | 不支持旧版参数 | 自动映射为顶层 tools 与 tool_choice,将旧版 role: "function" 消息映射为标准工具调用项。 |
工具 Schema 健壮性修复
为防止客户端传入的非规范 Schema 导致上游抛出 400 错误,UniGateway 在出站转发前执行确定性修复:
| 校验场景 | OpenAI 上游要求 | UniGateway 自动修复规则 |
|---|---|---|
工具 description 空值 | 上游要求工具定义中的 description 不能为空字符串(或必传非空字符串)。 | 空描述自动填充:若 tools[].description(或 tools[].function.description)为空字符串,网关自动填充占位符 "-";若上游因缺失 description 返回 400,网关自动补齐并重试。 |
工具 parameters 根节点缺失 | 上游要求 parameters 的根节点必须具有合法的 "type": "object"(不能为 null 或 "none")。 | 根节点修复:若 parameters.type 为 null / "none",或根节点仅包含对象分支的 anyOf / oneOf 而缺失 type,网关自动补齐 "type": "object";若 required: null,自动移除该空字段。 |
| PCRE 环视断言不支持 | parameters 内的正则表达式 pattern 不支持 PCRE 环视断言(Lookaround,如 (?=...)、(?!...)、(?<=...)、(?<!...))。 | 环视正则清理:网关自动检测并移除包含环视语法的 pattern 约束字段,保留其余校验规则,避免上游 JSON Schema 编译器崩溃。 |
官方内置工具集(Built-in Tools Suite)
在 Responses API 中,OpenAI 将常用 Agent 工具沉淀为平台级内置工具,客户端只需在 tools 中声明对应 type 即可调用:
工具类型 (type) | 适用场景 | 说明与代际演进 |
|---|---|---|
web_search | 联网实时搜索 | Migration Guide:早期 Responses API 使用的 "web_search_preview" 与 "web_search_preview_2025_03_11" 已在最新模型(GPT-5.6 / GPT-6 / GPT-6.1)上收敛为正式版 "web_search"。网关在出站时自动将预览版升级为正式版;若历史 input[] 中包含往期搜索项,网关自动补齐声明以满足校验。 |
image_generation | 内置图像生成 | 模型在对话中可直接触发图像生成工具,在响应中返回生成的图像载体。 |
code_interpreter | 沙箱代码执行 | 提供安全的 Python 代码执行环境,支持数据分析、图表生成与复杂数学计算。 |
file_search | 文件语义检索 | 配合知识库与向量存储,在用户挂载的文档集合中进行相关片段检索。 |
computer_use_preview | 计算机操作 | 支持屏幕定位、键盘输入与点击导航。 |
local_shell | 本地终端执行 | 面向 Codex 系列模型的命令与脚本执行环境。 |
tool_search | 工具动态检索 | 在工具数量庞大时支持模型自主检索并加载所需子工具。 |
mcp | 远程 MCP 工具 | 接入基于 Model Context Protocol 的远程工具服务。 |
工具命名空间与调用控制
| 参数 / 场景 | 规范要求 | UniGateway 处理规则 |
|---|---|---|
工具命名空间 namespace 一致性 | 在使用命名空间工具(如 MCP 工具或带 namespace 的自定义工具)时,Responses API 要求 input[] 中回传的工具调用项必须携带与工具定义一致的 namespace 字段;而部分标准端点或 /responses/compact 端点则拒绝未知的 input[].namespace 字段。 | 命名空间自动推断与按需剥离:当 input[] 中的工具调用项缺失 namespace 时,网关自动从当前请求的 tools[] 及内置已知工具集中匹配工具名并回填 namespace;在不支持该字段的标准 API Key 端点或 /responses/compact 端点上,网关自动剥离该字段并支持自适应重试。 |
parallel_tool_calls 与 tool_choice 联动 | parallel_tool_calls 仅在请求同时携带非空 tools 时允许传入;当 tools 为空时,指定 tool_choice: "required" 属于非法请求;部分通道在 tool_choice: "none" 时要求不同时携带 tools 定义。 | 联动清理与校验:当请求未携带 tools(或为空数组)时,网关出站时自动移除孤立的 parallel_tool_calls;若此时 tool_choice 为 "required" 则返回 400;在要求 tool_choice: "none" 不带工具定义的通道上,网关自动剥离 tools 数组以防止误触发工具调用。 |
| 函数调用与思考签名透传(Function Call & Thought Signature) | 带有扩展推理的模型在触发函数调用(Function Calling)时可能附带思考签名元数据(如 signature 或 thoughtSignature / extra_content.google.thought_signature);客户端在多轮回传工具结果或函数输出时需保留这些上下文元数据。 | 全流程签名绑定与保护:网关双向保障工具调用项与思考签名的绑定关系,保留跨协议桥接下的 thoughtSignature,并在多轮历史回传中准确关联 CallID 与签名,防止上游因签名缺失或篡改抛出 400 错误。 |