Vapi：开发者优先的低延迟语音 Agent 平台上手攻略

为什么需要 Vapi：语音 Agent 从“能跑”到“能上线”

自建语音 Agent 的经典链路是“音频流 → 转写 → LLM → 合成 → 播放”，但真正上线还要额外解决四类问题：一是“用户到底说完没有”的检测，检测不准会抢话或冷场；二是用户中途打断时，如何停止合成并带着上下文重新进入对话；三是电话线路（PSTN）接入需要号码、中继与通话控制能力；四是并发与扩容，高峰期不能掉链子。每一层都有现成组件，但串起来调试通常以周为单位，且每一跳都在累积延迟。

Vapi 把上述能力收拢为一个托管运行时，对外暴露三个核心概念：Assistant（系统提示词、模型、语音、转写、工具等配置）、Call（一次通话会话）、Phone Number（号码线路）。开发者不需要管理媒体服务器，通过 REST API 或 SDK 创建通话，通话结束后自动拿到转写、录音和 EOCR（含摘要、成功评估、结构化数据、成本明细）。计费按分钟，成本透明，特别适合把语音交互当作产品功能而非基础设施的团队。

与开源框架（如 LiveKit Agents）相比，Vapi 是“托管运行时”：省掉运维，但深度定制受平台能力边界限制；与 Retell AI、Bland AI 等同类平台相比，Vapi 的差异化在配置即 API、工具调用机制和开发者文档体验。选型时先明确一件事：是要快速上线，还是要彻底掌控底层管线。

安装与环境配置：拿到 Key 三步就绪

Vapi 没有本地服务可装，核心是拿到两把 Key 并装好 SDK。注册后在控制台 API Keys 页面复制：Private Key 用于服务端（创建通话、管理资源），Public Key 用于浏览器端（Web SDK 初始化）。随后安装 Server SDK（后端集成）与 Web SDK（浏览器通话）。

验证命令返回 [] 即表示鉴权通过。注意 Private Key 泄露等同于账号管理权限泄露，不要写进前端代码或提交到 Git 仓库。

# 1) 安装 Server SDK（服务端创建通话、管理资源）npm install @vapi-ai/server-sdk # 浏览器端集成npm install @vapi-ai/web @vapi-ai/react # Python 环境：官方 Python SDK 包名为 vapi-server-sdk# pip install vapi-server-sdk # 2) 配置环境变量（Private Key 只放服务端）export VAPI_API_KEY="你的_Private_Key" # 3) 验证 Key 是否有效：应返回 assistant 列表，新账号为空数组 []curl -s https://api.vapi.ai/assistant \  -H "Authorization: Bearer $VAPI_API_KEY"

快速上手：30 分钟打出第一通电话

最小可行路径：在 Playground 配好一个 Assistant → 购买一个号码 → 手机拨打验证 → 再用 API 批量外呼。Playground 是控制台内的可视化配置入口，能直接测试对话效果，也可以完全跳过它、全程用 API 定义 Assistant。

1. 控制台 → Assistants → 创建 Assistant：填写名称与系统提示词（如“你是某品牌售后助理，先核对订单号再回答问题”）；模型选 gpt-4o-mini（OpenAI，速度快、成本低）；语音选 11labs 的 paula；First Message 填开场白“您好，我是xx，请问有什么可以帮您”；转写（Transcriber）选 Deepgram，Turn Detection 保持默认 server-vad；保存后复制 assistantId。

2. 控制台 → Phone Numbers → 购买号码：直接购买一个美国号码（底层为 Twilio，约一分钟开通），在号码详情中绑定刚才创建的 Assistant。

3. 用手机拨打该号码：接通后应听到 First Message，对话结束挂断后，在 Calls 列表能看到该通话的状态、时长、成本，并可打开转写与录音回放。

4. 外呼自动化：用 Server SDK 创建 Call，即可把名单里的手机号批量发起外呼，代码如下。

运行脚本后控制台输出 Call ID，通话结束再执行一次查询即可拿到 EOCR 摘要。进阶技巧：用 assistantOverrides 在单次调用中覆盖 System Prompt 或语音，实现同一 Assistant 多话术；把 EOCR 中的 structuredData 字段回写 CRM，实现全自动留痕。

import Vapi from '@vapi-ai/server-sdk'import 'dotenv/config' const client = new Vapi({ token: process.env.VAPI_API_KEY }) // 用 Playground 里创建好的 assistantId 直接外呼const call = await client.calls.create({  phoneNumberId: process.env.PHONE_NUMBER_ID, // 控制台「Phone Numbers」中的号码 ID  customer: { number: '+14155550100', name: 'Demo' },  assistantId: 'your_assistant_id_here',})console.log('通话已发起，Call ID:', call.id) // 通话结束后查询详情（含 End of Call Report）const detail = await client.calls.get(call.id)console.log(detail.endOfCallReport?.summary)

核心能力详解：4 大支柱

支柱一：低延迟会话管线与打断处理。 Vapi 把“转写 → 模型 → 合成”组织成流式管线：音频边传边识别，模型边生成边合成，官方宣传端到端延迟通常低于 500ms（从用户结束说话到 Agent 开口）。管线上有两个关键参数：transcriber（转写服务商，如 Deepgram、OpenAI、Gladia）和 turn detection（判定“用户说完”的方式）。turn detection 有多种模式，如 server-vad（Vapi 服务端统一检测）、provider-vad（交由转写服务商的端点检测）等。打断处理（barge-in）由平台完成：用户插话时立即停止 TTS 播放，把“用户新输入 + 被打断内容摘要”重新交给模型，让 Agent 无缝接话。这两组配置直接决定通话是“抢话”还是“冷场”，是上线前必调的旋钮。

支柱二：“先思考再开口”（model.think）。 在 model 配置下增加 think 子配置（指定思考用的模型），Agent 会先用一个独立模型生成内部思考笔记，再让主模型基于笔记回答。适合金额计算、政策解释、多步推理等复杂问题；代价是每次回答多一次模型调用，延迟和 token 成本上升。是否开启应按问题复杂度决定，不建议全局默认开启。

支柱三：工具调用与结构化数据。 Assistant 可配置 Tools：Function Tool 按 JSON Schema 声明参数，LLM 判断调用时机并生成参数，Vapi 把调用转发到你提供的 HTTP 接口；Webhook Tool 则直接触发指定 URL。这一机制让语音 Agent 在通话中实时查订单、建工单、写 CRM。通话结束后，EOCR 自动产出：summary（摘要）、successEvaluation（是否达成通话目标）、structuredData（按自定义字段提取，如“客户意向：高/中/低”）、costBreakdown（成本明细）与完整转写。业务系统对接 EOCR 即可实现自动留痕与质检，无需人工抽听录音。

支柱四：电话与 Web 双端接入。 电话侧：控制台可直接购买号码并绑定 Assistant；已有 Twilio 账号可 BYO（Bring Your Own Twilio）接入，适合国际号码和已有线路资源。Web 侧：@vapi-ai/web 提供浏览器实时通话——new Vapi(publicKey) 初始化，vapi.start(assistantId) 开始通话、vapi.stop() 结束，完全不需要电话号码；@vapi-ai/react 提供 useVapi Hook 与 VapiComponent，适合 React 产品快速嵌入。Web 与电话共用同一套 Assistant 配置，同一话术两个入口都能跑。

生产部署与监控：从上线到运维

配置即代码。 不建议在控制台手工维护生产配置。Assistant 的完整定义是 JSON，用 POST /assistant 和 PATCH /assistant/:id 创建与更新，把配置存进 Git 仓库并在 CI 中同步。单次通话用 assistantOverrides 覆盖提示词、模型或语音，做 A/B 测试和灰度，避免为每个变体新建 Assistant 造成配置爆炸。

号码与呼叫策略。 国内及国际线路建议 BYO Twilio 并完成企业资质认证，注意主叫号码实名与呼叫时段合规。外呼走 POST /call 或 SDK 的 calls.create，必须提供 phoneNumberId（从哪条线路呼出）、customer.number（打给谁，E.164 格式）与 assistant 或 assistantId。批量外呼前先小流量验证号码信誉与接通率，再逐步放量，避免因号码被标记导致接通率骤降。

可观测性与成本。 控制台 Calls 页面提供逐通话的状态、实时日志（转写/模型/合成各阶段事件）、延迟与成本；API 侧 GET /call/:id 拿到完整 Call 对象，转写与录音地址在 artifacts 中。成本控制手段：给 Assistant 设置 maxDurationSeconds 限制单通通话时长；关注 EOCR 中的成本明细按模型拆分费用，发现异常模型调用及时收敛；工具（Webhook Tool）的请求日志在业务侧也保留一份，便于定位调用失败。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>Key 混淆：Private Key 仅用于服务端，Web SDK 必须用 Public Key；把 Private Key 放进前端代码等于把账号管理权限公开，任何人可代你发起通话并产生费用。</li><li>号码未绑定：外呼前确认 phoneNumberId 已绑定 Assistant，customer.number 必须为 E.164 格式（如 +14155550100），否则会报错或拨打失败。</li><li>turn detection 不调优：默认 server-vad 对多数场景可用，但嘈杂环境或语速差异大时需调整，否则出现抢话或应答迟钝，建议在 Playground 实测后再固化配置。</li><li>忽略 EOCR：每次通话的转写、摘要、结构化数据与成本都在 EOCR 中，上线前把 structuredData 接入 CRM/质检，而不是事后人工翻录音。</li><li>think 模式滥用：model.think 会引入额外模型调用，增加延迟与 token 成本，只对复杂问题开启，简单问答不要开。</li></ul>

AI 应用场景

常见误区

面试题

参考来源

• webpageVapi 官网产品介绍、定价与行业案例
• webpage@vapi_ai 官方 X产品动态与社区互动