AI 视频生成 on 方糖猫Blog

方糖猫 AI 视频平台：ReAct Agent 任务规划实战

Tue, 23 Jun 2026 10:00:00 +0800

方糖猫 AI 视频平台：ReAct Agent 任务规划实战

在方糖猫项目中，我们面对的是这样一个问题：用户输入一段文案，系统需要在几分钟内自动完成素材检索、脚本生成、视频渲染和后期处理，输出一条可发布的短视频。这个链路很长、步骤之间依赖复杂、失败场景多。我们最终选择用 ReAct Agent 来编排整个生成流程。这篇文章会还原当时的设计思路、关键实现和踩过的坑。

一、业务场景：为什么不是简单流水线？

短视频自动生成的典型流程大致如下：

flowchart LR
    A["文案输入"] --> B["素材检索"] --> C["故事板生成"] --> D["配音/字幕"] --> E["视频渲染"] --> F["FFmpeg 后处理"] --> G["成片"]

最直觉的做法是用一个硬编码的工作流引擎按顺序执行每个步骤。但我们很快发现几个问题：

步骤之间的依赖不是固定的。比如某些文案不需要 B-roll，某些素材缺失时需要回退到文字卡片，某些场景需要先合成配音再决定画面节奏。
失败恢复成本高。渲染失败后要重试还是跳过？素材检索为空时是终止还是换关键词重搜？每个决策点都需要上下文。
未来要支持更多视频类型。口播、科普、剧情、产品介绍，每种类型的工作流差异很大，硬编码会迅速失控。

所以我们需要一个能够根据输入动态决策、具备工具调用能力、失败后能自主重试或降级的编排机制。ReAct Agent 是其中一个可行方案。

二、ReAct Agent 的核心设计

2.1 任务拆解

我们把整个生成流程拆成 6 个核心步骤，每个步骤对应一个 Agent 任务：

任务	职责	关键输出
`AnalyzeIntent`	理解文案意图、视频类型、风格要求	意图标签、关键词、情绪基调
`RetrieveMaterials`	根据关键词检索本地素材库	Top-K 图片/视频/文案片段
`GenerateStoryboard`	规划每帧画面、配音、视觉元素	故事板 JSON
`SynthesizeSpeech`	调用 TTS 生成配音	音频文件 URL
`RenderVideo`	调用 Remotion 渲染视频	视频文件 URL
`PostProcess`	FFmpeg 后处理：转码、压缩、加字幕	成片 URL

每个任务都是一个 Tool，Agent 通过 Reasoning 决定调用哪个 Tool、以什么参数调用、如何处理返回结果。

2.2 Agent Loop 设计

我们的 Agent 遵循典型的 ReAct 循环：

flowchart LR
    O["观察（Observation）"] --> T["思考（Thought）"] --> A["行动（Action）"] --> O

具体实现中，我把每次循环抽象为三个动作：

Plan：根据当前状态生成下一步计划
Act：调用 Tool 执行计划
Reflect：检查 Tool 输出，决定继续、重试还是终止

一个简化版的状态机如下：

flowchart TD
    Start["Start"] --> AnalyzeIntent["AnalyzeIntent"]
    AnalyzeIntent --> RetrieveMaterials["RetrieveMaterials"]
    RetrieveMaterials -- "素材不足" --> Fallback["FallbackToTextCards"]
    Fallback --> GenerateStoryboard["GenerateStoryboard"]
    RetrieveMaterials --> GenerateStoryboard
    GenerateStoryboard --> SynthesizeSpeech["SynthesizeSpeech"]
    SynthesizeSpeech -- "TTS 失败" --> RetryAudio["Retry / SkipAudio"]
    SynthesizeSpeech --> RenderVideo["RenderVideo"]
    RenderVideo -- "渲染失败" --> RetryRender["Retry / ReduceResolution"]
    RenderVideo --> PostProcess["PostProcess"]
    PostProcess --> EndNode["End"]

三、关键实现

3.1 Tool 注册与统一接口

所有 Tool 都实现统一的 Tool 接口：

from abc import ABC, abstractmethod
from typing import Any, Dict

class Tool(ABC):
    @property
    @abstractmethod
    def name(self) -> str:
        pass

    @property
    @abstractmethod
    def description(self) -> str:
        pass

    @abstractmethod
    def run(self, params: Dict[str, Any], context: Dict[str, Any]) -> Dict[str, Any]:
        """
        params: LLM 生成的调用参数
        context: 当前任务上下文，包含前面步骤的输出
        """
        pass

所有 Tool 注册到一个 Registry 中，Agent 根据 LLM 的输出动态调用：

class ToolRegistry:
    def __init__(self):
        self._tools: Dict[str, Tool] = {}

    def register(self, tool: Tool):
        self._tools[tool.name] = tool

    def get(self, name: str) -> Tool:
        return self._tools[name]

这种设计的好处是：新增一种视频类型或新增一个处理步骤，只需要新增一个 Tool，Agent 的编排逻辑不需要改动。

3.2 Agent Loop 核心代码

class ReActAgent:
    def __init__(self, llm_client, tool_registry, max_steps=15):
        self.llm = llm_client
        self.tools = tool_registry
        self.max_steps = max_steps

    def run(self, user_input: str) -> Dict[str, Any]:
        context = {
            "user_input": user_input,
            "history": [],
            "status": "running"
        }

        for step in range(self.max_steps):
            # 1. 让 LLM 根据当前状态决定下一步
            prompt = self._build_prompt(context)
            action = self.llm.generate(prompt)

            # 2. 解析 LLM 输出：Tool 名称 + 参数
            tool_name, params = self._parse_action(action)

            if tool_name == "Finish":
                context["status"] = "completed"
                break

            # 3. 执行 Tool
            tool = self.tools.get(tool_name)
            try:
                result = tool.run(params, context)
                result["success"] = True
            except Exception as e:
                result = {"success": False, "error": str(e)}

            # 4. 更新上下文
            context["history"].append({
                "step": step,
                "tool": tool_name,
                "params": params,
                "result": result
            })

            # 5. 失败时触发重试或降级
            if not result["success"]:
                fallback = self._decide_fallback(tool_name, result)
                if fallback:
                    context["history"].append({"fallback": fallback})

        return context

3.3 Prompt 设计

Prompt 的核心不是让 LLM「自由发挥」，而是把它限定在一个结构化的决策空间里：

你是一名短视频生成助手。当前任务状态如下：

- 用户输入：{user_input}
- 已执行步骤：{history}
- 可用工具：
  1. AnalyzeIntent: 分析文案意图
  2. RetrieveMaterials: 检索素材
  3. GenerateStoryboard: 生成故事板
  4. SynthesizeSpeech: 合成配音
  5. RenderVideo: 渲染视频
  6. PostProcess: 后处理
  7. Finish: 任务完成

请输出下一步操作，格式如下：

Thought: <你的推理过程>
Action: <Tool 名称>
ActionInput: <JSON 格式的参数>

为了让输出更稳定，我们做了几层约束：

JSON Schema 约束：要求 LLM 输出固定字段
Few-shot 示例：在 Prompt 里放 2-3 个正确示例
Pydantic 校验 + 重试：后端严格校验输出格式，失败自动重试

四、踩过的坑

4.1 LLM 输出格式不稳定

最早用纯 Prompt 约束时，LLM 有时输出 Action: GenerateStoryboard，有时输出 下一步：生成故事板，导致解析失败率很高。

解决方案：

引入 JSON Schema，明确要求输出 JSON
后端用 Pydantic 校验，失败自动重试 3 次
重试时 temperature 从 0.7 降到 0.2，让输出更稳定

效果：结构解析成功率从约 75% 提升到 98% 以上。

4.2 任务卡住没有超时机制

早期 Agent 会无限循环，比如某一步失败后 LLM 反复决定重试同一个 Tool。

解决方案：

设置 max_steps=15
每个 Tool 设置独立超时
同一 Tool 连续失败 2 次后强制降级或人工介入

4.3 上下文过长导致成本飙升

随着步骤推进，history 越来越长，LLM Token 消耗快速增长。

解决方案：

对 history 做摘要，只保留关键结果
每个 Tool 输出只保留必要字段
长视频场景下采用「分段生成 + 本地组装」策略

五、当前效果与待优化方向

目前这套 Agent 编排已经支撑方糖猫平台的核心生成链路，能够覆盖常见的口播、科普类视频生成场景。

已验证的收益：

新增一种视频类型的支持成本明显降低，从改动整个工作流变成新增一个 Tool
失败恢复路径清晰，常见异常无需人工介入
渲染失败、素材缺失等场景可以自动降级，任务完成率稳定在较高水平

还在探索的方向：

更细粒度的 Agent 评估：不是只看任务是否完成，还要看成片质量
多 Agent 协作：把创意策划、素材审核、质量评估拆成独立 Agent
成本优化：不同步骤路由到不同模型，复杂推理用大模型，简单调用用小模型

六、什么场景适合 ReAct，什么不适合

适合：

步骤之间有复杂依赖，需要动态决策
失败场景多，需要自动重试或降级
流程经常变化，硬编码维护成本高

不适合：

步骤固定、成功率高、性能要求极高的场景，传统工作流更合适
对延迟极度敏感的场景，Agent 的多次 LLM 调用会显著增加耗时

七、总结

ReAct Agent 不是银弹，但它确实帮我们解决了一个核心问题：如何把复杂的 AI 视频生成流程，从「硬编码脚本」变成「可编排、可观测、可恢复」的工程系统。

关键经验：

Tool 接口要统一，新增能力时不要改动 Agent 核心逻辑
Prompt 输出要做 Schema 约束和后端校验，否则线上会不稳定
失败处理、超时、降级必须一开始就想清楚
Agent 的评估指标不能只看「跑通」，要看「生成质量」和「成本」

后续我会继续分享 RAG 素材库、多 Worker 分布式渲染、以及 Whisper + Remotion 渲染链路的实践，欢迎关注。

如果你也在做 AI Agent 相关的项目，欢迎在评论区交流。

RAG 本地素材库：从 Embedding 选型到召回调优

Tue, 10 Feb 2026 11:00:00 +0800

RAG 本地素材库：从 Embedding 选型到召回调优

在我开发的方糖猫 AI 视频平台中，一个核心能力是「根据文案自动匹配视频素材」。用户的文案可能是「讲一个关于坚持的故事」，系统需要从本地素材库中找到最契合的画面。我们最终用 RAG（检索增强生成） 的思路搭建了本地素材库。这篇文章会完整复盘从 Embedding 选型到召回调优的全过程。

一、业务背景：为什么需要 RAG？

短视频生成平台里的素材通常有几类：

图片素材：背景图、人物图、概念图
视频片段：B-roll、转场、动画
文案片段：金句、案例、开场白

早期我们用关键词标签做检索，很快就发现几个问题：

标签覆盖不全。一个海边日落镜头，可能被标注为「海」「日落」「风景」「旅行」，但用户文案写的是「人生低谷后的曙光」，关键词完全对不上。
标签质量参差不齐。不同运营人员打的标签不一致，导致召回结果波动大。
无法跨模态匹配。图片素材没有文字描述，靠文件名搜索基本不可用。

RAG 的思路是：用 Embedding 把素材和查询都映射到同一向量空间，通过语义相似度做召回。这样即使关键词不同，只要语义接近，就能被检索出来。

二、系统设计

整个 RAG 素材库分为三个核心环节：

flowchart LR
    subgraph S1["素材入库"]
        A1["原始素材"] --> A2["内容提取"] --> A3["Embedding"] --> A4["ChromaDB"]
    end
    subgraph S2["查询召回"]
        B1["用户文案"] --> B2["Embedding"] --> B3["Top-K 检索"] --> B4["重排"] --> B5["返回结果"]
    end
    subgraph S3["持续更新"]
        C1["新增素材"] --> C2["增量 Embedding"] --> C3["索引更新"]
    end

2.1 素材入库流程

flowchart LR
    A["图片/视频"] --> B["抽帧/缩略图"] --> C["视觉特征提取（CLIP/ResNet）"] --> D["文本描述生成"] --> E["Embedding"] --> F["写入 ChromaDB"]
    G["文本片段"] --> H["清洗/分块"] --> I["Embedding"] --> F

对于图片和视频，我们会：

视频抽帧为关键帧
用多模态模型生成一句话描述
同时保存原始文件路径、文件类型、使用次数等元数据

2.2 查询召回流程

# 简化版召回流程
def retrieve_materials(query: str, top_k: int = 10):
    # 1. 查询向量化
    query_embedding = embedding_model.encode(query)

    # 2. 向量库初筛
    candidates = chroma_collection.query(
        query_embeddings=[query_embedding],
        n_results=top_k * 3,  # 多召回一些，留给重排
        where={"status": "active"}
    )

    # 3. 重排序
    ranked = reranker.rerank(query, candidates)

    # 4. 返回 Top-K
    return ranked[:top_k]

三、Embedding 选型实测

Embedding 模型的选择直接决定召回质量。我们测试了以下几种：

模型	类型	维度	中文语义	多模态	延迟	成本
text-embedding-ada-002	文本	1536	中等	否	快	低
text-embedding-3-small	文本	1536	较好	否	快	低
BGE-M3	文本	1024	优秀	否	中等	本地
OpenAI CLIP	多模态	512	一般	是	中等	中等
中文 CLIP	多模态	512	较好	是	中等	本地

3.1 文本 Embedding 选型

因为我们的查询主要是中文文案，最终选择了 BGE-M3，原因：

中文语义理解能力明显优于 OpenAI 的 Embedding
支持本地部署，无调用成本
向量维度 1024，检索速度和存储成本可接受

3.2 多模态 Embedding 选型

对于图片/视频素材，CLIP 系列可以把视觉内容和文本映射到同一空间。但实测发现：

通用 CLIP 对中文概念的支持较弱
视频场景下，关键帧的质量直接影响召回效果

最终方案：

关键帧用 中文 CLIP 生成视觉 Embedding
同时用图像描述模型生成一句话中文描述，再用 BGE-M3 生成文本 Embedding
向量库中同时存储两种 Embedding，查询时分别召回再融合

四、向量库设计

我们选用 ChromaDB 作为向量存储，主要考虑：

部署简单，适合小团队
支持元数据过滤（按项目、类型、状态筛选）
Python 生态集成好
支持内存模式和持久化模式，开发方便

4.1 Collection 划分

# 按素材类型分 Collection
image_collection = chroma_client.get_or_create_collection("materials_image")
video_collection = chroma_client.get_or_create_collection("materials_video")
text_collection = chroma_client.get_or_create_collection("materials_text")

分 Collection 的好处是查询更聚焦，也方便针对不同类型的素材调优。

4.2 文档结构设计

documents = [{
    "id": "img_001",
    "embedding": image_embedding,
    "metadata": {
        "type": "image",
        "project_id": "proj_123",
        "tags": ["海边", "日落", "风景"],
        "file_url": "oss://ftmao/materials/img_001.jpg",
        "width": 1920,
        "height": 1080,
        "status": "active",
        "usage_count": 12
    },
    "document": "海边日落，宁静的风景画面"  # 用于可读性和调试
}]

五、召回调优实战

5.1 评测数据集构建

召回调优的前提是有评测数据。我们标注了 200 条查询-素材对：

{
  "query": "人生低谷后重新出发",
  "relevant": ["img_001", "img_015", "vid_008"],
  "irrelevant": ["img_099", "vid_045"]
}

评测指标：

Recall@K：相关素材在 Top-K 中的占比
Precision@K：Top-K 中相关素材的占比
MRR：第一个相关素材的平均排名倒数

5.2 Embedding 调优

通过对比实验，我们发现：

方案	Recall@10	Precision@10	MRR
关键词标签	42%	35%	0.18
BGE-M3 文本 Embedding	68%	54%	0.31
BGE-M3 + 中文 CLIP 融合	79%	63%	0.40
+ 重排序模型	86%	71%	0.48

5.3 查询改写

用户的原始查询往往比较抽象，比如「做一个励志视频」。直接用这个查询做向量检索，召回结果会比较散。

我们的做法是让 LLM 先对查询做改写和扩展：

输入：做一个励志视频
输出：
- 核心语义：励志、奋斗、坚持不懈
- 扩展查询：逆境中成长、永不放弃、追逐梦想、突破自我
- 情绪基调：激昂、温暖、希望

然后用扩展后的多个查询分别检索，最后合并结果。这个策略让 Recall@10 提升了约 8%。

5.4 重排序模型

初筛召回 30 个候选后，用轻量级重排序模型做二次排序。我们用的是 bge-reranker-base，原因：

模型小，CPU 推理足够快
对中文语义匹配效果好
可以 fine-tune 适应平台特定素材

六、工程化细节

6.1 索引更新策略

素材库是动态变化的，每天都有新增、删除、状态变更。我们采用：

增量更新：新增素材立即 Embedding 入库
批量补偿：每天晚上全量校验一次，修复漏入/错入
软删除：素材状态改为 inactive，不立即物理删除，便于恢复和审计

6.2 缓存与去重

热门查询的 Embedding 结果会被缓存到 Redis，缓存 key 是查询文本的 hash。同时 TTS 结果也按文案 hash 去重，避免重复调用。

def get_cached_or_compute(query: str):
    key = f"rag:query:{hashlib.md5(query.encode()).hexdigest()}"
    cached = redis.get(key)
    if cached:
        return json.loads(cached)

    result = retrieve_materials(query)
    redis.setex(key, 3600, json.dumps(result))  # 缓存 1 小时
    return result

6.3 多项目隔离

同一个平台可能服务多个创作者或项目，不同项目的素材库需要隔离。我们通过 project_id 元数据过滤实现：

results = collection.query(
    query_embeddings=[embedding],
    n_results=10,
    where={"project_id": "proj_123", "status": "active"}
)

七、踩过的坑

7.1 向量维度不一致

早期我们同时用了 OpenAI Embedding（1536 维）和 BGE-M3（1024 维），混在一个 Collection 里，结果查询时报维度错误。

解决：严格按模型维度分 Collection，每个 Collection 只存同一模型产出的向量。

7.2 关键帧质量影响召回

视频素材如果关键帧选得不好（比如黑屏、转场瞬间），CLIP 生成的 Embedding 会偏离视频真实内容。

解决：

用场景检测算法选取稳定画面
一个视频保存多个关键帧，查询时合并召回
人工抽检低质量素材

7.3 查询过短导致语义漂移

用户查询只有一个词，比如「奋斗」，召回结果可能包含大量不相关但语义宽泛的素材。

解决：

短查询自动扩展为完整句子
提高重排序模型的权重
对短查询增加元数据过滤

八、当前效果与下一步

目前这套 RAG 素材库已经支撑方糖猫平台的核心素材检索能力，覆盖了图片、视频片段、文案片段三类素材。

已验证的收益：

素材召回质量明显高于关键词检索
新素材无需人工打标签即可被检索到
跨项目复用素材变得可行

下一步计划：

引入用户反馈数据，做在线学习优化
针对视频内容做更细粒度的时序检索
探索多模态大模型直接做端到端素材匹配

九、总结

RAG 不只是 LLM 应用的一个热门概念，对于内容生成类平台来说，它是连接用户意图和内容资产的关键基础设施。

几个关键经验：

Embedding 选型要以业务语言为主。中文场景不要迷信 OpenAI，BGE 系列性价比更高。
一定要有评测数据集。没有数据就没有优化方向。
召回 pipeline 通常是多阶段的：初筛 + 重排 + 业务规则过滤。
工程化比算法更重要。索引更新、缓存、隔离、监控，这些决定系统能不能长期稳定运行。

如果你也在做 RAG 相关的项目，欢迎交流 Embedding 选型和召回调优的经验。