AI与TTS故障排查

本文引用的文件

index.ts
langgraph-controller.ts
graph.ts
fault-tolerance.ts
stage-manager.ts
tts.service.ts
aliyun.provider.ts
minimax.provider.ts
index.ts
rate-limiter.ts
queue.service.ts
logger.service.ts
sentry.service.ts
models.json

简介

本故障排查文档专为AI有声书生成平台设计，重点解决AI内容生成和TTS语音合成过程中的常见问题。文档涵盖LangGraph工作流异常、LLM模型调用失败、TTS服务提供商连接问题、音色合成质量异常、生成进度卡死等场景，并提供断点分析、多供应商切换方案、模型参数调优建议和性能优化策略。

项目结构

AI有声书生成平台采用模块化架构，主要分为以下核心模块：

graph TB
subgraph "AI生成模块"
BG[index.ts<br/>书籍生成器主入口]
LC[langgraph-controller.ts<br/>LangGraph控制器]
FT[fault-tolerance.ts<br/>容错层]
SM[stage-manager.ts<br/>阶段管理器]
GR[graph.ts<br/>状态定义]
end
subgraph "TTS合成模块"
TS[tts.service.ts<br/>TTS服务]
AP[aliyun.provider.ts<br/>阿里云TTS]
MP[minimax.provider.ts<br/>MiniMax TTS]
end
subgraph "基础设施"
LLM[index.ts<br/>LLM服务]
RL[rate-limiter.ts<br/>限流器]
QS[queue.service.ts<br/>队列服务]
LS[logger.service.ts<br/>日志服务]
SS[sentry.service.ts<br/>错误监控]
MC[models.json<br/>模型配置]
end
BG --> LC
LC --> FT
LC --> SM
LC --> GR
TS --> AP
TS --> MP
TS --> LLM
TS --> QS
LLM --> MC
RL --> LC
QS --> LC
LS --> BG
SS --> BG

图表来源

index.ts:1-104
langgraph-controller.ts:1-800
tts.service.ts:1-715

核心组件

LangGraph书籍生成器

LangGraph书籍生成器采用策略模式，支持多种生成策略：

串行策略：传统顺序生成
一步大纲+并行内容：推荐方案
逐章内聚：终极方案

TTS多供应商架构

TTS服务支持三种供应商，具备自动切换能力：

MiniMax：异步长文本语音合成，支持speech-2.8-hd模型
阿里云百炼：HTTP接口，支持实时模式
模拟服务：开发调试用

容错与监控体系

AI调用重试机制（3次重试+指数退避）
节点级超时控制（10-45分钟不等）
进度监控（最长空闲10分钟）
自动恢复机制

章节来源

index.ts:1-104
tts.service.ts:1-715
fault-tolerance.ts:1-387

架构概览

sequenceDiagram
participant Client as 客户端
participant Controller as LangGraph控制器
participant Generator as 生成器
participant LLM as LLM服务
participant TTS as TTS服务
participant Storage as 存储服务
Client->>Controller : POST /api/book-generator/langgraph/books
Controller->>Controller : 队列检查
alt 队列可用
Controller->>Generator : 加入队列任务
Controller-->>Client : 返回队列ID
else 队列不可用
Controller->>Generator : 同步执行
Controller-->>Client : 直接返回结果
end
Generator->>LLM : 调用AI生成大纲
LLM-->>Generator : 返回大纲数据
Generator->>LLM : 调用AI生成内容
LLM-->>Generator : 返回内容数据
loop 章节生成
Generator->>TTS : 语音合成请求
TTS->>TTS : 多供应商切换
alt MiniMax可用
TTS->>MiniMax : 异步任务创建
MiniMax-->>TTS : 返回任务ID
TTS->>MiniMax : 轮询任务状态
MiniMax-->>TTS : 返回音频文件
else 阿里云可用
TTS->>阿里云 : HTTP请求
阿里云-->>TTS : 返回音频URL
else 模拟服务
TTS->>TTS : 生成模拟音频
end
TTS->>Storage : 上传音频文件
Storage-->>TTS : 返回访问URL
TTS-->>Generator : 返回音频URL
end
Generator->>Storage : 保存章节音频
Storage-->>Generator : 确认保存
Generator-->>Controller : 更新生成进度
Controller-->>Client : 返回生成完成

图表来源

langgraph-controller.ts:383-530
tts.service.ts:200-542

详细组件分析

LangGraph工作流异常排查

断点分析流程

flowchart TD
Start([开始生成]) --> CheckQueue["检查队列状态"]
CheckQueue --> QueueAvailable{"队列可用?"}
QueueAvailable --> |是| AddQueue["加入队列"]
QueueAvailable --> |否| SyncExec["同步执行"]
AddQueue --> UpdateStatus["更新书籍状态"]
SyncExec --> UpdateStatus
UpdateStatus --> GenStage["进入大纲生成阶段"]
GenStage --> OutlineGen["生成章大纲"]
OutlineGen --> OutlineSuccess{"大纲生成成功?"}
OutlineSuccess --> |否| RetryOutline["重试大纲生成"]
OutlineSuccess --> |是| SectionGen["生成节大纲"]
RetryOutline --> OutlineRetry{"重试次数<3?"}
OutlineRetry --> |是| RetryOutline
OutlineRetry --> |否| FailOutline["大纲生成失败"]
SectionGen --> ContentGen["生成章节内容"]
ContentGen --> AudioGen["音频生成"]
AudioGen --> QualityCheck["音质检查"]
QualityCheck --> QualityPass{"音质合格?"}
QualityPass --> |是| Complete["生成完成"]
QualityPass --> |否| Regenerate["重新生成"]
Regenerate --> AudioGen
FailOutline --> Recovery["自动恢复"]
Recovery --> Complete

图表来源

fault-tolerance.ts:68-123
stage-manager.ts:158-198

阶段管理器

阶段管理器确保状态转移的合法性：

stateDiagram-v2
[*] --> draft
draft --> outlining : 创建书籍
outlining --> outline_completed : 生成大纲
outline_completed --> 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 --> draft : 重新开始

图表来源

stage-manager.ts:13-67

章节来源

langgraph-controller.ts:383-530
fault-tolerance.ts:188-261
stage-manager.ts:100-147

LLM模型调用失败排查

模型自动切换机制

flowchart TD
CallLLM[调用LLM] --> TryModel[尝试当前模型]
TryModel --> Success{调用成功?}
Success --> |是| ReturnResult[返回结果]
Success --> |否| CheckError{检查错误类型}
CheckError --> IsRateLimit{是否额度限制?}
IsRateLimit --> |是| SwitchModel[切换到下一个模型]
IsRateLimit --> |否| ThrowError[抛出错误]
SwitchModel --> ModelAvailable{还有可用模型?}
ModelAvailable --> |是| TryModel
ModelAvailable --> |否| ThrowError
ThrowError --> ReturnResult

图表来源

index.ts:129-201

模型配置管理

系统支持多供应商模型配置：

阿里云百炼：支持多种Qwen模型
MiniMax：支持文本生成和语音合成
火山引擎：支持多种推理模型

章节来源

index.ts:1-362
models.json:1-186

TTS服务提供商连接问题排查

多供应商切换流程

sequenceDiagram
participant TTS as TTS服务
participant Provider as 供应商选择器
participant MiniMax as MiniMax
participant Aliyun as 阿里云
participant Mock as 模拟服务
TTS->>Provider : 获取TTS供应商
Provider->>Provider : 检查配置优先级
alt MiniMax可用
Provider->>MiniMax : 创建任务
MiniMax-->>Provider : 返回任务ID
Provider-->>TTS : 返回MiniMax实例
else 阿里云可用
Provider->>Aliyun : HTTP请求
Aliyun-->>Provider : 返回音频URL
Provider-->>TTS : 返回阿里云实例
else 模拟服务
Provider->>Mock : 生成模拟音频
Mock-->>Provider : 返回模拟文件
Provider-->>TTS : 返回模拟实例
end
TTS->>TTS : 处理音频文件
TTS->>TTS : 合并音频段
TTS->>TTS : 上传存储
TTS-->>调用方 : 返回音频URL

图表来源

tts.service.ts:163-190
minimax.provider.ts:237-278
aliyun.provider.ts:21-150

供应商特性对比

供应商	模型支持	传输方式	适用场景	限制
MiniMax	speech-2.8-hd	异步轮询	长文本合成	5分钟超时限制
阿里云	多种TTS模型	HTTP直连	实时需求	600字符限制
模拟服务	无	本地生成	开发调试	无实际音频

章节来源

tts.service.ts:1-715
minimax.provider.ts:1-280
aliyun.provider.ts:1-152

音色合成质量异常排查

音色参数调优

flowchart TD
Start([音色质量异常]) --> CheckText["检查文本质量"]
CheckText --> TextQuality{"文本格式正确?"}
TextQuality --> |否| FixText["修正文本格式"]
TextQuality --> |是| CheckParams["检查音色参数"]
FixText --> CheckParams
CheckParams --> ParamRange{"参数在合理范围内?"}
ParamRange --> |否| AdjustParams["调整参数范围"]
ParamRange --> |是| CheckProvider["检查供应商状态"]
AdjustParams --> CheckProvider
CheckProvider --> ProviderOK{"供应商正常?"}
ProviderOK --> |否| SwitchProvider["切换供应商"]
ProviderOK --> |是| CheckModel["检查模型配置"]
SwitchProvider --> CheckModel
CheckModel --> ModelOK{"模型配置正确?"}
ModelOK --> |否| FixModel["修正模型配置"]
ModelOK --> |是| QualityOK{"音质仍然异常?"}
FixModel --> QualityOK
QualityOK --> |是| LogIssue["记录问题详情"]
QualityOK --> |否| Complete["问题解决"]
LogIssue --> Complete

图表来源

tts.service.ts:604-635

音色映射表

系统支持10种预设音色，每种音色都有对应的参数配置：

女性音色：Cherry、Serena、Chelsie、Momo、Vivian、Maia
男性音色：Ethan、Moon、Kai、Nofish

章节来源

tts.service.ts:24-55

依赖关系分析

graph TB
subgraph "AI生成依赖"
BG[index.ts] --> FT[fault-tolerance.ts]
BG --> SM[stage-manager.ts]
BG --> GR[graph.ts]
LC[langgraph-controller.ts] --> BG
LC --> FT
LC --> SM
LLM[llm/index.ts] --> LC
end
subgraph "TTS依赖"
TS[tts.service.ts] --> AP[aliyun.provider.ts]
TS --> MP[minimax.provider.ts]
TS --> LLM
TS --> QS[queue.service.ts]
end
subgraph "基础设施"
RL[rate-limiter.ts] --> LC
QS --> LC
LS[logger.service.ts] --> BG
SS[sentry.service.ts] --> BG
MC[models.json] --> LLM
end
FT --> LLM
SM --> BG
GR --> BG

图表来源

index.ts:17-20
tts.service.ts:7-14

章节来源

index.ts:1-104
tts.service.ts:1-715

性能考虑

限流策略

系统实施多层次限流机制：

flowchart TD
Request[请求到达] --> GlobalRate[全局API限流]
GlobalRate --> LoginRate[登录接口限流]
LoginRate --> TTSRate[TTS生成限流]
TTSRate --> UploadRate[文件上传限流]
GlobalRate --> CheckGlobal{检查是否触发}
CheckGlobal --> |是| BlockGlobal[阻塞请求]
CheckGlobal --> |否| Proceed[继续处理]
BlockGlobal --> Wait[等待重试]
Wait --> GlobalRate
Proceed --> Next[下一限流]

图表来源

rate-limiter.ts:49-120

队列优化

Redis队列：生产环境使用，支持持久化和分布式
内存队列：Redis不可用时的降级方案
超时控制：书籍生成2小时，音频生成5分钟

章节来源

rate-limiter.ts:1-120
queue.service.ts:1-347

故障排查指南

常见问题诊断流程

1. LangGraph工作流异常

症状：生成进度卡死，章节无法继续 排查步骤：

检查队列状态：GET /api/book-generator/langgraph/books/:id/progress
查看容错日志：检查AI调用重试记录
验证阶段转移：确认状态机是否正常
监控进度：检查10分钟空闲告警

解决方案：

重启队列处理器
清理僵尸任务
手动触发自动恢复

2. LLM模型调用失败

症状：AI生成内容异常或超时 排查步骤：

检查模型配置：验证API Key和基础URL
查看错误类型：区分额度限制和服务器错误
监控重试机制：确认3次重试是否生效
验证模型切换：检查备用模型是否可用

解决方案：

补充API配额
调整温度参数
切换到备用模型
优化提示词格式

3. TTS服务提供商连接问题

症状：音频生成失败或超时 排查步骤：

检查供应商配置：验证API Key和模型设置
监控重试机制：确认指数退避是否正常
验证文本分段：检查600字符限制
查看存储状态：确认文件上传成功

解决方案：

切换到可用供应商
调整并发参数
优化文本格式
检查网络连接

4. 音色合成质量异常

症状：音频质量差或音色不匹配 排查步骤：

检查音色参数：速度、音调、音量设置
验证文本格式：特殊字符和标点符号
测试不同音色：对比效果差异
查看音频时长：确认LRC歌词生成

解决方案：

调整音色参数范围
修正文本格式
更换合适音色
优化分段策略

错误重试机制

AI调用重试策略

flowchart TD
Start[AI调用开始] --> Attempt1[第1次尝试]
Attempt1 --> Success1{成功?}
Success1 --> |是| Return[返回结果]
Success1 --> |否| CheckError1{检查错误}
CheckError1 --> RateLimit1{额度限制?}
RateLimit1 --> |是| Wait1[等待2秒]
RateLimit1 --> |否| Fail1[调用失败]
Wait1 --> Attempt2[第2次尝试]
Attempt2 --> Success2{成功?}
Success2 --> |是| Return
Success2 --> |否| CheckError2{检查错误}
CheckError2 --> RateLimit2{额度限制?}
RateLimit2 --> |是| Wait2[等待4秒]
RateLimit2 --> |否| Fail2[调用失败]
Wait2 --> Attempt3[第3次尝试]
Attempt3 --> Success3{成功?}
Success3 --> |是| Return
Success3 --> |否| FinalFail[最终失败]
Fail1 --> FinalFail
Fail2 --> FinalFail

图表来源

fault-tolerance.ts:68-123

TTS供应商重试策略

MiniMax：429状态码和5xx错误自动重试
阿里云：429状态码和5xx错误自动重试
指数退避：2秒、4秒、8秒等待时间

章节来源

fault-tolerance.ts:68-123
minimax.provider.ts:247-278
aliyun.provider.ts:125-145

降级方案

自动降级流程

flowchart TD
Primary[主供应商] --> CheckPrimary{检查可用性}
CheckPrimary --> |可用| UsePrimary[使用主供应商]
CheckPrimary --> |不可用| Secondary[备选供应商]
Secondary --> CheckSecondary{检查可用性}
CheckSecondary --> |可用| UseSecondary[使用备选供应商]
CheckSecondary --> |不可用| Mock[模拟服务]
Mock --> UseMock[使用模拟服务]
UsePrimary --> MonitorPrimary{监控性能}
UseSecondary --> MonitorSecondary{监控性能}
MonitorPrimary --> |异常| SwitchSecondary[切换到备选]
MonitorSecondary --> |异常| SwitchMock[切换到模拟]
SwitchSecondary --> UseSecondary
SwitchMock --> UseMock

图表来源

tts.service.ts:163-190

人工干预降级

当自动降级失败时，可通过以下方式人工干预：

修改供应商优先级
调整重试参数
切换到备用配置
手动触发恢复

章节来源

tts.service.ts:304-314

监控与日志

日志记录策略

系统采用多层日志记录：

AI请求日志：详细记录LLM调用参数
TTS处理日志：记录音频生成过程
错误日志：捕获异常堆栈信息
HTTP请求日志：监控API调用情况

错误监控

Sentry集成：生产环境错误监控
Redis健康检查：队列服务可用性监控
进度监控：生成任务状态跟踪
性能指标：响应时间和吞吐量统计

章节来源

logger.service.ts:1-114
sentry.service.ts:1-113

结论

本故障排查文档建立了完整的AI有声书生成平台问题诊断和解决体系。通过多层容错机制、智能供应商切换、完善的监控日志和详细的降级方案，能够有效应对各种异常情况。

关键要点：

预防为主：通过限流、超时控制和重试机制减少故障发生
快速恢复：自动降级和手动干预相结合确保服务连续性
可观测性：全面的日志记录和错误监控便于问题定位
持续优化：基于监控数据不断优化配置和参数

建议运维团队定期检查以下指标：

队列积压情况
供应商可用性比率
AI调用成功率
TTS生成时延
错误率趋势

通过这些措施，可以确保AI有声书生成平台的稳定运行和高质量服务体验。

AI与TTS故障排查.md 19 KB History Raw

AI与TTS故障排查

目录

简介

项目结构

核心组件

LangGraph书籍生成器

TTS多供应商架构

容错与监控体系

架构概览

详细组件分析

LangGraph工作流异常排查

断点分析流程

阶段管理器

LLM模型调用失败排查

模型自动切换机制

模型配置管理

TTS服务提供商连接问题排查

多供应商切换流程

供应商特性对比

音色合成质量异常排查

音色参数调优

音色映射表

依赖关系分析

性能考虑

限流策略

队列优化

故障排查指南

常见问题诊断流程

1. LangGraph工作流异常

2. LLM模型调用失败

3. TTS服务提供商连接问题

4. 音色合成质量异常

错误重试机制

AI调用重试策略

TTS供应商重试策略

降级方案

自动降级流程

人工干预降级

监控与日志

日志记录策略

错误监控

结论

AI与TTS故障排查.md 19 KB

History Raw