1. 项目概述一个由AI智能体驱动的“虚拟制片厂”最近在折腾一个挺有意思的东西我把它叫做openOii。简单来说你可以把它理解为一个全自动的“虚拟制片厂”。你只需要给它一个故事点子比如“一只会编程的猫在火星上开咖啡馆”它就能调动背后一整套AI“员工”从写剧本、设计角色、画分镜一直到生成最终的视频成片全部自动完成。这背后的核心不是什么单一的“超级AI”而是一套精心设计的多智能体Multi-Agent协作系统。想象一下你有一个导演、一个编剧、一个角色设计师、一个分镜师、一个视频剪辑师……只不过他们全都是AI。每个AI“员工”Agent都专精于一项任务并且能根据上游同事的产出继续自己的工作最终串联起从“创意文本”到“视频文件”的完整流水线。这比单纯用一个模型去“一步到位”要靠谱得多因为每个环节都可以做得更专业、更可控。这个项目非常适合那些有创意但缺乏美术或视频制作能力的内容创作者、想快速验证故事概念的编剧、或者单纯对AIGC人工智能生成内容工作流感兴趣的技术开发者。它把目前市面上分散的AI能力大语言模型、文生图、文生视频用工程化的方式整合了起来提供了一个开箱即用的创作平台。2. 核心架构与设计思路拆解2.1 为什么选择多智能体架构在项目初期我考虑过几种方案。最简单的是“单模型提示词工程”即写一个巨长无比的提示词让一个大语言模型比如GPT-4一次性输出剧本、角色描述、分镜描述然后再调用其他AI生成图像和视频。但实测下来这条路问题很大输出质量不稳定格式容易混乱且一旦中间某个环节出错整个流程就得推倒重来。于是我转向了智能体Agent的思路。智能体不仅仅是调用API它具备一定的“思考”能力通过LLM可以根据目标、上下文和历史信息自主规划并执行任务。将整个漫剧生成流程拆解成多个由智能体负责的环节带来了几个显著优势职责分离与专业化每个智能体只关心自己的领域。ScriptwriterAgent编剧智能体不需要懂图像生成它只需要专注于把故事写好CharacterArtistAgent角色设计师智能体则专注于根据角色描述画出好看且一致的角色图。这大大降低了单个智能体的认知负担提升了各环节的产出质量。流程可控与可调试每个环节的输入和输出都是结构化的数据。剧本是一个包含场景、对话、动作的JSON角色是一组带有详细属性发型、服装、表情的描述。这意味着你可以在任意环节介入检查中间产物如果对角色设计不满意可以只让CharacterArtistAgent重新工作而不影响已经写好的剧本。系统的可扩展性如果需要增加新的环节比如“配乐智能体”或“特效智能体”只需要定义好它的输入输出接口将其插入到协作链的合适位置即可对现有系统影响很小。2.2 技术栈选型的背后考量一个稳定、高效的技术栈是支撑这套复杂系统的基石。我的选型主要基于开发效率、性能、以及与现代AI服务生态的兼容性。后端BackendFastAPI SQLModel这是黄金组合。FastAPI的异步特性完美应对AI API调用这类高I/O延迟的操作自动生成的交互式API文档Swagger UI对于前后端联调和后期维护至关重要。SQLModel基于Pydantic和SQLAlchemy让我能用Python类同时定义数据模型Schema和数据库表结构ORM保证了从API接口到数据库层数据一致性减少了大量样板代码。PostgreSQL RedisPostgreSQL作为主数据库存储项目、剧本、角色、生成任务等所有核心数据。Redis则用于跨进程的状态共享和信号传递这是关键。例如当视频生成任务在后台Celery worker中运行时前端需要通过WebSocket实时获取进度。这个进度状态就通过Redis进行发布/订阅实现了后端进程与前端连接的解耦。Claude Agent SDK选择Anthropic的Claude系列模型作为智能体的“大脑”主要是看中其在长文本理解、复杂指令遵循和创造性写作方面的稳定表现。其Agent SDK提供了构建智能体所需的基础框架简化了开发。前端FrontendReact 18 TypeScript Vite这是现代React开发的标配。TypeScript的强类型检查在管理复杂的状态如项目数据、生成队列时能提前发现大量潜在错误。Vite的快速热更新极大地提升了开发体验。Zustand TanStack Query状态管理上我放弃了Redux的繁琐选择了轻量且易用的Zustand来管理UI状态如侧边栏开关、画布视图。对于服务器状态项目列表、任务详情则用TanStack Query原React Query来处理。它能自动处理缓存、后台刷新、错误重试让数据同步逻辑变得异常清晰。Tailwind CSS DaisyUI快速构建美观且响应式界面的不二之选。DaisyUI提供了大量现成的、风格统一的组件让我不必在CSS细节上花费过多时间能更专注于业务逻辑和交互体验。注意技术栈的选择也带来了特定的部署考量。例如异步的FastAPI需要搭配支持异步驱动的数据库连接库如asyncpg这在选择云数据库或配置连接池时需要留意。3. 多智能体协作流程的深度解析整个系统的灵魂在于八个智能体如何像接力赛一样协同工作。下面我详细拆解每个智能体的职责、技术实现和它们之间的数据流转。3.1 智能体分工与协作链条整个流程是一个有向无环图DAG智能体按顺序被触发上游的输出是下游的输入。用户输入创意 ↓ [OnboardingAgent]需求分析师 ↓ [DirectorAgent]总导演 ↓ [ScriptwriterAgent]编剧 ↓ [CharacterArtistAgent]角色设计师 ↓ [StoryboardArtistAgent]分镜师 ↓ [VideoGeneratorAgent]视频生成师 ↓ [VideoMergerAgent]剪辑师 ↓ [ReviewAgent]质量审核与重制1. OnboardingAgent需求分析智能体这是第一个接触用户创意的智能体。它的任务不是直接开始创作而是澄清和细化需求。用户输入可能很模糊比如“一个科幻爱情故事”。OnboardingAgent会通过多轮对话在后台自动完成询问并确认故事的时代背景主要角色有几个风格是悲情还是喜剧预期视频时长它将模糊的输入转化为一份结构化的“创意简报”为后续所有工作定下基调。2. DirectorAgent导演智能体拿到创意简报后DirectorAgent开始进行高层规划。它决定这个故事大概需要分成几个场景Scene每个场景的核心冲突或转折点是什么整体的节奏如何把控。它会生成一个“导演阐述”类似于电影开拍前的分场大纲这将成为编剧的创作指南。3. ScriptwriterAgent编剧智能体这是文本创作的核心。它根据导演阐述为每一个场景生成详细的剧本。剧本是结构化的JSON数据包含scene_number场次编号。location场景地点如“火星咖啡馆内部”。characters本场出现的角色列表。dialogue角色的对话内容。action角色的动作和表情描述。shot_description这一场建议的镜头描述推近、特写、全景等这部分描述会直接用于后续的分镜生成。4. CharacterArtistAgent角色设计师智能体剧本中所有角色会被提取出来交给这个智能体。它的核心挑战是保证角色一致性。它不会为每个场景重新生成角色而是为每个角色生成一份详细的“角色设定图”包括面部特征、发型、服饰、标志性道具等。这份详细的文本描述会作为后续所有图像生成的“种子”。在生成角色立绘时它会调用文生图API并使用如(character_name:1.5)这样的提示词权重技巧来强化对角色关键特征的刻画。5. StoryboardArtistAgent分镜师智能体这是连接文本和画面的关键一环。它为剧本中的每一个镜头Shot生成一张分镜首帧图。这里有两种模式文生图模式直接根据镜头的shot_description生成图像。速度快但角色形象可能和之前设计的立绘有偏差。图生图模式推荐将CharacterArtistAgent生成的角色立绘作为生成分镜图的参考图像输入。这样能最大程度保证分镜图中的人物与角色设计保持一致。这需要后端的图像生成服务如Stable Diffusion的Img2Img功能支持。6. VideoGeneratorAgent视频生成师智能体将分镜图转化为动态视频。同样有两种策略文生视频使用镜头的shot_description直接生成视频。兼容性最好但画面元素和分镜图可能关联不强。图生视频强力推荐将分镜图或分镜图与角色图的拼接图作为参考帧输入给视频生成模型如Sora、Pika等兼容此功能的模型。这能极大地提升视频画面与前期设计的一致性是产出高质量成片的关键。我们在环境变量中通过VIDEO_IMAGE_MODE来精细控制参考方式。7. VideoMergerAgent视频剪辑师智能体这个智能体不调用AI模型而是进行传统的工程化处理。它将VideoGeneratorAgent生成的所有片段视频按照剧本的顺序使用FFmpeg进行拼接、转场处理如简单的淡入淡出并合成最终的一条完整视频。同时它也可以处理音频轨道如果未来加入配音或配乐。8. ReviewAgent审核与重制智能体这是一个“后置”智能体负责处理用户反馈。当用户在预览环节对某个部分比如某个角色的形象、某段视频的质量不满意时可以触发重制。ReviewAgent会分析用户的反馈如“这个角色的发型不对”定位到需要修改的具体智能体环节如CharacterArtistAgent并携带上下文和反馈信息重新触发该环节的生成任务实现精准修正。3.2 状态管理与实时通信WebSocket与Redis的配合如何让用户在前端实时看到“剧本写到了第三场”、“角色图生成中”、“视频正在渲染第5个镜头”这样的进度这是体验的关键。我采用了WebSocket Redis Pub/Sub的方案。前端页面加载时会与后端建立一个WebSocket长连接。当后端启动一个生成任务如生成剧本时该任务会被分配一个唯一的task_id。任务执行过程中每个智能体在完成关键步骤开始、成功、失败时都会向一个与task_id相关的Redis频道Channel发布一条状态消息。后端有一个专门的WebSocket管理器订阅了所有任务频道的消息。当它收到消息后会立即通过对应的WebSocket连接推送给前端。前端接收到消息更新UI中的进度条、日志列表或卡片状态。这样设计的好处是解耦。生成任务可能在Celery后台Worker中运行而WebSocket连接由主服务器进程处理。它们之间不需要直接通信通过Redis这个“消息中转站”即可。整个系统变得非常灵活和可扩展。4. 从零到一的部署与配置实战理论讲完了我们来点实在的。如何把这一套系统跑起来我强烈推荐使用Docker Compose进行部署它能一键搞定所有依赖。4.1 基于Docker的一键部署生产环境推荐这是最省心的方法尤其适合不熟悉Python或Node.js环境配置的伙伴。第一步准备配置文件# 克隆项目 git clone https://github.com/Xeron2000/openOii.git cd openOii # 复制后端环境变量模板 cp backend/.env.example backend/.env现在用文本编辑器打开backend/.env文件这是整个系统的中枢神经。你需要配置几个关键的API密钥。# 1. LLM 服务智能体的大脑 # 这里使用 Claude你需要一个能访问 Claude API 的终端节点和密钥。 # 可以是官方API也可以是第三方提供的兼容接口。 ANTHROPIC_BASE_URLhttps://your-claude-api-proxy.com/v1 ANTHROPIC_AUTH_TOKENsk-your-secret-token-here # 2. 图像生成服务 # 推荐使用国内可访问的魔搭ModelScope它提供了OpenAI兼容的接口。 IMAGE_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 IMAGE_API_KEYsk-your-modelscope-api-key # 3. 视频生成服务 # 选择提供商目前支持 openai (如Sora API) 或 doubao (火山引擎豆包) VIDEO_PROVIDERdoubao # 如果选择豆包需要配置其API密钥 DOUBAO_API_KEYyour-doubao-api-key # 如果选择 openai则需要配置 VIDEO_BASE_URL 和 VIDEO_API_KEY # VIDEO_BASE_URLhttps://api.openai.com/v1 # VIDEO_API_KEYsk-your-openai-api-key # 4. 数据库和RedisDocker Compose会自动设置通常无需修改 # DATABASE_URLpostgresqlasyncpg://postgres:postgresdb:5432/openoii # REDIS_URLredis://redis:6379/0实操心得关于IMAGE_BASE_URL的配置这里有个巨坑。如果你按照某些教程在宿主机本地运行了另一个图像生成服务比如另一个Stable Diffusion WebUI并在.env里写成localhost:7860那么在Docker容器内的后端服务是无法访问宿主机的localhost的。你必须使用宿主机的局域网IP或者特殊的DNS名称host.docker.internalMac/Windows的Docker Desktop支持Linux需额外配置。最省事的方案是直接使用魔搭这类在线服务。第二步启动所有服务配置好.env后一行命令即可启动所有服务数据库、Redis、后端、前端docker-compose up -d-d参数表示在后台运行。你可以用docker-compose logs -f backend来实时查看后端日志确认启动是否成功。第三步访问应用前端界面打开浏览器访问http://你的服务器IP:15173API文档访问http://你的服务器IP:18765/docs这里是完整的后端API接口文档方便开发者调试。4.2 本地开发环境搭建如果你想二次开发或深度调试需要在本地运行。后端环境准备cd backend # 使用 uv新一代的Python包管理器速度极快 uv sync # 或者使用传统的 pip pip install -e .前端环境准备cd frontend # 使用 pnpm比 npm/yarn 更节省磁盘和快速 pnpm install启动服务确保PostgreSQL和Redis已在本地运行并正确配置在.env中。在一个终端启动后端cd backend uvicorn app.main:app --reload --host 0.0.0.0 --port 18765在另一个终端启动前端cd frontend pnpm dev分别访问http://localhost:18765/docs和http://localhost:15173。4.3 核心配置项详解除了API密钥还有一些配置项深刻影响生成效果ENABLE_IMAGE_TO_IMAGE是否开启图生图模式。强烈建议在拥有强大图生图模型如SDXL时开启这是保证角色一致性的生命线。如果使用魔搭等仅支持文生图的服务则设为false。VIDEO_IMAGE_MODE当ENABLE_IMAGE_TO_VIDEO为true时生效。first_frame仅使用分镜图作为视频生成的参考。适合分镜图信息量足的场景。reference将角色立绘和分镜图拼接后作为参考。这是最优选能为视频生成模型提供最丰富、最一致的角色视觉信息。各智能体的MODEL配置在代码中可以为每个智能体指定不同的LLM模型。例如DirectorAgent和ScriptwriterAgent可能需要能力更强的模型如Claude-3.5-Sonnet而OnboardingAgent可以用稍小一点的模型以节省成本。这需要在后端代码的智能体初始化部分进行配置。5. 常见问题、排查技巧与优化经验在实际开发和使用的过程中我踩过不少坑也总结出一些让系统运行更稳定的技巧。5.1 部署与网络问题问题1后端服务启动失败报数据库连接错误。排查首先检查docker-compose.yml中PostgreSQL和Redis的服务名与.env文件中的DATABASE_URL和REDIS_URL是否匹配。在Docker Compose网络中应该使用服务名作为主机名如dbredis而不是localhost。解决确保.env文件中的配置类似DATABASE_URLpostgresqlasyncpg://postgres:postgresdb:5432/openoii REDIS_URLredis://redis:6379/0问题2图像或视频生成任务一直超时或失败。排查检查API密钥和Base URL确认.env中的配置无误并且你的账号有足够的余额或调用权限。检查网络连通性在容器内执行docker-compose exec backend curl -v https://your-image-api.com看是否能通。如果使用宿主机服务确保防火墙放行了对应端口。查看详细日志运行docker-compose logs -f backend找到任务失败时的具体错误信息。AI服务API通常会返回详细的错误码和原因。解决根据错误信息调整。如果是网络问题考虑使用更稳定的在线服务替代本地服务。如果是额度不足充值或更换账号。5.2 生成质量与一致性问题问题3生成的视频里人物形象和之前设计的角色图对不上。原因这是文生视频模型的通病仅凭文本提示词很难保持复杂的视觉一致性。解决确保开启了图生视频模式设置ENABLE_IMAGE_TO_VIDEOtrue和VIDEO_IMAGE_MODEreference。优化参考图像CharacterArtistAgent生成的角色图要足够清晰、特征鲜明。可以尝试在角色描述中加入更具体的、易于视觉化的特征词。提示词工程在VideoGeneratorAgent中除了传入参考图其文本提示词应简洁地重申角色核心特征如“一个红发扎着马尾辫、穿着机甲服的女性”与图像信息形成互补。问题4剧本逻辑混乱或分镜与剧本描述不符。原因LLM的“幻觉”或上下文理解偏差。解决强化系统提示词System Prompt在每个智能体的初始化阶段都有其专属的、详细的系统提示词用于定义其角色、职责和输出格式。仔细打磨这些提示词是提升质量最有效的方法。例如为ScriptwriterAgent的提示词增加“确保场景转换自然”、“对话符合角色性格”等约束。利用ReviewAgent进行迭代不要期望一次生成就完美。系统设计了ReviewAgent就是让你可以针对不满意的部分如“第二场戏的对话太生硬”提供反馈让它重新生成。这是一个迭代优化的过程。人工审核与编辑目前系统在关键节点如剧本生成后可以设计“人工审核”环节。在完全自动化的流程中插入一个暂停点让用户确认或微调中间结果再继续后续流程能极大提升最终成品的可控性。5.3 性能与成本优化问题5生成一个完整的短片耗时太长API调用费用高昂。优化策略缓存中间结果对于已经生成且用户满意的角色设计、场景剧本可以将其存入数据库缓存。如果用户创建新项目时使用了相似的角色或场景可以直接复用避免重复生成。模型分级调用不是所有任务都需要最强大的模型。OnboardingAgent的对话可以使用较小、较快的模型而核心的ScriptwriterAgent和DirectorAgent则使用能力更强的模型。这可以在代码中为不同智能体配置不同的LLM模型来实现。异步与队列优化确保视频生成这类耗时任务被正确地放入后台任务队列如Celery避免阻塞主请求线程。同时合理设置任务的超时时间和重试策略。预览与降级生成在创作初期可以提供“快速预览”模式例如使用更低分辨率、更短视频时长、或更经济的模型来生成草稿待用户确认方向后再使用高配置生成最终版。问题6前端画布基于tldraw在项目内容很多时变得卡顿。解决虚拟化渲染只渲染视口内的画布元素。tldraw本身性能不错但如果自定义的卡片组件过于复杂需要考虑此优化。数据分片加载不要一次性将项目的所有历史版本、所有中间数据都加载到前端。按需加载当用户查看某个具体部分时再请求相关数据。优化卡片组件确保每个卡片剧本卡、角色卡等都是纯函数组件并使用React.memo进行记忆化避免不必要的重渲染。这个项目本质上是一个AIGC应用工程化的实践。它展示了如何将多个独立的AI能力通过软件工程的方法串联成一个稳定、可用的产品。其中最大的挑战不在于某个模型的调用而在于如何设计智能体间的协作协议、如何管理复杂异步任务的状态、以及如何构建一个让用户感觉流畅自然的交互界面。