# voice-inter

**Repository Path**: fanxinkeji_admin/voice-inter

## Basic Information

- **Project Name**: voice-inter
- **Description**: 语音交互RAG，兼容小智AI硬件
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-12
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Voice Knowledge Service (语音知识服务)

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

 :smiley: 
 **第一次提交，许多文档还不完善，该文档有AI根据代码提取生成，大家学习使用以代码和项目内文档为主。** 

**Voice Knowledge Service** 是一个为智能硬件提供语音交互和知识问答能力的后端服务框架。它兼容 **小智 AI 硬件协议**，支持 WebSocket 和 MQTT+UDP 双协议接入，内置 RAG（检索增强生成）引擎，可快速接入自定义知识库，打造智能化的语音助手。

该项目包含两个核心模块：
- **语音网关** (`voice_gateway`)：处理设备连接、音频流转发、协议转换，负责与设备进行实时通信。
- **RAG 知识服务** (`rag_process`)：提供文档加载、向量检索、LLM 问答、实时讲解等功能，是语音助手的“大脑”。

> **注意**：OTA 配置服务将稍后开源，敬请期待。


相关服务：
大模型本地服务：https://gitee.com/fanxinkeji_admin/llm
语音交互本地服务：https://gitee.com/fanxinkeji_admin/audio

---

## ✨ 功能特性

- **多协议设备接入**  
  支持 WebSocket（版本 1/2/3）和 MQTT+UDP 双协议，与各类智能硬件无缝对接，兼容小智 AI 硬件通信规范。

- **实时语音对话**  
  通过可插拔的 ASR、TTS、LLM 组件实现端到端语音对话，支持流式音频转发，延迟低至百毫秒级。

- **知识库问答（RAG）**  
  基于向量检索（pgvector）和 LLM，从 PDF、Word、Markdown 等文档中检索相关知识并生成自然语言回答，让设备拥有领域知识。

- **角色化知识库**  
  可为不同角色（如 `coach`、`reception`、`announcer`、`safety`）配置独立的知识文档和提示词模板，实现千人千面的回答风格。

- **实时讲解与播报**  
  支持事件驱动的自动解说：订阅眼动、射击、安全告警等事件，动态生成讲解内容并推送至前端（如大屏、教练平板）。

- **模块化设计**  
  ASR、TTS、LLM 均通过抽象接口解耦，可轻松替换为本地模型（Whisper、F5-TTS、ChatGLM 等）或云端 API（阿里云、OpenAI 等）。

- **易于扩展**  
  提供清晰的端口与适配器模式，可快速集成新的向量数据库、嵌入模型或外部服务。

---

## 🚀 快速开始

### 环境要求

- Python 3.10+
- PostgreSQL (建议 14+) + pgvector 扩展
- （可选）Redis（用于对话记忆缓存）
- （可选）本地嵌入模型（如 `BAAI/bge-small-zh-v1.5`）或使用云端 API

### 安装步骤

1. **克隆仓库**
   ```bash
   git clone https://gitee.com/your-username/voice-knowledge-service.git
   cd voice-knowledge-service
   ```

2. **创建并激活虚拟环境**
   ```bash
   python -m venv venv
   source venv/bin/activate  # Linux/macOS
   venv\Scripts\activate      # Windows
   ```

3. **安装依赖**
   ```bash
   pip install -r requirements.txt
   ```

4. **配置环境变量**  
   复制 `.env.example` 为 `.env`，并根据实际情况修改：
   ```bash
   cp .env.example .env
   ```
   主要配置项说明见下文。

5. **初始化数据库**  
   确保 PostgreSQL 已安装并启用 pgvector 扩展，然后执行：
   ```bash
   python scripts/init_db.py
   ```

6. **启动服务**
   ```bash
   # 启动语音网关和知识服务（一体）
   python mcp/service6_knowledge/main.py
   ```
   服务默认监听端口：
   - HTTP API: `8107`（网关）
   - WebSocket: `8106`（网关设备接入）
   - RAG 服务: `8006`（知识服务内部 API）

7. **测试连接**  
   使用 WebSocket 客户端连接 `ws://localhost:8106/chat` 发送 `hello` 消息，或通过 HTTP 访问 `http://localhost:8006/health` 查看服务状态。

---

## ⚙️ 配置说明

主要配置项通过环境变量设置，可在 `.env` 文件中定义（所有变量均有默认值）。

### 语音网关配置（前缀 `VOICE_GW_`）

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `VOICE_GW_RAG_WS_URL` | RAG 服务的 WebSocket 端点 | `ws://localhost:8006/api/v1/voice_chat/stream` |
| `VOICE_GW_WS_PORT` | 设备 WebSocket 监听端口 | `8106` |
| `VOICE_GW_API_PORT` | HTTP API 端口 | `8107` |
| `VOICE_GW_ENABLE_OPUS` | 是否启用 Opus 编解码（false 表示透传） | `false` |
| `VOICE_GW_MQTT_BROKER` | MQTT broker 地址 | `mqtts://localhost:8883` |
| `VOICE_GW_UDP_HOST` | UDP 服务监听地址 | `0.0.0.0` |
| `VOICE_GW_UDP_PORT` | UDP 服务端口 | `9106` |
| 更多参数请查看 `voice_gateway/config.py` |

### RAG 知识服务配置（前缀 `RAG_`）

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `RAG_VECTOR_STORE_CONNECTION_STRING` | PostgreSQL 连接串 | `postgresql://user:pass@localhost:5432/db` |
| `RAG_VECTOR_STORE_COLLECTION_NAME` | 向量表名 | `knowledge_chunks` |
| `RAG_EMBEDDING_MODEL_NAME` | 本地嵌入模型名称 | `BAAI/bge-small-zh-v1.5` |
| `RAG_EMBEDDING_DIMENSION` | 向量维度 | `512` |
| `RAG_LLM_PROVIDER` | LLM 提供方 (`local` 或 `dashscope`) | `local` |
| `RAG_LLM_API_BASE` | 本地 LLM 服务地址 | `http://localhost:8201` |
| `RAG_DASHSCOPE_API_KEY` | 阿里云百炼 API Key | - |
| `RAG_ASR_HTTP_URL` | ASR 文件转写接口 | `http://localhost:8300/transcribe` |
| `RAG_ASR_WS_URL` | ASR WebSocket 实时流接口 | `ws://localhost:8300/ws/stream` |
| `RAG_TTS_SYNTHESIZE_URL` | TTS 合成接口 | `http://localhost:8301/synthesize` |
| `RAG_TTS_STREAM_URL` | TTS 流式合成接口 | `http://localhost:8301/synthesize/stream` |

完整的配置项请参考 `config/rag_config.py` 和 `voice_gateway/config.py`。

---

## 🧠 架构概述

```
┌─────────────────────────────────────────────────────────────────────┐
│                           智能硬件设备 (ESP32)                         │
│                    (支持小智协议：WebSocket / MQTT+UDP)                 │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         语音网关 (voice_gateway)                       │
│  • 处理设备连接、协议转换                                               │
│  • Opus 音频透传，无编解码                                              │
│  • 管理设备会话、唤醒词处理                                             │
│  • 转发音频流至 RAG 服务                                                │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────┐
│                     RAG 知识服务 (rag_process)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                   │
│  │   ASR 客户端 │  │   LLM 客户端 │  │   TTS 客户端 │                   │
│  └─────────────┘  └─────────────┘  └─────────────┘                   │
│         │                │                │                           │
│         ▼                ▼                ▼                           │
│  ┌─────────────────────────────────────────────────────┐             │
│  │                RAG 核心引擎 (RAGEngine)                │             │
│  │  • 向量检索（pgvector）                               │             │
│  │  • 提示词模板管理（Jinja2）                           │             │
│  │  • 对话记忆管理                                       │             │
│  │  • 事件驱动的实时讲解处理器                             │             │
│  └─────────────────────────────────────────────────────┘             │
│                                    │                                   │
│                                    ▼                                   │
│                         ┌─────────────────────┐                       │
│                         │  向量数据库 (pgvector) │                       │
│                         │  文档存储 (本地文件)   │                       │
│                         └─────────────────────┘                       │
└─────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │   外部 AI 服务       │
                         │  ASR / TTS / LLM    │
                         │  (本地或云端API)     │
                         └─────────────────────┘
```

### 工作流程示例（语音对话）

1. 设备通过 WebSocket 或 MQTT+UDP 连接网关，发送 `hello` 建立会话。
2. 用户说话，设备将 Opus 音频流发送给网关。
3. 网关透传音频流至 RAG 服务的 ASR 模块（通过 WebSocket 或 HTTP）。
4. ASR 返回识别文本，RAG 引擎执行检索增强生成：
   - 向量检索相似文档块
   - 加载对话记忆
   - 调用 LLM 生成回答
5. 回答文本经 TTS 合成为音频流，通过网关转发给设备播放。
6. 若配置了实时讲解规则，眼动/射击等事件会触发自动播报。

---

## 📚 使用示例

### 1. 设备接入（WebSocket）

```python
import asyncio
import websockets
import json

async def device_client():
    uri = "ws://localhost:8106/chat"
    async with websockets.connect(uri) as ws:
        # 发送 hello
        await ws.send(json.dumps({
            "type": "hello",
            "version": 3,
            "transport": "websocket",
            "audio_params": {
                "format": "opus",
                "sample_rate": 16000,
                "frame_duration": 60
            }
        }))
        response = await ws.recv()
        print("Server hello:", response)

        # 模拟发送音频数据（Opus 帧）
        with open("audio.opus", "rb") as f:
            opus_data = f.read(120)  # 60ms 帧
            await ws.send(opus_data)

asyncio.run(device_client())
```

### 2. 上传文档构建知识库

```bash
curl -X POST http://localhost:8006/api/v1/documents/upload \
  -F "file=@/path/to/document.pdf" \
  -F "role=coach" \
  -F 'metadata={"source": "training_manual"}'
```

### 3. 发起对话

```bash
curl -X POST http://localhost:8006/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "role": "coach",
    "query": "如何提高射击稳定性？",
    "shooter_id": "SH001"
  }'
```

响应示例：
```json
{
  "code": 200,
  "message": "对话生成成功",
  "data": {
    "answer": "根据训练手册，您可以通过注视点训练和呼吸控制来提高稳定性...",
    "sources": [...],
    "conversation_id": "conv_abc123",
    "processing_time_ms": 1250
  }
}
```

### 4. 实时讲解配置（触发眼动漂移时推送讲解）

```bash
curl -X POST http://localhost:8006/api/v1/commentary/config \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session_A3",
    "trigger_type": "gaze_drift",
    "threshold": 45,
    "role": "coach",
    "cooldown_seconds": 10
  }'
```

当眼动漂移超过阈值时，系统会自动生成讲解并通过 WebSocket 推送到前端。

---

## 🔌 组件替换指南

### 替换 ASR 服务

1. 实现与 `rag_process/clients/asr_client.py` 中 `ASRClient` 相同接口的类。
2. 在 `config/rag_config.py` 中修改 `asr_http_url` 和 `asr_ws_url`。
3. 可选：在 `rag_process/clients/__init__.py` 中注册新客户端。

### 替换 TTS 服务

1. 实现 `rag_process/clients/tts_client.py` 中 `TTSClient` 接口。
2. 更新 `tts_synthesize_url` 和 `tts_stream_url` 配置。
3. 若使用其他格式（如 MP3），需在网关或客户端适配。

### 替换 LLM 服务

- **本地模型**：启动一个兼容 OpenAI API 格式的服务（如 vLLM、FastChat），配置 `RAG_LLM_PROVIDER=local` 和 `RAG_LLM_API_BASE`。
- **阿里云百炼**：配置 `RAG_LLM_PROVIDER=dashscope`，并填入 `RAG_DASHSCOPE_API_KEY`。
- **其他云服务**：可扩展 `LLMClient` 支持新提供商。

### 扩展知识库角色

1. 在 `data/rag_knowledge/prompts/` 下创建对应角色的 Jinja2 模板，如 `chat/referee.j2`。
2. 上传文档时指定角色 `role=referee`。
3. 对话请求中传入相同角色即可。

---

## 🤝 贡献指南

我们欢迎任何形式的贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发流程。

- 报告 Bug 或提出新功能：在 Issues 中创建新话题。
- 提交代码：Fork 仓库，创建分支，提交 Pull Request。
- 代码风格：遵循 [PEP 8](https://peps.python.org/pep-0008/)，使用 `black` 格式化。

---

## 📄 许可证

本项目采用 [MIT 许可证](LICENSE)。您可以自由使用、修改和分发，但需保留版权声明。

---

## 🙏 致谢

- 感谢 [小智 AI 硬件](https://github.com/xiaozhi-ai) 项目提供的优秀协议参考。
- 感谢所有贡献者和使用者。

---

**更多文档**：
- [语音网关详细设计](docs/voice_gateway.md)
- [RAG 核心模块设计](docs/rag_process.md)
- [API 参考文档](docs/api.md)

如有问题，欢迎通过 Issue 或邮件联系。