---
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)，並按其他即時通話相同方式收費（[收費](/yue/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 智能體的 AI 智能體）代為設定，然後在此傳入其 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](/yue/guides/use-with-livekit)。
</Note>
