# shiping

**Repository Path**: wangcixuan/shiping

## Basic Information

- **Project Name**: shiping
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-03
- **Last Updated**: 2026-06-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 电商 AI 视频制作平台 · 运行说明（README）

> 竞赛交付物 #1：源代码 + 运行说明
> Python 3.12 / FastAPI · 本文档面向评委，目标是让你在本地 **零障碍部署并复现** 端到端效果。

---

## 1. 项目简介

本项目是一个面向 **非技术背景的中小电商运营** 的零门槛 Web 平台：运营只需上传 **产品图 + 一段文字**，点一次按钮，即可自动产出一条 **30 秒竖屏带货短视频**（含黄金前 3 秒钩子、AI 口播文案、运镜与卡点、可量化的爆款潜力评分）。平台 **自身不训练、不构建任何模型**，只 **编排（orchestrate）两个外部服务**：DeepSeek API 负责全部文本智能（卖点提炼 / 口播 / 提示词优化 / 诊断建议），火山引擎 Ark / Seedance 负责全部视频生成；所有凭据 **只按环境变量名（env-var NAME）引用**，绝不硬编码、绝不入库。

---

## 2. 环境要求

| 项目 | 要求 |
| --- | --- |
| Python | **3.12** |
| 操作系统 | Windows / macOS / Linux 均可 |
| ffmpeg | **无需单独安装**，依赖 `imageio-ffmpeg` 已自带打包 ffmpeg 可执行文件 |

安装依赖（建议先创建虚拟环境）：

```bash
# 1) 创建并激活虚拟环境（可选但推荐）
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS / Linux:
source .venv/bin/activate

# 2) 安装依赖
pip install -r requirements.txt
```

`requirements.txt` 仅含 7 个核心依赖：`fastapi`、`uvicorn[standard]`、`sqlalchemy`、`requests`、`imageio-ffmpeg`、`python-dotenv`、`pytest`。

---

## 3. 配置（API 凭据）

复制环境变量模板为 `.env` 并填入三个 API Key：

```bash
# macOS / Linux:
cp .env.example .env
# Windows:
copy .env.example .env
```

`.env` 需要填写的三个凭据（平台只按 **变量名** 读取，`.env` 已被 `.gitignore` 排除，不会提交）：

| 环境变量名 | 用途 |
| --- | --- |
| `DEEPSEEK_API_KEY` | DeepSeek：全部文本智能 |
| `ARK_API_KEY_SEEDANCE_20` | 火山 Ark / Seedance 2.0：图生视频、主力 / 终稿生成 |
| `ARK_API_KEY_SEEDANCE_15_PRO` | 火山 Ark / Seedance 1.5 Pro：草稿 / 文生视频 |

模板中还包含 **非机密** 的模型 id 与 API 地址（一般无需修改）：`SEEDANCE_20_MODEL_ID`、`SEEDANCE_15_PRO_MODEL_ID`、`DEEPSEEK_MODEL_ID`、`ARK_API_BASE`。

> **重要（推荐的评审方式）**：即使 **不填写任何 API Key**，平台仍可 **完全离线** 运行两个内置 demo 行业案例（确定性 mock 适配器，结果可复现）。这是评委验证「端到端可复现性」最稳妥的方式，详见第 5 节。线上 `/ready` 健康检查只会回报 **缺失凭据的变量名**，绝不暴露任何密钥值。

---

## 4. 启动

```bash
python main.py
# 等价写法：
uvicorn app.web.app:app
```

服务默认监听 `0.0.0.0:8000`。启动后在浏览器打开：

| 入口 | 地址 | 说明 |
| --- | --- | --- |
| 商户 Web UI | <http://localhost:8000/> | 运营操作主界面（上传 / 一键生成 / 预览 / 下载 / 评分报告） |
| 管理后台 Admin Console | <http://localhost:8000/admin> | 账号 / 配额 / 素材 / 产物 / 统计管理 |
| 商户 REST API | `http://localhost:8000/api/merchant` | Web UI 背后的接口（提交、状态、下载、分段编辑、评分、报告等） |

健康检查 / 就绪探针：

- `GET /health` — 存活探针，返回 `{"status":"ok"}`
- `GET /ready` — 就绪探针，返回凭据是否齐全（仅回报缺失凭据的 **变量名**，不泄露密钥）

---

## 5. 快速体验（离线可复现 demo）

平台内置两个 **保存好的行业案例**，无需任何 API Key、无需真实 ffmpeg，即可端到端跑通（输入 → 编剧链 → 分镜 → 双模型生成 → 拼接 → 音画同步 → 后期 → 评分 → 建议 → 优化闭环 → 合规终审 → 生成报告，并额外执行一次显式的分段重生成），最终产出固定规格（360×640 / 9:16 / ≤30s）的可下载视频：

- `beauty_lipstick` — 美妆（口红）
- `appliance_humidifier` — 小家电 / 家居（加湿器）

**方式一：用测试复现（最简单，推荐评委使用）**

```bash
python -m pytest tests/test_demo_cases.py -q
```

**方式二：用 demos 模块直接跑**

```bash
# 跑口红案例
python -c "from app.demos import run_demo_case; j = run_demo_case('beauty_lipstick'); print(j.final_video_path, j.overall_score.display)"

# 跑加湿器案例
python -c "from app.demos import run_demo_case; j = run_demo_case('appliance_humidifier'); print(j.final_video_path, j.overall_score.display)"
```

入口函数：`app.demos.run_demo_case(case_id)`（返回 `Generation_Job`，含 `final_video_path`、`overall_score`、`report`）。需要更详细结果（基线分 vs 最终分、重生成结果、规格校验）可用 `app.demos.demo_cases.run_demo_case_detailed`。所有外部协作方（DeepSeek / Ark / Seedance / TTS / ffmpeg）均由 `app.demos.adapters` 注入为确定性离线 mock，因此 **每次运行结果一致、可复现**。

---

## 6. 核心功能 与 6 大痛点对应

| 官方 6 大痛点 | 平台能力 | 主要实现位置 |
| --- | --- | --- |
| 零门槛操作 | 产品图 + 文字 → 一键生成，关键词 / 风格均为可选且由 AI 补全 | 输入层 `app/input/` + 商户 `Web_UI`（`app/web/ui_routes.py`、`app/web/merchant_routes.py`） |
| 模板化一键生成 | 行业模板驱动的一键流水线 | `Industry_Templates` + 一键 `Generation_Pipeline`（`app/pipeline.py`） |
| 片段级局部重生成 | 标记不满意片段 + 自然语言描述，仅重生成该片段 | `Segment_Editor`（`app/scoring/segment_editor.py`） |
| 语音卡点同步 < 0.3s | 基于 TTS 自带时间戳的语义节奏对齐 | `Audio_Sync_Engine`（`app/assembly/audio_sync_engine.py`，`SYNC_TOLERANCE_SECONDS = 0.3`） |
| 自动运镜与故事吸引力 | 导演级运镜 + 叙事框架编剧链（黄金前 1.5s 钩子） | `AI_Director`（`app/story/ai_director.py`）+ `AI_Screenwriter_Chain`（`app/story/screenwriter_chain.py`） |
| 可推广性量化评分 | 4 维度爆款潜力评分 + 诊断式改进建议 | `Quality_Scorer`（`app/scoring/quality_scorer.py`）+ `Suggestion_Engine`（`app/scoring/suggestion_engine.py`） |

---

## 7. 视频规格说明

平台产出固定规格，由 `app/constants.py` 作为唯一事实来源统一驱动：

- **分辨率**：360×640（**竖屏 9:16**）
- **帧率**：30 fps
- **结构**：5 段 × 6 秒 = **30 秒**（±1s 容差；单段重生成 6s ±0.5s）

之所以选择 **竖屏 9:16**，是为契合 **抖音 / 快手 / 视频号** 的主流竖屏带货场景。官方评分附录中提到的 640×360 **横屏** 仅作为另一种可选朝向（备选 / 未来扩展），不属于本次构建的默认输出。

---

## 8. 项目结构

```
app/
├── adapters/      外部服务适配器（DeepSeek / Ark·Seedance / TTS），平台不自建模型
├── input/         输入处理：卖点提炼、风格映射
├── story/         叙事与文案：AI 导演、编剧链、口播、分镜脚本、提示词优化
├── generation/    视频生成：模型路由、分段生成、连贯性管理
├── assembly/      合成：拼接、音画同步、后期、后期润色
├── scoring/       评分与优化：质量评分、建议、优化闭环、分段编辑器
├── cost/          成本 / 积分管理（按生成秒数计费）
├── safety/        安全网：合规终审 Compliance_Guard、Demo 兜底 Demo_Fallback_Mode
├── report/        生成报告 Generation_Report
├── web/           FastAPI 应用工厂、商户 REST API、商户与管理后台 UI、静态页
├── demos/         两个离线可复现 demo 案例（口红 / 加湿器）及其 mock 适配器
├── config.py      按环境变量名加载凭据 + 重导出格式常量
├── constants.py   固定规格与阈值（唯一事实来源）
├── pipeline.py    一键生成主流水线
├── models.py      领域数据模型
└── db.py          SQLite 持久化
```

---

## 9. 测试

```bash
python -m pytest -q
```

仓库包含约 **400+ 个测试**（当前约 431 个），覆盖输入、叙事、生成、合成、评分、优化、合规、兜底、Web API 与两个 demo 案例。

---

## 10. 一票否决项的规避

- **文字 / logo 一律由 ffmpeg 后期合成，模型从不渲染文字**：Seedance 永远不被要求渲染屏幕文字 / 字幕 / CTA / 品牌 logo，`Negative_Prompt` 明确禁止模型产出任何文字与 logo，所有文字与 logo 由 `Post_Processor` 用内嵌字体经 ffmpeg 叠加合成 —— 从结构上杜绝「文字乱码」这一典型一票否决项。
- **Compliance_Guard 终审**：交付前的最终闸门，拦截文字乱码、错误 / 变形 logo、空字幕帧、损坏的拼接等致命缺陷。
- **Demo_Fallback_Mode 兜底**：任一流水线阶段失败且无既定降级路径时，先重试可恢复阶段，再跳过优化闭环、用最后有效片段安全合成，**始终保证有可下载视频** —— 避免现场演示因报错而无法复现。