# OPTIMAL_KNN_MNIST_QUESTION

**Repository Path**: li-kun-zhe/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**: 309
- **Created**: 2025-09-19
- **Last Updated**: 2025-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 最佳 KNN 手写数字识别（本地模型 + Pinecone 云检索）

![训练过程](modle_training.png)
![效果图](%E6%95%88%E6%9E%9C%E5%9B%BE1.png)
![输入图片说明](%E6%95%88%E6%9E%9C%E5%9B%BE2.png)
![输入图片说明](%E6%95%88%E6%9E%9C%E5%9B%BE3.png)

## 项目简介
本项目提供两种推理方式：

1) 本地 KNN 模型推理：
- `optimal_knn.py` 寻找 K=1..40 中使准确率最高的最优 K，保存模型为 `best_knn_model.pkl`，并输出准确率曲线 `accuracy_plot.pdf`。
- `optimal_knn_webapp.py` 使用 Gradio 启动 Web 应用，载入本地最佳模型进行预测。

2) Pinecone 云向量检索推理：
- 将 sklearn digits 数据集写入 Pinecone 索引，使用 K=11 的最近邻进行多数投票，实现每次推理走云端检索。
- `import_MNIST.py`：快速将全部 1797 条向量导入到索引（需索引已存在）。
- `pinecone_train.py`：80% 训练集上传索引且带进度条；使用 20% 测试集在 k=11 下评估准确率并打印日志（带日期）。
- `pinecone_example.py`：构造一个“3”的 8x8 示例向量查询并打印相似结果。
- `optimal_knn_webapp_pinecone.py`：每次推理都通过 Pinecone 检索（k=11），按邻居标签占比输出概率。

所有 Pinecone 相关代码基于 Pinecone v5 客户端（`pinecone>=5.0.0`）。

## 目录结构
- `optimal_knn.py`：寻找最优 K 并保存本地模型
- `optimal_knn_webapp.py`：基于本地模型的 Web 应用
- `optimal_knn_webapp_pinecone.py`：基于 Pinecone 检索的 Web 应用（每次推理走云端）
- `import_MNIST.py`：导入 digits 全量向量到索引
- `pinecone_train.py`：创建/重建索引，上传 80% 训练数据并评估 k=11 准确率
- `pinecone_example.py`：示例查询脚本
- `link.py`：演示索引的创建/删除（v5 用法）
- `requirements.txt`：依赖清单

## 环境要求
- Python 3.9+（推荐 3.10/3.11/3.12）
- Windows/ macOS/ Linux（文档命令以 Windows PowerShell 为例）
- 网络可访问 Pinecone 服务

## 安装
建议使用虚拟环境，以下命令以 PowerShell 为例：

```powershell
python -m pip install -r requirements.txt
```

`requirements.txt` 中已包含：
- gradio, numpy, scikit-learn, matplotlib, pillow, tqdm
- pinecone>=5.0.0（Pinecone v5 客户端）

## 一、本地 KNN 模型流程

### 1) 训练最优 K 模型
```powershell
python .\optimal_knn.py
```
输出：
- `best_knn_model.pkl`
- `accuracy_plot.pdf`
- 终端打印最高准确率、最佳 K、使用的随机种子

### 2) 启动本地模型 Web 应用
```powershell
python .\optimal_knn_webapp.py
```
浏览器打开后，在画布中绘制数字，点击提交查看预测结果。

## 二、Pinecone 云向量检索流程

### 0) 准备 Pinecone API Key
在 PowerShell 中给当前会话设置环境变量（运行前每次设置或配置为系统环境变量）：
```powershell
$env:PINECONE_API_KEY = "你的真实APIKey"
```
可选：指定索引名（默认 `mnist-index`）
```powershell
$env:PINECONE_INDEX = "mnist-index"
```

### 1) 创建索引（二选一）
方法 A：使用 `pinecone_train.py`（推荐，它会自动删除重建索引）
```powershell
python .\pinecone_train.py
```
该脚本会：
- 删除同名索引并重建（dimension=64, metric=euclidean, serverless: aws/us-east-1）
- 上传 80% 训练数据（约 1437 条，带进度条）
- 在 20% 测试集上以 k=11 评估准确率（带进度条）
- 日志打印包含日期，例如：
	- 成功创建索引，并上传了1437条数据
	- 当k=11时，使用Pinecone的准确率: 0.98xx

方法 B：只创建索引（`link.py`），然后用 `import_MNIST.py` 全量上传
```powershell
python .\link.py
python .\import_MNIST.py
```

### 2) 示例查询（可选）
```powershell
python .\pinecone_example.py
```
构造一个“3”的 8x8 图像向量进行查询，打印相似结果的 id、score、label，并显示图像及最终预测标签。

### 3) 启动 Pinecone 在线推理 Web 应用
```powershell
python .\optimal_knn_webapp_pinecone.py
```
说明：
- 该应用的每次预测都会对预处理后的 64 维向量执行 `top_k=11` 的检索，对邻居标签做多数投票。
- 将标签在邻居中出现的频率当作“概率”展示前 3 名。

## 关键实现说明
- 预处理：与 sklearn digits 对齐，输入画布转灰度，反相+对比度增强，裁剪居中成方形，缩放到 8x8，缩放到 0..16，最后展平成 64 维向量。
- 索引设置：dimension=64，metric=euclidean；Serverless 默认在 aws/us-east-1，可按账号改区域。
- Pinecone v5：所有客户端操作通过实例方法（`pc = Pinecone(api_key=...)`，`pc.Index(name)`，`pc.list_indexes()`，`pc.create_index(...)`，`pc.delete_index(...)`）。
- 向量格式：v5 推荐字典格式 `{id, values, metadata}`；metadata 中保存 `{"label": int}`。

## 常见问题排查（FAQ）
- 报错 `PINECONE_API_KEY` 缺失：
	- 请先在 PowerShell 设置环境变量：`$env:PINECONE_API_KEY = "..."`
- 报错 `未找到索引 'mnist-index'`：
	- 先运行 `pinecone_train.py` 或 `link.py`+`import_MNIST.py` 创建并写入数据。
- `TypeError: Pinecone.list_indexes() missing 1 required positional argument: 'self'`：
	- 说明以类方法调用了 v5 客户端方法，请改为实例调用（本仓库代码已修正）。
- 维度或度量不匹配：
	- digits 是 8x8 展平 => dimension=64；使用 euclidean 度量与预处理保持一致。

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