rag_jrxml/docs/file_guide.md

# 文件功能说明

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

---

## 1. collect_jrxml.py — JRXML 文件收集脚本

**功能**: 从指定的 JasperReports 模板库目录递归收集所有 `.jrxml` 文件，复制到项目的 `jrxml_source` 目录。

**输入**:
- 源目录: `C:\Users\zy187\JaspersoftWorkspace\JasperReportsSamples`（可修改）

**输出**:
- `jrxml_source/` 目录，包含所有收集到的 JRXML 文件

**使用方式**:
```bash
python collect_jrxml.py
```

**核心逻辑**:
- 使用 `os.walk()` 递归遍历源目录
- 筛选 `.jrxml` 后缀文件
- 自动处理文件名冲突（添加数字后缀）
- 使用 `shutil.copy2()` 保留文件元数据

---

## 2. jrxml_chunker.py — JRXML 语义分块核心引擎

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

**输入**:
- 单个 JRXML 文件路径

**输出**:
- `JRXMLChunk` 对象列表，每个包含:
  - `chunk_id`: 唯一标识
  - `chunk_type`: 分块类型（如 `query`, `field`, `band_title` 等）
  - `human_description`: 人类可读的结构化描述
  - `raw_xml`: 原始 XML 片段
  - `context`: 上下文信息（所属报表名称）
  - `metadata`: 元数据字典

**核心类**:
- `JRXMLChunk`: 单个 chunk 的数据结构
- `JRXMLSemanticChunker`: 主分块器，支持多种数据源类型（SQL、HQL、XPath、JSON、CSV 等）

**分块策略**:
- 按 XML 元素类型分类（field、parameter、variable、band、chart 等）
- 提取数据源配置和查询语句
- 保留元素间的层级关系
- 为每个 chunk 生成结构化的人类可读描述

**使用方式**:
```bash
# 处理单个文件
python jrxml_chunker.py report.jrxml

# 处理整个目录
python jrxml_chunker.py ./jrxml_source/
```

---

## 3. jrxml_banch_chunker.py — 批量分块入口脚本

**功能**: 批量处理目录下所有 JRXML 文件，生成统计报告和分类输出。

**输入**:
- JRXML 文件目录（默认: `jrxml_source`）

**输出**:
- `jrxml_chunker_output/all_chunks.json`: 所有 chunks 合并文件
- `jrxml_chunker_output/processing_stats.json`: 处理统计（成功/失败数、耗时、chunk 类型分布）
- `jrxml_chunker_output/per_file/`: 按原文件分类的独立 chunk 文件

**核心函数**:
- `batch_chunk_with_report()`: 批量处理目录
- `chunk_single_file_with_report()`: 处理单个文件

**使用方式**:
```bash
# 使用默认输入目录
python jrxml_banch_chunker.py

# 指定输入目录
python jrxml_banch_chunker.py ./jrxml_source

# 指定输出目录
python jrxml_banch_chunker.py ./jrxml_source --output ./my_output
```

---

## 4. down_embedding_model.py — 嵌入模型下载脚本

**功能**: 从 HuggingFace Hub 下载 Qwen3-Embedding-4B 嵌入模型到本地。

**输入**:
- HuggingFace 模型仓库: `Qwen/Qwen3-Embedding-4B`

**输出**:
- `models/Qwen3-Embedding-4B/` 目录，包含完整的模型文件

**特性**:
- 使用国内镜像加速下载（`hf-mirror.com`）
- 支持断点续传
- 自动安装依赖

**使用方式**:
```bash
python down_embedding_model.py
```

---

## 5. embed_chunks.py — Chunk 向量化脚本

**功能**: 使用嵌入模型将分块后的文本转换为向量表示，支持 GPU 加速和 FP16 半精度。

**输入**:
- `jrxml_chunker_output/all_chunks.json`（默认）

**输出**:
- `embeddings/embeddings.npy`: 向量矩阵（float32）
- `embeddings/chunk_id_map.json`: chunk ID 映射
- `embeddings/chunk_type_map.json`: chunk 类型映射
- `embeddings/chunks.json`: 原始 chunks 副本
- `embeddings/embeddings.pkl`: 完整数据 pickle

**核心函数**:
- `build_text_for_embedding()`: 将 chunk 转换为适合向量化的文本（拼接类型、描述、XML、元数据）
- `main()`: 主流程（加载→编码→保存→质量检查）

**特性**:
- 自动检测 CUDA/CPU
- 默认启用 FP16 半精度（节省约 50% 显存）
- 支持 HuggingFace Hub 在线模型
- 向量归一化 + NaN 检测

**使用方式**:
```bash
# 使用默认设置
python embed_chunks.py

# 指定模型和 batch size
python embed_chunks.py --model_path "sentence-transformers/all-MiniLM-L6-v2" --batch_size 64

# 使用本地 Qwen3 模型
python embed_chunks.py --batch_size 2

# 禁用 FP16
python embed_chunks.py --no_fp16 --batch_size 1
```

---

## 6. import_to_chroma.py — 向量导入 Chroma 数据库

**功能**: 将已生成的向量和 chunks 导入 Chroma 持久化向量数据库。

**输入**:
- `embeddings/embeddings.npy`: 向量矩阵
- `embeddings/chunks.json`: chunks 数据

**输出**:
- `chroma_db/`: Chroma 持久化数据库目录
- 集合名称: `jrxml_chunks`（默认）

**核心逻辑**:
- 加载向量和 chunks
- 初始化 Chroma PersistentClient
- 创建集合（余弦相似度）
- 分批导入（每批 1000 条）
- 提取元数据（chunk_type、report_name、band_name 等）
- 快速验证查询

**使用方式**:
```bash
# 使用默认设置
python import_to_chroma.py

# 指定路径
python import_to_chroma.py --embeddings_dir ./embeddings --chroma_path ./chroma_db
```

---

## 7. query_chroma.py — 语义搜索查询工具

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

**输入**:
- 用户自然语言查询
- 可选的元数据过滤条件

**输出**:
- 相似度排序的检索结果（含 chunk 类型、报表名称、区域、内容摘要）

**核心类**:
- `JRXMLSearcher`: 搜索器，封装模型加载、向量编码和 Chroma 查询

**核心方法**:
- `search()`: 基础语义搜索
- `search_with_threshold()`: 带相似度阈值的搜索
- `format_result()`: 格式化输出结果

**两种模式**:
1. **命令行单次查询**: `python query_chroma.py "查询内容"`
2. **交互模式**: `python query_chroma.py`（支持连续查询和内联命令）

**交互模式命令**:
```
filter:<类型>     按 chunk_type 过滤（如 filter:query）
t:<阈值>          设置相似度阈值 0~1（如 t:0.5）
k:<数量>          设置返回结果数（如 k:10）
```

**使用方式**:
```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
```

---

## 数据流全景

```
┌─────────────────┐
│ JasperReports   │  C:\Users\...\JasperReportsSamples
│ 模板库           │
└────────┬────────┘
         │ collect_jrxml.py
         ▼
┌─────────────────┐
│ jrxml_source/   │  收集的 JRXML 文件
└────────┬────────┘
         │ jrxml_banch_chunker.py (调用 jrxml_chunker.py)
         ▼
┌──────────────────────┐
│ jrxml_chunker_output/│  all_chunks.json + per_file/
└────────┬─────────────┘
         │ embed_chunks.py (使用 Qwen3-Embedding-4B)
         ▼
┌─────────────────┐
│ embeddings/     │  embeddings.npy + chunks.json
└────────┬────────┘
         │ import_to_chroma.py
         ▼
┌─────────────────┐
│ chroma_db/      │  Chroma 向量数据库
└────────┬────────┘
         │ query_chroma.py
         ▼
┌─────────────────┐
│ 用户查询         │  自然语言 → 相关 JRXML 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
jrxml_banch_chunker.py ─► jrxml_chunker.py
jrxml_chunker.py ─────► xml.etree.ElementTree (标准库)
collect_jrxml.py ─────► 标准库 (os, shutil)
```