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