# JRXML RAG 项目

基于 RAG（Retrieval-Augmented Generation）的 JasperReports JRXML 模板智能问答系统。

## 项目简介

本项目将 JasperReports 的 JRXML 模板文件进行语义分块、向量化，并存入 Chroma 向量数据库，实现通过自然语言查询来检索和理解报表模板的结构、配置和逻辑。

## 项目结构

```
RAG-jaspersoft/
├── collect_jrxml.py              # JRXML 文件收集脚本
├── jrxml_chunker.py              # JRXML 语义分块核心引擎
├── jrxml_banch_chunker.py        # 批量分块入口脚本
├── down_embedding_model.py       # 嵌入模型下载脚本
├── embed_chunks.py               # Chunk 向量化脚本
├── import_to_chroma.py           # 向量导入 Chroma 数据库
├── query_chroma.py               # 语义搜索查询工具
├── jrxml_source/                 # JRXML 源文件目录
├── jrxml_chunker_output/         # 分块输出目录
│   ├── all_chunks.json           # 所有 chunks 合并文件
│   ├── processing_stats.json     # 处理统计报告
│   └── per_file/                 # 按文件分类的 chunks
├── models/                       # 嵌入模型存放目录
│   └── Qwen3-Embedding-4B/       # Qwen3 嵌入模型
├── embeddings/                   # 向量输出目录
│   ├── embeddings.npy            # 向量矩阵
│   ├── chunks.json               # 原始 chunks
│   └── embeddings.pkl            # 完整数据 pickle
├── chroma_db/                    # Chroma 向量数据库
└── docs/                         # 项目文档
    └── file_guide.md             # 文件功能说明
```

## 快速开始

### 环境要求

- Python 3.11+
- NVIDIA GPU（推荐，8GB+ 显存）或 CPU
- CUDA 12.1+（GPU 模式）

### 安装依赖

```bash
# 安装 PyTorch (CUDA 版本)
uv pip install torch --index-url https://download.pytorch.org/whl/cu130

# 安装其他依赖
uv pip install sentence-transformers chromadb numpy tqdm
```

### 完整流程

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

# 2. 语义分块
python jrxml_banch_chunker.py ./jrxml_source --output ./jrxml_chunker_output

# 3. 下载嵌入模型（首次运行）
python down_embedding_model.py

# 4. 向量化
python embed_chunks.py --batch_size 2

# 5. 导入 Chroma 数据库
python import_to_chroma.py

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

### 快速查询

```bash
# 交互模式
python query_chroma.py

# 单次查询
python query_chroma.py "如何修改报表标题"

# 按类型过滤
python query_chroma.py "SQL查询怎么写" --filter_field query
```

## 分块类型

系统将 JRXML 模板按以下语义类型进行分块：

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

## 技术栈

- **分块引擎**: 基于 XML 解析的语义分块器
- **嵌入模型**: Qwen3-Embedding-4B（支持 FP16 半精度）
- **向量数据库**: ChromaDB（持久化模式，余弦相似度）
- **嵌入框架**: Sentence-Transformers
- **深度学习**: PyTorch + CUDA

## 性能参考

| 硬件 | 模型 | Batch Size | 速度 |
|------|------|-----------|------|
| RTX 4060 Laptop 8GB | Qwen3-Embedding-4B (FP16) | 2 | ~1.2s/chunk |
| RTX 4060 Laptop 8GB | all-MiniLM-L6-v2 | 64 | ~0.001s/chunk |

> 离线建库是一次性开销，在线查询仅需 1-2 秒。

## License

MIT