> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tapapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 工具调用

> 函数调用、结构化输出和外部工具协作

工具调用适合让模型决定是否调用外部函数，例如查订单、查库存、调用搜索、写数据库或触发自动化流程。

<Warning>工具调用是进阶能力，不是所有文本模型都支持。实际支持情况以控制台、模型详情和真实请求测试为准。</Warning>

## 什么时候用工具调用

| 场景    | 例子                    |
| ----- | --------------------- |
| 查业务数据 | 查订单、查库存、查会员状态         |
| 调内部系统 | 创建工单、发送消息、更新 CRM      |
| 自动化流程 | 调 n8n、Make、内部 webhook |
| 结构化动作 | 让模型选择下一步要调用的函数        |

如果你只是想让模型输出固定 JSON，优先看 `response_format` 或普通 JSON prompt；如果模型需要调用你的系统，再考虑工具调用。

## 典型流程

1. 应用把可用工具和参数 schema 发给模型
2. 模型返回需要调用的工具名和参数
3. 应用执行真实工具
4. 应用把工具结果再发回模型
5. 模型生成最终回答

## 字段口径

| 字段            | 说明              |
| ------------- | --------------- |
| `tools`       | 传入可用工具定义        |
| `tool_choice` | 控制是否强制或允许模型调用工具 |
| `tool_calls`  | 模型返回的工具调用请求     |

这些字段沿用 OpenAI-compatible 的常见结构，但不同模型支持程度不同。生产接入前必须用目标模型做真实测试。

Tapapi 负责把请求转发给模型并返回模型的工具调用意图；真正的查库、发货、扣费、发消息、调用 webhook 等动作必须由你的业务系统执行和鉴权。不要让模型返回的参数直接绕过业务权限。

工具定义通常包含：

```json theme={null}
{
  "type": "function",
  "function": {
    "name": "get_order",
    "description": "查询订单状态",
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" }
      },
      "required": ["order_id"]
    }
  }
}
```

## 安全边界

* 工具调用结果不能直接信任，要由应用执行权限控制
* 涉及扣费、发货、删数据等动作时，必须有业务侧确认或风控
* 工具参数要做 schema 校验和白名单校验
* 记录 `request_id`、业务用户、工具名、参数摘要、执行结果和最终回答，方便排查成本和异常行为
* 工具失败后不要无限重试，按 [错误码与重试](/errors) 处理

## 接入前检查

* 确认目标模型在控制台或模型详情中标记支持工具调用
* 目标模型是否返回 `tool_calls`
* JSON Schema 是否被目标模型稳定遵循
* 工具参数是否经过业务侧校验
* n8n / Make / 内部 webhook 是否有鉴权和重试
* 如果使用流式输出，确认工具调用 chunk 能被你的 SDK 或解析器正确处理

## 下一步

| 场景             | 文档                                                    |
| -------------- | ----------------------------------------------------- |
| 文本接口基础         | [Chat Completions](/text-generation/chat-completions) |
| 流式输出           | [流式输出](/text-generation/streaming)                    |
| 错误与重试          | [错误码与重试](/errors)                                     |
| n8n / Make 自动化 | [n8n / Make](/integrations/n8n-make)                  |