OpenMontage：面向AI视频生产的代理协同框架与工程化实践

1. 项目概述：OpenMontage不是视频剪辑软件，而是一套面向AI原生工作流的开源代理协同框架

OpenMontage这个名字乍一听容易让人联想到视频蒙太奇（montage）——毕竟“montage”在影视制作里专指镜头拼接与叙事重构。但如果你真去GitHub搜这个项目，会发现它既不处理帧率、色键，也不生成H.264编码，甚至没有一个时间轴界面。它压根就不是给剪辑师用的。OpenMontage真正的核心，是把“视频生产”这个复杂任务，拆解成一组可调度、可验证、可回溯的AI代理（agent）协作单元。它解决的不是“怎么剪”，而是“谁来决定剪哪一段、为什么剪、剪完要不要重试、失败时由谁兜底”。这背后是一整套面向AI工作流的工程化设计：任务分解策略、代理角色定义、执行上下文隔离、结果可信验证、失败熔断机制。我第一次看到它的README时，第一反应是——这根本不是个工具，而是一份AI时代内容生产的SOP说明书。

它瞄准的是当前AI视频生成领域最痛的三个断层：一是提示词工程师写完prompt扔给模型就收工，没人管后续是否跑偏；二是多个AI服务（比如先让Stable Diffusion出分镜，再让Whisper转语音，最后用ElevenLabs配音）之间靠人工粘合，中间出错就得全链路重跑；三是生成结果缺乏可审计性，你没法说清“这段配音为什么没对上口型”，因为整个流程像黑箱。OpenMontage用一套轻量级但严谨的协议，把每个环节变成可注册、可替换、可监控的代理节点。比如它内置的ScenePlannerAgent不直接画图，只负责把脚本拆成5个镜头+每个镜头的视觉关键词+时长约束；VoiceSynthAgent也不管文本怎么写，只接收结构化JSON输入，输出带时间戳的WAV片段。这种契约式设计，让团队能并行开发不同环节的代理，而不必等上游模型调通才开始写下游逻辑。它不是替代LLM，而是给LLM装上工程化的“手和脚”。

适合谁参考？如果你正在搭建内部AI内容工厂，或者想把几个开源模型串成一条稳定产线，又或者被客户反复问“你们的AI生成过程能复现吗”，那OpenMontage提供的不是代码，而是一种思维范式：把AI当作可编排的协作者，而不是不可控的魔术盒子。它不追求单点性能最强，但特别在意“当某个代理突然返回乱码时，整条流水线不会崩，且能准确定位到是哪个环节、哪次调用出了问题”。这种设计哲学，在当前动辄几十个模型混搭的AI应用中，比单纯堆参数重要得多。

2. 架构设计与核心思路：为什么放弃传统Pipeline，选择代理驱动的协同范式？

2.1 传统视频生成Pipeline的三大硬伤

我们先看一个典型AI视频工作流的原始实现方式：用Python脚本串联调用。比如先调用script_gen.py生成文案，再喂给scene_diffuser.py出图，接着用audio_gen.py配语音，最后用ffmpeg合成。这种写法看似直白，实则埋着三颗定时炸弹：

第一颗是状态耦合。scene_diffuser.py的输出格式必须严格匹配audio_gen.py的输入要求——比如前者必须输出PNG序列且命名规则为frame_001.png，后者才能正确读取。一旦某天scene_diffuser升级了，改成输出WebP格式或改了命名规则，整个流程就卡死。更糟的是，这种依赖关系散落在各处代码里，没人记得清哪个函数调用了哪个文件路径。

第二颗是错误传播。假设audio_gen.py在处理第3个镜头时因API限频失败，传统脚本要么整个重跑（浪费前两步资源），要么手动跳过该步骤（但后续合成逻辑可能依赖所有音频文件存在）。而OpenMontage的设计原则是：任何代理的失败，都不应阻塞其他代理对其他任务的处理。它把“生成第3个镜头的配音”视为独立任务，失败后自动标记为pending_retry，同时允许video_composer继续用已有的2个音频+1个占位图生成初版视频。

第三颗是责任模糊。当最终合成的视频里出现口型不对的问题，你是该怪audio_gen没生成准确时长，还是video_composer没对齐音画，抑或scene_diffuser生成的画面本身节奏就不对？传统Pipeline里，所有日志混在一起，很难追溯。OpenMontage强制每个代理在执行前后记录结构化元数据：输入哈希、输出哈希、耗时、模型版本、关键参数。这样查问题时，只需查VoiceSynthAgent对scene_003的那次调用日志，就能立刻确认是TTS模型的speed参数设成了1.8导致语速过快，而非合成环节的锅。

2.2 OpenMontage的代理协同四层架构

OpenMontage把整个系统拆成四个清晰层级，每一层都解决一个特定问题：

第一层：任务编排层（Orchestration Layer）
这是系统的“交通指挥中心”。它不处理任何业务逻辑，只做三件事：接收用户提交的VideoProductionRequest（含脚本、风格约束、时长要求），按预设策略（如SceneFirstThenAudio或ParallelAll）将大任务拆成原子子任务，并分配给对应代理；监控所有子任务状态；在超时或失败时触发重试或降级策略。关键设计是它使用声明式任务描述而非命令式调用——你告诉它“需要5个镜头，每个镜头需包含人物动作、背景、情绪标签”，而不是“先调A接口，再调B接口”。这使得编排逻辑可配置、可测试、可替换。

第二层：代理运行时（Agent Runtime）
这是每个代理的“操作系统”。它为代理提供统一的沙箱环境：标准输入/输出接口（JSON Schema）、资源配额（CPU/内存限制）、网络访问控制（默认禁外网，需显式授权）、执行超时保护。比如ScenePlannerAgent在运行时会被自动注入MAX_SCENE_COUNT=5和ALLOWED_STYLE_TAGS=["cyberpunk","watercolor"]，这些不是代码里硬编码的，而是从编排层下发的运行时参数。更重要的是，运行时强制代理输出符合AgentResultSchema的JSON，其中必须包含output_hash（对输出内容做SHA256）、execution_id（唯一追踪ID）、confidence_score（代理自评置信度）。这为后续的验证层提供了基础。

第三层：验证与仲裁层（Verification & Arbitration）
这是OpenMontage区别于其他框架的核心创新点。它不假设代理输出一定正确，而是引入第三方验证器。例如，对VoiceSynthAgent输出的WAV文件，系统会并行启动AudioValidator检查：时长是否在±0.3秒内符合要求、静音段是否超过阈值、频谱是否异常。如果验证失败，结果不会直接丢弃，而是进入仲裁队列——由ArbitratorAgent（一个轻量级LLM代理）分析原始提示、代理输出、验证报告，判断是代理能力不足（需换模型）、输入歧义（需人工澄清）还是验证器误判（调整阈值）。这种“质疑-验证-仲裁”闭环，极大提升了结果可信度。

第四层：可观测性与审计层（Observability & Audit）
所有层的操作都被强制记录到统一事件总线。每条日志包含：task_id、agent_name、execution_id、input_hash、output_hash、status、timestamp、resource_usage。这些数据实时流入时序数据库，支持两种关键查询：一是“溯源查询”——给定最终视频ID，反向查出生成它的所有代理调用链及每次输出哈希；二是“模式分析”——统计过去一周ScenePlannerAgent在处理“儿童教育类脚本”时，confidence_score低于0.7的占比，从而识别出该代理在此类任务上的能力短板。这才是真正意义上的AI工作流审计能力。

2.3 为什么选Rust作为核心语言？不只是性能

OpenMontage的底层运行时用Rust编写，这常被误解为单纯追求速度。实际上，Rust在这里解决了三个更关键的工程问题：

首先是内存安全带来的可靠性。代理运行时需要频繁解析、验证、序列化大量JSON，且必须保证即使恶意代理故意构造超长字符串或嵌套深度攻击，也不会导致运行时崩溃或内存泄露。Rust的借用检查器在编译期就堵死了这类漏洞，而Python/C++项目往往要靠运行时防护（如ulimit、cgroups）来补救，效果差且配置复杂。

其次是零成本抽象对异步调度的支持。OpenMontage的编排层需要同时管理数百个代理任务的生命周期（创建、暂停、恢复、终止）。Rust的async/await配合tokio运行时，能以极低开销实现真正的并发调度。我们做过对比测试：同样管理500个并发任务，Rust运行时平均CPU占用12%，而Node.js（V18）在同等负载下CPU飙升至89%且出现任务延迟抖动。这不是理论优势，而是直接影响产线吞吐量的实际指标。

最后是跨平台二进制分发的便利性。OpenMontage设计目标之一是让非技术用户（如内容策划）也能在本地Mac/Windows上一键部署。Rust编译出的静态二进制文件，无需安装Python环境、无需配置CUDA驱动、无需处理各种依赖冲突。用户下载一个openmontage-runtime-v0.4.2-x86_64-pc-windows-msvc.exe，双击就能启动，这大大降低了采用门槛。相比之下，用Python写的同类框架，光是解决Windows上FFmpeg路径问题就能让新手折腾半天。

3. 核心模块解析与实操要点：从零搭建一个可验证的视频生成代理

3.1 代理注册与契约定义：让每个AI组件“签劳动合同”

在OpenMontage里，添加一个新代理不是简单写个Python脚本然后扔进目录就行。它要求你先定义一份严格的“代理契约”（Agent Contract），这本质上是一个JSON Schema文件，存放在contracts/目录下。以VoiceSynthAgent为例，它的契约文件voice-synth.contract.json长这样：

{ "name": "VoiceSynthAgent", "version": "1.2.0", "description": "Converts text to speech with precise timing control", "input_schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "text": {"type": "string", "minLength": 1, "maxLength": 500}, "target_duration_ms": {"type": "integer", "minimum": 1000, "maximum": 30000}, "voice_id": {"type": "string", "enum": ["en-US-Standard-A", "en-GB-Standard-B"]}, "speed": {"type": "number", "minimum": 0.5, "maximum": 2.0, "default": 1.0} }, "required": ["text", "target_duration_ms"] }, "output_schema": { "type": "object", "properties": { "audio_wav_base64": {"type": "string"}, "actual_duration_ms": {"type": "integer"}, "word_timestamps": { "type": "array", "items": { "type": "object", "properties": { "word": {"type": "string"}, "start_ms": {"type": "integer"}, "end_ms": {"type": "integer"} } } } }, "required": ["audio_wav_base64", "actual_duration_ms"] }, "capabilities": ["tts", "timing_control"], "resources_required": {"cpu_cores": 2, "ram_gb": 4, "gpu": false} }

这个契约文件不是文档，而是运行时强制校验的依据。当你注册代理时，OpenMontage会：

1. 静态校验：检查契约JSON是否符合OpenMontage的元Schema（比如name字段不能含空格，version必须是语义化版本号）；
2. 动态校验：启动代理进程，发送一个符合input_schema的测试请求，验证其输出是否严格满足output_schema（包括字段类型、范围、必需性）；
3. 资源校验：根据resources_required启动沙箱，若代理实际内存占用超过4GB，则自动终止并标记为resource_violation。

这种契约驱动的设计，让代理开发变成了“填空题”而非“问答题”。开发者只需关注如何实现text→wav的转换逻辑，不必操心输入校验、错误包装、日志格式等重复劳动。而系统方则获得了强类型保障——你知道VoiceSynthAgent永远返回actual_duration_ms，就可以放心地把它作为VideoComposerAgent的输入参数，无需在合成环节再写一堆防御性代码。

提示：契约中的capabilities字段是编排层做智能调度的关键。比如当任务要求“必须支持中文发音”，编排层会自动过滤掉capabilities不含"chinese"的代理，而不是让不支持的代理去尝试并失败。

3.2 验证器开发实战：如何让AI自己检查AI的输出质量

OpenMontage的验证层不是摆设。我们以SceneValidator为例，说明如何开发一个真正有用的验证器。它的任务是检查ScenePlannerAgent输出的分镜描述是否符合视频叙事逻辑。一个常见问题是：AI生成的分镜顺序混乱，比如先出现“爆炸”，再出现“主角走进房间”，明显违背因果律。

SceneValidator的实现思路是三层校验：

第一层：语法校验（Syntax Check）
用正则表达式快速扫描分镜JSON，确保每个scene对象都有id、duration_ms、visual_description字段，且duration_ms是数字。这层能在毫秒级排除90%的格式错误。

第二层：语义一致性校验（Semantic Consistency）
加载一个轻量级的因果推理模型（我们用的是微调过的DistilBERT，仅12MB），对所有分镜的visual_description进行两两比较。模型输入是类似“爆炸发生后，主角走进房间”的句子，输出是0-1的因果合理性分数。如果任意相邻分镜对的分数低于0.6，即标记为causal_inconsistency。这个模型不需要联网，完全离线运行，且推理耗时控制在200ms内。

第三层：人工反馈闭环（Human-in-the-Loop）
当验证器标记出causal_inconsistency时，不直接拒绝，而是生成一个validation_report.json，包含：

• 问题分镜ID对（如scene_002→scene_003）
• 模型判定的因果分数（0.32）
• 原始描述文本（scene_002: "火球从天而降，吞噬大楼"；scene_003: "主角推开咖啡馆玻璃门，阳光洒在脸上"）
• 修正建议（"建议将scene_003调整为'主角在废墟中爬行，抬头看见燃烧的大楼'"）

这个报告会推送到内容审核员的Web界面，审核员可点击“接受建议”或“忽略”，选择后系统自动更新任务状态。这种设计让验证器不是冷冰冰的裁判，而是辅助人类决策的伙伴。

注意：验证器本身也是代理，必须注册自己的契约。SceneValidator的契约要求输入是ScenePlanJSON数组，输出是ValidationReport对象。这意味着你可以随时替换验证器——比如换成更大模型的版本，只要契约不变，整个系统无需修改。

3.3 编排策略配置：如何用YAML定义你的AI产线SOP

OpenMontage的编排逻辑不写在代码里，而是通过YAML配置文件定义。这使得业务流程变更无需重启服务。一个典型的视频生成编排配置video-production.flow.yaml如下：

name: "EducationalVideoFlow" version: "2.1" description: "For K12 science explainers, prioritizes accuracy over speed" stages: - name: "ScriptAnalysis" agent: "ScriptAnalyzerAgent" input_mapping: script_text: "$.request.script" subject_area: "$.request.metadata.subject" timeout_ms: 30000 retry_policy: max_attempts: 2 backoff_factor: 1.5 - name: "ScenePlanning" agent: "ScenePlannerAgent" input_mapping: analyzed_script: "$.stages.ScriptAnalysis.output" style_guide: "$.config.style_guides.educational" timeout_ms: 45000 # 关键：此阶段失败时，启用降级策略 fallback_strategy: type: "use_predefined_scenes" config: scene_library_path: "/data/scenes/biology_kit.json" - name: "VoiceSynthesis" agent: "VoiceSynthAgent" input_mapping: text: "$.stages.ScriptAnalysis.output.narration" target_duration_ms: "$.stages.ScenePlanning.output.total_duration_ms" # 并行执行：为每个分镜生成配音 parallelism: true batch_size: 5 - name: "VideoComposition" agent: "VideoComposerAgent" input_mapping: scenes: "$.stages.ScenePlanning.output.scenes" audio_tracks: "$.stages.VoiceSynthesis.output" # 此阶段必须等待所有前置完成 dependencies: ["ScenePlanning", "VoiceSynthesis"] validation: - validator: "SceneValidator" target_stage: "ScenePlanning" on_failure: "alert_and_pause" - validator: "AudioValidator" target_stage: "VoiceSynthesis" on_failure: "auto_retry" output_mapping: final_video_url: "$.stages.VideoComposition.output.video_url" audit_log_url: "$.system.audit_log_url"

这个配置文件体现了OpenMontage的核心思想：把AI工作流当成可配置的工业产线。你可以看到：

• fallback_strategy定义了降级方案，当ScenePlannerAgent连续失败时，自动切换到预定义的生物学科场景库，保证产线不断；
• parallelism: true让配音阶段并发执行，大幅提升效率；
• validation区块明确指定每个验证器作用于哪个阶段，以及失败时的动作（alert_and_pause表示通知管理员并暂停后续步骤，auto_retry表示自动重试）；
• input_mapping使用JSONPath语法，实现了灵活的数据流转，避免硬编码字段名。

实操中，我们曾用这套配置快速响应客户需求变更：某教育客户临时要求所有视频开头加3秒校徽动画。我们只需在VideoComposition阶段的input_mapping里增加一行school_logo_path: "$.request.metadata.school_logo"，并更新VideoComposerAgent的契约，整个变更10分钟内上线，无需改动任何代理代码。

4. 实操过程详解：从源码构建到部署一个端到端视频生成服务

4.1 环境准备与源码构建：避开Rust新手的三大坑

OpenMontage的构建过程看似简单，但Rust生态的细节容易让新手踩坑。以下是经过我们团队实测的可靠步骤（以Ubuntu 22.04为例）：

第一步：安装Rust工具链（必须用rustup）
不要用系统包管理器（如apt install rustc），因为Ubuntu仓库里的Rust版本通常滞后。正确做法是：

# 下载并安装rustup curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh source "$HOME/.cargo/env" # 验证安装 rustc --version # 应显示 >=1.75.0 cargo --version # 应显示 >=1.75.0

注意：rustup会自动设置$HOME/.cargo/bin到PATH，但新终端可能未生效。务必运行source "$HOME/.cargo/env"，否则后续cargo build会报command not found。

第二步：安装系统依赖（关键！）
OpenMontage的某些代理（如VideoComposerAgent）依赖FFmpeg和OpenCV。Rust本身不处理这些，必须手动安装：

sudo apt update sudo apt install -y ffmpeg libavcodec-dev libavformat-dev libswscale-dev \ libvpx-dev libx264-dev libx265-dev libtheora-dev \ libopencv-dev pkg-config # 验证FFmpeg ffmpeg -version # 应显示>=6.0

警告：如果跳过这步，cargo build会成功，但运行时VideoComposerAgent会因找不到libavcodec.so而崩溃，错误信息晦涩难懂。我们曾为此排查3小时。

第三步：克隆与构建（推荐release模式）
OpenMontage主仓库包含大量调试用的dev依赖，正式部署务必用release构建：

git clone https://github.com/openmontage/core.git cd core # 构建release二进制（约需5-10分钟，CPU密集） cargo build --release # 生成的二进制在target/release/openmontage ls -lh target/release/openmontage # 输出：-rwxr-xr-x 1 user user 25M ... target/release/openmontage

--release构建的二进制比debug版本小60%，且性能提升3倍以上。调试时可用cargo run，但生产环境必须用--release。

4.2 代理开发入门：用Python写第一个可注册代理

虽然核心是Rust，但OpenMontage允许用任何语言开发代理，只要遵循契约。我们以Python为例，开发一个极简的EchoAgent（用于测试）：

Step 1：创建代理目录结构

agents/ └── echo-agent/ ├── echo_agent.py └── echo_agent.contract.json

Step 2：编写契约文件
echo_agent.contract.json：

{ "name": "EchoAgent", "version": "0.1.0", "description": "Returns input unchanged, for testing", "input_schema": {"type": "string"}, "output_schema": {"type": "string"}, "capabilities": ["echo"], "resources_required": {"cpu_cores": 1, "ram_gb": 0.5} }

Step 3：实现代理逻辑
echo_agent.py：

#!/usr/bin/env python3 import sys import json def main(): # 从stdin读取输入（OpenMontage运行时会pipe JSON） try: input_data = json.load(sys.stdin) except json.JSONDecodeError: print(json.dumps({"error": "Invalid JSON input"})) return # 核心逻辑：原样返回 output = input_data # 强制添加OpenMontage要求的元数据 output.update({ "output_hash": "sha256:" + str(hash(str(input_data))), # 简化版哈希 "execution_id": "echo-" + str(hash(str(input_data)))[-8:], "confidence_score": 0.99 }) print(json.dumps(output)) if __name__ == "__main__": main()

Step 4：注册代理
启动OpenMontage时，指定代理目录：

./target/release/openmontage \ --config config.yaml \ --agents-dir ./agents/

系统会自动扫描agents/下的所有子目录，读取.contract.json，验证echo_agent.py的可执行性，并将其加入代理池。之后你就可以在编排配置中引用EchoAgent了。

实操心得：代理脚本的第一行#!/usr/bin/env python3至关重要。OpenMontage运行时通过execve调用它，如果Python路径不对，会直接报exec format error。建议用which python3确认路径，并在shebang中写死（如#!/usr/bin/python3）。

4.3 部署与监控：让AI产线像水电一样稳定

OpenMontage生产部署推荐Docker Compose方案，核心是分离关注点：

docker-compose.yml关键片段：

version: '3.8' services: openmontage-core: image: openmontage/core:v0.4.2 command: ["--config", "/app/config.yaml"] volumes: - ./config.yaml:/app/config.yaml - ./agents:/app/agents - ./storage:/app/storage ports: - "8080:8080" # API端口 - "9090:9090" # Prometheus指标端口 restart: unless-stopped prometheus: image: prom/prometheus:latest volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml depends_on: - openmontage-core grafana: image: grafana/grafana:latest ports: - "3000:3000" environment: - GF_SECURITY_ADMIN_PASSWORD=admin

监控指标设计（Prometheus）：
OpenMontage暴露了20+个关键指标，我们重点关注三个黄金信号：

1. openmontage_agent_execution_total{agent="ScenePlannerAgent",status="success"}：成功执行次数，用于计算SLA；
2. openmontage_agent_execution_duration_seconds_bucket{agent="VoiceSynthAgent",le="10"}：10秒内完成的占比，反映TTS服务健康度；
3. openmontage_validation_failure_total{validator="SceneValidator",reason="causal_inconsistency"}：因果逻辑错误次数，直接关联内容质量。

Grafana仪表盘中，我们设置了这样的告警规则：当SceneValidator的causal_inconsistency错误率连续5分钟超过5%，自动发送企业微信告警，并附上最近3次失败的validation_report.json链接。这比单纯监控CPU使用率有用得多——它直接告诉你“内容质量在下滑”，而不是“机器很忙”。

经验分享：我们最初把所有代理和验证器都放在一个容器里，结果VideoComposerAgent的GPU内存泄漏导致整个服务重启。后来严格遵循“一个容器一个关注点”原则，每个代理类型（TTS、Diffusion、Compositor）单独部署，用Kubernetes的ResourceQuota限制GPU显存，稳定性从99.2%提升到99.95%。

5. 常见问题与排查技巧实录：那些文档里不会写的血泪教训

5.1 代理注册失败的七种可能原因与定位方法

代理注册失败是新手最高频问题。OpenMontage的日志默认只输出INFO级别，很多关键错误被淹没。以下是我们的排查速查表：

血泪教训：我们曾遇到一个代理注册成功但始终不被调用的问题，折腾两天才发现是契约文件名错了——voice-synth.contract.json写成了voice_synth.contract.json（下划线）。OpenMontage只扫描*.contract.json，而_不匹配*。这种低级错误，日志里没有任何提示，只能靠ls agents/肉眼排查。

5.2 验证器误报的典型场景与调优技巧

验证器不是万能的，过度严格的验证会导致正常结果被拒。以下是三个真实案例：

案例1：AudioValidator误判静音
现象：VoiceSynthAgent生成的配音开头有0.2秒静音（TTS模型固有特性），但验证器阈值设为0.1秒，导致大量失败。
解决方案：在config.yaml中调整验证器参数：

validators: AudioValidator: max_leading_silence_ms: 250 # 从100提升到250 min_speech_energy: 0.05 # 降低能量阈值

案例2：SceneValidator因果分数波动
现象：同一组分镜，白天验证分数0.72，晚上降到0.58，原因是模型加载时GPU显存碎片化影响精度。
解决方案：为验证器独占GPU资源，在docker-compose.yml中：

services: scene-validator: deploy: resources: reservations: devices: - driver: nvidia count: 1 capabilities: [gpu]

案例3：人工审核积压
现象：SceneValidator每天产生200+条causal_inconsistency告警，审核员不堪重负。
解决方案：引入置信度过滤。在编排配置中加：

validation: - validator: "SceneValidator" target_stage: "ScenePlanning" # 只对低置信度分镜触发人工审核 filter: "input.confidence_score < 0.8" on_failure: "alert_and_pause"

实操技巧：验证器的filter字段支持JMESPath表达式，可以写非常复杂的条件，比如"input.duration_ms > 5000 && input.visual_description contains 'explosion'"，实现精准干预。

5.3 性能瓶颈诊断：从日志到火焰图的完整链路

当视频生成耗时突然翻倍，不要盲目加机器。OpenMontage提供了完整的性能分析链路：

第一步：查看OpenMontage自身指标
访问http://localhost:8080/metrics，搜索openmontage_agent_execution_duration_seconds，看哪个代理的P95耗时异常升高。如果是VideoComposerAgent，说明瓶颈在合成环节。

第二步：进入代理容器抓取火焰图

# 进入VideoComposerAgent容器 docker exec -it openmontage-video-composer bash # 安装perf（需root权限） apt update && apt install -y linux-tools-common linux-tools-$(uname -r) # 抓取30秒CPU火焰图 perf record -g -F 99 -p $(pgrep -f "video_composer.py") -- sleep 30 perf script > perf-output.txt

第三步：用FlameGraph可视化
将perf-output.txt上传到 FlameGraph在线工具 ，你会看到类似这样的调用栈：

ffmpeg [unknown] ├─ encode_frame │ ├─ avcodec_encode_video2 │ │ └─ x264_encoder_encode │ │ └─ x264_slice_write │ └─ write_frame └─ read_frame └─ av_read_frame

如果x264_slice_write占80% CPU，说明是编码器瓶颈；如果av_read_frame占高，说明是IO读取慢（可能是存储在机械硬盘上）。

第四步：针对性优化

• 编码瓶颈：改用更快的preset（--preset fast），或换用svt-av1编码器；
• IO瓶颈：将/app/storage挂载到SSD，或启用FFmpeg的-threads 0自动线程数。

独家技巧：我们在VideoComposerAgent里加了一个--profile参数，开启后会自动生成/tmp/composition-profile.json，包含每个环节耗时（读帧、编码、写帧），比perf更直观。这个功能在官方文档里没提，但源码里有开关。

6. 扩展可能性与实践边界：OpenMontage能做什么，不能做什么

6.1 真实落地场景：从教育视频到电商广告的迁移实践

OpenMontage已在三个垂直领域落地，证明其架构的普适性：

教育领域（某在线教育平台）
需求：每天生成2000+条1分钟科学知识点短视频，要求字幕准确率>99.5%，画面与讲解严格同步。
实现：用ScriptAnalyzerAgent提取知识点关键词，ScenePlannerAgent