298 lines
5.6 KiB
Markdown
298 lines
5.6 KiB
Markdown
# Voice CLI - 语音转文字服务
|
||
|
||
**[English](README.md)** | **[简体中文](README_zh-CN.md)**
|
||
|
||
---
|
||
|
||
# Voice CLI - 语音转文字服务
|
||
|
||
高性能语音转文字 HTTP 服务，基于 Rust 构建，使用 Whisper 引擎提供准确的语音识别能力。
|
||
|
||
## 核心特性
|
||
|
||
### 语音处理能力
|
||
- **多格式支持**: MP3, WAV, FLAC, M4A, AAC, OGG 等主流音频格式
|
||
- **自动格式转换**: 基于 rs-voice-toolkit 的智能音频处理
|
||
- **Whisper 模型**: 支持 tiny/base/small/medium/large 系列模型
|
||
- **自动模型管理**: 按需下载和管理 Whisper 模型
|
||
|
||
### 部署模式
|
||
- **🏠 单节点部署**: 快速启动，适合小规模使用
|
||
|
||
### 高级功能
|
||
- **RESTful API**: 完整的 HTTP API 接口
|
||
- **实时监控**: 服务状态、健康检查
|
||
- **任务处理**: 高效的音频处理流水线
|
||
|
||
> **注意**: TTS（文本转语音）功能目前正在开发中，存在已知问题，将在未来版本中提供。
|
||
|
||
## 系统要求
|
||
|
||
- **操作系统**: Linux/macOS/Windows
|
||
- **内存**: 最低 2GB，推荐 8GB+
|
||
- **存储**: 至少 5GB（用于模型存储）
|
||
|
||
## 快速安装
|
||
|
||
### 从源码构建
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone https://github.com/nuwax-ai/mcp-proxy
|
||
cd mcp-proxy
|
||
|
||
# 构建 voice-cli
|
||
cargo build --release -p voice-cli
|
||
|
||
# 二进制文件位置
|
||
ls target/release/voice-cli
|
||
```
|
||
|
||
## 单节点部署
|
||
|
||
### 方式一：直接运行（最简单）
|
||
|
||
```bash
|
||
# 1. 切换到工作目录
|
||
mkdir -p /opt/voice-service
|
||
cd /opt/voice-service
|
||
cp /path/to/voice-cli ./
|
||
|
||
# 2. 启动服务（自动创建配置文件）
|
||
./voice-cli server run
|
||
|
||
# 3. 测试服务
|
||
curl -X POST http://localhost:8080/transcribe \
|
||
-F "audio=@test.mp3" \
|
||
-F "model=base"
|
||
```
|
||
|
||
### 方式二：后台运行（使用 nohup）
|
||
|
||
```bash
|
||
# 1. 启动后台服务
|
||
nohup ./voice-cli server run > server.log 2>&1 &
|
||
|
||
# 2. 检查进程状态
|
||
ps aux | grep voice-cli
|
||
|
||
# 3. 停止服务
|
||
pkill -f "voice-cli server run"
|
||
|
||
# 4. 查看日志
|
||
tail -f server.log
|
||
```
|
||
|
||
### 方式三：系统服务（推荐生产环境）
|
||
|
||
```bash
|
||
# 1. 创建配置文件
|
||
./voice-cli server init
|
||
|
||
# 2. 编辑配置文件（可选）
|
||
nano server-config.yml
|
||
|
||
# 3. 使用配置文件运行
|
||
./voice-cli server run --config server-config.yml
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### 生成配置文件
|
||
|
||
```bash
|
||
# 生成默认配置文件
|
||
./voice-cli server init
|
||
|
||
# 生成到指定路径
|
||
./voice-cli server init --config /path/to/config.yml
|
||
|
||
# 强制覆盖现有文件
|
||
./voice-cli server init --force
|
||
```
|
||
|
||
### 配置文件示例 (server-config.yml)
|
||
|
||
```yaml
|
||
server:
|
||
host: "0.0.0.0"
|
||
port: 8080
|
||
max_file_size: 268435456 # 256MB
|
||
cors_enabled: true
|
||
|
||
whisper:
|
||
default_model: "base"
|
||
models_dir: "./models"
|
||
auto_download: true
|
||
supported_models:
|
||
- "tiny"
|
||
- "base"
|
||
- "small"
|
||
- "medium"
|
||
- "large"
|
||
audio_processing:
|
||
sample_rate: 16000
|
||
channels: 1
|
||
bit_depth: 16
|
||
workers:
|
||
transcription_workers: 2
|
||
channel_buffer_size: 100
|
||
worker_timeout: 3600
|
||
|
||
logging:
|
||
level: "info"
|
||
log_dir: "./logs"
|
||
max_file_size: "10MB"
|
||
max_files: 10
|
||
|
||
daemon:
|
||
pid_file: "./voice_cli.pid"
|
||
log_file: "./logs/daemon.log"
|
||
work_dir: "./work"
|
||
```
|
||
|
||
## 命令行使用
|
||
|
||
### 主要命令
|
||
|
||
```bash
|
||
# 初始化配置文件
|
||
voice-cli server init [--config <path>] [--force]
|
||
|
||
# 运行服务（前台模式）
|
||
voice-cli server run [--config <path>]
|
||
|
||
# 显示帮助信息
|
||
voice-cli --help
|
||
voice-cli server --help
|
||
```
|
||
|
||
### 环境变量配置
|
||
|
||
支持通过环境变量覆盖配置：
|
||
|
||
```bash
|
||
# HTTP 端口
|
||
VOICE_CLI_PORT=8081
|
||
|
||
# 日志级别
|
||
VOICE_CLI_LOG_LEVEL=debug
|
||
|
||
# 默认模型
|
||
VOICE_CLI_DEFAULT_MODEL=large
|
||
|
||
# 模型目录
|
||
VOICE_CLI_MODELS_DIR=/opt/models
|
||
```
|
||
|
||
## HTTP API 接口
|
||
|
||
### 语音转录接口
|
||
|
||
```bash
|
||
POST /transcribe
|
||
Content-Type: multipart/form-data
|
||
|
||
参数:
|
||
- audio: 音频文件 (必填)
|
||
- model: 模型名称 (可选，默认使用配置的默认模型)
|
||
- language: 语言代码 (可选，如 "zh", "en")
|
||
- response_format: 响应格式 (可选，"json" 或 "text"，默认 "json")
|
||
```
|
||
|
||
### 健康检查接口
|
||
|
||
```bash
|
||
GET /health
|
||
```
|
||
|
||
### 示例请求
|
||
|
||
```bash
|
||
# 使用 curl
|
||
curl -X POST http://localhost:8080/transcribe \
|
||
-F "audio=@speech.wav" \
|
||
-F "model=base" \
|
||
-F "language=zh"
|
||
|
||
# 响应示例
|
||
{
|
||
"text": "你好，这是一个测试语音",
|
||
"language": "zh",
|
||
"duration": 5.2,
|
||
"model": "base",
|
||
"processing_time": 2.1
|
||
}
|
||
```
|
||
|
||
## 监控和日志
|
||
|
||
### 日志文件
|
||
- `./logs/server.log` - 服务运行日志
|
||
- `./logs/daemon.log` - 后台服务日志
|
||
|
||
### 日志级别
|
||
支持以下日志级别：
|
||
- `trace` - 最详细的调试信息
|
||
- `debug` - 调试信息
|
||
- `info` - 一般信息（默认）
|
||
- `warn` - 警告信息
|
||
- `error` - 错误信息
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
|
||
1. **端口被占用**
|
||
```bash
|
||
# 检查端口占用
|
||
lsof -i :8080
|
||
|
||
# 杀死占用进程
|
||
kill -9 <PID>
|
||
|
||
# 或者修改配置端口
|
||
VOICE_CLI_PORT=8081 ./voice-cli server run
|
||
```
|
||
|
||
2. **模型下载失败**
|
||
```bash
|
||
# 检查网络连接
|
||
curl -I https://huggingface.co
|
||
|
||
# 手动下载模型
|
||
# 模型下载到 ./models/ggml-{model_name}.bin
|
||
```
|
||
|
||
3. **内存不足**
|
||
```bash
|
||
# 使用较小的模型
|
||
VOICE_CLI_DEFAULT_MODEL=tiny ./voice-cli server run
|
||
|
||
# 减少工作线程
|
||
VOICE_CLI_TRANSCRIPTION_WORKERS=1 ./voice-cli server run
|
||
```
|
||
|
||
### 调试模式
|
||
|
||
```bash
|
||
# 启用详细日志
|
||
RUST_LOG=debug ./voice-cli server run
|
||
|
||
# 查看实时日志
|
||
tail -f ./logs/server.log
|
||
```
|
||
|
||
## 许可证
|
||
|
||
本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。
|
||
|
||
## 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
## 支持
|
||
|
||
- 提交 Issue: [GitHub Issues](https://github.com/nuwax-ai/mcp-proxy/issues)
|
||
- 文档: [项目 Wiki](https://github.com/nuwax-ai/mcp-proxy/wiki)
|