chore: 初始化JRXML RAG项目，添加基础文件

创建了完整的JRXML语义检索RAG项目，包含： 1. 新增.gitignore忽略项目生成的缓存、依赖目录和本地文件 2. 编写详细的项目README文档 3. 补充文件功能说明文档 4. 实现向量导入、向量化、查询等核心脚本
2026-05-12 08:14:55 +08:00
parent 4f475e9e36
commit bd98486de0
6 changed files with 1030 additions and 42 deletions
@@ -0,0 +1,131 @@
+# 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