rag_jrxml/docs/file_guide.md

文件功能说明

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

---

1. collect_jrxml.py — JRXML 文件收集

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

输入: 源目录路径（硬编码，可按需修改）

输出: jrxml_source/ 目录

使用方式:

python collect_jrxml.py

---

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

功能: 将单个 JRXML 文件按语义结构拆分，每个 chunk 包含人类可读描述、原始 XML 和结构化元数据。

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

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

• chunk_id: 文件内序号
• 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

使用方式:

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

---

3. jrxml_banch_chunker.py — JRXML 批量分块 (单类型)

功能: 批量处理目录下所有 JRXML 文件，生成统计报告和按文件分类的输出。是旧版入口，被 batch_chunker.py 取代。

使用方式:

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) 划分段落
• 代码块作为独立 chunk
• 表格作为独立 chunk
• H2 标题自动识别特殊类型（安装、配置、API、示例等）
• 过长段落按段落/句子二次拆分

使用方式:

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

---

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

功能: 统一入口，支持 JRXML 和 Markdown 文件混合批量处理，生成合并的 chunks 和统计报告。

输入: 包含 .jrxml / .md 文件的目录

输出:

• all_chunks.json: 所有 chunks 合并
• processing_stats.json: 处理统计 (成功/失败/耗时/类型分布)

使用方式:

python batch_chunker.py ./mixed_source
python batch_chunker.py ./mixed_source --output ./my_output

---

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

功能: 从 HuggingFace Hub 下载嵌入模型到本地。支持国内镜像加速和断点续传。

使用方式:

python down_embedding_model.py

---

7. embed_chunks.py — Chunk 向量化

功能: 使用嵌入模型将 chunks 转换为向量。支持 GPU/CPU、FP16 半精度，支持增量模式。

输入: chunks JSON 文件 (默认 jrxml_chunker_output/all_chunks.json)

输出:

• 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 "sentence-transformers/all-MiniLM-L6-v2"

增量模式 (--incremental / -i):

# 只向量化新增 chunks，自动合并到已有向量数据
python embed_chunks.py ./new_chunks/all_chunks.json --incremental

增量模式逻辑：

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

---

8. import_to_chroma.py — Chroma 向量入库

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

输入: embeddings/embeddings.npy + embeddings/chunks.json

输出: chroma_db/ 持久化数据库

全量模式 (删除旧集合重建):

python import_to_chroma.py

增量模式 (--incremental / -i):

# 追加新记录到已有集合，不删除已有数据
python import_to_chroma.py --incremental

增量模式逻辑：

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

---

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

功能: 通过自然语言查询 Chroma 数据库，检索相关的 JRXML/Markdown chunks。

两种模式:

• 命令行单次查询: python query_chroma.py "查询内容"
• 交互模式: python query_chroma.py (支持连续查询)

交互模式命令:

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

使用方式:

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 — 统一配置管理

功能: 从 .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

python config.py   # 打印当前配置

---

数据流全景

┌─────────────────────┐
│ JasperReports 模板库 │  (.jrxml)
│ Markdown 文档        │  (.md)
└──────────┬──────────┘
           │ collect_jrxml.py / 手动放置
           ▼
┌─────────────────────┐
│ jrxml_source/       │  源文件目录
│ docs/               │
└──────────┬──────────┘
           │ batch_chunker.py (调用 jrxml_chunker.py + md_chunker.py)
           ▼
┌──────────────────────┐
│ jrxml_chunker_output/│  all_chunks.json + processing_stats.json
└──────────┬───────────┘
           │ embed_chunks.py (Qwen3-Embedding, 支持增量)
           ▼
┌─────────────────┐
│ embeddings/     │  embeddings.npy + chunks.json
└────────┬────────┘
         │ import_to_chroma.py (ChromaDB, 支持增量)
         ▼
┌─────────────────┐
│ 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)