一.项目
1.1 需求
| 角色 | 痛点 | 核心诉求 |
|---|
| 家庭烹饪新手 | 面对冰箱里的食材不知道做什么 | 输入食材 → 获得可行菜谱 |
| 日常买菜族 | 买完菜后决策疲劳 | 拍照即出推荐，省去搜索步骤 |
| 健康饮食关注者 | 希望兼顾营养与简易度 | 按营养+难度量化打分，科学排序 |
1.2 技术栈总结
| 类别 | 技术选型 | 版本 | 作用 |
|---|
| 语言 | Python | 3.12 | 后端核心语言 |
| Web 框架 | FastAPI | ≥0.109 | 异步 HTTP 服务 |
| ASGI | Uvicorn | ≥0.27 | 服务器运行 |
| AI 框架 | LangChain | ≥0.3 | Agent 编排 |
| LangGraph | ≥0.3 | 状态图编排 + 会话持久化 |
| LLM | 通义千问 qwen3.5-plus | — | 多模态推理（DashScope，OpenAI 兼容接口） |
| 搜索 | Tavily Search | — | 实时 Web 菜谱搜索 |
| 记忆 | SQLite（LangGraph SqliteSaver） | — | 会话历史持久化 |
| 图片存储 | 阿里云 OSS | — | 食材照片云端存储 |
| 前端 | 原生 HTML/CSS/JS | — | 单页聊天应用（764行） |
| 包管理 | uv | — | 依赖管理与虚拟环境 |
| 部署 | LangGraph API | — | 云平台部署配置 |
| 可观测 | LangSmith | — | LLM 调用链追踪 |
| 序列化 | Pydantic | ≥2.0 | 数据模型校验 |
1.3 核心功能
| 特性 | 状态 | 说明 |
|---|
| 食材图片识别 | ✅ 已实现 | 多模态 LLM 识别照片中的食材种类和数量 |
| 新鲜度评估 | ✅ 已实现 | 基于外观状态判断食材新鲜程度 |
| 智能菜谱检索 | ✅ 已实现 | Tavily Web 搜索 + LLM 理解，组合食材关键词搜菜谱 |
| 双维度打分 | ✅ 已实现 | 营养价值 + 制作难度量化评分 |
| 结构化推荐报告 | ✅ 已实现 | 含食谱信息、得分、推荐理由、参考图片 |
| 流式输出 | ✅ 已实现 | SSE 实时推送，打字机效果 |
| 多轮对话 | ✅ 已实现 | 基于 thread_id 的 SQLite 会话记忆 |
| 纯文本输入 | ✅ 已实现 | 不上传图片也能输入食材清单 |
1.4 项目效果
![]()
二.问题与解决汇总
2.1 LangGraph Studio 连接/部署问题
| # | 问题 | 根因 | 解决方案 |
|---|
| 1 | Graph 加载失败，服务启动即崩溃 | app/agents/personal_chief.py手动传入SqliteSavercheckpointer，与 LangGraph API 内置持久化机制冲突 | 创建personal_chief_lg.py，移除自定义checkpointer，由 LangGraph 平台自动管理 |
| 2 | .env中 LangSmith API Key 无效 | LANGSMITH_API_KEY= ***等号后多了前导空格 | 删除空格：LANGSMITH_API_KEY=*** |
| 3 | Studio（HTTPS）无法连接本地langgraph devHTTP 服务 | 浏览器混合内容策略（Mixed Content）阻止 LangSmith 向 http://127.0.0.1:8123 发请求 | 方案 A：自签名证书启动 HTTPSlanggraph dev --ssl-keyfile key.pem --ssl-certfile cert.pem方案 B：Cloudflare 隧道langgraph dev --tunnel --port 8123 |
方案 A vs 方案 B：
- A 适合本地开发，浏览器需信任自签名证书
- B 自动生成 https://xxx.trycloudflare.com 公网地址，无需处理证书，但依赖外网
2.2 图片上传与识别问题
| # | 问题 | 根因 | 解决方案 |
|---|
| 4 | 图片上传后一直"思考"不回答 | _build_message使用 OpenAI 格式{"type": "image_url", "image_url": {"url": "..."}}，DashScope 不兼容 | 改为 DashScope 兼容格式：{"type": "image", "url": "..."} |
| 5 | 图片上传失败 | ① OSS bucket 区域与代码默认区域不一致 → 签名错误② Bucket 私有，模型无法直接下载图片 | ①.env加OSS_REGION配置正确区域，换用oss2SDK②_build_message自动将私有 OSS URL 转为 GET 签名 URL |
2.3 Windows 启动脚本问题
| # | 问题 | 根因 | 解决方案 |
|---|
| 6 | 路径引号解析异常 | cd /d <项目路径>未加引号，含特殊字符时解析出错 | cd /d "<项目路径>" |
| 7 | bat 文件中文乱码 | UTF-8 编码的 bat 被 CMD 默认 GBK 解码 | bat 开头加chcp 65001切 UTF-8，或以 GBK/ANSI 保存 |
| 8 | 端口权限/占用（WinError 10013） | 端口被 Hyper-V 保留或防火墙拦截 | 换非保留端口（如 8099），或管理员身份运行 |
| 9 | main.py与start.bat端口不一致 | 两处配置了不同端口 | 统一端口，或明确区分不同启动方式 |
2.4 附
1.带 Cloudflare 隧道（解决 HTTPS）
langgraph dev --tunnel --port 8123
2.TTPS 本地启动（自签名证书）
langgraph dev --ssl-keyfile key.pem --ssl-certfile cert.pem --port 8123
3.普通本地启动
langgraph dev --port 8123
