# SmartDietian

**Repository Path**: zeron2022/smart-dietian

## Basic Information

- **Project Name**: SmartDietian
- **Description**: 一个基于大语言模型的 AI 私人厨师应用。用户上传食材图片或描述食材清单，LangChain/LangGraph Agent 自动识别食材、搜索食谱，从营养价值和制作难度多维度评分排序，返回结构化的推荐报告。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 4
- **Created**: 2026-07-26
- **Last Updated**: 2026-07-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Smart Dietian（智能私厨）

一个基于大语言模型的 AI 私人厨师应用。用户上传食材图片或描述食材清单，LangChain/LangGraph Agent 自动识别食材、搜索食谱，从营养价值和制作难度多维度评分排序，返回结构化的推荐报告。

## 核心特性

- **多模态识别**：支持上传食材图片，LLM 自动辨识并评估新鲜度与可用量
- **智能食谱搜索**：Agent 自动调用 Tavily 搜索引擎检索可行菜谱
- **多维度评分排序**：从营养价值和制作难度两个维度量化打分，简单又营养的排名靠前
- **结构化推荐报告**：包含食谱信息、得分、推荐理由的完整建议报告
- **流式对话**：基于 SSE (Server-Sent Events) 的实时流式响应
- **会话管理**：支持多会话历史记录，可切换、删除历史会话
- **国际化**：支持中英文界面切换（vue-i18n）
- **Markdown 渲染**：AI 回复自动渲染为格式化内容

## 效果展示

以下是 Smart Dietian 的实际运行效果：

<table>
  <tr>
    <td><img src="docs/images/feature-1.png" width="400"/></td>
    <td><img src="docs/images/feature-2.png" width="400"/></td>
  </tr>
  <tr>
    <td><img src="docs/images/feature-3.png" width="400"/></td>
    <td><img src="docs/images/feature-4.jpg" width="400"/></td>
  </tr>
</table>

## 技术栈

### 后端

| 技术 | 版本 | 用途 |
|------|------|------|
| FastAPI | 0.128.0 | Web 框架 |
| LangChain | 1.2.3 | LLM 应用框架 |
| LangGraph | 0.7.60 | Agent 状态图编排 |
| langgraph-checkpoint-redis | 0.4.0 | Redis 会话记忆持久化 |
| langchain-tavily | 0.2.17 | Tavily 网络搜索工具 |
| Uvicorn | 0.40.0 | ASGI 服务器 |
| Redis Stack | latest | 向量存储 + RediSearch |
| 阿里云 OSS v2 | 1.2.4 | 图片对象存储 |

**LLM 模型**：通义千问 Qwen 3.7 Plus（通过 DashScope OpenAI 兼容 API）

### 前端

| 技术 | 版本 | 用途 |
|------|------|------|
| Vue 3 | 3.5.13 | 前端框架 |
| TypeScript | 5.8.3 | 类型系统 |
| Vite | 6.3.2 | 构建工具 |
| TailwindCSS | 3.4.17 | 样式框架 |
| Pinia | 3.0.2 | 状态管理 |
| vue-i18n | 11.1.3 | 国际化 |
| Lucide Vue Next | 0.474.0 | 图标库 |
| markdown-it | 14.1.0 | Markdown 渲染 |

## 项目结构

```
SmartDietian/
├── app/                          # 后端应用
│   ├── agent/
│   │   └── personal_chief.py     # LangGraph Agent 核心（LLM、工具、记忆、流式输出）
│   ├── api/
│   │   └── v1/
│   │       ├── chat.py           # 对话接口（流式对话 / 历史消息 / 会话列表）
│   │       └── oss.py            # OSS 预签名上传 URL 接口
│   ├── models/
│   │   └── schemas.py            # Pydantic 请求/响应模型
│   ├── common/
│   │   └── logger.py             # 日志配置
│   ├── static/                   # 前端构建产物（Vite build 输出）
│   └── main.py                   # FastAPI 入口（CORS、路由、SPA fallback）
├── frontend/                     # 前端源码
│   ├── src/
│   │   ├── api/                  # API 调用（chat.ts / oss.ts）
│   │   ├── components/           # Vue 组件
│   │   │   ├── AppHeader.vue     # 顶部导航栏
│   │   │   ├── AppChat.vue       # 主聊天区域（流式消息 + 图片上传）
│   │   │   ├── ChatSidebar.vue   # 历史会话侧边栏
│   │   │   ├── ChatMessage.vue   # 消息气泡（Markdown 渲染）
│   │   │   ├── ChatInput.vue     # 输入框（文本 + 图片选择）
│   │   │   └── ChatEmpty.vue     # 空状态引导
│   │   ├── composables/          # 组合式函数
│   │   │   ├── useChat.ts        # 会话管理逻辑
│   │   │   └── useImageUpload.ts # 图片上传流程
│   │   ├── locales/              # 国际化文件（zh-CN / en）
│   │   └── assets/               # 静态资源
│   ├── index.html
│   ├── package.json
│   ├── vite.config.ts            # Vite 配置（代理 + 构建输出路径）
│   └── tailwind.config.js
├── .env                           # 环境变量（不提交）
├── .gitignore
├── CLAUDE.md                      # AI 辅助开发指南
├── pyproject.toml                 # Python 项目配置
├── uv.lock                        # uv 依赖锁文件
└── README.md
```

## 系统架构

```
用户 → Vue 3 SPA → FastAPI → LangGraph Agent
                                ├── Qwen 3.7 Plus (多模态 LLM)
                                ├── Tavily Search (网络搜索)
                                ├── Redis Stack (会话记忆/Checkpoint)
                                └── 阿里云 OSS (图片存储)
```

### 数据流

1. 用户在前端输入食材描述或上传图片
2. 若上传图片，前端通过 OSS 预签名 URL 直传到阿里云 OSS
3. 前端通过 `POST /api/v1/chat/stream` 以 SSE 方式发送请求
4. Agent 接收多模态消息（文本 + 图片 URL），按流程处理：
   - 识别食材 → 搜索食谱 → 评分排序 → 生成推荐报告
5. 响应实时流式返回前端，Markdown 渲染展示
6. 会话状态通过 Redis Checkpoint 持久化，支持历史回顾

## 环境要求

- **Python**: >= 3.13
- **Node.js**: >= 18（推荐 22.22.2）
- **Redis Stack**：含 RediSearch 模块（Docker 推荐）
- **包管理器**：
  - Python：`uv`（推荐）
  - Node.js：`npm`

## 快速开始

### 1. 克隆项目

```bash
git clone https://gitee.com/yuanwang99/smart-dietian.git
cd smart-dietian
```

### 2. 启动 Redis Stack

```bash
docker run -d --name redis-stack -p 6379:6379 redis/redis-stack:latest
```

### 3. 配置环境变量

创建 `.env` 文件：

```env
# 通义千问 API（DashScope OpenAI 兼容接口）
DASHSCOPE_API_KEY=your_dashscope_api_key
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

# Tavily 搜索 API
TAVILY_API_KEY=your_tavily_api_key

# 阿里云 OSS 配置
OSS_ACCESS_KEY_ID=your_access_key_id
OSS_ACCESS_KEY_SECRET=your_access_key_secret
OSS_ENDPOINT=oss-cn-beijing.aliyuncs.com
OSS_BUCKET=your_bucket_name

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
```

### 4. 后端部署

```bash
# 安装依赖
uv sync

# 启动开发服务器（热重载）
python -m app.main
```

服务运行在 http://127.0.0.1:8001，访问 `/docs` 查看 Swagger API 文档。

### 5. 前端开发

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

前端开发服务器运行在 http://localhost:5173，API 请求自动代理到后端。

### 6. 生产构建

```bash
# 构建前端（输出到 app/static/）
cd frontend && npm run build

# 启动生产服务器
cd .. && uvicorn app.main:app --host 0.0.0.0 --port 8001
```

构建后前端静态文件集成在后端服务中，只需启动后端即可访问完整应用。

## API 接口

基础 URL：`http://127.0.0.1:8001/api/v1`

### 对话

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/chat/stream` | 流式对话（SSE），支持文本 + 图片多模态输入 |
| GET | `/chat/messages?thread_id=xxx` | 获取指定会话的历史消息 |
| DELETE | `/chat/messages?thread_id=xxx` | 删除指定会话 |
| GET | `/chat/threads` | 获取所有会话列表 |

#### 流式对话请求示例

```json
{
  "message": "这些食材可以做什么菜？",
  "image_url": "https://bucket.oss-cn-beijing.aliyuncs.com/food.jpg",
  "thread_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

### 文件上传

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/oss/presign?filename=food.jpg` | 获取 OSS 预签名上传 URL |

返回 `uploadUrl`（用于客户端直传）和 `accessUrl`（图片访问地址）。

## Agent 工作流程

```
用户输入（食材图片/文字）
    │
    ▼
┌─────────────────────────────┐
│ 1. 识别和评估食材            │
│    辨识可见食材，评估新鲜度   │
│    整理「当前可用食材清单」   │
├─────────────────────────────┤
│ 2. 智能食谱检索              │
│    调用 Tavily 搜索食谱      │
├─────────────────────────────┤
│ 3. 多维度评估排序            │
│    营养价值 + 制作难度 打分  │
│    简单营养的排名靠前         │
├─────────────────────────────┤
│ 4. 结构化方案输出            │
│    食谱信息 / 得分 / 推荐理由 │
└─────────────────────────────┘
    │
    ▼
流式输出 → 前端 Markdown 渲染
```

## 核心模块说明

### Agent（`app/agent/personal_chief.py`）

- 基于 LangChain `create_agent` 构建
- 使用 **Qwen 3.7 Plus** 多模态模型，支持图文理解
- 集成 **Tavily Search** 作为网络搜索工具
- 通过 **RedisSaver** 实现 LangGraph Checkpoint 会话持久化
- 支持 `stream_mode="messages"` 逐 token 流式输出

### 前端会话管理（`useChat.ts` + `ChatSidebar.vue`）

- 自动生成 UUID 作为 thread_id，存储在 localStorage
- 支持多会话切换、历史消息加载
- 侧边栏展示所有会话预览，支持删除操作
- 流式响应期间可中断（AbortController）

### 图片上传（`useImageUpload.ts` + `oss.ts`）

- 前端选择图片后本地预览
- 通过 OSS 预签名 URL 客户端直传，不经过后端中转
- 上传完成后返回可访问的 HTTPS URL，随对话请求发送给 Agent

## 开发指南

### IDE 配置（Claude Code）

项目包含 `CLAUDE.md` 文件，为 Claude Code（VS Code 扩展）提供上下文指导。推荐使用 Claude Code 作为 AI 辅助开发工具。

### 代码规范

- **Python**：遵循 PEP 8
- **TypeScript/Vue**：使用 TypeScript 严格模式
- **提交规范**：[Conventional Commits](https://www.conventionalcommits.org/)

```
feat: 新功能
fix: 修复
docs: 文档更新
refactor: 重构
style: 格式调整
chore: 构建/工具配置
```

## 常见问题

**Q: Redis 连接失败？**
A: 确保 Redis Stack 已启动（`docker ps`），且端口 6379 未被占用。Agent 强制使用 db 0（RediSearch 索引限制）。

**Q: 图片上传失败？**
A: 检查 `.env` 中 OSS 相关配置是否正确，Bucket 是否存在且允许跨域访问。

**Q: 前端开发时 API 请求 404？**
A: 确保后端已启动在 8001 端口，Vite 代理配置会将 `/api` 请求转发到后端。

## 许可证

MIT License

## 作者

**袁旺** - [Gitee @yuanwang99](https://gitee.com/yuanwang99)

项目地址：[https://gitee.com/yuanwang99/smart-dietian](https://gitee.com/yuanwang99/smart-dietian)

---

⭐ 如果这个项目对你有帮助，请 Star 支持！