Chat（工具tools调用） - 数字先锋API文档

## Chat Completions API（Tools 工具调用）文档

## 1）接口说明

所有对话模型均可使用本接口进行文本对话与工具调用。
只需修改 `model` 为已开通的模型名。

```http
POST /v1/chat/completions
```

Base URL:
```text
https://api.cxsee.com
```

完整地址：
```text
https://api.cxsee.com/v1/chat/completions
```

---

## 2）认证方式

```http
Authorization: Bearer sk-your_api_key
Content-Type: application/json
```

---

## 3）核心能力

- 普通对话补全（chat completion）
- Tools 工具调用（function calling）
- 流式输出（`stream: true`）
- 可配置采样参数（`temperature`、`top_p` 等）

---

## 4）请求参数

| 参数 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `model` | string | 是 | 模型名称 |
| `messages` | array | 是 | 对话消息数组 |
| `temperature` | number | 否 | 采样温度，通常 0~2 |
| `top_p` | number | 否 | nucleus sampling |
| `n` | integer | 否 | 返回候选数量 |
| `stream` | boolean | 否 | 是否流式返回 |
| `stop` | string/array | 否 | 停止词 |
| `max_tokens` | integer | 否 | 最大输出 token |
| `presence_penalty` | number | 否 | 话题新颖度惩罚 |
| `frequency_penalty` | number | 否 | 重复惩罚 |
| `logit_bias` | object/null | 否 | token 偏置 |
| `user` | string | 否 | 终端用户标识 |
| `response_format` | object | 否 | 结构化输出控制 |
| `seed` | integer | 否 | 随机种子（如支持） |
| `tools` | array | 否 | 可调用工具列表（函数定义） |
| `tool_choice` | string/object | 否 | 工具调用策略（auto/none/指定工具） |

> 说明：建议使用 `seed`（兼容主流 SDK 习惯）。

---

## 5）Tools 定义格式

`tools` 中每一项通常为：

```json
{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "根据城市查询天气",
    "parameters": {
      "type": "object",
      "properties": {
        "city": { "type": "string", "description": "城市名，如 Beijing" },
        "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
      },
      "required": ["city"]
    }
  }
}
```

---

## 6）请求示例（触发工具调用）

```bash
curl -X POST "https://api.cxsee.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {
        "role": "user",
        "content": "帮我查一下北京今天天气"
      }
    ],
    "temperature": 0.2,
    "stream": false,
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_weather",
          "description": "根据城市查询实时天气",
          "parameters": {
            "type": "object",
            "properties": {
              "city": { "type": "string", "description": "城市名" },
              "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
            },
            "required": ["city"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'
```

---

## 7）模型请求工具时的响应示例

```json
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1774039000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_123",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"北京\",\"unit\":\"celsius\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}
```

---

## 8）工具执行后回传（二次请求）

你的服务端执行 `get_weather` 后，将结果作为 `tool` 角色消息回传，再请求一次同接口：

```json
{
  "model": "gpt-4o-mini",
  "messages": [
    { "role": "user", "content": "帮我查一下北京今天天气" },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_123",
          "type": "function",
          "function": {
            "name": "get_weather",
            "arguments": "{\"city\":\"北京\",\"unit\":\"celsius\"}"
          }
        }
      ]
    },
    {
      "role": "tool",
      "tool_call_id": "call_123",
      "content": "{\"city\":\"北京\",\"temp\":26,\"condition\":\"晴\"}"
    }
  ]
}
```

最终模型会返回面向用户的自然语言答案。

---

## 9）流式（stream）说明

- `stream: true` 时返回 SSE 分片。
- 当工具调用发生时，增量中会出现 `delta.tool_calls` 字段。
- 客户端需按 `tool_call_id` 拼接完整函数名与参数。

---

## 10）错误码

- `400` 参数错误（tools schema 非法、messages 格式错误）
- `401` 认证失败
- `403` 模型无权限
- `429` 限流
- `500/502/503` 服务异常

---

## 11）最佳实践

1. 工具参数使用 JSON Schema，`required` 写清楚。
2. 工具名使用英文小写+下划线，稳定不变。
3. `temperature` 在工具场景建议 `0~0.3`，减少幻觉。
4. 不要让模型直连内部系统；由你服务端执行工具并做鉴权审计。
5. 对 `function.arguments` 做 JSON 解析兜底与字段校验。

---

上一篇：Chat（分析图片）下一篇：Chat（思考Thinking）