147 lines
5.2 KiB
Markdown
147 lines
5.2 KiB
Markdown
# 部署说明
|
||
|
||
本文说明如何把「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. 获取代码与虚拟环境
|
||
|
||
```bash
|
||
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/` 目录打包拷贝到离线机）：
|
||
|
||
```bash
|
||
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`）：
|
||
|
||
```bash
|
||
python scripts/vendor_hf_models.py --skip-hf
|
||
```
|
||
|
||
## 4. 配置环境变量（`.env`）
|
||
|
||
```bash
|
||
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`](../.env.example)。
|
||
|
||
## 5. 生成自签证书（可选但常需要）
|
||
|
||
在**项目根目录**执行：
|
||
|
||
```bash
|
||
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. 启动服务
|
||
|
||
**开发 / 前台运行：**
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
python main.py
|
||
```
|
||
|
||
或使用脚本（会读 `.env` 中的 `HTTP_HOST`、`HTTP_PORT`）：
|
||
|
||
```bash
|
||
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. 验证
|
||
|
||
```bash
|
||
curl -s "http://127.0.0.1:${HTTP_PORT:-8080}/health" | head
|
||
```
|
||
|
||
或用仓库内脚本（需根据实际 URL 调整）：
|
||
|
||
```bash
|
||
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](development-guide.md)。
|