味觉笔记 · Savor

AI 私厨助手 — 拍张食材照片，秒出食谱方案。多模态识别 · 智能搜索 · 流式对话 · 全链路可观测。

---

功能展示

---

功能

用户侧

• 📸 图片识别 — 拍照上传食材，AI 自动辨识并评估新鲜度
• 💬 流式对话 — 实时流式输出，不用等待完整响应
• 🔍 智能搜索 — 基于 Tavily 实时检索网络食谱
• 📝 多模态输入 — 图片 + 文字混合，灵活表达需求
• 📂 会话管理 — 多会话独立切换，历史消息持久保存

工程侧

• 🧩 Prompt 配置中心 — prompts/*.yaml 统一管理所有 prompt，版本可追踪
• 🔄 Agent 容错机制 — 识别失败自动降级，搜索无结果换词重试，API 异常指数退避
• 📊 全链路可观测 — 请求级 trace（LLM 调用 / 工具调用 / 延迟 / token）
• 🖥 实时看板 — /dashboard 统计卡片 + 延迟分布图 + 请求状态饼图 + 最近请求表
• 💚 健康检查 — /api/v1/health 检测 DB / LLM API / Prompt 加载状态
• 📋 JSON 结构化日志 — 每条日志带 trace_id，可被日志系统直接消费

---

技术栈

层	技术
前端	Next.js 16, React 19, Tailwind CSS 4, react-markdown
后端	FastAPI, LangChain, LangGraph, PyYAML
AI	通义千问 (qwen3.5-plus via DashScope)
搜索	Tavily Search API
存储	阿里云 OSS (图片), SQLite (会话 & checkpoint)

---

项目结构

TasteNotes/
├── app/                          # FastAPI 后端
│   ├── main.py                   # 入口：中间件注册、路由挂载、静态文件
│   ├── agent/
│   │   └── personal_chef.py      # AI Agent：识别 → 搜索 → 评分 → 推荐
│   ├── core/                     # 核心服务
│   │   ├── config.py             # ConfigService — YAML 配置加载单例
│   │   ├── observability.py      # Trace + Metrics + TraceMiddleware
│   │   └── resilience.py         # 搜索重试、识别失败检测、降级文案
│   ├── api/v1/
│   │   ├── chat.py               # 对话流式 API
│   │   ├── oss.py                # OSS 预签名上传 URL
│   │   ├── health.py             # 健康检查端点
│   │   └── observability.py      # 观测数据 API (traces / metrics)
│   ├── common/
│   │   └── logger.py             # JSON 结构化日志
│   ├── models/
│   │   └── schemas.py            # Pydantic 数据模型
│   └── templates/
│       └── dashboard.html        # 性能看板页面
├── prompts/                      # Prompt 配置文件
│   ├── chef_system.yaml          # 主厨 system prompt
│   ├── fallback.yaml             # 容错降级文案
│   └── model_config.yaml         # LLM 连接参数
├── frontend/                     # Next.js 前端
│   ├── app/                      # 页面 & 全局样式
│   ├── components/               # ChatMessage, ChatInput, Sidebar 等
│   ├── lib/api.ts                # API 调用封装
│   └── types/chat.ts             # TypeScript 类型
├── assets/                       # README 展示图片
├── .env.example                  # 环境变量模板
└── pyproject.toml                # Python 依赖

---

快速开始

1. 环境要求

• Python >= 3.13
• Node.js >= 18

git clone https://github.com/kiym7/TasteNotes_agent.git
cd TasteNotes

2. 配置环境变量

cp .env.example .env

编辑 .env，填入以下服务的 API Key：

服务	用途	申请地址
DashScope	AI 模型 (qwen3.5-plus)	https://dashscope.aliyun.com
Tavily	食谱联网搜索	https://tavily.com
阿里云 OSS	图片上传存储	https://oss.console.aliyun.com

3. 安装依赖

uv sync                   # Python 依赖
cd frontend && npm install  # 前端依赖

4. 构建前端

cd frontend && npm run build
cp -r out ../app/static

5. 启动

uv run python -m app.main

然后访问：

地址	说明
http://127.0.0.1:8001	聊天界面
http://127.0.0.1:8001/dashboard	性能看板
http://127.0.0.1:8001/api/v1/health	健康检查
http://127.0.0.1:8001/docs	Swagger API 文档

---

Prompt 配置

所有 prompt 集中在 prompts/ 目录，YAML 格式，修改后重启即生效：

# prompts/chef_system.yaml
id: chef_system
version: "1.0"
model: qwen3.5-plus
prompt: |
  你是味觉笔记 (Savor) 的 AI 主厨...
metadata:
  max_tokens: 4096
  temperature: 0.7

支持多版本管理：创建 chef_system@v1.1.yaml，修改 model_config.yaml 指定模型参数。

---

OSS 配置

阿里云 OSS Bucket 需配置 CORS 规则（浏览器直传需要）：

配置项	值
来源 Origin	*
允许 Methods	PUT, GET
允许 Headers	*
暴露 Headers	ETag