Cách chạy project Python trên Kaggle bằng CLI với KRun

Khi làm một project AI, đôi khi mình viết code trên máy nhưng lại muốn chạy phần Training bằng GPU của Kaggle. Nếu project đã có nhiều module, file cấu hình và dependency, việc chuyển mọi thứ sang một notebook mới có thể khá mất công.

Mình xây KRun để giải quyết tình huống đó. Đây là một CLI cho phép gửi project Python lên Kaggle từ terminal: KRun đóng gói các file cần thiết, tạo job, theo dõi log và tải kết quả về máy. Bạn có thể chạy script, Python module hoặc notebook mà không cần đổi tên file thành main.py hay bắt buộc tạo krun.yaml.

I. KRun hoạt động như thế nào?

Có thể hình dung quy trình của KRun như sau:

Project trên máy → đóng gói → chạy trên Kaggle → xem log → tải output về máy.

KRun chạy trên máy của bạn, còn code của project chạy trong môi trường Kaggle. Vì vậy, máy cá nhân không cần có GPU. Workflow cài đặt chính hiện tại cũng không yêu cầu Docker.

Điểm mình muốn giữ lại là cấu trúc project đang có. Ví dụ, nếu entrypoint của bạn là train.py và nó import code từ các module khác, bạn có thể chỉ định thư mục gốc bằng --project để KRun biết cần đưa những file nào lên Kaggle.

II. Cài đặt và kết nối tài khoản Kaggle

Bạn cần có tài khoản Kaggle, Git và uv. Theo README hiện tại, KRun yêu cầu Python 3.11 trở lên; uv có thể chuẩn bị phiên bản Python phù hợp cho CLI.

Hiện tại, README hướng dẫn cài trực tiếp từ repository:

uv tool install --python 3.12 git+https://github.com/nhminh107/KRun-PyProjectOnKaggle.git

Sau đó kiểm tra CLI và đăng nhập:

krun --version
krun login
krun doctor

Lệnh login sẽ đưa ra một đường dẫn để bạn xác thực tài khoản Kaggle trên trình duyệt. Nếu máy đã có thông tin đăng nhập Kaggle trong ~/.kaggle, KRun có thể sử dụng lại.

III. Thử một job nhỏ trước

Repo có sẵn demo chạy bằng CPU, không cần tải model hay chuẩn bị dataset:

krun demo sales-report

Sau khi job hoàn thành, KRun lưu kết quả trong thư mục .krun/jobs/<job-id>/ của project demo. Đây là cách khá nhanh để kiểm tra toàn bộ quá trình từ đăng nhập, gửi job cho tới tải output.

Nếu chỉ muốn xem KRun sẽ chuẩn bị những gì trước khi gửi lên Kaggle, bạn có thể dùng --dry-run:

krun demo sales-report --dry-run

--dry-run giúp kiểm tra file và cấu hình sẽ được sử dụng; nó không chạy code trên Kaggle.

IV. Chạy project Python của mình

Giả sử project của bạn có file train.py, lệnh chạy với GPU T4 có thể viết như sau:

krun run /path/to/my-project/train.py \
--project /path/to/my-project \
--gpu T4 \
--internet

Ở đây, --project xác định thư mục gốc chứa code, các module nội bộ và những input mà chương trình cần. --gpu T4 yêu cầu GPU cho job; --internet hữu ích khi job cần cài dependency hoặc tải dữ liệu, model từ bên ngoài.

Trước khi gửi một project thật, mình khuyên nên xem danh sách file sẽ được đóng gói:

krun run /path/to/my-project/train.py \
--project /path/to/my-project \
--gpu T4 \
--internet \
--dry-run

KRun cũng hỗ trợ chạy module với -m và chạy file .ipynb. Vì vậy, bạn có thể chọn entrypoint phù hợp với project thay vì sửa cấu trúc code chỉ để đưa nó lên Kaggle.

V. Dependency và kết quả được xử lý ra sao?

KRun có thể đọc dependency từ requirements.txt hoặc pyproject.toml. Nó không tự đoán tên package từ các lệnh import và cũng không sao chép nguyên môi trường Conda hoặc venv trên máy lên Kaggle. Với project có nhiều file khai báo dependency, bạn có thể chỉ định file cần dùng bằng --requirements.

Để xem trạng thái và log của job:

krun status --project /path/to/my-project
krun logs --project /path/to/my-project

Mặc định, KRun thu thập các file mà chương trình ghi vào thư mục outputs/ của project. Bạn cũng có thể chọn đường dẫn khác bằng --output. Cần lưu ý rằng tùy chọn này chỉ chọn file để tải về; code của bạn vẫn phải tự ghi kết quả vào đúng vị trí đó.

VI. Những giới hạn cần biết

KRun giúp đơn giản hóa việc gửi và theo dõi job, nhưng nó không thay đổi giới hạn của Kaggle. GPU có dùng được hay không vẫn phụ thuộc vào tài khoản, quota và tình trạng tài nguyên tại thời điểm chạy. Yêu cầu --gpu T4 cũng không tự khiến một chương trình vốn chỉ chạy CPU sử dụng GPU; phần code Training vẫn cần hỗ trợ thiết bị đó.

KRun hiện giới hạn phần project tải lên ở 20 MB trước khi nén. Với dữ liệu lớn hơn, hướng phù hợp là gắn một Kaggle Dataset đã có và đọc dữ liệu từ /kaggle/input/. Những workload cần giao diện desktop, nhập liệu tương tác hoặc chạy server lâu dài cũng không phù hợp với kiểu job này.

Kết luận

Nếu bạn đã có một project Python trên máy và muốn chạy nó trên Kaggle mà vẫn giữ cấu trúc code hiện tại, KRun là một cách để bắt đầu từ terminal. Mình nghĩ điểm hữu ích nhất của công cụ không nằm ở một lệnh run riêng lẻ, mà ở cả vòng lặp: kiểm tra project, gửi job, đọc log và lấy kết quả về.

Mã nguồn, ví dụ và hướng dẫn chi tiết nằm tại KRun-PyProjectOnKaggle trên GitHub.