XiaoShengpeng/BERT_SHL

# BERT_SHL

《伤寒论》领域的中文检索增强问答（RAG）项目，面向中医经典条文的结构化预处理、向量检索、规则抽取与可解释回答生成。

本仓库不仅包含模型文件，也包含一个可以直接运行的《伤寒论》RAG 基线系统：从原始文本清洗、条文切分、FAISS 建库，到检索、答案抽取、自然语言生成与简单评估，形成了一个完整闭环。

---

## 项目简介

`BERT_SHL` 聚焦《伤寒论》文本问答场景，核心目标是：

- 将《伤寒论》原始文本转为适合检索的结构化语料
- 基于中文领域编码器构建向量索引
- 在问答阶段融合：
  - 检索增强（RAG）
  - 症状/术语改写
  - 方剂组成类问题的规则抽取
  - 轻量生成模型兜底
- 输出尽量可解释、可追溯、有证据依据的答案

本项目更适合作为：
1. 中医经典问答的教学型 baseline  
2. 小规模领域 RAG 项目的参考实现  
3. “规则 + 检索 + 轻量生成”混合范式的实验起点  

---

## 项目特点

### 1. 面向《伤寒论》的结构化预处理
项目首先把原始《伤寒论》文本做清洗、编号修正与条文切分，并进一步拆成更适合向量检索的 `chunk`，同时保留 `parent_doc_id` 以支持从 chunk 回溯到原始条文。

### 2. 领域检索增强
使用本地编码器模型对 chunk 建立向量表示，并基于 FAISS 建库，实现高效检索。

### 3. 面向中医问答的规则增强
对部分问题（尤其是方剂组成 / 配方 / 煎服法）采用专门的规则抽取 pipeline，而不是完全依赖通用生成模型，以增强可解释性和稳定性。

### 4. 口语症状到经典表述的查询改写
针对现代口语化表达（如“发烧”“怕冷”“腹泻”等），在检索前自动扩展到《伤寒论》中更常见的表述，从而提高召回效果。

### 5. 规则优先、生成兜底
回答生成阶段优先根据证据做规则抽取；只有在规则不足但证据相对充分时，才调用轻量生成模型组织语言，尽量减少无依据生成。

---

## 方法概览

整体流程如下：

```text
Raw Text
  ↓
01_preprocess.py
  ↓
docs.jsonl / chunks.jsonl
  ↓
02_build_index.py
  ↓
FAISS Index + chunk_meta.jsonl
  ↓
03_retrieve.py
  ↓
04_answer_extract.py
  ↓
05_generate.py
  ↓
Answer + Evidence
  ↓
06_evaluate.py

---

仓库结构

BERT_SHL/
├── shtl_rag/
│   ├── data/
│   │   ├── raw/
│   │   │   └── shanghanlun.txt
│   │   └── processed/
│   │       ├── docs.jsonl
│   │       └── chunks.jsonl
│   ├── index/
│   │   ├── faiss.index
│   │   └── chunk_meta.jsonl
│   ├── models/
│   │   ├── finetuned_lm_domain_corpus/
│   │   └── tcm_bert/
│   ├── src/
│   │   ├── 01_preprocess.py
│   │   ├── 02_build_index.py
│   │   ├── 03_retrieve.py
│   │   ├── 04_answer_extract.py
│   │   ├── 05_generate.py
│   │   └── 06_evaluate.py
│   ├── Dockerfile
│   └── Dockerfile.gpu

---

核心模块说明

01_preprocess.py

将《伤寒论》原始文本预处理为两层结构：

• doc：条文级结构单元
• chunk：检索级最小单元

主要功能：

• 文本清洗
• 编号强制换行修复
• 按条文编号切分
• 生成带 overlap 的检索 chunk

---

02_build_index.py

对 chunks.jsonl 中的文本做向量化，并构建 FAISS 索引。

输出：

• index/faiss.index
• index/chunk_meta.jsonl

---

03_retrieve.py

实现查询检索逻辑：

• query 向量化
• FAISS top-k 召回
• 根据 chunk_meta.jsonl 映射回原始文本证据

---

04_answer_extract.py

问答主入口，负责把整个 RAG 闭环串起来。

主要逻辑包括：

• 查询改写（口语症状 → 经典表达）
• 问题类型判断
• 普通问答检索
• 方剂组成类问题的规则增强
• 证据抽取与融合
• 调用生成模块输出最终答案

---

05_generate.py

回答生成模块，采用“规则优先、生成兜底”的设计：

• 若能直接从证据中抽取答案，则优先规则输出
• 若需要更自然的表述，则调用轻量 Seq2Seq 模型进行受约束生成

---

06_evaluate.py

提供一个简单的检索评估脚本，基于伪造问答样本统计：

• Hit@1
• Hit@3
• Hit@5

包括：

• chunk-level 命中率
• doc-level 命中率

---

快速开始

方式一：本地 Python 环境

建议 Python 3.10+。

安装依赖：

pip install -U pip
pip install torch transformers faiss-cpu numpy tqdm regex rank-bm25 gdown pdfplumber

如果你使用 GPU，请根据本机 CUDA 版本安装对应的 PyTorch。

---

方式二：Docker（CPU）

cd shtl_rag
docker build -t bert_shl_rag -f Dockerfile .
docker run --rm -it bert_shl_rag bash

方式三：Docker（GPU）

cd shtl_rag
docker build -t bert_shl_rag_gpu -f Dockerfile.gpu .
docker run --gpus all --rm -it bert_shl_rag_gpu bash

###最推荐方式三

运行步骤（按顺序跑就行）

进入项目目录：

cd shtl_rag

1. 预处理《伤寒论》原始文本

python src/01_preprocess.py

生成：

• data/processed/docs.jsonl
• data/processed/chunks.jsonl

---

2. 构建向量索引

python src/02_build_index.py

生成：

• index/faiss.index
• index/chunk_meta.jsonl

---

3. 启动问答

python src/04_answer_extract.py --mode rag-gen --topk 10 --top_sent 3

程序会提示你输入问题，例如：

请输入问题：麻黄汤由哪些药物组成？

---

4. 运行简单评估

python src/06_evaluate.py

---

##当然你仓库下全了可以直接运行04因为我全传上来了能开盖即食

示例问题

你可以尝试以下问题：

• 麻黄汤由哪些药物组成？
• 桂枝汤主治什么？
• 发烧怕冷无汗，用什么方？
• 少阴病常见表现有哪些？
• 白虎汤适用于什么证候？
• 某方怎么煎服？

---

设计思路

这个项目的设计并不是“纯生成式问答”，而是强调：

1. 文本证据优先 所有输出尽量回到原文 chunk 与条文级证据。

2. 规则增强可解释性 对方剂、配伍、煎服法等结构化问题，规则比开放式生成更稳定。

3. 查询改写增强召回 用户常用的是现代口语，而原始经典文本常用古典表达，因此需要做桥接。

4. 小而清晰的教学型 RAG baseline 保持流程清楚、模块独立，便于后续扩展 BM25、reranker、LLM、知识图谱等能力。

---

可扩展方向

后续可以考虑加入：

• BM25 / Dense / Hybrid Retrieval
• 更强的 reranker
• 更严格的证据过滤
• 中医术语词表与知识图谱
• 多轮对话记忆
• Web Demo / Gradio 界面
• 更完整的标准测试集

---

当前限制

• 当前语料主要围绕《伤寒论》，领域范围较窄
• 规则抽取覆盖面有限，复杂问法仍可能失败
• 当前评估脚本偏 baseline 性质，尚不是严格标准 benchmark
• 生成模块仅作兜底，不代表完整临床推理能力
• 本项目仅用于学术研究与技术实验，不构成医疗建议

---

使用说明

如果你基于本项目做二次开发，建议优先关注以下部分：

• 想换语料：修改 data/raw/ + 01_preprocess.py
• 想换编码器：修改 02_build_index.py 与 03_retrieve.py 的 MODEL_NAME
• 想换检索器：替换 03_retrieve.py
• 想增强回答逻辑：修改 04_answer_extract.py 和 05_generate.py

---

引用

如果你觉得这个项目对你有帮助，欢迎引用或标注来源：

@misc{bert_shl,
  title  = {BERT_SHL: RAG Baseline for Shanghanlun QA},
  author = {XiaoShengpeng},
  year   = {2025},
  url    = {https://huggingface.co/XiaoShengpeng/BERT_SHL}
}

---

致谢

感谢以下开源生态：

• Hugging Face Transformers
• FAISS
• PyTorch
• IDEA-CCNL/Randeng-T5-77M
• 中文领域预训练与检索相关开源工作

---

联系方式

如有合作、交流或问题反馈，欢迎通过 Hugging Face 仓库联系 https://huggingface.co/XiaoShengpeng/BERT_SHL "XiaoShengpeng/BERT_SHL · Hugging Face"