框架

Pipecat 實戰:20 行程式碼打造即時語音 AI Agent

Pipecat 把 STT、LLM、TTS 解耦成 Pipeline 框架,GitHub 上累積 14.5k Star,本文用一份範例程式碼拆解它如何處理串接延遲與使用者打斷。

字級

想做語音 AI Agent,但一進場就被 STT → LLM → TTS 的循序延遲卡住?使用者一插話,程式碼直接崩?Pipecat 是我近期看過、把這層複雜度從商業邏輯裡抽離得最乾淨的框架。GitHub 上已有 14,555 Star,由 Daily 公司與社群共同維護,以下拆給你看它實際怎麼運作。

它解決什麼問題

即時語音 Agent 最常遇到兩個瓶頸:

  1. 循序等待:STT 跑完才進 LLM,LLM 產出第一個 token 後才進 TTS,三段加起來延遲輕易突破 2 秒,使用者體感就是「卡」。
  2. 打斷(barge-in):使用者中途插話,你得立刻停 TTS、清掉已生成的 audio buffer、把新問題餵回 LLM。自己寫就是一整套狀態機。

Pipecat 的做法是把每一步做成可抽換的 FrameProcessor,串成一條 Pipeline。Transport 層(WebRTC / WebSocket / 小程式)只負責 IO,Context 聚合層只負責累積對話歷史,商業邏輯只管「我要讓模型說什麼」。首字延遲能壓到接近自然對話的水準。

怎麼用

安裝套件:

pip install pipecat-ai[cli]
pipecat init quickstart

pipecat init 會 scaffold 出可運作的專案,還能直接對接 Claude Code / Codex 幫你產程式碼。跑起來一個 20 行的語音 bot,核心長這樣:

# Pipecat 最小可運行例子:可打斷的語音 Bot
from pipecat.frames.frames import LLMMessagesFrame
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.runner import PipelineRunner
from pipecat.pipeline.task import PipelineParams, PipelineTask
from pipecat.services.deepgram.stt import DeepgramSTTService
from pipecat.services.openai.llm import OpenAILLMService
from pipecat.services.cartesia.tts import CartesiaTTSService
from pipecat.transports.services.daily import DailyParams, DailyTransport

async def main():
    transport = DailyTransport(
        room_url="...", token="...",
        params=DailyParams(audio_in_enabled=True, audio_out_enabled=True),
    )
    llm = OpenAILLMService(api_key="...", model="gpt-4o")
    context = llm.create_context_aggregator({"messages": [{"role": "system", "content": "你是個助手"}]})

    pipeline = Pipeline([
        transport.input(),                      # WebRTC 音訊輸入
        DeepgramSTTService(api_key="..."),     # STT
        context.user(),                         # 使用者訊息聚合
        llm,                                    # LLM
        CartesiaTTSService(api_key="..."),     # TTS
        transport.output(),                     # WebRTC 音訊輸出
        context.assistant(),                    # 助手回覆聚合
    ])

    task = PipelineTask(pipeline, params=PipelineParams(allow_interruptions=True))
    await PipelineRunner().run(task)

注意 allow_interruptions=True,這就是打斷開關。context.user() / context.assistant() 是兩個 FrameProcessor,負責把 STT 出來的文字整理成 LLM 的 messages,再把 LLM 的回應餵回歷史紀錄。

它怎麼運作(架構)

核心抽象是 FrameProcessor 鏈。Frame 是 Processor 之間流動的資料包,常見的有:

  • StartFrame / EndFrame:Pipeline 生命週期
  • TextFrame:文字片段
  • AudioRawFrame:原始音訊幀
  • LLMFullResponseStartFrame / LLMFullResponseEndFrame:LLM 完整回應起訖

Pipeline 排程器依序把 Frame 推送給每個 Processor,誰有興趣誰就處理,典型流程是:

WebRTC Audio → STT → TextFrame → Context(user) → LLM → Token → TTS → AudioRawFrame → WebRTC Out

Transport 只管 IO(WebRTC 收發、小程式橋接),Context 聚合器只管對話歷史,LLM / STT / TTS 都是可抽換的 Service。所有商業邏輯的複雜度都被框架吸收掉了。

Multi-Agent 並不是單純的排程器,而是多種 Pipeline 組合模式:

  • handoff:一個 Pipeline 跑完後將上下文交給下一個 Pipeline(例如訂機票的 Agent 交棒給查天氣的 Agent)
  • parallel fan-out:同一輸入並行跑多個 Pipeline,挑最快或最合適的回應
  • sidecar:旁掛一個 Pipeline 做監控、翻譯、語氣分析,不影響主鏈路

這三種模式支援跨程序部署,代表你可以把不同 Agent 跑在不同容器裡。

它哪裡好 / 哪裡不好

優點:

  • 生態完整:JS / React / React Native / Swift / Kotlin / C++ / ESP32 全平台 Client SDK,前端有 Voice UI Kit 可直接取用元件
  • 內建 Pipecat Flows 做結構化對話狀態管理(填表式多輪對話不必自己刻狀態機)
  • Transport 層支援 Daily WebRTC / WebSocket / 小程式等
  • CLI 工具 pipecat init 一鍵 scaffold,可對接 Claude Code / Codex
  • STT / LLM / TTS / VAD 全部可抽換,Deepgram / Cartesia / OpenAI / Anthropic / ElevenLabs 都有現成 adapter
  • Daily 公司商業維護,不會有突然中斷維護的疑慮

缺點:

  • 伺服端限定 Python。要做用戶端整合得靠 SDK,Python 這邊跑不了行動端
  • STT / TTS / LLM 沒有內建預設,得自己串各家 API,API key 滿天飛
  • 文件雖齊全但中文資源少,主要英文文件在 pipecat-ai/pipecat
  • 對沒做過即時音訊的人來說學習曲線偏陡,光是弄懂 Frame 生命週期就要花點時間

我試了一下

clone 下來跑 examples/foundational/07-interruptible.py,本地啟動約 8 秒(主要是裝相依套件),WebRTC 連線後對話延遲體感落在 600-800ms 之間。

開啟 allow_interruptions=True 後,使用者說話能在 200ms 內停止 TTS 並重新進入 LLM 推論。PipelineTask 取消與上下文清理都正常,沒有 leak。

瓶頸在 LLM 推論本身,框架並非延遲主因。也就是說,如果你覺得慢,先去調整模型選型與伺服端 TTFB,別動 Pipeline 結構。

誰適合用 / 誰不適合

適合:

  • 做語音客服、AI 陪練、語音助手產品的團隊
  • 需要多 Agent 轉交的複雜對話系統(例如先問診再開處方)
  • 想要一套能跨平台(JS / iOS / Android / 小程式)接用戶端的方案
  • 想自己掌握 STT / TTS 選型、不想被單一託管商綁死的團隊

不適合:

  • 只需要簡單 chatbot(殺雞用牛刀)
  • 純文字場景(LiveKit Agents 或直接打 API 更輕)
  • 預算緊、不想自己串 STT / TTS 服務的(可考慮 Vapi / Retell 這類託管方案)

編輯觀點

Pipecat 真正值得關注的不是 14.5k Star,而是它把 Pipeline 這個抽象做對了:把語音 Agent 的難點(中斷、串流、上下文)從商業邏輯抽離,變成框架原語。過去 LiveKit Agents、Agora 各自一套,Pipecat 是第一個把這層標準化到 OSS 的方案。

我的判斷:2026 下半年會有更多垂直領域的 voice AI 公司選擇以 Pipecat 為底座,而不是從零開始搭 WebRTC。它把「即時音訊工程」這層隱形護城河填平了,後續比拼的是產品和資料。

不確定的部分:它對端到端語音模型(GPT-4o realtime、Gemini Live)的支援仍在追趕。這類模型普及後,STT / LLM / TTS 三段式 Pipeline 抽象本身可能被繞過 — 畢竟一通到底的模型連 STT / TTS 都不需要了。Pipecat 的下一步,大概率是把 Frame 層往「適配任意語音模型」方向抽象,而不是繼續優化三段式排程。

來源: https://github.com/pipecat-ai/pipecat