panda/rag_jrxml
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新文档，区分首次全量与增量更新两种使用场景

Browse Source 
- README.md: 拆分为"首次使用"和"增量更新"两个独立章节
- docs/file_guide.md: 新增三种使用场景 (首次建库/追加模板/换模型)
- 补充三个 --incremental 标志的工作逻辑对比表

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
panda
2026-05-15 11:26:54 +08:00
parent ea44096b12
commit 9b913302fd
2 changed files with 194 additions and 163 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+73 -65
View File
@@ -2,7 +2,7 @@
基于 RAG 的 JasperReports JRXML 模板 + Markdown 文档智能检索系统，作为构建 JRXML 自定义 Agent 的前置工作。 基于 RAG 的 JasperReports JRXML 模板 + Markdown 文档智能检索系统，作为构建 JRXML 自定义 Agent 的前置工作。
支持 JRXML 模板和 Markdown 文档的语义分块、向量化、Chroma 持久化存储，以及自然语言查询。 支持 JRXML 模板和 Markdown 文档的语义分块、向量化、Chroma 持久化存储，以及自然语言查询。**三个核心步骤均支持增量处理**。
## 项目结构 ## 项目结构
@@ -10,102 +10,126 @@
rag_jrxml/ rag_jrxml/
├── collect_jrxml.py # JRXML 文件收集 ├── collect_jrxml.py # JRXML 文件收集
├── jrxml_chunker.py # JRXML 语义分块引擎 (v3.0) ├── jrxml_chunker.py # JRXML 语义分块引擎 (v3.0)
├── jrxml_banch_chunker.py # JRXML 批量分块 (单类型)
├── md_chunker.py # Markdown 语义分块引擎 ├── md_chunker.py # Markdown 语义分块引擎
├── batch_chunker.py # 统一批量分块入口 (JRXML + MD) ├── batch_chunker.py # 统一批量分块入口 (JRXML + MD, 支持增量)
├── down_embedding_model.py # 嵌入模型下载 ├── down_embedding_model.py # 嵌入模型下载
├── embed_chunks.py # Chunk 向量化 (支持增量) ├── embed_chunks.py # Chunk 向量化 (支持增量)
├── import_to_chroma.py # Chroma 向量入库 (支持增量) ├── import_to_chroma.py # Chroma 向量入库 (支持增量)
├── query_chroma.py # 语义搜索查询 ├── query_chroma.py # 语义搜索查询
├── config.py # 统一配置管理 (.env) ├── config.py # 统一配置管理 (.env)
├── .env # 环境变量配置 ├── .env / .env.example # 环境变量配置
├── .env.example # 配置模板
├── requirements.txt # Python 依赖 ├── requirements.txt # Python 依赖
├── jrxml_source/ # JRXML 源文件 ├── jrxml_source/ # JRXML 源文件
├── jrxml_chunker_output/ # 分块输出 ├── jrxml_chunker_output/ # 分块输出
│ ├── all_chunks.json
│ ├── processing_stats.json
│ └── per_file/
├── models/ # 本地嵌入模型
├── embeddings/ # 向量输出 ├── embeddings/ # 向量输出
│ ├── embeddings.npy
│ ├── chunks.json
│ └── embeddings.pkl
├── chroma_db/ # Chroma 持久化数据库 ├── chroma_db/ # Chroma 持久化数据库
└── docs/ └── docs/file_guide.md # 详细文件功能说明
└── file_guide.md
``` ```
## 快速开始 ## 环境要求
### 环境要求
- Python 3.11+ - Python 3.11+
- NVIDIA GPU (推荐 8GB+ 显存) 或 CPU - NVIDIA GPU (推荐 8GB+ 显存) 或 CPU
- CUDA 12.1+ (GPU 模式) - CUDA 12.1+ (GPU 模式)
### 安装 ## 安装与配置
```bash ```bash
pip install -r requirements.txt pip install -r requirements.txt
``` cp .env.example .env # 编辑 .env 调整模型、路径等参数
### 配置
```bash
cp .env.example .env # 编辑 .env 调整模型、路径等参数
``` ```
主要配置项： 主要配置项：
| 变量 | 说明 | 默认值 | | 变量 | 说明 | 默认值 |
|---|---|---| | --- | --- | --- |
| `EMBEDDING_MODEL_NAME` | 嵌入模型 (Hub 名) | `Qwen/Qwen3-Embedding-0.6B` | | `EMBEDDING_MODEL_NAME` | 嵌入模型 (Hub 名) | `Qwen/Qwen3-Embedding-0.6B` |
| `EMBEDDING_MODEL_PATH` | 本地模型路径 | `models/Qwen3-Embedding-0.6B` | | `EMBEDDING_MODEL_PATH` | 本地模型路径 | `models/Qwen3-Embedding-0.6B` |
| `MAX_CHUNK_SIZE` | 单个 chunk 最大字符数 | `2000` | | `MAX_CHUNK_SIZE` | 单个 chunk 最大字符数 | `2000` |
| `BATCH_SIZE` | 向量化批大小 | `16` | | `BATCH_SIZE` | 向量化批大小 | `16` |
| `CHROMA_COLLECTION_NAME` | Chroma 集合名 | `jrxml_chunks` | | `CHROMA_COLLECTION_NAME` | Chroma 集合名 | `jrxml_chunks` |
### 完整流程 ---
## 首次使用 — 全量建库
从头构建向量数据库，三个步骤顺序执行：
### 步骤 1：收集 & 分块
```bash ```bash
# 1. 收集 JRXML 文件 # 收集 JRXML 模板文件
python collect_jrxml.py python collect_jrxml.py
# 2. 统一分块 (JRXML + Markdown) # 统一分块 (JRXML + Markdown 混合目录)
python batch_chunker.py ./jrxml_source --output ./jrxml_chunker_output 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
``` ```
### 增量更新 输出 `jrxml_chunker_output/all_chunks.json` 和 `processing_stats.json`。
新增或修改部分文件时，无需重新处理全部数据： ### 步骤 2：向量化
```bash ```bash
# 分块新文件 # 下载嵌入模型 (仅首次)
python batch_chunker.py ./new_files --output ./jrxml_chunker_output/new_batch python down_embedding_model.py
# 增量向量化 (只处理新 chunks) # 全量向量化
python embed_chunks.py ./jrxml_chunker_output/new_batch/all_chunks.json --incremental python embed_chunks.py
```
# 增量导入 (不删除已有数据) 输出 `embeddings/embeddings.npy`、`chunks.json` 等文件。
### 步骤 3：导入 Chroma
```bash
# 全量导入 (创建新集合)
python import_to_chroma.py
```
输出 `chroma_db/` 持久化向量数据库。
### 步骤 4：查询
```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
```
---
## 增量更新 — 追加新模板
已有数据库后，添加新模板无需重建。将新文件放入源目录后：
```bash
# 步骤 1：增量分块 (自动跳过已处理文件，合并到已有结果)
python batch_chunker.py ./jrxml_source --incremental
# 步骤 2：增量向量化 (只对新 chunks 编码，合并到已有向量)
python embed_chunks.py --incremental
# 步骤 3：增量导入 (追加到已有集合，不删除现有数据)
python import_to_chroma.py --incremental python import_to_chroma.py --incremental
``` ```
三个 `--incremental` 标志各自的工作逻辑：
| 步骤 | 如何识别已处理 | 无新数据时 |
| --- | --- | --- |
| `batch_chunker` | 对比 `processing_stats.json` 中的文件路径 | 输出 "没有新文件需要处理" |
| `embed_chunks` | 按 `(context, chunk_id)` 去重 | 输出 "没有新 chunks 需要向量化" |
| `import_to_chroma` | 查询 Chroma 已有 ID | 输出 "没有新数据需要导入" |
---
## 分块类型 ## 分块类型
### JRXML 分块 ### JRXML
| 类型 | 说明 | | 类型 | 说明 |
|---|---| |---|---|
@@ -126,7 +150,7 @@ python import_to_chroma.py --incremental
| `subreport` | 子报表元素 | | `subreport` | 子报表元素 |
| `component` | 组件元素 (列表等) | | `component` | 组件元素 (列表等) |
### Markdown 分块 ### Markdown
| 类型 | 说明 | | 类型 | 说明 |
|---|---| |---|---|
@@ -140,22 +164,6 @@ python import_to_chroma.py --incremental
| `section_changelog` | 更新日志章节 | | `section_changelog` | 更新日志章节 |
| `code` | 代码块 | | `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 数据源 ## 支持的 JRXML 数据源
SQL/JDBC · HQL/Hibernate · XPath/XML · JSON · JSONQL · CSV · Data Adapter (Excel/XML/HTTP) · Bean Collection · Empty SQL/JDBC · HQL/Hibernate · XPath/XML · JSON · JSONQL · CSV · Data Adapter (Excel/XML/HTTP) · Bean Collection · Empty
docs/file_guide.md
+121 -98
View File
@@ -8,10 +8,6 @@
**功能**: 从 JasperReports 模板库目录递归收集 `.jrxml` 文件，复制到项目 `jrxml_source` 目录。 **功能**: 从 JasperReports 模板库目录递归收集 `.jrxml` 文件，复制到项目 `jrxml_source` 目录。
**输入**: 源目录路径（硬编码，可按需修改）
**输出**: `jrxml_source/` 目录
**使用方式**: **使用方式**:
```bash ```bash
python collect_jrxml.py python collect_jrxml.py
@@ -21,21 +17,19 @@ python collect_jrxml.py
## 2. jrxml_chunker.py — JRXML 语义分块引擎 (v3.0) ## 2. jrxml_chunker.py — JRXML 语义分块引擎 (v3.0)
**功能**: 将单个 JRXML 文件按语义结构拆分，每个 chunk 包含人类可读描述、原始 XML 和结构化元数据。 **功能**: 将单个 JRXML 文件按语义结构拆分。被 `batch_chunker.py` 调用，也可单独使用。
**输入**: 单个 `.jrxml` 文件路径（或目录） **输入**: 单个 `.jrxml` 文件路径（或目录）
**输出**: `JRXMLChunk` 列表，字段包括: **输出**: `JRXMLChunk` 列表，字段包括:
- `chunk_id`: 文件内序号 - `chunk_id`: 文件内序号
- `chunk_type`: 分块类型 (如 `query`, `band_detail`, `chart` 等) - `chunk_type`: 分块类型 (`query`, `band_detail`, `chart` 等)
- `human_description`: 人类可读描述 - `human_description`: 人类可读描述
- `raw_xml`: 原始 XML 片段 - `raw_xml`: 原始 XML 片段
- `context`: 所属报表名称 - `context`: 所属报表名称
- `metadata`: 元数据 (report_name, band_name, element_kind 等) - `metadata`: 元数据 (report_name, band_name, element_kind 等)
**支持的数据源**: SQL, HQL, XPath, JSON, JSONQL, CSV, Data Adapter, Bean Collection, Empty **单独使用**:
**使用方式**:
```bash ```bash
python jrxml_chunker.py report.jrxml # 单文件 python jrxml_chunker.py report.jrxml # 单文件
python jrxml_chunker.py ./jrxml_source/ # 目录 python jrxml_chunker.py ./jrxml_source/ # 目录
@@ -43,39 +37,16 @@ python jrxml_chunker.py ./jrxml_source/ # 目录
--- ---
## 3. jrxml_banch_chunker.py — JRXML 批量分块 (单类型) ## 3. md_chunker.py — Markdown 语义分块引擎
**功能**: 批量处理目录下所有 JRXML 文件，生成统计报告和按文件分类的输出。是旧版入口，被 `batch_chunker.py` 取代。 **功能**: 将 Markdown 文件按标题层级、代码块、表格等结构化元素智能分块。被 `batch_chunker.py` 调用，也可单独使用。
**使用方式**:
```bash
python jrxml_banch_chunker.py ./jrxml_source --output ./output
```
---
## 4. md_chunker.py — Markdown 语义分块引擎
**功能**: 将 Markdown 文件按标题层级、代码块、表格等结构化元素智能分块。
**输入**: 单个 `.md` 文件路径（或目录）
**输出**: `MDChunk` 列表，字段包括:
- `chunk_id`: 文件内序号
- `chunk_type`: 分块类型 (`section_h1`, `code`, `section_installation` 等)
- `human_description`: 人类可读描述
- `raw_content`: 原始 Markdown 内容
- `context`: 所属文档标题
- `metadata`: 元数据 (heading, heading_level, language 等)
**分块策略**: **分块策略**:
- 按标题层级 (H1/H2/H3) 划分段落 - 按标题层级 (H1/H2/H3) 划分段落，H2 自动识别特殊类型
- 代码块作为独立 chunk - 代码块、表格作为独立 chunk
- 表格作为独立 chunk
- H2 标题自动识别特殊类型（安装、配置、API、示例等）
- 过长段落按段落/句子二次拆分 - 过长段落按段落/句子二次拆分
**使用方式**: **单独使用**:
```bash ```bash
python md_chunker.py doc.md # 单文件 python md_chunker.py doc.md # 单文件
python md_chunker.py ./docs/ # 目录 python md_chunker.py ./docs/ # 目录
@@ -83,58 +54,63 @@ python md_chunker.py ./docs/ # 目录
--- ---
## 5. batch_chunker.py — 统一批量分块入口 ## 4. batch_chunker.py — 统一批量分块入口
**功能**: 统一入口，支持 JRXML 和 Markdown 文件混合批量处理，生成合并的 chunks 和统计报告。 **功能**: 统一入口，支持 JRXML + Markdown 混合批量处理。**支持增量模式**。
**输入**: 包含 `.jrxml` / `.md` 文件的目录
**输出**: **输出**:
- `all_chunks.json`: 所有 chunks 合并 - `all_chunks.json`: 所有 chunks 合并
- `processing_stats.json`: 处理统计 (成功/失败/耗时/类型分布) - `processing_stats.json`: 处理统计 (文件级 chunk 数量、类型分布)
**使用方式**: **全量模式** — 首次建库:
```bash ```bash
python batch_chunker.py ./mixed_source python batch_chunker.py ./jrxml_source --output ./jrxml_chunker_output
python batch_chunker.py ./mixed_source --output ./my_output
``` ```
**增量模式** (`--incremental`) — 追加新文件:
```bash
python batch_chunker.py ./jrxml_source --incremental
```
增量模式逻辑：
1. 加载已有 `processing_stats.json`，获取已处理文件列表
2. 扫描输入目录，自动跳过已处理文件
3. 只分块新增文件
4. 合并新旧 `all_chunks.json` 和统计数据后保存
--- ---
## 6. down_embedding_model.py — 嵌入模型下载 ## 5. down_embedding_model.py — 嵌入模型下载
**功能**: 从 HuggingFace Hub 下载嵌入模型到本地。支持国内镜像加速和断点续传。 **功能**: 从 HuggingFace Hub 下载嵌入模型到本地。支持国内镜像 (`hf-mirror.com`)、断点续传。
**使用方式**:
```bash ```bash
python down_embedding_model.py python down_embedding_model.py
``` ```
--- ---
## 7. embed_chunks.py — Chunk 向量化 ## 6. embed_chunks.py — Chunk 向量化
**功能**: 使用嵌入模型将 chunks 转换为向量。支持 GPU/CPU、FP16 半精度，**支持增量模式**。 **功能**: 将 chunks 转换为向量。支持 GPU/CPU、FP16 半精度，**支持增量模式**。
**输入**: chunks JSON 文件 (默认 `jrxml_chunker_output/all_chunks.json`)
**输出**: **输出**:
- `embeddings/embeddings.npy`: 向量矩阵 (float32) - `embeddings/embeddings.npy`: 向量矩阵 (float32)
- `embeddings/chunks.json`: 原始 chunks - `embeddings/chunks.json`: 原始 chunks
- `embeddings/chunk_id_map.json` / `chunk_type_map.json`: 映射文件 - `embeddings/chunk_id_map.json` / `chunk_type_map.json`
- `embeddings/embeddings.pkl`: 完整数据 pickle - `embeddings/embeddings.pkl`: 完整 pickle
**全量模式**: **全量模式** — 首次向量化:
```bash ```bash
python embed_chunks.py python embed_chunks.py
python embed_chunks.py --batch_size 2 python embed_chunks.py --batch_size 2 # 调整批大小
python embed_chunks.py --model_path "sentence-transformers/all-MiniLM-L6-v2" python embed_chunks.py --model_path "all-MiniLM-L6-v2" # 换模型
python embed_chunks.py --no_fp16 # 禁用半精度
``` ```
**增量模式** (`--incremental` / `-i`): **增量模式** (`--incremental` / `-i`) — 只编码新 chunks:
```bash ```bash
# 只向量化新增 chunks，自动合并到已有向量数据 python embed_chunks.py --incremental
python embed_chunks.py ./new_chunks/all_chunks.json --incremental
``` ```
增量模式逻辑： 增量模式逻辑：
@@ -145,67 +121,55 @@ python embed_chunks.py ./new_chunks/all_chunks.json --incremental
--- ---
## 8. import_to_chroma.py — Chroma 向量入库 ## 7. import_to_chroma.py — Chroma 向量入库
**功能**: 将向量数据导入 Chroma 持久化数据库。**支持增量模式**。 **功能**: 将向量数据导入 Chroma 持久化数据库。**支持增量模式**。
**输入**: `embeddings/embeddings.npy` + `embeddings/chunks.json` **全量模式** — 首次导入 (删除旧集合重建):
**输出**: `chroma_db/` 持久化数据库
**全量模式** (删除旧集合重建):
```bash ```bash
python import_to_chroma.py python import_to_chroma.py
``` ```
**增量模式** (`--incremental` / `-i`): **增量模式** (`--incremental` / `-i`) — 追加新记录:
```bash ```bash
# 追加新记录到已有集合，不删除已有数据
python import_to_chroma.py --incremental python import_to_chroma.py --incremental
``` ```
增量模式逻辑： 增量模式逻辑：
1. 使用 `get_or_create_collection` (不删除已有数据) 1. `get_or_create_collection` (不删除已有数据)
2. 查询已有 ID，跳过已导入的记录 2. 查询 Chroma 已有 ID
3. 只追加新增数据 3. 跳过已导入的记录，只追加新数据
--- ---
## 9. query_chroma.py — 语义搜索查询 ## 8. query_chroma.py — 语义搜索查询
**功能**: 通过自然语言查询 Chroma 数据库，检索相关的 JRXML/Markdown chunks。 **功能**: 通过自然语言查询 Chroma 数据库。
**两种模式**: **两种模式**:
- 命令行单次查询: `python query_chroma.py "查询内容"` - **单次查询**: `python query_chroma.py "查询内容"`
- 交互模式: `python query_chroma.py` (支持连续查询) - **交互模式**: `python query_chroma.py`（支持连续查询和内联命令）
**交互模式命令**: **交互模式命令**:
``` ```
filter:<类型> 按 chunk_type 过滤 (如 filter:query) filter:<类型> 按 chunk_type 过滤 (如 filter:query)
t:<阈值> 设置相似度阈值 0~1 t:<阈值> 相似度阈值 0~1 (如 t:0.5)
k:<数量> 设置返回结果数 k:<数量> 返回结果数 (如 k:10)
``` ```
**使用方式**: **使用示例**:
```bash ```bash
python query_chroma.py # 交互模式 python query_chroma.py # 交互模式
python query_chroma.py "如何修改报表标题" # 单次查询 python query_chroma.py "如何修改报表标题" # 单次查询
python query_chroma.py "SQL怎么写" --filter_field query python query_chroma.py "SQL怎么写" --filter_field query
python query_chroma.py "参数" --threshold 0.5 --n_results 10 python query_chroma.py "参数" --threshold 0.5 --n_results 10
``` ```
--- ---
## 10. config.py — 统一配置管理 ## 9. config.py — 统一配置管理
**功能**: 从 `.env` 文件加载所有配置项，所有脚本通过此模块获取配置。 **功能**: 从 `.env` 加载所有配置，所有脚本通过此模块获取配置项。
**配置分组**:
- 模型配置: `EMBEDDING_MODEL_NAME`, `EMBEDDING_MODEL_PATH`, `HF_ENDPOINT`
- 硬件配置: `USE_GPU`, `USE_FP16`, `BATCH_SIZE`
- 目录配置: `JRXML_SOURCE_DIR`, `CHUNKER_OUTPUT_DIR`, `EMBEDDINGS_DIR`, `CHROMA_DB_PATH`
- 分块配置: `MAX_CHUNK_SIZE`
- 查询配置: `DEFAULT_N_RESULTS`, `SIMILARITY_THRESHOLD`
```bash ```bash
python config.py # 打印当前配置 python config.py # 打印当前配置
@@ -213,30 +177,89 @@ python config.py # 打印当前配置
--- ---
## 数据流全景 ## 10. jrxml_banch_chunker.py — 旧版入口 (已废弃)
**功能**: JRXML 单类型批量分块。已被 `batch_chunker.py` 取代，保留以兼容旧流程。
---
## 使用场景
### 场景 A：首次构建数据库
```bash
# 1. 准备源文件
python collect_jrxml.py
# 将 Markdown 文档放入 jrxml_source/ 或指定目录
# 2. 全量分块
python batch_chunker.py ./jrxml_source
# 3. 下载模型 + 全量向量化
python down_embedding_model.py
python embed_chunks.py
# 4. 全量导入
python import_to_chroma.py
# 5. 开始查询
python query_chroma.py
```
### 场景 B：追加新模板/文档
```bash
# 将新 .jrxml / .md 文件放入源目录后：
# 1. 增量分块 — 自动跳过已处理文件
python batch_chunker.py ./jrxml_source --incremental
# 2. 增量向量化 — 只编码新 chunks
python embed_chunks.py --incremental
# 3. 增量导入 — 追加到已有数据库
python import_to_chroma.py --incremental
```
### 场景 C：更换嵌入模型
```bash
# 1. 编辑 .env 修改 EMBEDDING_MODEL_NAME / EMBEDDING_MODEL_PATH
# 2. 下载新模型
python down_embedding_model.py
# 3. 重新向量化 (全量)
python embed_chunks.py
# 4. 重建数据库
python import_to_chroma.py
```
---
## 数据流
``` ```
┌─────────────────────┐ ┌─────────────────────┐
│ JasperReports 模板库 │ (.jrxml) │ JRXML 模板 (.jrxml) │
│ Markdown 文档 │ (.md) │ Markdown 文档 (.md) │
└──────────┬──────────┘ └──────────┬──────────┘
│ collect_jrxml.py / 手动放置 │ collect_jrxml.py / 手动放置
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ jrxml_source/ │ 源文件目录 │ jrxml_source/ │
│ docs/ │
└──────────┬──────────┘ └──────────┬──────────┘
│ batch_chunker.py (调用 jrxml_chunker.py + md_chunker.py) │ batch_chunker.py [--incremental]
▼ ▼
┌──────────────────────┐ ┌──────────────────────┐
│ jrxml_chunker_output/│ all_chunks.json + processing_stats.json │ jrxml_chunker_output/│ all_chunks.json
└──────────┬───────────┘ └──────────┬───────────┘
│ embed_chunks.py (Qwen3-Embedding, 支持增量) │ embed_chunks.py [--incremental]
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ embeddings/ │ embeddings.npy + chunks.json │ embeddings/ │ embeddings.npy + chunks.json
└────────┬────────┘ └────────┬────────┘
│ import_to_chroma.py (ChromaDB, 支持增量) │ import_to_chroma.py [--incremental]
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ chroma_db/ │ Chroma 向量数据库 │ chroma_db/ │ Chroma 向量数据库