Bài tập lớn: Inside Airbnb

Đây là tệp bắt buộc ở gốc GitHub repo, cần cập nhật suốt kì. Khai báo đầy đủ không bị trừ điểm. Giấu hoặc khai man là vi phạm chính sách AI.

# AI_USAGE.md
## Công cụ đã dùng (vào việc gì)
## Prompt then chốt (5-10): bước nào, vào tệp nào
## AI sai ở đâu (ví dụ thật)
## Nhóm kiểm chứng thế nào

Môi trường chạy và thư viện

• Python 3; thư viện tự chọn (không bắt buộc pandas), miễn giải thích và kiểm chứng được.
• .python-version: một dòng, phiên bản Python đã chạy thử (3.x.y).
• requirements.txt ghim == đủ để chạy quy trình (hoặc lockfile tương đương).
• README.md: cách cài, lệnh chạy, tên biến môi trường chứa khoá API, tệp kết quả để đối chiếu.
• Tự kiểm trước khi nộp: clone vào thư mục mới, dựng môi trường theo README, chạy một lệnh, tạo lại được số liệu và hình trong báo cáo.

Cấu trúc GitHub repo yêu cầu

.
├── configs/
│   └── <city>.yaml           # mỗi thành phố một tệp: dataRoot, danh sách mốc chụp, tham số QA/KPI/LLM
├── data/
│   ├── raw/                  # dữ liệu thô: KHÔNG commit (gitignore), do script tải sinh ra
│   ├── processed/            # dữ liệu sạch, kpi_*.csv, kết quả LLM đã lưu (commit nếu <50 MB)
│   └── samples/              # mẫu nhỏ để test nhanh + tệp ≥100 nhãn tay (review_id, nhãn)
├── src/                      # mã nguồn quy trình, tách mô-đun (gợi ý):
│   ├── download.py           #   tải + kiểm toàn vẹn
│   ├── qa.py                 #   làm sạch + bộ quy tắc QA, xuất qa_report.csv
│   ├── kpi.py                #   tính KPI
│   ├── llm.py                #   trích xuất bằng LLM (có cache, --skip-llm)
│   ├── baseline.py           #   phương pháp đối chứng không LLM
│   ├── evaluate.py           #   chấm LLM vs đối chứng trên nhãn tay
│   └── viz.py                #   sinh hình vào figures/
├── figures/                  # hình sinh tự động từ quy trình
├── reports/                  # report.pdf, qa_report.csv, từ điển dữ liệu
├── notebooks/                # notebook khám phá (nếu có), không phải quy trình chính
├── run_pipeline.py           # (hoặc Makefile) một lệnh gọi các mô-đun theo thứ tự
├── .python-version           # một dòng: phiên bản Python đã kiểm thử (3.x.y)
├── .env.example              # tên biến môi trường cho khoá API (KHÔNG chứa khoá thật)
├── .gitignore                # loại data/raw/, .venv/, .env và mọi tệp chứa khoá
├── AI_USAGE.md               # khai báo AI (bắt buộc)
├── README.md                 # tham chiếu .python-version; môi trường, cài đặt, cách chạy/chấm lại
└── requirements.txt          # thư viện ghim phiên bản (hoặc bộ tệp lockfile tương đương)

Ví dụ configs/<city>.yaml

Giá trị dưới đây là minh hoạ.

city: santiago
data_root: chile/rm/santiago      # dựng URL: data.insideairbnb.com/<data_root>/<mốc>/...
currency: CLP
snapshots: [2025-09-27, 2025-12-29, 2026-03-30, 2026-06-29]

qa:
  price_max_clp: 5000000          # ngưỡng ngoại lai giá
  min_nights_cap: 365
  dedupe_keys: [id, last_scraped]

kpi:
  area_col: neighbourhood_cleansed

llm:
  provider: gemini                # model tuỳ chọn
  sample_size: 3000               # nhóm giải thích cỡ mẫu
  aspects: [vị trí, sạch sẽ, chủ nhà, giá trị, tiện nghi, độ ồn, an toàn]
  cache: data/processed/llm_cache.jsonl

seed: 42

Vấn đáp: hỏi riêng từng thành viên

• Mỗi nhóm khoảng 20 phút, không có phần trình bày: vào thẳng hỏi riêng từng người (mở ngẫu nhiên bất kỳ đoạn mã hoặc số liệu trong sản phẩm mà nhóm nộp).
• Điểm nhóm là trần; vấn đáp điều chỉnh điểm từng người. Mỗi thành viên chịu trách nhiệm cho toàn bộ sản phẩm: không giải thích được phần được hỏi thì cá nhân đó bị trừ điểm, dù phần đó do người khác trong nhóm viết.
• Dùng AI lúc vấn đáp là gian lận (chế độ 🚫 đóng).