面向 8 类岩石（大理岩、片麻岩、玄武岩、石灰岩、石英岩、砂岩、花岗岩、页岩）的图像分类项目。 本仓库收录两个可直接查阅/复现的部分：
| 目录 | 内容 | 当前状态 |
|---|---|---|
PC_Project/ |
PC 端训练与评估：数据治理、特征工程、K 折 OOF、集成/蒸馏训练、模型注册表与 ONNX 导出、全部结果产物 | 当前交付模型 V8.1 为 evaluation_only（锁定测试 Accuracy 0.7203，未达 0.8 门槛） |
Jetson/ |
Jetson 端完整部署包：运行时、模型包、配置、主机侧测试、目标板脚本与文档 | 主机 ONNX Runtime 模拟已通过；目标板 TensorRT / 相机 / 功耗验证待做 |
本仓库只发布训练结果与部署端，不发布原始数据集与训练过程记录，边界见「收录与排除范围」。
Rock/
├── PC_Project/ # PC 端训练结果（代码 + 模型 + 评估产物）
│ ├── README.md # PC 端详细说明与版本结论
│ ├── docs/ # 数据/特征/训练规格与各版本报告（v3 → v8）
│ ├── configs/ # 数据切分、训练、蒸馏、集成配置
│ ├── rockid/ # 训练与评估主包
│ ├── scripts/ # 数据处理、训练、评估、导出、基准脚本
│ ├── tests/ # PC 端回归测试
│ ├── models/ # 模型注册表 + ONNX/INT8 导出（含量化说明）
│ └── outputs/ # 评估结果：指标 JSON/CSV、OOF 预测、选型证据、报告、图表
└── Jetson/ # Jetson 端完整部署包
├── README.md # 部署说明与验证边界
├── src/rockid_jetson/ # CLI、推理、拒识、SQLite 归档、导出
├── models/packages/ # 签名模型包（ONNX + manifest + 发布证据）
├── scripts/ # 环境检查、TensorRT 引擎构建、TensorRT 基准
├── deploy/jetson/ # 目标板安装/构建/基准脚本
├── tests/ # 主机侧测试
├── configs/, docs/, fixtures/, reports/, rock-ai.service
| 版本 | 方法 | 开发集 OOF Accuracy | 冻结/锁定集 Accuracy | 结论 |
|---|---|---|---|---|
| V4 | MobileNetV3-Large 224px + 矿物/纹理/颗粒/构造/孔隙裂缝加权特征融合 | 0.6414 | 0.6643（858 张） | 历史注册版本（models/registry.json 的 latest） |
| V5 | Swin V2 Tiny + 三尺度深度可分离纹理适配器 + FAISS 模糊检索融合 | 0.6891 | 0.7249（858 张） | 评估候选，未达 75% 目标 |
| V7 | V6.2 全局 Swin + DINOv2-Small（224/448/448-hflip）严格 5 折 OOF 加权集成 | 0.7504 | 未做外部测试 | 达到 75% 开发 OOF 门槛，但非外部发布版本（超出边缘预算） |
| V8.1 | MobileNetV3-Large 多视图蒸馏学生（教师 Swin V2 Tiny） | 0.7805 | 0.7203（640 张，461/640） | 当前交付 Jetson 的 evaluation_only 模型 |
补充口径：
| 版本 | 开发集 Macro-F1 | 冻结/锁定集 Macro-F1 | ECE |
|---|---|---|---|
| V4 | 0.6296 | 0.6580 | 0.0470 |
| V5 | 0.6824 | 0.7151 | 0.1317 |
| V7 | 0.7517（3,462 条 OOF） | — | 0.0416 |
| V8.1 | 0.7398 | 0.7178 | — |
V8 内部对比（开发集，来源 docs/v8_training_report.md）：教师 Swin V2 Tiny 0.7642、学生基线 0.7498、单视图蒸馏 0.7683、V8.1 同标本多视图蒸馏 0.7805。
- 口径纪律：开发集 OOF 用于选型，冻结集/锁定集只在模型确定后评估一次；V7 明确声明为开发 OOF 结果，不等价于外部测试。
- 模型状态诚实标注：V8.1 锁定测试未达 80% 门槛，因此注册表与 Jetson 包统一标记
evaluation_only，未包装为正式精度发布版。 - ONNX 一致性：V8.1 的 ONNX 与 FP32 PyTorch 最大概率差 0.01230532，Top-1 一致。
- 加速基准：
outputs/v7/benchmark_accelerators/与outputs/benchmarks/保留了加速器对比结果，不据此宣称 TensorRT 部署收益。
cd PC_Project
conda activate cuda_132 # Python 3.12 + torch 2.13.0+cu132
# V4/V5 主流程
python -m scripts.train_v5 --stage oof --run-id v5_swin_oof_e10 --batch-size 12
python -m scripts.eval_v5 --checkpoint outputs/runs/v5_swin_final_oof9/final_model/best.pt \
--index-dir outputs/runs/v5_swin_final_oof9/final_model/retrieval_index \
--selection outputs/runs/v5_swin_oof_e10/fuzzy_selection.json \
--out outputs/eval/v5_swin_final_oof9_cuda_recheck --batch-size 12
# V7 多尺度 OOF 集成
python -m scripts.prepare_v7_data --config configs/train_v7.yaml
python -m scripts.benchmark_v7 --config configs/train_v7.yaml --out outputs/v7/benchmark_accelerators
python -m scripts.select_v7_ensemble --config configs/ensemble_v7.yaml
# V8.1 学生蒸馏与 ONNX 导出
python -m scripts.prepare_v8_data --config configs/dataset_v81.yaml
python -m scripts.train_v8 --config configs/train_v81.yaml --stage final-student \
--run-id final_v81_student --teacher outputs/v8/candidate_teacher/best.pt --epochs 9原始训练数据（figure_data/）与派生的 PC_Project/data/ 未包含在本仓库中，因此上述命令需要先准备数据；数据规格见 PC_Project/docs/data_spec.md、feature_spec.md。
Jetson/models/packages/v81_student_evaluation/：
classifier.onnx：MobileNetV3-Large，输入1x3x224x224，8 类，预处理 BGR→RGB / bilinear / ImageNet 归一化（SHA256d2581e8c…71cc0c，与包内 manifest 一致）。manifest.json：类别顺序、预处理、拒识阈值、目标平台、SHA256、训练评估血缘；release_status = evaluation_only，gate_met = false。release_summary.json/release_report.md：PC 端评估证据。engine/：目标板上由trtexec生成的 FP16 引擎目录（不会随仓库提供，TensorRT 引擎与 JetPack/GPU 绑定）。
cd Jetson
export PYTHONPATH="$PWD/src"
python -m rockid_jetson.cli selfcheck
python -m rockid_jetson.cli verify-package --package models/packages/v81_student_evaluation
python -m rockid_jetson.cli run --package models/packages/v81_student_evaluation \
--input fixtures/v8_smoke.jpg --db data/rockid.db --device onnxruntime
python -m rockid_jetson.cli export --db data/rockid.db --out data/exports
python -m pytest tests/ -q已验证项：包完整性/篡改检测、真实 JPEG 推理、三档置信度与低置信度拒识（进入 review）、SQLite WAL 归档、CSV/JSON 导出、输入张量契约。Jetson 主机侧测试 5 项通过，PC 端回归 68 项通过。
cd Jetson
bash scripts/install.sh
bash scripts/check_environment.sh
bash scripts/build_engine.sh models/packages/v81_student_evaluation
bash scripts/benchmark_tensorrt.sh models/packages/v81_student_evaluation <nvpmodel-id>引擎必须在目标板（Jetson Orin NX Super 8GB，JetPack 6.x）本地构建。尚未验证：TensorRT 引擎加载、CSI 相机链路、延迟、功耗与热行为——这些结论只能来自真机数据，详见 Jetson/docs/deployment_report.md。
为满足 GitHub 单文件 100MB 限制并避免泄露原始数据，做了如下裁剪：
| 处理 | 内容 | 体积 |
|---|---|---|
| 收录 | PC_Project/ 全部代码、配置、文档、模型注册表、ONNX/INT8 导出、outputs/ 指标与评估证据 |
≈322MB |
| 收录 | Jetson/ 完整部署端（运行时、模型包、脚本、测试、文档） |
≈17MB |
| 排除 | PC_Project/data/（原始与派生数据集、切分、特征缓存） |
≈5.4GB |
| 排除 | 34 个 114MB 级训练中间 checkpoint（outputs/v7、outputs/v61 的 fold_*，outputs/v8/candidate_teacher）——超出 GitHub 单文件上限 |
≈3.9GB |
| 排除 | outputs/v8/smoke_* 冒烟测试产物、__pycache__ / .pytest_cache、.agent/ 过程记录、Jetson data/ 运行期数据库 |
— |
被排除项不影响结果可读性：所有指标 JSON/CSV、OOF 预测、选型证据、报告与图表均已收录；如需复算，可从数据规格文档重建数据与 checkpoint。
PC 端：PC_Project/README.md（版本结论）、docs/project_summary.md、docs/data_spec.md、docs/feature_spec.md、docs/training_spec.md、docs/v3_training_report.md、docs/v4_pc_training_report.md、docs/v5_swin_training_report.md、docs/v7_multiscale_rl_oof_report.md、docs/v7_multiscale_rl_algorithm_report.pdf、docs/v8_training_report.md。
Jetson 端：Jetson/README.md、Jetson/docs/deployment.md、Jetson/docs/deployment_report.md、Jetson/models/packages/v81_student_evaluation/release_report.md。
MIT License，见 LICENSE。