zipenhancer 0.2.0

语音降噪核心库 — ZipEnhancer/FRCRN/MossFormer2 纯 PyTorch 推理

 ______       _____       _                               
|__  (_)_ __ | ____|_ __ | |__   __ _ _ __   ___ ___ _ __ 
  / /| | '_ \|  _| | '_ \| '_ \ / _` | '_ \ / __/ _ \ '__|
 / /_| | |_) | |___| | | | | | | (_| | | | | (_|  __/ |   
/____|_| .__/|_____|_| |_|_| |_|\__,_|_| |_|\___\___|_|   
       |_|                                                

做了什么

• 模型剥离 — 从 ModelScope 黑盒 pipeline 中提取出 ZipEnhancer，用原生 PyTorch 加载权重推理，不再依赖 pipeline 封装
• FP16 半精度推理 — 仅模型计算部分使用 FP16，STFT/iSTFT 保持 FP32 避免 cuFFT 精度问题，显存占用降低 ~40%
• 长音频分段 — 4s 滑动窗口 + 75% 重叠的 overlap-add 策略，支持任意时长音频，彻底解决 CUDA OOM
• 多模型切换 — 同时支持 ZipEnhancer（轻量）、FRCRN（实时）、MossFormer2（高质）三种模型
• 声道/位深保持 — 立体声输入 → 立体声输出，32-bit float / 16-bit PCM 自动适配
• PyPI 发布 — pip install zipenhancer 一键安装，也可作为库集成到你的项目中

它能做什么？

• 清除录音中的环境噪声（空调声、风扇声、键盘声、街道噪音等）
• 支持单文件和批量处理两种模式
• 多种降噪模型一键切换
• GPU 加速，实时率可达 20x 以上（RTX 4090）

无需 ModelScope pipeline 黑盒，一行命令启动服务，适合集成到语音处理流程、会议录音后处理、音频预处理管道等场景。

快速开始

方式一：pip 安装（推荐）

pip install zipenhancer

如需 FRCRN 或 MossFormer2 模型（依赖 ModelScope）：

pip install zipenhancer[modelscope]

在代码中使用：

import soundfile as sf
from zipenhancer import denoise, write

audio, sr = sf.read("input.wav")
denoised, proc_time, duration = denoise(audio, sr)
print(f"处理耗时: {proc_time:.2f}s, 实时比: {duration/proc_time:.1f}x")
write("output.wav", denoised, sr)

方式二：手动部署

1. 创建虚拟环境

conda create -n zipenhancer python=3.10 -y
conda activate zipenhancer

2. 安装依赖

pip install -r requirements.txt

GPU 加速（NVIDIA 显卡，先于上一步安装 CUDA 版 PyTorch）：

pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt

3. 配置

复制 .env.example 为 .env，按需求修改：

cp .env.example .env

4. 启动

uvicorn app:app --host 0.0.0.0 --port 8765

方式三：Docker 部署

1. 前置条件

安装 Docker 和 NVIDIA Container Toolkit。

2. 构建并启动

# 从 docker/ 目录启动
cd docker
docker compose up -d

# 或从项目根目录直接运行
docker run --gpus all -p 8765:8765 zipenhancer:latest

所有依赖和模型已在构建时下载，启动即用，无需额外等待。

文档

文档	说明
包使用文档	pip install zipenhancer 的 Python API 参考（模型列表、降噪强度、输出格式）
API 接口文档	FastAPI 接口说明（curl 示例、参数、响应格式）
CLI 命令行文档	终端降噪命令（单文件、批量、管道、进度条）
Docker 部署指南	Docker 构建与部署

可用模型

模型 ID	说明
iic/speech_zipenhancer_ans_multiloss_16k_base	ZipEnhancer（轻量）
iic/speech_frcrn_ans_cirm_16k	FRCRN（实时降噪）
iic/speech_mossformer2_ans_48k	MossFormer2（高质量）

Roadmap

已完成

• 单文件语音降噪
• 批量文件语音降噪
• 多模型切换（ZipEnhancer / FRCRN / MossFormer2）
• 音量归一化
• 自定义输出采样率
• 声道/位深保持
• FP16 半精度推理

计划中

P0 — 短期（完成）

• Docker 一键部署（多阶段构建、GPU 直通、健康检查、优雅关闭）
• 输出格式选择（WAV / MP3 / FLAC / OGG，编码参数可配）
• 降噪强度控制（频域掩码指数，0~100% 可调） 论文参考：DeepFilterNet Base

P1 — 中期（4-6 个月）

• PyPI 发布（pip install zipenhancer）
• Noise Gate（Attack / Release / Hold / Hysteresis / Look-ahead）
• 残差监听（延迟对齐 + 位深统一，输出原始与降噪的差值信号）
• 频段选择降噪（Linkwitz-Riley 分频，各频段独立降噪强度）
• VAD 自动静音切除（Silero VAD + 状态机 + 自适应阈值 + Cross-fade 拼接）

P2 — 中后期（5-7 个月）

• 噪声轮廓学习（基于 VAD 的自适应谱减法后处理、音乐噪声抑制）
• 质量评估指标（PESQ / STOI / Si-SNR / DNSMOS，离线评测管线）
• 音频格式转换（ffmpeg 封装，格式兼容矩阵，元数据透传）

P3 — 长期

• 异步任务 + 进度查询（2-3 个月，任务持久化、队列调度、Worker 池、Webhook）
• 去混响（4-8 个月，WPE + DNN，场景分类 + 参数矩阵）
• 实时流式降噪（4-8 个月，WebSocket + 因果模型 + Jitter Buffer + AEC）

需要前端、CLI协助

• CLI 命令行工具（多命令、管道、进度条、配置文件）
• 输入音频信息预览（波形峰值、LUFS 响度、削波检测、完整性校验）
• Web UI 界面（3-4 个月，拖拽上传 + 波形/频谱可视化 + 在线试听 + Before/After 对比）

已评估放弃

• 超分（低采样率 → 高采样率） — 研究级难题，和降噪正交
• 模型量化 int8 — 模型架构（自定义算子）不支持
• 语音识别（ASR） — 另一个产品领域
• 说话人分离 — 重叠说话人问题当前无工业级开源方案

项目结构

├── app.py                 # FastAPI 服务主程序
├── log.py                 # 日志管理模块
├── zipenhancer/           # 降噪核心包
│   ├── __init__.py
│   ├── codec.py           # 音频编码模块（WAV/FLAC/MP3/OGG）
│   ├── denoise.py         # 降噪核心函数
│   ├── standalone.py      # 剥离版推理（纯 PyTorch）
│   ├── models/            # 模型架构
│   │   ├── zipenhancer.py
│   │   └── layers/
│   │       ├── generator.py
│   │       ├── scaling.py
│   │       ├── zipenhancer_layer.py
│   │       └── zipformer.py
│   └── configs/
│       └── configuration.json
├── docker/
│   ├── Dockerfile          # Docker 构建文件
│   └── docker-compose.yml  # Docker Compose 配置
├── docs/
│   ├── index.html           # GitHub Pages 降噪对比页面
│   ├── guide/
│   │   ├── docker.md        # Docker 部署指南
│   │   ├── package.md       # pip 包使用文档
│   │   └── api.md           # API 接口文档
│   └── mp3_audio/           # GitHub Pages 播放用 MP4 音频
├── images/                # README 截图
├── pyproject.toml         # 项目构建配置（PyPI 打包）
├── requirements.txt       # 依赖列表
├── LICENSE                # MIT 开源许可证
├── .env.example           # 环境配置模板
├── .gitignore             # Git 忽略规则
├── README.md              # 使用文档
└── logs/                  # 日志输出目录
    ├── app/               # 全部日志
    └── error/             # 错误日志

Credits

• 降噪模型：阿里达摩院 ZipEnhancer（Apache 2.0）
• 模型提取参考：boreas-l/zipEnhancer

License

MIT © 2026 gao yi jun