# pinecone_knn_mnist_app

**Repository Path**: liu-yi-ch-en/pinecone_knn_mnist_app

## Basic Information

- **Project Name**: pinecone_knn_mnist_app
- **Description**: 使用Pinecone实现最佳 KNN 模型识别手写数字的APP
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-10-10
- **Last Updated**: 2025-11-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 使用Pinecone实现最佳 KNN 模型识别手写数字的APP
![model training process](model_training.jpeg)
![webapp screen shot](screen_shot.jpeg)
![model example](model_example.jpeg)

## 项目简介
本项目基于 Pinecone 向量数据库实现手写数字识别的 KNN 推理：

- 使用 `pinecone_train.py` 将 MNIST 训练集（784 维，28×28 展平）写入 Pinecone 索引，并用测试集做基于近邻投票的准确率评估。
- 使用 `optimal_knn_webapp_pinecone.py` 启动 Gradio Web 应用，用户在画布上书写数字后，通过 Pinecone 检索近邻并返回预测。
- `pinecone_example.py` 提供一个更轻量的 8×8 手写数字示例流程（维度为 64），用于演示索引创建、插入与查询。

参考：Pinecone 官方网站 https://www.pinecone.io ；Gradio 官方网站 https://www.gradio.app/

## 项目结构
```
├─ accuracy_plot.pdf           # 训练/测试结果可视化（如有）
├─ best_knn_model.pkl          # 旧版本地KNN模型（当前Web端不再依赖）
├─ model_training.jpeg         # 训练流程示意图
├─ optimal_knn_webapp_pinecone.py  # Gradio Web应用（通过 Pinecone 检索预测）
├─ pinecone_train.py           # 将MNIST数据写入 Pinecone 并评估准确率
├─ pinecone_example.py         # 8×8手写数字的 Pinecone 示例（维度64）
├─ readme.md                   # 本说明文档
└─ screen_shot.jpeg            # Web应用截图
```

## 环境与安装
- Python 3.9+
- 建议创建虚拟环境

安装依赖（示例）：
```bash
pip install "pinecone-client>=3" scikit-learn numpy pillow gradio tqdm matplotlib
```

## Pinecone 配置（重要）
- 建议通过环境变量提供 API Key：
  - Windows PowerShell：`$env:PINECONE_API_KEY = "你的APIKey"`
- 当前代码中 `pinecone_train.py`、`optimal_knn_webapp_pinecone.py`、`pinecone_example.py` 使用了硬编码变量 `api_key = "..."`。为安全起见，推荐改成从环境变量读取，或手动替换为你自己的密钥。
- 索引名称默认使用 `mnist-index`。不同维度的数据请使用不同索引名称，避免维度不匹配。

## 数据与索引维度
- `pinecone_train.py` 使用 MNIST（784 维），索引维度=784，`metric="euclidean"`。
- `pinecone_example.py` 使用 8×8 digits（64 维），索引维度=64。请避免与 `mnist-index(784维)` 复用同一索引名。

## 使用步骤
### 1) 训练并写入索引（MNIST，784维）
运行 `pinecone_train.py` 将训练数据批量 upsert 到 Pinecone，并对测试集进行投票评估：
```bash
python pinecone_train.py
```
脚本会：
- 加载 MNIST 数据并划分训练/测试集。
- 如存在同名索引将其删除并重新创建（注意数据会被清空）。
- 分批 `upsert` 训练向量，随后对测试集逐条查询近邻进行投票，输出准确率。

### 2) 启动 Web 应用（基于 Pinecone 推理）
```bash
python optimal_knn_webapp_pinecone.py
```
然后在浏览器打开本地地址（Gradio 启动日志中会显示 URL）。在画布中书写 0–9 任意数字，点击“提交”即可看到预测结果。

### 3) 运行示例脚本（64维示例）
```bash
python pinecone_example.py
```
注意：该脚本维度为 64，请使用与 784 维索引不同的索引名，或相应修改维度以保持一致。

## 常见问题
- 索引维度不匹配：确保创建索引的 `dimension` 与写入/查询向量长度一致（784 或 64）。
- 索引空查询：新 upsert 的数据可能需要数秒同步，脚本中已加入 `time.sleep()` 等待。
- API Key 安全：请不要把真实密钥提交到仓库，推荐使用环境变量或密钥管理服务。

## 个人信息

- 学号: 202352320122
- 年级: 2023级
- 专业: 智能科学与技术
- 班级: 1 班