提交qiming-mcp-proxy
This commit is contained in:
Codex
297
qiming-mcp-proxy/voice-cli/README_zh-CN.md
Normal file
297
qiming-mcp-proxy/voice-cli/README_zh-CN.md
Normal file
@@ -0,0 +1,297 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user