AI Story 核心架构文档

AI Story 核心架构文档

仓库: github.com/xhongc/ai_s… 项目定位: AI 驱动的故事视频自动化生成平台 —— 输入一个主题，自动完成「文案 → 分镜 → 文生图 → 运镜 → 图生视频」全流程产出。

---

1. 项目一览

维度	说明
后端	Django 3.2.15 + DRF + Celery + Redis
前端	Vue 2.7.14 + Vuex + Tailwind CSS + daisyUI
运行方式	ASGI（推荐，Daphne，支持 SSE 流式输出）/ 也可 WSGI
数据库	SQLite（开发）/ PostgreSQL（生产）
任务队列	Celery + Redis（多队列：llm、image、video）
实时通信	Redis Pub/Sub + SSE，Worker 把进度发布到 Redis，前端订阅渲染
容器化	Docker / docker-compose（backend、celery、celery-beat、frontend、redis、db）
闭源	backend/apps/agent 与 backend/apps/mcp 在开源仓中只保留 .so，源码需放到 PRIVATE_BACKEND_APPS_ROOT 指向的私有仓库

---

2. 端到端工作流

系统的核心业务能力是一条 责任链 Pipeline，每一阶段对应一个 StageProcessor：

原始主题 (Project.original_topic)
   │
   ▼
┌──────────────────┐
│ rewrite          │  剧本精修 / 文案改写  (LLM)
├──────────────────┤
│ asset_extraction │  资产抽取 (人/物/场景结构化)  (LLM)
├──────────────────┤
│ storyboard       │  分镜生成 (拆句 + 画面 prompt)  (LLM)
├──────────────────┤
│ image_generation │  文生图 (每个分镜一张)  (Text2Image)
├──────────────────┤
│ multi_grid_image │  多宫格大图生成 (可选)  (Text2Image)
├──────────────────┤
│ image_edit       │  图片编辑 / 高清还原 (可选)  (ImageEdit)
├──────────────────┤
│ camera_movement  │  运镜规划 (每个分镜一段运镜文本)  (LLM)
├──────────────────┤
│ video_generation │  图生视频 (图 + 运镜 → 5s 视频片段)  (Image2Video)
└──────────────────┘
   │
   ▼
合成 / 字幕 / 剪映草稿导出

阶段定义来自 backend/apps/projects/models.py（ProjectStage.STAGE_TYPES）和 backend/apps/prompts/models.py（PromptTemplate.STAGE_TYPES），两侧保持一致。

每个阶段在数据库里都有一行 ProjectStage，状态在 pending → processing → completed / failed / skipped 之间流转，并保存 input_data / output_data、retry_count、error_message。

---

3. 分层架构

                ┌──────────────────────────────┐
   API 层       │  DRF ViewSets / SSE Views    │  apps/*/views.py  apps/*/sse_views.py
                ├──────────────────────────────┤
   业务服务层   │  Service / Queue / Signals   │  apps/*/services.py  queue_service.py
                ├──────────────────────────────┤
   工作流引擎   │  Pipeline (责任链)            │  core/pipeline/{base,orchestrator}.py
                ├──────────────────────────────┤
   Stage 处理器 │  LLM/Text2Image/Image2Video… │  apps/content/processors/*
                ├──────────────────────────────┤
   AI 客户端    │  策略模式 + 工厂动态导入      │  core/ai_client/*
                ├──────────────────────────────┤
   领域模型     │  Project / Stage / Storyboard│  apps/*/models.py
                ├──────────────────────────────┤
   基础设施     │  Postgres + Redis + Celery   │  config/settings/* config/celery.py
                └──────────────────────────────┘

关键约定

• apps/ 放业务逻辑，core/ 放抽象与基础设施。视图、URL、业务服务必须放在 apps/ 下，core/ 不得包含视图层。
• 所有 Stage 处理器走的都是 core/pipeline/base.py 里的同一套抽象：validate() → process() → on_success / on_failure。
• 所有 AI 客户端走的都是 core/ai_client/base.py 里的同一套接口，统一返回 AIResponse(success, text, data, metadata, error)。
• 严格 SOLID（详见 CLAUDE.md），新增 stage / 新增厂商时只继承不改核心。

---

4. 核心抽象

4.1 Pipeline / StageProcessor

文件: backend/core/pipeline/base.py

@dataclass
class PipelineContext:
    project_id: str
    results: Dict[str, Any]
    metadata: Dict[str, Any]

@dataclass
class StageResult:
    success: bool
    data: Dict[str, Any]
    error: Optional[str]
    can_retry: bool = True

class StageProcessor(ABC):
    @abstractmethod
    async def validate(self, context): ...
    @abstractmethod
    async def on_failure(self, context, error): ...
    async def on_success(self, context, result): ...

编排器: backend/core/pipeline/orchestrator.py ProjectPipeline

• execute(project_id)：完整流程
• execute_stage(project_id, stage_name)：单阶段
• 失败自动重试（指数退避 1s/2s/4s）

4.2 AI 客户端抽象 + 工厂 + 注册表

文件:

• 抽象基类: backend/core/ai_client/base.py
• 工厂: backend/core/ai_client/factory.py
• 注册表: backend/core/ai_client/registry.py

BaseAIClient
├── LLMClient            ← OpenAIClient / MockLLMClient
├── Text2ImageClient     ← Text2ImageClient / ComfyUIClient / MockText2ImageClient
├── Image2VideoClient    ← VideoGeneratorClient / VolcengineImage2VideoClient / ComfyUIClient / MockImage2VideoClient
└── ImageEditClient      ← ImageEditClient / MockImageEditClient

工厂通过 ModelProvider.executor_class 字段（如 core.ai_client.openai_client.OpenAIClient）动态导入具体客户端类，不需要 if/elif 判断厂商 —— 这是 OCP 的关键落点：新增一个厂商 = 新增一个文件 + 在数据库里录入一条 ModelProvider。

ModelProvider 还内置了一组允许的执行器白名单（LLM_EXECUTORS / TEXT2IMAGE_EXECUTORS / …），用于校验和管理后台下拉选择。

4.3 负载均衡

ProjectModelConfig（backend/apps/projects/models.py）允许每个阶段挂 多个 ModelProvider（M2M），并支持 4 种策略：

round_robin / random / weighted / least_loaded

容错机制：失败自动重试 + 故障转移（切换下一个 provider）。

---

5. 领域模型速查

5.1 项目管理域 apps/projects

模型	作用
Series	顶层作品（多分集组合）
Project	项目聚合根，关联 PromptTemplateSet，状态 draft/queued/processing/completed/failed/paused
ProjectStage	阶段状态追踪（stage_type 见上文 8 个阶段）
ProjectModelConfig	阶段 ↔ 多模型 M2M + 负载均衡策略
EpisodeTaskQueue	同一作品下分集任务串行执行队列

5.2 提示词管理域 apps/prompts

模型	作用
PromptTemplateSet	提示词集（一个项目挂一个集合，可复用、可设默认）
PromptTemplate	单个阶段的提示词（Jinja2 模板 + variables + client_params + 版本号 + 关联默认 model_provider）
GlobalVariable	全局变量（系统级 / 用户级，类型支持 string/number/boolean/json/image）
PromptDebugSession / PromptDebugRun / PromptDebugArtifact	提示词调试三件套：会话草稿 → 运行记录 → 可被下游复用的资产

5.3 模型管理域 apps/models

模型	作用
ModelProvider	厂商配置（provider_type ∈ llm/text2image/image2video/image_edit，含 executor_class、API URL、API Key、限流、优先级、extra_config）
VendorConnectionConfig	内置厂商导入连接（按用户保存的 API Key/URL，方便从厂商目录批量导入模型）
ModelUsageLog	调用日志：tokens、延迟、状态、关联 project/stage（用于成本统计）

5.4 内容生成域 apps/content

模型	关系	关键字段
ContentRewrite	1:1 Project	original_text、rewritten_text
Storyboard	N:1 Project	sequence_number、scene_description、narration_text、image_prompt、duration_seconds
MultiGridImageTask / MultiGridTile	N:1 Storyboard	多宫格大图与切片
GeneratedImage	N:1 Storyboard	generation_params、retry_count
EditedImage	关联多宫格 / 单图	图片编辑产物
CameraMovement	1:1 Storyboard	movement_type、movement_params
GeneratedVideo	N:1 Storyboard，关联 image + camera_movement	duration / width / height / fps / file_size

---

6. 运行时 / 异步与流式

• 新架构（Celery + Redis Pub/Sub）：API 入口下发任务到 Celery Worker（按 llm / image / video 队列分流），Worker 在执行过程中通过 core/redis/publisher.py RedisStreamPublisher 把 token / 进度 / 结果发布到 Redis Channel；前端通过 SSE 或轮询订阅。
• 旧架构（直连 SSE）：apps/projects/sse_views.py 在 ASGI 模式下做实时流式输出，作为 fallback 保留。
• Redis 数据库切分（避免冲突）：
  • db 0 Celery broker
  • db 1 Celery result backend
  • db 2 Pub/Sub
  • db 4 Django cache

---

7. 关键扩展点（写新代码时该改哪里）

7.1 新增一个 Stage（阶段）

1. 在 ProjectStage.STAGE_TYPES 与 PromptTemplate.STAGE_TYPES 同步加新枚举。
2. 在 backend/apps/content/processors/ 新建处理器：
   • 文本类继承 LLMStageProcessor（覆盖 _get_input_data / _build_tasks / _save_result 即可）
   • 图片 / 视频类继承 Text2ImageStageProcessor / Image2VideoStageProcessor
3. 在 apps/projects/tasks.py 注册对应 Celery 任务，按需挂队列。
4. 在 apps/prompts/client_param_specs.py 加该阶段可调参数（max_tokens、temperature、强度等），管理端会自动生成表单。
5. 在 apps/projects/default_promot/ 放一份默认提示词 <stage>.md，迁移后会被 signals.py::_ensure_default_prompt_template_set 自动种入数据库。

7.2 新增一个 AI 厂商

1. 在 core/ai_client/ 新建 xxx_client.py，继承对应基类，实现 _generate_* + validate_config。
2. 在 apps/models/models.py::ModelProvider 对应 *_EXECUTORS 白名单加一行。
3. 后台或种子脚本里录入 ModelProvider 行（带 executor_class 完整类路径）。
4. （可选）在 apps/models/vendor_catalog.py 加目录条目，让用户能"按厂商导入"。

7.3 调整提示词 / 默认提示词集

• 用户态：在前端"提示词管理"创建 PromptTemplateSet，挂到项目上。
• 系统态：放 apps/projects/default_promot/<stage>.md，下次 migrate 时自动写入"默认提示词模板集"。

---

8. 启动 & 部署摘要

# 一键起全部
docker-compose up -d
docker-compose exec backend python backend/manage.py migrate
docker-compose exec backend python backend/manage.py createsuperuser
# 前端: http://localhost:3000   后端: http://localhost:8000   Admin: /admin

本地开发：

cd backend
uv sync                                         # 装依赖
./run_asgi.sh                                   # 启 ASGI（推荐）
uv run celery -A config worker -Q llm,image,video -l info
uv run celery -A config beat -l info

---

9. 闭源边界

• 开源仓 backend/apps/agent/ 与 backend/apps/mcp/ 目录是空的（README 与 backend/docs/CLOSED_SOURCE_APPS.md 说明只保留编译后的 .so）。
• 这两个 app 在本仓中没有源码可读，因此本系列文档只覆盖开源部分的 Pipeline、Stage、AI 客户端、提示词三大主线。

---

10. 配套文档

• 02_Agents与Skills.md —— 项目里"Agent / Skill"在工程里以何种形态存在（Stage Processor / AI Client / 提示词模板），按角色逐个拆开。
• 03_提示词.md —— 默认提示词原文 + 提示词运行时变量 / 参数 / 调试机制。