# OPTIMAL_KNN_MNIST_QUESTION

**Repository Path**: ipa-project01-palette/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**: 378
- **Created**: 2025-09-19
- **Last Updated**: 2025-10-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

## 项目简介
这个项目包含两个主要的Python脚本：`optimal_knn.py` 和 `optimal_knn_webapp.py`。

`optimal_knn.py` 脚本用于找出最优的K值，以便在K近邻分类器中使用。它首先加载手写数字数据集，然后尝试不同的K值，找出能够使模型准确率最高的K值。最后，它将最优的KNN模型保存到一个pickle文件中。

`optimal_knn_webapp.py` 脚本使用[Gradio](https://www.gradio.app/)库创建一个web应用，该应用可以接收用户的手写数字图像输入，然后使用之前保存的最优KNN模型进行预测，最后返回预测的数字。Gradio库使得创建这个用户友好的界面变得简单快捷。

## 文件结构（主要文件）
- optimal_knn.py          - 寻找并保存最优 K 的训练脚本
- optimal_knn_webapp.py   - 基于 Gradio 的预测 Web 应用
- model_knn_best.pkl      -（输出）保存的最优 KNN 模型（运行训练脚本后生成）
- readme.md               - 本文档，包括安装与使用说明
- model_training.jpeg / screen_shot.jpeg - 项目展示图片

## 依赖与安装
建议使用虚拟环境（venv 或 conda）。主要依赖：
- python >= 3.8
- scikit-learn
- matplotlib
- numpy
- pillow (PIL)
- opencv-python (cv2)
- tqdm
- gradio
- pickle（内置）

使用 pip 安装示例：
```bash
pip install scikit-learn matplotlib numpy pillow opencv-python tqdm gradio
```

## 运行说明

1. 训练并生成最优模型
   - 在 `optimal_knn.py` 中填充所有 `# TODO` 部分（若尚未实现）。
   - 运行训练脚本：
     ```bash
     python optimal_knn.py
     ```
   - 脚本将：
     - 加载数据集（例如 sklearn 自带的 digits 或自定义 MNIST 预处理后的数据）；
     - 在一系列 K 值上评估（通常使用交叉验证或验证集）；
     - 输出最佳的 K、对应的准确率并将模型保存为 `model_knn_best.pkl`（或脚本内指定的路径）

2. 启动 Web 应用进行在线预测
   - 确保训练步骤已生成模型文件（默认名如 `model_knn_best.pkl`）。
   - 在 `optimal_knn_webapp.py` 中填充 `# TODO` 部分（如模型加载、输入预处理、返回格式等）。
   - 运行 Web 应用：
     ```bash
     python optimal_knn_webapp.py
     ```
   - 打开命令行中给出的本地 URL（Gradio 会显示），在画板中绘制手写数字并提交，查看预测结果。

## 输入预处理提示
- Web 应用中用户绘制的图像通常需要：
  - 转为灰度；
  - 调整大小到训练时使用的尺寸（例如 8x8 或 28x28）；
  - 归一化（0-1）或按训练时相同的方式展平为 1D 向量；
  - 有需要时进行反色（画布白底黑字 vs 训练样本格式）。
- 在 `optimal_knn_webapp.py` 中务必保证预处理流程与训练时一致，否则预测效果会下降。

## 模型格式与保存位置
- 推荐使用 pickle 保存模型，例如 `model_knn_best.pkl`：
  ```python
  import pickle
  with open('model_knn_best.pkl', 'wb') as f:
      pickle.dump(best_model, f)
  ```
- Web 应用加载示例：
  ```python
  with open('model_knn_best.pkl', 'rb') as f:
      model = pickle.load(f)
  ```

## 示例命令（快速回顾）
- 训练并保存模型：
  ```bash
  python optimal_knn.py
  ```
- 启动 Web 应用：
  ```bash
  python optimal_knn_webapp.py
  ```

## 常见问题与调优建议
- 精度低：
  - 检查训练/测试集划分是否合理；
  - 尝试更大的训练集或数据增强；
  - 调整 K 的搜索范围，或使用距离加权（weights='distance'）；
  - 确保输入预处理和训练时一致（尤其是尺寸与灰度反转）。
- 预测速度慢（对大数据）：
  - KNN 在查询时成本高；可考虑使用 KDTree/BallTree，或在部署时改用更快的模型（如小型 CNN）。

## 许可证与作者信息
- 学号: 202352320205  
- 年级: 2023  
- 专业: 智能科学与技术  
- 班级: 2 班