rag_jrxml/README.md

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 模式）

安装依赖

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

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

完整流程

# 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

快速查询

# 交互模式
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