bolna-ai/bolna

Bol na – 오픈소스 음성AI 오케스트레이션 플랫폼

무엇인가요 – Bol na는 대규모 언어 모델(LLM)로 구동되는 음성 우선 대화형 어시스턴트를 구축할 수 있는 프로덕션 준비 완료된 프레임워크입니다. 음성-텍스트 변환(ASR), LLM, 텍스트-음성 변환(TTS) 제공업체를 연결하고, 통화 서비스를 통해 전화 통화를 발신 및 수신할 수 있습니다. 모든 오케스트레이션 로직은 이 리포지토리에 포함되어 있으며, Bol na가 제공하는 호스팅된 API 및 UI는 이 위에 구축됩니다.

핵심 개념

구성 요소	역할	예시 제공업체
통화	전화 통화를 시작/수신하고 웹소켓을 통해 오디오 스트리밍	Twilio, Plivo (다른 것도 추가 가능)
ASR(변환기)	들어오는 오디오를 텍스트로 변환	Deepgram, Azure
LLM 에이전트	대화 응답 생성	OpenAI, DeepSeek, Llama, Cohere, Mistral (LiteLLM 경유)
TTS(합성기)	LLM 출력을 다시 음성으로 변환	AWS Polly, ElevenLabs, OpenAI, Cartesia 등
Redis	에이전트 상태 및 프롬프트 데이터를 지속화
ngrok	로컬 서버를 공개 인터넷에 노출하여 통화 콜백 가능

주요 기능

엔드투엔드 오케스트레이션 – 하나의 Python 수준 파이프라인(Assistant)으로 오디오 → 텍스트 → LLM → 오디오의 스트리밍을 구현.
제공업체 독립성 – 환경 변수를 통해 지원되는 ASR, LLM, TTS 서비스를 자유롭게 연결 가능. 코드는 LLM에 대해 liteLLM 래퍼를 사용합니다.
통화 통합 – Twilio 및 Plivo용 미리 준비된 Docker 컨테이너 제공. Vonage, Telnyx 등 다른 것들도 쉽게 추가 가능.
스트리밍 – 변환 및 합성 모두 스트리밍 가능하여 낮은 지연 시간의 음성 상호작용 가능.
자체 호스팅 – 모든 구성 요소가 Docker Compose로 실행됨 (Bol na 서버, 통화 서버, Redis, ngrok). 데이터와 키는 자체 내부에 보관 가능.
확장성 – 새로운 통화 또는 TTS 제공업체를 추가하려면 핸들러 클래스를 구현하고 작은 서버 래퍼를 작성하기만 하면 됩니다.

일반적인 워크플로우 (Python API)

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

assistant = Assistant(name="demo_agent")

# 1️⃣ 음성-텍스트 변환
transcriber = Transcriber(provider="deepgram", model="nova-2", stream=True)

# 2️⃣ LLM 응답
llm = LlmAgent(
    agent_type="simple_llm_agent",
    agent_flow_type="streaming",
    llm_config=SimpleLlmAgent(
        provider="openai",
        model="gpt-4o-mini",
        temperature=0.3,
    ),
)

# 3️⃣ 텍스트-음성 변환
synth = Synthesizer(
    provider="elevenlabs",
    provider_config=ElevenLabsConfig(voice="George", voice_id="JBFqnCBsd6RMkjVDRZzb"),
    stream=True,
    audio_format="wav",
)

assistant.add_task(
    task_type="conversation",
    llm_agent=llm,
    transcriber=transcriber,
    synthesizer=synth,
    enable_textual_input=False,
)

# 실행 – 점진적인 결과 사전을 생성
async for chunk in assistant.execute():
    print(chunk)

같은 Assistant는 트랜스크립터/심소사이저를 생략하고 enable_textual_input=True로 설정하면 텍스트 전용 모드에서도 사용 가능합니다.

로컬에서 시작하기

리포지토리 복제 후 .env.sample → .env 복사, 사용할 제공업체(OpenAI, Deepgram, ElevenLabs, Twilio 등)의 API 키를 입력.
Docker-compose – local_setup/ 폴더에 docker-compose.yml이 있으며, 다음 4개 컨테이너를 빌드합니다:
- bolna-app – 핵심 오케스트레이션 서버
- twilio-app 또는 plivo-app – 통화 웹훅 서버
- ngrok – 웹훅 URL 공개
- redis – 상태 저장소

모든 것을 시작하기 위한 헬퍼 스크립트 사용:

cd local_setup
chmod +x start.sh
./start.sh   # BuildKit로 빌드하고 디테치 모드로 실행

REST API(API.md) 또는 위의 Python SDK를 통해 에이전트 생성.
통화하기 – 통화 서버가 Twilio/Plivo로부터 웹훅을 수신하고 오디오를 Bol na로 전달한 후, 합성된 응답을 통화자에게 스트리밍.

플랫폼 확장하기

새로운 통화 제공업체 추가 – bolna/input_handlers/telephony_providers/에 입력 핸들러 구현, bolna/output_handlers/telephony_providers/에 출력 핸들러 구현, twilio_api_server.py와 유사한 작은 서버 작성.
새로운 ASR/TTS 제공업체 추가 – .env에 필요한 자격 증명 노출하고, bolna/providers.py의 매핑에 제공업체 추가.
사용자 정의 LLM 로직 – 다른 LlmAgent 서브클래스 연결하거나 프롬프트 흐름 수정. 프레임워크는 LLM을 블랙박스 호출 가능 객체로 간주합니다.

커뮤니티 및 지원

Discord – 도움과 기능 논의를 위한 활성 채팅 채널.
문서 – https://docs.bolna.ai에 호스팅 (API 참조, 제공업체 심층 분석, 배포 가이드).
기여 – MIT 라이선스, PR 환영. 리포지토리에는 CONTRIBUTING.md와 열린 이슈 목록 포함.

라이선스

MIT – 코드를 자유롭게 사용, 수정, 재배포 가능.