OpenAI API/OpenAI 工具调用与内置工具

OpenAI 自定义函数工具、官方内置工具集、Schema 兼容性修复、命名空间一致性与选择策略。

OpenAI 工具调用与内置工具

本文档详细说明通过 UniGateway 调用 OpenAI 规范端点时的工具定义、函数调用(Function Calling)、官方内置工具集(Web Search、代码解释器、文件搜索等)、Schema 兼容性修复、命名空间一致性与选择策略。


章节导引

本篇为 OpenAI API 参考文档的第 5 章节:

  1. Responses 概述与快速开始
  2. 请求参数与输入格式
  3. 扩展推理与会话状态
  4. 结构化输出与采样参数
  5. 工具调用与内置工具(当前章节)
  6. 响应、流式与错误处理

工具调用代际支持与智能协议升级

UniGateway 同时支持自定义函数工具(function)、自定义无 Schema 工具(custom)、MCP 远程工具(mcp)以及 OpenAI 官方内置工具集。

参数 / 场景OpenAI 官方规范与 Migration GuideUniGateway 处理规则
/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 错误。