Upload COLAB_GUIDE.md

COLAB_GUIDE.md

@@ -0,0 +1,325 @@
+# 🚀 Google Colab 训练指南
+
+本指南教你如何在 **免费的 Google Colab T4 GPU** 上训练籽粒分类模型。
+
+---
+
+## 第一步：打开 Colab
+
+1. 访问 [colab.research.google.com](https://colab.research.google.com)
+2. 点击 **文件 → 新建笔记本**
+
+---
+
+## 第二步：切换到 GPU 环境
+
+点击菜单栏：
+```
+Runtime → Change runtime type → Hardware accelerator → T4 GPU
+```
+然后点击 **Save**，并 **重新连接**（点击左上角重新连接按钮）。
+
+---
+
+## 第三步：逐 Cell 运行代码
+
+将下面的代码按顺序复制到 Colab 的每个 Cell 中运行：
+
+### Cell 1：检查 GPU
+```python
+!nvidia-smi
+```
+> 应该能看到 `Tesla T4` 信息。如果看不到，回到第二步确认 GPU 已启用。
+
+---
+
+### Cell 2：安装依赖
+```python
+!pip install -q transformers datasets accelerate evaluate pillow huggingface_hub
+print("✅ 依赖安装完成")
+```
+
+---
+
+### Cell 3：导入库
+```python
+import os
+import numpy as np
+from datasets import load_dataset
+from transformers import (
+    AutoImageProcessor,
+    AutoModelForImageClassification,
+    TrainingArguments,
+    Trainer,
+    DefaultDataCollator,
+)
+from PIL import Image
+import evaluate
+from huggingface_hub import notebook_login
+```
+
+---
+
+### Cell 4：登录 Hugging Face（必须！）
+```python
+notebook_login()
+```
+> 运行后会弹出一个输入框，要求输入 **Access Token**。
+>
+> 🔑 **如何获取 Token？**
+> 1. 打开 [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens)
+> 2. 点击 `New token`
+> 3. 选择 **Write** 权限
+> 4. 复制 token 粘贴到 Colab 弹窗中
+
+---
+
+### Cell 5：加载数据集
+```python
+DATASET_NAME = "nateraw/rice-image-dataset"
+print(f"Loading dataset: {DATASET_NAME}...")
+ds = load_dataset(DATASET_NAME)
+print(ds)
+
+labels = ds["train"].features["label"].names
+num_labels = len(labels)
+print(f"\n📋 类别数量: {num_labels}")
+print(f"📋 类别列表: {labels}")
+```
+
+---
+
+### Cell 6：划分训练/验证集
+```python
+split_ds = ds["train"].train_test_split(
+    test_size=0.15,
+    stratify_by_column="label",
+    seed=42
+)
+train_ds = split_ds["train"]
+val_ds = split_ds["test"]
+
+print(f"训练集: {len(train_ds)} 张")
+print(f"验证集: {len(val_ds)} 张")
+```
+
+---
+
+### Cell 7：加载模型
+```python
+MODEL_NAME = "microsoft/resnet-18"
+
+processor = AutoImageProcessor.from_pretrained(MODEL_NAME)
+
+label2id = {label: i for i, label in enumerate(labels)}
+id2label = {i: label for i, label in enumerate(labels)}
+
+model = AutoModelForImageClassification.from_pretrained(
+    MODEL_NAME,
+    num_labels=num_labels,
+    id2label=id2label,
+    label2id=label2id,
+    ignore_mismatched_sizes=True,
+)
+
+print(f"✅ 模型加载完成")
+print(f"参数总量: {sum(p.numel() for p in model.parameters()) / 1e6:.1f}M")
+```
+
+---
+
+### Cell 8：数据预处理
+```python
+def transform(example_batch):
+    images = []
+    for img in example_batch["image"]:
+        if isinstance(img, Image.Image):
+            if img.mode != "RGB":
+                img = img.convert("RGB")
+            images.append(img)
+        else:
+            img = Image.fromarray(np.array(img)).convert("RGB")
+            images.append(img)
+    inputs = processor(images, return_tensors="pt")
+    inputs["labels"] = example_batch["label"]
+    return inputs
+
+train_ds.set_transform(transform)
+val_ds.set_transform(transform)
+print("✅ 数据预处理设置完成")
+```
+
+---
+
+### Cell 9：评估指标
+```python
+accuracy = evaluate.load("accuracy")
+f1 = evaluate.load("f1")
+
+def compute_metrics(eval_pred):
+    predictions, labels = eval_pred
+    preds = np.argmax(predictions, axis=1)
+    acc = accuracy.compute(predictions=preds, references=labels)
+    f1_score = f1.compute(predictions=preds, references=labels, average="weighted")
+    return {"accuracy": acc["accuracy"], "f1": f1_score["f1"]}
+
+print("✅ 评估指标定义完成")
+```
+
+---
+
+### Cell 10：训练参数配置
+```python
+OUTPUT_REPO = "chaosbee997/rice-seed-classifier"  # ← 改成你的仓库名
+
+args = TrainingArguments(
+    output_dir="/content/rice-seed-classifier",
+    remove_unused_columns=False,
+    evaluation_strategy="epoch",
+    save_strategy="epoch",
+    learning_rate=5e-5,
+    per_device_train_batch_size=64,
+    per_device_eval_batch_size=64,
+    num_train_epochs=5,
+    warmup_ratio=0.1,
+    logging_strategy="steps",
+    logging_steps=50,
+    logging_first_step=True,
+    load_best_model_at_end=True,
+    metric_for_best_model="accuracy",
+    seed=42,
+    push_to_hub=True,
+    hub_model_id=OUTPUT_REPO,
+    report_to="none",
+)
+
+print(f"训练配置:")
+print(f"  输出仓库: {OUTPUT_REPO}")
+print(f"  学习率: {args.learning_rate}")
+print(f"  Batch size: {args.per_device_train_batch_size}")
+print(f"  Epochs: {args.num_train_epochs}")
+```
+
+---
+
+### Cell 11：开始训练 🚀
+```python
+trainer = Trainer(
+    model=model,
+    args=args,
+    train_dataset=train_ds,
+    eval_dataset=val_ds,
+    compute_metrics=compute_metrics,
+    data_collator=DefaultDataCollator(),
+    tokenizer=processor,
+)
+
+print("开始训练...\n" + "="*50)
+trainer.train()
+```
+> ⏱️ 训练时间：T4 GPU 上约 **15-30 分钟**（5 epochs，63K训练样本）
+>
+> 📊 预期结果：准确率 > **95%**
+
+---
+
+### Cell 12：评估并上传模型
+```python
+metrics = trainer.evaluate()
+print("\n最终评估结果:")
+print("="*50)
+for k, v in metrics.items():
+    if isinstance(v, float):
+        print(f"  {k}: {v:.4f}")
+    else:
+        print(f"  {k}: {v}")
+
+print("\n正在上传到 Hugging Face Hub...")
+trainer.push_to_hub()
+print(f"\n✅ 上传成功!")
+print(f"🔗 模型地址: https://huggingface.co/{OUTPUT_REPO}")
+```
+
+---
+
+### Cell 13：推理测试
+```python
+from transformers import pipeline
+import matplotlib.pyplot as plt
+
+classifier = pipeline("image-classification", model=OUTPUT_REPO)
+
+# 从数据集取一张图测试
+test_image = ds["train"][100]["image"]
+
+plt.figure(figsize=(5, 5))
+plt.imshow(test_image)
+plt.axis("off")
+plt.title("测试图像")
+plt.show()
+
+results = classifier(test_image)
+print("\n🔮 预测结果:")
+for r in results:
+    print(f"  {r['label']}: {r['score']*100:.2f}%")
+```
+
+---
+
+## ⚡ 训练完成后
+
+你的模型会自动上传到：
+- **https://huggingface.co/chaosbee997/rice-seed-classifier**
+
+任何人都可以用一行代码加载你的模型：
+```python
+from transformers import pipeline
+classifier = pipeline("image-classification", model="chaosbee997/rice-seed-classifier")
+```
+
+---
+
+## 🌽 扩展到花生/玉米/小麦等其他作物
+
+如果你想训练包含 **花生、玉米、小麦、水稻** 的通用籽粒分类模型：
+
+1. **收集图像**：每种作物建立一个文件夹，例如：
+   ```
+   crop_seeds/
+   ├── peanut/
+   │   ├── img1.jpg
+   │   └── img2.jpg
+   ├── corn/
+   │   ├── img1.jpg
+   │   └── img2.jpg
+   ├── wheat/
+   │   ├── img1.jpg
+   │   └── img2.jpg
+   └── rice/
+       ├── img1.jpg
+       └── img2.jpg
+   ```
+
+2. **创建数据集**：
+   ```python
+   from datasets import load_dataset
+   ds = load_dataset("imagefolder", data_dir="/path/to/crop_seeds")
+   ds.push_to_hub("yourname/crop-seeds")
+   ```
+
+3. **修改 Cell 5**：把 `DATASET_NAME` 改成你的数据集名称
+
+4. **重新运行 Cell 5-12**，其余代码完全不用改！
+
+---
+
+## 🆘 常见问题
+
+**Q: 训练时报 `CUDA out of memory`？**  
+A: 减小 batch size：把 `per_device_train_batch_size=64` 改成 `32` 或 `16`。
+
+**Q: 没有 Hugging Face 账号？**  
+A: 免费注册：[huggingface.co/join](https://huggingface.co/join)
+
+**Q: 训练时间太长？**  
+A: 可以减少 epoch 数（`num_train_epochs=3`），或换更小的模型（`microsoft/resnet-34` 更大，`google/mobilenet_v2_1.0_224` 更轻）。