# Vapi

[Vapi](https://docs.vapi.ai/) 是用于构建和运行网页及电话对话语音助手的托管平台。它负责协调通话传输、语音识别、语言模型轮次、语音生成、工具和助手编排，使应用能够通过已配置的助手提供实时语音体验。

Vapi 的 Custom LLM 服务提供方将这种编排与模型端点分离。Vapi 助手可以继续在 Vapi 中使用其语音服务、通话处理和工具，同时把兼容 OpenAI 的语言模型请求通过 AISIX 发送。这样，团队无需把 AISIX 当作语音运行时，就能在 LLM 环节应用 AISIX 模型别名、调用方授权、路由和遥测。

请使用 AISIX 兼容 OpenAI 的 API 根路径、AISIX 模型别名以及包含专用 AISIX 调用方 API Key 的凭证配置 Vapi 模型。

## 前置条件[​](#prerequisites "前置条件的直接链接")

开始前，请准备以下内容：

* Vapi 账户和一个可编辑的助手。
* 可从公网访问的 AISIX HTTPS 代理 URL。
* 专用于该助手的 AISIX 调用方 API Key。
* 调用方 Key 可以通过[兼容 OpenAI 的 API](https://docs.apiseven.com/ai-gateway/endpoints/openai-compatible-chat.md)访问的模型别名。

请把上游服务提供方凭证保存在 AISIX 中。Vapi 只应存储受限的 AISIX 调用方 Key。

## 配置 Custom LLM[​](#configure-a-custom-llm "配置 Custom LLM的直接链接")

首先，把 AISIX 调用方 Key 存储为组织级 Custom LLM 凭证：

1. 在 Vapi Dashboard 中打开 **Settings → Integrations**。
2. 在 **Model Providers** 下选择 **Configure Custom LLM**。
3. 在 **API Key** 中输入 AISIX 调用方 Key。将可选的 OAuth2 字段留空。
4. 选择 **Save**。

接下来，配置助手以使用 AISIX：

1. 打开 **Assistants**，然后选择要配置的助手。
2. 选择 **Model** 卡片，然后选择 **Custom LLM**。
3. 将 **Model** 设置为 AISIX 模型别名，例如 `voice-agent-prod`。
4. 将 **Custom LLM URL** 设置为 AISIX API 根路径并包含 `/v1`，例如 `https://gateway.example.com/v1`。
5. Vapi 保存草稿后，选择 **Publish** 并检查模型变更。
6. 选择 **Next**，在 **Publish Description** 下输入版本名称，然后再次选择 **Publish**。

Vapi 把该 URL 用作 OpenAI 客户端的基础 URL，并附加 `/chat/completions`。它在调用自定义端点时，会把凭证作为 Bearer Token 放入 `Authorization` 请求头。AISIX 将该值作为调用方 Key 进行身份认证。

AISIX 别名及其上游模型必须支持流式 Chat Completions。Vapi 可以在收到文本增量时开始合成答案。

## 验证集成[​](#verify-the-integration "验证集成的直接链接")

运行一段简短的网页或电话测试，并要求返回一句话。

确认以下结果：

* Vapi 以语音形式返回响应。
* AISIX 记录一条成功的 `POST /v1/chat/completions` 请求。
* 调用方 Key 和模型别名与专用 Vapi 配置一致。

Vapi 负责通话录音设置、对话文本、语音服务和电话事件。AISIX 只治理 Vapi 通过自定义端点发送的 LLM 交互。

## 单独验证工具[​](#verify-tools-separately "单独验证工具的直接链接")

Vapi 可以在 Custom LLM 请求中包含兼容 OpenAI 的工具定义。如果助手使用工具，请先验证通过 AISIX 传输的流式函数名称、参数和工具调用 ID，再在生产环境中依赖该集成。

Vapi 工具执行还可能涉及助手、工具或账户级 Server URL。这些 Webhook 端点与 Custom LLM URL 相互独立，不会被 AISIX 替换。

## 排查 Vapi 请求问题[​](#troubleshoot-vapi-requests "排查 Vapi 请求问题的直接链接")

| 现象               | 检查项                                                                |
| ------------------ | --------------------------------------------------------------------- |
| 身份认证失败       | 确认 Custom LLM 凭证包含 AISIX 调用方 Key，而不是上游服务提供方 Key。 |
| 找不到模型         | 确认 Vapi 模型值是调用方 Key 可见的 AISIX 别名。                      |
| 响应延迟           | 分别检查 Vapi Transcriber 和语音延迟，以及 AISIX 上游延迟。           |
| 文本成功但工具失败 | 验证 Vapi 的工具服务器配置以及模型的流式函数调用格式。                |

## 后续步骤[​](#next-steps "后续步骤的直接链接")

* [流式传输](https://docs.apiseven.com/ai-gateway/endpoints/streaming.md)：了解流式响应传输。
* [工具调用](https://docs.apiseven.com/ai-gateway/endpoints/tool-calling.md)：验证网关工具调用约定。
* [API Key 和模型限流](https://docs.apiseven.com/ai-gateway/traffic-controls/rate-limits.md)：限制助手流量。
