130 lines
5.2 KiB
Markdown
130 lines
5.2 KiB
Markdown
---
|
|
phase: 14-robustness-cost
|
|
plan: 02
|
|
subsystem: semantic-segmentation
|
|
tags: [llm, error-handling, retry, fallback, pydantic, json-parsing]
|
|
|
|
# Dependency graph
|
|
requires:
|
|
- phase: 13-llm
|
|
provides: UnifiedSegmentationStrategy, SemanticSegmentationEngine, VideoSegment
|
|
provides:
|
|
- Parse error retry logic with JSONDecodeError/ValueError recovery
|
|
- ValidationError immediate fallback (data structure errors)
|
|
- Detailed error logging with LLM output fragments
|
|
affects: [14-03, 14-04, 14-05]
|
|
|
|
# Tech tracking
|
|
tech-stack:
|
|
added: []
|
|
patterns:
|
|
- Error type differentiation (recoverable vs non-recoverable)
|
|
- Retry loop with attempt tracking
|
|
- Detailed logging for parse failures
|
|
|
|
key-files:
|
|
created: []
|
|
modified:
|
|
- kb_workflow/srt/semantic_engine.py
|
|
- tests/test_semantic_robustness.py
|
|
|
|
key-decisions:
|
|
- "ValidationError checked before ValueError (ValidationError inherits from ValueError)"
|
|
- "JSON parse errors (JSONDecodeError, ValueError) are recoverable - retry 1 time"
|
|
- "Pydantic validation errors (ValidationError) are non-recoverable - immediate fallback"
|
|
- "Parse failures log LLM output fragment (first 500 chars) for diagnosis"
|
|
|
|
patterns-established:
|
|
- "Error type hierarchy: ValidationError → ValueError → Exception"
|
|
- "Recoverable error detection: network, timeout, rate limit, JSON parse errors"
|
|
- "Non-recoverable errors: 4xx HTTP, ValidationError, other exceptions"
|
|
- "Logging levels: INFO for retry, WARNING for fallback, DEBUG for success"
|
|
|
|
requirements-completed: [ROBUST-02, ROBUST-04]
|
|
|
|
# Metrics
|
|
duration: 4min
|
|
completed: 2026-03-23T14:38:45Z
|
|
---
|
|
|
|
# Phase 14 Plan 02: 增强解析失败错误处理和日志
|
|
|
|
**实现 LLM 响应解析失败的类型区分策略:JSON 解析错误重试 1 次,Pydantic 验证错误直接降级,所有失败记录详细日志**
|
|
|
|
## Performance
|
|
|
|
- **Duration:** 4 min
|
|
- **Started:** 2026-03-23T14:35:06Z
|
|
- **Completed:** 2026-03-23T14:38:45Z
|
|
- **Tasks:** 1 (TDD: RED → GREEN)
|
|
- **Files modified:** 2
|
|
|
|
## Accomplishments
|
|
|
|
- 实现 JSONDecodeError/ValueError 重试逻辑(可恢复错误,重试 1 次)
|
|
- 实现 ValidationError 直接降级(不可恢复错误,数据结构问题)
|
|
- 增强日志记录:解析失败时记录 LLM 输出片段(前 500 字符)
|
|
- 修复 `_is_recoverable_error()` 方法,确保 ValidationError 在 ValueError 之前检查
|
|
|
|
## Task Commits
|
|
|
|
Each task was committed atomically:
|
|
|
|
1. **Task 1: 改进解析失败的错误处理和日志 (TDD)** - `970c13a` (test)
|
|
- RED: 创建失败的测试(JSONDecodeError 重试、ValidationError 不重试、日志记录)
|
|
- GREEN: 实现错误类型区分和重试逻辑
|
|
- 验证:所有 10 个测试通过(4 + 2 + 4)
|
|
|
|
**Plan metadata:** (待最终提交)
|
|
|
|
_Note: Implementation code was already committed as part of Plan 14-01 (commit 5c32cfd)_
|
|
|
|
## Files Created/Modified
|
|
|
|
- `kb_workflow/srt/semantic_engine.py` - 增强的错误处理和日志记录
|
|
- `_is_recoverable_error()`: 添加 ValidationError 检查(在 ValueError 之前)
|
|
- `segment()`: 添加 last_llm_output 跟踪,改进日志记录
|
|
- 区分可恢复/不可恢复错误的日志分支
|
|
- `tests/test_semantic_robustness.py` - 测试覆盖
|
|
- `TestParseFailureRetry`: 4 个测试(JSONDecodeError 重试、ValidationError 不重试、日志记录)
|
|
- `TestFallbackLogging`: 2 个测试(降级日志、重试日志)
|
|
- `TestExtractJSON`: 4 个测试(JSON 提取函数)
|
|
|
|
## Decisions Made
|
|
|
|
- **ValidationError 继承链处理**: Pydantic 的 `ValidationError` 继承自 `ValueError`,必须在 `_is_recoverable_error()` 中先检查 `ValidationError`,否则会被误判为可恢复错误
|
|
- **可恢复错误定义**: JSONDecodeError 和 ValueError(非 ValidationError)被视为可恢复错误,因为 LLM 输出格式可能不稳定,重试可能成功
|
|
- **不可恢复错误定义**: ValidationError 表示数据结构错误(缺少必需字段、类型错误等),重试无意义,直接降级
|
|
- **日志详细程度**: 解析失败时记录 LLM 输出片段(前 500 字符),便于诊断 LLM 输出格式问题
|
|
|
|
## Deviations from Plan
|
|
|
|
None - plan executed exactly as written.
|
|
|
|
## Issues Encountered
|
|
|
|
1. **ValidationError 继承自 ValueError**
|
|
- **Problem**: 初始实现中,`isinstance(error, ValueError)` 匹配了 `ValidationError`,导致验证错误被误判为可恢复错误
|
|
- **Solution**: 在 `_is_recoverable_error()` 中先检查 `ValidationError`,再检查 `ValueError`
|
|
- **Verification**: 测试 `test_validation_error_no_retry` 验证 ValidationError 只调用 1 次 LLM(不重试)
|
|
|
|
2. **日志级别不一致**
|
|
- **Problem**: 测试期望 ERROR 级别日志,但实现使用 WARNING 级别
|
|
- **Solution**: 更新测试使用 WARNING 级别,与实际日志级别一致
|
|
- **Rationale**: WARNING 级别更合适,因为系统已降级到规则分段,仍可继续运行
|
|
|
|
## User Setup Required
|
|
|
|
None - no external service configuration required.
|
|
|
|
## Next Phase Readiness
|
|
|
|
- ✅ ROBUST-02 完成:解析失败时自动重试或降级
|
|
- ✅ ROBUST-04 完成:降级过程记录详细日志
|
|
- 准备好进入 Plan 14-03(AI 不可用时的降级策略)
|
|
- 准备好进入 Plan 14-04(长视频分块处理)
|
|
|
|
---
|
|
*Phase: 14-robustness-cost*
|
|
*Completed: 2026-03-23*
|