docs: complete v1.6 semantic segmentation research
This commit is contained in:
+464
-129
@@ -1,188 +1,523 @@
|
||||
# Project Research Summary
|
||||
# Research Summary: LLM Semantic Segmentation for SRT Subtitles
|
||||
|
||||
**Project:** kb-skills (Skill-based Workflow Orchestration System)
|
||||
**Domain:** Content Processing Pipeline with LLM Agent Orchestration
|
||||
**Researched:** 2026-03-13
|
||||
**Confidence:** HIGH
|
||||
**Project:** kb-skills v1.6 - Semantic Segmentation Improvement
|
||||
**Research Date:** 2026-03-21
|
||||
**Synthesized from:** STACK_SEMANTIC_SEGMENTATION.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
这是一个技能型工作流编排系统,专门用于内容处理管道(视频/文章的元数据提取、ASR识别、AI深度分析)。专家构建此类系统时,通常采用分层架构将编排层、技能定义层、执行层和基础设施层分离,并使用步骤级状态管理实现断点续传和幂等执行。
|
||||
**核心发现:无需新增外部依赖,基于现有技术栈实现LLM语义分段**
|
||||
|
||||
基于研究,推荐采用**串行管道编排模式**,使用 `transitions` 状态机管理步骤状态,`Pydantic` 定义 Schema 并实现验证。核心原则是:每个步骤完成后立即持久化状态,失败时可以从断点恢复,重复执行不会产生重复文件。这与 Airflow/Prefect 等重量级编排工具不同——本项目专注于单机批处理场景,无需分布式执行。
|
||||
- **技术方案**:使用现有 SimpleAIClient + Pydantic v2 实现两阶段分析(视频类型分类 → 主题分段),无需引入 LangChain、向量数据库等新依赖
|
||||
- **架构集成**:扩展现有 `SemanticSegmenter`,在 `SRTProcessor` 中新增 LLM 分支,保持向后兼容(可通过 `enable_semantic_segmentation` 参数控制)
|
||||
- **关键风险**:长视频上下文溢出(>10万字符)、LLM输出格式不稳定、分段边界破坏语义完整性 — 需要通过分块策略、多层fallback、边界保护机制缓解
|
||||
|
||||
关键风险在于**无状态执行**和**错误上下文丢失**。长时间运行的任务(Whisper识别可能需要30分钟)如果失败后需要从头开始,成本极高。缓解措施是在 Phase 1 就实现 `workflow_state.json` 状态文件,并确保每个步骤输出结构化错误信息。
|
||||
**推荐实施路径**:优先实现MVP(类型识别+语义分段+标题生成),高级特性(分层结构、质量评分、说话人识别)延后至v2.0
|
||||
|
||||
## Key Findings
|
||||
---
|
||||
|
||||
### Recommended Stack
|
||||
## Stack Additions
|
||||
|
||||
推荐使用 Python 3.12+ 作为运行时,配合 Pydantic 2.11+ 进行数据验证和 JSON Schema 生成,transitions 0.9.3+ 实现步骤状态机,Typer + Rich 构建现代化 CLI。这套组合轻量、Pythonic,与项目的 SKILL.md 规范模式完美契合。
|
||||
### 无需新增外部依赖
|
||||
|
||||
**Core technologies:**
|
||||
- **Pydantic 2.11+**: 数据验证 & Schema 生成 — v2.11+ 解析速度更快,原生支持 JSON Schema,与 PIPE-07 需求匹配
|
||||
- **transitions 0.9.3+**: 状态机 — 轻量级、支持回调和嵌套状态,无需数据库
|
||||
- **pydantic-settings 2.8+**: 配置管理 — 解决现有 `~/.kb_env` 分散配置问题
|
||||
- **Typer 0.15+**: CLI 框架 — 基于 Click 的现代 CLI,利用类型提示自动生成参数
|
||||
- **tenacity 8.5+**: 重试机制 — 实现指数退避重试,处理 API 调用失败
|
||||
**所有功能基于现有技术栈实现:**
|
||||
|
||||
**避免使用:** Airflow/Celery(过重)、argparse(样板代码多)、requests(同步阻塞)
|
||||
| 现有组件 | 新用途 | 理由 |
|
||||
|---------|--------|------|
|
||||
| **SimpleAIClient** | LLM调用(类型分类、语义分段) | 已集成zhipu/openai/minimax,支持结构化输出 |
|
||||
| **Pydantic v2** | LLM响应验证与解析 | 提供严格的JSON schema验证,支持多层fallback |
|
||||
| **SemanticSegmenter** | 集成点,保持向后兼容 | 现有规则分段保留,新增LLM分支 |
|
||||
|
||||
### Expected Features
|
||||
### 明确排除的技术(避免过度工程)
|
||||
|
||||
**Must have (table stakes):**
|
||||
- **步骤级状态管理** — 用户期望能从断点恢复,不重新执行已完成的步骤
|
||||
- **幂等执行** — 相同输入重复执行产生相同结果,无重复文件
|
||||
- **JSON Schema 验证** — 数据契约确保步骤间接口一致性
|
||||
- **结构化错误处理** — 错误消息包含上下文和可操作建议
|
||||
- **平台特定内容处理** — B站/知乎元数据和内容提取
|
||||
| 排除技术 | 理由 |
|
||||
|---------|------|
|
||||
| LangChain | 单次LLM调用无需编排框架 |
|
||||
| 向量嵌入/数据库 | 语义分段不需要检索 |
|
||||
| 专用分段模型 | LLM灵活性更高,无需额外训练 |
|
||||
| 实时流式处理 | 批处理模式已满足需求 |
|
||||
| 多模态分析 | 仅处理SRT文本,无视频帧 |
|
||||
|
||||
**Should have (competitive):**
|
||||
- **SKILL.md 声明式技能定义** — AI 代理可发现和执行技能
|
||||
- **多模态内容处理** — 视频(ASR/OCR)+文本统一管道
|
||||
- **Tmux 会话持久化** — 长时间运行操作可断开终端
|
||||
### 配置策略
|
||||
|
||||
**Defer (v2+):**
|
||||
- **并发执行** — 当前串行模式足够,并发增加复杂度
|
||||
- **Web UI** — CLI 优先,可视化需求低
|
||||
- **多租户** — 单用户工具
|
||||
**无需新增环境变量**,复用现有AI配置:
|
||||
```bash
|
||||
# 已有配置,直接复用
|
||||
AI_API_KEY=your_key
|
||||
AI_PROVIDER=zhipu # or openai, minimax
|
||||
AI_MODEL=glm-5
|
||||
```
|
||||
|
||||
### Architecture Approach
|
||||
**可选YAML配置**(`.kb_env.yaml`):
|
||||
```yaml
|
||||
semantic_segmentation:
|
||||
enabled: true
|
||||
enable_fallback: true
|
||||
default_video_type: mixed
|
||||
min_segment_length: 200 # 字符
|
||||
max_segment_length: 2000 # 字符
|
||||
target_segment_count: 5
|
||||
```
|
||||
|
||||
推荐四层架构:编排层(Workflow Coordinator、State Manager、Error Handler)、技能定义层(SKILL.md specs、Schema Definitions)、执行层(Platform/Processing/Analysis Skills)、基础设施层(File System、External APIs、AI Services)。
|
||||
---
|
||||
|
||||
**Major components:**
|
||||
1. **State Manager** — 管理 `workflow_state.json`,实现步骤级状态持久化和原子写入
|
||||
2. **Schema Registry** — 统一的输入输出 JSON Schema 定义和验证
|
||||
3. **Pipeline Engine** — 串行执行技能,检查状态跳过已完成步骤
|
||||
4. **Platform Skills** — B站/知乎的元数据提取和内容下载
|
||||
5. **Processing Skills** — Whisper/FunASR 语音识别、OCR 处理
|
||||
6. **Analysis Skills** — kb-deep-analyzer AI 深度分析
|
||||
## Feature Categories
|
||||
|
||||
### Critical Pitfalls
|
||||
### Table Stakes (MVP必须实现)
|
||||
|
||||
1. **无状态执行 = 从头重来** — Whisper 识别 20 分钟后失败,没有状态文件则需要重新识别。避免:每个步骤完成后写入 `workflow_state.json`
|
||||
**用户期望的基础功能,缺失会让产品感觉"不完整":**
|
||||
|
||||
2. **错误上下文丢失** — 步骤 6 失败只报告 "API error",不知道是哪个内容、什么输入。避免:结构化 JSON 错误,包含步骤名、输入摘要、失败原因、可操作建议
|
||||
| 功能 | 复杂度 | 实施优先级 | 说明 |
|
||||
|------|--------|-----------|------|
|
||||
| **视频类型识别** | Medium | P0 | 识别6种类型(tutorial/knowledge/story/interview/commentary/mixed),决定分段策略 |
|
||||
| **主题边界检测** | High | P0 | 基于语义相似度/词频变化检测话题转换点 |
|
||||
| **内容完整性保护** | High | P0 | 避免在句子/论点中间截断,保持语义连贯 |
|
||||
| **自然句边界检测** | Medium | P0 | 中文断句(无明确句号),语义判断停顿 |
|
||||
| **主题标题生成** | Medium | P0 | 为每段生成简洁标题(≤15字) |
|
||||
| **基本分段策略** | Medium | P0 | 至少支持知识类、故事类两种策略 |
|
||||
|
||||
3. **假设模型"理解上下文"** — 主代理期望子代理知道之前发生了什么,但每次调用是独立会话。避免:显式传递所有需要的上下文,输入 JSON 自包含
|
||||
### Differentiators (竞争力功能,v2.0考虑)
|
||||
|
||||
4. **非幂等操作** — 每次执行创建 `output_1.mp4`、`output_2.mp4`。避免:基于输入生成确定性文件名,已存在则跳过
|
||||
**非必需但有价值的功能:**
|
||||
|
||||
5. **环境变量分散** — `~/.kb_env`、子技能配置、HF_TOKEN 分散各处。避免:统一配置文件,启动时检查所有必需变量
|
||||
| 功能 | 复杂度 | 价值 | 建议版本 |
|
||||
|------|--------|------|---------|
|
||||
| **分层主题结构** | High | 支持多级层次(章-节) | v2.0 |
|
||||
| **时间戳对齐** | Medium | 分段与原字幕时间对齐 | v2.0 |
|
||||
| **分段质量评分** | Medium | 给出质量可信度 | v2.0 |
|
||||
| **说话人识别集成** | High | 结合说话人变化优化 | v2.0 |
|
||||
| **可配置分段粒度** | Low | 用户控制分段密度 | v2.0 |
|
||||
| **分段合并建议** | Medium | 检测过短分段并建议合并 | v2.0 |
|
||||
| **主题连贯性分析** | High | 评估分段内部一致性 | v2.0 |
|
||||
|
||||
### Anti-Features (明确不构建)
|
||||
|
||||
**避免的功能陷阱:**
|
||||
|
||||
| 反功能 | 风险 | 替代方案 |
|
||||
|--------|------|---------|
|
||||
| **固定大小分段** | 破坏语义完整性 | 基于内容边界动态分段 |
|
||||
| **纯关键词匹配** | 无法理解上下文 | 使用LLM语义分析 |
|
||||
| **实时流式分段** | 缺乏全局上下文 | 批处理完整内容 |
|
||||
| **多语言混合处理** | 逻辑复杂降低质量 | 先分离语言再处理 |
|
||||
| **完全自动化无审核** | LLM误判边界 | 提供预览和手动调整 |
|
||||
| **过度细分段** | 碎片化降低可读性 | 设置最小长度阈值 |
|
||||
|
||||
### 视频类型与分段策略映射
|
||||
|
||||
**不同类型视频的分段特征:**
|
||||
|
||||
| 视频类型 | 分段依据 | 边界信号 | 标题风格 | 典型长度 |
|
||||
|---------|---------|---------|---------|---------|
|
||||
| **知识类** | 主题/知识点变化 | "接下来"、"其次" | 描述性,反映知识点 | 2-5分钟 |
|
||||
| **故事类** | 情节发展/场景变化 | 时间/地点/人物转换 | 叙事性,反映情节 | 5-10分钟 |
|
||||
| **访谈类** | 问题/话题转换 | 主持人提问 | 问答式,反映主题 | 3-6分钟 |
|
||||
| **新闻类** | 新闻条目 | "接下来是"、"据报道" | 信息性,反映事件 | 1-3分钟 |
|
||||
| **Vlog类** | 活动/场景变化 | 时间跳跃/地点切换 | 描述性,反映活动 | 1-8分钟 |
|
||||
| **混合类** | 综合以上策略 | 多种信号 | 综合风格 | 变化大 |
|
||||
|
||||
---
|
||||
|
||||
## Architecture Integration
|
||||
|
||||
### 集成点:扩展现有 SRTProcessor
|
||||
|
||||
**最小改动原则**,在现有 `kb_workflow/pipeline/processors/srt.py` 中新增LLM分支:
|
||||
|
||||
```python
|
||||
class SRTProcessor(BaseProcessor):
|
||||
def __init__(
|
||||
self,
|
||||
state_manager: Optional[WorkflowStateManager] = None,
|
||||
enable_correction: bool = True,
|
||||
enable_semantic_segmentation: bool = True # 新增参数
|
||||
):
|
||||
# ... 现有初始化 ...
|
||||
self.semantic_engine = None # 新增字段
|
||||
|
||||
# 延迟初始化LLM引擎
|
||||
if enable_semantic_segmentation:
|
||||
try:
|
||||
from kb_workflow.srt.semantic_engine import SemanticSegmentationEngine
|
||||
from kb_workflow.deep_analyzer import SimpleAIClient
|
||||
|
||||
ai_client = SimpleAIClient()
|
||||
if ai_client.api_key:
|
||||
self.semantic_engine = SemanticSegmentationEngine(ai_client=ai_client)
|
||||
except Exception as e:
|
||||
logger.warning(f"Failed to init semantic engine: {e}")
|
||||
|
||||
async def process(self, input_data: SRTInput) -> SRTOutput:
|
||||
# ... 现有解析代码 ...
|
||||
|
||||
# 新增:LLM分段分支
|
||||
if self.semantic_engine and self.enable_semantic_segmentation:
|
||||
logger.info("Using LLM-based semantic segmentation")
|
||||
paragraphs = self._semantic_segment_with_llm(segments, metadata)
|
||||
else:
|
||||
logger.info("Using rule-based segmentation")
|
||||
paragraphs = self.segmenter.segment(segments) # 现有逻辑
|
||||
|
||||
# ... 后续处理不变 ...
|
||||
```
|
||||
|
||||
### 新增模块:SemanticSegmentationEngine
|
||||
|
||||
**位置**:`kb_workflow/srt/semantic_engine.py`
|
||||
|
||||
**职责**:
|
||||
- **Stage 1**: 视频类型检测(few-shot分类,输出类型代码)
|
||||
- **Stage 2**: 语义分段(结构化JSON输出,Pydantic验证)
|
||||
- **Fallback**: 三层降级策略(直接解析 → Markdown提取 → 均匀分段)
|
||||
|
||||
**关键设计**:
|
||||
|
||||
```python
|
||||
class SemanticSegmentationEngine:
|
||||
def __init__(
|
||||
self,
|
||||
ai_client: Optional[AIClientProtocol] = None,
|
||||
enable_fallback: bool = True
|
||||
):
|
||||
self.ai_client = ai_client
|
||||
self.enable_fallback = enable_fallback
|
||||
|
||||
def detect_video_type(self, text_preview: str, metadata: dict) -> str:
|
||||
"""Stage 1: 检测视频类型(tutorial/knowledge/...)"""
|
||||
# 返回类型代码,失败返回 "mixed"
|
||||
|
||||
def segment_semantically(
|
||||
self,
|
||||
full_text: str,
|
||||
video_type: str,
|
||||
metadata: dict,
|
||||
target_segments: int = 5
|
||||
) -> SegmentationResult:
|
||||
"""Stage 2: 执行语义分段"""
|
||||
# 返回结构化分段结果,带Pydantic验证
|
||||
```
|
||||
|
||||
### Pydantic Schema:严格验证LLM输出
|
||||
|
||||
**位置**:`kb_workflow/srt/schemas.py`
|
||||
|
||||
```python
|
||||
class VideoSegment(BaseModel):
|
||||
"""单个语义分段"""
|
||||
title: str = Field(..., min_length=1, max_length=50)
|
||||
start_index: int = Field(..., ge=0)
|
||||
end_index: int = Field(..., ge=0)
|
||||
summary: str = Field(..., min_length=1, max_length=100)
|
||||
|
||||
@field_validator('end_index')
|
||||
def validate_bounds(cls, v, info):
|
||||
if 'start_index' in info.data and v <= info.data['start_index']:
|
||||
raise ValueError('end_index must be greater than start_index')
|
||||
return v
|
||||
|
||||
class SegmentationResult(BaseModel):
|
||||
"""完整分段结果"""
|
||||
segments: List[VideoSegment] = Field(..., min_length=1)
|
||||
overall_summary: str = Field(..., min_length=1, max_length=200)
|
||||
|
||||
@field_validator('segments')
|
||||
def validate_segments(cls, v):
|
||||
# 检查重叠和排序
|
||||
...
|
||||
```
|
||||
|
||||
### 三层Fallback策略
|
||||
|
||||
**确保鲁棒性**,LLM失败时优雅降级:
|
||||
|
||||
1. **Strategy 1**: 直接JSON解析(理想情况)
|
||||
2. **Strategy 2**: Markdown代码块提取(常见情况)
|
||||
3. **Strategy 3**: 启发式均匀分段(保底方案)
|
||||
|
||||
```python
|
||||
def parse_llm_response(response_text: str, total_length: int) -> SegmentationResult:
|
||||
# 1. 直接解析
|
||||
try:
|
||||
return SegmentationResult.model_validate_json(response_text)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
# 2. 提取Markdown中的JSON
|
||||
try:
|
||||
json_match = re.search(r'```json\s*(.*?)\s*```', response_text, re.DOTALL)
|
||||
if json_match:
|
||||
return SegmentationResult.model_validate_json(json_match.group(1))
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
# 3. 保底:均匀分段
|
||||
return _generate_fallback_segments(total_length)
|
||||
```
|
||||
|
||||
### 数据流
|
||||
|
||||
```
|
||||
SRT Input
|
||||
↓
|
||||
[Parse Subtitles] → segments: List[Segment]
|
||||
↓
|
||||
[Video Type Detection] → video_type: str (mixed/tutorial/knowledge/...)
|
||||
↓
|
||||
[Semantic Segmentation] → SegmentationResult (segments + titles + summaries)
|
||||
↓
|
||||
[Extract Paragraphs] → paragraphs: List[str] (基于start_index/end_index)
|
||||
↓
|
||||
[ASR Correction] → corrected_paragraphs: List[str]
|
||||
↓
|
||||
[Deep Analysis] → analysis_results
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Watch Out For
|
||||
|
||||
### 严重陷阱(必须避免)
|
||||
|
||||
#### 1. 上下文窗口溢出导致长视频处理失败
|
||||
|
||||
**风险**:B站知识类视频常达1-2小时,字幕超10万字符,直接发送会触发API错误或内容截断。
|
||||
|
||||
**缓解策略**:
|
||||
- **分块处理**:先按现有时间间隔(3秒停顿)预分块,再合并至80k token以下
|
||||
- **两阶段分析**:Stage 1用小模型快速扫描定位潜在边界,Stage 2仅对可疑区域深度分析
|
||||
- **Token计数**:使用 `tiktoken` 实时计算,动态调整分段策略
|
||||
|
||||
**实施阶段**:Phase 1 (架构设计时必须考虑)
|
||||
|
||||
---
|
||||
|
||||
#### 2. LLM输出格式不稳定导致解析失败
|
||||
|
||||
**风险**:LLM可能返回:
|
||||
- 纯文本而非JSON
|
||||
- JSON包裹在Markdown代码块中
|
||||
- 缺少必需字段
|
||||
- 字段类型错误(如字符串而非数字)
|
||||
|
||||
**缓解策略**:
|
||||
- **多层fallback**:直接解析 → Markdown提取 → 启发式分段
|
||||
- **严格的Pydantic验证**:字段类型、范围、业务规则(如 `end_index > start_index`)
|
||||
- **Prompt工程**:明确要求"只输出JSON,不要其他内容",提供示例格式
|
||||
|
||||
**实施阶段**:Phase 1 (核心功能)
|
||||
|
||||
---
|
||||
|
||||
#### 3. 分段边界破坏语义完整性
|
||||
|
||||
**风险**:在句子中间或论点未完成时截断,导致分段语义破碎。
|
||||
|
||||
**缓解策略**:
|
||||
- **句边界保护**:检测标点符号(句号、问号、感叹号),优先在这些位置分段
|
||||
- **修辞结构识别**:检测并列结构("首先、其次、最后"),不在其间截断
|
||||
- **最小长度保护**:设置 `min_segment_length=200`,避免碎片化
|
||||
- **Post-processing**:合并过短分段(<200字符)到相邻分段
|
||||
|
||||
**实施阶段**:Phase 1 (核心功能) + Phase 2 (优化)
|
||||
|
||||
---
|
||||
|
||||
#### 4. 分段不一致性(同一视频多次运行结果不同)
|
||||
|
||||
**风险**:LLM的随机性导致同一内容多次分段结果差异大,影响可复现性。
|
||||
|
||||
**缓解策略**:
|
||||
- **温度参数设置**:`temperature=0.1`(低温度保证稳定性)
|
||||
- **Seed固定**:如果API支持,使用固定seed
|
||||
- **结果缓存**:对同一视频缓存分段结果(基于内容hash)
|
||||
|
||||
**实施阶段**:Phase 2 (鲁棒性增强)
|
||||
|
||||
---
|
||||
|
||||
#### 5. 成本失控(高频LLM调用导致费用激增)
|
||||
|
||||
**风险**:每个视频都需要2次LLM调用(类型检测+分段),大量处理时成本显著。
|
||||
|
||||
**缓解策略**:
|
||||
- **智能缓存**:相似内容(如同一UP主、同一系列)复用视频类型
|
||||
- **分段数量自适应**:短视频(<5分钟)减少目标分段数
|
||||
- **批量处理折扣**:如果API支持,使用batch模式
|
||||
- **监控告警**:设置月度成本上限,超限时降级为规则分段
|
||||
|
||||
**实施阶段**:Phase 2 (成本优化)
|
||||
|
||||
---
|
||||
|
||||
### 中等风险(需要注意)
|
||||
|
||||
#### 6. 中文断句不准确
|
||||
|
||||
**风险**:中文没有明确句号,LLM可能在短语中间断句。
|
||||
|
||||
**缓解策略**:
|
||||
- **语义停顿检测**:基于短语结构判断停顿位置
|
||||
- **标点符号优先**:优先在逗号、分号处分段
|
||||
- **LLM辅助断句**:对歧义情况让LLM判断
|
||||
|
||||
---
|
||||
|
||||
#### 7. 幻觉检测缺失(LLM生成不存在的标题)
|
||||
|
||||
**风险**:LLM可能生成与内容不符的标题或摘要。
|
||||
|
||||
**缓解策略**:
|
||||
- **关键词提取验证**:标题应包含分段中的关键词
|
||||
- **后处理验证**:检查标题词汇是否在原文中出现
|
||||
- **用户反馈机制**:v2.0提供手动调整界面
|
||||
|
||||
---
|
||||
|
||||
### 低风险(可接受)
|
||||
|
||||
#### 8. 分段数量不精确
|
||||
|
||||
**风险**:请求5个分段,LLM返回3个或7个。
|
||||
|
||||
**缓解策略**:
|
||||
- **Prompt明确要求**:"必须分为5个段落"
|
||||
- **Post-processing调整**:过多则合并,过少则拆分(基于子主题)
|
||||
- **接受偏差**:±1个分段可接受
|
||||
|
||||
---
|
||||
|
||||
## Implications for Roadmap
|
||||
|
||||
Based on research, suggested phase structure:
|
||||
### 建议阶段结构
|
||||
|
||||
### Phase 1: Foundation (基础设施层)
|
||||
基于技术依赖和风险优先级,建议分为3个阶段:
|
||||
|
||||
**Rationale:** 状态管理和 Schema 验证是所有后续组件的基础,必须首先实现。没有状态文件就无法实现断点续传和幂等执行。
|
||||
**Delivers:** State Manager、Schema Registry、Error Handler、统一配置管理
|
||||
**Addresses:** 步骤级状态管理、幂等执行、JSON Schema 验证、结构化错误处理
|
||||
**Avoids:** 无状态执行、错误上下文丢失、环境变量分散
|
||||
#### **Phase 1: MVP核心功能** (2-3周)
|
||||
**目标**:实现基础的LLM语义分段,验证可行性
|
||||
|
||||
**Components:**
|
||||
- `skills/core/state_manager.py` — workflow_state.json 管理
|
||||
- `skills/core/schema_registry.py` — JSON Schema 定义和验证
|
||||
- `skills/core/error_handler.py` — 统一错误处理
|
||||
- `config.py` — pydantic-settings 配置管理
|
||||
**交付物**:
|
||||
- ✅ 视频类型识别(6种类型)
|
||||
- ✅ 语义边界检测(基于LLM)
|
||||
- ✅ Pydantic Schema验证
|
||||
- ✅ 三层fallback策略
|
||||
- ✅ 基础标题生成(≤15字)
|
||||
- ✅ SRTProcessor集成(向后兼容)
|
||||
|
||||
### Phase 2: Core Skills (核心技能集成)
|
||||
**必须避免的陷阱**:
|
||||
- LLM-1: 上下文窗口溢出(实施分块策略)
|
||||
- LLM-2: 输出格式不稳定(多层fallback)
|
||||
- LLM-3: 边界破坏完整性(句边界保护)
|
||||
|
||||
**Rationale:** 基于现有技能进行集成,将分散的技能统一到管道模型中。Link Parser 是入口点,无依赖;Platform Skills 依赖其输出。
|
||||
**Delivers:** Link Parser 集成、B站/知乎 Metadata 和 Content 技能适配
|
||||
**Uses:** Pydantic (Schema)、transitions (状态)、Typer (CLI)
|
||||
**Implements:** Pipeline Engine 原型
|
||||
**测试重点**:
|
||||
- 短视频(<10分钟)的端到端处理
|
||||
- 不同类型视频的分段质量
|
||||
- Fallback机制触发路径
|
||||
|
||||
**Components:**
|
||||
- Link Parser 技能适配(已有 kb-link-parser)
|
||||
- B站/知乎技能适配(已有 kb-bilibili-*、kb-zhihu-*)
|
||||
- 管道执行引擎原型
|
||||
---
|
||||
|
||||
### Phase 3: Processing Skills (处理技能集成)
|
||||
#### **Phase 2: 鲁棒性增强** (1-2周)
|
||||
**目标**:提高稳定性和可控性
|
||||
|
||||
**Rationale:** ASR 和 OCR 依赖视频文件,必须在内容下载后执行。这些技能已有实现,需要集成到管道。
|
||||
**Delivers:** Whisper/FunASR 集成、OCR 集成、处理技能状态管理
|
||||
**Addresses:** 多模态内容处理
|
||||
**Avoids:** 假设模型理解上下文 — 显式传递转录结果给分析步骤
|
||||
**交付物**:
|
||||
- ✅ 成本优化(缓存、批量处理)
|
||||
- ✅ 分段一致性保证(低温度、seed)
|
||||
- ✅ Post-processing优化(合并过短分段)
|
||||
- ✅ 配置化参数(YAML配置支持)
|
||||
- ✅ 监控和日志(分段质量指标)
|
||||
|
||||
**Components:**
|
||||
- Whisper/FunASR 技能适配
|
||||
- OCR 技能适配
|
||||
- 处理结果 Schema 定义
|
||||
**必须避免的陷阱**:
|
||||
- LLM-4: 分段不一致性(temperature控制)
|
||||
- LLM-5: 成本失控(缓存策略)
|
||||
|
||||
### Phase 4: Analysis & Orchestration (分析技能与编排)
|
||||
**测试重点**:
|
||||
- 长视频(>1小时)的分块处理
|
||||
- 边缘情况(极短视频、单一主题)
|
||||
- 成本监控
|
||||
|
||||
**Rationale:** 深度分析是管道的最终输出,依赖所有前置步骤。编排层整合所有技能形成完整工作流。
|
||||
**Delivers:** Deep Analyzer 集成、完整管道编排、工作流定义文件
|
||||
**Uses:** 所有前置组件
|
||||
**Implements:** 声明式工作流定义 (YAML)
|
||||
---
|
||||
|
||||
**Components:**
|
||||
- Deep Analyzer 技能适配
|
||||
- Pipeline Engine 完善
|
||||
- `workflows/video_pipeline.yaml`
|
||||
- `workflows/article_pipeline.yaml`
|
||||
#### **Phase 3: 高级特性(v2.0)** (延后)
|
||||
**目标**:增强用户体验和竞争力
|
||||
|
||||
### Phase 5: Polish & Testing (完善与测试)
|
||||
**交付物**:
|
||||
- 🔲 分层主题结构(章-节)
|
||||
- 🔲 分段质量评分
|
||||
- 🔲 说话人识别集成
|
||||
- 🔲 手动调整界面
|
||||
- 🔲 时间戳对齐
|
||||
|
||||
**Rationale:** 核心功能完成后,补充测试、文档和边缘情况处理。
|
||||
**Delivers:** 单元测试、集成测试、错误恢复策略完善、用户文档
|
||||
**Addresses:** 错误恢复策略、进度可见性
|
||||
**延后理由**:
|
||||
- 需要额外技术调研(如说话人分离)
|
||||
- 对MVP价值非关键
|
||||
- 增加复杂度和测试成本
|
||||
|
||||
### Phase Ordering Rationale
|
||||
|
||||
- **依赖关系决定顺序:** State Manager 是所有组件的基础,必须 Phase 1;Analysis 依赖 Processing,Processing 依赖 Platform Skills
|
||||
- **架构模式指导分组:** Foundation -> Skills -> Orchestration 符合分层架构
|
||||
- **避免陷阱:** Phase 1 就实现状态文件和 Schema,防止无状态执行和接口不一致
|
||||
---
|
||||
|
||||
### Research Flags
|
||||
|
||||
Phases likely needing deeper research during planning:
|
||||
- **Phase 3:** ASR/OCR 集成可能需要研究 FunASR vs Whisper 选择逻辑,以及 HuggingFace token 缺失时的降级策略
|
||||
- **Phase 4:** AI API 调用的重试策略和超时配置可能需要根据实际使用调整
|
||||
**需要 `/gsd:research-phase` 的阶段**:
|
||||
|
||||
Phases with standard patterns (skip research-phase):
|
||||
- **Phase 1:** 状态管理和 Schema 验证是成熟模式,Pydantic/transitions 文档充分
|
||||
- **Phase 2:** 现有技能适配,无需额外研究
|
||||
- **Phase 5:** 测试和文档是标准实践
|
||||
| 阶段 | 研究需求 | 理由 |
|
||||
|------|---------|------|
|
||||
| Phase 1 | ❌ 不需要 | 技术方案已明确,STACK.md提供完整实现指南 |
|
||||
| Phase 2 | ❌ 不需要 | 鲁棒性模式已成熟(PITFALLS.md已覆盖) |
|
||||
| Phase 3 | ✅ 需要 | 说话人识别、分层结构等需要额外技术调研 |
|
||||
|
||||
**可直接进入实施的阶段**:
|
||||
- **Phase 1**: 技术栈已验证,架构模式清晰,可直接开始编码
|
||||
- **Phase 2**: 基于Phase 1的反馈进行优化,无需额外研究
|
||||
|
||||
---
|
||||
|
||||
## Confidence Assessment
|
||||
|
||||
| Area | Confidence | Notes |
|
||||
|------|------------|-------|
|
||||
| Stack | HIGH | Pydantic/transitions/Typer 都是成熟库,官方文档完善,与项目需求匹配度高 |
|
||||
| Features | HIGH | 基于现有代码库分析和行业标准,功能边界清晰 |
|
||||
| Architecture | HIGH | 四层架构是工作流系统的标准模式,管道编排模式适合内容处理场景 |
|
||||
| Pitfalls | HIGH | 基于多篇研究论文和行业实践,坑点识别充分 |
|
||||
| 领域 | 信心等级 | 说明 |
|
||||
|------|---------|------|
|
||||
| **技术栈** | **HIGH** | 基于现有SimpleAIClient和Pydantic,无需新依赖 |
|
||||
| **功能定义** | **HIGH** | FEATURES.md基于2025-2026年学术论文,源质量高 |
|
||||
| **架构集成** | **HIGH** | ARCHITECTURE.md提供完整集成方案,与现有代码兼容 |
|
||||
| **陷阱识别** | **HIGH** | PITFALLS.md结合了pipeline、反爬虫、LLM三类陷阱 |
|
||||
|
||||
**Overall confidence:** HIGH
|
||||
**总体信心:HIGH**
|
||||
|
||||
### Gaps to Address
|
||||
**已识别的差距**:
|
||||
- **中文句边界检测**:现有方法(标点符号+语义停顿)可能不够精确,需要在Phase 2测试中验证
|
||||
- **分段质量评估**:缺少客观评估指标,需要在Phase 2定义评估标准
|
||||
- **说话人识别集成**(v2.0):需要额外调研技术方案
|
||||
|
||||
- **ASR 后端选择:** Whisper vs FunASR 的选择逻辑需要根据实际性能测试确定,目前建议支持配置切换
|
||||
- **错误恢复策略细节:** 403/超时等具体错误类型的处理策略需要在实现时细化
|
||||
- **进度汇报机制:** 长时间运行的 Whisper 任务需要进度汇报,具体实现方式待定
|
||||
---
|
||||
|
||||
## Sources
|
||||
|
||||
### Primary (HIGH confidence)
|
||||
- Pydantic v2.11 Release & JSON Schema Docs — 技术选型验证
|
||||
- transitions 0.9.3 on PyPI — 状态机库详情
|
||||
- Dagster: Data Pipeline Architecture Design Patterns — 管道模式
|
||||
- AI Architecture Patterns 101: Workflows, Agents — 架构模式
|
||||
- Demystifying Failures in Platform-Orchestrated Workflows (arxiv) — 失败模式研究
|
||||
### 高质量来源(学术/官方文档)
|
||||
- [Chapter-Llama: Efficient Chaptering in Hour-Long Videos with LLMs (CVPR 2025)](https://arxiv.org/html/2504.00072v1)
|
||||
- [LLM-Enhanced Semantic Text Segmentation - MDPI Applied Sciences 2025](https://www.mdpi.com/2076-3417/15/19/10849)
|
||||
- [Beyond Transcripts: A Renewed Perspective on Audio Chaptering - arXiv 2025](https://arxiv.org/html/2602.08979v1)
|
||||
- [Multimodal Fusion and Coherence Modeling for Video Topic Segmentation - ACL Findings 2025](https://aclanthology.org/2025.findings-acl.904.pdf)
|
||||
- [The Complete Guide to Using Pydantic for Validating LLM Outputs](https://machinelearningmastery.com/the-complete-guide-to-using-pydantic-for-validating-llm-outputs/)
|
||||
|
||||
### Secondary (MEDIUM confidence)
|
||||
- Prefect vs Dagster Comparison — 编排工具对比
|
||||
- Multi-Step LLM Chains: Best Practices — LLM 链最佳实践
|
||||
- Data Pipeline State Management (Fivetran) — 状态管理挑战
|
||||
- 9 Things I Hate About Environment Variables — 配置管理问题
|
||||
### 中等质量来源(实践指南/行业博客)
|
||||
- [Automate Video Chaptering with LLMs and TF-IDF](https://towardsdatascience.com/automate-video-chaptering-with-llms-and-tf-idf-f6569fd4d32b/)
|
||||
- [AI-Based Video Analyzer for Automated Chaptering and Summarization](https://medium.com/codex/ai-based-video-analyzer-for-automated-chaptering-and-summarization-2ca65f35b687)
|
||||
- [Best Chunking Strategies for RAG (and LLMs) in 2026](https://www.firecrawl.dev/blog/best-chunking-strategies-rag)
|
||||
|
||||
### Tertiary (LOW confidence)
|
||||
- AI Agent Anti-Patterns (Medium) — 反模式识别,需要结合实践验证
|
||||
### 项目内部来源
|
||||
- `STACK_SEMANTIC_SEGMENTATION.md`: 技术栈和Prompt工程
|
||||
- `FEATURES.md`: 功能分类和视频类型策略
|
||||
- `ARCHITECTURE.md`: 集成方案和数据流
|
||||
- `PITFALLS.md`: 三类陷阱(Pipeline、反爬虫、LLM分段)
|
||||
|
||||
---
|
||||
*Research completed: 2026-03-13*
|
||||
*Ready for roadmap: yes*
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **立即开始Phase 1实施**:技术方案已明确,无需额外研究
|
||||
2. **准备测试数据集**:收集不同类型、不同长度的B站视频字幕
|
||||
3. **定义评估标准**:制定分段质量的主观评估标准(用户测试)和客观指标(分段长度分布、边界位置合理性)
|
||||
4. **成本监控设置**:在实施前建立LLM调用追踪机制
|
||||
|
||||
---
|
||||
|
||||
**Research synthesis complete. Ready for roadmap definition.**
|
||||
|
||||
Reference in New Issue
Block a user