# Research Summary: LLM Semantic Segmentation for SRT Subtitles

**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

**核心发现：无需新增外部依赖，基于现有技术栈实现LLM语义分段**

- **技术方案**：使用现有 SimpleAIClient + Pydantic v2 实现两阶段分析（视频类型分类 → 主题分段），无需引入 LangChain、向量数据库等新依赖
- **架构集成**：扩展现有 `SemanticSegmenter`，在 `SRTProcessor` 中新增 LLM 分支，保持向后兼容（可通过 `enable_semantic_segmentation` 参数控制）
- **关键风险**：长视频上下文溢出（>10万字符）、LLM输出格式不稳定、分段边界破坏语义完整性 — 需要通过分块策略、多层fallback、边界保护机制缓解

**推荐实施路径**：优先实现MVP（类型识别+语义分段+标题生成），高级特性（分层结构、质量评分、说话人识别）延后至v2.0

---

## Stack Additions

### 无需新增外部依赖

**所有功能基于现有技术栈实现：**

| 现有组件 | 新用途 | 理由 |
|---------|--------|------|
| **SimpleAIClient** | LLM调用（类型分类、语义分段） | 已集成zhipu/openai/minimax，支持结构化输出 |
| **Pydantic v2** | LLM响应验证与解析 | 提供严格的JSON schema验证，支持多层fallback |
| **SemanticSegmenter** | 集成点，保持向后兼容 | 现有规则分段保留，新增LLM分支 |

### 明确排除的技术（避免过度工程）

| 排除技术 | 理由 |
|---------|------|
| LangChain | 单次LLM调用无需编排框架 |
| 向量嵌入/数据库 | 语义分段不需要检索 |
| 专用分段模型 | LLM灵活性更高，无需额外训练 |
| 实时流式处理 | 批处理模式已满足需求 |
| 多模态分析 | 仅处理SRT文本，无视频帧 |

### 配置策略

**无需新增环境变量**，复用现有AI配置：
```bash
# 已有配置，直接复用
AI_API_KEY=your_key
AI_PROVIDER=zhipu  # or openai, minimax
AI_MODEL=glm-5
```

**可选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
```

---

## Feature Categories

### Table Stakes (MVP必须实现)

**用户期望的基础功能，缺失会让产品感觉"不完整"：**

| 功能 | 复杂度 | 实施优先级 | 说明 |
|------|--------|-----------|------|
| **视频类型识别** | Medium | P0 | 识别6种类型（tutorial/knowledge/story/interview/commentary/mixed），决定分段策略 |
| **主题边界检测** | High | P0 | 基于语义相似度/词频变化检测话题转换点 |
| **内容完整性保护** | High | P0 | 避免在句子/论点中间截断，保持语义连贯 |
| **自然句边界检测** | Medium | P0 | 中文断句（无明确句号），语义判断停顿 |
| **主题标题生成** | Medium | P0 | 为每段生成简洁标题（≤15字） |
| **基本分段策略** | Medium | P0 | 至少支持知识类、故事类两种策略 |

### Differentiators (竞争力功能，v2.0考虑)

**非必需但有价值的功能：**

| 功能 | 复杂度 | 价值 | 建议版本 |
|------|--------|------|---------|
| **分层主题结构** | 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

### 建议阶段结构

基于技术依赖和风险优先级，建议分为3个阶段：

#### **Phase 1: MVP核心功能** (2-3周)
**目标**：实现基础的LLM语义分段，验证可行性

**交付物**：
- ✅ 视频类型识别（6种类型）
- ✅ 语义边界检测（基于LLM）
- ✅ Pydantic Schema验证
- ✅ 三层fallback策略
- ✅ 基础标题生成（≤15字）
- ✅ SRTProcessor集成（向后兼容）

**必须避免的陷阱**：
- LLM-1: 上下文窗口溢出（实施分块策略）
- LLM-2: 输出格式不稳定（多层fallback）
- LLM-3: 边界破坏完整性（句边界保护）

**测试重点**：
- 短视频（<10分钟）的端到端处理
- 不同类型视频的分段质量
- Fallback机制触发路径

---

#### **Phase 2: 鲁棒性增强** (1-2周)
**目标**：提高稳定性和可控性

**交付物**：
- ✅ 成本优化（缓存、批量处理）
- ✅ 分段一致性保证（低温度、seed）
- ✅ Post-processing优化（合并过短分段）
- ✅ 配置化参数（YAML配置支持）
- ✅ 监控和日志（分段质量指标）

**必须避免的陷阱**：
- LLM-4: 分段不一致性（temperature控制）
- LLM-5: 成本失控（缓存策略）

**测试重点**：
- 长视频（>1小时）的分块处理
- 边缘情况（极短视频、单一主题）
- 成本监控

---

#### **Phase 3: 高级特性（v2.0）** (延后)
**目标**：增强用户体验和竞争力

**交付物**：
- 🔲 分层主题结构（章-节）
- 🔲 分段质量评分
- 🔲 说话人识别集成
- 🔲 手动调整界面
- 🔲 时间戳对齐

**延后理由**：
- 需要额外技术调研（如说话人分离）
- 对MVP价值非关键
- 增加复杂度和测试成本

---

### Research Flags

**需要 `/gsd:research-phase` 的阶段**：

| 阶段 | 研究需求 | 理由 |
|------|---------|------|
| Phase 1 | ❌ 不需要 | 技术方案已明确，STACK.md提供完整实现指南 |
| Phase 2 | ❌ 不需要 | 鲁棒性模式已成熟（PITFALLS.md已覆盖） |
| Phase 3 | ✅ 需要 | 说话人识别、分层结构等需要额外技术调研 |

**可直接进入实施的阶段**：
- **Phase 1**: 技术栈已验证，架构模式清晰，可直接开始编码
- **Phase 2**: 基于Phase 1的反馈进行优化，无需额外研究

---

## Confidence Assessment

| 领域 | 信心等级 | 说明 |
|------|---------|------|
| **技术栈** | **HIGH** | 基于现有SimpleAIClient和Pydantic，无需新依赖 |
| **功能定义** | **HIGH** | FEATURES.md基于2025-2026年学术论文，源质量高 |
| **架构集成** | **HIGH** | ARCHITECTURE.md提供完整集成方案，与现有代码兼容 |
| **陷阱识别** | **HIGH** | PITFALLS.md结合了pipeline、反爬虫、LLM三类陷阱 |

**总体信心：HIGH**

**已识别的差距**：
- **中文句边界检测**：现有方法（标点符号+语义停顿）可能不够精确，需要在Phase 2测试中验证
- **分段质量评估**：缺少客观评估指标，需要在Phase 2定义评估标准
- **说话人识别集成**（v2.0）：需要额外调研技术方案

---

## Sources

### 高质量来源（学术/官方文档）
- [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/)

### 中等质量来源（实践指南/行业博客）
- [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)

### 项目内部来源
- `STACK_SEMANTIC_SEGMENTATION.md`: 技术栈和Prompt工程
- `FEATURES.md`: 功能分类和视频类型策略
- `ARCHITECTURE.md`: 集成方案和数据流
- `PITFALLS.md`: 三类陷阱（Pipeline、反爬虫、LLM分段）

---

## Next Steps

1. **立即开始Phase 1实施**：技术方案已明确，无需额外研究
2. **准备测试数据集**：收集不同类型、不同长度的B站视频字幕
3. **定义评估标准**：制定分段质量的主观评估标准（用户测试）和客观指标（分段长度分布、边界位置合理性）
4. **成本监控设置**：在实施前建立LLM调用追踪机制

---

**Research synthesis complete. Ready for roadmap definition.**