remote-sensing/SYSTEM_UPDATE_GUIDE.md

HƯỚNG DẪN SỬ DỤNG HỆ THỐNG MỚI

Tổng quan

Hệ thống đã được cập nhật để chuẩn hóa việc trích xuất features giữa training và prediction, sử dụng module feature_extractor.py.

Các thành phần mới

1. feature_extractor.py

Module chuẩn hóa việc trích xuất features với 3 modes:

• simple: 3 features cơ bản

  • NDVI_mean
  • VH_db_mean
  • VV_db_mean

• temporal: 39+ features time-series

  • NDVI_t1, NDVI_t2, ..., NDVI_tn
  • NDWI_t1, NDWI_t2, ..., NDWI_tn
  • NDBI_t1, NDBI_t2, ..., NDBI_tn
  • VH_db_mean, VV_db_mean, VH_VV_ratio

• extended: 15 features với statistics

  • NDVI_mean, NDVI_std, NDVI_min, NDVI_max
  • NDWI_mean, NDWI_std, NDWI_min, NDWI_max
  • NDBI_mean, NDBI_std, NDBI_min, NDBI_max
  • VH_db_mean, VV_db_mean, VH_VV_ratio

2. train_module.py (Đã cập nhật)

• Thêm tham số feature_mode (default='simple')
• Sử dụng FeatureExtractor để extract features
• Lưu feature_mode vào metadata của model
• Load đúng bands Sentinel-2 theo feature mode

3. api_server.py (Cần cập nhật thủ công)

File này quá lớn để tự động replace. Cần thay thế hàm run_prediction bằng version mới trong run_prediction_new.py.

Cách sử dụng

Training với feature modes khác nhau

1. Simple Mode (Mặc định - Nhanh nhất)

from train_module import train_model

result = train_model(
    bbox=[105.6, 9.3, 106.2, 9.8],
    time_range='2023-03-01/2023-05-31',
    max_scenes=12,
    feature_mode='simple',  # 3 features
    model_type='xgboost',
    use_cache=True
)

2. Temporal Mode (Cho model_odc.joblib)

result = train_model(
    bbox=[105.6, 9.3, 106.2, 9.8],
    time_range='2023-03-01/2023-05-31',
    max_scenes=12,
    feature_mode='temporal',  # 39+ features
    model_type='random_forest',
    use_cache=True
)

3. Extended Mode (Cân bằng speed/accuracy)

result = train_model(
    bbox=[105.6, 9.3, 106.2, 9.8],
    time_range='2023-03-01/2023-05-31',
    max_scenes=12,
    feature_mode='extended',  # 15 features
    model_type='xgboost',
    use_cache=True
)

Prediction

Prediction sẽ tự động detect feature_mode từ model metadata và sử dụng FeatureExtractor tương ứng.

# Prediction sẽ tự động:
# 1. Load model metadata
# 2. Đọc feature_mode từ metadata
# 3. Khởi tạo FeatureExtractor với mode tương ứng
# 4. Extract features giống như training
# 5. Predict

Tạo metadata cho model_odc.joblib

Model hiện tại model_odc.joblib được train với 39 features (temporal mode) nhưng chưa có metadata. Tạo metadata:

python create_odc_metadata.py

File này sẽ tạo model_train/model_odc_info.json với:

• n_features: 39
• feature_mode: "temporal"
• features: list of 39 feature names

So sánh các modes

Feature Mode	N Features	Training Time	Accuracy	Use Case
simple	3	Nhanh nhất	Trung bình	Test nhanh, dataset nhỏ
extended	15	Trung bình	Tốt	Cân bằng speed/accuracy
temporal	39+	Chậm nhất	Tốt nhất	Production, dataset lớn

Lưu ý quan trọng

1. Bands được load

• simple: B04, B08, SCL
• temporal/extended: B02, B03, B04, B08, B11, SCL

2. Cache compatibility

Cache cũ từ trước khi cập nhật sẽ KHÔNG tương thích vì:

• Không có field feature_mode
• Features có thể không match

Giải pháp: Xóa cache cũ

rm -rf dataset_cache/*

3. Model compatibility

• Models cũ (trước cập nhật) sẽ được coi là feature_mode='simple' nếu không có metadata
• Models mới sẽ có field feature_mode trong metadata

Workflow đề xuất

Bước 1: Xóa cache cũ

rm -rf dataset_cache/*

Bước 2: Tạo metadata cho model_odc.joblib

python create_odc_metadata.py

Bước 3: Cập nhật api_server.py

Thay thế hàm run_prediction (line 834-1295) với nội dung từ run_prediction_new.py

Bước 4: Test training với simple mode

# Qua web interface hoặc
python test_training_simple.py

Bước 5: Test prediction với model vừa train

# Qua web interface
# Model sẽ tự động detect feature_mode và extract đúng features

Bước 6: Test với temporal mode (nếu cần accuracy cao)

python test_training_temporal.py

Troubleshooting

Lỗi: "feature_mode not found in metadata"

• Model cũ chưa có metadata
• Giải pháp: Hệ thống tự động fallback về 'simple' mode

Lỗi: "Expected X features but got Y"

• Feature extraction không match với training
• Giải pháp: Kiểm tra model metadata, đảm bảo feature_mode đúng

Lỗi: "B11 band not found"

• Sentinel-2 scene thiếu SWIR band
• Giải pháp: Hệ thống tự động fallback về B02

API Changes

TrainingConfig (Mới)

class TrainingConfig(BaseModel):
    # ... existing fields ...
    feature_mode: str = "simple"  # NEW: 'simple', 'temporal', 'extended'

Model Metadata (Mới)

{
  "feature_mode": "temporal",
  "features": ["NDVI_t1", "NDVI_t2", ...],
  "n_features": 39,
  ...
}

File Structure

/home/x79/remote-sensing/
├── feature_extractor.py         # NEW: Core feature extraction module
├── train_module.py              # UPDATED: Uses FeatureExtractor
├── api_server.py                # NEEDS UPDATE: run_prediction function
├── run_prediction_new.py        # NEW: Updated run_prediction code
├── create_odc_metadata.py       # NEW: Generate metadata for model_odc.joblib
├── SYSTEM_UPDATE_GUIDE.md       # This file
└── model_train/
    ├── model_odc.joblib         # Existing 39-feature model
    ├── model_odc_info.json      # TO CREATE: Metadata file
    └── ...

Next Steps

1. ✅ Created feature_extractor.py
2. ✅ Updated train_module.py
3. ⏳ Update api_server.py (manual)
4. ⏳ Create metadata for model_odc.joblib
5. ⏳ Test full workflow

Contact & Support

Nếu gặp vấn đề, kiểm tra:

1. feature_extractor.py có import được không
2. Model metadata có field feature_mode chưa
3. Cache đã được xóa chưa
4. api_server.py đã cập nhật run_prediction chưa