# rag-chunk

**Repository Path**: fa0/rag-chunk

## Basic Information

- **Project Name**: rag-chunk
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-30
- **Last Updated**: 2026-01-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 语义文档切片工具

使用大语言模型对文档进行语义切片，用于知识库构建。

## 功能特点

- 🧠 **语义切片**：基于 LLM 进行智能语义分割，而非简单按字数切割
- 📄 **多格式支持**：支持 txt、markdown、PDF、Word 文档
- 📦 **大文档处理**：自动分批处理大文档
- 🔄 **输出续传**：自动处理 LLM 输出 token 限制
- ⚙️ **灵活配置**：支持自定义 API 地址和模型

## 安装

```bash
pip install -r requirements.txt
```

## 配置

设置环境变量：

```bash
export OPENAI_API_KEY="your-api-key"
export OPENAI_BASE_URL="https://api.openai.com/v1"  # 可选，自定义 API 地址
export LLM_MODEL="gpt-4o"  # 可选，指定模型
```

## 使用方法

### 命令行使用

```bash
# 基本用法
python main.py --input document.pdf

# 指定输出文件
python main.py --input article.md --output chunks.json

# 自定义切片大小（1000-2000 字符）
python main.py --input book.docx --min-size 800 --max-size 1500

# 使用自定义 API
python main.py --input doc.txt --base-url https://your-api.com/v1 --model gpt-4
```

### 代码调用

```python
from config import Config
from chunker import SemanticChunker
from utils import read_document

# 加载配置
config = Config.from_env()

# 自定义配置（可选）
config.llm.base_url = "https://your-api.com/v1"
config.llm.model = "gpt-4o"
config.chunk.min_chunk_size = 1000
config.chunk.max_chunk_size = 2000

# 创建切片器
chunker = SemanticChunker(config)

# 读取文档并切片
text = read_document("document.pdf")
chunks = chunker.chunk_document(text)

# 使用切片结果
for chunk in chunks:
    print(f"[{chunk.id}] {chunk.char_count} 字")
    print(chunk.content[:100] + "...")
```

## 输出格式

输出 JSON 文件格式：

```json
{
  "source_file": "document.pdf",
  "total_chunks": 10,
  "chunks": [
    {
      "id": 1,
      "content": "第一个切片的完整内容...",
      "char_count": 1500
    },
    {
      "id": 2,
      "content": "第二个切片的完整内容...",
      "char_count": 1200
    }
  ]
}
```

## 参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--input` | 输入文件路径 | 必填 |
| `--output` | 输出 JSON 文件路径 | `<input>_chunks.json` |
| `--min-size` | 最小切片字符数 | 1000 |
| `--max-size` | 最大切片字符数 | 2000 |
| `--batch-size` | 每批处理的最大字符数 | 6000 |
| `--model` | LLM 模型名称 | `gpt-4o` |
| `--api-key` | API 密钥 | 环境变量 |
| `--base-url` | API 地址 | 环境变量 |
| `--verbose` | 显示详细日志 | false |

## 工作原理

1. **文档读取**：根据文件类型自动选择读取器
2. **大小判断**：判断文档是否需要分批处理
3. **分批处理**：大文档按段落边界分批，批次间有重叠确保连贯
4. **LLM 调用**：发送提示词给 LLM 进行语义分析
5. **输出续传**：检测 LLM 输出截断，自动发送继续请求
6. **结果合并**：合并多批次结果，处理边界切片

## 许可证

MIT