rag_jrxml/README.md

# JRXML RAG 项目

基于 RAG 的 JasperReports JRXML 模板 + Markdown 文档智能检索系统，作为构建 JRXML 自定义 Agent 的前置工作。

支持 JRXML 模板和 Markdown 文档的语义分块、向量化、Chroma 持久化存储，以及自然语言查询。**三个核心步骤均支持增量处理**。

## 项目结构

```
rag_jrxml/
├── collect_jrxml.py              # JRXML 文件收集
├── jrxml_chunker.py              # JRXML 语义分块引擎 (v3.0)
├── md_chunker.py                 # Markdown 语义分块引擎
├── batch_chunker.py              # 统一批量分块入口 (JRXML + MD, 支持增量)
├── down_embedding_model.py       # 嵌入模型下载
├── embed_chunks.py               # Chunk 向量化 (支持增量)
├── import_to_chroma.py           # Chroma 向量入库 (支持增量)
├── query_chroma.py               # 语义搜索查询
├── config.py                     # 统一配置管理 (.env)
├── .env / .env.example           # 环境变量配置
├── requirements.txt              # Python 依赖
├── jrxml_source/                 # JRXML 源文件
├── jrxml_chunker_output/         # 分块输出
├── embeddings/                   # 向量输出
├── chroma_db/                    # Chroma 持久化数据库
└── docs/file_guide.md            # 详细文件功能说明
```

## 环境要求

- Python 3.11+
- NVIDIA GPU (推荐 8GB+ 显存) 或 CPU
- CUDA 12.1+ (GPU 模式)

## 安装与配置

```bash
pip install -r requirements.txt
cp .env.example .env              # 编辑 .env 调整模型、路径等参数
```

主要配置项：

| 变量 | 说明 | 默认值 |
| --- | --- | --- |
| `EMBEDDING_MODEL_NAME` | 嵌入模型 (Hub 名) | `Qwen/Qwen3-Embedding-0.6B` |
| `EMBEDDING_MODEL_PATH` | 本地模型路径 | `models/Qwen3-Embedding-0.6B` |
| `MAX_CHUNK_SIZE` | 单个 chunk 最大字符数 | `2000` |
| `BATCH_SIZE` | 向量化批大小 | `16` |
| `CHROMA_COLLECTION_NAME` | Chroma 集合名 | `jrxml_chunks` |

---

## 首次使用 — 全量建库

从头构建向量数据库，三个步骤顺序执行：

### 步骤 1：收集 & 分块

```bash
# 收集 JRXML 模板文件
python collect_jrxml.py

# 统一分块 (JRXML + Markdown 混合目录)
python batch_chunker.py ./jrxml_source --output ./jrxml_chunker_output
```

输出 `jrxml_chunker_output/all_chunks.json` 和 `processing_stats.json`。

### 步骤 2：向量化

```bash
# 下载嵌入模型 (仅首次)
python down_embedding_model.py

# 全量向量化
python embed_chunks.py
```

输出 `embeddings/embeddings.npy`、`chunks.json` 等文件。

### 步骤 3：导入 Chroma

```bash
# 全量导入 (创建新集合)
python import_to_chroma.py
```

输出 `chroma_db/` 持久化向量数据库。

### 步骤 4：查询

```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
```

---

## 增量更新 — 追加新模板

已有数据库后，添加新模板无需重建。将新文件放入源目录后：

```bash
# 步骤 1：增量分块 (自动跳过已处理文件，合并到已有结果)
python batch_chunker.py ./jrxml_source --incremental

# 步骤 2：增量向量化 (只对新 chunks 编码，合并到已有向量)
python embed_chunks.py --incremental

# 步骤 3：增量导入 (追加到已有集合，不删除现有数据)
python import_to_chroma.py --incremental
```

三个 `--incremental` 标志各自的工作逻辑：

| 步骤 | 如何识别已处理 | 无新数据时 |
| --- | --- | --- |
| `batch_chunker` | 对比 `processing_stats.json` 中的文件路径 | 输出 "没有新文件需要处理" |
| `embed_chunks` | 按 `(context, chunk_id)` 去重 | 输出 "没有新 chunks 需要向量化" |
| `import_to_chroma` | 查询 Chroma 已有 ID | 输出 "没有新数据需要导入" |

---

## 分块类型

### JRXML

| 类型 | 说明 |
|---|---|
| `report_overview` | 报表概览 (含数据源分析) |
| `datasource_config` | 数据源配置 |
| `query` | 数据查询 (SQL/HQL/XPath/JSON 等) |
| `parameters` | 参数定义 |
| `fields` / `field` | 字段定义 |
| `sortFields` | 排序字段 |
| `filterExpression` | 过滤表达式 |
| `variables_*` | 变量定义 (按 resetType) |
| `styles` | 样式定义 |
| `dataset` | 数据集定义 |
| `group` | 分组定义 |
| `band_*` | 标准带区 (title/detail/pageHeader 等) |
| `chart` | 图表元素 |
| `crosstab` | 交叉表元素 |
| `subreport` | 子报表元素 |
| `component` | 组件元素 (列表等) |

### Markdown

| 类型 | 说明 |
|---|---|
| `section_h1` | 一级标题段落 |
| `section_h2` / `section_h3` | 二/三级标题段落 |
| `section_installation` | 安装/部署章节 |
| `section_configuration` | 配置章节 |
| `section_api` | API 接口章节 |
| `section_example` | 示例/用法章节 |
| `section_faq` | FAQ/常见问题章节 |
| `section_changelog` | 更新日志章节 |
| `code` | 代码块 |

## 支持的 JRXML 数据源

SQL/JDBC · HQL/Hibernate · XPath/XML · JSON · JSONQL · CSV · Data Adapter (Excel/XML/HTTP) · Bean Collection · Empty

## 技术栈

- **分块引擎**: XML 语义解析 (JRXML) + Markdown 结构化解析
- **嵌入模型**: Qwen3-Embedding (支持 FP16, 可替换)
- **嵌入框架**: Sentence-Transformers
- **向量数据库**: ChromaDB (持久化, 余弦相似度)
- **深度学习**: PyTorch + CUDA (CPU 兼容)

## License

MIT