Mrianda/dunhuang-knowledge-base

<p align="center"> <h1 align="center">🏛️ 敦煌文化遗产智能知识库系统</h1> <p align="center"> <strong>Dunhuang Cultural Heritage AI Knowledge Base</strong> </p> <p align="center"> 基于 RAG 架构的敦煌学智能问答与语义检索平台 </p> </p>

项目简介

本人在学习人工智能与自然语言处理的过程中，独立完成了这个敦煌文化遗产智能知识库系统。系统聚焦于敦煌藻井纹样（而非整个敦煌文化），收录了 35 篇藻井纹样相关的学术论文，通过 RAG（检索增强生成）技术，支持自然语言问答和语义检索。

作为一项学习实践作品，知识库的内容基于学术文献构建，力求数据的准确性与严谨性，但受限于个人的学识和经验，可能存在不够准确或不够全面的地方。如有疏漏，恳请各位前辈和同学指教，非常欢迎交流学习。

⚡ 核心特性：语义理解检索（非关键词匹配）· 来源可追溯 · 交互式界面 · 可本地部署

在线体验

[🚀 点击在线体验](https://huggingface.co/spaces/Mrianda/dunhuang-knowledge-base) — 无需安装，打开即可使用

 

本地体验：python run.py → 打开 http://localhost:5000

目标用户

🎬 演示

• —在线演示：Hugging Face Space（敦煌风格 Web 界面，与本地 python run.py 一致）
• —演示视频：录制中，敬请期待

核心功能

💬 智能问答

• —对话式交互界面，支持多轮追问
• —基于 RAG 架构：检索 → 上下文注入 → LLM 生成
• —每条回答标注来源文献，支持学术引用
• —首页提供引导示例，降低使用门槛
• —支持两种问答模式：
• —检索摘要模式（默认，无需 API Key）：从知识库检索相关文献并生成带来源标注的摘要
• —AI 生成模式（需配置 API Key）：调用大语言模型生成更完整、连贯的回答

🔍 语义检索

• —自然语言输入，理解语义而非仅匹配关键词
• —返回相关度评分与文献片段预览
• —支持自定义返回数量（3/5/10 条）

📊 数据看板

• —纹样分类体系可视化（4 大类 15+ 子类）
• —各朝代藻井演变趋势图
• —敦煌矿物颜料色彩分析
• —知识库文献统计分布
• —图表数据均来源于所收录文献的整理归纳

🎨 敦煌风格前端

• —采用敦煌壁画金/靛蓝/米色配色
• —滚动动画与交互反馈
• —响应式布局，适配不同屏幕

🔧 技术特性

• —向量模型：paraphrase-multilingual-MiniLM-L12-v2（384 维，50+ 语言）
• —检索策略：余弦相似度 Top-K 召回，支持阈值过滤
• —索引缓存：首次构建后持久化，后续秒级加载
• —配置分离：YAML 集中管理，环境变量注入 API Key

技术架构

用户提问（自然语言）
        │
        ▼
┌───────────────────────────────────┐
│  1. 向量化（Embedding）            │  ← Sentence Transformers
│  2. 语义检索（Vector Search）      │  ← Cosine Similarity Top-K
│  3. 上下文注入（Prompt Build）     │  ← RAG Context Assembly
│  4. 生成回答（LLM）               │  ← DeepSeek / OpenAI API
└───────────────────────────────────┘
        │
        ▼
  带来源标注的准确回答

为什么用 RAG 而非纯 LLM？

技术栈

安装步骤

环境要求

• —Python 3.9+
• —pip

快速安装

# 1. 克隆项目
git clone https://github.com/qiadastrachen-bit/dunhuang-ai-knowledge-base.git
cd dunhuang-ai-knowledge-base

# 2. 创建虚拟环境（推荐）
python -m venv venv
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 准备数据
# 将 PDF 文献放入 data/raw/ 目录

# 5. 启动系统
python run.py

首次运行时，系统会自动：

1. 1.解析 data/raw/ 下的所有 PDF 文件
2. 2.按滑动窗口（500 字/块，50 字重叠）切分文本
3. 3.生成向量嵌入并缓存到 data/processed/
4. 4.启动 Web 前端界面（默认端口 5000）

⏱️ 首次构建约需 3-5 分钟（取决于 PDF 数量和硬件性能），后续启动秒级加载。

可选：启用 AI 生成模式

默认使用检索摘要模式（无需 API Key）。如需 AI 生成完整回答：

# 方式一：复制环境变量模板
cp .env.example .env          # macOS/Linux
copy .env.example .env        # Windows CMD
# 编辑 .env，填入 DUNHUANG_API_KEY

# 方式二：直接设置环境变量
export DUNHUANG_API_KEY="your-api-key"  # macOS/Linux
set DUNHUANG_API_KEY=your-api-key       # Windows CMD

# 方式三：Streamlit 侧边栏输入 API Key

支持 DeepSeek（默认端点 https://api.deepseek.com）、OpenAI 及任何 OpenAI 兼容接口。 配置 API Key 后，Web 前端会自动切换为 AI 生成模式。

发布到 GitHub 并让别人在线体验

GitHub 只能预览 README 和代码，无法直接运行 Python 后端。要让别人「点开就能用」，需要：本地配好 Key → 提交向量索引 → 部署到云平台 → README 贴上体验链接。

第一步：本地填入 DeepSeek API Key

# 若还没有 .env，先复制模板
copy .env.example .env        # Windows
# cp .env.example .env        # macOS/Linux

用记事本打开 .env，把 Key 填进去（只保存在本地，不要提交到 Git）：

DUNHUANG_API_KEY=sk-你的真实密钥

Key 在 DeepSeek 开放平台 申请。保存后本地验证：

python run.py

浏览器打开 http://localhost:5000 ，状态栏应显示 「AI 生成模式」。在「知识问答」提一个问题，能收到连贯回答即表示 Key 生效。

第二步：确保知识库索引已构建

data/raw/ 中放入 PDF 后，运行一次 python run.py，系统会自动生成 data/processed/ 下的三个文件：

在线部署不需要上传 PDF，只需把 data/processed/ 这三个文件提交到 GitHub（原始 PDF 仍被 .gitignore 忽略）。

git add data/processed/
git status   # 确认没有 .env 和 data/raw/*.pdf
git commit -m "add vector index for online demo"
git push

第三步：部署到 Hugging Face Spaces（推荐，已上线 ✅）

本项目已部署至：https://huggingface.co/spaces/Mrianda/dunhuang-knowledge-base

自行部署可参考以下步骤（无需信用卡）：

1. 1.注册 huggingface.co（邮箱即可，无需绑卡）
2. 2.打开 huggingface.co/new-space
3. 3.填写：
4. 4.Space name：dunhuang-knowledge-base（或自定义）
5. 5.SDK：Docker（重要）
6. 6.Hardware：CPU basic（免费）
7. 7.上传代码（推荐使用项目内脚本）：

   # 设置 HF Token 后执行
   python upload_hf.py

或使用 Git 推送：

   git remote add hf https://你的用户名:你的Token@huggingface.co/spaces/你的用户名/dunhuang-knowledge-base
   git push hf main --force

1. 1.在 Space Settings → Variables and secrets → Secrets 添加：

1. 1.等待 Building 完成（首次约 15～40 分钟）
2. 2.获得体验地址：https://huggingface.co/spaces/你的用户名/dunhuang-knowledge-base

README.md 顶部需包含 Hugging Face Docker Space 所需的 YAML 配置（本项目已包含）。 项目根目录已有 Dockerfile，监听端口 7860。

备选 A：Streamlit Cloud（更简单，界面为 Streamlit 版）

1. 1.打开 share.streamlit.io ，GitHub 登录
2. 2.New app → 选本仓库，Main file 填 ui/app.py
3. 3.Advanced settings → Secrets 填入：

   DUNHUANG_API_KEY = "sk-你的密钥"
   DUNHUANG_API_BASE = "https://api.deepseek.com"
   DUNHUANG_MODEL = "deepseek-chat"

1. 1.Deploy 后获得 https://你的应用名.streamlit.app（展示的是 Streamlit 后台，不是 demo.html 主页）

备选 B：Render（需 Visa/Mastercard 验证）

1. 1.打开 render.com 注册并连接 GitHub
2. 2.New → Web Service → Runtime: Docker
3. 3.环境变量同 Hugging Face Secrets 表
4. 4.获得 https://你的服务名.onrender.com

安全提醒

• —永远不要把 DUNHUANG_API_KEY 写进代码或提交到 GitHub（.env 已在 .gitignore 中）
• —公网部署后，所有访客都会消耗你的 DeepSeek 额度，建议在 DeepSeek 控制台 设置用量上限
• —若只想公开展示、不消耗 Key，部署时不填 DUNHUANG_API_KEY，访客仍可使用检索摘要模式

GitHub 仓库展示建议

• —README 顶部已附上 在线体验 链接
• —截图放入 docs/screenshots/ 并更新 README 图片（GitHub 会直接渲染）
• —可选：录制 1–2 分钟演示视频上传到 B 站/YouTube，链接写在 README

使用方法

启动

python run.py              # Web 模式（默认，Flask + 前端，端口 5000）
python run.py --mode ui    # Streamlit 管理后台
python run.py --mode api   # 仅 API 服务器
python run.py --port 8080  # 自定义端口

界面导航

Web 前端（主界面）：

Streamlit 管理后台：

快速体验

1. 1.打开 http://localhost:5000，浏览首页各区域
2. 2.在「语义检索」区域输入关键词（如"宝相花"、"藻井"）
3. 3.在「知识问答」区域提问，查看回答及来源标注

API 接口

Flask 后端提供以下 RESTful API：

项目结构

dunhuang-ai-knowledge-base/
├── api/
│   ├── __init__.py           # API 模块初始化
│   └── server.py             # Flask 后端（RESTful API + 静态文件服务）
├── config/
│   ├── __init__.py           # 配置加载工具
│   └── settings.yaml         # 集中配置文件
├── core/
│   ├── __init__.py
│   ├── pdf_parser.py         # PDF 文本提取
│   ├── chunker.py            # 滑动窗口分块
│   ├── vectorizer.py         # 向量化 & 语义检索
│   └── rag_engine.py         # RAG 检索增强生成
├── ui/
│   ├── __init__.py
│   ├── app.py                # Streamlit 管理后台
│   └── templates/
│       └── demo.html         # Web 前端主页面
├── utils/
│   ├── __init__.py
│   └── logger.py             # 日志工具
├── data/
│   ├── raw/                  # PDF 文献（不提交 Git，仅本地使用）
│   └── processed/            # 向量索引缓存（可提交，供在线部署）
├── Dockerfile                # Hugging Face / 云平台 Docker 部署
├── upload_hf.py              # 上传项目到 Hugging Face Space
├── streamlit_app.py          # Streamlit Cloud 入口（备选）
├── render.yaml               # Render 一键部署配置（需绑卡）
├── docs/
│   └── screenshots/          # 项目截图
├── .env.example              # 环境变量模板（复制为 .env 使用）
├── .gitignore
├── requirements.txt
├── run.py                    # 一键启动入口
└── README.md

项目截图

📸 使用时替换为实际截图，截图请放入 docs/screenshots/ 目录

Roadmap

✅ 已完成（v1.0）

• —[x] PDF 批量解析与文本提取
• —[x] 滑动窗口分块（可配置大小与重叠）
• —[x] 语义向量检索引擎（余弦相似度 Top-K）
• —[x] RAG 检索增强生成（支持 OpenAI 兼容 API）
• —[x] 向量索引持久化与快速加载
• —[x] Flask API 后端（RESTful 接口）
• —[x] 敦煌风格 Web 前端（语义检索 + 知识问答）
• —[x] Streamlit 管理后台（数据看板 + 可视化）
• —[x] YAML 集中配置管理
• —[x] 引导示例与来源标注

🔜 规划中（v2.0）

• —[ ] 图像检索（CLIP / 以图搜图）
• —[ ] 知识图谱构建（从向量升级为结构化图谱）
• —[ ] 向量模型升级（bge-m3 / 领域微调）
• —[ ] 多用户支持与对话历史持久化
• —[ ] Docker 容器化部署
• —[ ] 3D 洞窟藻井可视化（Three.js）

作者

陈锦彤 — 在校大学生，本人在学习过程中独立完成了本项目的系统设计、开发与实现。

本项目作为学习实践作品，如有不足之处，恳请各位前辈和同学不吝指教，欢迎交流学习。

许可证

本项目仅供学术研究与学习交流使用。文献版权归原作者所有。

<p align="center"> Built with ❤️ for Dunhuang Cultural Heritage </p>