# smart-agent

**Repository Path**: myparadises/smart-agent

## Basic Information

- **Project Name**: smart-agent
- **Description**: 本项目基于 LangChain 框架构建了一个智能点餐对话 Agent 系统，集成了多种 AI 技术实现餐厅服务的智能化和自动化。系统通过自然语言对话，为用户提供菜品推荐、餐厅预订、FAQ
问答等一站式服务。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-07
- **Last Updated**: 2026-02-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能点购系统

## 项目简介

`本项目基于 LangChain 框架构建了一个智能点餐对话 Agent 系统，集成了多种 AI 技术实现餐厅服务的智能化和自动化。系统通过自然语言对话，为用户提供菜品推荐、餐厅预订、FAQ
问答等一站式服务。`

![智能点餐系统界面](media/image1.png)

## 核心功能

### 🍽️ 智能对话点餐

- 基于用户口味偏好推荐菜品
- 多轮对话收集预订信息
- 自然语言理解和响应

### 🔍 向量搜索推荐

- 使用 Milvus 向量数据库存储菜品特征
- 基于 BGE-M3 模型进行语义搜索
- 根据用户查询匹配最相关菜品

### 📅 智能预订系统

- 结构化参数收集（人数、时间、偏好等）
- 数据持久化存储到 MySQL
- 预订信息确认流程

### ❓ FAQ 智能问答

- Redis 存储常见问题库
- 实时相似度匹配建议
- 用户输入过程中的智能提示

### 🗺️ 地理信息服务

- 集成高德地图 MCP 工具
- 提供导航和位置信息

## 技术架构

### 后端技术栈

- **框架**: FastAPI + LangChain
- **AI 模型**: BGE-M3（向量化）、DeepSeek/ChatOpenAI（对话）
- **数据库**: MySQL（结构化数据）、Redis（缓存/FAQ）、Milvus（向量数据）
- **部署**: Uvicorn（ASGI 服务器）

### 前端技术栈

- Vue.js + Element Plus
- Vite 构建工具
- SSE（Server-Sent Events）流式响应

### 开发工具

- **环境管理**: UV（快速 Python 包管理器）
- **版本控制**: Git
- **项目管理**: pyproject.toml

## 系统架构图

```
┌─────────────────────────────────────────────────────────┐
│                     前端界面 (Vue.js)                     │
├─────────────────────────────────────────────────────────┤
│         API 接口层 (FastAPI + SSE 流式响应)              │
├─────────────────────────────────────────────────────────┤
│         Agent 核心层 (LangChain + 工具集成)              │
├───────────┬───────────┬───────────┬───────────┬─────────┤
│  MySQL    │   Redis   │  Milvus   │  MCP工具  │  模型   │
│ (菜单/预订)│  (FAQ缓存) │(向量搜索) │(高德地图) │(BGE-M3) │
└───────────┴───────────┴───────────┴───────────┴─────────┘
```

## 数据库设计

### 菜单表 (menu_items)

```sql
CREATE TABLE `menu_items`
(
    `id`               int                                                           NOT NULL AUTO_INCREMENT COMMENT '菜品ID，主键自增',
    `dish_name`        varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '菜品名称',
    `price`            decimal(8, 2)                                                 NOT NULL COMMENT '价格（元）',
    `description`      text CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci COMMENT '菜品描述',
    `category`         varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci  NOT NULL COMMENT '菜品分类',
    `spice_level`      tinyint                                                       DEFAULT '0' COMMENT '辣度等级：0-不辣，1-微辣，2-中辣，3-重辣',
    `flavor`           varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '口味特点',
    `main_ingredients` text CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci COMMENT '主要食材，多个食材用逗号分隔',
    `cooking_method`   varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci  DEFAULT NULL COMMENT '烹饪方法',
    `is_vegetarian`    tinyint(1) DEFAULT '0' COMMENT '是否素食：0-否，1-是',
    `allergens`        varchar(200) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '过敏原信息，多个过敏原用逗号分隔',
    `is_available`     tinyint(1) DEFAULT '1' COMMENT '是否可供应：0-不可用，1-可用',
    `is_featured`      tinyint(1) DEFAULT '0' COMMENT '是否特色主菜：0-否，1-是',
    `created_at`       timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `updated_at`       timestamp NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    PRIMARY KEY (`id`) USING BTREE,
    KEY                `idx_category` (`category`) USING BTREE,
    KEY                `idx_is_available` (`is_available`) USING BTREE,
    KEY                `idx_is_vegetarian` (`is_vegetarian`) USING BTREE,
    KEY                `idx_price` (`price`) USING BTREE,
    KEY                `idx_spice_level` (`spice_level`) USING BTREE
) ENGINE=InnoDB AUTO_INCREMENT=6 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci ROW_FORMAT=DYNAMIC COMMENT='菜单表';
```

### 预订单表 (reservation_order)

```sql
CREATE TABLE `reservation_order`
(
    `id`                   int      NOT NULL AUTO_INCREMENT COMMENT '预订单ID，主键自增',
    `num_people`           int      NOT NULL COMMENT '客人人数',
    `num_children`         int      NOT NULL COMMENT '儿童人数',
    `arrival_time`         datetime NOT NULL COMMENT '到达时间',
    `seat_preference`      varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '座位偏好',
    `main_dish_preference` varchar(100) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci DEFAULT NULL COMMENT '主菜偏好',
    `other_comments`       text CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci COMMENT '其他备注需求',
    `created_at`           timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    `updated_at`           timestamp NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB AUTO_INCREMENT=28 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci ROW_FORMAT=DYNAMIC COMMENT='预订单表';
```

## 核心 Agent 设计

### 系统提示词

Agent 被设计为餐厅智能助手，具有以下核心能力：

1. **回答问题**：基于餐厅事实信息回答常见问题
2. **完成预订**：收集必要信息并执行预订操作
3. **菜品推荐**：根据用户口味推荐合适菜品

### 工具定义

1. **search_featured_dishes()** - 查询特色主菜
2. **main_dish_recommendation()** - 基于向量搜索推荐菜品
3. **make_reservation()** - 执行预订操作
4. **高德地图 MCP 工具** - 提供地理信息服务

## 关键技术实现

### 1. 向量数据同步

```python
# 将 MySQL 菜品数据同步到 Milvus
def sync_milvus():
# 1. 从 MySQL 读取菜品数据
# 2. 使用 BGE-M3 模型生成向量
# 3. 存储到 Milvus 向量数据库
```

### 2. FAQ 相似度匹配

```python
def get_similarity_score(query: str, candidate: str) -> float:
# 使用三种策略计算相似度：
# 1. SequenceMatcher.ratio() 字符序列相似度
# 2. Jaccard 相似度（字符集合）
# 3. 包含关系 bonus
```

### 3. 流式响应接口

```python
@app.post("/chat")
async def chat_endpoint(request: ChatRequest):
    # 使用 SSE 技术实现打字机效果
    return StreamingResponse(
        chat_with_assistant(request.query),
        media_type="text/event-stream"
    )
```

## API 接口

### 主要端点

- `POST /chat` - 智能对话接口（流式响应）
- `GET /faq/suggest` - FAQ 建议接口
- `GET /reservation/list` - 预订列表查询
- `GET /menu/list` - 菜品列表查询

## 部署与运行

### 环境要求

- Python 3.12+
- MySQL 8.0+
- Redis 7.0+
- Milvus 2.4+

### 快速启动

1. **后端启动**

```bash
# 安装依赖
uv venv --python 3.12
uv add -r requirements.txt

# 启动服务
python run.py
```

2. **前端启动**

```bash
cd ui
npm install
npm run dev
```

3. **数据同步**

```bash
# 一键同步 Milvus 和 Redis FAQ 数据

python src.core.sync_data.py
```

### 访问地址

- **前端界面**: http://localhost:3000
- **后端 API**: http://localhost:8000
- **API 文档**: http://localhost:8000/docs

## 项目特色

### 🚀 技术先进性

- 使用最新的 LangChain 框架构建智能体
- 集成向量数据库实现语义搜索
- 采用 SSE 实现流畅的流式响应

### 🎯 业务实用性

- 完整的餐厅服务流程覆盖
- 智能的菜品推荐算法
- 友好的用户交互体验

### 🔧 工程规范性

- 清晰的项目结构分层
- 完善的环境配置管理
- 标准化的 API 设计

## 适用场景

1. **智能餐厅助手** - 为顾客提供自动化点餐服务
2. **教育培训** - 学习 LangChain 和大模型应用开发
3. **技术研究** - 研究 AI Agent 在实际业务中的应用

## 项目结构

```
smart-restaurant-agent/
├── src/
│   ├── run.py          # 启动入口
│   ├── configuration/  # 配置文件
│   ├── core/           # 核心代码
│   ├── utils/          # 工具模块
│   ├── web/            # 前端模块
│   │   ├── api/
├── ui/              # 前端界面
├── models/          # 用的系统的没放这里
├── data/            # 数据文件
├── .env             # 环境配置
├── pyproject.toml   # 项目配置
└── run.py           # 启动入口
```

## 学习价值

本项目涵盖了现代 AI 应用开发的关键技术：

- LangChain 框架的实践应用
- 向量数据库的集成使用
- 大模型工具的编排调用
- 实时流式响应的实现
- 多数据源的协同工作

---

**项目地址
**: [https://gitee.com/myparadises/smart-agent](https://gitee.com/myparadises/smart-agent)

**许可证**: MIT License

**版本**: v1.0.0

**最后更新**: 2026年2月7日

---

通过本项目，您可以学习到如何将现代 AI 技术与传统业务场景相结合，构建出真正有价值的智能应用系统。