大星口播智能体 使用说明

# 大星口播智能体 口播智能体 · 完整使用说明手册

> 版本：V7 便携版 | 主界面：Studio 十步产线 | 后端端口：**8091**

---

## 一、产品简介

大星口播智能体 是一款**本地部署**的短视频口播创作工具，对标 Deepshow 十步流程，覆盖：

| 步骤 | 功能 |
|------|------|
| STEP 01 | 爆款视频下载（抖音等链接，带进度条） |
| STEP 02 | 提取口播文案（分享文案 / ASR 语音识别） |
| STEP 03 | AI 拆解爆款逻辑 |
| STEP 04 | AI 仿写文案（需云端 LLM） |
| STEP 05 | AI 法务审核 |
| STEP 06 | 声音克隆 + TTS 合成（FunSpeech） |
| STEP 07 | 口播对口型视频（GPU 口型合成） |
| STEP 08 | 字幕与标题烧录 |
| STEP 09 | 画中画素材（规划中） |
| STEP 10 | 背景音乐混合 |

**主入口**：浏览器打开 **http://localhost:8091/studio**  
**设置中心**：http://localhost:8091/settings

---

## 二、环境要求

| 项目 | 建议配置 |
|------|----------|
| 系统 | Windows 10/11 64 位 |
| 显卡 | NVIDIA GPU（如 RTX 4060 8GB），用于口型合成 / 配音合成 |
| 内存 | 16GB 及以上 |
| 磁盘 | 至少 20GB 可用（模型 + Docker 镜像） |
| 网络 | 首次安装需下载 Python 依赖、模型；文案 AI 需访问火山方舟等云端 API |
| Docker | 音色克隆 / ASR 依赖 **FunSpeech** 容器（端口 **8000**） |

---

## 三、安装与启动

### 3.1 首次安装（推荐）

1. 解压便携包到任意目录（路径尽量不要含特殊字符）。
2. 双击 **`setup-and-run.bat`**，按提示完成：
   - Python 便携环境
   - 依赖与口型模型
   - FFmpeg（自动下载或从兄弟目录复制）
   - Docker + FunSpeech 镜像（若本机已装 Docker）
   - 启动后端并打开 Studio
3. 安装过程约 10～30 分钟（视网速而定）。

### 3.2 日常启动

双击 **`start.bat`**：

- 自动释放 **8091** 端口
- 启动后端
- 打开 **http://localhost:8091/studio**

### 3.3 仅补模型

若提示缺少口型模型权重，可运行 **`download-models.bat`**。

### 3.4 运行自测

先 **`start.bat`** 启动后端，再双击 **`run-all-tests.bat`**（或 `run-self-test.bat` 仅离线+API 快测）。

### 3.5 单根目录：model / runtime / 数据

| 目录 | 用途 |
|------|------|
| **`model/`** | 配音、转写等大模型权重 |
| **`runtime/`** | SuperIP 口型 Runtime 包（adapters、packages、core），**不含**大模型 |
| **`data/runtime-data/`** | Runtime 任务与口型中间数据 |

**勿再**在设置或 `config.yaml` 中填写外部盘符的 runtime 根路径；推荐 `runtime.package.root: ./runtime`。若旧机有 `D:\superip-agent-runtime\runtime`，可运行项目根 **`link-runtime-into-project.bat`** 用目录联接挂到 `runtime/`（不复制大文件）。详见 **`docs/项目单根目录布局.md`**。

### 3.6 换机 / 自定义安装路径（客户部署）

软件可解压到**任意文件夹**（如 `E:\大星口播智能体`），不必与开发机路径一致。

| 要点 | 说明 |
|------|------|
| 路径写法 | `backend/config.yaml` 的 `paths` 只用 `./uploads`、`./data/agents` 等**相对路径**，不要写 `D:\...` 绝对路径 |
| 数据迁移 | 复制整个 `uploads`、`outputs`、`data` 到新安装根目录即可 |
| 浏览器访问 | 地址端口与 `server.port`（默认 **8091**）一致 |
| CORS | 局域网或多地址访问时，须在配置中写明实际 `http://IP:端口`，不要用 `*` |

**详细步骤（CORS、环境变量、检查清单）** → **[docs/DEPLOY-config.md](docs/DEPLOY-config.md)**

---

## 四、必做配置（文案 AI · 豆包/火山方舟）

本版本使用**火山方舟 OpenAI 兼容接口**，需两样东西（不是同一个）：

| 配置项 | 从哪里获取 | 示例 |
|--------|------------|------|
| **API Key** | [API Key 管理](https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey) | 一串 UUID 格式 Key |
| **推理接入点 ID** | [在线推理 → 推理接入点](https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint) | **`ep-20250412xxxxx`** |

**重要**：「模型」一栏必须填 **`ep-` 开头的接入点 ID**，不能填 `doubao-lite-32k-240828`（多数账号会 404）。

### 获取 ep- 接入点 ID（首次）

1. 打开 [模型广场](https://console.volcengine.com/ark/region:ark+cn-beijing/model)，开通要用的豆包模型（如 Doubao-lite / Seed 等）。  
2. 打开 [推理接入点](https://console.volcengine.com/ark/region:ark+cn-beijing/endpoint) → **创建推理接入点** → 选择已开通模型 → 确认接入。  
3. 在列表中点进该接入点，复制 **接入点 ID**（格式 `ep-xxxxxxxx-xxxxx`）。  

### 写入本工具

1. http://localhost:8091/settings → **基础配置**  
2. 服务商：**豆包（火山方舟）**  
3. **API Key**：粘贴方舟 Key（与资源 ID `apikey-xxx` 不同，用 Key 管理页那一串 UUID）  
4. **推理接入点 ID**：粘贴 `ep-...`  
5. **保存** → **测试连接** → Studio 顶栏「文案AI」变绿  

也可直接编辑 `backend/config.yaml` 的 `llm.model` 为 `ep-xxx` 后重启后端。

其他可选服务商（同一 OpenAI 兼容接口）：

| 服务商 | api_base 示例 | model 示例 |
|--------|---------------|------------|
| DeepSeek | https://api.deepseek.com | deepseek-chat |
| 通义千问 | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen-turbo |

配置写入 `backend/config.yaml`，可手动编辑后重启后端。

---

## 五、FunSpeech（音色克隆 / ASR）

### 5.1 检查状态

Studio 顶栏 **FunSpeech** 为绿色表示容器正常。

命令行检查：

```cmd
docker ps --filter name=cosyvoice
curl http://localhost:8000/stream/v1/tts/health
```

### 5.2 手动启动容器

若未运行，在项目根目录执行（路径按你本机修改）：

```cmd
docker start cosyvoice
```

首次需 `setup-and-run.bat` 拉取镜像，或：

```cmd
docker run -d --name cosyvoice --gpus all -p 8000:8000 -e TTS_MODEL_MODE=clone ^
  --memory=10g --memory-swap=12g --shm-size=2g ^
  -v "%CD%\backend\outputs:/app/outputs" ^
  -v "%CD%\backend\voices:/app/voices" ^
  -v "%CD%\backend\modelscope_cache:/root/.cache/modelscope" ^
  --restart unless-stopped docker.cnb.cool/nexa/funspeech:gpu-latest
```

**注意**：`backend\voices` 需挂载为本项目目录，否则音色列表为空。

### 5.3 注册音色

**方式 A — 设置中心**  
设置 → 声音克隆管理 → 上传 3～15 秒清晰人声 + 参考文字 → 注册音色  

**方式 B — Studio 右侧资源库**  
点击「+新建」音色智能体，上传参考音频  

合成口播：STEP 06 选择音色 → 填写文案 → 合成。

---

## 六、Studio 十步操作指南

### STEP 01 — 爆款视频下载

- 粘贴抖音分享口令或链接（支持 v.douyin.com 短链）。
- 点击下载，界面显示**进度条与阶段**（解析 → 下载 → 完成）。
- 也可 **上传本地视频** 作为素材源。

### STEP 02 — 提取爆款文案

- **自动**：对已下载视频做 ASR（需 FunSpeech + ffmpeg）。
- **链接文案**：从分享文本提取简介（无需下载成功）。
- **手动**：在文本框直接输入口播稿。

### STEP 03 — AI 拆解爆款逻辑

- 需已配置 **豆包 API Key**。
- 输出：钩子类型、段落结构、仿写公式等。

### STEP 04 — AI 仿写文案

- 填写 **产品介绍**（你的商品/服务）。
- 选择风格（爆款 / 专业等），基于 STEP 03 结构生成新稿。

### STEP 05 — AI 法务审核

- 检测敏感与违规表述，可填**自定义违禁规则**。
- 通过后再进入配音环节。

### STEP 06 — 声音克隆

- 选择已注册音色，或现场克隆。
- 合成 MP3 保存到 `outputs/tts/` 对应子目录，可在右侧预览播放。

### STEP 07 — 口播视频生成

- 在资源库选择 **数字人**（需先上传正面说话视频）。
- 使用 STEP 06 音频做 **GPU 口型** 对口型（耗时与显卡有关）。

### STEP 08 — 字幕与标题

- 需 **ffmpeg** 在 PATH 中。
- 填写标题、字幕内容，烧录到视频。

### STEP 09 — 画中画

- 当前为规划能力，可先跳过。

### STEP 10 — 背景音乐

- 在设置中心上传 BGM，在此选择并混合成片。

---

## 七、设置中心说明

| 菜单 | 作用 |
|------|------|
| 声音克隆管理 | 注册/查看音色，FunSpeech 对接 |
| 场景视频管理 | 上传场景片段、对口型任务 |
| 素材包管理 | B-roll 素材（STEP 09 预留） |
| 背景音乐管理 | BGM 库 |
| 基础配置 | LLM、抖音 Cookie（可选）等 |

**安装路径 / CORS / 端口**：不在设置页修改时，见 **[docs/DEPLOY-config.md](docs/DEPLOY-config.md)**（`paths`、`cors_origins`、`PORT`、`CORS_ORIGINS`）。

**抖音 Cookie（可选）**：在 `backend/config.yaml` 的 `douyin.cookie` 填写，或使用浏览器 Cookie 导出，可提升下载成功率。不填时走公开 Hybrid API，可能限流。

---

## 八、目录结构（简要）

```
{项目根}/                    # 解压后的文件夹，可任意盘符
├── start.bat
├── setup-and-run.bat
├── studio.html / settings.html
├── python/                  # 便携 Python
├── ffmpeg/                  # 可选本地 ffmpeg
├── model/                   # 大模型权重
├── runtime/                 # Native 口型/TTS Runtime 包（若已内置）
├── uploads/                 # 用户上传
├── outputs/                 # 成片、配音、口型结果
├── data/
│   ├── agents/              # 音色库 voices/、数字人 avatars/
│   └── runtime-data/        # Runtime 工作数据
├── logs/                    # 日志
└── backend/
    ├── app.py
    └── config.yaml          # 主配置（路径均相对项目根）
```

路径含义与换机说明见 **[docs/DEPLOY-config.md](docs/DEPLOY-config.md)**。

---

## 九、服务端口与健康检查

| 服务 | 地址 | 说明 |
|------|------|------|
| Studio | http://localhost:8091/studio | 主界面 |
| API 文档 | http://localhost:8091/docs | Swagger |
| 健康检查 | http://localhost:8091/api/health | JSON 各组件状态 |
| FunSpeech | http://localhost:8000 | TTS / ASR |

```cmd
:: 查看后端日志
type backend\logs\app.log

:: FunSpeech 日志
docker logs cosyvoice --tail 80

:: 重启 FunSpeech
docker restart cosyvoice
```

---

## 十、常见问题

### 1. 网页打不开 / 一直转圈

- 确认已运行 `start.bat`，窗口无报错。
- 8091 被占用时脚本会尝试结束旧进程；仍失败则任务管理器结束残留 `python.exe` 后重试。

### 2. 批处理报错 `'EnableDelayedExpansion'`、`'eoForge'`、`此时不应有 .Length`

- **原因**：`.bat` 被保存成 Unix 换行（仅 LF），CMD 无法正确解析。
- **处理**：双击 **`fix-bat-crlf.bat`**，然后重新运行 **`setup-and-run.bat`**。
- 新版 `setup-and-run.bat` 启动时会自动尝试修复所有 `.bat` 的 CRLF。
- 也可用 **`validate-setup.bat`** 快速检查 Python / FFmpeg / 后端是否正常。

### 3. 批处理报错 `'AI'`、`'tps:'`、找不到标签

- 请使用最新版 `start.bat` / `setup-and-run.bat`（已修复 CMD 对 `https://` 的误解析）。

### 4. 文案改写 / 拆解失败

- 设置中心配置豆包 API Key 并「测试连接」。
- 顶栏「文案AI」应为已配置状态。

### 5. FunSpeech 灰色 / ASR 失败

- 启动 Docker Desktop，执行 `docker start cosyvoice`。
- 首次启动容器需 2～5 分钟加载模型。

### 6. 抖音下载失败

- 尝试配置 Cookie；或改用手动文案 + 本地上传视频。
- 网络环境无法访问抖音时，仅能用分享文本中的简介。

### 7. 口型同步很慢或 OOM

- 在 `config.yaml` 的口型相关段调低 `batch_size`、`resize_factor`。
- 关闭其他占 GPU 程序。

### 8. `/classic` 旧书签

- 自动跳转到 `/studio`，无需经典版页面。

### 9. 换安装目录后「一键克隆」提示找不到参考音频

- 旧配置里若残留 `D:\某盘\...\voice_xxx.mp3` 会失效；请把 `data/agents/voices/` 复制到新安装目录，或在 Studio 重新上传音色。
- 详见 **[docs/DEPLOY-config.md](docs/DEPLOY-config.md)** 常见问题。

### 10. 页面能开但接口全部失败（CORS）

- 浏览器地址（含 `http://` 与端口）须写入 `config.yaml` 的 `cors_origins`，或启动前设置 `CORS_ORIGINS`。
- 详见 **[docs/DEPLOY-config.md](docs/DEPLOY-config.md)**。

---

## 十一

…完整版请通过飞书文档同步或联系客服获取。