Một sổ tay Jupyter dùng được cho nghiên cứu là sổ tay mà ai cũng có thể bấm khởi động lại nhân rồi chạy toàn bộ ô từ trên xuống và nhận đúng kết quả đã báo cáo. Muốn vậy, giữ thứ tự ô tuyến tính, tách hàm dùng lại ra tệp .py, xoá đầu ra trước khi chia sẻ và kiểm bằng lệnh chạy tự động.
Jupyter cho phép chạy ô theo bất kỳ thứ tự nào, sửa một ô ở giữa rồi chạy lại riêng nó. Đó là điểm mạnh khi thăm dò dữ liệu, và cũng là lý do nhiều sổ tay chỉ chạy được trên máy tác giả, trong đúng phiên làm việc hôm đó. Bài này nói các thói quen giữ cho sổ tay sạch, theo thứ tự nên tập.
Vì sao sổ tay hay “chạy được trên máy mình” mà không chạy lại được?
Mỗi ô khi chạy làm thay đổi trạng thái của nhân (kernel): biến, bảng, hàm đã định nghĩa. Số trong ngoặc vuông cạnh ô là thứ tự chạy thật. Nếu số nhảy lung tung, ví dụ ô thứ ba mang số 41 còn ô thứ tư mang số 12, kết quả bạn đang nhìn là sản phẩm của một chuỗi chạy không ai lặp lại được.
Ba tình huống điển hình: một ô định nghĩa biến đã bị xoá nhưng biến vẫn còn trong bộ nhớ; một ô phía dưới sửa bảng dữ liệu rồi ô phía trên được chạy lại trên bảng đã sửa; một hàm được sửa trong tệp ngoài nhưng nhân vẫn giữ bản cũ. Không tình huống nào báo lỗi. Chỉ đến khi người hướng dẫn mở sổ tay và chạy từ đầu, mọi thứ mới vỡ.
Thói quen số một: khởi động lại và chạy toàn bộ
Trước mỗi lần lưu bản quan trọng, gửi cho người khác, hay lấy số đưa vào bản thảo:
- Trong JupyterLab, chọn
Kernel → Restart Kernel and Run All Cells…. Trong VS Code, bấmRestartrồiRun Alltrên thanh công cụ sổ tay. - Đợi chạy hết, xem số thứ tự ô có tăng đều từ 1 không và có ô nào báo lỗi không.
- So các con số then chốt với những gì bạn đã ghi trong bản thảo.
- Chỉ khi chạy sạch mới lưu và chia sẻ.
Kiểm tương tự từ dòng lệnh, không cần mở giao diện: jupyter nbconvert --to notebook --execute --inplace phan-tich.ipynb. Lệnh này chạy toàn bộ sổ tay trong một nhân mới và dừng ở ô lỗi đầu tiên. Đặt nó trong tệp hướng dẫn của dự án để người khác cũng biết cách kiểm.
Cấu trúc một sổ tay dễ đọc
Ô đầu: nhập thư viện và tham số
Gom mọi lệnh import, đường dẫn dữ liệu, hạt giống ngẫu nhiên (rng = np.random.default_rng(2024)) và tham số như ngưỡng lọc vào một hai ô đầu. Người đọc thấy ngay sổ tay cần gì, bạn đổi tham số ở một chỗ.
Ô Markdown làm đề mục
Chèn ô Markdown trước mỗi phần: đọc dữ liệu, làm sạch, mô tả, mô hình, hình. Mỗi ô ghi một hai câu “bước này làm gì, vì sao”. Thanh mục lục của JupyterLab và VS Code dựng từ các đề mục này.
Một ô, một việc
Ô dài hàng trăm dòng khó dò lỗi; ô một dòng thì vụn. Một ô nên làm trọn một việc có thể đặt tên, và kết thúc bằng một đầu ra để soát, ví dụ df.shape hay vài dòng đầu bảng.
Đường dẫn tương đối
Đọc dữ liệu bằng đường dẫn tính từ thư mục dự án, ví dụ qua pathlib.Path('du-lieu') / 'tho' / 'khaosat.csv', không ghi đường dẫn tuyệt đối của máy mình.
Tách hàm ra tệp .py khi nào?
Khi một đoạn mã được chép sang ô thứ hai, hoặc được dùng ở sổ tay khác, đã đến lúc chuyển nó thành hàm trong một tệp .py cạnh sổ tay, ví dụ tien_ich.py với hàm lam_sach_khao_sat(df). Sổ tay gọi from tien_ich import lam_sach_khao_sat. Hàm trong tệp dễ kiểm thử, dễ xem thay đổi bằng Git, và không bị lẫn trạng thái giữa các ô.
Vướng mắc quen thuộc: sửa tệp .py xong, sổ tay vẫn chạy bản cũ vì Python đã nạp mô-đun một lần. Thêm hai dòng ở đầu sổ tay: %load_ext autoreload và %autoreload 2, nhân sẽ nạp lại mô-đun mỗi khi chạy ô. Dù vậy, trước khi chốt kết quả vẫn khởi động lại và chạy toàn bộ.
Nhân nào đang chạy sổ tay của bạn?
Một dự án, một môi trường
Sổ tay chạy trên một nhân, và nhân đó gắn với một môi trường Python cụ thể. Khi máy có nhiều bản Python, Anaconda cài song song với Python hệ thống, hay mỗi dự án một môi trường ảo, rất dễ xảy ra chuyện cài thư viện vào môi trường này còn sổ tay chạy ở môi trường kia. Dấu hiệu quen: vừa cài xong, chạy import vẫn báo ModuleNotFoundError.
Cách xử lý gọn
Tạo một môi trường riêng cho mỗi đề tài, bằng python -m venv .venv hoặc conda create. Trong môi trường đó, cài ipykernel rồi đăng ký nhân với một tên dễ nhận ra: python -m ipykernel install --user --name de-tai-khao-sat. Khi mở sổ tay, chọn đúng nhân có tên đó ở góc trên bên phải. Nếu cần cài thêm từ trong sổ tay, dùng lệnh ma thuật %pip install ten-goi: lệnh này cài vào đúng môi trường của nhân đang chạy, khác với !pip có thể trỏ sang một Python khác.
Ghi lại môi trường
Khi kết quả đã ổn, xuất danh sách thư viện ra requirements.txt bằng pip freeze hoặc environment.yml bằng conda env export. Người nhận dựng lại môi trường từ tệp này trước khi chạy sổ tay.
Ngẫu nhiên và các bước chạy lâu
Kết quả có yếu tố ngẫu nhiên, như chia mẫu huấn luyện và kiểm tra, bootstrap, mô phỏng, phải đặt hạt giống ở đầu sổ tay và truyền nó vào mọi hàm có tham số random_state hay seed. Không có hạt giống, khởi động lại và chạy toàn bộ sẽ cho số hơi khác mỗi lần, và bạn không biết chênh lệch đó do mã hay do may rủi.
Bước chạy hàng giờ, như huấn luyện mô hình hay gọi dịch vụ ngoài, không nên nằm giữa sổ tay phân tích. Tách thành kịch bản riêng ghi kết quả ra tệp; sổ tay chỉ đọc tệp kết quả. Như vậy “chạy lại toàn bộ” sổ tay vẫn chỉ mất vài phút, và bạn có lý do để làm việc đó thường xuyên.
Chia sẻ sổ tay: xoá đầu ra hay giữ?
Đầu ra trong sổ tay gồm bảng, hình, thông báo, có khi cả dữ liệu cá nhân in ra lúc soát. Chọn theo mục đích:
| Mục đích | Nên làm | Lệnh |
|---|---|---|
| Đưa lên kho mã, Git | Xoá đầu ra, chỉ giữ mã và chữ | jupyter nbconvert --clear-output --inplace phan-tich.ipynb |
| Tự động xoá đầu ra mỗi lần commit | Cài bộ lọc Git | nbstripout --install trong thư mục kho |
| Gửi người hướng dẫn đọc kết quả | Xuất HTML sau khi chạy sạch | jupyter nbconvert --to html phan-tich.ipynb |
| Lấy mã ra tệp chạy được | Xuất kịch bản Python | jupyter nbconvert --to script phan-tich.ipynb |
| Nộp kèm bài báo, lưu trữ | Nộp cả bản có đầu ra và bản xoá đầu ra, kèm tệp phiên bản gói | pip freeze > requirements.txt hoặc tệp môi trường conda |
Trước khi chia sẻ bản có đầu ra, cuộn lại toàn bộ một lượt: ô nào in ra họ tên, số điện thoại, địa chỉ thư của người tham gia thì xoá đầu ra của ô đó và sửa mã để chỉ in số đếm.
Từ sổ tay sang báo cáo
Sổ tay thăm dò và báo cáo cuối là hai việc khác nhau. Khi phân tích đã ổn, có hai hướng. Hướng thứ nhất: dọn sổ tay thành bản báo cáo, chỉ giữ ô cần thiết, rồi xuất HTML. Hướng thứ hai: dùng Quarto, công cụ đọc được tệp .ipynb và dựng thành HTML, Word hoặc PDF; lệnh quarto render phan-tich.ipynb --execute chạy lại toàn bộ ô rồi mới dựng, nên báo cáo luôn khớp với mã. Không có --execute, Quarto dùng đầu ra đang lưu sẵn trong sổ tay.
Nếu cần xem thay đổi trong Git cho dễ, Jupytext ghép mỗi sổ tay với một tệp .py dạng chữ thuần; thay đổi hiện ra rõ ràng, không lẫn siêu dữ liệu của sổ tay.
Lỗi hay gặp và bảng soát trước khi gửi
Rà nhanh trước khi bấm gửi:
- Số thứ tự ô tăng đều từ 1, không có ô báo lỗi.
- Không có đường dẫn tuyệt đối, không có mật khẩu hay khoá API trong mã.
- Không có ô bị “tắt” bằng cách biến thành Markdown mà vẫn cần cho kết quả.
- Có tệp phiên bản gói đi kèm.
- Hình trong bản thảo được sinh ra từ đúng sổ tay này, không phải từ một bản cũ.
- Việc KHÔNG cần làm: viết lại toàn bộ sổ tay thành kịch bản
.py. Sổ tay sạch, chạy lại được, đã đủ cho phần lớn luận văn và bài báo.
Câu hỏi thường gặp
JupyterLab và Jupyter Notebook khác nhau thế nào?
Cùng định dạng tệp .ipynb và cùng nhân. JupyterLab là giao diện nhiều khung, có trình duyệt tệp, mục lục và terminal; Notebook là giao diện gọn hơn. Sổ tay tạo ở bên này mở được ở bên kia.
Có nên dùng VS Code thay JupyterLab không?
Tuỳ thói quen. VS Code mở và chạy được .ipynb, mạnh về gợi ý mã và Git. Nguyên tắc sổ tay sạch giống hệt nhau ở cả hai: khởi động lại, chạy toàn bộ, kiểm kết quả.
Sổ tay quá nặng vì nhiều hình thì làm sao?
Xoá đầu ra trước khi đưa lên Git và lưu hình ra thư mục riêng bằng savefig. Sổ tay chỉ cần mã sinh hình; hình xuất ra có thể tạo lại bất cứ lúc nào.
Làm sao chạy cùng một sổ tay với nhiều tham số?
Công cụ papermill cho phép đánh dấu một ô tham số rồi chạy sổ tay nhiều lần với giá trị khác nhau từ dòng lệnh, mỗi lần lưu ra một sổ tay kết quả riêng.
Có cần ghi phiên bản Python không?
Có. Ghi phiên bản Python và phiên bản các thư viện chính trong tệp hướng dẫn hoặc ô cuối sổ tay. Cùng một hàm có thể đổi hành vi giữa hai phiên bản thư viện.
Sổ tay có dữ liệu cá nhân thì chia sẻ thế nào?
Chia sẻ bản đã xoá đầu ra, dữ liệu thật để ngoài thư mục dự án và chỉ cấp theo quy định của đề tài. Nếu cần người khác chạy thử, kèm một bộ dữ liệu giả cùng cấu trúc.
