Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,52 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# Model files (HF Spaces needs .pth for deployment)
+# Remove the # below to exclude from GitHub:
+# models/*.pth
+models/*.pt
+!models/.gitkeep
+
+# Database
+*.db
+*.sqlite
+
+# Uploads
+uploads/*
+!uploads/.gitkeep
+
+# Dataset (large, download separately)
+dataset/trashnet/*
+!dataset/trashnet/.gitkeep
+dataset/train/*
+!dataset/train/.gitkeep
+dataset/val/*
+!dataset/val/.gitkeep
+dataset/test/*
+!dataset/test/.gitkeep
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# trssssssshnet repo (separate clone)
+trashnet/
+
+# Temp
+temp_upload.jpg

README.md

@@ -1,13 +1,178 @@
 ---
-title: Garbage Classification
-emoji: 👁
-colorFrom: gray
-colorTo: gray
+title: AI 垃圾分类助手
+emoji: ♻️
+colorFrom: green
+colorTo: green
 sdk: gradio
-sdk_version: 6.16.0
-python_version: '3.13'
+sdk_version: 5.0.0
 app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# ♻️ AI 垃圾分类助手
+
+基于深度学习的垃圾分类识别系统，支持 6 类垃圾（塑料、纸板、纸张、玻璃、金属、其他垃圾）的图像识别，并提供投放指南、环保积分和排行榜功能。
+
+**[GitHub 仓库](https://github.com/hutiger9/garbage-classification)**
+
+## 技术栈
+
+| 模块 | 技术 |
+|------|------|
+| 深度学习框架 | PyTorch + torchvision |
+| 模型架构 | MobileNetV3-Small（迁移学习，ImageNet 预训练） |
+| 硬件加速 | Apple Silicon MPS / NVIDIA CUDA / CPU 自动切换 |
+| Web 界面 | Gradio |
+| REST API | FastAPI + uvicorn |
+| 数据库 | SQLite（用户积分、分类记录） |
+| 包管理 | uv / pip |
+| 数据可视化 | Matplotlib（训练曲线） |
+| 推理优化 | Top-K 置信度输出、混淆矩阵分析 |
+
+## 项目结构
+
+```
+Garbage_classification/
+├── main.py              # CLI 入口（训练/预测/webui/api）
+├── train.py             # 模型训练 + 评估报告
+├── predict.py           # 推理预测
+├── webui.py             # Gradio 网页界面
+├── app/
+│   └── api.py           # FastAPI REST 接口
+├── config.py            # 全局配置
+├── database.py          # SQLite 数据库
+├── knowledge.py         # 垃圾分类知识库
+├── split_dataset.py     # 数据集划分工具
+├── download_trashnet.py # 数据集下载
+├── models/              # 模型保存目录
+├── dataset/             # 数据集目录
+├── pyproject.toml       # 项目配置
+└── requirements.txt     # 依赖列表
+```
+
+## 快速开始
+
+### 1. 解压项目
+
+```bash
+unzip Garbage_classification.zip
+cd Garbage_classification
+```
+
+### 2. 安装 Python 环境
+
+**方式一：uv（推荐）**
+
+```bash
+# 安装 uv（如未安装）
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 创建虚拟环境并安装依赖
+uv venv
+uv sync
+```
+
+**方式二：pip**
+
+```bash
+python -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+```
+
+### 3. 准备数据集
+
+```bash
+# 自动下载 TrashNet 数据集并划分训练集/验证集/测试集
+python download_trashnet.py
+```
+
+或手动下载后将图片放入 `dataset/` 目录，运行：
+
+```bash
+python split_dataset.py
+```
+
+### 4. 训练模型
+
+```bash
+# 使用 uv
+uv run python main.py train
+
+# 或使用 pip 虚拟环境
+python main.py train
+```
+
+训练完成后会在 `models/` 目录生成：
+- `garbage_model.pth` — 最佳模型权重
+- `training_curves.png` — 训练 Loss/Accuracy 曲线图
+- `evaluation_report.txt` — 详细评估报告（各类别准确率 + 混淆矩阵）
+
+### 5. 启动 Web 界面
+
+```bash
+uv run python main.py webui
+```
+
+打开浏览器访问 `http://localhost:7860`
+
+### 6. 启动 API 服务（可选，供小程序调用）
+
+```bash
+uv run python main.py api
+```
+
+API 文档访问 `http://localhost:8000/docs`
+
+## 支持的垃圾类别
+
+| 类别 | 英文 | 举例 |
+|------|------|------|
+| 🥤 塑料 | plastic | 饮料瓶、塑料袋、塑料容器 |
+| 📦 纸板 | cardboard | 快递纸箱、包装盒 |
+| 📄 纸张 | paper | 办公用纸、报纸、杂志 |
+| 🍾 玻璃 | glass | 玻璃瓶、玻璃制品 |
+| 🥫 金属 | metal | 易拉罐、金属罐、铁盒 |
+| 🍂 其他垃圾 | trash | 杂物、不可回收物 |
+
+## 模型性能
+
+在 TrashNet 测试集上（基于 MobileNetV3-Small）：
+
+| 类别 | 准确率 |
+|------|--------|
+| 纸板 | 96.77% |
+| 纸张 | 96.67% |
+| 金属 | 93.65% |
+| 塑料 | 91.67% |
+| 玻璃 | 90.79% |
+| 其他垃圾 | 77.27% |
+| **总体** | **92.99%** |
+
+## CLI 命令
+
+```bash
+# 训练模型
+python main.py train
+
+# 预测单张图片
+python main.py predict <图片路径>
+
+# 查询垃圾分类知识
+python main.py query <垃圾名称>
+
+# 查看用户环保记录
+python main.py record <用户名>
+
+# 查看用户统计
+python main.py stats <用户名>
+
+# 查看排行榜
+python main.py leaderboard
+
+# 启动 Web 界面
+python main.py webui
+
+# 启动 API 服务
+python main.py api
+```

app.py

@@ -0,0 +1,9 @@
+"""
+Hugging Face Spaces 入口文件
+自动加载 webui.py 中的 Gradio demo
+"""
+
+from webui import demo
+
+# Gradio SDK 会自动调用 demo.launch()
+# 这里只需导出 demo 对象即可

app/__init__.py

@@ -0,0 +1 @@
+"""AI 垃圾分类助手 - Web API"""

app/api.py

@@ -0,0 +1,125 @@
+"""
+AI 垃圾分类助手 - Web API (FastAPI)
+为小程序提供后端服务接口
+"""
+
+from fastapi import FastAPI, UploadFile, File, Form, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+import uvicorn
+
+from predict import GarbageClassifier
+from knowledge import get_class_info, search_knowledge, KNOWLEDGE_BASE
+from database import Database
+from config import UPLOAD_DIR
+
+app = FastAPI(title="AI 垃圾分类助手", version="1.0.0")
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"])
+
+classifier = None
+db = Database()
+
+UPLOAD_DIR.mkdir(exist_ok=True)
+
+
+def get_classifier():
+    global classifier
+    if classifier is None:
+        classifier = GarbageClassifier()
+    return classifier
+
+
+@app.get("/")
+def root():
+    return {"message": "AI 垃圾分类助手 API", "version": "1.0.0"}
+
+
+@app.post("/predict")
+async def predict(file: UploadFile = File(...), username: str = Form("default")):
+    """上传图片并分类"""
+    image_path = UPLOAD_DIR / file.filename
+    content = await file.read()
+    with open(image_path, "wb") as f:
+        f.write(content)
+
+    clf = get_classifier()
+    results = clf.predict(str(image_path))
+    best = results[0]
+
+    user_id = db.register_user(username)
+    points = db.add_record(user_id, best["class_name"], best["confidence"], str(image_path))
+
+    info = get_class_info(best["class_name"])
+    return {"success": True, "results": results, "points_earned": points, "knowledge": info}
+
+
+@app.get("/predict_url")
+def predict_url(image_url: str, username: str = "default"):
+    """通过 URL 识别图片"""
+    import requests
+    from PIL import Image
+    import io
+
+    response = requests.get(image_url, timeout=10)
+    image = Image.open(io.BytesIO(response.content)).convert("RGB")
+
+    temp_path = UPLOAD_DIR / "url_temp.jpg"
+    image.save(temp_path)
+
+    clf = get_classifier()
+    results = clf.predict(str(temp_path))
+    best = results[0]
+
+    user_id = db.register_user(username)
+    points = db.add_record(user_id, best["class_name"], best["confidence"], image_url)
+
+    info = get_class_info(best["class_name"])
+    return {"success": True, "results": results, "points_earned": points, "knowledge": info}
+
+
+@app.get("/knowledge/{class_name}")
+def get_knowledge(class_name: str):
+    info = get_class_info(class_name)
+    if not info:
+        raise HTTPException(status_code=404, detail="未找到该类别信息")
+    return info
+
+
+@app.get("/knowledge")
+def search_knowledge_api(q: str = ""):
+    if q:
+        return {k: v for k, v in search_knowledge(q)}
+    return KNOWLEDGE_BASE
+
+
+@app.post("/user/register")
+def register_user(username: str = Form(...)):
+    user_id = db.register_user(username)
+    return {"user_id": user_id, "username": username}
+
+
+@app.get("/user/{username}/stats")
+def user_stats(username: str):
+    user = db.get_user(username)
+    if not user:
+        raise HTTPException(status_code=404, detail="用户不存在")
+    return db.get_user_stats(user["id"])
+
+
+@app.get("/leaderboard")
+def leaderboard(limit: int = 10):
+    return {"leaderboard": db.get_leaderboard(limit)}
+
+
+def start_api(host="0.0.0.0", port=8000):
+    print(f"🌐 API 服务已启动: http://localhost:{port}")
+    print(f"   POST /predict          # 上传图片分类")
+    print(f"   GET  /predict_url       # URL 图片分类")
+    print(f"   GET  /knowledge         # 查询知识库")
+    print(f"   POST /user/register     # 注册用户")
+    print(f"   GET  /user/{{name}}/stats # 用户统计")
+    print(f"   GET  /leaderboard       # 排行榜")
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":
+    start_api()

config.py

@@ -0,0 +1,46 @@
+"""
+AI 垃圾分类助手 - 全局配置
+集中管理路径和参数
+"""
+
+from pathlib import Path
+
+# 项目根目录
+ROOT = Path(__file__).parent
+
+# 原始数据集 (手动下载)
+RAW_DATASET_DIR = ROOT / "dataset" / "trashnet"
+
+# 划分后的数据集 (split_dataset.py 生成)
+DATASET_DIR = ROOT / "dataset"
+TRAIN_DIR = DATASET_DIR / "train"
+VAL_DIR = DATASET_DIR / "val"
+TEST_DIR = DATASET_DIR / "test"
+
+# 模型
+MODEL_DIR = ROOT / "models"
+MODEL_PATH = MODEL_DIR / "garbage_model.pth"
+
+# 上传目录 (API)
+UPLOAD_DIR = ROOT / "uploads"
+
+# 数据库
+DB_PATH = ROOT / "garbage_assistant.db"
+
+# TrashNet 类别 (6类)
+CLASS_NAMES = ["cardboard", "glass", "metal", "paper", "plastic", "trash"]
+CLASS_NAMES_CN = ["纸板", "玻璃", "金属", "纸张", "塑料", "其他垃圾"]
+
+# 训练参数
+TRAIN_PARAMS = {
+    "epochs": 30,
+    "batch_size": 32,
+    "lr": 0.001,
+    "input_size": 224,
+    "resize_size": 256,
+}
+
+# 推理参数
+INFER_PARAMS = {
+    "top_k": 3,
+}

database.py

@@ -0,0 +1,148 @@
+"""
+AI 垃圾分类助手 - 数据库模块
+使用 SQLite 记录用户分类历史和环保积分
+"""
+
+import sqlite3
+from datetime import date
+
+
+class Database:
+    def __init__(self, db_path="garbage_assistant.db"):
+        self.db_path = db_path
+        self.init_database()
+
+    def _get_conn(self):
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        conn.execute("PRAGMA journal_mode=WAL")
+        return conn
+
+    def init_database(self):
+        conn = self._get_conn()
+        conn.executescript("""
+            CREATE TABLE IF NOT EXISTS users (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                username TEXT UNIQUE NOT NULL,
+                total_points INTEGER DEFAULT 0,
+                total_classifications INTEGER DEFAULT 0,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+            );
+
+            CREATE TABLE IF NOT EXISTS records (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                user_id INTEGER NOT NULL,
+                image_path TEXT,
+                predicted_class TEXT NOT NULL,
+                confidence REAL,
+                points INTEGER DEFAULT 10,
+                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                FOREIGN KEY (user_id) REFERENCES users(id)
+            );
+
+            CREATE TABLE IF NOT EXISTS daily_stats (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                user_id INTEGER NOT NULL,
+                date TEXT NOT NULL,
+                count INTEGER DEFAULT 0,
+                points INTEGER DEFAULT 0,
+                FOREIGN KEY (user_id) REFERENCES users(id),
+                UNIQUE(user_id, date)
+            );
+        """)
+        conn.commit()
+        conn.close()
+
+    def register_user(self, username):
+        conn = self._get_conn()
+        try:
+            cursor = conn.cursor()
+            cursor.execute("INSERT INTO users (username) VALUES (?)", (username,))
+            conn.commit()
+            user_id = cursor.lastrowid
+            print(f"✓ 用户 '{username}' 注册成功 (ID: {user_id})")
+            return user_id
+        except sqlite3.IntegrityError:
+            user_id = conn.execute(
+                "SELECT id FROM users WHERE username = ?", (username,)
+            ).fetchone()["id"]
+            print(f"ℹ 用户 '{username}' 已存在 (ID: {user_id})")
+            return user_id
+        finally:
+            conn.close()
+
+    def get_user(self, username):
+        conn = self._get_conn()
+        user = conn.execute(
+            "SELECT * FROM users WHERE username = ?", (username,)
+        ).fetchone()
+        conn.close()
+        return dict(user) if user else None
+
+    def add_record(self, user_id, predicted_class, confidence, image_path=None):
+        today = date.today().isoformat()
+        points = max(5, min(20, int(confidence * 20)))
+
+        conn = self._get_conn()
+        conn.execute(
+            "INSERT INTO records (user_id, image_path, predicted_class, confidence, points) VALUES (?, ?, ?, ?, ?)",
+            (user_id, image_path, predicted_class, confidence, points),
+        )
+        conn.execute(
+            "UPDATE users SET total_points = total_points + ?, total_classifications = total_classifications + 1 WHERE id = ?",
+            (points, user_id),
+        )
+        conn.execute(
+            "INSERT INTO daily_stats (user_id, date, count, points) VALUES (?, ?, 1, ?) "
+            "ON CONFLICT(user_id, date) DO UPDATE SET count = count + 1, points = points + ?",
+            (user_id, today, points, points),
+        )
+        conn.commit()
+        conn.close()
+        return points
+
+    def get_user_stats(self, user_id):
+        conn = self._get_conn()
+        user = conn.execute("SELECT * FROM users WHERE id = ?", (user_id,)).fetchone()
+        if not user:
+            conn.close()
+            return None
+
+        stats = dict(user)
+        stats["recent_records"] = [
+            dict(r) for r in conn.execute(
+                "SELECT predicted_class, confidence, points, created_at FROM records WHERE user_id = ? ORDER BY created_at DESC LIMIT 10",
+                (user_id,),
+            ).fetchall()
+        ]
+        stats["class_distribution"] = [
+            dict(r) for r in conn.execute(
+                "SELECT predicted_class, COUNT(*) as count FROM records WHERE user_id = ? GROUP BY predicted_class ORDER BY count DESC",
+                (user_id,),
+            ).fetchall()
+        ]
+
+        today = date.today().isoformat()
+        today_row = conn.execute(
+            "SELECT * FROM daily_stats WHERE user_id = ? AND date = ?", (user_id, today)
+        ).fetchone()
+        stats["today"] = dict(today_row) if today_row else {"count": 0, "points": 0}
+
+        stats["weekly"] = [
+            dict(r) for r in conn.execute(
+                "SELECT date, count, points FROM daily_stats WHERE user_id = ? AND date >= date('now', '-7 days') ORDER BY date DESC",
+                (user_id,),
+            ).fetchall()
+        ]
+
+        conn.close()
+        return stats
+
+    def get_leaderboard(self, limit=10):
+        conn = self._get_conn()
+        leaders = conn.execute(
+            "SELECT username, total_points, total_classifications FROM users ORDER BY total_points DESC LIMIT ?",
+            (limit,),
+        ).fetchall()
+        conn.close()
+        return [dict(r) for r in leaders]

download_trashnet.py

@@ -0,0 +1,44 @@
+"""下载 TrashNet 数据集并整理为 ImageFolder 格式"""
+from datasets import load_dataset
+from pathlib import Path
+import argparse
+
+CLASS_NAMES = ["cardboard", "glass", "metal", "paper", "plastic", "trash"]
+
+def download_trashnet(output_dir="dataset/trashnet"):
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    print("正在从 Hugging Face 下载 TrashNet 数据集...")
+    ds = load_dataset("garythung/trashnet", split="train", trust_remote_code=True)
+
+    label_names = ds.features["label"].names
+    print(f"类别: {label_names}")
+    print(f"总样本数: {len(ds)}")
+
+    # 为每个类别创建子目录
+    for name in label_names:
+        (out / name).mkdir(exist_ok=True)
+
+    # 逐条保存
+    for i, sample in enumerate(ds):
+        label = label_names[sample["label"]]
+        img = sample["image"]
+        ext = "png" if img.mode == "RGBA" else "jpg"
+        save_path = out / label / f"{label}_{i:05d}.{ext}"
+        img = img.convert("RGB")
+        img.save(save_path)
+        if (i + 1) % 500 == 0:
+            print(f"  已保存 {i + 1}/{len(ds)} 张...")
+
+    # 打印统计
+    print("\n下载完成！数据集统计:")
+    for name in label_names:
+        count = len(list((out / name).iterdir()))
+        print(f"  {name}: {count} 张")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--output-dir", default="dataset/trashnet")
+    args = parser.parse_args()
+    download_trashnet(args.output_dir)

knowledge.py

@@ -0,0 +1,154 @@
+"""
+AI 垃圾分类助手 - 知识库模块
+提供各类垃圾的投放指南、注意事项和环保知识
+"""
+
+KNOWLEDGE_BASE = {
+    "cardboard": {
+        "name_cn": "纸板/纸箱",
+        "category": "可回收物",
+        "description": "纸板属于可回收物，包括快递纸箱、包装纸盒、纸板箱等。",
+        "disposal": (
+            "1. 清空内容物，去除胶带和标签\n"
+            "2. 压平折叠，减小体积\n"
+            "3. 保持干燥清洁，避免油污污染\n"
+            "4. 绑扎整齐后投入可回收物收集容器"
+        ),
+        "tips": [
+            "沾有油污的纸板属于其他垃圾，不可回收",
+            "纸板上的塑料胶带需要撕掉",
+            "淋湿的纸板回收价值降低，尽量保持干燥",
+            "大型纸板箱应拆开压平后再投放",
+        ],
+        "fun_fact": "回收1吨废纸板可造好纸约800公斤，少砍17棵树！",
+        "degradation_time": "约3-4个月（自然降解）",
+    },
+    "glass": {
+        "name_cn": "玻璃",
+        "category": "可回收物",
+        "description": "玻璃制品属于可回收物，包括玻璃瓶、玻璃杯、玻璃碎片等。",
+        "disposal": (
+            "1. 清空残留物，用清水冲洗干净\n"
+            "2. 去掉瓶盖和金属环\n"
+            "3. 建议用纸包好后再投放，防止破碎伤人\n"
+            "4. 投入可回收物收集容器"
+        ),
+        "tips": [
+            "碎玻璃应用厚纸包好后再投放，并标注小心玻璃",
+            "灯泡、镜子属于其他垃圾（部分为有害垃圾）",
+            "玻璃瓶的金属瓶盖需分离投放",
+            "耐热玻璃和普通玻璃应分开回收（处理温度不同）",
+        ],
+        "fun_fact": "玻璃可以100%无限次循环利用，且质量不会下降！",
+        "degradation_time": "约100万年（自然降解）",
+    },
+    "plastic": {
+        "name_cn": "塑料",
+        "category": "可回收物",
+        "description": "塑料制品属于可回收物，包括塑料瓶、塑料桶、塑料包装等。",
+        "disposal": (
+            "1. 清空内容物，压扁瓶体\n"
+            "2. 取下瓶盖（瓶盖和瓶身材质不同，需分类）\n"
+            "3. 冲洗干净，去除残留\n"
+            "4. 投入可回收物收集容器"
+        ),
+        "tips": [
+            "饮料瓶需要把水倒空再投放",
+            "塑料袋、塑料膜也可以回收",
+            "一次性塑料餐具如果污染严重属于其他垃圾",
+            "化妆品瓶需要清洗干净才能回收",
+        ],
+        "fun_fact": "一个塑料瓶需要450年才能降解，回收是最好的选择！",
+        "degradation_time": "约200-500年（自然降解）",
+    },
+    "metal": {
+        "name_cn": "金属",
+        "category": "可回收物",
+        "description": "金属制品属于可回收物，包括易拉罐、金属罐、金属工具等。",
+        "disposal": (
+            "1. 清空内容物，冲洗干净\n"
+            "2. 易拉罐应压扁以减少体积\n"
+            "3. 喷雾罐需确认完全排空\n"
+            "4. 投入可回收物收集容器"
+        ),
+        "tips": [
+            "易拉罐压扁后投放，节省空间",
+            "金属瓶盖可单独投放或和金属一起放",
+            "废弃的小件金属可直接投放",
+            "大型金属制品应联系废品回收站",
+        ],
+        "fun_fact": "回收1个铝罐节省的电量可让电视运行3小时！",
+        "degradation_time": "约50-200年（自然降解）",
+    },
+    "paper": {
+        "name_cn": "纸张",
+        "category": "可回收物",
+        "description": "纸张属于可回收物，包括报纸、书籍、笔记本、办公用纸等。",
+        "disposal": (
+            "1. 去除订书钉、胶带等非纸附件\n"
+            "2. 尽量保持平整，不要揉成团\n"
+            "3. 保持干燥清洁\n"
+            "4. 投入可回收物收集容器"
+        ),
+        "tips": [
+            "纸巾、卫生纸属于其他垃圾（水溶性太强）",
+            "照片纸不属于可回收纸张",
+            "复写纸、蜡纸属于其他垃圾",
+            "碎纸机处理后的纸张仍可回收",
+        ],
+        "fun_fact": "回收1吨废纸可造好纸约800公斤，节省木材约3立方米！",
+        "degradation_time": "约2-6个月（自然降解）",
+    },
+    "trash": {
+        "name_cn": "其他垃圾/厨余",
+        "category": "其他垃圾",
+        "description": "包括食品残渣、果皮、纸巾、一次性餐具等不属于以上类别的垃圾。",
+        "disposal": (
+            "1. 沥干水分后投放\n"
+            "2. 用垃圾袋装好，扎紧袋口\n"
+            "3. 投入其他垃圾收集容器\n"
+            "4. 避免混入可回收物和有害垃圾"
+        ),
+        "tips": [
+            "厨余垃圾应沥干水分后再投放",
+            "大骨头、贝壳属于其他垃圾（不易粉碎）",
+            "电池、药品等有害垃圾不可投入此桶",
+            "尽量减少厨余浪费，按需购买食材",
+        ],
+        "fun_fact": "中国每年产生约1.5亿吨厨余垃圾，减少浪费从你我做起！",
+        "degradation_time": "约2-6周（自然降解）",
+    },
+}
+
+EN_TO_CN = {k: v["name_cn"] for k, v in KNOWLEDGE_BASE.items()}
+
+
+def get_class_info(class_name):
+    """获取指定类别的知识信息"""
+    return KNOWLEDGE_BASE.get(class_name)
+
+
+def get_all_classes():
+    """获取所有垃圾类别列表"""
+    return list(KNOWLEDGE_BASE.keys())
+
+
+def search_knowledge(keyword):
+    """搜索相关知识"""
+    kw = keyword.lower()
+    return [
+        (k, v) for k, v in KNOWLEDGE_BASE.items()
+        if kw in k or kw in v["name_cn"].lower()
+    ]
+
+
+def get_classification_guide():
+    """获取简洁的分类指南"""
+    return {
+        k: {
+            "name_cn": v["name_cn"],
+            "category": v["category"],
+            "summary": v["description"],
+        }
+        for k, v in KNOWLEDGE_BASE.items()
+    }

main.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""
+AI 垃圾分类助手 - 环保小能手
+主入口程序 (CLI)
+"""
+
+import argparse
+from pathlib import Path
+from config import DATASET_DIR, MODEL_DIR, MODEL_PATH
+
+
+def cmd_train(args):
+    from train import train
+    train(args)
+
+
+def cmd_predict(args):
+    from predict import GarbageClassifier
+    from knowledge import get_class_info
+
+    classifier = GarbageClassifier(model_path=args.model_path)
+    image_path = Path(args.image)
+    if not image_path.exists():
+        print(f"✗ 图片不存在: {image_path}")
+        return
+
+    print(f"正在识别: {image_path.name}")
+    results = classifier.predict(str(image_path), top_k=args.top_k)
+
+    print(f"\n{'='*40}")
+    print("识别结果:")
+    print(f"{'='*40}")
+    for i, r in enumerate(results, 1):
+        pct = r["confidence"] * 100
+        bar = "█" * int(pct // 5) + "░" * (20 - int(pct // 5))
+        print(f"  {i}. [{bar}] {r['class_name_cn']} ({pct:.1f}%)")
+
+    if args.detail:
+        info = get_class_info(results[0]["class_name"])
+        if info:
+            print(f"\n{'='*40}")
+            print(f"垃圾分类指南 - {info['name_cn']}")
+            print(f"分类: {info['category']}")
+            print(f"{'='*40}")
+            print(info["disposal"])
+            print(f"\n💡 {info['fun_fact']}")
+
+
+def cmd_query(args):
+    from knowledge import search_knowledge
+
+    results = search_knowledge(args.keyword)
+    if not results:
+        print(f"未找到与 '{args.keyword}' 相关的知识")
+        return
+
+    for _, info in results:
+        print(f"\n{'='*50}")
+        print(f"{info['name_cn']} | 类别: {info['category']}")
+        print(f"{'='*50}")
+        print(info["description"])
+        print(f"\n📋 投放方法:")
+        print(info["disposal"])
+        print(f"\n💡 小贴士:")
+        for tip in info["tips"]:
+            print(f"  • {tip}")
+        print(f"\n🎯 {info['fun_fact']}")
+        print(f"⏱ 降解时间: {info['degradation_time']}")
+
+
+def cmd_record(args):
+    from database import Database
+    from predict import GarbageClassifier
+    from knowledge import get_class_info
+
+    db = Database()
+    user_id = db.register_user(args.username)
+
+    classifier = GarbageClassifier(model_path=args.model_path)
+    image_path = Path(args.image)
+    if not image_path.exists():
+        print(f"✗ 图片不存在: {image_path}")
+        return
+
+    results = classifier.predict(str(image_path))
+    best = results[0]
+    points = db.add_record(user_id, best["class_name"], best["confidence"])
+
+    print(f"\n✓ 已记录! {best['class_name_cn']} (置信度: {best['confidence']*100:.1f}%)")
+    print(f"  +{points} 环保积分!")
+
+    info = get_class_info(best["class_name"])
+    if info:
+        print(f"\n📋 投放提示: {info['disposal'].split(chr(10))[0]}")
+
+
+def cmd_stats(args):
+    from database import Database
+    from knowledge import KNOWLEDGE_BASE
+
+    db = Database()
+    user = db.get_user(args.username)
+    if not user:
+        print(f"用户 '{args.username}' 不存在，请先使用 record 命令")
+        return
+
+    stats = db.get_user_stats(user["id"])
+    print(f"\n{'='*50}")
+    print(f"  环保统计 - {stats['username']}")
+    print(f"{'='*50}")
+    print(f"  总分类次数: {stats['total_classifications']}")
+    print(f"  总环保积分: {stats['total_points']}")
+    print(f"  今日分类: {stats['today']['count']} 次")
+    print(f"  今日积分: {stats['today']['points']}")
+
+    if stats["class_distribution"]:
+        print(f"\n  各类别分类统计:")
+        for item in stats["class_distribution"]:
+            cn = KNOWLEDGE_BASE.get(item["predicted_class"], {}).get("name_cn", item["predicted_class"])
+            print(f"    • {cn}: {item['count']} 次")
+
+    if stats["recent_records"]:
+        print(f"\n  最近记录:")
+        for r in stats["recent_records"][:5]:
+            cn = KNOWLEDGE_BASE.get(r["predicted_class"], {}).get("name_cn", r["predicted_class"])
+            print(f"    • {cn} | 积分: +{r['points']} | {r['created_at']}")
+
+
+def cmd_leaderboard(args):
+    from database import Database
+
+    db = Database()
+    leaders = db.get_leaderboard(args.limit)
+
+    if not leaders:
+        print("暂无环保数据，快去分类吧！")
+        return
+
+    print(f"\n{'='*50}")
+    print("  🏆 环保积分排行榜")
+    print(f"{'='*50}")
+    print(f"  {'排名':>4} {'用户名':<15} {'积分':<8} {'分类次数':<8}")
+    print(f"  {'-'*35}")
+    badges = ["🥇", "🥈", "🥉"]
+    for i, u in enumerate(leaders, 1):
+        badge = badges[i - 1] if i <= 3 else "  "
+        print(f"  {badge} {i:<2} {u['username']:<15} {u['total_points']:<8} {u['total_classifications']:<8}")
+
+
+def cmd_web(args):
+    from app.api import start_api
+    start_api(host=args.host, port=args.port)
+
+
+def cmd_webui(args):
+    from webui import launch_gradio
+    launch_gradio(server_port=args.port)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="AI 垃圾分类助手 - 环保小能手",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+使用示例:
+  %(prog)s train --data-dir dataset/trashnet
+  %(prog)s predict image.jpg
+  %(prog)s query 塑料
+  %(prog)s record --username 小明 image.jpg
+  %(prog)s stats --username 小明
+  %(prog)s leaderboard
+  %(prog)s web          # 启动 API 服务 (供小程序调用)
+  %(prog)s webui        # 启动 Gradio 网页界面
+        """,
+    )
+    sub = parser.add_subparsers(dest="command", help="可用命令")
+
+    p = sub.add_parser("train", help="训练分类模型")
+    p.add_argument("--data-dir", default=str(DATASET_DIR))
+    p.add_argument("--model-dir", default=str(MODEL_DIR))
+    p.add_argument("--epochs", type=int, default=30)
+    p.add_argument("--batch-size", type=int, default=32)
+    p.add_argument("--lr", type=float, default=0.001)
+
+    p = sub.add_parser("predict", help="分类垃圾图片")
+    p.add_argument("image")
+    p.add_argument("--model-path", default=str(MODEL_PATH))
+    p.add_argument("--top-k", type=int, default=3)
+    p.add_argument("--no-detail", dest="detail", action="store_false", default=True)
+
+    p = sub.add_parser("query", help="查询垃圾分类知识")
+    p.add_argument("keyword")
+
+    p = sub.add_parser("record", help="分类并记录积分")
+    p.add_argument("image")
+    p.add_argument("--username", default="default")
+    p.add_argument("--model-path", default=str(MODEL_PATH))
+
+    p = sub.add_parser("stats", help="查看个人统计")
+    p.add_argument("--username", default="default")
+
+    p = sub.add_parser("leaderboard", help="查看排行榜")
+    p.add_argument("--limit", type=int, default=10)
+
+    p = sub.add_parser("web", help="启动 API 服务")
+    p.add_argument("--host", default="0.0.0.0")
+    p.add_argument("--port", type=int, default=8000)
+
+    p = sub.add_parser("webui", help="启动 Gradio 网页界面")
+    p.add_argument("--port", type=int, default=7860)
+
+    args = parser.parse_args()
+
+    cmds = {
+        "train": cmd_train,
+        "predict": cmd_predict,
+        "query": cmd_query,
+        "record": cmd_record,
+        "stats": cmd_stats,
+        "leaderboard": cmd_leaderboard,
+        "web": cmd_web,
+        "webui": cmd_webui,
+    }
+    fn = cmds.get(args.command)
+    if fn:
+        fn(args)
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

models/evaluation_report.txt

@@ -0,0 +1,26 @@
+AI 垃圾分类助手 - 模型评估报告
+=======================================================
+训练设备: mps
+训练轮数: 30
+批次大小: 32
+学习率: 0.001
+
+最佳验证准确率: 94.41%
+测试集准确率: 92.99%
+
+各类别准确率:
+  纸板 (cardboard): 96.77%
+  玻璃 (glass): 90.79%
+  金属 (metal): 93.65%
+  纸张 (paper): 96.67%
+  塑料 (plastic): 91.67%
+  其他垃圾 (trash): 77.27%
+
+混淆矩阵:
+       cardb glass metal paper plast trash
+card:     60     1     1     0     0     0
+glas:      0    69     3     0     4     0
+meta:      0     2    59     1     1     0
+pape:      0     0     1    87     0     2
+plas:      0     3     0     2    66     1
+tras:      0     1     2     1     1    17

models/garbage_model.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8ac534413ac47e735c01822d3b11ec8d9e70e71b6b90410ab8c6de9145719df1
+size 18532291

predict.py

@@ -0,0 +1,80 @@
+"""
+AI 垃圾分类助手 - 预测模块
+使用训练好的模型进行垃圾图像分类
+"""
+
+import torch
+import torch.nn as nn
+from torchvision import transforms
+from torchvision.models import mobilenet_v3_small
+from PIL import Image
+from pathlib import Path
+from config import CLASS_NAMES, CLASS_NAMES_CN, MODEL_PATH as DEFAULT_MODEL_PATH
+
+
+class GarbageClassifier:
+    def __init__(self, model_path=None, device=None):
+        model_path = model_path or str(DEFAULT_MODEL_PATH)
+        self.device = device or self._get_device()
+        self.class_names = CLASS_NAMES
+        self.class_names_cn = CLASS_NAMES_CN
+        self.model = self._load_model(model_path)
+        self.model.eval()
+
+        self.transform = transforms.Compose([
+            transforms.Resize((256, 256)),
+            transforms.CenterCrop(224),
+            transforms.ToTensor(),
+            transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
+        ])
+
+    def _get_device(self):
+        if torch.backends.mps.is_available():
+            return torch.device("mps")
+        elif torch.cuda.is_available():
+            return torch.device("cuda")
+        return torch.device("cpu")
+
+    def _load_model(self, model_path):
+        model = mobilenet_v3_small(weights=None)
+        in_features = model.classifier[3].in_features
+        model.classifier[3] = nn.Linear(in_features, len(CLASS_NAMES))
+
+        path = Path(model_path)
+        if not path.exists():
+            raise FileNotFoundError(f"模型文件不存在: {model_path}\n请先运行 train.py 训练模型")
+
+        checkpoint = torch.load(model_path, map_location=self.device, weights_only=True)
+        model.load_state_dict(checkpoint["model_state_dict"])
+        model = model.to(self.device)
+        print(f"✓ 模型加载成功 ({model_path})")
+        print(f"  验证准确率: {checkpoint.get('best_acc', 'N/A'):.2f}%")
+        return model
+
+    def predict(self, image_path, top_k=3):
+        image = Image.open(image_path).convert("RGB")
+        input_tensor = self.transform(image).unsqueeze(0).to(self.device)
+
+        with torch.no_grad():
+            outputs = self.model(input_tensor)
+            probabilities = torch.nn.functional.softmax(outputs, dim=1)
+
+        top_probs, top_indices = torch.topk(probabilities, top_k)
+        top_probs = top_probs.squeeze().cpu().numpy()
+        top_indices = top_indices.squeeze().cpu().numpy()
+
+        if top_k == 1:
+            top_probs = [top_probs]
+            top_indices = [top_indices]
+
+        return [
+            {
+                "class_name": self.class_names[idx],
+                "class_name_cn": self.class_names_cn[idx],
+                "confidence": float(prob),
+            }
+            for prob, idx in zip(top_probs, top_indices)
+        ]
+
+    def predict_batch(self, image_paths):
+        return {path: self.predict(path) for path in image_paths}

pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "ai-garbage-assistant"
+version = "1.0.0"
+description = "AI 垃圾分类助手 - 环保小能手"
+requires-python = ">=3.9"
+dependencies = [
+    "torch>=2.0.0",
+    "torchvision>=0.15.0",
+    "pillow>=10.0.0",
+    "numpy>=1.24.0",
+    "fastapi>=0.104.0",
+    "uvicorn>=0.24.0",
+    "python-multipart>=0.0.6",
+    "requests>=2.31.0",
+    "tqdm>=4.66.0",
+    "gradio>=4.0.0",
+    "matplotlib>=3.7.0",
+]
+
+[project.scripts]
+garbage-assistant = "main:main"
+
+[tool.ruff]
+line-length = 100
+target-version = "py39"

requirements.txt

@@ -0,0 +1,11 @@
+torch>=2.0.0
+torchvision>=0.15.0
+pillow>=10.0.0
+numpy>=1.24.0
+fastapi>=0.104.0
+uvicorn>=0.24.0
+python-multipart>=0.0.6
+gradio>=4.0.0
+requests>=2.31.0
+tqdm>=4.66.0
+pillow-heif>=1.3.0

split_dataset.py

@@ -0,0 +1,83 @@
+"""
+数据集划分脚本
+将 dataset/trashnet/ 按比例拆分为 train / val / test
+生成结构:
+  dataset/
+  ├── trashnet/         (原始数据, 不动)
+  ├── train/
+  │   ├── cardboard/
+  │   └── ...
+  ├── val/
+  │   ├── cardboard/
+  │   └── ...
+  └── test/
+      ├── cardboard/
+      └── ...
+"""
+
+import argparse
+import random
+import shutil
+from pathlib import Path
+
+
+def split_dataset(data_dir, output_dir, train_ratio=0.7, val_ratio=0.15, seed=42):
+    data_dir = Path(data_dir)
+    output_dir = Path(output_dir)
+
+    if not data_dir.exists():
+        print(f"✗ 数据集路径不存在: {data_dir}")
+        return
+
+    random.seed(seed)
+
+    # 收集所有类别
+    classes = sorted([d.name for d in data_dir.iterdir() if d.is_dir()])
+    print(f"发现 {len(classes)} 个类别: {classes}")
+
+    splits = {"train": train_ratio, "val": val_ratio, "test": 1 - train_ratio - val_ratio}
+    print(f"\n划分比例: {splits}")
+
+    for cls in classes:
+        src_dir = data_dir / cls
+        images = sorted([f for f in src_dir.iterdir() if f.is_file()])
+        random.shuffle(images)
+
+        n = len(images)
+        n_train = int(n * train_ratio)
+        n_val = int(n * val_ratio)
+
+        split_files = {
+            "train": images[:n_train],
+            "val": images[n_train:n_train + n_val],
+            "test": images[n_train + n_val:],
+        }
+
+        for split_name, files in split_files.items():
+            dest_dir = output_dir / split_name / cls
+            dest_dir.mkdir(parents=True, exist_ok=True)
+            for f in files:
+                shutil.copy2(f, dest_dir / f.name)
+
+        print(f"  {cls:12s}: train={len(split_files['train']):4d}  "
+              f"val={len(split_files['val']):4d}  "
+              f"test={len(split_files['test']):4d}")
+
+    print(f"\n✓ 划分完成!")
+    print(f"  输出目录: {output_dir.resolve()}")
+    print(f"  结构: ")
+    print(f"    {output_dir.name}/")
+    for split_name in ["train", "val", "test"]:
+        total = sum(len(list((output_dir / split_name / cls).iterdir())) for cls in classes)
+        print(f"    ├── {split_name}/  ({total} 张)")
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="划分训练集/验证集/测试集")
+    parser.add_argument("--data-dir", default="dataset/trashnet", help="原始数据集路径")
+    parser.add_argument("--output-dir", default="dataset", help="输出目录 (将在其中创建 train/val/test)")
+    parser.add_argument("--train-ratio", type=float, default=0.7, help="训练集比例")
+    parser.add_argument("--val-ratio", type=float, default=0.15, help="验证集比例")
+    parser.add_argument("--seed", type=int, default=42, help="随机种子")
+    args = parser.parse_args()
+    split_dataset(args.data_dir, args.output_dir, args.train_ratio, args.val_ratio, args.seed)

train.py

@@ -0,0 +1,388 @@
+"""
+AI 垃圾分类助手 - 训练模块
+支持两种数据目录结构:
+  1. 已划分: dataset/train/ + dataset/val/ [+ dataset/test/]
+  2. 未划分: dataset/trashnet/  (自动随机划分)
+训练结束后保存 loss 曲线图并输出详细评估报告
+"""
+
+import argparse
+import torch
+import torch.nn as nn
+import torch.optim as optim
+from torch.utils.data import DataLoader, random_split
+from torchvision import datasets, transforms
+from torchvision.models import mobilenet_v3_small, MobileNet_V3_Small_Weights
+from pathlib import Path
+from tqdm import tqdm
+import matplotlib
+matplotlib.use("Agg")  # 不依赖 GUI 后端
+import matplotlib.pyplot as plt
+import numpy as np
+from config import CLASS_NAMES, CLASS_NAMES_CN
+
+
+# ── 设备 ──────────────────────────────────────────────
+
+def get_device():
+    if torch.backends.mps.is_available():
+        device = torch.device("mps")
+        print("✓ 使用 MPS (Apple Silicon) 加速训练")
+    elif torch.cuda.is_available():
+        device = torch.device("cuda")
+        print("✓ 使用 CUDA 加速训练")
+    else:
+        device = torch.device("cpu")
+        print("⚠ 使用 CPU 训练 (建议使用 MPS/CUDA)")
+    return device
+
+
+# ── 数据预处理 ────────────────────────────────────────
+
+def get_transforms():
+    train_tf = transforms.Compose([
+        transforms.Resize((256, 256)),
+        transforms.RandomResizedCrop(224),
+        transforms.RandomHorizontalFlip(),
+        transforms.RandomRotation(15),
+        transforms.ColorJitter(brightness=0.2, contrast=0.2, saturation=0.2),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
+    ])
+    eval_tf = transforms.Compose([
+        transforms.Resize((256, 256)),
+        transforms.CenterCrop(224),
+        transforms.ToTensor(),
+        transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225]),
+    ])
+    return train_tf, eval_tf
+
+
+# ── 模型 ──────────────────────────────────────────────
+
+def create_model(num_classes=6):
+    model = mobilenet_v3_small(weights=MobileNet_V3_Small_Weights.IMAGENET1K_V1)
+    in_features = model.classifier[3].in_features
+    model.classifier[3] = nn.Linear(in_features, num_classes)
+    return model
+
+
+# ── 训练 / 评估 ───────────────────────────────────────
+
+def train_epoch(model, loader, criterion, optimizer, device, desc="Training"):
+    model.train()
+    running_loss = correct = total = 0
+    pbar = tqdm(loader, desc=desc, leave=False)
+    for inputs, labels in pbar:
+        inputs, labels = inputs.to(device), labels.to(device)
+        optimizer.zero_grad()
+        outputs = model(inputs)
+        loss = criterion(outputs, labels)
+        loss.backward()
+        optimizer.step()
+        running_loss += loss.item() * inputs.size(0)
+        _, predicted = outputs.max(1)
+        total += labels.size(0)
+        correct += predicted.eq(labels).sum().item()
+        acc = 100.0 * correct / total if total > 0 else 0
+        pbar.set_postfix(loss=f"{running_loss/total:.4f}", acc=f"{acc:.1f}%")
+    return running_loss / total, 100.0 * correct / total
+
+
+@torch.no_grad()
+def evaluate(model, loader, criterion, device, desc="Evaluating"):
+    model.eval()
+    running_loss = correct = total = 0
+    pbar = tqdm(loader, desc=desc, leave=False)
+    for inputs, labels in pbar:
+        inputs, labels = inputs.to(device), labels.to(device)
+        outputs = model(inputs)
+        loss = criterion(outputs, labels)
+        running_loss += loss.item() * inputs.size(0)
+        _, predicted = outputs.max(1)
+        total += labels.size(0)
+        correct += predicted.eq(labels).sum().item()
+        acc = 100.0 * correct / total if total > 0 else 0
+        pbar.set_postfix(loss=f"{running_loss/total:.4f}", acc=f"{acc:.1f}%")
+    return running_loss / total, 100.0 * correct / total
+
+
+@torch.no_grad()
+def detailed_evaluate(model, loader, class_names, device):
+    """返回: (loss, acc, per_class_acc, confusion_matrix)"""
+    model.eval()
+    n = len(class_names)
+    correct_per_class = np.zeros(n)
+    total_per_class = np.zeros(n)
+    conf_matrix = np.zeros((n, n), dtype=int)
+    criterion = nn.CrossEntropyLoss()
+    total_loss = total_samples = 0
+
+    for inputs, labels in tqdm(loader, desc="详细评估", leave=False):
+        inputs, labels = inputs.to(device), labels.to(device)
+        outputs = model(inputs)
+        loss = criterion(outputs, labels)
+        total_loss += loss.item() * inputs.size(0)
+        total_samples += inputs.size(0)
+        _, predicted = outputs.max(1)
+
+        for t, p in zip(labels.cpu().numpy(), predicted.cpu().numpy()):
+            conf_matrix[t, p] += 1
+            total_per_class[t] += 1
+            if t == p:
+                correct_per_class[t] += 1
+
+    avg_loss = total_loss / total_samples
+    overall_acc = 100.0 * correct_per_class.sum() / total_per_class.sum()
+    per_class_acc = 100.0 * correct_per_class / np.maximum(total_per_class, 1)
+    return avg_loss, overall_acc, per_class_acc, conf_matrix
+
+
+# ── 绘图 ──────────────────────────────────────────────
+
+def plot_training_curves(history, save_path):
+    """绘制并保存 Loss / Accuracy 曲线图"""
+    epochs = range(1, len(history["train_loss"]) + 1)
+
+    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(12, 4.5))
+
+    # Loss
+    ax1.plot(epochs, history["train_loss"], "o-", label="Train Loss", color="#2196F3")
+    ax1.plot(epochs, history["val_loss"], "s-", label="Val Loss", color="#FF5722")
+    ax1.set_xlabel("Epoch")
+    ax1.set_ylabel("Loss")
+    ax1.set_title("Loss 曲线")
+    ax1.legend()
+    ax1.grid(True, alpha=0.3)
+
+    # Accuracy
+    ax2.plot(epochs, history["train_acc"], "o-", label="Train Acc", color="#2196F3")
+    ax2.plot(epochs, history["val_acc"], "s-", label="Val Acc", color="#FF5722")
+    ax2.axhline(y=history["best_acc"], color="green", linestyle="--", alpha=0.5,
+                label=f"Best Val {history['best_acc']:.1f}%")
+    ax2.set_xlabel("Epoch")
+    ax2.set_ylabel("Accuracy (%)")
+    ax2.set_title("Accuracy 曲线")
+    ax2.legend()
+    ax2.grid(True, alpha=0.3)
+
+    plt.tight_layout()
+    plt.savefig(save_path, dpi=150, bbox_inches="tight")
+    plt.close()
+    print(f"  📊 训练曲线已保存: {save_path}")
+
+
+# ── 评估报告 ──────────────────────────────────────────
+
+def print_evaluation_report(class_names, per_class_acc, conf_matrix):
+    """打印详细的评估报告"""
+    print(f"\n{'='*55}")
+    print(f"   详细评估报告")
+    print(f"{'='*55}")
+    print(f"  类别准确率:")
+    for i, name in enumerate(class_names):
+        cn = CLASS_NAMES_CN[i] if i < len(CLASS_NAMES_CN) else name
+        bar = "█" * int(per_class_acc[i] // 5) + "░" * (20 - int(per_class_acc[i] // 5))
+        print(f"    {i}. {cn:8s} ({name:10s}): {per_class_acc[i]:5.1f}%  [{bar}]")
+    print(f"{'─'*55}")
+
+    # 混淆矩阵
+    print(f"  混淆矩阵 (行=真实, 列=预测):")
+    header = "".join(f"{short:>6}" for short in [c[:5] for c in class_names])
+    print(f"    {'':>6}{header}")
+    for i in range(len(class_names)):
+        row = "".join(f"{conf_matrix[i, j]:>6}" for j in range(len(class_names)))
+        cn = CLASS_NAMES_CN[i][:2] if i < len(CLASS_NAMES_CN) else class_names[i][:2]
+        print(f"    {cn:>4}: {row}  {per_class_acc[i]:.1f}%")
+
+    # 易混淆对
+    print(f"\n  易混淆组合 (非对角线最高):")
+    n = len(class_names)
+    pairs = []
+    for i in range(n):
+        for j in range(n):
+            if i != j and conf_matrix[i, j] > 0:
+                pairs.append((conf_matrix[i, j], i, j))
+    pairs.sort(reverse=True)
+    for count, i, j in pairs[:3]:
+        cn_i = CLASS_NAMES_CN[i] if i < len(CLASS_NAMES_CN) else class_names[i]
+        cn_j = CLASS_NAMES_CN[j] if j < len(CLASS_NAMES_CN) else class_names[j]
+        ratio = count / max(conf_matrix[i].sum(), 1) * 100
+        print(f"    {cn_i} → {cn_j}: {count} 次 ({ratio:.1f}%)")
+
+
+# ── 数据加载 ──────────────────────────────────────────
+
+def load_split_data(data_dir, train_tf, eval_tf, batch_size):
+    """加载已划分的数据集 (train/val/test 子目录)"""
+    train_dir = data_dir / "train"
+    val_dir = data_dir / "val"
+    if not train_dir.exists() or not val_dir.exists():
+        return None
+
+    train_dataset = datasets.ImageFolder(root=str(train_dir), transform=train_tf)
+    val_dataset = datasets.ImageFolder(root=str(val_dir), transform=eval_tf)
+
+    train_loader = DataLoader(train_dataset, batch_size=batch_size, shuffle=True, num_workers=0)
+    val_loader = DataLoader(val_dataset, batch_size=batch_size, shuffle=False, num_workers=0)
+
+    test_loader = None
+    test_dir = data_dir / "test"
+    if test_dir.exists():
+        test_dataset = datasets.ImageFolder(root=str(test_dir), transform=eval_tf)
+        test_loader = DataLoader(test_dataset, batch_size=batch_size, shuffle=False, num_workers=0)
+
+    return train_loader, val_loader, test_loader, train_dataset.classes
+
+
+def load_random_split_data(data_dir, train_tf, eval_tf, batch_size):
+    """从单目录随机划分"""
+    full_dataset = datasets.ImageFolder(root=str(data_dir), transform=train_tf)
+    train_size = int(0.8 * len(full_dataset))
+    val_size = len(full_dataset) - train_size
+    train_dataset, val_dataset = random_split(full_dataset, [train_size, val_size])
+    val_dataset.dataset.transform = eval_tf
+
+    train_loader = DataLoader(train_dataset, batch_size=batch_size, shuffle=True, num_workers=0)
+    val_loader = DataLoader(val_dataset, batch_size=batch_size, shuffle=False, num_workers=0)
+
+    return train_loader, val_loader, None, full_dataset.classes
+
+
+# ── 主训练流程 ────────────────────────────────────────
+
+def train(args):
+    device = get_device()
+    data_dir = Path(args.data_dir)
+    model_dir = Path(args.model_dir)
+    model_dir.mkdir(parents=True, exist_ok=True)
+
+    if not data_dir.exists():
+        print(f"✗ 数据集路径不存在: {data_dir}")
+        print("请将数据集放在以下结构之一:")
+        print(f"  {data_dir}/  ├── cardboard/  └── ...  (自动 80/20 划分)")
+        print(f"  或运行 split_dataset.py 划分后使用:")
+        print(f"  {data_dir}/train/  ├── cardboard/  └── ...")
+        print(f"  {data_dir}/val/    ├── cardboard/  └── ...")
+        return
+
+    train_tf, eval_tf = get_transforms()
+
+    if (data_dir / "train").exists():
+        result = load_split_data(data_dir, train_tf, eval_tf, args.batch_size)
+        if result:
+            train_loader, val_loader, test_loader, classes = result
+            print(f"\n检测到已划分的数据集")
+    else:
+        result = load_random_split_data(data_dir, train_tf, eval_tf, args.batch_size)
+        if result:
+            train_loader, val_loader, test_loader, classes = result
+            print(f"\n检测到未划分的数据集 (自动 80/20 随机划分)")
+
+    print(f"  类别 ({len(classes)}): {classes}")
+    print(f"  训练集: {len(train_loader.dataset)} 张")
+    print(f"  验证集: {len(val_loader.dataset)} 张")
+    if test_loader:
+        print(f"  测试集: {len(test_loader.dataset)} 张")
+
+    model = create_model(num_classes=len(classes)).to(device)
+    criterion = nn.CrossEntropyLoss()
+    optimizer = optim.Adam(model.parameters(), lr=args.lr)
+    scheduler = optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=args.epochs)
+
+    # ── 训练循环 ──
+    history = {"train_loss": [], "train_acc": [], "val_loss": [], "val_acc": [], "best_acc": 0.0}
+    best_acc = 0.0
+    print(f"\n开始训练 (共 {args.epochs} 轮)...")
+    print(f"{'─'*65}")
+
+    for epoch in range(1, args.epochs + 1):
+        train_loss, train_acc = train_epoch(
+            model, train_loader, criterion, optimizer, device,
+            desc=f"Epoch {epoch}/{args.epochs}",
+        )
+        val_loss, val_acc = evaluate(model, val_loader, criterion, device, desc="Validating")
+        scheduler.step()
+
+        history["train_loss"].append(train_loss)
+        history["train_acc"].append(train_acc)
+        history["val_loss"].append(val_loss)
+        history["val_acc"].append(val_acc)
+
+        print(
+            f"Epoch {epoch:2d}/{args.epochs} | "
+            f"Train Loss: {train_loss:.4f} Acc: {train_acc:.2f}% | "
+            f"Val Loss: {val_loss:.4f} Acc: {val_acc:.2f}% | "
+            f"LR: {scheduler.get_last_lr()[0]:.2e}"
+        )
+
+        if val_acc > best_acc:
+            best_acc = val_acc
+            history["best_acc"] = best_acc
+            model_path = model_dir / "garbage_model.pth"
+            torch.save({
+                "epoch": epoch,
+                "model_state_dict": model.state_dict(),
+                "optimizer_state_dict": optimizer.state_dict(),
+                "best_acc": best_acc,
+                "class_names": classes,
+            }, str(model_path))
+            print(f"  ✓ 保存最佳模型 (验证准确率: {best_acc:.2f}%)")
+
+    # ── 训练结束 ──
+    print(f"{'─'*65}")
+    print(f"训练完成！最佳验证准确率: {best_acc:.2f}%")
+
+    # 绘制训练曲线
+    plot_path = model_dir / "training_curves.png"
+    plot_training_curves(history, plot_path)
+
+    # 测试集详细评估
+    if test_loader:
+        print(f"\n{'='*55}")
+        print(f"   测试集最终评估")
+        print(f"{'='*55}")
+
+        test_loss, test_acc, per_class_acc, conf_matrix = detailed_evaluate(
+            model, test_loader, classes, device
+        )
+        print(f"  测试集 Loss: {test_loss:.4f} | 准确率: {test_acc:.2f}%")
+        print_evaluation_report(classes, per_class_acc, conf_matrix)
+
+        # 追加测试结果到报告文件
+        report_path = model_dir / "evaluation_report.txt"
+        with open(report_path, "w", encoding="utf-8") as f:
+            f.write(f"AI 垃圾分类助手 - 模型评估报告\n")
+            f.write(f"{'='*55}\n")
+            f.write(f"训练设备: {device}\n")
+            f.write(f"训练轮数: {args.epochs}\n")
+            f.write(f"批次大小: {args.batch_size}\n")
+            f.write(f"学习率: {args.lr}\n\n")
+            f.write(f"最佳验证准确率: {best_acc:.2f}%\n")
+            f.write(f"测试集准确率: {test_acc:.2f}%\n\n")
+            f.write(f"各类别准确率:\n")
+            for i, name in enumerate(classes):
+                cn = CLASS_NAMES_CN[i] if i < len(CLASS_NAMES_CN) else name
+                f.write(f"  {cn} ({name}): {per_class_acc[i]:.2f}%\n")
+            f.write(f"\n混淆矩阵:\n")
+            f.write(f"{'':>6}" + "".join(f"{c[:5]:>6}" for c in classes) + "\n")
+            for i in range(len(classes)):
+                f.write(f"{classes[i][:4]:>4}: " + "".join(f"{conf_matrix[i,j]:>6}" for j in range(len(classes))) + "\n")
+        print(f"  📄 评估报告已保存: {report_path}")
+
+    print(f"\n✓ 模型: {model_dir / 'garbage_model.pth'}")
+    print(f"✓ 曲线图: {plot_path}")
+    print(f"  如需启动 Web 界面:  python main.py webui")
+
+
+# ── CLI ───────────────────────────────────────────────
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="训练垃圾分类模型")
+    parser.add_argument("--data-dir", default="dataset")
+    parser.add_argument("--model-dir", default="models")
+    parser.add_argument("--epochs", type=int, default=30)
+    parser.add_argument("--batch-size", type=int, default=32)
+    parser.add_argument("--lr", type=float, default=0.001)
+    args = parser.parse_args()
+    train(args)

webui.py

@@ -0,0 +1,790 @@
+"""
+AI 垃圾分类助手 - 高级 Gradio UI 版本
+特点：
+1. 缩略图显示
+2. 点击查看原图
+3. Tabs 分区布局
+4. 排行榜折叠
+5. 更现代化卡片式 UI
+6. 更清晰的视觉层级
+"""
+
+import base64
+from PIL import Image
+
+# HEIC 支持
+try:
+    import pillow_heif
+    pillow_heif.register_heif_opener()
+    HEIF_SUPPORT = True
+except Exception:
+    HEIF_SUPPORT = False
+import random
+import gradio as gr
+from knowledge import get_class_info
+from database import Database
+
+# 数据库
+# --------------------------------------------------
+db = Database()
+
+# 分类器懒加载
+_classifier = None
+TEMP_IMG = "temp_upload.jpg"
+
+
+# --------------------------------------------------
+# 模型加载
+# --------------------------------------------------
+def get_classifier():
+    global _classifier
+
+    if _classifier is None:
+        from predict import GarbageClassifier
+        _classifier = GarbageClassifier()
+
+    return _classifier
+
+
+# --------------------------------------------------
+# 图片转 base64
+# --------------------------------------------------
+def make_img_data_uri(path):
+    with open(path, "rb") as f:
+        return (
+            "data:image/jpeg;base64,"
+            + base64.b64encode(f.read()).decode()
+        )
+
+
+# --------------------------------------------------
+# 主识别逻辑
+# --------------------------------------------------
+def classify_and_advise(image, username="default"):
+
+    if image is None:
+        return (
+            """
+            <div class='empty-card'>
+                <h2>⚠️ 未检测到图片</h2>
+                <p>请先上传一张垃圾图片</p>
+            </div>
+            """,
+            "",
+            ""
+        )
+
+    # 加载模型
+    try:
+        classifier = get_classifier()
+
+    except FileNotFoundError as e:
+        return (
+            f"""
+            <div class='error-card'>
+                <h2>❌ 模型未训练</h2>
+                <p>{e}</p>
+                <p>请先运行:</p>
+                <code>python main.py train</code>
+            </div>
+            """,
+            "",
+            ""
+        )
+
+    # 推理
+    try:
+        # 自动兼容 HEIC / HEIF
+        if isinstance(image, str):
+
+            if image.lower().endswith((".heic", ".heif")):
+
+                if not HEIF_SUPPORT:
+                    raise RuntimeError(
+                        "未安装 pillow-heif，请执行: pip install pillow-heif"
+                    )
+
+                heif_file = pillow_heif.read_heif(image)
+
+                image = Image.frombytes(
+                    heif_file.mode,
+                    heif_file.size,
+                    heif_file.data,
+                    "raw"
+                )
+
+            else:
+                image = Image.open(image)
+
+        img = image.convert("RGB")
+        img.save(TEMP_IMG, "JPEG")
+
+        results = classifier.predict(TEMP_IMG)
+
+        best = results[0]
+
+        info = get_class_info(best["class_name"])
+
+    except Exception as e:
+        return (
+            f"""
+            <div class='error-card'>
+                <h2>❌ 识别失败</h2>
+                <p>{e}</p>
+            </div>
+            """,
+            "",
+            ""
+        )
+
+    # --------------------------------------------------
+    # 用户记录
+    # --------------------------------------------------
+    user_id = db.register_user(username)
+
+    points = db.add_record(
+        user_id,
+        best["class_name"],
+        best["confidence"]
+    )
+
+    stats = db.get_user_stats(user_id)
+
+    leaderboard = db.get_leaderboard(5)
+
+    # --------------------------------------------------
+    # 图片 data uri
+    # --------------------------------------------------
+    data_uri = make_img_data_uri(TEMP_IMG)
+
+    modal_id = f"modal-{random.randint(10000,99999)}"
+
+    # --------------------------------------------------
+    # 结果卡片
+    # --------------------------------------------------
+    pct = best["confidence"] * 100
+
+    progress_width = min(max(pct, 5), 100)
+
+    if pct >= 80:
+        result_color = "#2e7d32"
+        result_bg = "#e8f5e9"
+
+    elif pct >= 60:
+        result_color = "#ef6c00"
+        result_bg = "#fff3e0"
+
+    else:
+        result_color = "#c62828"
+        result_bg = "#ffebee"
+
+    result_html = f"""
+
+    <div class='result-card'>
+
+        <div class='thumb-wrapper'>
+
+            <img
+                src='{data_uri}'
+                class='thumb-image'
+                onclick="document.getElementById('{modal_id}').style.display='flex'"
+            >
+
+            <div class='thumb-text'>🔍 点击查看原图</div>
+
+        </div>
+
+        <div class='result-content'>
+
+            <div class='result-label'>AI 识别结果</div>
+
+            <div class='result-name' style='color:{result_color};'>
+                {best['class_name_cn']}
+            </div>
+
+            <div class='result-category'>
+                ♻️ {info['category'] if info else '未知分类'}
+            </div>
+
+            <div class='confidence-text'>
+                识别置信度：{pct:.1f}%
+            </div>
+
+            <div class='progress-bar-bg'>
+                <div
+                    class='progress-bar-fill'
+                    style='width:{progress_width}%;background:{result_color};'>
+                </div>
+            </div>
+
+            <div class='score-badge'>
+                🎉 获得 +{points} 环保积分
+            </div>
+
+        </div>
+
+    </div>
+
+    <!-- 原图弹窗 -->
+    <div
+        id='{modal_id}'
+        class='image-modal'
+        onclick="this.style.display='none'">
+
+        <img src='{data_uri}' class='modal-image'>
+
+        <div class='modal-close'>✕</div>
+
+    </div>
+
+    """
+
+    # --------------------------------------------------
+    # 投放指南
+    # --------------------------------------------------
+    disposal_html = (
+        info["disposal"].replace("\n", "<br>")
+        if info else "暂无信息"
+    )
+
+    tips_html = "".join(
+        [f"<li>💡 {t}</li>" for t in info["tips"]]
+    ) if info else ""
+
+    knowledge_html = f"""
+
+    <div class='knowledge-card'>
+
+        <div class='knowledge-title'>
+            📋 {info['name_cn']} 投放指南
+        </div>
+
+        <div class='knowledge-body'>
+            {disposal_html}
+        </div>
+
+        <div class='tips-title'>💡 分类小贴士</div>
+
+        <ul class='tips-list'>
+            {tips_html}
+        </ul>
+
+        <div class='fun-fact'>
+            🎯 {info['fun_fact']}
+        </div>
+
+        <div class='degradation'>
+            ⏱ 降解时间：{info['degradation_time']}
+        </div>
+
+    </div>
+
+    """
+
+    # --------------------------------------------------
+    # 排行榜
+    # --------------------------------------------------
+    leaderboard_html = ""
+
+    for i, user in enumerate(leaderboard):
+
+        medal = ""
+
+        if i == 0:
+            medal = "🥇"
+        elif i == 1:
+            medal = "🥈"
+        elif i == 2:
+            medal = "🥉"
+        else:
+            medal = f"{i+1}."
+
+        leaderboard_html += f"""
+        <div class='leader-item'>
+            <span>{medal} {user['username']}</span>
+            <span>{user['total_points']} 分</span>
+        </div>
+        """
+
+    stats_html = f"""
+
+    <div class='stats-card'>
+
+        <div class='stats-title'>
+            📊 {stats['username']} 的环保数据
+        </div>
+
+        <div class='stats-grid'>
+
+            <div class='stat-box'>
+                <div class='stat-number'>{stats['total_points']}</div>
+                <div class='stat-label'>总积分</div>
+            </div>
+
+            <div class='stat-box'>
+                <div class='stat-number'>{stats['total_classifications']}</div>
+                <div class='stat-label'>分类次数</div>
+            </div>
+
+            <div class='stat-box'>
+                <div class='stat-number'>{stats['today']['points']}</div>
+                <div class='stat-label'>今日积分</div>
+            </div>
+
+        </div>
+
+        <div class='leaderboard-title'>🏆 环保排行榜 TOP5</div>
+
+        <div class='leaderboard-list'>
+            {leaderboard_html}
+        </div>
+
+    </div>
+
+    """
+
+    return result_html, knowledge_html, stats_html
+
+
+# --------------------------------------------------
+# CSS
+# --------------------------------------------------
+CSS = """
+
+.gradio-container {
+    width: 100% !important;
+    max-width: 900px !important;
+    margin: auto !important;
+    overflow-x: hidden !important;
+    margin: auto;
+}
+
+footer {
+    display: none !important;
+}
+
+/* 标题 */
+.main-title {
+    text-align:center;
+    padding: 10px 0 20px 0;
+}
+
+/* 提示标签 */
+.class-badge {
+    display:inline-block;
+    padding:6px 14px;
+    border-radius:20px;
+    margin:4px;
+    font-size:13px;
+    font-weight:bold;
+    background:#f1f8e9;
+    border:1px solid #c5e1a5;
+}
+
+/* 上传区域 */
+.upload-panel {
+    width: 100%;
+    max-width: 900px;
+    margin: auto;
+    background:white;
+    border-radius:18px;
+    padding:20px;
+    box-shadow:0 4px 15px rgba(0,0,0,0.06);
+}
+
+/* 结果卡片 */
+.result-card {
+    box-sizing: border-box;
+    width: 100%;
+    max-width: 900px;
+    margin: 10px auto 0 auto;
+    display:flex;
+    align-items:center;
+    gap:20px;
+    background:white;
+    border-radius:20px;
+    padding:20px;
+    box-shadow:0 6px 18px rgba(0,0,0,0.08);
+    margin-top:5px;
+}
+
+.thumb-wrapper {
+    text-align:center;
+    flex-shrink:0;
+}
+
+.thumb-image {
+    max-width: 95px;
+    min-width: 95px;
+    width:95px;
+    height:95px;
+    object-fit:cover;
+    border-radius:14px;
+    cursor:pointer;
+    border:3px solid #c8e6c9;
+    transition:0.2s;
+}
+
+.thumb-image:hover {
+    transform:scale(1.05);
+}
+
+.thumb-text {
+    margin-top:6px;
+    font-size:11px;
+    color:#777;
+}
+
+.result-content {
+    flex:1;
+}
+
+.result-label {
+    color:#777;
+    font-size:13px;
+}
+
+.result-name {
+    font-size:34px;
+    font-weight:800;
+    margin:4px 0;
+}
+
+.result-category {
+    font-size:15px;
+    color:#555;
+    margin-bottom:10px;
+}
+
+.confidence-text {
+    font-size:13px;
+    margin-bottom:6px;
+    color:#666;
+}
+
+.progress-bar-bg {
+    width:100%;
+    height:10px;
+    background:#eeeeee;
+    border-radius:999px;
+    overflow:hidden;
+}
+
+.progress-bar-fill {
+    height:100%;
+    border-radius:999px;
+}
+
+.score-badge {
+    display:inline-block;
+    margin-top:12px;
+    padding:8px 14px;
+    background:#fff3e0;
+    border-radius:999px;
+    color:#ef6c00;
+    font-size:13px;
+    font-weight:bold;
+}
+
+/* 投放指南 */
+.knowledge-card {
+    background:white;
+    padding:22px;
+    border-radius:18px;
+    box-shadow:0 4px 15px rgba(0,0,0,0.06);
+}
+
+.knowledge-title {
+    font-size:22px;
+    font-weight:bold;
+    color:#2e7d32;
+    margin-bottom:15px;
+}
+
+.knowledge-body {
+    background:#f8f9fa;
+    padding:16px;
+    border-radius:12px;
+    line-height:1.8;
+    font-size:15px;
+}
+
+.tips-title {
+    margin-top:18px;
+    font-size:17px;
+    font-weight:bold;
+    color:#ef6c00;
+}
+
+.tips-list {
+    margin-top:8px;
+    line-height:1.9;
+}
+
+.fun-fact {
+    margin-top:15px;
+    background:#fff8e1;
+    padding:12px;
+    border-radius:12px;
+    color:#e65100;
+    font-weight:bold;
+}
+
+.degradation {
+    margin-top:10px;
+    color:#777;
+    font-size:13px;
+}
+
+/* 环保统计 */
+.stats-card {
+    background:white;
+    padding:22px;
+    border-radius:18px;
+    box-shadow:0 4px 15px rgba(0,0,0,0.06);
+}
+
+.stats-title {
+    font-size:22px;
+    font-weight:bold;
+    color:#1565c0;
+    margin-bottom:20px;
+}
+
+.stats-grid {
+    display:grid;
+    grid-template-columns:repeat(3,1fr);
+    gap:15px;
+}
+
+.stat-box {
+    background:#f5f7fa;
+    padding:18px;
+    border-radius:14px;
+    text-align:center;
+}
+
+.stat-number {
+    font-size:28px;
+    font-weight:bold;
+    color:#1565c0;
+}
+
+.stat-label {
+    margin-top:6px;
+    color:#666;
+    font-size:13px;
+}
+
+.leaderboard-title {
+    margin-top:24px;
+    font-size:18px;
+    font-weight:bold;
+    color:#2e7d32;
+}
+
+.leaderboard-list {
+    margin-top:12px;
+}
+
+.leader-item {
+    display:flex;
+    justify-content:space-between;
+    padding:12px 14px;
+    background:#f8f9fa;
+    border-radius:12px;
+    margin-bottom:10px;
+    font-size:14px;
+}
+
+/* 弹窗 */
+.image-modal {
+    display:none;
+    position:fixed;
+    top:0;
+    left:0;
+    width:100%;
+    height:100%;
+    background:rgba(0,0,0,0.92);
+    z-index:99999;
+    justify-content:center;
+    align-items:center;
+    cursor:pointer;
+}
+
+.modal-image {
+    width: auto;
+    height: auto;
+    object-fit: contain;
+    max-width:90%;
+    max-height:90%;
+    border-radius:10px;
+    object-fit:contain;
+}
+
+.modal-close {
+    position:absolute;
+    top:20px;
+    right:30px;
+    color:white;
+    font-size:36px;
+    font-weight:bold;
+}
+
+/* 空卡片 */
+.empty-card,
+.error-card {
+    text-align:center;
+    padding:40px;
+    background:white;
+    border-radius:18px;
+}
+
+/* 手机端适配 */
+@media (max-width:768px) {
+
+    .result-card {
+        flex-direction:column;
+        text-align:center;
+    }
+
+    .stats-grid {
+        grid-template-columns:1fr;
+    }
+
+    .result-name {
+        font-size:28px;
+    }
+}
+
+"""
+
+
+# --------------------------------------------------
+# 分类提示
+# --------------------------------------------------
+CLASS_HINT = """
+<div style='text-align:center;margin-bottom:12px;'>
+
+<span class='class-badge'>🥤 塑料</span>
+<span class='class-badge'>📦 纸板</span>
+<span class='class-badge'>📄 纸张</span>
+<span class='class-badge'>🍾 玻璃</span>
+<span class='class-badge'>🥫 金属</span>
+<span class='class-badge'>🍂 其他垃圾</span>
+
+<div style='margin-top:10px;color:#777;font-size:13px;'>
+本系统当前支持以上 6 类垃圾识别
+</div>
+
+</div>
+"""
+
+
+# --------------------------------------------------
+# Gradio UI
+# --------------------------------------------------
+with gr.Blocks(fill_width=False,
+    title="AI 垃圾分类助手",
+    theme=gr.themes.Soft(primary_hue="green"),
+    css=CSS
+) as demo:
+
+    gr.Markdown(
+        """
+        <div class='main-title'>
+            <h1>♻️ AI 垃圾分类助手</h1>
+            <h3>拍照识别 · 投放指南 · 环保积分</h3>
+        </div>
+        """
+    )
+
+    gr.HTML(CLASS_HINT)
+
+    # 上传区域
+    with gr.Group(elem_classes="upload-panel"):
+
+        image_input = gr.Image(
+            type="pil",
+            label="📷 上传垃圾图片",
+            height=220,
+            elem_id="upload-image"
+        )
+
+        username_input = gr.Textbox(
+            label="👤 用户名",
+            value="default",
+            placeholder="输入用户名记录积分"
+        )
+
+        submit_btn = gr.Button(
+            "🔍 开始识别",
+            variant="primary",
+            size="lg"
+        )
+
+    # 识别结果区域
+    gr.Markdown(
+        "### 🤖 AI 识别结果"
+    )
+
+    result_output = gr.HTML(
+        value="""
+        <div class='empty-card'>
+            <h2>📷 等待上传图片</h2>
+            <p>上传垃圾图片后点击「开始识别」</p>
+        </div>
+        """
+    )
+
+    # Tabs
+    with gr.Tabs():
+
+        with gr.Tab("📋 投放指南"):
+            knowledge_output = gr.HTML(
+                value="""
+                <div class='empty-card'>
+                    等待识别结果...
+                </div>
+                """
+            )
+
+        with gr.Tab("📊 环保统计"):
+            stats_output = gr.HTML(
+                value="""
+                <div class='empty-card'>
+                    等待识别结果...
+                </div>
+                """
+            )
+
+    # 按钮事件
+    submit_btn.click(
+        fn=classify_and_advise,
+        inputs=[image_input, username_input],
+        outputs=[
+            result_output,
+            knowledge_output,
+            stats_output
+        ]
+    )
+
+
+# --------------------------------------------------
+# 启动
+# --------------------------------------------------
+def launch_gradio(server_port=7860):
+
+    print(
+        f"🌐 Gradio Web 界面: http://localhost:{server_port}"
+    )
+
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=server_port,
+        share=False
+    )
+
+
+if __name__ == "__main__":
+    launch_gradio()