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)
├── jrxml_banch_chunker.py        # JRXML 批量分块 (单类型)
├── 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/         # 分块输出
│   ├── all_chunks.json
│   ├── processing_stats.json
│   └── per_file/
├── models/                       # 本地嵌入模型
├── embeddings/                   # 向量输出
│   ├── embeddings.npy
│   ├── chunks.json
│   └── embeddings.pkl
├── chroma_db/                    # Chroma 持久化数据库
└── docs/
    └── file_guide.md

快速开始

环境要求

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

安装

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. 收集 JRXML 文件
python collect_jrxml.py

# 2. 统一分块 (JRXML + Markdown)
python batch_chunker.py ./jrxml_source --output ./jrxml_chunker_output

# 3. 下载嵌入模型 (首次)
python down_embedding_model.py

# 4. 向量化
python embed_chunks.py

# 5. 导入 Chroma
python import_to_chroma.py

# 6. 查询
python query_chroma.py

增量更新

新增或修改部分文件时，无需重新处理全部数据：

# 分块新文件
python batch_chunker.py ./new_files --output ./jrxml_chunker_output/new_batch

# 增量向量化 (只处理新 chunks)
python embed_chunks.py ./jrxml_chunker_output/new_batch/all_chunks.json --incremental

# 增量导入 (不删除已有数据)
python import_to_chroma.py --incremental

分块类型

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	代码块

查询

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

支持的 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