# VoiceFlow

**Repository Path**: codealy/voice-flow

## Basic Information

- **Project Name**: VoiceFlow
- **Description**: 实时语音输入转文本
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-01
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VoiceFlow - 语音转文本工程实践

生产级语音转文本服务平台，包含API网关、多STT引擎支持和完整的异步处理能力。

## 工程结构

```
VoiceFlow/
├── gateway/                     # API网关 (Java 21 + Spring Boot 3.2)
│   ├── src/main/java/          # 源代码
│   ├── src/main/resources/     # 配置文件
│   ├── Dockerfile              # Docker构建文件
│   └── pom.xml                 # Maven配置
│
├── ai-voice-to-text/
│   ├── example/
│   │   ├── sense_voice/        # SenseVoice Demo (Python)
│   │   └── voice-py/           # 前端可视化服务 Demo
│   │
│   ├── voice-curl-py/          # 本地模型服务 (Python 3.10 + FastAPI + Celery)
│   │   ├── server/             # FastAPI 后端
│   │   ├── front/              # React 前端
│   │   └── docker-compose.yml  # Docker编排
│   │
│   └── sense-voice-server/     # STT编排服务 (Java 21 + Spring Boot)
│       ├── src/main/java/      # 源代码
│       │   └── com/voiceflow/stt/
│       │       ├── engine/     # 引擎接口和枚举
│       │       ├── engine/impl/# 引擎实现
│       │       ├── model/      # 数据模型
│       │       ├── strategy/   # 引擎选择策略
│       │       ├── orchestrator/# 编排服务
│       │       ├── client/     # HTTP客户端
│       │       ├── config/     # 配置类
│       │       └── api/        # REST API
│       ├── src/main/resources/ # 配置文件
│       ├── Dockerfile          # Docker构建文件
│       └── pom.xml             # Maven配置
│
├── docker-compose.yml          # 整体部署编排
├── docker-compose.gpu.yml      # GPU支持配置
└── deploy.sh                   # 一键部署脚本
```

## 核心功能

- **统一API网关**: JWT认证、请求限流、服务熔断、动态路由
- **多STT引擎支持**: 本地SenseVoice、科大讯飞、阿里云
- **异步任务处理**: Celery + Redis 高并发异步转录
- **实时进度推送**: WebSocket 实时反馈
- **HTTP回调通知**: 支持第三方系统回调
- **情感分析**: SenseVoice 支持情感识别
- **说话人分离**: 科大讯飞支持说话人分离

## 快速开始

### 环境要求

- Docker & Docker Compose
- Java 21 (本地开发)
- Python 3.10+ (本地开发)
- Node.js 18+ (前端开发)

### 一键部署

```bash
# 克隆项目
git clone https://github.com/voiceflow/voiceflow.git
cd voiceflow

# 开发环境部署
./deploy.sh docker

# GPU加速部署
./deploy.sh docker gpu

# 生产环境部署
./deploy.sh production
```

### 手动部署

```bash
# 构建并启动所有服务
docker compose up -d

docker compose --env-file .env.development up -d


# 查看日志
docker compose logs -f

# 停止服务
docker compose down
```

## API使用

### 提交转录任务

```bash
curl -X POST http://localhost:8080/api/v1/stt/transcribe \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "X-Callback-Url: https://your-server/callback" \
  -d '{
    "fileName": "test.wav",
    "fileSize": 1024000,
    "language": "zh",
    "enableSentimentAnalysis": true,
    "enableSpeakerDiarization": false,
    "audioData": "BASE64_ENCODED_AUDIO"
  }'
```

### 查询任务状态

```bash
curl http://localhost:8080/api/v1/tasks/{taskId}/status \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### 获取转录结果

```bash
curl http://localhost:8080/api/v1/tasks/{taskId}/result \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## 引擎能力对比

| 能力 | Local SenseVoice | 科大讯飞 LFASR | 阿里云 Paraformer |
|------|-----------------|---------------|------------------|
| 最大时长 | 无限制 | 5小时 | 2小时 |
| 最大文件 | 无限制 | 500MB | 100MB |
| 支持语言 | zh/en/yue/ja/ko | zh/en/yue等 | zh/en等 |
| 情感分析 | 支持 | 不支持 (需大模型版) | 不支持 |
| 说话人分离 | 不支持 | 支持 | 支持 |
| 分词 | 支持 | 支持 | 支持 |
| 回调通知 | 支持 | 支持 | 支持 |
| 成本 | 免费 | 付费 | 付费 |

## 配置说明

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `GATEWAY_PORT` | 网关端口（宿主机） | 8080 |
| `STT_SERVER_PORT` | STT服务端口（宿主机） | 8081 |
| `BACKEND_PORT` | 后端端口（宿主机） | 8000 |
| `FRONTEND_PORT` | 前端端口（宿主机） | 3000 |
| `REDIS_EXTERNAL_PORT` | Redis端口（宿主机映射） | 6379 |
| `DEVICE` | 推理设备 | cpu |
| `JWT_SECRET_KEY` | JWT密钥（>=32字节） | - |

### 云服务API配置

```bash
# 科大讯飞
XUNFEI_APP_ID=your_app_id
XUNFEI_API_KEY=your_api_key
XUNFEI_API_SECRET=your_api_secret

# 阿里云
ALIYUN_ACCESS_KEY=your_access_key
ALIYUN_ACCESS_SECRET=your_access_secret
```

## 架构设计

```
┌─────────────┐    ┌─────────────┐    ┌─────────────────────┐
│   Gateway   │───▶│ STT Server │───▶│ voice-curl-py       │
│   :8080     │    │   :8081     │    │ Backend: :8000      │
│             │    │             │    │ Worker: Celery      │
│ - JWT认证   │    │ - 引擎编排  │    │ Model: SenseVoice   │
│ - 限流熔断  │    │ - 策略选择  │    │ GPU/CPU推理         │
│ - 动态路由  │    │ - 降级处理  │    │                     │
└─────────────┘    └─────────────┘    └─────────────────────┘
       │                  │                     │
       └──────────────────┴─────────────────────┘
                          │
                   ┌──────┴──────┐
                   │    Redis    │
                   │   :6379     │
                   └─────────────┘
```

## 许可证

MIT License