# demo

**Repository Path**: sssugar0310/demo

## Basic Information

- **Project Name**: demo
- **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-06-15
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 旅游智库 - 智能知识库问答系统

基于 RAG（检索增强生成）架构的旅游知识库系统，支持景点攻略、线路推荐、酒店信息、美食推荐、交通指南等内容的智能问答。

## 部署架构

```
本机 Windows（开发机）                    虚拟机 192.168.10.150
┌──────────────────────┐                ┌──────────────────────┐
│ Python API 服务       │                │ Docker 服务           │
│  - import_api :8000  │ ──连接──→      │  - Milvus   :29530   │
│  - query_api  :8001  │                │  - Neo4j    :17687   │
│                      │                │  - MongoDB  :37017   │
│ 前端页面              │                │  - Attu     :17000   │
│  - localhost:8000    │                │  - MinIO    :19000   │
│  - localhost:8001    │                └──────────────────────┘
└──────────────────────┘
```

## 技术栈

| 组件 | 技术 | 说明 |
|------|------|------|
| LLM | MiMo-v2.5-pro（小米旗舰） | 场景分类、HyDE、KG抽取、答案生成 |
| 嵌入模型 | BGE-M3（本地部署） | 稠密+稀疏混合向量，1024维 |
| 精排模型 | BGE-Reranker-Large（本地） | Cross-encoder 精排 + 断崖截断 |
| 向量数据库 | Milvus 2.5.5 | chunk 向量存储 + 混合检索 |
| 图数据库 | Neo4j 2026.01.3 | 知识图谱实体关系存储 |
| 文档数据库 | MongoDB 7.0 | 聊天历史记录存储 |
| Web 搜索 | MCP 百炼搜索 | 本地知识库补充 |
| Web 框架 | FastAPI | 导入服务（8000）+ 查询服务（8001） |

## 项目结构

```
Travel_Knowledge/
├── import_all.py               # 一键清空并全量导入脚本
├── .env                        # 配置文件（LLM/数据库/模型路径）
├── requirements.txt            # Python 依赖
├── docker-compose.yml          # Docker 服务编排
│
├── core/                       # 核心配置
│   ├── config.py               # 全局配置（单例，从 .env 加载）
│   └── paths.py                # 项目路径常量
│
├── data/                       # 旅游数据（6城市 × 5类型 = 30个MD文件）
│   ├── 景点攻略/               # 每个城市一个文件，含 ## 元数据 块
│   ├── 线路推荐/
│   ├── 酒店信息/
│   ├── 美食推荐/
│   └── 交通指南/
│
├── processor/                  # 处理流水线
│   ├── import_process/         # 导入流水线（5节点）
│   │   ├── main_graph.py       # entry → split → embed → milvus → kg
│   │   ├── base.py             # 导入节点基类（统一日志+异常处理）
│   │   ├── state.py            # 导入流程状态定义
│   │   └── nodes/
│   │       ├── n01_entry_node.py           # 文件解析 + 元数据提取
│   │       ├── n02_document_split_node.py  # 按 ### 段落切分
│   │       ├── n03_bge_embedding_node.py   # BGE-M3 向量化
│   │       ├── n04_import_milvus_node.py   # 写入 Milvus
│   │       └── n05_kg_graph_node.py        # KG 抽取（仅景点攻略）
│   │
│   └── query_process/          # 查询流水线（8节点）
│       ├── main_graph.py       # classify → [vector|hyde|kg|web] → rrf → rerank → answer
│       ├── base.py             # 查询节点基类（出错降级，不抛异常）
│       ├── state.py            # 查询流程状态定义
│       └── nodes/
│           ├── n01_scene_classifier_node.py  # 场景分类器
│           ├── n02_vector_search_node.py     # 向量检索
│           ├── n03_hyde_search_node.py       # HyDE 检索
│           ├── n04_kg_search_node.py         # 图谱检索
│           ├── n05_web_search_node.py        # Web 搜索
│           ├── n06_rrf_node.py               # RRF 融合
│           ├── n07_rerank_node.py            # Rerank 精排
│           └── n08_answer_output_node.py     # 答案生成
│
├── prompts/                    # Prompt 模板
│   ├── upload/import_prompt.py # KG 抽取 prompt（实体关系抽取）
│   └── query/query_prompt.py   # 查询全流程 prompt
│
├── utils/                      # 工具模块（单例模式，全局复用）
│   ├── llm_util.py             # MiMo-v2.5-pro 客户端
│   ├── embedding_util.py       # BGE-M3 本地模型
│   ├── milvus_util.py          # Milvus 混合检索
│   ├── neo4j_util.py           # Neo4j 驱动
│   ├── mongo_util.py           # MongoDB 客户端
│   ├── rerank_util.py          # BGE-Reranker
│   ├── metadata_util.py        # 元数据解析（正则，零LLM调用）
│   └── chunk_extract_util.py   # Milvus 结果提取
│
├── api/                        # FastAPI 服务
│   ├── import_api.py           # 导入服务（端口 8000）
│   └── query_api.py            # 查询服务（端口 8001）
│
└── front/                      # 前端页面
    ├── chat.html               # 问答界面
    └── import.html             # 导入界面
```

## 快速开始

### 1. 启动 Docker 服务（虚拟机上执行）

```bash
cd /path/to/Travel_Knowledge
docker-compose up -d
```

验证服务状态：

```bash
docker ps --filter "name=travel-"
```

全部 `healthy` 后继续。

### 2. 安装 Python 依赖（本机执行）

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

### 3. 导入数据

**一键清空并全量导入（推荐）：**

```bash
python import_all.py
```

该脚本会：
1. 清空 Milvus（travel_kb_chunks + travel_kb_entities）
2. 清空 Neo4j 所有节点和关系
3. 清空 MongoDB chat_messages 集合
4. 批量导入 data/ 下所有 30 个 MD 文件（含 KG 抽取）

**通过 API 逐个上传：**

启动导入服务后访问 http://localhost:8000/import

### 4. 启动服务（本机执行）

```bash
# 导入服务（端口 8000）
python -m api.import_api

# 查询服务（端口 8001）
python -m api.query_api
```

### 5. 访问前端

| 页面 | 地址 | 说明 |
|------|------|------|
| 问答 | http://localhost:8001/chat | 智能问答界面 |
| 导入 | http://localhost:8000/import | 数据导入界面 |
| Attu | http://192.168.10.150:17000 | Milvus 可视化管理 |
| Neo4j | http://192.168.10.150:17474 | Neo4j 浏览器 |

## 配置说明

所有配置在 `.env` 文件中：

```ini
# LLM（小米 MiMo-v2.5-pro）
LLM_API_BASE=https://token-plan-cn.xiaomimimo.com/v1
LLM_API_KEY=your-key
LLM_MODEL=mimo-v2.5-pro

# 嵌入模型（本地部署）
BGE_M3_PATH=D:\bge_models\BAAI\bge-m3
BGE_DEVICE=cuda              # cuda 或 cpu
BGE_FP16=True                # GPU 时开启，CPU 时关闭

# 精排模型（本地）
RERANK_MODEL_PATH=D:\bge_models\BAAI\bge-reranker-large

# Milvus
MILVUS_URL=http://192.168.10.150:29530

# Neo4j
NEO4J_URI=bolt://192.168.10.150:17687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password

# MongoDB
MONGO_URI=mongodb://root:123456@192.168.10.150:37017
MONGO_DB=travel_kb

# Web 搜索（MCP 百炼）
MCP_DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/api/v1/mcps/WebSearch/mcp
DASHSCOPE_API_KEY=your-key
```

## Docker 端口映射

| 服务 | 宿主机端口 | 容器端口 |
|------|-----------|---------|
| MinIO API | 19000 | 9000 |
| MinIO 控制台 | 19001 | 9001 |
| Milvus | 29530 | 19530 |
| Milvus 健康检查 | 29091 | 9091 |
| Attu | 17000 | 7000 |
| Neo4j 浏览器 | 17474 | 7474 |
| Neo4j Bolt | 17687 | 7687 |
| MongoDB | 37017 | 27017 |

## 数据格式

每个 MD 文件需包含 `## 元数据` 块：

```markdown
# 三亚景点推荐
## 元数据
- 内容类型：景点介绍
- 城市：三亚
- 主题：海湾、离岛、西线观光

## 目的地概览
...

## 核心景点推荐
### 亚龙湾
...
```

文件放在 `data/` 对应的子目录下，目录名即内容类型。

## 查询流程

```
用户提问
  ↓
场景分类器（MiMo：提取城市/类型/人群/改写查询）
  ↓
┌────────────┬────────────┬────────────┬────────────┐
│ 向量检索    │ HyDE 检索   │ KG 检索     │ Web 搜索   │
│ BGE-M3     │ LLM+BGE-M3 │ Neo4j图查询 │ MCP百炼    │
└────────────┴────────────┴────────────┴────────────┘
  ↓
RRF 融合（向量:1.0 + HyDE:1.0 + KG:0.7）
  ↓
Rerank 精排（BGE-Reranker + 断崖截断）
  ↓
答案生成（MiMo：基于检索结果 + 图谱三元组）
```

## API 接口

### 导入服务（端口 8000）

```
POST /upload          上传 MD 文件并导入
GET  /stats           查询数据统计
GET  /import          前端页面
GET  /health          健康检查
```

### 查询服务（端口 8001）

```
POST /query           提交问题（SSE 流式输出）
GET  /chat            前端页面
GET  /stats           查询数据统计
GET  /health          健康检查
```

#### POST /query 请求体

```json
{
  "query": "三亚有哪些适合老人去的景点？",
  "session_id": "sess_001",
  "history": [
    {"role": "user", "content": "你好"},
    {"role": "assistant", "content": "你好，有什么可以帮你的？"}
  ]
}
```

#### POST /query 响应（SSE 流式）

```
data: {"type": "progress", "node": "scene_classifier"}
data: {"type": "progress", "node": "vector_search"}
data: {"type": "delta", "content": "三亚"}
data: {"type": "delta", "content": "适合"}
...
data: {"type": "answer", "answer": "三亚适合老人去的景点主要是..."}
data: {"type": "done"}
```

## 数据库说明

### Milvus（向量数据库）

**travel_kb_chunks 集合：**
- chunk_id: INT64 主键（自动递增）
- dense_vector: FLOAT_VECTOR 1024维（COSINE 索引）
- sparse_vector: SPARSE_FLOAT_VECTOR（IP 索引）
- content/title/file_title/city/content_type: VARCHAR 标量字段

**travel_kb_entities 集合：**
- pk: INT64 主键（自动递增）
- entity_name: VARCHAR（实体名称）
- dense_vector/sparse_vector: 混合向量
- source_chunk_id/context/item_name: 来源信息

### Neo4j（图数据库）

**节点类型：**
- Chunk: {id, item_name}
- Entity: {name, item_name, description} + 动态标签（Attraction/Hotel/Restaurant 等）

**关系类型：**
- LOCATED_IN, SUITABLE_FOR, HAS_FEATURE, HAS_ACTIVITY
- BEST_SEASON, NEAR_TO, COVERS, MENTIONED_IN, RELATED_TO

### MongoDB（文档数据库）

**travel_kb 数据库：**
- chat_messages 集合：存储聊天历史记录