一.项目1.1 需求角色痛点核心诉求家庭烹饪新手面对冰箱里的食材不知道做什么输入食材 → 获得可行菜谱日常买菜族买完菜后决策疲劳拍照即出推荐省去搜索步骤健康饮食关注者希望兼顾营养与简易度按营养难度量化打分科学排序1.2 技术栈总结类别技术选型版本作用语言Python3.12后端核心语言Web 框架FastAPI≥0.109异步 HTTP 服务ASGIUvicorn≥0.27服务器运行AI 框架LangChain≥0.3Agent 编排LangGraph≥0.3状态图编排 会话持久化LLM通义千问 qwen3.5-plus—多模态推理DashScopeOpenAI 兼容接口搜索Tavily Search—实时 Web 菜谱搜索记忆SQLiteLangGraph 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 连接/部署问题#问题根因解决方案1Graph 加载失败服务启动即崩溃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***3StudioHTTPS无法连接本地langgraph devHTTP 服务浏览器混合内容策略Mixed Content阻止 LangSmith 向 http://127.0.0.1:8123 发请求方案 A自签名证书启动 HTTPSlanggraph dev --ssl-keyfile key.pem --ssl-certfile cert.pem方案 BCloudflare 隧道langgraph dev --tunnel --port 8123方案 A vs 方案 BA 适合本地开发浏览器需信任自签名证书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 签名 URL2.3 Windows 启动脚本问题#问题根因解决方案6路径引号解析异常cd /d 项目路径未加引号含特殊字符时解析出错cd /d 项目路径7bat 文件中文乱码UTF-8 编码的 bat 被 CMD 默认 GBK 解码bat 开头加chcp 65001切 UTF-8或以 GBK/ANSI 保存8端口权限/占用WinError 10013端口被 Hyper-V 保留或防火墙拦截换非保留端口如 8099或管理员身份运行9main.py与start.bat端口不一致两处配置了不同端口统一端口或明确区分不同启动方式2.4 附1.带 Cloudflare 隧道解决 HTTPSlanggraph dev --tunnel --port 81232.TTPS 本地启动自签名证书langgraph dev --ssl-keyfile key.pem --ssl-certfile cert.pem --port 81233.普通本地启动langgraph dev --port 8123