panda
0787901acc
- 新增 md_chunker.py: Markdown语义分块引擎，支持标题/代码块/表格智能拆分 - 新增 batch_chunker.py: 统一批量分块入口，支持JRXML+Markdown混合处理 - 新增 requirements.txt: 整理项目依赖 - embed_chunks.py: 新增 --incremental 增量模式，追加新向量到已有数据 - import_to_chroma.py: 新增 --incremental 增量模式，不再每次清空数据库 - 更新 README.md 与 docs/file_guide.md 反映最新架构 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
174 lines
4.9 KiB
Markdown
174 lines
4.9 KiB
Markdown
# 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 模式)
|
|
|
|
### 安装
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### 配置
|
|
|
|
```bash
|
|
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` |
|
|
|
|
### 完整流程
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
### 增量更新
|
|
|
|
新增或修改部分文件时，无需重新处理全部数据：
|
|
|
|
```bash
|
|
# 分块新文件
|
|
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` | 代码块 |
|
|
|
|
## 查询
|
|
|
|
```bash
|
|
# 交互模式
|
|
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
|