4.7 KiB
4.7 KiB
Phase 14: 鲁棒性与成本控制 - Context
Gathered: 2026-03-23 Status: Ready for planning
## Phase Boundary提高 LLM 语义分段的稳定性和成本效率。
核心能力：
- LLM 调用失败时的重试和降级策略
- 长视频字幕的分块处理，避免上下文窗口溢出
- 智能缓存，避免重复 LLM 调用
- 详细的日志记录，便于问题诊断
不包括：
- 输出格式优化（Phase 15 - 兼容性）
- 新的分段策略（Phase 13 已实现统一策略）
重试策略
- 重试次数: 重试 1 次 — 失败后立即降级到规则分段，简单快速，避免浪费配额
- 重试条件: 仅可恢复错误触发重试 — 网络错误/超时/限流重试，API 错误（如 400）直接降级
- 重试延迟: 立即重试 — 失败后立即重试，大多数情况下网络抖动是瞬时的
- 不可恢复错误: API 错误（4xx）、解析失败、验证失败等直接降级，不重试
分块处理
- 分块阈值: 5000 字符（约 10-15 分钟字幕）— 与 ASRCorrector 的 batch_size 一致，保持代码模式统一
- 分块方式: 按句子边界分割 — 在句号、问号、感叹号等标点符号后分割，保持语义完整性
- 结果合并: 直接拼接各分块结果 — 每个分块独立分段后直接拼接，简单快速
- 分块策略: 长字幕按句子边界分成多个 5000 字符以内的块，每块独立调用 LLM 分段
缓存机制
- 缓存键: 字幕内容哈希（SHA256）— 精确匹配，相同内容一定命中
- 缓存存储: 本地文件系统 — 存储在
.planning/cache/semantic/目录，简单持久化 - 缓存 TTL: 永久有效 — 字幕内容不变，分段结果应该一致，手动清理过期缓存
- 缓存内容: 完整的 SegmentationResult（JSON 格式），包含 video_type 和 segments
日志详细程度
- 降级日志: 记录原因 + 降级方式 — 如 "API key 未配置，降级到规则分段"
- 日志级别: 区分级别
- 降级：warning 级别
- 重试：info 级别
- 成功：debug 级别
- 重试日志: 记录重试原因和次数
- 缓存日志: 记录缓存命中/未命中，使用 debug 级别
Claude's Discretion
- 具体的重试逻辑实现细节
- 缓存文件命名规则和目录结构
- 分块算法的具体实现（句子边界检测）
- 日志消息的具体措辞和格式
<code_context>
Existing Code Insights
Reusable Assets
- kb_workflow/srt/semantic_engine.py — UnifiedSegmentationStrategy 类，已有基本降级逻辑（AI 不可用时使用规则分段）
- kb_workflow/srt/corrector.py — ASRCorrector 类，有
_correct_long_text()方法处理长文本分批（batch_size=5000，按句子分割） - kb_workflow/deep_analyzer/__init__.py — SimpleAIClient 类，统一的 LLM 调用接口
Established Patterns
- Lazy AI Client 初始化: ASRCorrector 模式 — 在 init 中尝试创建 SimpleAIClient，如果 api_key 为空则设为 None
- AIClientProtocol: 定义了 generate(prompt, max_tokens, disable_reasoning) 方法
- 降级策略: UnifiedSegmentationStrategy.segment() 中已有 try-except，异常时返回规则分段
- 日志模式: 使用
logger.info/warning/error，已在 semantic_engine.py 中使用
Integration Points
- UnifiedSegmentationStrategy.segment(): 需要添加重试逻辑和分块处理
- SemanticSegmentationEngine: 可以添加缓存层
- SimpleAIClient.generate(): LLM 调用点，需要捕获可恢复错误进行重试
- 缓存目录:
.planning/cache/semantic/— 需要创建目录结构
</code_context>
## Specific Ideas- 分块与 ASRCorrector 一致: 复用 ASRCorrector 的分批处理模式（batch_size=5000，按句子分割）
- 重试仅网络错误: 区分可恢复错误（网络、超时、限流）和不可恢复错误（API 错误、解析失败）
- 缓存与内容绑定: 使用内容哈希而非视频 ID，避免同一视频更新后缓存失效问题
- 日志便于诊断: 降级时记录具体原因（如 "ConnectionError: 请求超时，重试后仍失败，降级到规则分段"）
- 缓存清理命令: 自动清理过期缓存的功能 — 延后到未来版本，当前手动删除缓存文件
- 缓存压缩: 压缩缓存文件以节省空间 — 延后到缓存文件较大时再考虑
- 分块智能合并: 检测相邻分段语义相似度并合并 — 增加复杂度，当前直接拼接足够
Phase: 14-robustness-cost Context gathered: 2026-03-23