435 lines
20 KiB
Markdown
435 lines
20 KiB
Markdown
# Phase 14: 鲁棒性与成本控制 - Research
|
||
|
||
**Research Date:** 2026-03-23
|
||
**Domain:** LLM 容错处理、缓存优化、文本分块
|
||
**Confidence:** HIGH
|
||
|
||
## Summary
|
||
|
||
本阶段专注于提高 LLM 语义分段的稳定性和成本效率。基于用户决策，实现轻量级的重试机制、智能缓存和长文本分块处理。核心原则是"快速失败，优雅降级"——AI 不可用时立即使用规则分段，保证系统可用性。
|
||
|
||
**Primary Recommendation:** 复用 ASRCorrector 的分批处理模式和 SimpleAIClient 的重试逻辑，避免引入新依赖，保持代码一致性。
|
||
|
||
<user_constraints>
|
||
## User Constraints (from CONTEXT.md)
|
||
|
||
### Locked 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
|
||
|
||
- 具体的重试逻辑实现细节
|
||
- 缓存文件命名规则和目录结构
|
||
- 分块算法的具体实现（句子边界检测）
|
||
- 日志消息的具体措辞和格式
|
||
|
||
### Deferred Ideas (OUT OF SCOPE)
|
||
|
||
- **缓存清理命令**: 自动清理过期缓存的功能 — 延后到未来版本，当前手动删除缓存文件
|
||
- **缓存压缩**: 压缩缓存文件以节省空间 — 延后到缓存文件较大时再考虑
|
||
- **分块智能合并**: 检测相邻分段语义相似度并合并 — 增加复杂度，当前直接拼接足够
|
||
</user_constraints>
|
||
|
||
<phase_requirements>
|
||
## Phase Requirements
|
||
|
||
| ID | Description | Research Support |
|
||
|----|-------------|-----------------|
|
||
| ROBUST-01 | LLM 调用失败时自动降级到简单规则分段 | 重试策略实现，异常时调用 fallback_segmenter |
|
||
| ROBUST-02 | LLM 响应解析失败时自动重试或降级，有日志记录 | 区分可恢复/不可恢复错误，解析失败直接降级 |
|
||
| ROBUST-03 | AI 不可用时自动使用简单规则分段 | Lazy AI Client 初始化，None 时直接使用规则分段 |
|
||
| ROBUST-04 | 降级过程有日志记录，便于问题诊断 | 分级日志：降级 warning，重试 info，成功 debug |
|
||
| COST-01 | 长视频字幕自动分块处理，避免上下文窗口溢出 | 复用 ASRCorrector 分批模式，5000 字符阈值 |
|
||
| COST-02 | 相同内容使用缓存结果，避免重复 LLM 调用 | SHA256 哈希缓存键，本地文件系统存储 |
|
||
| COST-03 | 提供配置开关，用户可选择是否启用 LLM 分段 | SRTProcessor 已有 enable_semantic_segmentation 参数 |
|
||
</phase_requirements>
|
||
|
||
## Standard Stack
|
||
|
||
### Core
|
||
| Library | Version | Purpose | Why Standard |
|
||
|---------|---------|---------|--------------|
|
||
| hashlib (built-in) | - | 内容哈希计算 | Python 标准库，无需额外依赖 |
|
||
| logging (built-in) | - | 分级日志记录 | Python 标准库，已在项目中使用 |
|
||
| json (built-in) | - | 缓存序列化 | Python 标准库，已在项目中使用 |
|
||
| pathlib (built-in) | - | 路径操作 | Python 标准库，跨平台兼容 |
|
||
|
||
### Supporting
|
||
| Library | Version | Purpose | When to Use |
|
||
|---------|---------|---------|-------------|
|
||
| pydantic | v2 | 响应验证 | 已在项目中使用，验证 SegmentationResult |
|
||
| requests | 2.32.5+ | HTTP 请求 | 已通过 SimpleAIClient 隐式依赖 |
|
||
|
||
### Alternatives Considered
|
||
| Instead of | Could Use | Tradeoff |
|
||
|------------|-----------|----------|
|
||
| 简单重试循环 | tenacity 库 | tenacity 功能丰富但增加依赖，简单场景手写即可 |
|
||
| 文件系统缓存 | redis/sqlite | Redis 需要额外服务，sqlite 增加复杂度，文件系统最简单 |
|
||
| 手动分块 | langchain TextSplitter | langchain 体积大，ASRCorrector 模式已足够 |
|
||
|
||
**Installation:**
|
||
```bash
|
||
# 无需安装新依赖，全部使用 Python 标准库或已有依赖
|
||
```
|
||
|
||
## Architecture Patterns
|
||
|
||
### Recommended Project Structure
|
||
```
|
||
kb_workflow/srt/
|
||
├── semantic_engine.py # 现有文件，添加重试、分块、缓存
|
||
├── cache/ # 新增目录
|
||
│ ├── __init__.py
|
||
│ └── semantic_cache.py # 缓存管理器
|
||
└── corrector.py # 参考分批处理模式（已有）
|
||
```
|
||
|
||
### Pattern 1: Lazy Initialization with Fallback（已有模式）
|
||
**What:** 延迟初始化 AI Client，失败时使用规则分段
|
||
**When to use:** AI 依赖可能不可用的场景
|
||
**Example:**
|
||
```python
|
||
# Source: kb_workflow/srt/semantic_engine.py:99-114
|
||
if self.ai_client is None:
|
||
try:
|
||
from kb_workflow.deep_analyzer import SimpleAIClient
|
||
self.ai_client = SimpleAIClient()
|
||
if not self.ai_client.api_key:
|
||
logger.info("AI API key not configured")
|
||
self.ai_client = None
|
||
except Exception as e:
|
||
logger.warning(f"Failed to initialize AI client: {e}")
|
||
self.ai_client = None
|
||
```
|
||
|
||
### Pattern 2: Batch Processing with Sentence Boundary Detection（复用模式）
|
||
**What:** 按句子边界分割长文本，每批独立处理
|
||
**When to use:** 文本超过 LLM 上下文窗口
|
||
**Example:**
|
||
```python
|
||
# Source: kb_workflow/srt/corrector.py:125-136
|
||
# 按句子分割（简单分割，基于句号、问号、感叹号）
|
||
sentences = []
|
||
current = ""
|
||
for char in text:
|
||
current += char
|
||
if char in '。！？\n':
|
||
sentences.append(current)
|
||
current = ""
|
||
|
||
# 添加最后一个不完整的句子
|
||
if current:
|
||
sentences.append(current)
|
||
```
|
||
|
||
### Pattern 3: Content-Based Hashing（新增）
|
||
**What:** 使用 SHA256 哈希内容作为缓存键
|
||
**When to use:** 需要精确匹配相同内容
|
||
**Example:**
|
||
```python
|
||
import hashlib
|
||
|
||
def compute_content_hash(content: str) -> str:
|
||
"""计算内容的 SHA256 哈希"""
|
||
return hashlib.sha256(content.encode('utf-8')).hexdigest()
|
||
```
|
||
|
||
### Pattern 4: Retry with Distinguishable Errors（新增）
|
||
**What:** 区分可恢复和不可恢复错误，仅对可恢复错误重试
|
||
**When to use:** API 调用可能因临时故障失败
|
||
**Example:**
|
||
```python
|
||
import requests
|
||
from requests.exceptions import ConnectionError, Timeout, HTTPError
|
||
|
||
def is_recoverable_error(error: Exception) -> bool:
|
||
"""判断是否为可恢复错误"""
|
||
if isinstance(error, (ConnectionError, Timeout)):
|
||
return True
|
||
if isinstance(error, HTTPError):
|
||
status_code = error.response.status_code
|
||
# 网络错误、超时、限流重试
|
||
return status_code in (429, 500, 502, 503, 504)
|
||
return False
|
||
|
||
def call_llm_with_retry(prompt: str, max_retries: int = 1):
|
||
"""带重试的 LLM 调用"""
|
||
for attempt in range(max_retries + 1):
|
||
try:
|
||
return llm_client.generate(prompt)
|
||
except Exception as e:
|
||
if attempt < max_retries and is_recoverable_error(e):
|
||
logger.info(f"LLM call failed (attempt {attempt + 1}): {e}, retrying...")
|
||
continue
|
||
# 最后一次失败或不可恢复错误，抛出异常
|
||
raise
|
||
```
|
||
|
||
### Anti-Patterns to Avoid
|
||
- **不区分错误类型的盲目重试**: 所有错误都重试会导致浪费配额，应区分可恢复/不可恢复错误
|
||
- **固定延迟重试**: 应立即重试（网络抖动是瞬时的），不要使用指数退避
|
||
- **缓存键包含可变元数据**: 缓存键应仅基于内容哈希，不应包含视频 ID 或时间戳
|
||
- **过度复杂的分块合并**: 直接拼接各分块结果即可，无需检测语义相似度
|
||
|
||
## Don't Hand-Roll
|
||
|
||
| Problem | Don't Build | Use Instead | Why |
|
||
|---------|-------------|-------------|-----|
|
||
| 内容哈希 | 自定义哈希算法 | hashlib.sha256() | 标准库函数，安全可靠 |
|
||
| 日志分级 | print 语句 | logging 模块 | 已在项目中使用，支持分级和输出控制 |
|
||
| JSON 序列化 | 手动拼接字符串 | json.dump()/json.load() | 标准库函数，处理转义和格式 |
|
||
| 路径操作 | 字符串拼接 | pathlib.Path | 跨平台兼容，自动处理路径分隔符 |
|
||
| 重试装饰器 | 复杂的装饰器 | 简单 for 循环 | 简单场景（1 次重试）无需额外抽象 |
|
||
|
||
**Key insight:** Python 标准库提供了所需的全部基础设施，无需引入新依赖。重试、缓存、分块都是简单模式，过度工程化会增加维护成本。
|
||
|
||
## Common Pitfalls
|
||
|
||
### Pitfall 1: 不区分可恢复/不可恢复错误
|
||
**What goes wrong:** 所有 LLM 调用失败都重试，包括 API 错误（如 400 Bad Request），导致浪费配额和时间
|
||
**Why it happens:** 简单的 try-except 捕获所有异常，统一重试
|
||
**How to avoid:** 使用 `is_recoverable_error()` 函数判断错误类型，仅对网络错误、超时、限流进行重试
|
||
**Warning signs:** 看到 "重试 400 错误" 的日志
|
||
|
||
### Pitfall 2: 缓存键冲突
|
||
**What goes wrong:** 不同内容的哈希意外相同（哈希碰撞），导致返回错误的缓存结果
|
||
**Why it happens:** 使用弱哈希算法或包含可变元数据（如时间戳）
|
||
**How to avoid:** 使用 SHA256 强哈希，缓存键仅基于内容
|
||
**Warning signs:** 缓存命中后分段结果与内容不符
|
||
|
||
### Pitfall 3: 分块边界破坏语义
|
||
**What goes wrong:** 在句子或段落中间分割，破坏内容完整性
|
||
**Why it happens:** 仅按字符数分割，不考虑句子边界
|
||
**How to avoid:** 复用 ASRCorrector 的分批模式，在标点符号（。！？\n）后分割
|
||
**Warning signs:** 分块后某些分段以不完整的句子开头
|
||
|
||
### Pitfall 4: 缓存目录不存在导致写入失败
|
||
**What goes wrong:** 首次运行时缓存目录不存在，导致文件写入失败
|
||
**Why it happens:** 假设目录已存在，未创建父目录
|
||
**How to avoid:** 使用 `pathlib.Path.mkdir(parents=True, exist_ok=True)` 创建目录
|
||
**Warning signs:** FileNotFoundError 或 PermissionError
|
||
|
||
### Pitfall 5: 降级日志信息不足
|
||
**What goes wrong:** 降级时仅记录 "降级到规则分段"，无法诊断具体原因
|
||
**Why it happens:** 捕获异常后未记录原始错误信息
|
||
**How to avoid:** 记录具体错误类型和消息，如 "ConnectionError: 请求超时，降级到规则分段"
|
||
**Warning signs:** 无法定位降级原因
|
||
|
||
## Code Examples
|
||
|
||
Verified patterns from official sources:
|
||
|
||
### 可恢复错误检测
|
||
```python
|
||
# Source: WebSearch 2026 - Python Retry Best Practices
|
||
from requests.exceptions import ConnectionError, Timeout, HTTPError
|
||
|
||
def is_recoverable_error(error: Exception) -> bool:
|
||
"""判断是否为可恢复错误
|
||
|
||
可恢复错误：网络错误、超时、限流
|
||
不可恢复错误：API 错误（4xx）、解析失败、验证失败
|
||
"""
|
||
if isinstance(error, (ConnectionError, Timeout)):
|
||
return True
|
||
if isinstance(error, HTTPError):
|
||
status_code = error.response.status_code
|
||
# 429 Too Many Requests, 5xx Server Error
|
||
return status_code in (429, 500, 502, 503, 504)
|
||
return False
|
||
```
|
||
|
||
### 内容哈希缓存键
|
||
```python
|
||
# Source: Python standard library documentation
|
||
import hashlib
|
||
|
||
def compute_cache_key(content: str) -> str:
|
||
"""计算内容的 SHA256 哈希作为缓存键"""
|
||
return hashlib.sha256(content.encode('utf-8')).hexdigest()
|
||
```
|
||
|
||
### 缓存读写
|
||
```python
|
||
# Source: Python standard library documentation
|
||
import json
|
||
from pathlib import Path
|
||
|
||
def load_cache(cache_key: str, cache_dir: Path) -> dict | None:
|
||
"""从文件加载缓存"""
|
||
cache_file = cache_dir / f"{cache_key}.json"
|
||
if not cache_file.exists():
|
||
return None
|
||
try:
|
||
return json.loads(cache_file.read_text(encoding='utf-8'))
|
||
except (json.JSONDecodeError, IOError) as e:
|
||
logger.warning(f"Failed to load cache: {e}")
|
||
return None
|
||
|
||
def save_cache(cache_key: str, data: dict, cache_dir: Path):
|
||
"""保存缓存到文件"""
|
||
cache_dir.mkdir(parents=True, exist_ok=True)
|
||
cache_file = cache_dir / f"{cache_key}.json"
|
||
try:
|
||
cache_file.write_text(json.dumps(data, ensure_ascii=False), encoding='utf-8')
|
||
except IOError as e:
|
||
logger.warning(f"Failed to save cache: {e}")
|
||
```
|
||
|
||
### 按句子边界分割
|
||
```python
|
||
# Source: kb_workflow/srt/corrector.py:125-136
|
||
def split_by_sentences(text: str, max_length: int = 5000) -> list[str]:
|
||
"""按句子边界分割文本
|
||
|
||
在句号、问号、感叹号后分割，保持语义完整性。
|
||
"""
|
||
sentences = []
|
||
current = ""
|
||
for char in text:
|
||
current += char
|
||
if char in '。！？\n':
|
||
sentences.append(current)
|
||
current = ""
|
||
|
||
if current:
|
||
sentences.append(current)
|
||
|
||
# 按最大长度分批
|
||
batches = []
|
||
current_batch = []
|
||
current_length = 0
|
||
|
||
for sentence in sentences:
|
||
if current_length + len(sentence) > max_length:
|
||
if current_batch:
|
||
batches.append(''.join(current_batch))
|
||
current_batch = [sentence]
|
||
current_length = len(sentence)
|
||
else:
|
||
current_batch.append(sentence)
|
||
current_length += len(sentence)
|
||
|
||
if current_batch:
|
||
batches.append(''.join(current_batch))
|
||
|
||
return batches
|
||
```
|
||
|
||
## State of the Art
|
||
|
||
| Old Approach | Current Approach | When Changed | Impact |
|
||
|--------------|------------------|--------------|--------|
|
||
| 盲目重试所有错误 | 区分可恢复/不可恢复错误 | 2026-03-23 (Phase 14) | 减少配额浪费，提高响应速度 |
|
||
| 无缓存 | SHA256 内容哈希缓存 | 2026-03-23 (Phase 14) | 相同内容避免重复 LLM 调用 |
|
||
| 长文本直接调用 | 分块处理（5000字符） | 2026-03-23 (Phase 14) | 避免上下文窗口溢出 |
|
||
| 简单 print 日志 | 分级 logging | 已在项目中使用 | 便于问题诊断和日志过滤 |
|
||
|
||
**Deprecated/outdated:**
|
||
- **无区分的重试**: 所有错误都重试的模式已被淘汰，应根据错误类型决定是否重试
|
||
- **基于时间戳的缓存**: 缓存键包含时间戳会导致相同内容缓存不命中，应仅基于内容哈希
|
||
|
||
## Open Questions
|
||
|
||
1. **分块后的分段索引如何计算？**
|
||
- What we know: 每个分块独立分段，结果直接拼接
|
||
- What's unclear: VideoSegment.start_index 和 end_index 是相对于原文还是分块？
|
||
- Recommendation: 相对于原文，需要在分块时记录每个分块的起始偏移量，分段后累加偏移量
|
||
|
||
2. **缓存文件是否需要版本控制？**
|
||
- What we know: 缓存永久有效，手动清理
|
||
- What's unclear: 如果 SegmentationResult 结构变化，旧缓存会加载失败
|
||
- Recommendation: 在缓存 JSON 中添加 version 字段，加载时验证版本
|
||
|
||
3. **分块处理的顺序是否影响结果？**
|
||
- What we know: 每个分块独立调用 LLM，结果直接拼接
|
||
- What's unclear: 分块间是否有上下文依赖（如跨分块的论点）
|
||
- Recommendation: 假设分块间独立，直接拼接。如果出现问题，在 Phase 15 考虑智能合并
|
||
|
||
## Validation Architecture
|
||
|
||
### Test Framework
|
||
| Property | Value |
|
||
|----------|-------|
|
||
| Framework | pytest (python3 -m pytest) |
|
||
| Config file | pytest.ini (已存在) |
|
||
| Quick run command | `python3 -m pytest tests/test_semantic_robustness.py -v -x` |
|
||
| Full suite command | `python3 -m pytest tests/ -v` |
|
||
|
||
### Phase Requirements → Test Map
|
||
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|
||
|--------|----------|-----------|-------------------|-------------|
|
||
| ROBUST-01 | LLM 调用失败时自动降级 | unit | `pytest tests/test_semantic_robustness.py::test_llm_failure_fallback -x` | ❌ Wave 0 |
|
||
| ROBUST-02 | 解析失败时重试或降级 | unit | `pytest tests/test_semantic_robustness.py::test_parse_failure_retry -x` | ❌ Wave 0 |
|
||
| ROBUST-03 | AI 不可用时使用规则分段 | unit | `pytest tests/test_semantic_robustness.py::test_ai_unavailable_fallback -x` | ❌ Wave 0 |
|
||
| ROBUST-04 | 降级日志记录 | unit | `pytest tests/test_semantic_robustness.py::test_fallback_logging -x` | ❌ Wave 0 |
|
||
| COST-01 | 长文本分块处理 | unit | `pytest tests/test_semantic_robustness.py::test_long_text_chunking -x` | ❌ Wave 0 |
|
||
| COST-02 | 缓存命中避免重复调用 | unit | `pytest tests/test_semantic_robustness.py::test_cache_hit -x` | ❌ Wave 0 |
|
||
| COST-03 | 配置开关控制 | integration | `pytest tests/test_srt_processor.py::test_semantic_segmentation_toggle -x` | ❌ Wave 0 |
|
||
|
||
### Sampling Rate
|
||
- **Per task commit:** `python3 -m pytest tests/test_semantic_robustness.py -v -x`
|
||
- **Per wave merge:** `python3 -m pytest tests/ -v`
|
||
- **Phase gate:** Full suite green before `/gsd:verify-work`
|
||
|
||
### Wave 0 Gaps
|
||
- [ ] `tests/test_semantic_robustness.py` — 覆盖 ROBUST-01, ROBUST-02, ROBUST-03, ROBUST-04, COST-01, COST-02
|
||
- [ ] `tests/test_srt_processor.py` — 覆盖 COST-03（配置开关）
|
||
- [ ] `tests/conftest.py` — 共享 fixtures（mock LLM client, 样本字幕数据）
|
||
- [ ] 框架安装: 无需安装，pytest 已配置
|
||
|
||
**Mock Strategy:** 使用 unittest.mock.patch 模拟 SimpleAIClient.generate()，测试不同失败场景（网络错误、解析失败、超时等）
|
||
|
||
## Sources
|
||
|
||
### Primary (HIGH confidence)
|
||
- **kb_workflow/srt/semantic_engine.py** — 现有代码模式，UnifiedSegmentationStrategy, Lazy AI Client 初始化
|
||
- **kb_workflow/srt/corrector.py** — 分批处理模式（_correct_long_text），按句子分割
|
||
- **kb_workflow/deep_analyzer/__init__.py** — SimpleAIClient 重试逻辑（max_retries=3）
|
||
- **Python Standard Library** — hashlib, logging, json, pathlib
|
||
|
||
### Secondary (MEDIUM confidence)
|
||
- [Tenacity Official Repository](https://github.com/jd/tenacity) — 重试库参考（最终决定手写简单重试）
|
||
- [Python Retry Best Practices with Tenacity](https://medium.com/@isuru-perera/how-i-stopped-worrying-about-api-failures-python-retry-with-tenacity-03cf839b4ceb) — 重试最佳实践
|
||
- [How to Retry Failed Python Requests in 2026](https://oxylabs.io/blog/python-requests-retry) — 可恢复错误类型
|
||
|
||
### Tertiary (LOW confidence)
|
||
- [nnsplit - Semantic Text Segmentation](https://github.com/xinmeiyang/nnsplit) — 句子边界检测参考（最终决定复用 ASRCorrector 模式）
|
||
- [PySBD: Pragmatic Sentence Boundary Disambiguation](https://www.researchgate.net/publication/347234862_PySBD_Pragmatic_Sentence_Boundary_Disambiguation) — 句子边界检测研究（最终决定使用简单标点符号分割）
|
||
|
||
## Metadata
|
||
|
||
**Confidence breakdown:**
|
||
- Standard stack: HIGH - 全部使用 Python 标准库或已有依赖
|
||
- Architecture: HIGH - 基于现有代码模式（semantic_engine.py, corrector.py）
|
||
- Pitfalls: HIGH - 基于用户决策和常见错误模式
|
||
|
||
**Research date:** 2026-03-23
|
||
**Valid until:** 2026-04-23 (30 days, 稳定技术栈)
|