# CASE-ChatPDF-Faiss

**Repository Path**: fcwangluo/case-chat-pdf-faiss

## Basic Information

- **Project Name**: CASE-ChatPDF-Faiss
- **Description**: 基于 **DashScope + Faiss + LangChain** 的 RAG 架构本地知识库检索系统，支持 PDF 文档智能问答。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-24
- **Last Updated**: 2026-05-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ChatPDF - 本地知识库问答系统

基于 **DashScope + Faiss + LangChain** 的 RAG 架构本地知识库检索系统，支持 PDF 文档智能问答。

## 功能特性

- 📄 **PDF 文档解析**：支持中文 PDF，自动提取文本内容
- 🔍 **智能 Query 改写**：通过大模型分析用户查询类型并改写，提升检索精度
- 📊 **检索过程可视化**：Web UI 展示 Query 改写过程、检索结果及相似度分数
- 💬 **流式问答**：支持流式输出回答，带文档来源页码溯源
- 🤖 **统一 API**：嵌入向量和大语言模型均使用 DashScope，只需一个 API Key

## 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| 向量数据库 | **Faiss** | Facebook AI 开源的高效向量检索引擎 |
| 嵌入模型 | **DashScope text-embedding-v1** | 阿里云文本嵌入，1536 维向量 |
| 大语言模型 | **DashScope 通义千问 qwen-plus** | 阿里云大模型，用于问答生成与 Query 改写 |
| 框架 | **LangChain** | 统一封装嵌入、LLM 和 QA 链 |
| UI | **Streamlit** | 交互式 Web 界面 |
| PDF 处理 | **PyPDF2** | PDF 文本提取 |

## 项目结构

```
CASE-ChatPDF-Faiss/
├── .env                    # 环境变量配置（API Key）
├── .gitignore              # Git 忽略规则
├── requirements.txt        # Python 依赖包
├── README.md               # 项目说明文档
├── main.py                 # 主入口
├── config.py               # 配置管理模块
├── document_loader.py      # PDF 文档加载模块
├── text_splitter.py        # 文本分割模块
├── page_mapper.py          # 页码映射模块
├── embedding.py            # 嵌入向量生成模块
├── vector_store.py         # Faiss 向量存储模块
├── query_rewriter.py       # Query 改写模块（大模型分析查询类型并改写）
├── qa_chain.py             # 问答链模块
├── cli.py                  # 命令行交互界面
├── webui.py                # Streamlit Web UI 界面
├── utils.py                # 工具函数模块
├── faiss_index/            # Faiss 索引持久化目录
│   ├── index.faiss         # 向量索引文件
│   ├── metadata.pkl        # 元数据信息
│   └── page_info.pkl       # 页码映射关系
└── 浦发上海浦东发展银行西安分行个金客户经理考核办法.pdf
```

## 快速开始

### 1. 安装依赖

```powershell
pip install -r requirements.txt
```

### 2. 配置 API Key

编辑 `.env` 文件，填入阿里云 DashScope API Key：

```
DASHSCOPE_API_KEY=你的DashScope密钥
```

> 前往 [阿里云 DashScope 控制台](https://dashscope.aliyun.com/) 获取 API Key。

### 3. 构建知识库

```powershell
python main.py --mode build
# 或简写
python main.py -m b
```

构建流程：
```
PDF 文件 → 文本提取 → 文本分割 → 页码映射 → 嵌入向量 → Faiss 索引 → 本地持久化
```

### 4. 启动问答

**命令行模式：**
```powershell
python main.py --mode cli
# 或
python main.py -m c
```

**Web UI 模式（推荐）：**
```powershell
python main.py --mode webui
# 或
python main.py -m w
```

启动后浏览器访问 `http://localhost:8501`。

## RAG 架构

```
┌──────────────────────────────────────────────────────┐
│                    用户提问                            │
└──────────────────────┬───────────────────────────────┘
                       ▼
┌──────────────────────────────────────────────────────┐
│  Step 0: Query 改写 (Query Rewriting)                  │
│  大模型分析查询类型 → 改写为检索友好形式               │
│  支持识别：上下文依赖/对比/模糊指代/多意图/反问        │
└──────────────────────┬───────────────────────────────┘
                       ▼
┌──────────────────────────────────────────────────────┐
│  Step 1: 检索 (Retrieval)                             │
│  改写后 Query 向量化 → Faiss 相似度搜索 → Top-K 文档块 │
└──────────────────────┬───────────────────────────────┘
                       ▼
┌──────────────────────────────────────────────────────┐
│  Step 2: 增强 (Augmentation)                          │
│  将检索到的文档片段组装为上下文                        │
└──────────────────────┬───────────────────────────────┘
                       ▼
┌──────────────────────────────────────────────────────┐
│  Step 3: 生成 (Generation)                            │
│  上下文 + 改写后Query → 通义千问 LLM → 答案 + 页码溯源 │
└──────────────────────────────────────────────────────┘
```

### Query 改写类型

| 类型 | 说明 | 示例 |
|------|------|------|
| 上下文依赖型 | 包含"还有""其他"等依赖上下文的词汇 | "还有哪些指标？" → "还有哪些考核指标？" |
| 对比型 | 包含"哪个""比较""更"等对比词汇 | "哪个更重要？" → "储蓄存款和贷款考核哪个更重要？" |
| 模糊指代型 | 包含"它""他们""这个"等指代词 | "它是怎么计算的？" → "考核分数是怎么计算的？" |
| 多意图型 | 包含多个独立问题 | "考核标准有哪些？怎么计算？" → 拆分为子问题 |
| 反问型 | 包含"不会""难道"等反问语气 | "不会没达到标准就淘汰吧？" → "未达到考核标准会有什么后果？"

## Web UI 界面说明

启动后浏览器访问 `http://localhost:8501`，页面分为：

### 侧边栏
- 📊 **知识库状态**：显示索引大小、文本块数量
- 🔧 **知识库管理**：一键构建/重建知识库
- ⚙️ **参数设置**：可调整检索 Top-K（1~10）
- 🤖 **当前大模型**：显示使用的 LLM 和嵌入模型名称

### 主界面
- 💬 对话区：聊天气泡显示问答内容
- 🔍 **Query 改写 & 检索过程**：每次提问后自动展开显示：
  - 原始 Query vs 改写后 Query
  - 查询类型识别结果
  - Top-K 检索结果：页码、相似度分数、文档片段预览

## 核心参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `CHUNK_SIZE` | 1000 | 文本分块大小 |
| `CHUNK_OVERLAP` | 200 | 文本块重叠大小 |
| `TOP_K` | 3 | 检索返回的相似文档数 |
| `EMBEDDING_MODEL` | text-embedding-v1 | 嵌入模型 |
| `LLM_MODEL` | qwen-plus | 大语言模型 |
| `temperature` | 0.1 | LLM 温度参数 |

可在 `config.py` 中修改这些参数。

## 问答示例

```
用户: 客户经理的考核指标有哪些？

系统:
根据《浦发银行西安分行个金客户经理管理考核暂行办法》，客户经理的考核
指标主要包括以下内容：

1. 储蓄存款考核：最低考核标准为XX万元
2. 个人贷款考核：最低考核标准为XX万元
3. 有效卡考核：最低考核标准为XX张

超出最低考核标准可相互折算，折算标准为：
50万储蓄 = 50万个贷 = 50张有效卡 = 5分

来源页码：第5页
```

## 许可证

MIT License