rag_jrxml/docs/file_guide.md

# 文件功能说明

本文档详细解释项目中每个 Python 脚本的功能、输入输出和使用方式。

---

## 1. collect_jrxml.py — JRXML 文件收集

**功能**: 从 JasperReports 模板库目录递归收集 `.jrxml` 文件，复制到项目 `jrxml_source` 目录。

**使用方式**:
```bash
python collect_jrxml.py
```

---

## 2. jrxml_chunker.py — JRXML 语义分块引擎 (v3.0)

**功能**: 将单个 JRXML 文件按语义结构拆分。被 `batch_chunker.py` 调用，也可单独使用。

**输入**: 单个 `.jrxml` 文件路径（或目录）

**输出**: `JRXMLChunk` 列表，字段包括:
- `chunk_id`: 文件内序号
- `chunk_type`: 分块类型 (`query`, `band_detail`, `chart` 等)
- `human_description`: 人类可读描述
- `raw_xml`: 原始 XML 片段
- `context`: 所属报表名称
- `metadata`: 元数据 (report_name, band_name, element_kind 等)

**单独使用**:
```bash
python jrxml_chunker.py report.jrxml          # 单文件
python jrxml_chunker.py ./jrxml_source/       # 目录
```

---

## 3. md_chunker.py — Markdown 语义分块引擎

**功能**: 将 Markdown 文件按标题层级、代码块、表格等结构化元素智能分块。被 `batch_chunker.py` 调用，也可单独使用。

**分块策略**:
- 按标题层级 (H1/H2/H3) 划分段落，H2 自动识别特殊类型
- 代码块、表格作为独立 chunk
- 过长段落按段落/句子二次拆分

**单独使用**:
```bash
python md_chunker.py doc.md                   # 单文件
python md_chunker.py ./docs/                  # 目录
```

---

## 4. batch_chunker.py — 统一批量分块入口

**功能**: 统一入口，支持 JRXML + Markdown 混合批量处理。**支持增量模式**。

**输出**:
- `all_chunks.json`: 所有 chunks 合并
- `processing_stats.json`: 处理统计 (文件级 chunk 数量、类型分布)

**全量模式** — 首次建库:
```bash
python batch_chunker.py ./jrxml_source --output ./jrxml_chunker_output
```

**增量模式** (`--incremental`) — 追加新文件:
```bash
python batch_chunker.py ./jrxml_source --incremental
```

增量模式逻辑：
1. 加载已有 `processing_stats.json`，获取已处理文件列表
2. 扫描输入目录，自动跳过已处理文件
3. 只分块新增文件
4. 合并新旧 `all_chunks.json` 和统计数据后保存

---

## 5. down_embedding_model.py — 嵌入模型下载

**功能**: 从 HuggingFace Hub 下载嵌入模型到本地。支持国内镜像 (`hf-mirror.com`)、断点续传。

```bash
python down_embedding_model.py
```

---

## 6. embed_chunks.py — Chunk 向量化

**功能**: 将 chunks 转换为向量。支持 GPU/CPU、FP16 半精度，**支持增量模式**。

**输出**:
- `embeddings/embeddings.npy`: 向量矩阵 (float32)
- `embeddings/chunks.json`: 原始 chunks
- `embeddings/chunk_id_map.json` / `chunk_type_map.json`
- `embeddings/embeddings.pkl`: 完整 pickle

**全量模式** — 首次向量化:
```bash
python embed_chunks.py
python embed_chunks.py --batch_size 2                         # 调整批大小
python embed_chunks.py --model_path "all-MiniLM-L6-v2"        # 换模型
python embed_chunks.py --no_fp16                              # 禁用半精度
```

**增量模式** (`--incremental` / `-i`) — 只编码新 chunks:
```bash
python embed_chunks.py --incremental
```

增量模式逻辑：
1. 加载已有 `embeddings.npy` + `chunks.json`
2. 按 `(context, chunk_id)` 去重
3. 只向量化新 chunks
4. 合并新旧数据后保存

---

## 7. import_to_chroma.py — Chroma 向量入库

**功能**: 将向量数据导入 Chroma 持久化数据库。**支持增量模式**。

**全量模式** — 首次导入 (删除旧集合重建):
```bash
python import_to_chroma.py
```

**增量模式** (`--incremental` / `-i`) — 追加新记录:
```bash
python import_to_chroma.py --incremental
```

增量模式逻辑：
1. `get_or_create_collection` (不删除已有数据)
2. 查询 Chroma 已有 ID
3. 跳过已导入的记录，只追加新数据

---

## 8. query_chroma.py — 语义搜索查询

**功能**: 通过自然语言查询 Chroma 数据库。

**两种模式**:
- **单次查询**: `python query_chroma.py "查询内容"`
- **交互模式**: `python query_chroma.py`（支持连续查询和内联命令）

**交互模式命令**:
```
filter:<类型>     按 chunk_type 过滤 (如 filter:query)
t:<阈值>          相似度阈值 0~1 (如 t:0.5)
k:<数量>          返回结果数 (如 k:10)
```

**使用示例**:
```bash
python query_chroma.py                                    # 交互模式
python query_chroma.py "如何修改报表标题"                   # 单次查询
python query_chroma.py "SQL怎么写" --filter_field query
python query_chroma.py "参数" --threshold 0.5 --n_results 10
```

---

## 9. config.py — 统一配置管理

**功能**: 从 `.env` 加载所有配置，所有脚本通过此模块获取配置项。

```bash
python config.py   # 打印当前配置
```

---

## 10. jrxml_banch_chunker.py — 旧版入口 (已废弃)

**功能**: JRXML 单类型批量分块。已被 `batch_chunker.py` 取代，保留以兼容旧流程。

---

## 使用场景

### 场景 A：首次构建数据库

```bash
# 1. 准备源文件
python collect_jrxml.py
# 将 Markdown 文档放入 jrxml_source/ 或指定目录

# 2. 全量分块
python batch_chunker.py ./jrxml_source

# 3. 下载模型 + 全量向量化
python down_embedding_model.py
python embed_chunks.py

# 4. 全量导入
python import_to_chroma.py

# 5. 开始查询
python query_chroma.py
```

### 场景 B：追加新模板/文档

```bash
# 将新 .jrxml / .md 文件放入源目录后：

# 1. 增量分块 — 自动跳过已处理文件
python batch_chunker.py ./jrxml_source --incremental

# 2. 增量向量化 — 只编码新 chunks
python embed_chunks.py --incremental

# 3. 增量导入 — 追加到已有数据库
python import_to_chroma.py --incremental
```

### 场景 C：更换嵌入模型

```bash
# 1. 编辑 .env 修改 EMBEDDING_MODEL_NAME / EMBEDDING_MODEL_PATH
# 2. 下载新模型
python down_embedding_model.py

# 3. 重新向量化 (全量)
python embed_chunks.py

# 4. 重建数据库
python import_to_chroma.py
```

---

## 数据流

```
┌─────────────────────┐
│ JRXML 模板 (.jrxml)  │
│ Markdown 文档 (.md)  │
└──────────┬──────────┘
           │ collect_jrxml.py / 手动放置
           ▼
┌─────────────────────┐
│ jrxml_source/       │
└──────────┬──────────┘
           │ batch_chunker.py [--incremental]
           ▼
┌──────────────────────┐
│ jrxml_chunker_output/│  all_chunks.json
└──────────┬───────────┘
           │ embed_chunks.py [--incremental]
           ▼
┌─────────────────┐
│ embeddings/     │  embeddings.npy + chunks.json
└────────┬────────┘
         │ import_to_chroma.py [--incremental]
         ▼
┌─────────────────┐
│ chroma_db/      │  Chroma 向量数据库
└────────┬────────┘
         │ query_chroma.py
         ▼
┌─────────────────┐
│ 自然语言查询     │  返回相关 chunks
└─────────────────┘
```

## 依赖关系

```
query_chroma.py ──────────► chromadb, sentence_transformers, torch
import_to_chroma.py ──────► chromadb, numpy
embed_chunks.py ──────────► sentence_transformers, torch, numpy
down_embedding_model.py ──► huggingface_hub
batch_chunker.py ─────────► jrxml_chunker.py, md_chunker.py
md_chunker.py ────────────► 标准库 (re, json, pathlib)
jrxml_chunker.py ─────────► xml.etree.ElementTree (标准库)
config.py ────────────────► 标准库 (os, pathlib)
collect_jrxml.py ─────────► 标准库 (os, shutil)
```