rag_jrxml/docs/file_guide.md

文件功能说明

本文档详细解释项目中每个 Python 脚本的功能、输入输出和使用方式。

---

1. collect_jrxml.py — JRXML 文件收集

功能: 从 JasperReports 模板库目录递归收集 .jrxml 文件，复制到项目 jrxml_source 目录。

使用方式:

python collect_jrxml.py

---

2. jrxml_chunker.py — JRXML 语义分块引擎 (v3.0)

功能: 将单个 JRXML 文件按语义结构拆分。被 batch_chunker.py 调用，也可单独使用。

输入: 单个 .jrxml 文件路径（或目录）

输出: JRXMLChunk 列表，字段包括:

• chunk_id: 文件内序号
• chunk_type: 分块类型 (query, band_detail, chart 等)
• human_description: 人类可读描述
• raw_xml: 原始 XML 片段
• context: 所属报表名称
• metadata: 元数据 (report_name, band_name, element_kind 等)

单独使用:

python jrxml_chunker.py report.jrxml          # 单文件
python jrxml_chunker.py ./jrxml_source/       # 目录

---

3. md_chunker.py — Markdown 语义分块引擎

功能: 将 Markdown 文件按标题层级、代码块、表格等结构化元素智能分块。被 batch_chunker.py 调用，也可单独使用。

分块策略:

• 按标题层级 (H1/H2/H3) 划分段落，H2 自动识别特殊类型
• 代码块、表格作为独立 chunk
• 过长段落按段落/句子二次拆分

单独使用:

python md_chunker.py doc.md                   # 单文件
python md_chunker.py ./docs/                  # 目录

---

4. batch_chunker.py — 统一批量分块入口

功能: 统一入口，支持 JRXML + Markdown 混合批量处理。支持增量模式。

输出:

• all_chunks.json: 所有 chunks 合并
• processing_stats.json: 处理统计 (文件级 chunk 数量、类型分布)

全量模式 — 首次建库:

python batch_chunker.py ./jrxml_source --output ./jrxml_chunker_output

增量模式 (--incremental) — 追加新文件:

python batch_chunker.py ./jrxml_source --incremental

增量模式逻辑：

1. 加载已有 processing_stats.json，获取已处理文件列表
2. 扫描输入目录，自动跳过已处理文件
3. 只分块新增文件
4. 合并新旧 all_chunks.json 和统计数据后保存

---

5. down_embedding_model.py — 嵌入模型下载

功能: 从 HuggingFace Hub 下载嵌入模型到本地。支持国内镜像 (hf-mirror.com)、断点续传。

python down_embedding_model.py

---

6. embed_chunks.py — Chunk 向量化

功能: 将 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

全量模式 — 首次向量化:

python embed_chunks.py
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) — 只编码新 chunks:

python embed_chunks.py --incremental

增量模式逻辑：

1. 加载已有 embeddings.npy + chunks.json
2. 按 (context, chunk_id) 去重
3. 只向量化新 chunks
4. 合并新旧数据后保存

---

7. import_to_chroma.py — Chroma 向量入库

功能: 将向量数据导入 Chroma 持久化数据库。支持增量模式。

全量模式 — 首次导入 (删除旧集合重建):

python import_to_chroma.py

增量模式 (--incremental / -i) — 追加新记录:

python import_to_chroma.py --incremental

增量模式逻辑：

1. get_or_create_collection (不删除已有数据)
2. 查询 Chroma 已有 ID
3. 跳过已导入的记录，只追加新数据

---

8. query_chroma.py — 语义搜索查询

功能: 通过自然语言查询 Chroma 数据库。

两种模式:

• 单次查询: python query_chroma.py "查询内容"
• 交互模式: python query_chroma.py（支持连续查询和内联命令）

交互模式命令:

filter:<类型>     按 chunk_type 过滤 (如 filter:query)
t:<阈值>          相似度阈值 0~1 (如 t:0.5)
k:<数量>          返回结果数 (如 k:10)

使用示例:

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

---

9. config.py — 统一配置管理

功能: 从 .env 加载所有配置，所有脚本通过此模块获取配置项。

python config.py   # 打印当前配置

---

10. jrxml_banch_chunker.py — 旧版入口 (已废弃)

功能: JRXML 单类型批量分块。已被 batch_chunker.py 取代，保留以兼容旧流程。

---

使用场景

场景 A：首次构建数据库

# 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：追加新模板/文档

# 将新 .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：更换嵌入模型

# 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

---

数据流

┌─────────────────────┐
│ JRXML 模板 (.jrxml)  │
│ Markdown 文档 (.md)  │
└──────────┬──────────┘
           │ collect_jrxml.py / 手动放置
           ▼
┌─────────────────────┐
│ jrxml_source/       │
└──────────┬──────────┘
           │ batch_chunker.py [--incremental]
           ▼
┌──────────────────────┐
│ jrxml_chunker_output/│  all_chunks.json
└──────────┬───────────┘
           │ embed_chunks.py [--incremental]
           ▼
┌─────────────────┐
│ embeddings/     │  embeddings.npy + chunks.json
└────────┬────────┘
         │ import_to_chroma.py [--incremental]
         ▼
┌─────────────────┐
│ chroma_db/      │  Chroma 向量数据库
└────────┬────────┘
         │ query_chroma.py
         ▼
┌─────────────────┐
│ 自然语言查询     │  返回相关 chunks
└─────────────────┘

依赖关系

query_chroma.py ──────────► chromadb, sentence_transformers, torch
import_to_chroma.py ──────► chromadb, numpy
embed_chunks.py ──────────► sentence_transformers, torch, numpy
down_embedding_model.py ──► huggingface_hub
batch_chunker.py ─────────► jrxml_chunker.py, md_chunker.py
md_chunker.py ────────────► 标准库 (re, json, pathlib)
jrxml_chunker.py ─────────► xml.etree.ElementTree (标准库)
config.py ────────────────► 标准库 (os, pathlib)
collect_jrxml.py ─────────► 标准库 (os, shutil)