端到端开源语音智能体平台: 通过 JSON 快速构建以语音为核心的对话式助手。

Discord | 托管文档 | 官网

[!NOTE] 我们正在积极寻找维护者。

简介

Bolna 是一个端到端的开源生产就绪框架，用于快速构建基于大语言模型的语音驱动对话应用。

演示

https://github.com/bolna-ai/bolna/assets/1313096/2237f64f-1c5b-4723-b7e7-d11466e9b226

这个仓库是什么？

该仓库包含了构建语音 AI 应用的完整编排平台。它通过 WebSocket 结合不同的 ASR、LLM 和 TTS 提供商及模型来技术性地编排语音对话。

组件

Bolna 帮助您创建 AI 语音智能体，这些智能体可以被指令执行以下任务：

1. 编排平台（此开源仓库）
2. 托管 API（https://docs.bolna.ai/api-reference/introduction），基于此编排平台构建 [目前为闭源]
3. 使用托管 API 和 Tailwind CSS 的无代码 UI 交互平台 https://platform.bolna.ai/ [目前为闭源]

开发理念

1. 任何集成、增强或功能最初都会进入这个开源包，因为它构成了我们托管 API 和仪表板的核心。
2. 随后，我们会根据需要公开 API 或对现有 API 进行修改。
3. 最后，我们将更新推送到 UI 仪表板。

graph LR;
    A[Bolna 开源] -->B[托管 API];
    B[托管 API] --> C[托管 Playground]

支持的提供商和模型

1. 使用电话服务提供商如 Twilio、Plivo、Exotel（即将推出）、Vonage（即将推出）等发起电话呼叫。
2. 使用 Deepgram、Azure 等进行对话转录。
3. 使用 OpenAI、DeepSeek、Llama、Cohere、Mistral 等 LLM 处理对话。
4. 使用 AWS Polly、ElevenLabs、Deepgram、OpenAI、Azure、Cartesia、Smallest 等将 LLM 的响应合成回电话音频。

有关所有支持提供商的深入信息，请参阅 文档。

本地示例设置 [将移至另一个仓库]

基本的本地设置包括使用 Twilio 或 Plivo 进行电话通信。我们已将设置容器化在 local_setup/ 中。用户需要从 .env.sample 文件中填充环境变量文件 .env。

该设置包含四个容器：

1. 电话网络服务器：
   • 如果选择 Twilio：要发起呼叫，需要先设置一个 Twilio 账户
   • 如果选择 Plivo：要发起呼叫，需要先设置一个 Plivo 账户
2. Bolna 服务器：用于创建和管理智能体
3. ngrok：用于隧道转发。用户需要将 authtoken 添加到 ngrok-config.yml
4. redis：用于持久化智能体和提示数据。

快速开始

最简单的方式是使用提供的脚本：

cd local_setup
chmod +x start.sh
./start.sh

该脚本会检查 Docker 依赖项，启用 BuildKit 构建所有服务，并以分离模式启动它们。

手动设置

或者，您可以手动构建并运行这些服务：

1. 确保已安装 Docker 和 Docker Compose V2
2. 启用 BuildKit 以加快构建速度：

   export DOCKER_BUILDKIT=1
   export COMPOSE_DOCKER_CLI_BUILD=1
   

3. 构建镜像：

   docker compose build
   

4. 运行服务：

   docker compose up -d
   

如果只想运行特定服务：

docker compose up -d bolna-app twilio-app
# 或
docker compose up -d bolna-app plivo-app

Docker 容器启动后，您就可以开始创建智能体并指示它们发起呼叫了。

示例智能体：创建、使用并开始拨打电话

您可以尝试来自 example.bolna.dev 的不同智能体。

编程式使用（最小示例）

您也可以直接在 Python 中构建并运行一个智能体，而无需本地电话设置。

示例脚本：examples/simple_assistant.py

import asyncio
from bolna.assistant import Assistant
from bolna.models import (
    Transcriber,
    Synthesizer,
    ElevenLabsConfig,
    LlmAgent,
    SimpleLlmAgent,
)


async def main():
    assistant = Assistant(name="demo_agent")

    # 配置音频输入（ASR）
    transcriber = Transcriber(provider="deepgram", model="nova-2", stream=True, language="en")

    # 配置 LLM
    llm_agent = LlmAgent(
        agent_type="simple_llm_agent",
        agent_flow_type="streaming",
        llm_config=SimpleLlmAgent(
            provider="openai",
            model="gpt-4o-mini",
            temperature=0.3,
        ),
    )

    # 配置音频输出（TTS）
    synthesizer = Synthesizer(
        provider="elevenlabs",
        provider_config=ElevenLabsConfig(
            voice="George", voice_id="JBFqnCBsd6RMkjVDRZzb", model="eleven_turbo_v2_5"
        ),
        stream=True,
        audio_format="wav",
    )

    # 构建单一连贯的管道：转录器 -> LLM -> 合成器
    assistant.add_task(
        task_type="conversation",
        llm_agent=llm_agent,
        transcriber=transcriber,
        synthesizer=synthesizer,
        enable_textual_input=False,
    )

    # 流式输出结果
    async for chunk in assistant.execute():
        print(chunk)


if __name__ == "__main__":
    asyncio.run(main())

如何运行：

export OPENAI_API_KEY=...
export DEEPGRAM_AUTH_TOKEN=...
export ELEVENLABS_API_KEY=...
python examples/simple_assistant.py

这展示了编排和流式输出。对于电话通信，请使用 local_setup/ 中的服务。

注意：对于基于 REST 的使用（通过 HTTP 进行智能体的 CRUD 操作），请参阅仓库根目录下的 API.md。

预期输出格式：assistant.execute() 是一个异步生成器，每次产生一个任务结果字典（类似事件的块）。具体的键取决于配置的工具或提供商；应将其视为流，并逐步处理。

仅文本管道示例

如果您想要一个仅包含文本的流程（无需转录器/合成器），可以启用仅文本管道：

示例脚本：examples/text_only_assistant.py

import asyncio
from bolna.assistant import Assistant
from bolna.models import LlmAgent, SimpleLlmAgent


async def main():
    assistant = Assistant(name="text_only_agent")

    llm_agent = LlmAgent(
        agent_type="simple_llm_agent",
        agent_flow_type="streaming",
        llm_config=SimpleLlmAgent(
            provider="openai",
            model="gpt-4o-mini",
            temperature=0.2,
        ),
    )

    # 无转录器/合成器；启用仅文本管道
    assistant.add_task(
        task_type="conversation",
        llm_agent=llm_agent,
        enable_textual_input=True,
    )

    async for chunk in assistant.execute():
        print(chunk)


if __name__ == "__main__":
    asyncio.run(main())

运行方法（仅文本）：

export OPENAI_API_KEY=...
python examples/text_only_assistant.py

预期输出格式：assistant.execute() 每个任务步骤会流式返回字典；字段因配置而异。请逐块处理。

使用您自己的提供商

您可以通过填充 .env 文件来使用您自己的提供商密钥。

ASR 提供商

目前支持的 ASR 提供商如下：

提供商	需要在 .env 文件中添加的环境变量
Deepgram	DEEPGRAM_AUTH_TOKEN

 

LLM 提供商

Bolna 使用 LiteLLM 包来支持多种 LLM 集成。

目前支持的 LLM 提供商家族如下： https://github.com/bolna-ai/bolna/blob/10fa26e5985d342eedb5a8985642f12f1cf92a4b/bolna/providers.py#L30-L47

对于基于 LiteLLM 的 LLM，根据您的使用场景，在 .env 文件中添加以下内容之一：

LITELLM_MODEL_API_KEY：LLM 的 API 密钥
LITELLM_MODEL_API_BASE：托管 LLM 的 URL
LITELLM_MODEL_API_VERSION：适用于 Azure 等 LLM 的 API 版本

对于通过 VLLM 托管的 LLM，在 .env 文件中添加：
VLLM_SERVER_BASE_URL：使用 VLLM 托管的 LLM 的 URL

 

TTS 提供商

目前支持的 TTS 提供商如下： https://github.com/bolna-ai/bolna/blob/c8a0d1428793d4df29133119e354bc2f85a7ca76/bolna/providers.py#L7-L14

提供商	需要在 .env 文件中添加的环境变量
AWS Polly	通过系统范围内的凭据从 ~/.aws 访问
Elevenlabs	ELEVENLABS_API_KEY
OpenAI	OPENAI_API_KEY
Deepgram	DEEPGRAM_AUTH_TOKEN
Cartesia	CARTESIA_API_KEY
Smallest	SMALLEST_API_KEY

 

电话提供商

目前支持的电话提供商如下：

提供商	需要在 .env 文件中添加的环境变量
Twilio	TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PHONE_NUMBER
Plivo	PLIVO_AUTH_ID, PLIVO_AUTH_TOKEN, PLIVO_PHONE_NUMBER

开源与托管 API

我们过去曾尝试同时维护开源和托管解决方案（通过 API 和 UI 控制面板）。

由于时间紧张而非兴趣不足，我们曾在维护此仓库上有所波动。

目前，我们仍在为社区维护它，并致力于提升语音 AI 的普及度。

尽管该仓库完全开源，但如果您对托管服务或更定制化的解决方案感兴趣，仍可与我们联系。

扩展其他电话提供商

如果您希望扩展并添加 Vonage、Telnyx 等其他电话提供商，请遵循以下指南：

1. 确保该电话提供商支持双向流媒体
2. 在 input_handlers/telephony_providers 中添加特定于电话的输入处理器文件，编写从 telephony.py 类扩展的自定义函数
   1. 该文件主要包含如何从电话提供商处接收不同类型的事件数据包
3. 在 output_handlers/telephony_providers 中添加特定于电话的输出处理器文件，编写从 telephony.py 类扩展的自定义函数
   1. 这主要涉及将合成器类生成的音频转换为支持的音频格式，并通过电话提供商提供的 WebSocket 流式传输
4. 最后，您需要编写一个专用服务器，例如 local_setup 中提供的示例 twilio_api_server.py，以通过 WebSocket 发起呼叫。

贡献

我们欢迎各种形式的贡献：无论大小，只要有助于改善这一社区资源即可。

1. 当前有许多 未解决的问题，您可以从中选择一个开始
2. 如果您有改进建议，想贡献简单的修复（如纠正错别字），或想解决明显的 bug，请随时发起新问题或提交拉取请求
3. 如果您正在考虑对该仓库进行较大规模的更改或添加，无论是结构还是功能方面，请先创建一个问题 新建问题 :octocat: 并概述您的拟议变更。这将使我们在您投入大量时间和精力之前进行讨论。感谢您的合作与理解

Bolna 快速上手指南

Bolna 是一个端到端的开源语音智能体（Voice Agent）平台，支持通过 JSON 配置快速构建基于大语言模型（LLM）的语音对话应用。它协调 ASR（语音转文字）、LLM（大模型）和 TTS（文字转语音）组件，通过 WebSocket 实现实时语音交互。

环境准备

系统要求

• 操作系统: Linux, macOS, Windows (需安装 WSL2 或 Docker Desktop)
• Docker: 推荐安装 Docker Engine 及 Docker Compose V2
• Python: 3.9+ (用于本地脚本运行)

前置依赖与账号

在开始之前，你需要准备以下服务的 API Key：

1. LLM 提供商: 如 OpenAI (OPENAI_API_KEY)
2. ASR 提供商: 如 Deepgram (DEEPGRAM_AUTH_TOKEN)
3. TTS 提供商: 如 ElevenLabs (ELEVENLABS_API_KEY)
4. 电话服务 (可选): 如需拨打电话，需配置 Twilio 或 Plivo 账号。

注意: 国内开发者若无法直接访问上述服务，请自行配置网络代理或在 .env 文件中设置相应的代理地址。

安装步骤

方式一：使用 Docker 快速启动（推荐）

此方式包含完整的编排环境（含电话服务模拟、Redis 等）。

1. 克隆仓库并进入本地设置目录：

git clone https://github.com/bolna-ai/bolna.git
cd bolna/local_setup

2. 配置环境变量： 复制示例文件并填入你的 API Key：

cp .env.sample .env
# 编辑 .env 文件，填入 OPENAI_API_KEY, DEEPGRAM_AUTH_TOKEN 等

3. 运行启动脚本： 该脚本会自动检查依赖、构建镜像并启动服务。

chmod +x start.sh
./start.sh

手动启动备选方案:

export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1
docker compose build
docker compose up -d

方式二：Python 本地运行（仅核心逻辑）

如果你只想测试核心编排逻辑而不需要电话服务，可直接使用 Python 运行。

1. 安装依赖（假设已克隆项目）：

pip install -e .

2. 设置环境变量：

export OPENAI_API_KEY=your_key
export DEEPGRAM_AUTH_TOKEN=your_token
export ELEVENLABS_API_KEY=your_key

基本使用

示例 1：构建最小化语音助手

以下脚本演示了如何创建一个包含“听 (ASR) -> 思考 (LLM) -> 说 (TTS)"完整流程的语音助手。

创建文件 simple_assistant.py：

import asyncio
from bolna.assistant import Assistant
from bolna.models import (
    Transcriber,
    Synthesizer,
    ElevenLabsConfig,
    LlmAgent,
    SimpleLlmAgent,
)


async def main():
    assistant = Assistant(name="demo_agent")

    # 配置音频输入 (ASR) - 使用 Deepgram
    transcriber = Transcriber(provider="deepgram", model="nova-2", stream=True, language="en")

    # 配置 LLM - 使用 OpenAI
    llm_agent = LlmAgent(
        agent_type="simple_llm_agent",
        agent_flow_type="streaming",
        llm_config=SimpleLlmAgent(
            provider="openai",
            model="gpt-4o-mini",
            temperature=0.3,
        ),
    )

    # 配置音频输出 (TTS) - 使用 ElevenLabs
    synthesizer = Synthesizer(
        provider="elevenlabs",
        provider_config=ElevenLabsConfig(
            voice="George", voice_id="JBFqnCBsd6RMkjVDRZzb", model="eleven_turbo_v2_5"
        ),
        stream=True,
        audio_format="wav",
    )

    # 构建管道：transcriber -> llm -> synthesizer
    assistant.add_task(
        task_type="conversation",
        llm_agent=llm_agent,
        transcriber=transcriber,
        synthesizer=synthesizer,
        enable_textual_input=False,
    )

    # 执行并流式输出结果
    async for chunk in assistant.execute():
        print(chunk)


if __name__ == "__main__":
    asyncio.run(main())

运行脚本：

python simple_assistant.py

示例 2：纯文本对话流程

如果你不需要语音功能，仅需测试 LLM 对话逻辑，可启用纯文本模式。

创建文件 text_only_assistant.py：

import asyncio
from bolna.assistant import Assistant
from bolna.models import LlmAgent, SimpleLlmAgent


async def main():
    assistant = Assistant(name="text_only_agent")

    llm_agent = LlmAgent(
        agent_type="simple_llm_agent",
        agent_flow_type="streaming",
        llm_config=SimpleLlmAgent(
            provider="openai",
            model="gpt-4o-mini",
            temperature=0.2,
        ),
    )

    # 启用纯文本管道，无需配置 transcriber/synthesizer
    assistant.add_task(
        task_type="conversation",
        llm_agent=llm_agent,
        enable_textual_input=True,
    )

    async for chunk in assistant.execute():
        print(chunk)


if __name__ == "__main__":
    asyncio.run(main())

运行脚本：

export OPENAI_API_KEY=your_key
python text_only_assistant.py

下一步

• 电话集成: 若要实现真实的电话拨打功能，请使用 Docker 部署模式，并参考 local_setup 中的 Twilio/Plivo 配置。
• 更多示例: 访问 examples.bolna.dev 查看不同场景的智能体示例。
• 自定义提供商: 编辑 .env 文件即可切换支持的 ASR、LLM 或 TTS 提供商（支持 Azure, AWS Polly, Llama 等）。