feat: add doc and experiment

.gitea/workflows/test.yaml

@@ -0,0 +1,27 @@
+name: Gitea Actions Experiment Test
+run-name: 实验自动评测 Actions 🚀
+on: [push]
+
+jobs:
+  Experiment-Actions:
+    runs-on: ubuntu-latest
+    steps:
+      - name: 检出代码
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: 安装依赖
+        run: |
+          python -m venv ./.venv
+          . ./.venv/bin/activate
+          curl -s -o pip_cache.tar.gz ${{ vars.BACKEND_URL }}/download/pip_cache.tar.gz
+          tar -zxf pip_cache.tar.gz
+          pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
+          rm -rf testDigits trainingDigits main.py
+          curl -s -o main.py ${{ vars.BACKEND_URL }}/public/experiment/knn/main.py
+          curl -s -o dataSet.tar.gz ${{ vars.BACKEND_URL }}/public/experiment/knn/dataSet.tar.gz
+          tar -zxf dataSet.tar.gz
+      - name: 评测结果
+        run: |
+          . ./.venv/bin/activate
+          python main.py

README.md

@@ -1 +1,45 @@
-# Experiment-kNN
+# 实验一：kNN 算法
+
+## 实验说明
+
+- 自行在 [`function.py`](./function.py) 中编写实现数据加载与 kNN 的手写数字分类算法。
+- 函数输入: 待分类的样本 `input_vector`, 训练数据集 `dataSet`, 训练集对应的标签 `labels`。
+- 函数返回: 预测的分类标签。
+
+所有成功上传的评测结果均会被记录，但不会公开展示。
+
+评测次数不限，最终评测成绩取**最高分**。
+
+## 注意事项
+
+实验开始前必须在 [`function.py`](./function.py#L28-L29) 中填写自己的学号和姓名！
+
+- 可以自行导入其他库，需要在 [`requirements.txt`](./requirements.txt) 添加依赖，若未在 [`requirements.txt`](./requirements.txt) 中添加使用到的依赖，则无法自动评测，成绩为零。
+- 需要在 [`function.py`](./function.py) 中实现完整的 kNN 分类算法。
+- 自动评测脚本仅会加载 `classify` 和 `load_data` 函数，请勿修改函数名。
+- 仓库内不自带数据集，本地调试时，数据集需自行下载。
+- 本地调试完成后，**需要更新提交代码**，否则无法自动评测，**没有实验成绩**。
+- 评测的运行时间受机器性能影响，运行时间仅供参考。
+- 若有评测相关问题，请在[项目工单](https://git.intcplab.cn/LufsX/Evaluation-Backend/issues)处提出，或联系 QQ: `1968647927`。
+
+代码提交后会进行自动评测，评测所用的环境如下：
+
+- CPU: Intel Xeon(R) CPU E3-1231 v3 @ 3.40GHz
+- OS: Ubuntu 22.04.4 LTS
+- Python: 3.10.12
+- numpy: 2.1.1
+
+## 实验操作
+
+本次实验因数据文件较多，故仓库内不自带数据集，本地调试时需自行下载数据集。
+
+- [二值手写数字数据集.zip](https://git.intcplab.cn/yuhuapeng/Machine-Learning-in-Python/raw/branch/main/%E7%AC%AC9%E7%AB%A0%209.1%20KNN%E5%88%86%E7%B1%BB%E5%99%A8/%E4%BA%8C%E5%80%BC%E6%89%8B%E5%86%99%E6%95%B0%E5%AD%97%E6%95%B0%E6%8D%AE%E9%9B%86.zip)
+- [二值手写数字数据集.tar.gz](https://git.intcplab.cn/LufsX/Challenge-Backend/raw/branch/main/public/experiment/knn/dataSet.tar.gz)
+
+以上两文件解压内容相同，解压后得到 `trainDigits` 和 `testDigits` 文件夹，分别存放训练集和测试集。
+
+本次实验强烈建议将代码克隆/下载到本地进行实验调试。
+
+---
+
+提交评测简要说明同[挑战赛的说明](https://git.intcplab.cn/LufsX/Challenge-kNN#挑战操作)，这里不再赘述。

function.py

@@ -0,0 +1,98 @@
+# function.py
+import numpy as np
+import os
+
+"""
+实验说明:
+- 自行编写实现数据加载与 kNN 的手写数字分类算法。
+- 函数输入: 待分类的样本 input_vector, 训练数据集 dataSet, 训练集对应的标签 labels。
+- 函数返回: 预测的分类标签。
+
+注意事项:
+- 在 function.py 中实现 kNN 分类算法。
+- 可以自行导入其他库，需要在 requirements.txt 添加依赖，若未在 requirements.txt 中添加使用到的依赖，则无法自动评测，成绩为零。
+- 自动评测脚本仅会加载 classify 和 load_data 函数，请勿修改函数名。
+- 训练集和测试集需手动下载解压，并放入当前目录下。
+
+测评环境:
+- CPU: Intel Xeon(R) CPU E3-1231 v3 @ 3.40GHz
+- OS: Ubuntu 22.04.4 LTS
+- Python: 3.10.12
+- numpy: 2.1.1
+"""
+
+
+"""
+请在这里填写学号和姓名，不填写即成绩无效。
+"""
+id = "202210423xxx"
+name = "test_name"
+
+
+"""
+参数说明:
+- input_vector (numpy array): 输入待分类的样本。
+- dataSet (numpy array): 训练数据集。
+- labels (list or numpy array): 训练集对应的标签。
+- k (int): KNN 算法参数，请自行设置默认值，评测时仅会使用其默认值。
+返回值:
+- int: 预测的分类标签。
+"""
+
+
+# 这里写自己的代码实现
+def classify(input_vector, dataSet, labels, k=3):
+    """
+    KNN 分类算法。
+
+    Args:
+    - input_vector (numpy array): 输入待分类的样本。
+    - dataSet (numpy array): 训练数据集。
+    - labels (list or numpy array): 训练集对应的标签。
+    - k (int): KNN 算法参数，请自行设置默认值，评测时仅会使用其默认值。
+
+    Returns:
+    - int: 预测的分类标签。
+    """
+
+
+# 这里也写自己的代码实现
+def load_dataset(directory):
+    """
+    从文件夹中加载数据。
+
+    Args:
+    - directory (str): 数据文件夹路径。
+
+    Returns:
+    - np.array: 特征数据。
+    - np.array: 标签数据。
+    """
+
+
+# 这里还写自己的代码实现
+def img_to_vector(filename):
+    """
+    将二值图像转换为向量。
+
+    Args:
+    - filename (str): 图像文件路径。
+
+    Returns:
+    - np.array: 二值图像向量。
+    """
+
+
+if __name__ == "__main__":
+    # 以下代码可用于测试，可自行随意修改
+
+    train_data, train_labels = load_dataset("trainingDigits")
+
+    test_data = "0000000000000011000000000000000000000000000011111000000000000000000000000000111111000000000000000000000000111111111000000000000000000000001111111110000000000000000000000011111111000000000000000000000001111111100000000000000000000000111111111000000000000000000000001111111100000000000000000000000011111111000000000000000000000000111111110000000000000000000000001111111100000000000000000000000011111110000000000000000000000001111111100000000000000000000000011111111000000000000000000000000111111110000000000000000000000001111111111111000000000000000000011111111111111110000000000000000111111111111111110000000000000011111111111111111110000000000000111111111111111111100000000000000111111111111111111000000000000001111111111111111110000000000000001111111111001111111000000000000011111111100011111110000000000000011111111001111111100000000000000111111111111111110000000000000000111111111111111100000000000000000111111111111111000000000000000000111111111111000000000000000000000111111111000000000000000000000000000111100000000000"
+    predicted_label = classify(
+        np.array([int(char) for char in test_data]).reshape(1, 1024),
+        train_data,
+        train_labels,
+    )
+
+    print(f"预测的标签: {predicted_label}")

requirements.txt

@@ -0,0 +1,2 @@
+numpy==2.1.1
+requests==2.32.3