多智能体协作AI漫剧生成平台：从架构到部署的完整实践
1. 项目概述：一个多智能体协作的AI漫剧生成平台
最近在折腾一个挺有意思的项目，叫 openOii。简单来说，它是一个“AI导演工作室”，你只需要给它一个故事点子，它就能指挥一帮各司其职的AI“员工”，从写剧本、设计角色、画分镜，到最后生成视频，全流程自动给你跑下来，最终产出一个完整的漫剧视频。这玩意儿本质上是一个基于多智能体（Multi-Agent）协作架构的创作平台，把过去需要多个专业软件和大量人工操作的视频创作流程，用一套自动化的AI流水线给串联起来了。
我最初被这个项目吸引，是因为它解决了一个很实际的痛点：创意到成品的“最后一公里”问题。现在文生图、文生视频的模型很多，但单个模型的能力是点状的。你想做一个有角色、有情节、有转场的短片，光靠一个提示词丢给视频生成模型，出来的东西往往角色形象飘忽不定、剧情支离破碎。openOii 的思路很清晰——既然一个AI干不好所有事，那就搞个“剧组”，让不同的AI智能体（Agent）分别扮演导演、编剧、角色设计师、分镜师、视频合成师，甚至还有“品控”（Review Agent），让它们在一个规范的流程里协同工作。这比单纯堆砌模型接口要有意思得多，也更接近真实的创作逻辑。
这个项目适合几类人：一是对AI应用开发，特别是智能体（Agent）架构感兴趣的技术开发者，可以把它当作一个研究多智能体任务编排的绝佳案例；二是内容创作者或小型工作室，想探索用AI辅助或自动化生成短视频、故事短片；三是任何对“AI如何系统性完成复杂创意任务”这个命题感到好奇的人。它不是一个开箱即用的傻瓜软件，需要你配置一些AI服务的API密钥，但一旦跑通，看着AI们像流水线一样把你的想法一步步变成视频，那种感觉还是挺奇妙的。
2. 核心架构与多智能体协作流程拆解
2.1 技术栈选型背后的考量
openOii 采用了前后端分离的经典架构，这个选择很务实。后端用FastAPI + SQLModel，看中的是 FastAPI 的异步高性能和自动生成 API 文档的能力，这对于需要处理大量 AI 模型调用（这类 I/O 密集型任务）的服务来说非常合适。SQLModel 则结合了 SQLAlchemy 的 ORM 能力和 Pydantic 的数据验证，用一套代码定义数据库模型和 API 请求/响应模型，开发效率很高。数据库选了PostgreSQL，没毛病，关系型数据库对于管理项目、剧本、角色、分镜这些结构化数据是自然的选择，而且通过 asyncpg 驱动支持异步操作，不拖后腿。
前端是React 18 + TypeScript + Vite的组合，这是当前现代 React 开发的事实标准。状态管理用了Zustand，而不是 Redux，这点我很赞同。对于这种中复杂度的应用，Zustand 的 API 更简洁，心智负担小。样式是Tailwind CSS + DaisyUI，能快速搭建出美观且一致的界面，特别适合这种需要动态展示多种类型内容（卡片、画布）的应用。
真正体现项目特色的，是它的“中枢神经系统”：Redis和WebSocket。多智能体协作是个异步、耗时的过程。一个剧本生成可能花 30 秒，角色图生成 10 张图每张 5 秒，视频生成一段可能要一分钟。如果让前端傻傻地轮询，体验极差。这里用 WebSocket 建立长连接，后端每个 Agent 完成一个阶段（比如生成完一个角色），就通过 WebSocket 向前端“报喜”，前端实时更新进度条和预览图，体验就流畅了。而 Redis 在这里扮演了“共享内存”或“信号量”的角色，当多个进程（比如你用了多个 worker）需要协同或传递一些简单的状态信号时，通过 Redis 来同步比通过数据库更轻量、更快。
2.2 多智能体流水线：从创意到成品的八步走
项目的核心灵魂是那 8 个 AI Agent 组成的流水线。我们把它拆开看，理解每个 Agent 的职责和它们之间的协作逻辑：
Onboarding Agent（需求分析员）：这是第一个接触用户创意的 Agent。它的任务不是直接创作，而是“理解与澄清”。用户输入可能很模糊，比如“一个宇航员在火星上发现了猫”。Onboarding Agent 会尝试与用户（或根据初始输入）进行交互，明确风格（是科幻严肃还是搞笑卡通？）、时长、目标受众等，形成一份清晰的“创意简报”。这步很关键，它确保了后续所有创作都在正确的方向上。
Director Agent（导演）：拿到创意简报后，Director Agent 开始进行高层规划。它决定这个故事的整体结构：分几幕？有几个主要场景？每个场景的氛围是什么？需要哪些角色？它输出的是一个“导演阐述”或“拍摄大纲”，为编剧提供框架。
Scriptwriter Agent（编剧）：基于导演大纲，编剧 Agent 开始撰写详细的剧本。这包括具体的角色对话（如果有）、场景描述、以及分镜脚本。分镜脚本会详细描述每一个镜头的构图、角色动作、景别（特写、中景、全景等）。这是连接文字创意和视觉画面的关键桥梁。
Character Artist Agent（角色设计师）：剧本里出现了哪些角色？根据剧本中的描述和导演设定，这个 Agent 负责为每个主要角色生成设定图。这里的一个技术挑战是“角色一致性”。理想情况下，它应该生成同一个角色在不同角度、表情下的多张图，并且确保这些图看起来是同一个人。项目提到了使用“图生图”来提升一致性，但这也依赖于后端图像服务的能力。
Storyboard Artist Agent（分镜师）：这是我最欣赏的一环。它根据编剧提供的每一个镜头的文字描述，生成该镜头的“关键帧”或“首帧”图像。如果开启了图生图模式，它还会参考 Character Artist 生成的角色图，确保分镜画面上的人物形象和角色设定图保持一致。这样，在生成视频之前，你就能看到一个可视化的、带画面的“连环画”脚本。
Video Generator Agent（视频生成师）：重头戏来了。这个 Agent 拿到一个镜头的描述（来自剧本）和对应的首帧图像（来自分镜师），去调用文生视频或图生视频的模型，生成一段几秒钟的视频片段。它可以选择两种模式：纯文本生成，或者以分镜首帧（或结合角色图）为参考进行生成，后者能更好地保持画面连贯性和角色一致性。
Video Merger Agent（视频剪辑师）：所有镜头的视频片段都生成好后，是一堆零散的 MP4 文件。Video Merger Agent 的工作就是调用 FFmpeg 这样的工具，把这些片段按照剧本的顺序拼接起来，可能还会加上简单的转场效果、背景音乐（如果项目后续支持），最终输出一个完整的视频文件。
Review Agent（品控/复盘员）：这个 Agent 体现了系统的“闭环”思想。生成结果给用户看，用户可能对某个角色的形象、某个镜头的画面不满意。Review Agent 负责处理这种反馈。用户可以选中不满意的部分（比如第三号角色），提出修改意见（“把这个角色改成金发”），Review Agent 会协调流程，只重新运行与该部分相关的后续 Agent（比如重新生成该角色的设定图，然后基于新设定图重新生成涉及该角色的分镜和视频），而不是推倒重来。这大大提升了迭代效率。
这个流水线就像一个高度自动化的电影制片厂，每个 Agent 都是专业部门，它们通过标准的“工作单”（结构化数据）进行交接，最终共同完成一部作品。这种设计模式，对于复杂任务的 AI 自动化，非常有借鉴意义。
3. 实战部署：两种方式详解与避坑指南
纸上谈兵终觉浅，我们得把它跑起来。项目提供了 Docker 一键部署和本地开发部署两种方式，我强烈推荐Docker 方式，尤其是对于只想快速体验或者用于生产环境的情况。它能避免很多环境依赖的麻烦。
3.1 Docker 一键部署（推荐方案）
3.1.1 环境变量配置：成败的关键
部署的核心是正确配置.env文件。项目提供了一个.env.example模板，复制后你需要填写关键的 API 密钥。这里有几个容易踩坑的点，我结合自己的经历详细说说：
# 后端服务配置 DATABASE_URL=postgresql+asyncpg://postgres:yourpassword@db:5432/openoii REDIS_URL=redis://redis:6379/0 # LLM 服务（核心中的核心） ANTHROPIC_BASE_URL=https://你的代理服务地址/v1 ANTHROPIC_AUTH_TOKEN=你的代理服务密钥关于 LLM 服务：项目底层使用 Claude Agent SDK，所以需要配置 Anthropic 兼容的 API。如果你没有直接的 Anthropic API，可以使用国内外的各种兼容代理服务。ANTHROPIC_BASE_URL就是你的代理服务商提供的接口地址，ANTHROPIC_AUTH_TOKEN就是对应的密钥。这是驱动所有 Agent“大脑”的引擎，必须配对。
# 图像生成服务 IMAGE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 IMAGE_API_KEY=你的DashScope API Key IMAGE_MODEL=wanx-v1关于图像生成：项目兼容任何 OpenAI 格式的图片生成接口。我实测推荐使用阿里云的通义万相（DashScope），国内访问稳定，效果也不错。如上配置即可。IMAGE_MODEL指定模型，比如wanx-v1。注意，如果你想用“图生图”模式来保持角色一致性，需要确认你用的模型支持image-to-image功能。通义万相目前是支持的。
# 视频生成服务 VIDEO_PROVIDER=doubao DOUBAO_API_KEY=你的豆包视频API Key # 或者使用 OpenAI 兼容接口 # VIDEO_PROVIDER=openai # VIDEO_BASE_URL=https://你的视频服务地址/v1 # VIDEO_API_KEY=你的视频服务密钥关于视频生成：这是资源消耗最大的一步。项目推荐火山引擎的豆包视频服务（Ark API），实测生成速度和效果在中文场景下比较好。你需要去火山引擎平台申请开通。如果使用其他 OpenAI 兼容的视频生成接口（比如一些海外服务），需要相应修改VIDEO_BASE_URL和VIDEO_API_KEY。
最大的一个坑：网络配置。如果你的图像/视频服务是独立部署在宿主机或另一个容器里的，在 Docker 容器内不能直接用localhost或127.0.0.1去访问，因为localhost在容器内指向容器自己。
错误配置：
IMAGE_BASE_URL=http://localhost:8000 # 容器内找不到这个服务！正确配置（服务在宿主机）：
IMAGE_BASE_URL=http://host.docker.internal:8000 # 宿主机专用域名 # 或者 IMAGE_BASE_URL=http://192.168.1.100:8000 # 宿主机实际IP正确配置（服务在另一个Docker容器）： 这需要修改docker-compose.yml，让backend服务加入到图像服务所在的 Docker 网络。假设你的图像服务叫image-service，在名为ai-net的网络中。
首先，在docker-compose.yml的backend服务下添加网络配置：
services: backend: ... networks: - default # 默认网络，用于连接db和redis - ai-net # 加入图像服务的网络 networks: ai-net: external: true # 声明使用外部已存在的网络然后，在.env中，你就可以用容器名访问了：
IMAGE_BASE_URL=http://image-service:80003.1.2 启动与验证
配置好.env后，启动就一行命令：
docker-compose up -d-d参数让服务在后台运行。
启动后，用docker-compose ps查看状态，确保backend、frontend、db、redis四个服务都是Up状态。如果有问题，用docker-compose logs -f backend查看后端日志，大部分错误信息（如 API 连接失败、密钥错误）都会在这里显示。
访问前端：http://localhost:15173访问后端 API 文档：http://localhost:18765/docs（用这个来调试接口非常方便）
3.2 本地开发部署（适合深度定制）
如果你想修改代码、添加新 Agent 或者调试，就需要本地部署。
后端：
- 确保安装了 Python 3.10+、PostgreSQL 和 Redis。
- 克隆项目，进入
backend目录。 - 使用
uv或pip安装依赖。我推荐uv，速度飞快。 - 同样配置
.env文件，但DATABASE_URL和REDIS_URL要指向你本地安装的服务。 - 运行数据库迁移（如果项目有 Alembic 迁移脚本的话）。
- 用
uvicorn app.main:app --reload启动开发服务器。
前端：
- 进入
frontend目录。 - 用
pnpm install安装依赖（项目推荐 pnpm，也可以用 npm）。 - 通常
vite.config.ts里已经配置了代理，将前端请求转发到后端localhost:18765。如果端口冲突，需要修改这里。 - 用
pnpm dev启动开发服务器。
本地部署的优点是热重载，改代码立刻生效，方便调试。缺点是环境准备稍微麻烦。
4. 核心功能深度解析与配置技巧
4.1 无限画布与配置管理：体验提升的关键
2026年2月的更新引入了两个非常实用的功能：无限画布和前端配置管理。
无限画布：早期版本可能只是列表展示剧本、角色、分镜卡片。现在换成了基于tldraw的无限画布。这意味着你可以在一个巨大的、可自由缩放拖动的画布上，随意摆放你的剧本卡片、角色立绘、分镜画面和视频预览块。这不仅仅是UI的花哨，它极大地改善了创作体验。你可以像导演看分镜墙一样，全局审视整个项目的视觉元素，拖拽调整顺序，直观地建立元素之间的关联。这种空间化的信息组织方式，对于创意类项目来说，比线性列表友好得多。
前端配置管理：这是一个解决运维痛点的功能。原本修改配置（比如换一个LLM服务商、改视频模型）需要去后端修改.env文件，然后重启服务。现在，在前端界面就提供了一个配置页面，可以实时修改并保存到数据库。这太方便了，尤其是在多用户或者你需要频繁调整AI服务参数的场景下。实现上，它通常是前端提供一个表单，修改后通过 API 调用更新后端的某个配置存储（可能是数据库里的一张配置表），然后后端服务在需要时读取这些配置。注意，像数据库连接字符串这种启动时就必须确定的配置，可能还是需要重启，但AI服务的API密钥和端点这类动态配置，就可以实时生效。
4.2 图像与视频生成模式详解
项目提供了灵活的生成模式，理解它们对控制输出质量至关重要。
图像生成模式：
- 文生图（Text-to-Image）：这是默认模式。
Storyboard Artist Agent仅根据剧本的文字描述来生成分镜首帧。优点是快，不依赖其他环节。缺点是角色一致性难保证，同一个角色在不同镜头里可能长得不一样。 - 图生图（Image-to-Image）：需要设置
ENABLE_IMAGE_TO_IMAGE=true。在此模式下，Storyboard Artist Agent生成分镜时，会以Character Artist Agent生成的角色图作为参考图像输入。这能显著提升不同分镜中同一角色形象的一致性。但是，这要求你后端的图像生成服务必须支持图生图功能。像项目提到的魔搭（ModelScope）平台，可能某些模型不支持，那就无法启用此模式。在配置时务必确认你的图像API能力。
视频生成模式：
- 文生视频（Text-to-Video）：
Video Generator Agent仅根据镜头文本描述生成视频。这是最通用的模式。 - 图生视频（Image-to-Video）：设置
ENABLE_IMAGE_TO_VIDEO=true。此模式下，生成视频时会附加参考图像。这里又有两个子模式，通过VIDEO_IMAGE_MODE控制：first_frame：仅使用该镜头的分镜首帧作为参考。这有助于视频的开场画面与分镜图更接近。reference：将角色图和分镜首帧拼接起来作为参考。这是推荐的模式，它能同时引导视频的人物形象和场景构图，最大程度保证视频与前期设计的一致性。
实操心得：
- 质量与成本的权衡：图生图、图生视频模式无疑会提高一致性，但通常也会增加API调用成本（因为请求体更大），并可能略微增加生成时间。对于个人玩一玩，文生图+文生视频可能就够了。对于想产出更严肃作品，开启图生图/视频是值得的。
- 提示词（Prompt）工程是隐形的核心：虽然项目封装了Agent，但每个Agent调用AI模型时，其内部构建的提示词（Prompt）质量直接决定输出好坏。比如
Scriptwriter Agent如何将导演大纲转化为详细剧本和分镜描述，Character Artist Agent如何将角色文字描述转化为图像生成提示词。这部分逻辑在代码里，如果你发现生成的内容总是偏离预期，可能需要去调试或优化这些Agent内部的提示词模板。 - 种子（Seed）控制：为了可复现性，在图像和视频生成时，如果能固定种子（Seed），那么每次生成的結果会一致。项目是否暴露了种子参数，或者在其内部是否使用了固定逻辑，值得查看。这对于调试和确保流程稳定性很重要。
5. 常见问题排查与性能优化经验
在实际部署和运行中，你肯定会遇到各种问题。这里我整理了一份“踩坑实录”和解决方案。
5.1 部署与连接类问题
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
| Docker 启动后，前端白屏或无法连接后端。 | 1. 容器网络问题，前端无法访问后端API。 2. 后端服务启动失败。 | 1. 检查docker-compose ps，确认所有容器状态为Up。2. 查看后端日志： docker-compose logs -f backend。常见错误：数据库连接失败（检查DATABASE_URL）、Redis连接失败、API密钥无效。3. 打开浏览器开发者工具（F12），看Console和Network标签页，是否有前端JS报错或API请求失败（404/500）。确认API请求的地址和端口是否正确（应是后端容器名或宿主机映射端口）。 |
| 创建项目时，卡在“Onboarding Agent”或某个Agent阶段。 | 1. LLM服务（Anthropic）配置错误或无法访问。 2. 该Agent的API调用超时或返回错误。 | 1.首要检查：后端日志。会明确显示调用哪个API时失败，以及错误信息（如401认证失败、429频率限制、503服务不可用）。 2. 确认 ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN正确无误，且该代理服务可用。3. 如果是超时，可能是网络问题或服务响应慢。考虑在后端代码中适当调整请求超时时间。 |
| 图像或视频生成失败，提示“模型不支持”或“参数错误”。 | 1. 图像/视频服务提供商不支持当前模式（如图生图）。 2. 请求参数格式不符合该服务商要求。 | 1. 对照服务商文档，确认你使用的模型是否支持你开启的模式（如wanx-v1是否支持image-to-image）。2. 查看后端代码中对应服务（如 services/image/openai_compatible.py）的请求体构建逻辑，可能与标准OpenAI格式有细微差别，需要适配你的服务商。 |
| WebSocket 连接不稳定，进度更新时断时续。 | 1. 网络环境问题（如不稳定的代理）。 2. 后端WebSocket服务处理异常。 | 1. 检查浏览器开发者工具中WebSocket连接状态。 2. 在后端日志中搜索WebSocket相关错误。 3. 考虑在Nginx等反向代理配置中，增加对WebSocket的支持（ Upgrade和Connection头）。Docker Compose直接映射端口通常无此问题。 |
5.2 生成质量与逻辑类问题
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
| 生成的角色形象不一致，同一个角色在不同分镜里样子变了。 | 1. 未开启图生图模式。 2. 开启了图生图，但图像服务不支持或效果不佳。 3. Character Artist 生成的角色图本身差异大。 | 1. 确保ENABLE_IMAGE_TO_IMAGE=true，并确认你的图像API支持此功能。2. 尝试使用更强大的图像生成模型。 3. 优化 Character Artist Agent的提示词，要求其生成多视图、多表情但核心特征一致的角色图。可以在角色描述中增加更详细的、可区分的特征（如“左眼下方有颗痣”、“总是戴着红色围巾”）。 |
| 生成的视频内容与分镜图相差甚远。 | 1. 视频生成模型的理解能力有限。 2. 图生视频模式下，参考图像的影响权重可能太低。 3. 分镜图的提示词与视频提示词衔接不好。 | 1. 尝试使用VIDEO_IMAGE_MODE=reference模式，提供更强的图像参考。2. 如果视频API支持，尝试调整“图像参考强度”之类的参数（需要在代码中暴露或调整）。 3. 检查 Video Generator Agent的提示词构建逻辑，确保它充分结合了镜头文本描述和“参考图像”的信息。 |
| 剧本或分镜描述过于简单或不合逻辑。 | LLM（Claude）的提示词或生成逻辑有待优化。 | 这是最需要定制化的部分。你需要去修改对应Agent（如DirectorAgent,ScriptwriterAgent）的“系统提示词（System Prompt）”和生成逻辑。比如，在导演Agent的提示词中强调需要“起承转合”的三幕结构，在编剧Agent的提示词中要求每个分镜描述必须包含“景别、角色动作、镜头运动”等要素。 |
| 整个流程耗时太长。 | 1. 网络延迟高。 2. AI服务响应慢。 3. 串行流程，每个步骤必须等上一步完成。 | 1. 选择地理位置上更近或更稳定的AI服务提供商。 2.性能优化关键：分析流水线，看哪些步骤可以并行。例如，生成所有角色图、生成所有分镜图，这些任务之间如果没有强依赖，是可以并行执行的。同样，所有镜头的视频生成也可以并行。这需要修改任务调度逻辑，从串行改为有向无环图（DAG）调度，可以显著缩短总耗时。 |
5.3 成本控制与扩展建议
- API成本监控：视频生成，尤其是高分辨率、长时长，是成本大头。豆包视频服务按秒计费。务必在服务商后台设置用量告警和预算限制。对于测试，可以先用低分辨率、短时长生成。
- 缓存策略：对于经常使用的角色设定、场景风格，可以考虑将生成的图像缓存起来（存储到本地或对象存储），下次类似需求直接复用，避免重复生成，节省成本和时间。
- Agent能力扩展：目前的流水线是线性的。你可以尝试引入“评审循环”。例如，在
Scriptwriter Agent生成剧本后，新增一个Critic Agent从故事性、节奏等方面进行评价，并提出修改建议，让编剧Agent重写，直到达到一定标准再进入下一环节。这能让生成质量更高，但也会增加复杂度和成本。 - 人类介入点（Human-in-the-loop）：完全自动化不一定总是最优。可以在关键节点设置“人工审核”。例如，在生成角色设计图后，弹出界面让用户选择最满意的一张，后续流程都基于这张图进行。这能极大提升最终成果的满意度。
这个项目是一个非常好的多智能体系统范本。把它跑通，你就能切身感受到AI Agent如何通过分工协作来解决复杂任务。而在此基础上进行修改、优化和扩展，才是真正有趣且能学到东西的地方。从调整一个Agent的提示词，到重构任务调度流程，每一步都是对AI工程化能力的实践。