# hangzhou-guide

**Repository Path**: xjshiMax/hangzhou-guide

## Basic Information

- **Project Name**: hangzhou-guide
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-25
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 杭州导游 RAG 系统

基于 DeepSeek + RAG（检索增强生成）的本地杭州导游助手。无需微调模型，知识库可随时更新。

## RAG 原理

RAG（Retrieval-Augmented Generation，检索增强生成）解决的核心问题是：**LLM 的知识是静态的**，训练截止后无法获取新知识，也无法掌握私有领域数据。

RAG 的做法是在生成回答前，先从外部知识库检索相关内容，再把检索结果拼入 Prompt，让模型"带着资料"回答。

```
离线阶段（构建索引）
  原始文档 → 切片（Chunk）→ Embedding 向量化 → 存入向量数据库

在线阶段（回答问题）
  用户提问 → Embedding 向量化 → 向量相似度检索 → 召回相关片段
     ↓
  片段 + 问题 → 拼入 Prompt → LLM 生成回答
```

与直接问 LLM 相比，RAG 的优势：
- 知识可随时更新，无需重新训练模型
- 回答有据可查，可溯源到原始文档
- 私有数据不出本地，安全可控

---

## 核心组件

### LLM — DeepSeek-R1 7B（via Ollama）

**功能**：理解问题、结合检索到的知识片段生成自然语言回答。

**为什么选它**：DeepSeek-R1 是国产开源推理模型，中文理解能力强，7B 参数在消费级 GPU（6GB 显存）上可流畅运行。Ollama 提供统一的本地部署接口，一条命令拉取运行。

**同类替代**：

| 模型 | 参数量 | 特点 |
|------|--------|------|
| `qwen2.5:7b` | 7B | 阿里通义，中文同样优秀 |
| `llama3.1:8b` | 8B | Meta 开源，英文更强 |
| `gemma2:9b` | 9B | Google 开源，综合均衡 |
| `deepseek-r1:1.5b` | 1.5B | 显存不足时的轻量选项 |

---

### Embedding 模型 — nomic-embed-text（via Ollama）

**功能**：把文本（文档片段、用户问题）转换为高维向量，使语义相近的文本在向量空间中距离更近，从而支持语义检索而非关键词匹配。

**为什么选它**：nomic-embed-text 完全本地运行（274MB），中英文均支持，向量维度 768，在检索质量和速度之间取得良好平衡。

**同类替代**：

| 模型 | 特点 |
|------|------|
| `mxbai-embed-large` | 更高精度，体积稍大 |
| `bge-m3`（via Ollama） | 百度开源，中文检索更强 |
| `text-embedding-3-small`（OpenAI API） | 云端，需联网付费 |

---

### 向量数据库 — ChromaDB

**功能**：存储文档片段的向量表示，接收查询向量后快速返回最相似的 Top-K 片段（余弦相似度）。

**为什么选它**：ChromaDB 是纯 Python 实现，零配置，数据持久化到本地目录，适合单机原型项目，无需部署独立服务。

**同类替代**：

| 数据库 | 特点 | 适用场景 |
|--------|------|---------|
| FAISS | Meta 开源，纯内存，速度极快 | 大规模离线检索 |
| Milvus | 分布式，生产级 | 企业级部署 |
| Qdrant | Rust 实现，性能强，支持过滤 | 中大规模生产 |
| Weaviate | 内置 GraphQL，功能丰富 | 复杂查询场景 |
| pgvector | PostgreSQL 插件 | 已有 PG 数据库的项目 |

---

### RAG 框架 — LangChain

**功能**：串联 Embedding、向量数据库、LLM 等组件，提供文档加载、切片、检索链、对话记忆等开箱即用的抽象。

**为什么选它**：LangChain 是目前生态最完整的 RAG 框架，文档丰富，与 Ollama / ChromaDB 均有原生集成，适合快速搭建原型。

**同类替代**：

| 框架 | 特点 |
|------|------|
| LlamaIndex | 更专注于索引和检索，数据连接器更丰富 |
| Haystack | 企业级，Pipeline 设计更严谨 |
| DSPy | 编程式 Prompt 优化，适合研究场景 |
| 手写串联 | 依赖少，控制力强，适合生产精简 |

---

## 系统架构

```
离线构建（build_index.py）
  data/ 文档
     ↓ 切片 chunk_size=500, overlap=50
  文本片段
     ↓ nomic-embed-text 向量化
  向量 + 元数据 → ChromaDB（chroma_db/）

在线对话（chat.py）
  用户提问
     ↓ nomic-embed-text 向量化
  查询向量 → ChromaDB 检索 Top-4 片段
     ↓
  [系统 Prompt：导游人设]
  + [检索片段]
  + [最近 5 轮对话历史]
  + [用户问题]
     ↓ DeepSeek-R1 7B（Ollama）
  导游风格的自然语言回答
```

## 环境要求

- Python 3.10+
- NVIDIA GPU（推荐 6GB+ 显存，如 RTX 3060）
- 磁盘空间：约 10GB（模型 + 依赖）
- 操作系统：Windows / macOS / Linux

## 快速开始

### 第一步：安装 Ollama

前往 [https://ollama.com/download](https://ollama.com/download) 下载并安装。

这个比较快：

curl -fsSL https://cnb.cool/hex/ollama/-/git/raw/main/install.sh | sh

差不多20分钟等待 下载+安装；

安装完成后，拉取所需模型：

```bash
# 主模型（约 4.7GB，6GB 显存可运行）
ollama pull deepseek-r1:7b

# Embedding 模型（约 274MB）
ollama pull nomic-embed-text

# 验证主模型是否正常
ollama run deepseek-r1:7b "你好"
```

### 第二步：安装 Python 依赖

```bash
pip install langchain langchain-community chromadb ollama sentence-transformers
```

### 第三步：准备知识库

运行数据准备脚本，自动从中文维基百科（CC BY-SA 协议）抓取内容，并用本地 DeepSeek 生成 QA 数据：

```bash
# 仅需 requests，其余依赖已在第二步安装
pip install requests

# 查看会抓取哪些内容
python prepare_data.py --list

# 全量执行：抓取维基百科 + 生成 QA（推荐）
python prepare_data.py

# 分步执行
python prepare_data.py --fetch   # 仅抓取
python prepare_data.py --qa      # 仅生成 QA
```

脚本会自动生成以下结构：

```
data/
├── 景点/     西湖.txt、灵隐寺.txt、西溪湿地.txt ... 共 15 篇
│             西湖_qa.txt、灵隐寺_qa.txt ...（QA 问答）
├── 美食/     西湖醋鱼.txt、东坡肉.txt ... 共 9 篇
├── 交通/     杭州地铁.txt、杭州东站.txt ... 共 5 篇
└── 文化/     杭州.txt、西湖龙井.txt ... 共 5 篇
```

> 也可手动在对应目录下添加 `.txt` 文件来补充知识，格式参考：
> `【最佳游览时间】` `【门票】` `【交通】` `【必游景点】` `【小贴士】`

### 第四步：构建向量索引

```bash
python build_index.py

# 新增文档后重建
python build_index.py --reset
```

首次运行生成 `chroma_db/` 目录。`--reset` 参数会清空旧索引后重建，无需手动删目录。

### 第五步：启动导游对话

```bash
# 普通模式
python chat.py

# 调试模式（显示每次回答引用了哪些原始片段）
python chat.py --debug
```

输入问题开始对话，输入 `quit` / `退出` / `再见` 均可退出。

---

## 脚本说明

### prepare_data.py — 知识库数据准备

| 参数 | 说明 |
|------|------|
| （无参数） | 抓取维基百科 + 生成 QA，全量执行 |
| `--fetch` | 仅抓取维基百科（34 个词条） |
| `--qa` | 仅用本地 LLM 生成 QA 问答文件 |
| `--list` | 列出所有待抓取词条 |

- 数据来源：中文维基百科（CC BY-SA，合法免费）
- 每个词条截取前 3000 字，按中文标点切分
- QA 文件命名为 `景点名_qa.txt`，与原文档一起被索引
- 已有文件自动跳过，可安全重复运行

### build_index.py — 构建向量索引

| 参数 | 说明 |
|------|------|
| （无参数） | 构建索引（已有索引时追加） |
| `--reset` | 清空旧索引后重建 |

- 切分策略：`chunk_size=500`，`chunk_overlap=50`，优先按中文标点切分
- Embedding 模型：`nomic-embed-text`（本地运行，无需联网）

### chat.py — 对话主程序

| 参数 | 说明 |
|------|------|
| （无参数） | 启动对话 |
| `--debug` | 同时打印每次回答所引用的原始文档片段 |

- 多轮记忆：保留最近 5 轮对话上下文
- 每次检索召回 4 个最相关片段
- 退出关键词：`quit` / `exit` / `退出` / `再见`

---

## 优化路线图

### 阶段一：基础可用（已完成）
- [x] 本地 DeepSeek 模型运行（Ollama）
- [x] 中文维基百科数据抓取（prepare_data.py）
- [x] 本地 LLM 生成 QA 数据（prepare_data.py --qa）
- [x] ChromaDB 向量检索（build_index.py）
- [x] 多轮对话 + RAG 问答（chat.py）

### 阶段二：知识扩充
- [ ] 补充景点文档至 50 篇以上
- [ ] 添加美食、住宿、交通完整信息
- [ ] 加入节假日、季节性游览建议

### 阶段三：功能增强
- [ ] 接入实时天气 API（和风天气 / 高德）
- [ ] 加入地图链接（高德 POI）
- [ ] 支持多轮对话记忆（ConversationBufferMemory）

### 阶段四：界面优化
- [ ] Gradio Web 界面
- [ ] 或 Streamlit 界面
- [ ] 支持语音输入（可选）

### 阶段五：效果提升
- [ ] 用高质量 QA 数据做 LoRA 微调
- [ ] Reranker 重排序提升检索精度
- [ ] 评估框架（RAGAS）量化效果

---

## 常见问题

**Q：如何查看 CPU / GPU 资源，选择合适的模型？**

```bash
# 查看 GPU 显存（NVIDIA）
nvidia-smi

# 查看 GPU 显存（AMD / 通用，需安装 rocm-smi）
rocm-smi

# 查看 CPU 核心数和内存
# Windows
wmic cpu get NumberOfCores,NumberOfLogicalProcessors
systeminfo | findstr /C:"Total Physical Memory"

# macOS / Linux
nproc && free -h

# 查看 Ollama 当前模型运行状态（含显存占用）
ollama ps
```

模型选择参考：

| 显存 / 内存 | 推荐模型 | 说明 |
|------------|---------|------|
| ≥ 6GB 显存 | `deepseek-r1:7b` | 默认推荐，GPU 加速 |
| 4–6GB 显存 | `deepseek-r1:1.5b` | 速度快，质量略低 |
| 无 GPU / 纯 CPU | `deepseek-r1:1.5b` | 需 ≥ 8GB 内存，速度较慢 |

**Q：显存不够怎么办？**

```bash
# 换更小的模型
ollama pull deepseek-r1:1.5b
```

**Q：回答速度太慢？**

- 确认 GPU 被正确调用：`ollama ps` 查看运行状态
- 减小 `chunk_size` 和检索数量 `k`

**Q：新增文档后如何更新？**

```bash
python build_index.py --reset
```

**Q：回答引用了错误内容？**
```bash
# 用调试模式查看检索来源
python chat.py --debug
```

**Q：回答质量不好？**

- 优先补充更多、更详细的知识文档
- 调整 Prompt 中的导游人设描述
- 增大检索数量 `k`（从 3 改为 5）

**Q：能不能不写代码，直接用 `ollama run` 加载知识库对话？**

不能。`ollama run` 只启动纯 LLM 对话，不具备 RAG 能力，不会自动加载任何向量数据库。RAG 的检索→拼 Prompt→生成三个步骤必须由外部代码串联，Ollama 只负责最后的"生成"环节。

如果想要**无需写代码、带界面**的 RAG 体验，可以用以下现成工具：

**Open WebUI**（推荐，需要 Docker）

内置 RAG 功能，上传文档后自动建索引，对话时自动检索，完全图形化操作：

```bash
docker run -d -p 3000:80 \
  -v open-webui:/app/backend/data \
  --add-host=host.docker.internal:host-gateway \
  ghcr.io/open-webui/open-webui:main
```

启动后浏览器打开 `http://localhost:3000`，连接本地 Ollama，直接上传 `data/` 目录下的 txt 文件即可。

**AnythingLLM**（桌面应用，无需 Docker）

下载安装后，配置本地 Ollama 地址，拖拽上传文档，自动完成 RAG 全流程。官网：`https://anythingllm.com`

---

## 项目结构

```
hangzhou-guide/
├── README.md           # 本文档
├── prepare_data.py     # 知识库数据准备（抓取 + 生成 QA）
├── build_index.py      # 构建向量索引
├── chat.py             # 对话主程序
├── data/               # 知识库文档（由 prepare_data.py 生成）
│   ├── 景点/           # 西湖.txt、西湖_qa.txt ...
│   ├── 美食/
│   ├── 交通/
│   └── 文化/
└── chroma_db/          # 向量数据库（自动生成，勿手动修改）
```

---

## 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| 本地大模型 | DeepSeek-R1 7B via Ollama | 生成自然语言回答 |
| Embedding | nomic-embed-text via Ollama | 文本向量化（本地） |
| 向量数据库 | ChromaDB | 知识检索 |
| RAG 框架 | LangChain | 串联各组件 |
| 知识来源 | 中文维基百科（CC BY-SA） | 自动抓取，合法免费 |
| QA 生成 | DeepSeek 本地推理 | 自动生成问答对 |