---
title: "從 Pipecat 使用 ThunderPhone"
description: "在 Pipecat 管線中將 ThunderPhone 語音智慧體作為語音對語音服務執行，並使用你自己的傳輸與電話服務。"
---

[Pipecat](https://github.com/pipecat-ai/pipecat) 是一個開放原始碼框架，
可透過可組合的服務建置語音智慧體。ThunderPhone 可作為
**語音對語音 LLM 服務**整合：Pipecat 傳送來電者音訊，ThunderPhone
回傳智慧體語音、逐字稿與函式呼叫，而 Pipecat 的
傳輸層（Daily、LiveKit、Twilio、WebRTC、本機麥克風）負責傳遞
音訊。語音辨識、語言模型、語音、輪替發話、62 種
語言及工具皆在 ThunderPhone 上執行。

以這種方式撥打的通話會顯示在[通話紀錄](/api-reference/calls)中，並與其他即時通話相同方式計費（[定價](/zh-Hant/guides/pricing)）。不需訂閱，也不涉及 ThunderPhone 電話號碼。

## 安裝

```bash
pip install pipecat-thunderphone
export THUNDERPHONE_API_KEY=sk_live_...   # a secret API key
```

此套件封裝 Pipecat 的 OpenAI Realtime 服務，因為 ThunderPhone 的 [Realtime WebSocket](/api-reference/realtime) 採用相同通訊協定。它需要 `pipecat-ai` 1.8 或更新版本。

## 執行已儲存的智慧體

智慧體執行的所有事項（提示詞、語音、引擎、語言、工具、問候語、靜音檢查）都在 ThunderPhone 上設定。管線僅負責傳輸音訊。請在控制台建立智慧體，或請 Zeus（負責建立、測試及調校 ThunderPhone 智慧體的人工智慧智慧體）完成設定，然後在此傳入其 ID。你在 ThunderPhone 部署的變更會套用至下一通電話，無須修改你的管線。

```python
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.worker import PipelineParams, PipelineWorker
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair
from pipecat_thunderphone import ThunderPhoneRealtimeLLMService

llm = ThunderPhoneRealtimeLLMService(agent_id=12)

context = LLMContext()
aggregators = LLMContextAggregatorPair(context)
pipeline = Pipeline([
    transport.input(),
    aggregators.user(),
    llm,
    aggregators.assistant(),
    transport.output(),
])
worker = PipelineWorker(pipeline, params=PipelineParams(allow_interruptions=True))
```

已儲存的智慧體會依自身排程開啟通話，因此服務不會向 Pipecat 請求開場回應。若仍希望這麼做，請傳入 `greet_on_connect=True`。

## 直接設定工作階段

不使用 `agent_id` 時，指示與工具會和 OpenAI 一樣來自 Pipecat 內容。`product` 用於選擇引擎，`voice` 用於選擇 ThunderPhone 語音。

```python
from pipecat.adapters.schemas.function_schema import FunctionSchema
from pipecat.adapters.schemas.tools_schema import ToolsSchema
from pipecat.services.llm_service import FunctionCallParams

llm = ThunderPhoneRealtimeLLMService(product="bolt", voice="olivia", language="es")

async def check_availability(params: FunctionCallParams):
    slots = await calendar.free_slots(params.arguments["date"])
    await params.result_callback({"slots": slots})

llm.register_function("check_availability", check_availability)

context = LLMContext(
    messages=[{"role": "system", "content": "You are Acme Dental's receptionist."}],
    tools=ToolsSchema(standard_tools=[
        FunctionSchema(
            name="check_availability",
            description="Free appointment slots on a date",
            properties={"date": {"type": "string"}},
            required=["date"],
        )
    ]),
)
```

直接設定的工作階段由用戶端主導：由於 Pipecat 在收到內容時會請求回應，智慧體會先開口；而在靜默期間，除非你附加訊息或請求另一個回應，否則會保持安靜。

## 選項

| 參數 | 說明 |
|---|---|
| `api_key` | 密密鑰（`sk_live_...`）。預設為 `THUNDERPHONE_API_KEY`。 |
| `agent_id` | 執行已儲存的智慧體。不可與 `product` 和 `voice` 同時使用。 |
| `product` | 內嵌工作階段的引擎：`bolt`（仍接受較舊的 `spark` 和 `storm`）。 |
| `voice` | 內嵌工作階段的 ThunderPhone 語音名稱。 |
| `language` | 內嵌工作階段的主要語言提示，例如 `es`。 |
| `from_number`、`to_number` | 當管線位於電話線路前端時，要記錄於通話中的號碼。 |
| `live_transcripts` | 在話語尚未結束時串流來電者的轉錄片段（額外計費）。 |
| `greet_on_connect` | 在工作階段準備就緒後立即請求第一個回應。 |
| `end_task_on_call_ended` | 當 ThunderPhone 結束通話時推送 `EndWorkerFrame`（預設啟用）。 |

## 事件

ThunderPhone 在即時通訊協定之上新增平台事件。服務會將這些事件傳送至處理常式：

```python
@llm.event_handler("on_call_ended")
async def on_call_ended(service, event):
    print("call ended:", event["reason"], "call id:", service.call_id)
```

工作階段啟用後，系統便會設定 `service.call_id`。通話結束後，使用它搭配
[`GET /v1/calls/{call_id}`](/api-reference/calls) 取得錄音、逐字稿和評分。

## 限制

- 回合偵測在伺服器端執行且一律啟用；不支援由 Pipecat 驅動的回合
  （`turn_detection=False`）。
- 註冊於服務上的函式僅會在內嵌工作階段中執行。已儲存的智慧體會在 ThunderPhone 上執行自己的工具。
- 音訊在雙向皆為 24 kHz、16 位元單聲道 PCM。
- 會忽略視訊影格。

<Note>
改用 LiveKit Agents 建置嗎？請參閱
[從 LiveKit Agents 使用 ThunderPhone](/zh-Hant/guides/use-with-livekit)。
</Note>
