Files

T

2026-04-08 14:38:04 +08:00

5.2 KiB

Raw Permalink Blame History

部署说明

本文说明如何把「3D 数字人语音聊天」服务端部署到一台新机器（Linux / WSL / macOS 等类 Unix 环境）。唯一需要能访问公网的依赖是 LLM API；语音相关权重应放在项目内 models/ 目录，不在运行时从公网拉取。

1. 环境与依赖

Python：建议 3.12（与当前 requirements.txt 一致）。
系统工具：openssl（生成自签证书）；可选 ffmpeg（若你后续扩展音视频流程）。
硬件：CPU 可运行；有 NVIDIA GPU 时 ASR 等会优先用 CUDA（无卡则回退 CPU，可能较慢）。
磁盘：models/ 中 ASR + TTS 权重合计约 1.2GB+，请预留空间。

2. 获取代码与虚拟环境

git clone <你的仓库地址> product
cd product

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

pip install -U pip
pip install -r requirements.txt

说明：依赖里已包含 huggingface_hub（由其它包装带动）。若单独只为下载权重，也可 pip install huggingface_hub。

3. 准备本地模型（`models/`）

首次在一台能访问 Hugging Face的机器上执行（仅需一次，或把整份 models/ 目录打包拷贝到离线机）：

source .venv/bin/activate
python scripts/vendor_hf_models.py

该脚本会：

从已安装的 silero-vad 包复制 models/vad/silero_vad.jit
拉取 ASR：models/asr/SenseVoiceSmall/
拉取 TTS（Kokoro）：models/tts/Kokoro-82M/（含 voices/ 下各 .pt 音色）

若目标机无外网，可在有网机器上跑完上述命令后，整体复制 models/ 到部署机同一路径（相对于项目根）。

仅补全 VAD、不拉 HF（需已 pip install silero-vad）：

python scripts/vendor_hf_models.py --skip-hf

4. 配置环境变量（`.env`）

cp .env.example .env

必须非空（见 config.py 校验）：

变量	含义
`LLM_API_KEY`	OpenAI 兼容接口的 API Key
`LLM_BASE_URL`	例如 `https://api.deepseek.com/v1`
`LLM_MODEL`	例如 `deepseek-chat`

HTTP 服务（不要使用已废弃的 WEBRTC_*）：

变量	含义
`HTTP_HOST`	监听地址，一般 `0.0.0.0`
`HTTP_PORT`	端口，例如 `8080` 或 `8018`

HTTPS（推荐用于跨设备访问页面与麦克风）：

证书路径建议写相对项目根，便于迁移，例如：
- SSL_CERTFILE=certs/dev-cert.pem
- SSL_KEYFILE=certs/dev-key.pem
程序会把相对路径解析为项目根下的绝对路径。

TTS 音色：TTS_VOICE 必须与 models/tts/Kokoro-82M/voices/<名称>.pt 一致（默认示例为 zf_xiaoxiao）。

完整字段说明见仓库根目录 .env.example。

5. 生成自签证书（可选但常需要）

在项目根目录执行：

bash scripts/gen-self-signed-cert.sh

生成 certs/dev-cert.pem 与 certs/dev-key.pem，并在 .env 中配置上一节的 SSL_CERTFILE、SSL_KEYFILE。

默认证书主题为 CN=localhost。用局域网 IP 访问时浏览器可能提示证书与地址不符，属自签名常见情况，可在浏览器中选择继续访问；生产环境请改用正规 CA 或内网 PKI 签发的证书。

6. 启动服务

开发 / 前台运行：

source .venv/bin/activate
python main.py

或使用脚本（会读 .env 中的 HTTP_HOST、HTTP_PORT）：

bash scripts/start-public.sh

HTTPS：当 .env 中 SSL_CERTFILE、SSL_KEYFILE 均有效且文件存在时，main.py 会通过 uvicorn 加载证书（与 config 中解析后的路径一致）。

启动后在本机浏览器访问：

http(s)://127.0.0.1:<HTTP_PORT>/
http(s)://<服务器局域网IP>:<HTTP_PORT>/（需防火墙放行该端口）

7. 防火墙与端口

确保部署机对客户端开放 HTTP_PORT（TCP）。若前面有云厂商安全组，需同步放行。

8. 目录与可移植性约定

项目根：所有相对路径（SSL、models/ 布局、web/ 静态资源）均以含有 main.py 与 config.py 的目录为基准；启动时工作目录应为此目录。
可选：环境变量 VISUAL_CHAT_PYTHON 可指向指定 Python 解释器（部分 scripts/*.sh 会优先使用）。

9. 验证

curl -s "http://127.0.0.1:${HTTP_PORT:-8080}/health" | head

或用仓库内脚本（需根据实际 URL 调整）：

python scripts/qa_check.py --base-url "https://127.0.0.1:8080" --rounds 3

（若仅 HTTP，把 base-url 改成 http://...。）

10. 常见问题

.env 里 LLM_* 为空：应用在加载 config 时会校验失败，请务必填写有效值。
ASR/TTS 不工作：检查 models/asr/SenseVoiceSmall/ 是否含 configuration.json；models/tts/Kokoro-82M/ 是否含 config.json、权重 .pth 与 voices/<TTS_VOICE>.pt。
麦克风在别的设备上不可用：多数浏览器要求 HTTPS 与用户手势；请启用 HTTPS 并在页面内点击「连接语音通道」等操作。
旧变量名：WEBRTC_HOST、WEBRTC_PORT、STUN_URL 已废弃，请只使用 HTTP_HOST、HTTP_PORT。

更细的语音/文本流水线时序见 development-guide.md。

5.2 KiB Raw Permalink Blame History Unescape Escape