OpenAI API兼容格式请求参数 – tools

导航栏：首页 / AI开发参考资料 / OpenAI API 兼容格式参考资料 / 请求参数详解 / tools

如果您想深入了解如何借助 OpenAI API 打造人工智能硬件，欢迎访问本站教程目录页，查看太极创客团队为您精心准备的系列教程。

参数说明

tools参数允许你以特定的数据结构（如列表嵌套字典的形式）向模型提供一系列可调用的工具。在实际应用中，模型会基于对话上下文以及用户请求，智能地判断是否调用这些工具以及具体的使用方式

这个参数极大地扩展了模型的能力范围，使其能够执行超越纯文本生成的多样化任务，像查询实时数据、执行各类计算、调用外部服务等。需要注意的是，不同类型的工具在调用时，可能会受到工具自身接口限制、数据访问权限、调用频率限制等因素的约束。在使用 tools 参数时，要充分了解这些潜在的限制条件，以确保工具的有效调用和模型功能的正常发挥。

必需性

tools是API请求中的可选参数。如果不设置此参数，模型将无法调用任何工具，只能基于其训练数据生成响应。

工作原理

当设置tools参数时，模型会在生成过程中评估是否需要调用工具：

工具识别：模型会分析用户请求，判断是否需要调用提供的工具
参数提取：模型会从用户输入中提取调用工具所需的参数
工具调用：模型会生成工具调用请求，而不是直接回答用户
结果处理：模型会根据工具返回的结果继续对话

参数格式

tools是一个数组，每个元素是一个工具定义对象：

type：工具类型，目前主要支持”function”
function：函数定义对象，包含name、description、parameters等字段
name：函数名称，用于标识和调用工具
description：函数描述，该字段的作用是帮助模型准确理解工具的用途。
parameters：采用 JSON Schema 定义函数参数。一般来说，parameters是一个对象，每个属性对应一个函数参数

在请求体中的使用

以下是一个完整的请求体示例，展示了tools参数的位置和用法：

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "北京今天的天气怎么样？"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称"
            },
            "date": {
              "type": "string",
              "format": "date",
              "description": "查询日期"
            }
          },
          "required": ["city"]
        }
      }
    }
  ]
}

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "北京今天的天气怎么样？"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "获取指定城市的天气信息",
        "parameters": {
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "城市名称"
            },
            "date": {
              "type": "string",
              "format": "date",
              "description": "查询日期"
            }
          },
          "required": ["city"]
        }
      }
    }
  ]
}

在这个示例中：

"tools": [...] 定义了一个工具列表，包含一个天气查询函数
工具类型为”function”，表示这是一个可调用的函数
function对象包含了函数的完整定义，包括名称、描述和参数schema
模型会根据用户请求”北京今天的天气”决定是否调用get_weather函数

响应格式

当模型决定调用工具时，API响应中的message对象会包含tool_calls字段，而不是常规的content字段。以下是响应结构的示例：

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-5.2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\": \"北京\", \"date\": \"2024-01-15\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 82,
    "completion_tokens": 17,
    "total_tokens": 99
  }
}

{
  "id": "chatcmpl-123",
  "object": "chat.completion",
  "created": 1677652288,
  "model": "gpt-5.2",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\": \"北京\", \"date\": \"2024-01-15\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 82,
    "completion_tokens": 17,
    "total_tokens": 99
  }
}

响应中的关键字段：

content：当模型决定调用工具时，此字段为null
tool_calls：工具调用数组，包含模型请求调用的工具信息
id：工具调用的唯一标识符，用于后续将工具结果返回给模型
type：工具类型，通常为”function”
function.name：要调用的函数名称
function.arguments：调用函数所需的参数，JSON字符串格式
finish_reason：结束原因，当模型调用工具时为”tool_calls”

工具调用流程：

用户发送请求，包含tools参数定义
模型分析请求，决定是否需要调用工具
如果需要调用工具，API返回包含tool_calls的响应
客户端执行工具调用，获取结果
将工具结果作为新的消息（role: “tool”）发送回API
模型基于工具结果继续生成最终响应

工具结果提交示例：

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "北京今天的天气怎么样？"
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"city\": \"北京\", \"date\": \"2024-01-15\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temperature\": 5, \"condition\": \"晴\", \"humidity\": 45}"
    }
  ]
}

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "北京今天的天气怎么样？"
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"city\": \"北京\", \"date\": \"2024-01-15\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_abc123",
      "content": "{\"temperature\": 5, \"condition\": \"晴\", \"humidity\": 45}"
    }
  ]
}

在这个示例中：

"role": "tool" 表示这是一个工具结果消息
"tool_call_id" 必须与之前工具调用的id匹配
"content" 包含工具执行的结果数据
模型会根据这个工具结果生成最终的天气描述回答

使用场景

实时数据查询

场景说明：通过工具调用，模型可以获取实时数据，如天气、股票、新闻等，弥补模型训练数据的时间限制。模型无法直接访问互联网或实时数据，但可以通过定义的工具函数来获取这些信息。

使用方法：

定义一个能够查询实时数据的工具函数（如get_stock_price）
在函数描述中明确说明工具的功能和数据来源
定义必要的参数（如股票代码、城市名称等）
模型会识别用户请求中的实时数据需求并调用相应工具
工具执行后返回实时数据，模型基于这些数据生成回答

执行流程：用户提问 → 模型识别需要实时数据 → 调用工具函数 → 工具查询外部数据源 → 返回结果 → 模型生成基于实时数据的回答

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "查询苹果公司今天的股价。"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_stock_price",
        "description": "获取指定股票的实时价格",
        "parameters": {
          "type": "object",
          "properties": {
            "symbol": {
              "type": "string",
              "description": "股票代码"
            }
          },
          "required": ["symbol"]
        }
      }
    }
  ]
}

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "查询苹果公司今天的股价。"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_stock_price",
        "description": "获取指定股票的实时价格",
        "parameters": {
          "type": "object",
          "properties": {
            "symbol": {
              "type": "string",
              "description": "股票代码"
            }
          },
          "required": ["symbol"]
        }
      }
    }
  ]
}

外部系统集成

场景说明：将模型与现有系统集成，通过工具调用执行数据库查询、API调用、文件操作等任务。这使得模型能够访问和操作企业内部系统，实现智能化的业务流程自动化。

使用方法：

定义与外部系统交互的工具函数（如query_database）
在函数描述中说明工具的功能、权限范围和注意事项
定义必要的参数（如用户ID、查询条件、操作类型等）
实现工具函数时确保安全性和权限控制
模型会根据用户请求调用相应的工具函数与外部系统交互
工具返回外部系统的数据或操作结果，模型生成响应

执行流程：用户请求 → 模型识别需要访问外部系统 → 调用工具函数 → 工具与外部系统交互（数据库/API/文件系统） → 返回结果 → 模型生成基于系统数据的回答

注意事项：确保工具函数实现适当的身份验证、权限控制和错误处理机制，保护系统安全。

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "查询用户张三的订单信息。"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "query_database",
        "description": "查询数据库中的用户订单信息",
        "parameters": {
          "type": "object",
          "properties": {
            "user_id": {
              "type": "string",
              "description": "用户ID"
            }
          },
          "required": ["user_id"]
        }
      }
    }
  ]
}

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "查询用户张三的订单信息。"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "query_database",
        "description": "查询数据库中的用户订单信息",
        "parameters": {
          "type": "object",
          "properties": {
            "user_id": {
              "type": "string",
              "description": "用户ID"
            }
          },
          "required": ["user_id"]
        }
      }
    }
  ]
}

自动化任务执行

场景说明：通过工具调用，模型可以执行自动化任务，如发送邮件、创建日历事件、更新CRM系统等。这使得模型能够成为智能助手，帮助用户完成各种日常工作和业务操作。

使用方法：

定义能够执行特定操作的工具函数（如send_email、create_calendar_event）
在函数描述中详细说明工具的功能、参数要求和执行效果
定义所有必要的参数（如收件人、主题、正文、时间、地点等）
工具函数应验证参数完整性并执行实际操作
模型会根据用户的自然语言指令提取参数并调用相应工具
工具执行操作后返回结果，模型确认操作完成或报告错误

执行流程：用户发出指令 → 模型理解任务意图 → 提取必要参数 → 调用工具函数 → 工具执行自动化操作 → 返回执行结果 → 模型向用户确认任务完成

应用场景：邮件发送、日程管理、CRM数据更新、任务分配、报告生成、通知发送等日常办公自动化。

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "给李四发送一封会议邀请邮件。"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "send_email",
        "description": "发送邮件给指定收件人",
        "parameters": {
          "type": "object",
          "properties": {
            "to": {
              "type": "string",
              "description": "收件人邮箱"
            },
            "subject": {
              "type": "string",
              "description": "邮件主题"
            },
            "body": {
              "type": "string",
              "description": "邮件正文"
            }
          },
          "required": ["to", "subject", "body"]
        }
      }
    }
  ]
}

{
  "model": "gpt-5.2",
  "messages": [
    {
      "role": "user",
      "content": "给李四发送一封会议邀请邮件。"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "send_email",
        "description": "发送邮件给指定收件人",
        "parameters": {
          "type": "object",
          "properties": {
            "to": {
              "type": "string",
              "description": "收件人邮箱"
            },
            "subject": {
              "type": "string",
              "description": "邮件主题"
            },
            "body": {
              "type": "string",
              "description": "邮件正文"
            }
          },
          "required": ["to", "subject", "body"]
        }
      }
    }
  ]
}

使用建议

提供清晰的工具描述：为每个工具提供详细、准确的描述，帮助模型理解工具的用途和适用场景
定义完整的参数schema：在parameters字段中定义完整的JSON Schema，包括类型、描述、格式和必需字段
使用有意义的函数名：选择清晰、描述性的函数名称，便于模型理解和调用
限制工具数量：避免提供过多工具，这可能导致模型选择困难。建议根据场景提供3-10个相关工具
实现错误处理：设计可靠的错误处理机制，处理模型可能的错误调用或参数不完整的情况
结合tool_choice使用：使用tool_choice参数控制模型的工具选择行为，如强制调用特定工具或禁用工具调用
测试工具调用：在开发阶段充分测试工具调用逻辑，确保模型能够正确识别和使用工具
监控调用频率：监控工具调用的频率和成功率，优化工具定义和提示词设计

常见问题解答

问：模型如何决定是否调用工具？
答：模型会根据对话上下文和用户请求，分析是否需要调用提供的工具。如果用户请求的信息可以通过工具获取，或者用户明确要求执行某个操作，模型会倾向于调用工具。模型会评估工具的描述和参数，判断哪个工具最适合当前请求。如果不需要工具就能回答，模型可能会直接回答而不调用工具。
问：可以同时定义多个工具吗？
答：是的，可以在tools数组中定义多个工具。模型会根据用户请求选择最合适的工具进行调用。多个工具可以用于不同的任务类型，如天气查询、股票查询、数据库操作等。建议将相关功能的工具分组，避免提供过多不相关的工具。
问：工具调用的结果如何传递回模型？
答：工具调用的结果需要作为新的消息添加到messages数组中，通常使用”tool”角色。模型会根据工具返回的结果继续生成响应。这个过程可能需要多轮交互：模型调用工具，执行工具，返回结果，模型处理结果，可能再次调用工具或生成最终答案。
问：如何处理工具调用失败的情况？
答：当工具调用失败时，应该将错误信息作为工具结果返回给模型。模型会根据错误信息调整策略，可能尝试其他方法或向用户说明问题。建议在工具实现中添加详细的错误处理和日志记录，便于调试和监控。
问：tools参数会影响API响应时间吗？
答：tools参数本身不会显著影响API响应时间。但是，如果模型决定调用工具，整个交互过程会包括工具调用和结果返回，这会增加总体的响应时间。工具本身的执行时间也会影响整体性能。建议优化工具实现，确保快速响应。
问：可以在流式响应中使用工具吗？
答：是的，工具调用可以在流式响应中使用。当模型决定调用工具时，会生成一个特殊的工具调用消息，流式传输会暂停。工具执行完成后，将结果作为新消息发送，模型继续生成响应。需要注意的是，流式响应中的工具调用需要客户端进行特殊处理，识别工具调用消息和普通文本消息。

OpenAI API兼容格式目录

请求格式概览
请求参数详解
- model
- messages
- temperature
- max_tokens
- stream
- stop
- top_p
- n
- presence_penalty
- frequency_penalty
- user
- response_format
- tools
- tool_choice
- logit_bias
- logprobs
- top_logprobs
- seed
常见组和用法
附录