---
title: "Sử dụng ThunderPhone từ Pipecat"
description: "Chạy một tác nhân AI thoại ThunderPhone làm dịch vụ chuyển giọng nói sang giọng nói trong một pipeline Pipecat, với lớp truyền tải và hệ thống điện thoại của riêng bạn."
---

[Pipecat](https://github.com/pipecat-ai/pipecat) là một framework mã nguồn mở
để xây dựng tác nhân AI thoại từ các dịch vụ có thể kết hợp. ThunderPhone tích hợp dưới dạng
một **dịch vụ LLM giọng nói sang giọng nói**: Pipecat gửi âm thanh của người gọi, ThunderPhone
trả về giọng nói, bản ghi lời nói và lệnh gọi hàm của tác nhân AI, còn lớp truyền tải của Pipecat
(Daily, LiveKit, Twilio, WebRTC, micrô cục bộ) truyền âm thanh. Nhận dạng giọng nói, mô hình ngôn ngữ,
giọng nói, xử lý lượt thoại, 62 ngôn ngữ và công cụ đều chạy trên ThunderPhone.

Các cuộc gọi được thực hiện theo cách này xuất hiện trong [lịch sử cuộc gọi](/api-reference/calls) và
được tính phí như mọi cuộc gọi thời gian thực khác ([bảng giá](/vi/guides/pricing)). Không có
gói đăng ký nào và không có số điện thoại ThunderPhone nào liên quan.

## Cài đặt

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

Gói này bao bọc dịch vụ OpenAI Realtime của Pipecat, vì
[Realtime WebSocket](/api-reference/realtime) của ThunderPhone sử dụng cùng giao thức. Gói này
cần `pipecat-ai` 1.8 trở lên.

## Chạy tác nhân AI đã lưu

Mọi hoạt động của tác nhân AI (prompt, giọng nói, engine, ngôn ngữ, công cụ, lời chào, kiểm tra im lặng) đều được cấu hình trên ThunderPhone. Pipeline chỉ truyền âm thanh. Tạo tác nhân AI trong bảng điều khiển hoặc nhờ Zeus (tác nhân AI xây dựng, kiểm thử và tinh chỉnh các tác nhân AI ThunderPhone) thiết lập, rồi truyền ID của tác nhân tại đây. Các thay đổi bạn triển khai trên ThunderPhone sẽ áp dụng cho cuộc gọi tiếp theo mà không cần chạm vào pipeline của bạn.

```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))
```

Một tác nhân AI đã lưu sẽ tự bắt đầu cuộc gọi theo lịch riêng, nên dịch vụ không
yêu cầu phản hồi mở đầu từ Pipecat. Truyền `greet_on_connect=True` nếu bạn
vẫn muốn có phản hồi đó.

## Cấu hình phiên nội tuyến

Không có `agent_id`, chỉ dẫn và công cụ đến từ ngữ cảnh Pipecat, giống như
với OpenAI. `product` chọn engine và `voice` chọn giọng 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"],
        )
    ]),
)
```

Các phiên nội tuyến do máy khách điều khiển: tác nhân AI nói trước vì Pipecat
yêu cầu phản hồi khi ngữ cảnh đến, và giữ im lặng trong lúc im lặng
trừ khi bạn thêm tin nhắn hoặc yêu cầu một phản hồi khác.

## Tùy chọn

| Tham số | Ý nghĩa |
|---|---|
| `api_key` | Khóa bí mật (`sk_live_...`). Mặc định là `THUNDERPHONE_API_KEY`. |
| `agent_id` | Chạy một tác nhân AI đã lưu. Loại trừ lẫn nhau với `product` và `voice`. |
| `product` | Engine cho phiên nội tuyến: `bolt` (các `spark` và `storm` cũ hơn vẫn được chấp nhận). |
| `voice` | Tên giọng nói ThunderPhone cho phiên nội tuyến. |
| `language` | Gợi ý ngôn ngữ chính cho phiên nội tuyến, ví dụ: `es`. |
| `from_number`, `to_number` | Số cần ghi lại trong cuộc gọi khi pipeline đứng trước một đường dây điện thoại. |
| `live_transcripts` | Truyền các đoạn transcript của người gọi trong khi họ đang nói (tính phí thêm). |
| `greet_on_connect` | Yêu cầu phản hồi đầu tiên ngay khi phiên sẵn sàng. |
| `end_task_on_call_ended` | Đẩy `EndWorkerFrame` khi ThunderPhone kết thúc cuộc gọi (bật theo mặc định). |

## Sự kiện

ThunderPhone bổ sung các sự kiện nền tảng bên trên giao thức thời gian thực. Dịch vụ
gửi chúng đến các trình xử lý:

```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` được thiết lập khi phiên hoạt động. Dùng giá trị này với
[`GET /v1/calls/{call_id}`](/api-reference/calls) để lấy bản ghi âm,
bản ghi cuộc gọi và điểm đánh giá sau cuộc gọi.

## Giới hạn

- Phát hiện lượt nói diễn ra ở phía máy chủ và luôn bật; các lượt nói do Pipecat điều khiển
  (`turn_detection=False`) không được hỗ trợ.
- Các hàm được đăng ký trên dịch vụ chỉ chạy cho phiên nội tuyến. Một tác nhân AI đã lưu
  sẽ thực thi các công cụ riêng trên ThunderPhone.
- Âm thanh là PCM đơn kênh 16-bit ở 24 kHz theo cả hai chiều.
- Khung hình video bị bỏ qua.

<Note>
Bạn đang xây dựng với LiveKit Agents? Xem
[Sử dụng ThunderPhone từ LiveKit Agents](/vi/guides/use-with-livekit).
</Note>
