# chunk_llm

**Repository Path**: IceCream1012/chunk_llm

## Basic Information

- **Project Name**: chunk_llm
- **Description**: chunk方法大全。适用于ai应用学习
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-07
- **Last Updated**: 2025-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Chunk Demo - 完整的文本分块演示包


一个功能完整、模块化的文本分块（chunk）演示包，提供各种分块方法和评估工具，专为RAG系统、文档处理和文本分析任务设计。

## 🌟 特性

- **全面的分块方法**：涵盖基础、语义、文档结构、自适应和特殊格式分块
- **高级算法**：集成机器学习、深度学习、强化学习等先进技术
- **多格式支持**：支持文本、Markdown、HTML、JSON、XML、PDF、Word等格式
- **评估工具**：提供完整的评估和对比功能
- **实用工具**：包含管道、优化器、验证器等实用功能
- **性能优化**：支持并发处理和大规模文本处理
- **可视化支持**：生成评估结果的可视化图表
- **内存安全**：所有分块器都经过内存泄漏测试和优化

## 📋 包含的分块器

### 1. 基础分块器 (basic_chunking.py)
- **FixedLengthChunker**: 固定长度分块，支持重叠
- **SentenceChunker**: 句子级别分块
- **ParagraphChunker**: 段落分块，自动处理长段落
- **WordChunker**: 词级别分块
- **LineChunker**: 行级别分块
- **RecursiveChunker**: 递归分块，智能选择分隔符

### 2. 语义分块器 (semantic_chunking.py)
- **TfidfSemanticChunker**: 基于TF-IDF的语义分块
- **SentenceTransformerChunker**: 基于句子嵌入的语义分块
- **ClusteringChunker**: 基于聚类的语义分块
- **TopicBasedChunker**: 基于主题的语义分块
- **SlidingWindowSemanticChunker**: 滑动窗口语义分块
- **BERTSemanticChunker**: 基于BERT的语义分块
- **CrossEncoderChunker**: 基于交叉编码器的语义分块
- **GraphBasedChunker**: 基于图的语义分块

### 3. 文档结构分块器 (document_structure_chunking.py)
- **MarkdownChunker**: Markdown文档分块，支持标题、代码块等
- **HTMLChunker**: HTML文档分块，支持各种HTML标签
- **CodeChunker**: 代码文档分块，支持函数、类等结构
- **StructuredTextChunker**: 结构化文本分块，支持章节等

### 4. 自适应分块器 (adaptive_chunking.py)
- **DensityBasedChunker**: 基于文本密度的自适应分块
- **SemanticFlowChunker**: 基于语义流的自适应分块
- **HybridAdaptiveChunker**: 混合自适应分块，结合多种策略
- **ReinforcementLearningChunker**: 基于强化学习的自适应分块
- **NeuralNetworkChunker**: 基于神经网络的自适应分块
- **StreamingChunker**: 流式处理，支持大规模文本

### 5. 特殊格式分块器 (special_format_chunking.py)
- **TableChunker**: 表格分块，支持CSV和Markdown格式
- **JSONChunker**: JSON文档分块，支持结构和大小分块
- **XMLChunker**: XML文档分块，支持元素和大小分块
- **LogChunker**: 日志分块，支持时间和数量分块
- **CodeDocumentationChunker**: 代码文档分块，提取注释和文档字符串
- **YAMLChunker**: YAML文档分块，支持键值对和列表结构
- **LaTeXChunker**: LaTeX文档分块，支持章节、公式、图表结构
- **PDFChunker**: PDF文档分块，支持按页和内容分块
- **DOCXChunker**: Word文档分块，支持段落和表格提取
- **EmailChunker**: 邮件线程分块，支持邮件头和正文分析

### 6. 评估工具 (evaluation_and_comparison.py)
- **ChunkEvaluator**: 分块器评估工具
- **ComprehensiveComparison**: 综合对比测试
- **ChunkMetrics**: 分块指标数据类
- **GroundTruthEvaluator**: 基于真实标签的评估器
- **TaskBasedEvaluator**: 基于任务的评估器，支持RAG、分类、摘要、问答任务

## 🚀 快速开始

### 安装

#### 方法1：推荐安装（minimal）
```bash
# 安装核心依赖
pip install -r requirements-minimal.txt
```

#### 方法2：完整安装
```bash
# 安装所有依赖（可能会有版本冲突）
pip install -r requirements.txt
```

#### 方法3：分步安装
```bash
# 详见 INSTALL.md
pip install numpy pandas scikit-learn matplotlib seaborn nltk regex psutil tqdm joblib PyYAML lxml beautifulsoup4 markdown requests urllib3 pydantic
```

### 验证安装
```python
import basic_chunking
print("安装成功！")
```

### 基础使用

```python
from basic_chunking import FixedLengthChunker

# 创建分块器
chunker = FixedLengthChunker(chunk_size=500, overlap=100)

# 执行分块
chunks = chunker.chunk(your_text)

# 查看结果
for chunk in chunks:
    print(f"Chunk: {chunk.text[:100]}...")
    print(f"Type: {chunk.chunk_type}")
    print(f"Metadata: {chunk.metadata}")
```

### 语义分块

```python
from semantic_chunking import TfidfSemanticChunker

chunker = TfidfSemanticChunker(max_chunk_size=500, similarity_threshold=0.3)
chunks = chunker.chunk(your_text)
```

### 评估分块器

```python
from evaluation_and_comparison import ChunkEvaluator

evaluator = ChunkEvaluator()
metrics = evaluator.evaluate_chunker(chunker, your_text, "MyChunker")
print(f"平均块长度: {metrics.avg_chunk_length}")
print(f"语义连贯性: {metrics.semantic_coherence}")
```

## 📊 运行演示

### 基础演示
```bash
python basic_chunking.py
```

### 语义分块演示
```bash
python semantic_chunking.py
```

### 文档结构分块演示
```bash
python document_structure_chunking.py
```

### 自适应分块演示
```bash
python adaptive_chunking.py
```

### 特殊格式分块演示
```bash
python special_format_chunking.py
```

### 评估对比演示
```bash
python evaluation_and_comparison.py
```

## 🧪 测试

### 单元测试
```bash
python -m pytest tests/test_chunk_demo.py -v
```

### 性能基准测试
```bash
python tests/performance_benchmark.py
```

### 测试覆盖率
```bash
python -m pytest tests/ --cov=chunk_demo --cov-report=html
```

## 📈 性能指标

- **处理速度**: 最高可达 50MB/s（取决于文本复杂度和分块器）
- **内存使用**: 典型情况下 < 100MB
- **并发支持**: 支持多线程并发处理
- **可扩展性**: 支持GB级别的文本处理
- **内存安全**: 所有分块器都经过内存泄漏测试

## 🎯 适用场景

- **RAG系统**: 为检索增强生成系统准备文本块
- **文档处理**: 大规模文档的智能分块
- **知识库构建**: 为知识库构建结构化的文本单元
- **文本分析**: 为后续的文本分析任务准备数据
- **信息检索**: 优化检索系统的文本处理流程

## 🛠️ 开发

### 环境设置
```bash
# 创建虚拟环境
python -m venv chunk-env
source chunk-env/bin/activate  # Linux/Mac
# 或
chunk-env\Scripts\activate     # Windows

# 安装开发依赖
pip install -e ".[dev]"
```

### 代码格式化
```bash
black chunk_demo/
flake8 chunk_demo/
```

### 类型检查
```bash
mypy chunk_demo/
```

## 📚 API 文档

详细的API文档请参考各个模块的文档字符串和示例代码。

## 🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- 感谢所有贡献者和开源社区的支持
- 基于以下优秀的开源库：scikit-learn, transformers, spacy, nltk 等


**注意**: 这是一个演示和教育项目，展示了各种文本分块技术的实现。在生产环境中使用时，请根据具体需求进行适当的调整和优化。

## 🔧 已知问题修复

### 内存泄漏修复 (v1.0.1)
- **FixedLengthChunker**: 修复了无限循环导致的内存泄漏问题
- **参数验证**: 添加了重叠参数验证，防止无效配置
- **边缘情况**: 改进了空文本、小文本和极端参数的处理

### 依赖兼容性 (v1.0.0)
- **TensorFlow/Keras**: 添加了 tf-keras 包以解决 Keras 3 兼容性问题
- **PyTorch**: 支持CPU和GPU版本，自动检测硬件配置
- **可选依赖**: 优雅处理可选依赖的缺失情况