LLM驱动合成消费者在3D虚拟店铺中行走购物并输出转化指标

方案简介

LLM驱动合成消费者在3D虚拟店铺中行走购物并输出转化指标

组成与分工

组合中各成员的角色分工：

• FastAPI：后端 HTTP 框架，承载店铺/仿真相关 REST API，并暴露 /docs OpenAPI 文档。
• Pydantic：请求与响应模型的数据校验与序列化层。
• LiteLLM：统一多 LLM provider 调用入口，默认走 Gemini，便于切换模型。
• Instructor：在 LiteLLM 之上提供结构化输出能力，把 LLM 返回结果约束为 Pydantic 模型。
• pathfinding：后端单顾客路径规划库，计算每个 persona 在店铺网格中的行走路线。
• pandas / openpyxl：处理顾客档案、商品类目与导出 Excel 报表。
• React 19 + Vite + TypeScript：前端运行时与构建工具链。
• React Three Fiber (Three.js)：在浏览器中渲染 3D 等距网格店铺与顾客动画。
• TanStack Router / Query：前端路由与数据获取/缓存。
• Zustand：前端全局状态管理，承载仿真播放控制与人格/布局状态。
• Tailwind v4 + shadcn/ui：UI 样式与组件库。
• Recharts：仪表盘图表（转化、停留、货架参与度等）。
• ExcelJS：前端生成与导出仿真结果 Excel 报表。
• uvicorn：ASGI 服务器，启动后端开发服务。
• uv：Python 依赖与虚拟环境管理。
• pnpm：前端包管理。
• scripts/dev.sh：一键同时启动后端（:8000）与前端（:5173）的胶水脚本。

实施步骤

1. 一键启动（开发模式）

克隆仓库后在根目录执行：

cp backend/.env.example backend/.env   # add your LLM API key — DO NOT commit real keys
./scripts/dev.sh

scripts/dev.sh 会同时启动后端（uvicorn，监听 :8000）与前端（vite，监听 :5173），Ctrl-C 同时停止两者，浏览器打开 http://localhost:5173 即可。

2. 单独启动后端

cd backend
uv sync
uv run uvicorn store_emulator.server.main:app --reload

健康检查：curl http://localhost:8000/api/health；交互式 OpenAPI 文档位于 http://localhost:8000/docs。

3. 单独启动前端

cd frontend
pnpm install
pnpm dev

如需覆盖后端地址：VITE_API_URL=http://my-host:port pnpm dev。

4. 生产构建

cd frontend && pnpm build
# backend: no build step — run uvicorn behind a process manager

后端无构建步骤，建议在进程管理器（systemd / pm2 / supervisor 等）后运行 uvicorn。

优缺点

• ✓ 端到端LLM代理仿真可参考实现
• ✓ 前后端技术栈现代且分离清晰
• ✕ 无真实客流校准，输出仅作示意
• ✕ API与数据结构不稳定，版本间会破坏

出处

本方案挖掘自开源项目 intellicia-public/parastore，方案内容与实施命令均来自其 README 原文。