Rapida：端到端语音编排平台

Rapida 是一个用于设计、构建和大规模部署语音代理的开源平台。
它围绕三大核心原则构建：

• 可靠 — 专为生产级工作负载、实时音频和容错执行而设计
• 可观测性 — 深度洞察通话、延迟、指标及工具使用情况
• 可定制 — 灵活的架构，可适配任何大模型、工作流或企业级技术栈

Rapida 同时提供平台和框架，用于构建真实的语音代理——从低延迟音频流到编排、监控和集成。

Rapida 使用 Go 语言编写，并采用高度优化的 gRPC 协议，实现快速高效的双向通信。

---

架构

---

特性

• 实时语音编排
  使用 gRPC 以低延迟流式传输和处理音频。

• 大模型无关架构
  支持自定义模型——OpenAI、Anthropic、开源模型或自定义推理服务。

• 生产级可靠性
  内置重试机制、错误处理、通话生命周期管理及健康检查。

• 全面可观测性
  包括通话日志、流式事件、工具追踪、延迟细分、指标和仪表盘。

• 灵活的工具系统
  可为您的代理构建自定义工具和动作，或与任何后端系统集成。

• 开发者友好
  清晰的 API、模块化组件和简单配置。

• 企业就绪
  可扩展的设计、高效协议和可预测的性能。

文档与指南

https://doc.rapida.ai

前提条件

• Docker 和 Docker Compose（安装）
• 16GB+ 内存（适用于所有服务）

---

快速入门

只需四条命令即可运行所有服务：

# 克隆仓库
git clone https://github.com/rapidaai/voice-ai.git && cd voice-ai

# 设置并构建
make setup-local && make build-all

# 启动所有服务
make up-all

# 查看正在运行的服务
docker compose ps

服务已就绪（make up-all）：

• UI：http://localhost:3000
• API 网关（nginx）：http://localhost:8080
• Web API：默认仅限内部访问（容器网络）
• 助手 API：http://localhost:9007
• 终端点 API：http://localhost:9005
• 集成 API：http://localhost:9004

如需包含知识服务（OpenSearch + 文档 API），请运行：

make up-all-with-knowledge

随后：

• 文档 API：http://localhost:9010

停止服务：

make down-all

---

开发

针对特定服务开发

# 仅启动数据库
make up-db

# 仅启动 UI
make up-ui

# 仅启动助手 API
make up-assistant

# 列出所有启动命令
make help

查看日志

# 所有服务
make logs-all

# 特定服务
make logs-web
make logs-assistant

代码变更后重建

# 重建并重启单个服务
make rebuild-assistant

# 重建全部
make rebuild-all

配置服务

在启动前编辑环境文件：

• docker/web-api/.web.env - Web API（端口 9001）
• docker/assistant-api/.assistant.env - 助手 API（端口 9007）
• docker/endpoint-api/.endpoint.env - 终端点 API（端口 9005）
• docker/integration-api/.integration.env - 集成 API（端口 9004）
• docker/document-api/config.yaml - 文档 API（端口 9010）

在这些文件中添加您的 API 密钥（例如 OpenAI、Anthropic、Deepgram、Twilio 等）。

---

本地开发（无需 Docker）

Go 服务

# 安装依赖
go mod download

# 构建服务
go build -o bin/web ./cmd/web

# 运行服务
./bin/web

需要单独运行 PostgreSQL、Redis 和 OpenSearch。

React UI

cd ui

# 安装并运行
yarn install
yarn start:dev

# 构建用于生产
yarn build

---

故障排除

端口已被占用：

lsof -i :3000    # 查找进程
kill -9 <PID>    # 杀死该进程

服务无法启动：

make logs-all    # 检查日志
docker compose ps  # 验证状态

数据库问题：

# 测试连接
docker compose exec postgres psql -U rapida -d web_db -c "SELECT 1"

# 重置一切
make clean
make setup-local
make build-all
make up-all

---

所有命令

make help          # 显示所有可用命令
make setup-local   # 创建数据目录
make build-all     # 构建所有 Docker 镜像
make up-all        # 启动所有服务
make down-all      # 停止所有服务
make logs-all      # 查看所有日志
make clean         # 移除容器和卷
make restart-all   # 重启所有服务

---

贡献

请参阅 CONTRIBUTING.md 获取指南。

想要添加：

• 新的 STT/TTS 提供商？请查看 api/assistant-api/internal/transformer/
• 新的电话渠道？请查看 api/assistant-api/internal/telephony/

---

SDK 和工具

客户端 SDK

客户端 SDK 使您的前端能够支持交互式多用户体验。

语言	仓库	文档
Web (React)	rapida-react	文档
Web 小部件 (react)	react-widget

服务器 SDK

服务器 SDK 使您的后端能够构建和管理智能体。

语言	仓库	文档
Go	rapida-go	文档
Python	rapida-python	文档

贡献

对于希望贡献代码的开发者，请参阅我们的贡献指南。同时，也请通过在社交媒体以及各类活动和会议上分享 RapidaAi 来支持我们。

安全披露

为保护您的隐私，请勿在 GitHub 上公开安全问题。如有相关问题，请发送至 contact@rapida.ai，我们的团队将为您提供详细的解答。

许可证

Rapida 采用 GPL-2.0 开源许可证，并附加以下条件：

• 开源用户必须在 UI 组件中保持 Rapida 标志的可见性。
• 未来的许可条款可能会发生变化，但这不会影响已发布的版本。

针对企业使用，我们提供商业许可证，该许可证允许：

• 移除品牌标识
• 进行闭源使用
• 进行私有化修改 如需了解详情，请联系 sales@rapida.ai。

Rapida Voice AI 快速上手指南

Rapida 是一个开源的端到端语音编排平台，专为构建高可靠、可观测且可扩展的实时语音助手而设计。核心采用 Go 语言和 gRPC 协议，支持低延迟音频流处理及任意大模型（LLM）集成。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (需安装 WSL2)
• 核心依赖：
  • Docker 及 Docker Compose
  • Git
• 硬件要求：
  • 内存：16GB 或以上（运行全套服务所需）
  • CPU：建议 4 核以上
• 网络配置：
  • 需确保能访问 GitHub 以拉取代码。
  • 若需使用特定 AI 模型或电话服务，请提前准备好相关 API Key（如 OpenAI, Anthropic, Deepgram, Twilio 等）。

提示：国内开发者若遇到 git clone 速度慢的问题，可使用国内镜像源加速，或在克隆后手动替换远程地址。

安装步骤

通过以下 4 个命令即可在本地启动全套服务：

1. 克隆仓库并进入目录

   git clone https://github.com/rapidaai/voice-ai.git && cd voice-ai
   

2. 初始化环境与构建镜像

   make setup-local && make build-all
   

3. 启动所有服务

   make up-all
   

   (可选) 若需包含知识库服务（OpenSearch + Document API），请运行：

   make up-all-with-knowledge
   

4. 验证服务状态

   docker compose ps
   

基本使用

服务启动成功后，您可以通过以下地址访问核心组件：

• 用户界面 (UI): http://localhost:3000
• API 网关: http://localhost:8080
• Assistant API: http://localhost:9007
• Endpoint API: http://localhost:9005
• Integration API: http://localhost:9004
• Document API (仅当运行 up-all-with-knowledge 时): http://localhost:9010

配置 API Keys

在首次使用前，您需要配置第三方服务的凭证。编辑对应的环境变量文件：

• Web API: docker/web-api/.web.env
• Assistant API: docker/assistant-api/.assistant.env
• Endpoint API: docker/endpoint-api/.endpoint.env
• Integration API: docker/integration-api/.integration.env

在文件中填入您的 OPENAI_API_KEY, DEEPGRAM_API_KEY 等密钥，然后重启服务使其生效：

make restart-all

开发与调试

如果您需要针对特定服务进行开发或查看日志，可以使用以下快捷命令：

• 启动单个服务 (例如只启动数据库或 UI)：

  make up-db
  make up-ui
  

• 查看日志：

  # 查看所有服务日志
  make logs-all
  # 查看特定服务日志
  make logs-assistant
  

• 代码修改后重建：

  # 重建并重启 Assistant 服务
  make rebuild-assistant
  

停止服务

完成测试后，停止所有容器：

make down-all

如需彻底清理数据卷和容器，可执行：

make clean