00 快速复现清单：电商小二 — LLM 驱动对话系统

🏃 本文档目标：复制粘贴 + 回车 = 跑通完整项目 ❌ 不讲原理——原理在 01~06 篇 💬 卡住了？ 把错误信息复制给 AI："按清单第 X 步卡住了，错误信息：..."

0. 前置检查

bash

# 确认以下工具已安装
docker --version           # Docker ≥ 24
python --version           # Python ≥ 3.12
node --version             # Node ≥ 18（前端需要）
uv --version               # Python 包管理器

# 确认以下端口未被占用
# 3306(MySQL) 8000(客服后端) 8001(电商后端) 5173(前端)
# ✅ 前置检查完成

1. 阶段一：环境部署（≈10 min）

Step 1.1 获取项目代码

bash

git clone https://gitee.com/itlbo/customer-service-1020.git
cd customer-service-1020

Step 1.2 创建 docker-compose.yml

yaml

# → docker/docker-compose.yml
services:
  mysql:
    image: mysql:8.0
    container_name: cs_mysql
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: Atguigu.123
      MYSQL_DATABASE: customer_service
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
      - ./mysql/initdb:/docker-entrypoint-initdb.d
    command:
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_unicode_ci

volumes:
  mysql_data:

Step 1.3 启动数据库

bash

cd docker
docker compose up -d

# 验证
docker ps --format "&#123;&#123;.Names&#125;&#125;" | findstr cs_mysql && echo "✅ MySQL OK" || echo "❌ MySQL"

2. 阶段二：启动模拟电商后端（≈5 min）

Step 2.1 准备电商后端

bash

# 从课程 2.资料/ 中获取 ecommerce-service-backend/
# 或使用已克隆项目中的电商模块
cd ecommerce-service-backend
uv sync

Step 2.2 配置环境变量

env

# → .env
DATABASE_URL=mysql+aiomysql://root:Atguigu.123@localhost:3306/customer_service

Step 2.3 启动

bash

uv run python main.py

# 验证 API
curl http://localhost:8001/users/1/orders && echo "✅ 电商后端 OK" || echo "❌ 电商后端"

3. 阶段三：配置并启动客服后端（≈10 min）

Step 3.1 配置环境变量

bash

# 在 customer-service-backend/ 根目录
# 创建 .env 文件

env

# → .env
LLM_MODEL=<你的模型名，如 deepseek-chat>
LLM_BASE_URL=<你的 API 地址>
LLM_API_KEY=<你的 API Key>

COMMERCE_API_BASE_URL=http://localhost:8001

DATABASE_URL=mysql+aiomysql://root:Atguigu.123@localhost:3306/customer_service

APP_HOST=0.0.0.0
APP_PORT=8000

Step 3.2 安装依赖

bash

cd customer-service-backend
uv sync

# 验证
uv run python -c "from atguigu.conf.config import AppConfig; print('✅ 配置加载成功')"

Step 3.3 验证 LLM 连接

bash

uv run python -c "
from atguigu.infrastructure.llm import LLMClient
from atguigu.conf.config import AppConfig
config = AppConfig()
client = LLMClient(api_key=config.llm_api_key, base_url=config.llm_base_url)
import asyncio
async def test():
    resp = await client.generate('你好')
    print(f'✅ LLM 连接成功: {resp[:30]}...')
asyncio.run(test())
"

Step 3.4 启动客服后端

bash

uv run python main.py

# 验证
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"sender_id": "test001", "text": "你好"}' && echo "✅ 客服后端 OK" || echo "❌ 客服后端"

4. 阶段四：测试三大核心能力（≈10 min）

Step 4.1 测试闲聊

bash

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"sender_id": "test001", "text": "你好"}'

# 预期返回：
# {"reply": "你好，这里是 Atguigu 电商助手。我可以帮你查订单状态、查物流、了解商品信息，或者提交退款申请。", "sender_id": "test001"}

Step 4.2 测试知识问答

bash

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"sender_id": "test001", "text": "这件商品是什么材质的"}'

# 预期：调用电商 API 获取商品信息 → LLM 生成回答

Step 4.3 测试任务流程（退款申请）

bash

# 第一轮：发起退款
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"sender_id": "test001", "text": "我要退款"}'

# 第二轮：提供订单号
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"sender_id": "test001", "text": "订单号是 A20240315001"}'

# 第三轮：提供退款原因
curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"sender_id": "test001", "text": "尺码不合适"}'

# 预期：三轮对话完成退款申请流程

Step 4.4 验证对话历史

bash

curl http://localhost:8000/api/history/test001

# 预期：返回该用户的完整对话历史

5. 阶段五：启动前端（可选，≈3 min）

bash

cd customer-service-frontend
npm install
npm run dev

浏览器访问 http://localhost:5173

6. 可选：自定义 Flow 配置

bash

# 编辑 flow_config/user_flows.yml
# 添加你的业务流程，例如：

yaml

# → flow_config/user_flows.yml（新增）
flows:
  price_inquiry:
    name: 价格查询
    description: 用户查询商品价格
    steps:
      - id: start
        type: start
        next: ask_product_name

      - id: ask_product_name
        type: collect
        slot_name: product_name
        response:
          text: "请告诉我你想查询哪个商品的价格。"
        next: show_price

      - id: show_price
        type: action
        action: lookup_order_status
        args:
          text: "商品 &#123;&#123; slots.product_name }} 的当前价格为..."
        next: end

      - id: end
        type: end

bash

# 重启客服后端即可生效（无需修改代码）
# ✅ Flow 配置修改完成

7. 验证清单

编号	验证项	命令	预期结果
1	MySQL 启动	`docker ps`	看到 cs_mysql 容器
2	电商后端	`curl :8001/users/1/orders`	返回 JSON
3	LLM 连接	见 Step 3.3	打印回答
4	闲聊能力	`curl /api/chat -d '{"text":"你好"}'`	返回欢迎语
5	知识问答	`curl /api/chat -d '{"text":"商品信息"}'`	返回商品详情
6	任务流程	见 Step 4.3	三轮对话完成退款
7	对话历史	`curl /api/history/test001`	返回历史记录
8	自定义 Flow	修改 YAML → 重启	新流程生效

00 快速复现清单：电商小二 — LLM 驱动对话系统 ​

0. 前置检查 ​

1. 阶段一：环境部署（≈10 min） ​

Step 1.1 获取项目代码 ​

Step 1.2 创建 docker-compose.yml ​

Step 1.3 启动数据库 ​

2. 阶段二：启动模拟电商后端（≈5 min） ​

Step 2.1 准备电商后端 ​

Step 2.2 配置环境变量 ​

Step 2.3 启动 ​

3. 阶段三：配置并启动客服后端（≈10 min） ​

Step 3.1 配置环境变量 ​

Step 3.2 安装依赖 ​

Step 3.3 验证 LLM 连接 ​

Step 3.4 启动客服后端 ​

4. 阶段四：测试三大核心能力（≈10 min） ​

Step 4.1 测试闲聊 ​

Step 4.2 测试知识问答 ​

Step 4.3 测试任务流程（退款申请） ​

Step 4.4 验证对话历史 ​

5. 阶段五：启动前端（可选，≈3 min） ​

6. 可选：自定义 Flow 配置 ​

7. 验证清单 ​

00 快速复现清单：电商小二 — LLM 驱动对话系统

0. 前置检查

1. 阶段一：环境部署（≈10 min）

Step 1.1 获取项目代码

Step 1.2 创建 docker-compose.yml

Step 1.3 启动数据库

2. 阶段二：启动模拟电商后端（≈5 min）

Step 2.1 准备电商后端

Step 2.2 配置环境变量

Step 2.3 启动

3. 阶段三：配置并启动客服后端（≈10 min）

Step 3.1 配置环境变量

Step 3.2 安装依赖

Step 3.3 验证 LLM 连接

Step 3.4 启动客服后端

4. 阶段四：测试三大核心能力（≈10 min）

Step 4.1 测试闲聊

Step 4.2 测试知识问答

Step 4.3 测试任务流程（退款申请）

Step 4.4 验证对话历史

5. 阶段五：启动前端（可选，≈3 min）

6. 可选：自定义 Flow 配置

7. 验证清单