rag_jrxml/docs/file_guide.md

# 文件功能说明

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

---

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

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

**输入**: 源目录路径（硬编码，可按需修改）

**输出**: `jrxml_source/` 目录

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

---

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

**功能**: 将单个 JRXML 文件按语义结构拆分，每个 chunk 包含人类可读描述、原始 XML 和结构化元数据。

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

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

**支持的数据源**: SQL, HQL, XPath, JSON, JSONQL, CSV, Data Adapter, Bean Collection, Empty

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

---

## 3. jrxml_banch_chunker.py — JRXML 批量分块 (单类型)

**功能**: 批量处理目录下所有 JRXML 文件，生成统计报告和按文件分类的输出。是旧版入口，被 `batch_chunker.py` 取代。

**使用方式**:
```bash
python jrxml_banch_chunker.py ./jrxml_source --output ./output
```

---

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

**功能**: 将 Markdown 文件按标题层级、代码块、表格等结构化元素智能分块。

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

**输出**: `MDChunk` 列表，字段包括:
- `chunk_id`: 文件内序号
- `chunk_type`: 分块类型 (`section_h1`, `code`, `section_installation` 等)
- `human_description`: 人类可读描述
- `raw_content`: 原始 Markdown 内容
- `context`: 所属文档标题
- `metadata`: 元数据 (heading, heading_level, language 等)

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

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

---

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

**功能**: 统一入口，支持 JRXML 和 Markdown 文件混合批量处理，生成合并的 chunks 和统计报告。

**输入**: 包含 `.jrxml` / `.md` 文件的目录

**输出**:
- `all_chunks.json`: 所有 chunks 合并
- `processing_stats.json`: 处理统计 (成功/失败/耗时/类型分布)

**使用方式**:
```bash
python batch_chunker.py ./mixed_source
python batch_chunker.py ./mixed_source --output ./my_output
```

---

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

**功能**: 从 HuggingFace Hub 下载嵌入模型到本地。支持国内镜像加速和断点续传。

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

---

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

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

**输入**: chunks JSON 文件 (默认 `jrxml_chunker_output/all_chunks.json`)

**输出**:
- `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 "sentence-transformers/all-MiniLM-L6-v2"
```

**增量模式** (`--incremental` / `-i`):
```bash
# 只向量化新增 chunks，自动合并到已有向量数据
python embed_chunks.py ./new_chunks/all_chunks.json --incremental
```

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

---

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

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

**输入**: `embeddings/embeddings.npy` + `embeddings/chunks.json`

**输出**: `chroma_db/` 持久化数据库

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

**增量模式** (`--incremental` / `-i`):
```bash
# 追加新记录到已有集合，不删除已有数据
python import_to_chroma.py --incremental
```

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

---

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

**功能**: 通过自然语言查询 Chroma 数据库，检索相关的 JRXML/Markdown chunks。

**两种模式**:
- 命令行单次查询: `python query_chroma.py "查询内容"`
- 交互模式: `python query_chroma.py` (支持连续查询)

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

**使用方式**:
```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
```

---

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

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

**配置分组**:
- 模型配置: `EMBEDDING_MODEL_NAME`, `EMBEDDING_MODEL_PATH`, `HF_ENDPOINT`
- 硬件配置: `USE_GPU`, `USE_FP16`, `BATCH_SIZE`
- 目录配置: `JRXML_SOURCE_DIR`, `CHUNKER_OUTPUT_DIR`, `EMBEDDINGS_DIR`, `CHROMA_DB_PATH`
- 分块配置: `MAX_CHUNK_SIZE`
- 查询配置: `DEFAULT_N_RESULTS`, `SIMILARITY_THRESHOLD`

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

---

## 数据流全景

```
┌─────────────────────┐
│ JasperReports 模板库 │  (.jrxml)
│ Markdown 文档        │  (.md)
└──────────┬──────────┘
           │ collect_jrxml.py / 手动放置
           ▼
┌─────────────────────┐
│ jrxml_source/       │  源文件目录
│ docs/               │
└──────────┬──────────┘
           │ batch_chunker.py (调用 jrxml_chunker.py + md_chunker.py)
           ▼
┌──────────────────────┐
│ jrxml_chunker_output/│  all_chunks.json + processing_stats.json
└──────────┬───────────┘
           │ embed_chunks.py (Qwen3-Embedding, 支持增量)
           ▼
┌─────────────────┐
│ embeddings/     │  embeddings.npy + chunks.json
└────────┬────────┘
         │ import_to_chroma.py (ChromaDB, 支持增量)
         ▼
┌─────────────────┐
│ 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)
```