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

安装与配置

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

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

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

步骤 2：向量化

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

# 全量向量化
python embed_chunks.py

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

步骤 3：导入 Chroma

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

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

步骤 4：查询

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

增量更新 — 追加新模板

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

# 步骤 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