# OPTIMAL_KNN_MNIST_QUESTION

**Repository Path**: wangzhibo369/optimal_knn_mnist_question

## Basic Information

- **Project Name**: OPTIMAL_KNN_MNIST_QUESTION
- **Description**: 本项目使用gradio应用在 minist 上训练的最有 KNN 模型就行手写数字识别。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 297
- **Created**: 2025-09-19
- **Last Updated**: 2025-09-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 最佳 KNN 手写数字识别
![model training process](model_training.jpeg)
![webapp screen shot](screen_shot.jpeg)
# KNN 手写数字识别（MNIST-like digits）

这是一个用 K 近邻（KNN）算法识别手写数字的小项目，包含：

- `optimal_knn.py`：训练脚本，测试不同的 K 值（1..40），选择最佳 K 并保存模型与准确率图。
- `optimal_knn_webapp.py`：基于 Gradio 的 Web 应用，允许用户在画布上手写数字并获取模型预测结果。

本仓库的目标是：演示如何使用 sklearn 对手写数字进行分类、如何保存/加载模型、以及如何快速构建一个交互式的 Web 演示。

## 项目结构

```
optimal_knn_mnist_question/
├─ optimal_knn.py           # 训练并选择最佳 K 的脚本
├─ optimal_knn_webapp.py    # Gradio Web 应用
├─ best_knn_model.pkl       # 训练后保存的最佳模型（如果已生成）
├─ accuracy_plot.pdf        # 不同 K 下的准确率图（如果已生成）
├─ pyproject.toml           # uv 依赖配置
├─ uv.lock                  # uv 依赖锁
└─ readme.md
```

## 实现细节（简要）

1) 数据与训练

- 使用 `sklearn.datasets.load_digits()`（8x8 灰度像素，像素值范围约 0..16）作为样例数据集。
- 在 `optimal_knn.py` 中使用 `train_test_split(random_state=42)` 固定数据分割，避免每次运行产生过多随机差异。
- 遍历 k=1..40，训练 `KNeighborsClassifier(n_neighbors=k)` 并记录测试集准确率，使用 `tqdm` 显示进度条。
- 将最佳模型使用 `pickle.dump` 保存为 `best_knn_model.pkl`；将准确率随 k 变化绘制为 `accuracy_plot.pdf`，图中标有最佳 k 的垂直红线和文字标注。

2) Web 应用与预处理

- `optimal_knn_webapp.py` 使用 Gradio 的 Blocks API 构建界面，左侧为画布（`Sketchpad` 或回退为 `gr.Image`），右侧显示单一预测结果。
- 预处理流程较为稳健：支持 RGB/RGBA 输入，自动反转背景颜色（如有需要），使用 Otsu 二值化找到数字的边界框，裁剪并居中到正方形画布，使用质心居中与 GaussianBlur 平滑，然后缩放到 8x8 并映射到 0..16（与 sklearn digits 的范围一致）。
- 增加了“清除”按钮，使其同时清空画布和预测结果。

## 使用说明（在 Windows + PowerShell 下）

下面的步骤假设你已经安装了 Python 3.9+。

1) 安装并配置依赖（使用 uv）

如果你还没安装 `uv`，请先安装 `uv`（参见官方文档）。在项目根目录运行：

```powershell
# 安装项目依赖到 .venv 并创建虚拟环境
uv add scikit-learn matplotlib tqdm gradio pillow numpy opencv-python
```

这会在本目录下创建 `.venv` 并安装依赖，`uv` 会维护 `uv.lock`。

2) 训练模型

```powershell
uv run python optimal_knn.py
```

运行后会在当前目录生成：

- `best_knn_model.pkl`：序列化的 KNN 最优模型
- `accuracy_plot.pdf`：不同 K 下准确率的折线图，标注最佳 K

3) 启动 Web 应用

```powershell
uv run python optimal_knn_webapp.py
```

运行后终端会输出本地 URL，例如：`http://127.0.0.1:7862`，用浏览器打开即可在画布上手写数字并点击“识别”。清除按钮会同时清空画布与结果。

## 常见问题与故障排查

- 如果启动时报错 `ModuleNotFoundError: No module named 'sklearn'` 或类似错误，请确保已通过 `uv add` 安装依赖，并使用 `uv run` 来执行脚本以确保使用虚拟环境中的包。
- 如果 Gradio 画布无法显示或 `Sketchpad` 的参数不同（不同版本 API 变化），`optimal_knn_webapp.py` 已实现兼容回退到 `gr.Image(source='canvas', tool='sketch')`。
- 如果预测总是某一固定数字或预测不准，常见原因：
	- 画笔过细/数字太小或停靠在画布边缘，请尽量用较粗的笔触且把数字放在画布中心。
	- 模型训练受限于简单特征（8x8 原始像素），可以改用 HOG 特征或训练小型 CNN 以提升准确率（见下节）。

## 后续改进建议（可选）

1. 使用 HOG 特征：对原始图像提取 HOG（方向梯度直方图）作为 KNN 的输入，通常比 8x8 原始像素更稳健。
2. 数据增强：在训练阶段对样本做旋转、缩放、平移等，增强模型对手写差异的鲁棒性。
3. 使用小型卷积神经网络（CNN）：如果你愿意增加 TensorFlow 或 PyTorch 依赖，训练 CNN 能获得更好效果。

如果你要我继续，我可以：

- 立刻实现并训练基于 HOG 的 KNN（修改 `optimal_knn.py` 并保存新模型），然后同步修改 Web 应用的预处理以产生 HOG 特征并验证效果；或者
- 帮你实现一个小型 CNN 的训练与部署（需要额外依赖和更长训练时间）。

# 个人信息
学号: 202352320101
年级: 2023
专业: 智能科学与技术
班级: 1班