# Phase 14: 鲁棒性与成本控制 - Context **Gathered:** 2026-03-23 **Status:** Ready for planning ## Phase Boundary 提高 LLM 语义分段的稳定性和成本效率。 **核心能力:** - LLM 调用失败时的重试和降级策略 - 长视频字幕的分块处理,避免上下文窗口溢出 - 智能缓存,避免重复 LLM 调用 - 详细的日志记录,便于问题诊断 **不包括:** - 输出格式优化(Phase 15 - 兼容性) - 新的分段策略(Phase 13 已实现统一策略) ## Implementation Decisions ### 重试策略 - **重试次数**: 重试 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 - 具体的重试逻辑实现细节 - 缓存文件命名规则和目录结构 - 分块算法的具体实现(句子边界检测) - 日志消息的具体措辞和格式 ## 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/` — 需要创建目录结构 ## Specific Ideas - **分块与 ASRCorrector 一致**: 复用 ASRCorrector 的分批处理模式(batch_size=5000,按句子分割) - **重试仅网络错误**: 区分可恢复错误(网络、超时、限流)和不可恢复错误(API 错误、解析失败) - **缓存与内容绑定**: 使用内容哈希而非视频 ID,避免同一视频更新后缓存失效问题 - **日志便于诊断**: 降级时记录具体原因(如 "ConnectionError: 请求超时,重试后仍失败,降级到规则分段") ## Deferred Ideas - **缓存清理命令**: 自动清理过期缓存的功能 — 延后到未来版本,当前手动删除缓存文件 - **缓存压缩**: 压缩缓存文件以节省空间 — 延后到缓存文件较大时再考虑 - **分块智能合并**: 检测相邻分段语义相似度并合并 — 增加复杂度,当前直接拼接足够 --- *Phase: 14-robustness-cost* *Context gathered: 2026-03-23*