# Pipecat

**Repository Path**: genvex/pipecat

## Basic Information

- **Project Name**: Pipecat
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-31
- **Last Updated**: 2026-08-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 Pipecat Local - 本地语音助手

基于 [Pipecat](https://github.com/pipecat-ai/pipecat) 框架的本地语音对话系统

**状态**: ✅ 核心功能验证通过  
**最后更新**: 2026-08-31

---

## 📋 项目简介

Pipecat Local 是一个基于 Pipecat 框架的本地语音对话系统，集成以下组件：

| 组件 | 技术栈 | 版本 | 说明 |
|------|--------|------|------|
| **框架** | Pipecat | 1.8.1 | 实时语音对话框架 |
| **ASR** | sherpa-onnx (SenseVoice) | 1.13.6 | 多语言语音识别 |
| **LLM** | SenseNova API | 6.8-flash-lite | 云端大语言模型 |
| **TTS** | Piper | zh_CN-huayan-medium | 本地语音合成 |

---

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone https://gitee.com/genvex/pipecat.git
cd pipecat
```

### 2. 安装依赖

#### 方式一：使用 uv（推荐）

```bash
# 安装uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境
uv venv .venv --python 3.11
source .venv/bin/activate

# 安装依赖
uv pip install pipecat-ai sherpa-onnx piper-tts numpy onnxruntime requests loguru
```

#### 方式二：使用 pip

```bash
# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install pipecat-ai sherpa-onnx piper-tts numpy onnxruntime requests loguru
```

### 3. 下载模型

```bash
# 下载 SenseVoice 模型（约228MB）
mkdir -p /tmp/sherpa-onnx-sense-voice
wget -q -O /tmp/sensevoice.zip https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-sense-voice-zh-en-ja-ko-yue-int8-2024-07-17.zip
unzip /tmp/sensevoice.zip -d /tmp/sherpa-onnx-sense-voice

# 下载 Piper 模型（约61MB）
mkdir -p ~/.local/share/piper
wget -q -O ~/.local/share/piper/zh_CN-huayan-medium.onnx https://github.com/rhasspy/piper/releases/download/2023.11.14-libs/v1.2/zh_CN-huayan-medium.onnx
wget -q -O ~/.local/share/piper/zh_CN-huayan-medium.onnx.json https://github.com/rhasspy/piper/releases/download/2023.11.14-libs/v1.2/zh_CN-huayan-medium.onnx.json
```

### 4. 配置 API

编辑 `config.json`，填入你的 SenseNova API Key：

```json
{
    "base_url": "https://token.sensenova.cn/v1",
    "api_key": "sk-xxx",
    "model": "sensenova-6.8-flash-lite"
}
```

> **获取 API Key**: 访问 [Sensenova 控制台](https://sensenova.cn/) 申请

### 5. 运行测试

```bash
# 运行端到端测试
python tests/test_end_to_end.py

# 运行语音对话
python pipecat_local.py --config config.json
```

---

## 📁 项目结构

```
pipecat/
├── pipecat_local.py          # 主程序 (语音助手核心)
├── config.json               # API配置（需自行填写）
├── README.md                 # 本文件
├── BUILD_GUIDE.md           # 构建指南
├── USAGE_GUIDE.md           # 使用指南
│
├── tests/                    # 测试脚本
│   ├── test_asr.py          # ASR测试
│   ├── test_llm.py          # LLM测试
│   ├── test_tts.py          # TTS测试
│   └── test_end_to_end.py   # 端到端测试
│
├── examples/                 # 示例代码
│   ├── simple_conversation.py
│   └── batch_processing.py
│
└── docs/                     # 文档
    ├── PIPECAT_DEEP_DIVE.md    # 架构精读笔记
    ├── PIPECAT_REPRODUCTION.md # 复现过程报告
    └── TEST_REPORT.md         # 测试报告
```

---

## 🔧 构建说明

### 系统要求

- **操作系统**: Linux (Ubuntu 20.04+ / Debian 11+)
- **架构**: x86_64 或 ARM64
- **Python**: 3.10+
- **内存**: ≥ 2GB RAM
- **磁盘**: ≥ 500MB（模型文件）

### 编译优化（可选）

```bash
# Linux x86_64 优化编译
CFLAGS="-march=native -O3" pip install sherpa-onnx

# ARM64 优化编译（如 RDK X5）
CFLAGS="-mcpu=native -O3" pip install sherpa-onnx
```

### Docker 构建（可选）

```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# 下载模型
RUN mkdir -p /tmp/models && \
    wget -q -O /tmp/models/sensevoice.zip <URL> && \
    unzip /tmp/models/sensevoice.zip -d /tmp/models/ && \
    wget -q -O ~/.local/share/piper/zh_CN-huayan-medium.onnx <URL>

CMD ["python", "pipecat_local.py", "--config", "config.json"]
```

---

## 📖 使用指南

### 基本用法

```python
from pipecat_local import LocalVoiceAgent
import asyncio
import json

async def main():
    # 加载配置
    with open('config.json') as f:
        config = json.load(f)
    
    # 初始化语音助手
    agent = LocalVoiceAgent(config)
    await agent.initialize()
    
    # 语音识别
    text = await agent.recognize(audio_data, sample_rate=16000)
    print(f"识别结果: {text}")
    
    # 生成回复
    response = await agent.generate_response(text)
    print(f"LLM回复: {response}")
    
    # 语音合成
    audio_data, sample_rate = await agent.synthesize(response)
    print(f"音频生成成功: {len(audio_data)} bytes")

asyncio.run(main())
```

### API 说明

#### `LocalVoiceAgent(config: dict)`

初始化语音助手。

**参数**:
- `config`: 配置字典，包含 `base_url`, `api_key`, `model`

#### `initialize()`

异步初始化所有组件（ASR、LLM、TTS）。

#### `recognize(audio_data: bytes, sample_rate: int = 16000) -> str`

语音识别。

**参数**:
- `audio_data`: PCM音频数据（16-bit, mono, 16kHz）
- `sample_rate`: 采样率（默认16000）

**返回**: 识别文本

#### `generate_response(text: str, context: list = None) -> str`

生成LLM回复。

**参数**:
- `text`: 用户输入文本
- `context`: 对话上下文（可选）

**返回**: LLM回复文本

#### `synthesize(text: str) -> tuple`

语音合成。

**参数**:
- `text`: 待合成文本

**返回**: `(audio_data: bytes, sample_rate: int)`

---

## 📊 性能数据

测试环境: RDK X5 (ARM64, Ubuntu 22.04)

| 指标 | 数值 | 说明 |
|------|------|------|
| **ASR加载时间** | ~10秒 | SenseVoice INT8模型 |
| **ASR推理速度** | ~1秒/3秒音频 | RTF = 0.26 |
| **LLM响应时间** | ~0.4秒 | 网络延迟为主 |
| **TTS生成时间** | ~2秒/100字 | zh_CN-huayan-medium |
| **内存占用** | ~500MB | 含所有模型 |
| **CPU占用** | ~30% | 单核 |

---

## 🧪 测试

### 运行所有测试

```bash
# 运行单元测试
python -m pytest tests/ -v

# 或运行端到端测试
python tests/test_end_to_end.py
```

### 测试输出示例

```
🚀 初始化语音助手...
✅ SenseVoice ASR加载成功
✅ SenseNova LLM连接成功
✅ Piper TTS加载成功

📋 【测试1】语音识别 (ASR)
  ✅ test_0.pcm: "你好想去。"
  ✅ test_1.pcm: "心是山信怎呀。"

📋 【测试2】大模型回复 (LLM)
  ✅ Q: "你好，介绍一下你自己"
  ✅ A: "你好！我是商量（SenseNova）..."

📋 【测试3】语音合成 (TTS)
  ✅ TTS 1 成功！103KB, 22050Hz
  ✅ TTS 2 成功！131KB, 22050Hz

=== ✅ 所有测试完成 ===
```

---

## ⚠️ 注意事项

1. **API Key 过期**: Sensenova API Key 可能过期，请定期更新
2. **网络依赖**: LLM需要网络连接，ASR/TTS可离线运行
3. **模型大小**: SenseVoice模型约228MB，Piper模型约61MB
4. **内存占用**: 运行时需要至少500MB可用内存

---

## 📚 相关资源

- **Pipecat 官方文档**: https://docs.pipecat.ai/
- **sherpa-onnx GitHub**: https://github.com/k2-fsa/sherpa-onnx
- **Piper TTS GitHub**: https://github.com/rhasspy/piper
- **SenseNova 控制台**: https://sensenova.cn/

---

## 📝 许可证

本项目基于 Pipecat 框架构建，遵循其 BSD 2-Clause 许可证。

---

## 🙏 致谢

- [Pipecat](https://github.com/pipecat-ai/pipecat) - 优秀的语音对话框架
- [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) - 高效的语音识别工具包
- [Sensenova](https://sensenova.cn/) - 强大的大语言模型API

---

**开发时间**: 2026-08-31  
**测试状态**: ✅ 核心功能验证通过  
**维护状态**: 🟢 活跃开发