从零打造云端AI视频生成服务：基于CogVideoX和MCP协议的完整实践

前言

随着AIGC技术的快速发展，AI视频生成已经从实验室走向实际应用。本文将详细介绍如何构建一个生产级的云端AI视频生成服务，实现从文本/图片到视频的自动化生成，并通过MCP协议与本地客户端无缝集成。

项目亮点：

• 基于开源最强视频生成模型 CogVideoX-5B
• 支持文生视频（Text-to-Video）和图生视频（Image-to-Video）
• 完整的异步任务队列系统
• GPU显存深度优化（支持24GB显卡）
• MCP协议集成，可被Cherry Studio等客户端调用
• 生产级部署方案（systemd + Nginx + HTTPS）

技术栈：

• AI框架：PyTorch + Diffusers + Transformers
• Web框架：FastAPI + Uvicorn
• 协议：MCP (Model Context Protocol)
• GPU：NVIDIA RTX 4090 (24GB)
• 部署：Ubuntu 22.04 + CUDA 12.1

---

一、项目架构设计

1.1 整体架构

项目采用云端GPU服务 + 本地客户端调用的架构模式：

┌─────────────────────┐
│  本地 Cherry Studio │
│   (MCP 客户端)      │
└──────────┬──────────┘
           │ SSH/HTTP
           │ MCP Protocol
           ↓
┌─────────────────────────────────────┐
│     云端服务器 (Ubuntu + 4090)      │
│  ┌───────────────────────────────┐  │
│  │   FastAPI + Uvicorn           │  │
│  │   (0.0.0.0:8000)              │  │
│  └───────────┬───────────────────┘  │
│              │                       │
│  ┌───────────▼───────────────────┐  │
│  │   MCP Server                  │  │
│  │   - 工具注册与路由            │  │
│  │   - DeepSeek提示词优化        │  │
│  └───────────┬───────────────────┘  │
│              │                       │
│  ┌───────────▼───────────────────┐  │
│  │   Task Manager                │  │
│  │   - 异步队列(asyncio.Queue)   │  │
│  │   - 并发控制(max=1)           │  │
│  │   - 任务状态跟踪              │  │
│  └───────────┬───────────────────┘  │
│              │                       │
│  ┌───────────▼───────────────────┐  │
│  │   Video Generator             │  │
│  │   - CogVideoX T2V/I2V         │  │
│  │   - GPU显存优化               │  │
│  └───────────┬───────────────────┘  │
│              │                       │
│  ┌───────────▼───────────────────┐  │
│  │   NVIDIA 4090 GPU             │  │
│  │   - CUDA 12.1+                │  │
│  │   - 24GB VRAM                 │  │
│  └───────────────────────────────┘  │
│              │                       │
│              ↓                       │
│        outputs/*.mp4                │
└─────────────────────────────────────┘

1.2 核心模块

项目采用清晰的模块化设计：

story2film/
├── app/
│   ├── models.py              # Pydantic数据模型
│   ├── mcp_server.py          # MCP协议服务器
│   ├── video_generator.py     # CogVideoX视频生成器
│   ├── task_manager.py        # 异步任务队列
│   └── security.py            # API认证
├── main.py                    # FastAPI应用入口
├── config.py                  # 配置管理
└── outputs/                   # 视频输出目录

---

二、核心技术实现

2.1 视频生成器 - 驾驭CogVideoX

CogVideoX是清华大学开源的视频生成模型，支持文本和图片输入。核心挑战是如何在24GB显卡上稳定运行5B参数模型。

2.1.1 GPU显存优化

我们实现了多种显存优化技术：

class CogVideoXGenerator:
    def __init__(self, use_quantization=False):
        self.t2v_pipe = None  # 文生视频模型
        self.i2v_pipe = None  # 图生视频模型
        self.device = "cuda" if torch.cuda.is_available() else "cpu"
        self._current_model = None

    def _apply_optimizations(self, pipe):
        """应用显存优化策略"""
        # 1. VAE Tiling - 分块处理，减少显存峰值
        if hasattr(pipe.vae, 'enable_tiling'):
            pipe.vae.enable_tiling()
            logger.info("已启用 VAE Tiling")

        # 2. VAE Slicing - 切片处理，进一步优化
        if hasattr(pipe.vae, 'enable_slicing'):
            pipe.vae.enable_slicing()
            logger.info("已启用 VAE Slicing")

        # 3. Sequential CPU Offload - 模型分层卸载到CPU
        if hasattr(pipe, 'enable_sequential_cpu_offload'):
            pipe.enable_sequential_cpu_offload(gpu_id=0)
            logger.info("已启用 Sequential CPU Offload")

        return pipe

    def _optimize_memory(self):
        """主动清理显存"""
        if torch.cuda.is_available():
            torch.cuda.empty_cache()
            gc.collect()

优化效果对比：

优化策略	显存占用	减少幅度
无优化	~16 GB	-
VAE Tiling/Slicing	~12 GB	↓25%
+ CPU Offload	~8 GB	↓50%

2.1.2 图片预处理技术

图生视频对输入图片有严格要求，必须精确处理：

def _resize_image_to_requirements(self, image: Image.Image) -> Image.Image:
    """
    根据CogVideoX官方要求调整图片尺寸：
    - 最小边：768px
    - 最大边：768-1360px之间
    - 必须是16的倍数
    """
    image = image.convert("RGB")
    width, height = image.size

    # 计算缩放比例
    min_side = min(width, height)
    target_min = 768
    scale = target_min / min_side

    new_width = int(width * scale)
    new_height = int(height * scale)
    max_side = max(new_width, new_height)

    # 限制最大边并对齐到16
    new_max = min(max_side, 1360)
    new_max = (new_max // 16) * 16

    # 重新计算尺寸
    if width > height:
        new_width = new_max
        new_height = int((new_max / width) * height)
    else:
        new_height = new_max
        new_width = int((new_max / height) * width)

    # 确保都是16的倍数
    new_width = (new_width // 16) * 16
    new_height = (new_height // 16) * 16

    logger.info(f"图片尺寸调整: {width}x{height} -> {new_width}x{new_height}")
    return image.resize((new_width, new_height), Image.LANCZOS)

关键点：

• CogVideoX要求帧数必须是8N+1格式（13, 17, 25, 33, 41, 49）
• 图片尺寸必须是16的倍数（CUDA对齐要求）
• 使用LANCZOS算法保证缩放质量

2.1.3 视频生成主流程

async def generate_text_to_video(
    self,
    prompt: str,
    num_frames: int = 49,
    num_inference_steps: int = 50,
    guidance_scale: float = 6.0,
    seed: Optional[int] = None
) -> str:
    """文本生成视频"""
    # 1. 验证帧数格式
    if (num_frames - 1) % 8 != 0 or num_frames > 49:
        raise ValueError(f"帧数必须为8N+1格式且<=49，当前: {num_frames}")

    # 2. 加载模型（首次调用）
    self._ensure_t2v_pipe_loaded()

    # 3. 设置随机种子
    if seed is not None:
        generator = torch.Generator(device=self.device).manual_seed(seed)
    else:
        generator = None

    # 4. 执行推理
    with torch.inference_mode():  # 禁用梯度计算
        output = self.t2v_pipe(
            prompt=prompt,
            num_frames=num_frames,
            num_inference_steps=num_inference_steps,
            guidance_scale=guidance_scale,
            generator=generator
        )

    # 5. 导出视频
    video_path = self._export_video(output.frames[0], prompt)

    # 6. 清理显存
    self._optimize_memory()

    return video_path

2.2 异步任务队列 - 高并发管理

视频生成是耗时操作（3-5分钟），必须使用异步队列避免阻塞。

2.2.1 任务管理器设计

class TaskManager:
    def __init__(self, max_concurrent_tasks: int = 1, max_queue_size: int = 5):
        self.max_concurrent_tasks = max_concurrent_tasks  # 最大并发数
        self.max_queue_size = max_queue_size              # 队列容量
        self.current_tasks: Dict[str, asyncio.Task] = {}  # 运行中任务
        self.task_queue: asyncio.Queue = None             # 任务队列
        self.task_status: Dict[str, dict] = {}            # 任务状态
        self._processing = False

    async def initialize(self):
        """初始化任务队列和后台Worker"""
        self.task_queue = asyncio.Queue(maxsize=self.max_queue_size)
        self._processing = True
        # 启动后台处理协程
        asyncio.create_task(self._process_tasks())
        logger.info("任务管理器初始化完成")

2.2.2 任务处理流程

async def _process_tasks(self):
    """后台Worker持续处理队列"""
    while self._processing:
        try:
            # 从队列取出任务
            task_id, task_func, args = await self.task_queue.get()

            # 检查并发限制
            if len(self.current_tasks) >= self.max_concurrent_tasks:
                # 等待后重新入队
                await asyncio.sleep(1)
                await self.task_queue.put((task_id, task_func, args))
                continue

            # 执行任务
            task = asyncio.create_task(
                self._execute_task(task_id, task_func, args)
            )
            self.current_tasks[task_id] = task
            self.task_queue.task_done()

            # 智能显存清理
            if self.task_queue.qsize() == 0 and len(self.current_tasks) == 0:
                try:
                    from app.video_generator import CogVideoXGenerator
                    CogVideoXGenerator()._cleanup_memory()
                    logger.info("队列空闲，已自动清理显存")
                except Exception as e:
                    logger.warning(f"自动清理显存失败: {e}")

        except Exception as e:
            logger.error(f"任务处理出错: {e}")
            await asyncio.sleep(1)

2.2.3 任务状态跟踪

async def submit_task(self, task_func, args: dict, task_type: str) -> str:
    """提交任务到队列"""
    # 检查队列是否已满
    if self.task_queue.full():
        raise Exception("任务队列已满，请稍后再试")

    # 生成唯一任务ID
    task_id = str(uuid.uuid4())

    # 初始化任务状态
    self.task_status[task_id] = {
        "task_id": task_id,
        "type": task_type,
        "status": "pending",           # pending | processing | completed | failed
        "progress": 0.0,               # 0-100
        "created_at": datetime.now().isoformat(),
        "updated_at": datetime.now().isoformat(),
        "args": args,
        "result": None,
        "error": None
    }

    # 加入队列
    await self.task_queue.put((task_id, task_func, args))
    logger.info(f"任务 {task_id} 已提交，当前队列长度: {self.task_queue.qsize()}")

    return task_id

2.3 MCP协议集成 - 与Cherry Studio通信

MCP（Model Context Protocol）是一个允许应用调用AI工具的标准协议。

2.3.1 MCP工具注册

class MCPServer:
    def __init__(self):
        self.server = Server("cogvideox-server")
        self._register_tools()

    def _register_tools(self):
        """注册MCP工具"""
        @self.server.list_tools()
        async def list_tools():
            return [
                Tool(
                    name="generate_video_from_text",
                    description="根据文本提示词生成视频",
                    inputSchema={
                        "type": "object",
                        "properties": {
                            "prompt": {
                                "type": "string",
                                "description": "视频生成提示词"
                            },
                            "num_frames": {
                                "type": "integer",
                                "default": 49,
                                "description": "视频帧数（13/17/25/33/41/49）"
                            },
                            "num_inference_steps": {
                                "type": "integer",
                                "default": 50,
                                "description": "推理步数（20-100）"
                            },
                            "guidance_scale": {
                                "type": "number",
                                "default": 6.0,
                                "description": "引导系数（1.0-20.0）"
                            },
                            "seed": {
                                "type": "integer",
                                "description": "随机种子（可选）"
                            }
                        },
                        "required": ["prompt"]
                    }
                ),
                Tool(
                    name="generate_video_from_image",
                    description="根据图片和提示词生成视频",
                    inputSchema={...}
                ),
                Tool(
                    name="polish_prompt",
                    description="使用DeepSeek优化提示词",
                    inputSchema={...}
                )
            ]

2.3.2 DeepSeek提示词优化

为了提升视频质量，我们集成了DeepSeek API来优化用户输入的提示词：

async def _polish_prompt_with_deepseek(
    self,
    prompt: str,
    style: str,
    language: str
) -> str:
    """使用DeepSeek V3优化提示词"""
    system_prompts = {
        "zh": f"你是一个专业的视频生成提示词优化专家。请将用户的简短描述扩展为详细的、适合{style}风格的视频生成提示词。要求：\n1) 包含具体的场景描述\n2) 描述动作和运动\n3) 包含光线、色彩等视觉元素\n4) 保持在200字以内\n5) 只返回优化后的提示词，不要其他说明",
        "en": f"You are a professional video generation prompt engineer. Expand the user's brief description into a detailed prompt suitable for {style} style video generation. Requirements:\n1) Include specific scene descriptions\n2) Describe actions and movements\n3) Include lighting, color and other visual elements\n4) Keep within 200 words\n5) Return only the optimized prompt"
    }

    response = requests.post(
        config.Config.DEEPSEEK_API_URL,
        headers={
            "Authorization": f"Bearer {config.Config.DEEPSEEK_API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "model": config.Config.DEEPSEEK_MODEL,
            "messages": [
                {"role": "system", "content": system_prompts.get(language, system_prompts["zh"])},
                {"role": "user", "content": prompt}
            ],
            "temperature": 0.7,
            "max_tokens": 500
        },
        timeout=30
    )

    polished = response.json()["choices"][0]["message"]["content"].strip()
    logger.info(f"原始提示词: {prompt}")
    logger.info(f"优化后提示词: {polished}")

    return polished

优化效果示例：

原始：一只猫在花园里玩耍

优化后：在阳光明媚的下午，一只橘色的小猫在满是鲜花的花园中欢快地奔跑。镜头跟随它跳跃过石板路，追逐飞舞的蝴蝶。暖色调的光线透过树叶洒下，营造出梦幻般的氛围。画面采用电影级构图，景深效果突出主体。

2.4 安全性设计

2.4.1 API Key认证

import secrets
from fastapi import HTTPException, Header, Depends

def verify_api_key(x_api_key: Optional[str] = Header(None)) -> str:
    """验证API密钥（防时序攻击）"""
    if not x_api_key:
        raise HTTPException(status_code=401, detail="缺少API密钥")

    # 使用 secrets.compare_digest 防止时序攻击
    if not secrets.compare_digest(x_api_key, config.Config.API_SECRET_KEY):
        raise HTTPException(status_code=401, detail="无效的API密钥")

    return x_api_key

# 在路由中使用
api_key_dependency = Depends(verify_api_key)

@app.post("/api/generate/text-to-video")
async def generate_video(
    request: VideoGenerationRequest,
    api_key: str = api_key_dependency
):
    # 处理请求...

为什么使用secrets.compare_digest？

普通的字符串比较==会在第一个不匹配的字符处提前返回，攻击者可以通过测量响应时间来逐字符猜测密钥。compare_digest保证比较时间固定，无论密钥是否匹配。

2.4.2 路径遍历防护

@app.get("/api/download/{filename}")
async def download_video(filename: str, api_key: str = api_key_dependency):
    """下载生成的视频文件"""
    # 安全检查：防止路径遍历攻击
    if '..' in filename or filename.startswith('/'):
        raise HTTPException(status_code=400, detail="无效的文件名")

    file_path = os.path.join("outputs", filename)

    if not os.path.exists(file_path):
        raise HTTPException(status_code=404, detail="文件不存在")

    return FileResponse(
        path=file_path,
        media_type="video/mp4",
        filename=filename
    )

2.4.3 CORS配置

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=config.Config.ALLOWED_ORIGINS,  # 限制允许的域名
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["*"],
)

---

三、完整业务流程

3.1 文生视频流程

1. Cherry Studio 发送 MCP 请求
   ↓
2. FastAPI 接收 POST /api/generate/text-to-video
   ↓
3. API Key 验证 (security.py)
   ↓
4. Pydantic 数据验证 (models.py)
   ↓
5. MCP Server 处理请求 (mcp_server.py)
   ├── 可选：调用 DeepSeek 优化提示词
   └── 提交任务到队列
   ↓
6. Task Manager 接收任务 (task_manager.py)
   ├── 生成唯一 task_id
   ├── 检查队列容量
   ├── 初始化任务状态（pending）
   └── 加入 asyncio.Queue
   ↓
7. 后台 Worker 处理任务
   ├── 从队列取出任务
   ├── 检查并发限制
   ├── 更新状态为 processing
   └── 调用 Video Generator
   ↓
8. Video Generator 生成视频 (video_generator.py)
   ├── 加载 CogVideoX-T2V 模型（首次）
   ├── 应用显存优化
   ├── 设置随机种子
   ├── 执行推理（3-5分钟）
   ├── 导出 MP4 文件
   └── 清理显存
   ↓
9. 更新任务状态为 completed
   ↓
10. 客户端轮询 GET /api/task/{task_id}
   ↓
11. 任务完成后下载 GET /api/download/{filename}

3.2 图生视频流程（额外步骤）

1. 接收图片（image_path 或 image_base64）
   ↓
2. 图片预处理
   ├── Base64 解码（如果需要）
   ├── 转换为 RGB 格式
   ├── 调整尺寸（768-1360px，16倍数）
   └── 保存临时文件
   ↓
3. 加载 CogVideoX-I2V 模型
   ↓
4. 生成视频（使用 image 参数）
   ↓
5. 后续流程同文生视频

---

四、部署实战

4.1 系统要求

硬件：

• GPU：NVIDIA RTX 4090（24GB VRAM）
• CPU：8核心以上
• 内存：32GB RAM
• 存储：100GB 可用空间（包含模型缓存）

软件：

• 操作系统：Ubuntu 20.04/22.04
• Python：3.10+
• CUDA：12.1+
• FFmpeg：4.4+

4.2 快速部署

Step 1: 环境准备

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装基础依赖
sudo apt install -y git wget curl build-essential ffmpeg

# 安装 CUDA（如果未安装）
wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.run

# 验证 CUDA
nvidia-smi

Step 2: 克隆项目

git clone https://github.com/your-repo/story2film.git
cd story2film

Step 3: 创建虚拟环境

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装 PyTorch（CUDA 12.1）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 安装项目依赖
pip install -r requirements.txt

Step 4: 配置环境变量

# 复制配置模板
cp .env.example .env

# 编辑配置
nano .env

.env 配置示例：

# DeepSeek API 配置
DEEPSEEK_API_URL=https://api.deepseek.com/v1/chat/completions
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxx
DEEPSEEK_MODEL=deepseek-chat

# 服务器配置
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

# 安全配置（生成强密钥）
API_SECRET_KEY=your_generated_secure_key_here
ALLOWED_ORIGINS=http://localhost:3000,https://your-domain.com

# 模型配置
COGVIDEOX_T2V_MODEL=THUDM/CogVideoX1.5-5B
COGVIDEOX_I2V_MODEL=THUDM/CogVideoX-5b-I2V

# 性能配置
MAX_CONCURRENT_TASKS=1
TASK_TIMEOUT=1800
MAX_QUEUE_SIZE=5

生成安全密钥：

python -c "import secrets; print(secrets.token_urlsafe(32))"

Step 5: 首次运行（下载模型）

# 前台运行（用于测试）
python -m app.main

首次运行会自动从 Hugging Face 下载模型（约10-20GB），需要等待一段时间。

Step 6: systemd 服务配置（生产环境）

创建 /etc/systemd/system/story2film.service：

[Unit]
Description=Story2Film CogVideoX MCP Server
After=network.target

[Service]
Type=simple
User=your_username
Group=your_username
WorkingDirectory=/path/to/story2film
Environment="PATH=/path/to/story2film/venv/bin"
ExecStart=/path/to/story2film/venv/bin/python -m app.main
Restart=on-failure
RestartSec=10s

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl daemon-reload
sudo systemctl enable story2film
sudo systemctl start story2film

# 查看状态
sudo systemctl status story2film

# 查看日志
sudo journalctl -u story2film -f

Step 7: Nginx 反向代理（可选）

创建 /etc/nginx/sites-available/story2film：

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # 支持大文件上传
        client_max_body_size 100M;

        # 长连接超时（视频生成时间长）
        proxy_read_timeout 1800s;
        proxy_connect_timeout 1800s;
        proxy_send_timeout 1800s;
    }
}

启用配置：

sudo ln -s /etc/nginx/sites-available/story2film /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Step 8: 配置 HTTPS（Let's Encrypt）

# 安装 Certbot
sudo apt install -y certbot python3-certbot-nginx

# 获取证书
sudo certbot --nginx -d your-domain.com

# 自动续期
sudo certbot renew --dry-run

4.3 Cherry Studio 客户端配置

方式1：SSH 方式（推荐）

编辑 Cherry Studio 的 MCP 配置文件：

{
  "mcpServers": {
    "story2film": {
      "command": "ssh",
      "args": [
        "-T",
        "user@your-server-ip",
        "cd /path/to/story2film && source venv/bin/activate && python -m app.mcp_server"
      ],
      "transport": "stdio"
    }
  }
}

方式2：HTTP API 方式

{
  "mcpServers": {
    "story2film": {
      "url": "https://your-domain.com/api/mcp",
      "apiKey": "your_api_secret_key"
    }
  }
}

---

五、性能优化与监控

5.1 GPU 显存使用分析

在 NVIDIA RTX 4090 (24GB) 上的实际测试：

操作	显存占用	备注
模型加载	~8-10 GB	BFloat16精度
视频生成（49帧）	~12-16 GB	峰值
VAE Tiling 优化后	~8-12 GB	↓30%
CPU Offload 优化后	~6-10 GB	↓50%

监控显存命令：

# 实时监控
watch -n 1 nvidia-smi

# 查看进程显存
nvidia-smi --query-compute-apps=pid,name,used_memory --format=csv

5.2 生成速度估算

配置	生成时间	适用场景
13帧, 20步	~30秒	快速预览
25帧, 30步	~1-2分钟	平衡质量
49帧, 50步	~3-5分钟	高质量输出

影响因素：

1. num_frames：帧数越多越慢（线性增长）
2. num_inference_steps：步数越多质量越好，但时间增加
3. guidance_scale：对速度影响较小

5.3 性能优化建议

1. 模型缓存路径

# 将模型缓存移到大容量硬盘
export HF_HOME=/data/huggingface_cache

# 添加到 .bashrc 或 systemd 服务中

2. 并发控制调优

# config.py
MAX_CONCURRENT_TASKS = 1  # 保守设置（推荐）
# MAX_CONCURRENT_TASKS = 2  # 激进设置（需显存充足）

3. 任务超时调整

# 根据实际生成时间调整
TASK_TIMEOUT = 1800  # 30分钟（默认）
# TASK_TIMEOUT = 3600  # 1小时（长视频）

4. 使用 GPU 监控

安装 gpustat：

pip install gpustat

# 实时监控
gpustat -i 1

---

六、实战经验与踩坑记录

6.1 显存不足（OOM）问题

问题：

生成49帧视频时显存爆满，进程被杀。

解决方案：

1. 启用所有优化选项（VAE Tiling/Slicing + CPU Offload）
2. 降低帧数到25-33帧
3. 确保只有一个任务在运行（MAX_CONCURRENT_TASKS=1）
4. 使用 torch.inference_mode() 而非 torch.no_grad()

6.2 图片尺寸导致生成失败

问题：

图生视频时报错：RuntimeError: sizes must be divisible by 16

原因：

CogVideoX 要求图片尺寸必须是16的倍数（CUDA 对齐要求）。

解决方案：

实现严格的图片预处理：

# 确保尺寸对齐
new_width = (new_width // 16) * 16
new_height = (new_height // 16) * 16

6.3 任务队列卡死

问题：

提交任务后一直显示 pending，从未执行。

原因：

后台 Worker 协程未正确启动。

解决方案：

在 FastAPI 生命周期中初始化任务管理器：

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 启动时初始化
    await task_manager.initialize()
    yield
    # 关闭时清理
    await task_manager.shutdown()

app = FastAPI(lifespan=lifespan)

6.4 模型下载速度慢

问题：

首次运行时下载模型速度极慢（国内网络问题）。

解决方案：

使用 Hugging Face 镜像：

# 方法1：环境变量
export HF_ENDPOINT=https://hf-mirror.com

# 方法2：手动下载后指定本地路径
git lfs clone https://hf-mirror.com/THUDM/CogVideoX1.5-5B

# 修改 config.py
COGVIDEOX_T2V_MODEL = "/path/to/local/CogVideoX1.5-5B"

6.5 Cherry Studio 连接失败

问题：

Cherry Studio 无法连接到 MCP 服务器。

排查步骤：

1. 检查服务器防火墙：sudo ufw allow 8000/tcp
2. 验证服务运行：curl http://localhost:8000/health
3. 检查 SSH 密钥配置（SSH 方式）
4. 查看日志：sudo journalctl -u story2film -f

---

七、未来扩展计划

7.1 字幕生成（计划中）

技术方案：

• 使用 Whisper 进行语音识别
• 支持 SRT、ASS、VTT 格式
• FFmpeg 嵌入字幕

实现框架：

class SubtitleGenerator:
    def __init__(self):
        self.model = whisper.load_model("medium")

    async def generate_subtitle(self, video_path: str, language: str = "zh"):
        # 提取音频
        audio = self._extract_audio(video_path)

        # 语音识别
        result = self.model.transcribe(audio, language=language)

        # 生成 SRT
        srt_path = self._generate_srt(result["segments"])

        # 嵌入字幕
        final_video = self._add_subtitle_to_video(video_path, srt_path)

        return final_video

7.2 配音生成（计划中）

技术方案：

• Edge TTS 或 Coqui TTS
• 支持多音色、情感控制
• 自动音视频同步

实现框架：

class VoiceoverGenerator:
    async def generate_voiceover(
        self,
        text: str,
        voice: str = "zh-CN-XiaoxiaoNeural",
        speed: float = 1.0
    ) -> str:
        # 文本转语音
        audio_path = await self._text_to_speech(text, voice, speed)

        return audio_path

    async def merge_with_video(
        self,
        video_path: str,
        audio_path: str
    ) -> str:
        # 使用 FFmpeg 合并
        output = self._merge_audio_video(video_path, audio_path)
        return output

7.3 完整工作流（终极目标）

一站式视频生成流程：

用户输入故事文本
  ↓
DeepSeek 优化提示词
  ↓
CogVideoX 生成视频
  ↓
TTS 生成配音
  ↓
Whisper 生成字幕
  ↓
FFmpeg 合成最终视频
  ↓
返回完整带字幕带配音的视频

API 设计：

class CompleteVideoRequest(BaseModel):
    story_text: str                          # 故事文本
    video_style: str = "cinematic"           # 视频风格
    voice: str = "zh-CN-XiaoxiaoNeural"      # 配音音色
    include_subtitle: bool = True            # 是否添加字幕
    include_voiceover: bool = True           # 是否添加配音
    num_frames: int = 49                     # 视频帧数
    seed: Optional[int] = None               # 随机种子

@app.post("/api/generate/complete-video")
async def generate_complete_video(request: CompleteVideoRequest):
    """一站式生成完整视频"""
    # 1. 优化提示词
    # 2. 生成视频
    # 3. 生成配音
    # 4. 生成字幕
    # 5. 合成最终视频
    # 6. 返回结果

---

八、总结与展望

8.1 项目亮点回顾

1. 技术先进性

   • 采用最新的 CogVideoX-5B 模型
   • 支持文生视频和图生视频双模式
   • 集成 DeepSeek V3 提示词优化

2. 工程完整性

   • 完整的异步任务队列系统
   • 生产级 API 设计（认证、CORS、错误处理）
   • 详细的部署文档和配置指南

3. 性能优化

   • GPU 显存深度优化（VAE Tiling、CPU Offload）
   • 智能内存清理机制
   • 并发控制和队列管理

4. 协议创新

   • 完整的 MCP 协议实现
   • 与 Cherry Studio 无缝集成
   • 支持 SSH 和 HTTP 双调用方式

8.2 适用场景

1. 短视频创作

   • 自媒体内容生成
   • 广告素材制作
   • 社交媒体视频

2. 教育与科研

   • AI 视频生成研究
   • 视频合成技术学习
   • 模型性能测试

3. 企业应用

   • 产品演示视频
   • 营销素材生成
   • 内部培训视频

8.3 技术启示

1. GPU 资源管理

   • 显存优化是 AI 应用的核心挑战
   • VAE Tiling/Slicing 可显著降低峰值显存
   • CPU Offload 牺牲速度换取显存空间

2. 异步架构设计

   • 耗时操作必须异步处理
   • 任务队列 + 后台 Worker 是经典模式
   • 状态管理需要细致考虑

3. 协议标准化

   • MCP 协议提供了 AI 工具的标准接口
   • 统一的工具注册和调用方式
   • 便于与各类客户端集成

8.4 开源与贡献

项目地址： GitHub - story2film

欢迎贡献：

• 报告 Bug 和提出建议
• 提交 Pull Request
• 完善文档和示例
• 分享使用经验

联系方式：

• GitHub Issues: 提交问题
• 邮箱: your-email@example.com

---

附录

A. 常用 API 端点

端点	方法	功能	认证
/	GET	欢迎信息	否
/health	GET	健康检查 + 队列状态	否
/api/generate/text-to-video	POST	文生视频	是
/api/generate/image-to-video	POST	图生视频	是
/api/polish-prompt	POST	提示词优化	是
/api/task/{task_id}	GET	查询任务状态	是
/api/download/{filename}	GET	下载视频文件	是

B. 环境变量配置参考

# DeepSeek API
DEEPSEEK_API_URL=https://api.deepseek.com/v1/chat/completions
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxx
DEEPSEEK_MODEL=deepseek-chat

# 服务器
SERVER_HOST=0.0.0.0
SERVER_PORT=8000

# 安全
API_SECRET_KEY=your_secure_key_here
ALLOWED_ORIGINS=http://localhost:3000

# 模型
COGVIDEOX_T2V_MODEL=THUDM/CogVideoX1.5-5B
COGVIDEOX_I2V_MODEL=THUDM/CogVideoX-5b-I2V

# 性能
MAX_CONCURRENT_TASKS=1
TASK_TIMEOUT=1800
MAX_QUEUE_SIZE=5

C. 故障排查清单

• 检查 CUDA 是否正常：nvidia-smi
• 验证 Python 版本：python --version (需要3.10+)
• 检查依赖安装：pip list | grep torch
• 查看服务状态：systemctl status story2film
• 检查端口占用：sudo lsof -i :8000
• 查看日志：journalctl -u story2film -f
• 测试 API：curl http://localhost:8000/health
• 检查显存：nvidia-smi
• 验证模型路径：ls ~/.cache/huggingface/hub

D. 参考资源

1. 官方文档

   • CogVideoX GitHub
   • Diffusers Documentation
   • FastAPI Documentation
   • MCP Protocol Specification

2. 相关论文

   • CogVideoX: Text-to-Video Diffusion Models
   • Latent Diffusion Models
   • Stable Video Diffusion

3. 社区资源

   • Hugging Face Forums
   • PyTorch Forums
   • CSDN AI 技术社区

---

本文完整代码已开源： GitHub - story2film

如果觉得有帮助，欢迎 Star ⭐ 和 Fork！

---

作者：[Your Name]
日期：2025年
原创文章，转载请注明出处