官方 Function Calling 调用 API 文档

本接口用于创建一个聊天补全（Chat Completion）。通过提供消息列表和可选的工具列表（Functions），模型可以生成文本回复，或生成符合特定 JSON 架构的参数以调用外部函数。

1. 接口信息

接口地址: https://api.codingplanx.ai/v1/chat/completions
请求方法: POST
内容类型: application/json
认证方式: Authorization: Bearer {{YOUR_API_KEY}}

2. 请求参数

2.1 请求头 (Headers)

参数名	类型	必选	示例	描述
Content-Type	string	是	`application/json`	固定为 `application/json`
Accept	string	是	`application/json`	建议固定为 `application/json`
Authorization	string	是	`Bearer sk-xxxxxx`	API 密钥认证

2.2 请求体 (Body)

参数名	类型	必选	默认值	描述
model	string	是	-	使用的模型 ID（如 `gpt-4o`, `gpt-3.5-turbo` 等）。
messages	array	是	-	至今为止对话的消息列表。每个对象包含 `role` ("system", "user", "assistant", "tool") 和 `content`。
tools	array	是	-	模型可以调用的工具列表。目前仅支持 `type: "function"`。用于定义函数名、描述及参数。
tool_choice	object/str	否	`auto`	控制模型调用哪个函数。`none`: 不调用；`auto`: 自动选择；`{"type": "function", "function": {"name": "xxx"}}`: 强制调用特定函数。
temperature	number	否	1	采样温度 (0-2)。越高越随机，越低越确定。
top_p	number	否	1	核采样概率。
n	integer	否	1	为每条输入消息生成的聊天补全选择数。
stream	boolean	否	false	是否流式传输。设置为 `true` 时，标记将作为服务器发送事件 (SSE) 发送。
stop	string/array	否	null	API 停止生成标记的停止序列。
max_tokens	integer	否	inf	生成的最大标记数。
presence_penalty	number	否	0	介于 -2.0 和 2.0 之间。增加模型谈论新话题的可能性。
frequency_penalty	number	否	0	介于 -2.0 和 2.0 之间。降低模型重复相同内容的可能性。
response_format	object	否	-	指定输出格式。如 `{"type": "json_object"}` 可启用 JSON 模式。
seed	integer	否	-	若指定，系统将尽力确定性地采样，使相同种子和参数的请求返回相同结果。
user	string	否	-	代表最终用户的唯一标识符，用于监控滥用。

3. 请求示例

{
    "model": "gpt-4o",
    "messages": [
        {
            "role": "user",
            "content": "北京今天天气怎么样"
        }
    ],
    "tools": [
        {
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "获取指定位置的当前天气",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "城市名称，例如：北京市"
                        },
                        "unit": {
                            "type": "string",
                            "enum": ["celsius", "fahrenheit"]
                        }
                    },
                    "required": ["location"]
                }
            }
        }
    ],
    "tool_choice": "auto",
    "temperature": 0.8
}

4. 响应参数

4.1 响应体结构

参数名	类型	描述
id	string	该次请求的唯一标识符。
object	string	对象类型，通常为 `chat.completion`。
created	integer	Unix 时间戳（秒）。
choices	array	包含生成的响应列表。
└ message	object	包含 `role`, `content` 以及可能的 `tool_calls`。
└ finish_reason	string	停止原因。`stop` (自然停止), `length` (达到 max_tokens), `tool_calls` (需要调用工具)。
usage	object	消耗情况：`prompt_tokens`, `completion_tokens`, `total_tokens`。

4.2 响应示例 (正常文本)

{
    "id": "chatcmpl-123",
    "object": "chat.completion",
    "created": 1677652288,
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "北京今天天气晴朗，气温 25 摄氏度。"
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 9,
        "completion_tokens": 12,
        "total_tokens": 21
    }
}

5. FAQs (常见问题)

Q1: 什么是 Function Calling (工具调用)? A: 这是一种让模型具备调用外部能力的方式。模型不会直接执行代码，而是根据你的描述，生成一个包含函数名和所需参数的 JSON 对象。你需要提取这个 JSON，在自己的本地或服务器执行函数，然后将结果传回给模型。

Q2: 为什么我设置了 tools，模型却没有返回 tool_calls? A: 可能有以下原因：

模型认为用户的提问不需要调用该函数。
你的函数描述 (description) 不够清晰，导致模型无法匹配意图。
tool_choice 被显式设置为了 none。
模型能力限制（建议优先使用 gpt-4o 或 gpt-3.5-turbo 等支持工具调用的模型）。

Q3: 如何强制模型必须调用某个函数？ A: 你可以将 tool_choice 设置为特定对象，例如： "tool_choice": {"type": "function", "function": {"name": "get_current_weather"}}。这样即使模型觉得不需要，也会尝试生成该函数的参数。

Q4: 如果 finish_reason 是 length，我该怎么办？ A: 这意味着生成的回复超过了 max_tokens 限制或模型的上下文窗口限制。你可以尝试调大 max_tokens 参数，或者缩减 messages 历史记录的长度。

Q5: 使用 JSON 模式 (JSON Mode) 有什么注意事项？ A: 当设置 response_format: { "type": "json_object" } 时，必须在 System 或 User 消息中明确要求模型输出 JSON 格式的内容（例如包含“以 JSON 格式回复”），否则模型可能会陷入死循环输出空格。

Q6: 如何处理多个工具调用？ A: 在一次请求中，模型可能会同时产生多个工具调用（例如同时查询北京和上海的天气）。你需要遍历 choices[0].message.tool_calls 数组，并为每一个调用执行对应的本地逻辑。