使用 Docker 部署 voice-changer 实时语音转换客户端VC Client构建、权重准备与运行参数全指南【免费下载链接】voice-changerリアルタイムボイスチェンジャー Realtime Voice Changer项目地址: https://gitcode.com/gh_mirrors/vo/voice-changer本篇指南聚焦开源实时语音转换项目 voice-changerRealtime Voice Changer中的 Docker 化客户端VC Client部署方案即 docker_vcclient/README_en.md 所讲解的完整流程。读者将掌握如何通过npm run build:docker:vcclient构建镜像、如何将外部模型权重放入docker_vcclient/weights、如何使用start_docker.sh启动 GPU/CPU 服务并自定义端口以及如何结合 MMVCServerSIO.py 的命令行参数理解服务的底层启动逻辑最终在浏览器中打开实时变声界面。一、VC Client 是什么Docker 化的实时变声服务端voice-changer 项目整体分为浏览器端 GUIclient、Python 服务端server与多种 VC 模型实现RVC、SoVitsSvc40、DDSP-SVC、DiffusionSVC 等。VC Client for Docker目录docker_vcclient/就是把服务端及其依赖打包成开箱即用的 Docker 镜像让用户无需手动配置 Python 环境与 CUDA 依赖即可运行实时语音转换。从 docker_vcclient/Dockerfile 可以看出镜像的构成思路基础镜像使用nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04注释中保留可切换的 CUDA 12 版本安装python3-pip、espeak、gosu、libsndfile1-dev、emacs、git等运行依赖在构建时git clone指定版本v.1.5.3.13的 voice-changer 仓库固定安装numpy1.23.5、pyworld0.3.3 --no-build-isolation再安装 server/requirements.txt 中的依赖将setup.sh与exec.sh拷入/voice-changer/server以setup.sh作为容器 ENTRYPOINT。镜像启动后容器内的实际服务进程由 docker_vcclient/exec.sh 调用python3 MMVCServerSIO.py $拉起即运行 server/MMVCServerSIO.py 这一服务入口该入口在文件顶部通过setupArgParser()解析参数并加载VoiceChangerParams、VoiceChangerManager、SocketIO 应用与 REST API。二、构建镜像npm run build:docker:vcclient在仓库根目录执行npm run build:docker:vcclient该命令定义于仓库根目录的 package.jsonbuild:docker:vcclient: date %Y%m%d%H%M%S docker_vcclient/dummy DOCKER_BUILDKIT1 docker build -f docker_vcclient/Dockerfile docker_vcclient/ -t vcclient其内部做了两件事以当前时间戳写入docker_vcclient/dummy文件作为 Docker 构建上下文的时间戳标记避免缓存失效启用 BuildKit使用docker_vcclient/Dockerfile构建输出镜像名为vcclient。构建完成后可用docker images确认镜像存在。注意构建过程会git clone上游仓库并安装大量 Python 依赖含 pyworld 源码编译需要较长耗时与网络连接。三、运行前的准备放置外部模型权重实时变声服务依赖一系列外部预训练模型。运行前需要把这些权重文件放入docker_vcclient/weights目录。具体需要哪些文件取决于你使用哪种 VC 模型。原文档给出的目录结构如下$ tree docker_vcclient/weights/ docker_vcclient/weights/ ├── checkpoint_best_legacy_500.onnx ├── checkpoint_best_legacy_500.pt ├── hubert-soft-0d54a1f4.pt ├── hubert_base.pt └── nsf_hifigan ├── NOTICE.txt ├── NOTICE.zh-CN.txt ├── config.json └── model其中各文件对应的用途结合 server/MMVCServerSIO.py 的参数定义可以确认权重文件对应命令行参数作用checkpoint_best_legacy_500.pt/.onnx--content_vec_500/--content_vec_500_onnxcontent vec 500 编码器PyTorch 与 ONNX 版本hubert_base.pt--hubert_baseHuBERT base 特征提取模型hubert-soft-0d54a1f4.pt--hubert_softHuBERT soft 模型常用于 RVC 推理管线nsf_hifigan/model--nsf_hifiganNSF-HiFiGAN 声码器目录含config.json与model另外start_docker.sh 中实际传入的启动参数还涉及--hubert_base_jprinna hubert base jp、--crepe_onnx_full、--crepe_onnx_tiny、--rmvpeRMVPE 音高提取器等说明完整使用 RVC 管线时还需要额外的预训练文件这些均与 server/MMVCServerSIO.py 中的 argparse 定义一一对应。实际使用时请根据你选择的 VC 类型如 RVC、SoVitsSvc40将对应权重放入该目录。四、运行容器bash start_docker.sh在仓库根目录执行bash start_docker.sh脚本 start_docker.sh 的核心逻辑如下默认镜像为dannadori/vcclient:20230826_211406预发布镜像默认端口18888默认USE_GPUon、USE_LOCALoffGPU 模式使用docker run -it --rm --gpus all --shm-size1024MCPU 模式去掉--gpus all通过-e EX_IP、-e EX_PORT向容器传递主机 IP 与端口通过LOCAL_UID/LOCAL_GID让容器内用户与宿主机用户一致见 docker_vcclient/setup.sh读取LOCAL_UID/LOCAL_GID创建同名用户并gosu降权执行将宿主机docker_folder/model_dir与docker_folder/pretrain分别挂载到容器内/voice-changer/server/model_dir与/voice-changer/server/pretrain端口映射为${EX_PORT}:18888向容器进程exec.sh透传$传入-p 18888 --https true及一组模型权重路径参数。启动成功后用浏览器访问https://主机IP:EX_PORT脚本默认开启了--https true浏览器会提示自签名证书需手动信任原文档明确目前仅支持 Chrome即可看到实时变声的 GUI 界面。GUI 通过 SocketIO 与 server/MMVCServerSIO.py 通信后续在界面中加载模型槽即可进行实时语音转换。五、带选项运行GPU/端口/本地镜像start_docker.sh支持通过环境变量覆盖默认值原文档给出了三种典型用法1. 不使用 GPUCPU 模式USE_GPUoff bash start_docker.sh脚本中USE_GPU默认on置为off后走 CPU 分支docker run不再附加--gpus all。无 NVIDIA GPU 或驱动不支持时务必使用此选项。2. 指定端口EX_PORTport bash start_docker.sh默认端口为18888。通过EX_PORT可自定义宿主机监听端口容器内仍映射到18888。同时该端口值会通过-e EX_PORT传给容器用于 HTTPS 服务与客户端通信。3. 使用本地构建的镜像USE_LOCALon bash start_docker.sh默认使用官方预构建镜像dannadori/vcclient:20230826_211406置为on后改用上一节npm run build:docker:vcclient构建出的本地镜像vcclient适合离线环境或修改源码后的自测。三个变量可组合使用例如USE_GPUoff EX_PORT18080 USE_LOCALon bash start_docker.sh。六、进阶理解容器启动链与命令行参数从源码结构可以梳理出完整的启动链路start_docker.sh→docker run ... vcclient -p 18888 --https true --content_vec_500 ...→ 容器 ENTRYPOINTsetup.sh→gosu降权执行exec.sh $→python3 MMVCServerSIO.py $。也就是说start_docker.sh末尾追加的参数最终都会透传给 server/MMVCServerSIO.py 的 argparse 解析器。该解析器server/MMVCServerSIO.py支持的主要参数包括-p监听端口默认18888--https是否启用 HTTPS布尔默认关闭start_docker.sh显式传--https true--httpsKey/--httpsCert/--httpsSelfSignedHTTPS 证书相关默认自签名由 server/mods/ssl.py 的create_self_signed_cert生成--model_dir模型文件目录默认model_dir--content_vec_500、--content_vec_500_onnx、--content_vec_500_onnx_oncontent vec 500 编码器路径与是否启用 ONNX--hubert_base、--hubert_base_jp、--hubert_soft多种特征提取模型路径--whisper_tinyWhisper tiny 模型路径--nsf_hifiganNSF-HiFiGAN 声码器目录--crepe_onnx_full、--crepe_onnx_tiny、--rmvpe、--rmvpe_onnxCREPE / RMVPE 音高提取模型路径--hostHTTP 监听地址默认127.0.0.1需要容器外访问时传0.0.0.0--allowed-origins可追加允许多个来源 URL默认允许http(s)://127.0.0.1:{port}与http(s)://localhost:{port}。容器内setup.shdocker_vcclient/setup.sh会依据环境变量LOCAL_UID/LOCAL_GID默认9001创建非 root 用户并chmod uogrwx tmp_dir再以gosu切换用户执行exec.sh避免容器内以 root 运行产生文件权限问题——这也是挂载model_dir、pretrain目录后宿主机文件权限保持一致的关键设计。七、开发者专用推送镜像到仓库该命令仅面向镜像维护者普通使用者无需执行npm run push:docker:vcclient其对应脚本 script/003_pushDockerVCClient.sh 会以当前时间戳打标签如dannadori/vcclient:日期_时间、执行docker login、docker tag与docker push。执行前请确认已登录 Docker Hub 且有对应仓库的推送权限。八、常见问题与排查要点浏览器无法打开界面确认EX_PORT与访问地址一致脚本默认启用 HTTPS需使用https://协议并信任自签名证书原文档指出当前仅支持 Chrome。GPU 模式启动失败检查宿主机是否安装 NVIDIA 驱动与 nvidia-container-toolkit无 GPU 环境请改用USE_GPUoff。模型加载报错核对docker_vcclient/weights本地构建或docker_folder/pretrain运行脚本挂载目录中的权重文件是否与所选 VC 类型匹配路径是否与 start_docker.sh 中透传的参数一致。容器内文件权限异常setup.sh依赖LOCAL_UID/LOCAL_GID环境变量start_docker.sh会自动注入$(id -u $USER)/$(id -g $USER)手动执行docker run时需自行传入。九、相关资源项目总览README.md、README_en.md容器相关 docker_vcclient/Dockerfile、docker_vcclient/setup.sh、docker_vcclient/exec.sh、start_docker.sh服务端入口与参数server/MMVCServerSIO.py服务端依赖server/requirements.txt镜像推送脚本script/003_pushDockerVCClient.sh【免费下载链接】voice-changerリアルタイムボイスチェンジャー Realtime Voice Changer项目地址: https://gitcode.com/gh_mirrors/vo/voice-changer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考