Inicio Explorar Ayuda
Iniciar sesión
caojunfei
/
audio_codebuddy
1
0
Fork 0
Archivos Incidencias 0 Pull Requests 0 Wiki
Árbol: 34a9840639
Ramas Etiquetas
audio_codebuddy
/
.qoder
/
repowiki
/
zh
/
content
/
项目概述
/
核心功能特性
/
AI内容生成
/
批量生成系统.md

批量生成系统.md 25 KB
Histórico Raw

批量生成系统

本文引用的文件

  • server/src/modules/book-generator/book-generator.controller.ts
  • server/src/modules/book-generator/book-generator.service.ts
  • server/src/modules/book-generator/book-queue.processor.ts
  • server/src/services/queue.service.ts
  • server/src/services/memory-queue.ts
  • server/src/modules/book-generator/fault-tolerance.ts
  • server/src/modules/book-generator/stage-manager.ts
  • server/src/modules/book-generator/graph.ts
  • server/src/modules/book-generator/strategies/sequential.strategy.ts
  • server/src/modules/book-generator/strategies/one-step-outline.strategy.ts
  • server/src/modules/book-generator/strategies/per-chapter.strategy.ts
  • server/src/modules/book-generator/book-generator.types.ts
  • server/src/modules/book-generator/book-generator-optimizations.ts

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录：API 接口文档

简介

本技术文档面向“批量生成系统”，聚焦于书籍生成的端到端流程：从任务创建、队列调度与执行监控，到生成步骤的组合与执行策略、状态跟踪与容错恢复、以及性能优化与 API 使用说明。系统采用“线性步骤编排 + LangGraph 工作流”的双层架构，既保证生成步骤的可控性，又通过工作流图实现复杂节点的条件流转与并行化。

项目结构

批量生成系统主要分布在以下模块与服务中：

  • 控制器层：提供批量生成、取消与状态查询的 HTTP 接口
  • 编排层：负责生成步骤的顺序执行、进度推送与取消检查
  • 队列层：基于 Bull/Redis 的任务队列与内存队列回退
  • 容错层：AI 调用重试、节点超时、进度监控与自动恢复
  • 状态层：章节/书籍阶段管理与安全状态迁移

  • 工作流层：LangGraph 图结构与多种生成策略

    graph TB
subgraph "控制器层"
C1["book-generator.controller.ts<br/>批量生成/取消/状态接口"]
end
subgraph "编排层"
S1["book-generator.service.ts<br/>BatchGenerationOrchestrator<br/>步骤编排与进度推送"]
end
subgraph "队列层"
Q1["queue.service.ts<br/>Bull 队列封装"]
Q2["memory-queue.ts<br/>内存队列回退"]
QP["book-queue.processor.ts<br/>书籍生成队列处理器"]
end
subgraph "容错层"
F1["fault-tolerance.ts<br/>重试/超时/监控/恢复"]
end
subgraph "状态层"
SM["stage-manager.ts<br/>章节/书籍阶段迁移"]
end
subgraph "工作流层"
G1["graph.ts<br/>LangGraph 状态定义"]
ST1["sequential.strategy.ts"]
ST2["one-step-outline.strategy.ts"]
ST3["per-chapter.strategy.ts"]
end
C1 --> S1
S1 --> QP
QP --> Q1
QP --> Q2
S1 --> F1
S1 --> SM
QP --> G1
G1 --> ST1
G1 --> ST2
G1 --> ST3

图表来源

  • server/src/modules/book-generator/book-generator.controller.ts:1-199
  • server/src/modules/book-generator/book-generator.service.ts:1-549
  • server/src/modules/book-generator/book-queue.processor.ts:1-124
  • server/src/services/queue.service.ts:1-266
  • server/src/services/memory-queue.ts:1-99
  • server/src/modules/book-generator/fault-tolerance.ts:1-387
  • server/src/modules/book-generator/stage-manager.ts:1-202
  • server/src/modules/book-generator/graph.ts:1-83
  • server/src/modules/book-generator/strategies/sequential.strategy.ts:1-60
  • server/src/modules/book-generator/strategies/one-step-outline.strategy.ts:1-56
  • server/src/modules/book-generator/strategies/per-chapter.strategy.ts:1-56

章节来源

  • server/src/modules/book-generator/book-generator.controller.ts:1-199
  • server/src/modules/book-generator/book-generator.service.ts:1-549
  • server/src/modules/book-generator/book-queue.processor.ts:1-124
  • server/src/services/queue.service.ts:1-266
  • server/src/services/memory-queue.ts:1-99
  • server/src/modules/book-generator/fault-tolerance.ts:1-387
  • server/src/modules/book-generator/stage-manager.ts:1-202
  • server/src/modules/book-generator/graph.ts:1-83
  • server/src/modules/book-generator/strategies/sequential.strategy.ts:1-60
  • server/src/modules/book-generator/strategies/one-step-outline.strategy.ts:1-56
  • server/src/modules/book-generator/strategies/per-chapter.strategy.ts:1-56

核心组件

  • 批量生成编排器：负责按顺序执行生成步骤，推送进度，检查取消信号，并在完成后清理标志
  • 书籍生成队列处理器：使用 Bull/Redis 或内存队列处理书籍生成任务，支持并发控制与事件监听
  • 队列服务：封装 Bull 队列，提供任务状态查询与进度更新能力
  • 容错层：提供 AI 调用重试、节点超时控制、进度监控与自动恢复
  • 阶段管理器：确保章节/书籍状态的线性迁移与资源清理
  • 工作流与策略：LangGraph 状态图与多种生成策略（串行、一步大纲+并行内容、逐章内聚）

章节来源

  • server/src/modules/book-generator/book-generator.service.ts:45-143
  • server/src/modules/book-generator/book-queue.processor.ts:16-83
  • server/src/services/queue.service.ts:48-266
  • server/src/modules/book-generator/fault-tolerance.ts:68-180
  • server/src/modules/book-generator/stage-manager.ts:100-198
  • server/src/modules/book-generator/graph.ts:23-82

架构总览

系统采用“控制器-编排-队列-工作流-容错-状态”分层架构：

  • 控制器接收请求，创建批量任务并异步执行
  • 编排器驱动生成步骤，向前端推送进度
  • 队列层负责任务排队与并发控制；当 Redis 不可用时回退到内存队列
  • 工作流层通过 LangGraph 管理复杂节点与条件边
  • 容错层保障稳定性，包括重试、超时与自动恢复

  • 阶段管理器确保状态迁移合法与资源清理

    sequenceDiagram
participant Client as "客户端"
participant Ctrl as "控制器<br/>book-generator.controller.ts"
participant Orchestrator as "编排器<br/>book-generator.service.ts"
participant Queue as "队列处理器<br/>book-queue.processor.ts"
participant WS as "WebSocket<br/>进度推送"
participant Store as "状态/存储<br/>stage-manager.ts"
Client->>Ctrl : POST /books/ : id/batch-generate
Ctrl->>Orchestrator : 创建任务并启动后台执行
Orchestrator->>WS : 推送步骤进度
Orchestrator->>Queue : 添加书籍生成任务
Queue-->>Queue : 并发处理任务
Queue->>Store : 更新书籍/章节阶段
Queue-->>Orchestrator : 任务完成/失败事件
Orchestrator->>WS : 推送完成/异常
Ctrl-->>Client : 返回任务状态

图表来源

  • server/src/modules/book-generator/book-generator.controller.ts:24-119
  • server/src/modules/book-generator/book-generator.service.ts:77-143
  • server/src/modules/book-generator/book-queue.processor.ts:16-83
  • server/src/modules/book-generator/stage-manager.ts:158-198

详细组件分析

批量生成编排器（BatchGenerationOrchestrator）

  • 职责：顺序执行生成步骤（内容、音频、合并音频、视频、合并视频），推送进度，检查取消，处理异常

  • 关键点：

    • 步骤验证与默认执行顺序
    • 每步进度计算与推送
    • 取消检查与清理
    • 轮询等待子任务完成（如内容/音频/视频生成）

    • 完成后更新书籍进度

      flowchart TD
Start(["开始执行"]) --> Init["初始化与校验"]
Init --> StepLoop{"遍历生成步骤"}
StepLoop --> |内容生成| GenContent["生成内容LangGraph<br/>轮询等待完成"]
StepLoop --> |音频生成| GenAudio["批量生成叶节点音频<br/>轮询等待完成"]
StepLoop --> |合并音频| MergeAudio["按父节点合并音频<br/>更新章节音频URL"]
StepLoop --> |视频生成| GenVideo["为有音频的叶节点生成视频<br/>轮询等待完成"]
StepLoop --> |合并视频| MergeVideo["按父节点合并/简化视频处理"]
GenContent --> Next["推进到下一步"]
GenAudio --> Next
MergeAudio --> Next
GenVideo --> Next
MergeVideo --> Next
Next --> StepLoop
StepLoop --> |完成| Finish["更新书籍进度=100<br/>清理取消标志"]
Finish --> End(["结束"])

图表来源

  • server/src/modules/book-generator/book-generator.service.ts:77-536

章节来源

  • server/src/modules/book-generator/book-generator.service.ts:45-143
  • server/src/modules/book-generator/book-generator.service.ts:149-536

书籍生成队列处理器（Bull/内存队列）

  • 职责：处理书籍生成任务，设置初始状态，捕获完成/失败事件，更新书籍状态
  • 并发控制：Redis 队列最大并发 3；内存队列同构实现
  • 回退机制：当 Redis 不可用时自动切换到内存队列

  • 恢复机制：启动时扫描数据库中处于生成中的书籍并重新入队

    sequenceDiagram
participant QS as "队列服务<br/>queue.service.ts"
participant MQ as "内存队列<br/>memory-queue.ts"
participant Proc as "处理器<br/>book-queue.processor.ts"
participant LG as "LangGraph生成器"
participant DB as "数据库/存储"
QS->>Proc : getQueue(BOOK_GENERATION)
alt Redis可用
Proc->>QS : redisQueue.process(3, handler)
else Redis不可用
Proc->>MQ : memoryQueue.process(3, handler)
end
Proc->>DB : 更新书籍状态为 outling
Proc->>LG : generate(bookId, topic, scale, level)
LG-->>Proc : 完成/异常
Proc->>DB : 成功则标记完成；失败则标记失败

图表来源

  • server/src/modules/book-generator/book-queue.processor.ts:48-83
  • server/src/services/queue.service.ts:88-133
  • server/src/services/memory-queue.ts:48-99

章节来源

  • server/src/modules/book-generator/book-queue.processor.ts:16-124
  • server/src/services/queue.service.ts:48-133
  • server/src/services/memory-queue.ts:17-99

队列服务（Bull 封装）

  • 职责：提供队列实例、任务状态查询、进度更新回调注册
  • 设计原则：队列只负责排队与并发控制，失败重试、超时管理交由上层业务与容错层处理
  • 状态映射：waiting/active/completed/failed/delayed 映射到统一 TaskStatus

章节来源

  • server/src/services/queue.service.ts:48-266

容错层（重试/超时/监控/恢复）

  • AI 调用重试：最多 3 次，指数退避，失败记录与用户通知
  • 节点超时：按节点类型配置超时阈值，超时后通知并触发恢复
  • 进度监控：超过阈值无进度更新时发出告警，必要时自动恢复

  • 自动恢复：重新入队并通知用户

    flowchart TD
A["开始节点执行"] --> Timeout["设置超时定时器"]
Timeout --> Exec["执行节点函数"]
Exec --> Ok{"执行成功？"}
Ok --> |是| NotifyOk["通知用户完成"]
Ok --> |否| Retry["AI重试指数退避"]
Retry --> MaxRetry{"超过最大重试？"}
MaxRetry --> |是| MarkFail["标记失败并记录错误"]
MaxRetry --> |否| Exec
NotifyOk --> Done(["结束"])
MarkFail --> Done

图表来源

  • server/src/modules/book-generator/fault-tolerance.ts:68-180

章节来源

  • server/src/modules/book-generator/fault-tolerance.ts:17-180
  • server/src/modules/book-generator/fault-tolerance.ts:188-323

阶段管理器（线性阶段与安全迁移）

  • 章节阶段：从 idle 到 outline_completed → content_generating → content_completed → audio_generating → audio_completed → video_generating → video_completed → failed
  • 安全迁移：验证转移矩阵、乐观锁更新、回退时清理下游资源

  • 上层封装：advanceChapter（只能前进）、regenerateChapter（可回退并清理）

    stateDiagram-v2
[*] --> idle
idle --> content_generating : "开始内容生成"
content_generating --> content_completed : "完成"
content_completed --> audio_generating : "推进"
audio_generating --> audio_completed : "完成"
audio_completed --> video_generating : "推进"
video_generating --> video_completed : "完成"
content_generating --> failed : "失败"
audio_generating --> failed : "失败"
video_generating --> failed : "失败"
failed --> content_generating : "重新生成"
failed --> idle : "重置"

图表来源

  • server/src/modules/book-generator/stage-manager.ts:57-147

章节来源

  • server/src/modules/book-generator/stage-manager.ts:100-198

工作流与策略（LangGraph）

  • 状态定义：包含 bookId、topic、bookScale、genLevel、progress、completedChapters、failedChapters 等
  • 策略实现：
    • 串行策略：plan → outline → sections → subsections → write_chapters
    • 一步大纲+并行内容：plan → full_outline → write_chapters（并行）
    • 逐章内聚：plan → outline → per_chapter（每章独立并行）

章节来源

  • server/src/modules/book-generator/graph.ts:23-82
  • server/src/modules/book-generator/strategies/sequential.strategy.ts:21-59
  • server/src/modules/book-generator/strategies/one-step-outline.strategy.ts:21-55
  • server/src/modules/book-generator/strategies/per-chapter.strategy.ts:21-55

依赖关系分析

  • 控制器依赖编排器与 WebSocket 进度推送
  • 编排器依赖队列处理器、阶段管理器与容错层
  • 队列处理器依赖队列服务与 LangGraph 生成器
  • 容错层依赖 LLM 服务与队列服务

  • 工作流层依赖 LangGraph 与多种策略实现

    graph LR
Ctrl["book-generator.controller.ts"] --> Orchestrator["book-generator.service.ts"]
Orchestrator --> QueueProc["book-queue.processor.ts"]
QueueProc --> QueueSvc["queue.service.ts"]
QueueProc --> MemQ["memory-queue.ts"]
Orchestrator --> FT["fault-tolerance.ts"]
Orchestrator --> StageMgr["stage-manager.ts"]
QueueProc --> Graph["graph.ts"]
Graph --> StratSeq["sequential.strategy.ts"]
Graph --> StratOne["one-step-outline.strategy.ts"]
Graph --> StratPer["per-chapter.strategy.ts"]

图表来源

  • server/src/modules/book-generator/book-generator.controller.ts:1-199
  • server/src/modules/book-generator/book-generator.service.ts:1-549
  • server/src/modules/book-generator/book-queue.processor.ts:1-124
  • server/src/services/queue.service.ts:1-266
  • server/src/services/memory-queue.ts:1-99
  • server/src/modules/book-generator/fault-tolerance.ts:1-387
  • server/src/modules/book-generator/stage-manager.ts:1-202
  • server/src/modules/book-generator/graph.ts:1-83
  • server/src/modules/book-generator/strategies/sequential.strategy.ts:1-60
  • server/src/modules/book-generator/strategies/one-step-outline.strategy.ts:1-56
  • server/src/modules/book-generator/strategies/per-chapter.strategy.ts:1-56

章节来源

  • 同上

性能考虑

  • 内存队列：在 Redis 不可用时提供基本并发与处理能力，适合小规模场景
  • 并发控制：队列处理器最大并发 3，避免资源争用；策略层面的并行（如逐章内聚）可进一步提升吞吐
  • 轮询等待：内容/音频/视频生成采用轮询检查，间隔与超时时间可调，平衡实时性与负载
  • 指数退避：AI 调用重试采用指数退避，降低对上游服务的压力峰值
  • 模型角色：通过环境变量为不同任务选择合适模型，优化质量与成本
  • 后处理：内容清洗与格式化减少后续处理开销

章节来源

  • server/src/services/memory-queue.ts:17-99
  • server/src/modules/book-generator/book-queue.processor.ts:52-82
  • server/src/modules/book-generator/book-generator.service.ts:178-217
  • server/src/modules/book-generator/book-generator.service.ts:257-285
  • server/src/modules/book-generator/book-generator.service.ts:424-453
  • server/src/modules/book-generator/fault-tolerance.ts:68-123
  • server/src/modules/book-generator/book-generator-optimizations.ts:29-47
  • server/src/modules/book-generator/book-generator-optimizations.ts:49-54

故障排查指南

  • 任务状态查询：通过控制器接口查询任务是否在运行
  • 取消任务：向控制器发送取消请求，编排器会在步骤间检查取消标志
  • 队列不可用：Redis 不可用时自动回退到内存队列；检查队列处理器日志
  • 进度无更新：容错层会发出“长时间无响应”告警，必要时触发自动恢复
  • 失败重试：AI 调用失败会自动重试并记录错误，查看书籍错误信息字段

章节来源

  • server/src/modules/book-generator/book-generator.controller.ts:125-197
  • server/src/modules/book-generator/book-generator.service.ts:24-40
  • server/src/modules/book-generator/book-queue.processor.ts:77-82
  • server/src/modules/book-generator/fault-tolerance.ts:188-261
  • server/src/modules/book-generator/fault-tolerance.ts:268-323

结论

批量生成系统通过清晰的分层设计实现了高可靠与高扩展性：编排器确保步骤可控，队列层提供并发与回退，容错层保障稳定性，阶段管理器维护一致性，工作流层支持多种策略。结合性能优化与完善的监控告警，系统能够在复杂生成任务中保持稳定与高效。

附录：API 接口文档

1. 一键完整生成书籍

  • 方法与路径：POST /api/book-generator/books/:id/batch-generate
  • 请求体
    • steps: GenerationStep[]（可选，默认全部步骤）
    • 可选值：generate_content, generate_audio, merge_audio, generate_video, merge_video
  • 响应
    • code: 0 表示成功，非 0 表示错误
    • data.taskId: 任务 ID
    • data.bookId: 书籍 ID
    • data.status: started
    • data.steps: 实际执行的步骤列表

章节来源

  • server/src/modules/book-generator/book-generator.controller.ts:24-119

2. 取消批量生成任务

  • 方法与路径：POST /api/book-generator/books/:id/batch-generate/cancel
  • 响应
    • code: 0 表示成功
    • data.taskId: 任务 ID
    • data.bookId: 书籍 ID

章节来源

  • server/src/modules/book-generator/book-generator.controller.ts:125-156

3. 查询批量生成任务状态

  • 方法与路径：GET /api/book-generator/books/:id/batch-generate/status
  • 响应
    • data.isRunning: 是否有正在运行的任务
    • data.taskId: 任务 ID（若在运行）
    • data.bookId: 书籍 ID（若在运行）

章节来源

  • server/src/modules/book-generator/book-generator.controller.ts:162-197

4. 书籍生成队列任务（内部）

  • 方法与路径：队列处理器处理 book:generation 队列
  • 数据结构
    • bookId: 书籍 ID
    • topic: 书籍主题/描述
    • bookScale: 书籍规模
    • genLevel: 生成层级
  • 事件
    • progress: 进度回调
    • completed: 任务完成
    • failed: 任务失败（更新书籍状态为 failed）

章节来源

  • server/src/modules/book-generator/book-queue.processor.ts:16-83

5. 数据模型与类型

  • 书籍生成阶段（BookGenStage）：draft, outlining, outline_completed, content_generating, content_completed, audio_generating, audio_completed, video_generating, video_completed, failed
  • 章节生成阶段（ChapterGenStage）：idle, outline_completed, content_generating, content_completed, audio_generating, audio_completed, video_generating, video_completed, failed
  • 生成步骤（GenerationStep）：generate_content, generate_audio, merge_audio, generate_video, merge_video

章节来源

  • server/src/modules/book-generator/book-generator.types.ts:8-138