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 的前置工作。
支持 JRXML 模板和 Markdown 文档的语义分块、向量化、Chroma 持久化存储，以及自然语言查询。
支持 JRXML 模板和 Markdown 文档的语义分块、向量化、Chroma 持久化存储，以及自然语言查询。**三个核心步骤均支持增量处理**。
## 项目结构
@@ -10,102 +10,126 @@
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)
├── 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 # 配置模板
├── .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
└── 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 调整模型、路径等参数
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：收集 & 分块
```bash
# 1. 收集 JRXML 文件
# 收集 JRXML 模板文件
python collect_jrxml.py
# 2. 统一分块 (JRXML + Markdown)
# 统一分块 (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
```
### 增量更新
输出 `jrxml_chunker_output/all_chunks.json` 和 `processing_stats.json`。
新增或修改部分文件时，无需重新处理全部数据：
### 步骤 2：向量化
```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
```
三个 `--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` | 子报表元素 |
| `component` | 组件元素 (列表等) |
### Markdown 分块
### Markdown
| 类型 | 说明 |
|---|---|
@@ -140,22 +164,6 @@ python import_to_chroma.py --incremental
| `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
docs/file_guide.md
+121 -98
View File
@@ -8,10 +8,6 @@
**功能**: 从 JasperReports 模板库目录递归收集 `.jrxml` 文件，复制到项目 `jrxml_source` 目录。
**输入**: 源目录路径（硬编码，可按需修改）
**输出**: `jrxml_source/` 目录
**使用方式**:
```bash
python collect_jrxml.py
@@ -21,21 +17,19 @@ python collect_jrxml.py
## 2. jrxml_chunker.py — JRXML 语义分块引擎 (v3.0)
**功能**: 将单个 JRXML 文件按语义结构拆分，每个 chunk 包含人类可读描述、原始 XML 和结构化元数据。
**功能**: 将单个 JRXML 文件按语义结构拆分。被 `batch_chunker.py` 调用，也可单独使用。
**输入**: 单个 `.jrxml` 文件路径（或目录）
**输出**: `JRXMLChunk` 列表，字段包括:
- `chunk_id`: 文件内序号
- `chunk_type`: 分块类型 (如 `query`, `band_detail`, `chart` 等)
- `chunk_type`: 分块类型 (`query`, `band_detail`, `chart` 等)
- `human_description`: 人类可读描述
- `raw_xml`: 原始 XML 片段
- `context`: 所属报表名称
- `metadata`: 元数据 (report_name, band_name, element_kind 等)
**支持的数据源**: SQL, HQL, XPath, JSON, JSONQL, CSV, Data Adapter, Bean Collection, Empty
**使用方式**:
**单独使用**:
```bash
python jrxml_chunker.py report.jrxml # 单文件
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` 取代。
**使用方式**:
```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 等)
**功能**: 将 Markdown 文件按标题层级、代码块、表格等结构化元素智能分块。被 `batch_chunker.py` 调用，也可单独使用。
**分块策略**:
- 按标题层级 (H1/H2/H3) 划分段落
- 代码块作为独立 chunk
- 表格作为独立 chunk
- H2 标题自动识别特殊类型（安装、配置、API、示例等）
- 按标题层级 (H1/H2/H3) 划分段落，H2 自动识别特殊类型
- 代码块、表格作为独立 chunk
- 过长段落按段落/句子二次拆分
**使用方式**:
**单独使用**:
```bash
python md_chunker.py doc.md # 单文件
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` / `.md` 文件的目录
**功能**: 统一入口，支持 JRXML + Markdown 混合批量处理。**支持增量模式**。
**输出**:
- `all_chunks.json`: 所有 chunks 合并
- `processing_stats.json`: 处理统计 (成功/失败/耗时/类型分布)
- `processing_stats.json`: 处理统计 (文件级 chunk 数量、类型分布)
**使用方式**:
**全量模式** — 首次建库:
```bash
python batch_chunker.py ./mixed_source
python batch_chunker.py ./mixed_source --output ./my_output
python batch_chunker.py ./jrxml_source --output ./jrxml_chunker_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
python down_embedding_model.py
```
---
## 7. embed_chunks.py — Chunk 向量化
## 6. embed_chunks.py — Chunk 向量化
**功能**: 使用嵌入模型将 chunks 转换为向量。支持 GPU/CPU、FP16 半精度，**支持增量模式**。
**输入**: chunks JSON 文件 (默认 `jrxml_chunker_output/all_chunks.json`)
**功能**: 将 chunks 转换为向量。支持 GPU/CPU、FP16 半精度，**支持增量模式**。
**输出**:
- `embeddings/embeddings.npy`: 向量矩阵 (float32)
- `embeddings/chunks.json`: 原始 chunks
- `embeddings/chunk_id_map.json` / `chunk_type_map.json`: 映射文件
- `embeddings/embeddings.pkl`: 完整数据 pickle
- `embeddings/chunk_id_map.json` / `chunk_type_map.json`
- `embeddings/embeddings.pkl`: 完整 pickle
**全量模式**:
**全量模式** — 首次向量化:
```bash
python embed_chunks.py
python embed_chunks.py --batch_size 2
python embed_chunks.py --model_path "sentence-transformers/all-MiniLM-L6-v2"
python embed_chunks.py --batch_size 2 # 调整批大小
python embed_chunks.py --model_path "all-MiniLM-L6-v2" # 换模型
python embed_chunks.py --no_fp16 # 禁用半精度
```
**增量模式** (`--incremental` / `-i`):
**增量模式** (`--incremental` / `-i`) — 只编码新 chunks:
```bash
# 只向量化新增 chunks，自动合并到已有向量数据
python embed_chunks.py ./new_chunks/all_chunks.json --incremental
python embed_chunks.py --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 持久化数据库。**支持增量模式**。
**输入**: `embeddings/embeddings.npy` + `embeddings/chunks.json`
**输出**: `chroma_db/` 持久化数据库
**全量模式** (删除旧集合重建):
**全量模式** — 首次导入 (删除旧集合重建):
```bash
python import_to_chroma.py
```
**增量模式** (`--incremental` / `-i`):
**增量模式** (`--incremental` / `-i`) — 追加新记录:
```bash
# 追加新记录到已有集合，不删除已有数据
python import_to_chroma.py --incremental
```
增量模式逻辑：
1. 使用 `get_or_create_collection` (不删除已有数据)
2. 查询已有 ID，跳过已导入的记录
3. 只追加新增数据
1. `get_or_create_collection` (不删除已有数据)
2. 查询 Chroma 已有 ID
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)
t:<阈值> 设置相似度阈值 0~1
k:<数量> 设置返回结果数
t:<阈值> 相似度阈值 0~1 (如 t:0.5)
k:<数量> 返回结果数 (如 k:10)
```
**使用方式**:
**使用示例**:
```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 "参数" --threshold 0.5 --n_results 10
```
---
## 10. config.py — 统一配置管理
## 9. config.py — 统一配置管理
**功能**: 从 `.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`
**功能**: 从 `.env` 加载所有配置，所有脚本通过此模块获取配置项。
```bash
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)
│ Markdown 文档 │ (.md)
│ JRXML 模板 (.jrxml) │
│ Markdown 文档 (.md) │
└──────────┬──────────┘
│ collect_jrxml.py / 手动放置
▼
┌─────────────────────┐
│ jrxml_source/ │ 源文件目录
│ docs/ │
│ jrxml_source/ │
└──────────┬──────────┘
│ 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
└────────┬────────┘
│ import_to_chroma.py (ChromaDB, 支持增量)
│ import_to_chroma.py [--incremental]
▼
┌─────────────────┐
│ chroma_db/ │ Chroma 向量数据库