用途:把长 Chuukese/英文文档切分成文本块,供 OCR 流水线、AI 训练数据生成或检索(RAG)使用。仓库中已有实现 src/utils/intelligent_chunker.py,应直接使用,不要自行编写切分器。
主要能力:通过 IntelligentTextChunker 构造参数 max_chunk_size、min_chunk_size、overlap_ratio(0.0–0.5)、preserve_sentences、preserve_paragraphs 控制切分;调用 chunker.chunk(text) 返回 TextChunk 列表,每项含 content、start_position、end_position、chunk_id、chunk_type、metadata、overlap_with_previous、overlap_with_next。ChunkType 枚举为 SEMANTIC、STRUCTURAL、FIXED_SIZE、SLIDING_WINDOW。切分器内置多语言句子边界(英文、Chuukese、通用 CJK 标点)、结构标记(markdown 标题、列表项、词典条目、分页符)和语义过渡短语的识别。
使用方式:从 src.utils.intelligent_chunker 导入 IntelligentTextChunker、ChunkType、TextChunk 后构造并调用。参数选择参考:训练对 max_chunk_size 256–512、overlap_ratio 0.0–0.05;RAG/检索 512–1024、0.10–0.15;摘要输入 1024–2048、0.05。Chuukese 每字符信息密度高于英文,为下游 LLM 估算 token 时应按 token 而非字符计数。
限制与注意:切分器不识别圣经引用,可能把 1 Cor. 13:4-7 拆开,输入含引用时须用 src/utils/scripture_parser.py 的 protect_scripture_references / restore_scripture_references 包裹调用。max_chunk_size 默认按字符计(dataclass 的 len 返回 len(content)),需要 token 数时用模型分词器后处理。preserve_paragraphs=True 配合较小 max_chunk_size 会产生超长块而非断开段落,有硬上限时需校验长度。chunk_id 含位置信息、跨运行不确定,不可作数据库主键。不要继承该类,公开 API 很小,应通过构造参数配置或后处理块列表。该切分器被 EnhancedOCRProcessor、LargeDocumentProcessor 使用,AITrainingDataGenerator 通过 ParsedDocument 间接消费。