---
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/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](/zh/guides/use-with-livekit)。
</Note>
