Hướng dẫn dùng AI

Jupyter Notebook hay tệp .py: dự án AI nên viết ở đâu

Học AI, bạn sẽ gặp Jupyter Notebook ở khắp nơi: giáo trình, Google Colab, bài mẫu trên GitHub. Nhưng khi dự án lớn dần, nhiều người chuyển sang viết tệp .py bình thường. Vậy viết ở đâu thì đúng? Bài này đọc mô tả định dạng notebook của Jupyter, tài liệu VS Code và Python ngày 12/11/2026 để giải thích notebook thực chất lưu những gì, vì sao nó dễ gây lỗi khó thấy, khi nào nên dùng mỗi cách, và kèm đoạn Python soát một notebook rồi chuyển nó thành tệp .py.

Ý chính
  • Tệp .ipynb là JSON: mỗi ô code lưu code, các đầu ra và một số thứ tự chạy; vì lưu cả đầu ra, notebook có thể mang theo dữ liệu, kể cả khóa API, khi bạn chia sẻ.
  • Notebook giữ biến trong bộ nhớ giữa các ô, nên chạy ô không theo thứ tự có thể cho kết quả mà chạy lại từ đầu không ra được.
  • Notebook hợp để khám phá dữ liệu, thử ý, trình bày; tệp .py hợp với code dùng lại, chạy tự động, quản lý bằng Git.
  • VS Code cho chia tệp .py thành ô bằng dấu # %% để chạy từng ô, và xuất notebook ra tệp .py; đoạn Python trong bài làm việc đó và soát thứ tự chạy.

Code trong bài là Python, chỉ dùng thư viện chuẩn; phần kiểm dùng thêm thư viện nbformat bản 5.11.1. Notebook mẫu là giả lập.

Notebook thực chất là gì

Trang mô tả định dạng của Jupyter ghi: định dạng notebook chính thức được định nghĩa bằng một lược đồ JSON, và các công cụ Jupyter dùng lược đồ đó để kiểm tra notebook có hợp lệ không. Mỗi ô code chứa mã nguồn, một danh sách đầu ra sinh ra khi chạy ô đó, và một số thứ tự chạy execution_count, là số nguyên hoặc null nếu ô chưa chạy. Ô văn bản thì chứa markdown.

Hai hệ quả quan trọng. Thứ nhất, notebook lưu cả đầu ra: bảng dữ liệu bạn in ra, biểu đồ, thông báo lỗi. Mở notebook là thấy kết quả lần chạy trước mà không cần chạy lại, rất tiện để trình bày; nhưng cũng có nghĩa dữ liệu nằm sẵn trong tệp. Bài giữ khóa API an toàn đã chỉ ra notebook là chỗ khóa hay lọt nhất, vì một lần in biến chứa khóa là khóa nằm luôn trong tệp .ipynb. Thứ hai, vì là JSON, notebook khó so sánh thay đổi bằng Git; tài liệu VS Code cũng ghi việc so từng dòng của notebook rất khó đọc, nên VS Code làm riêng một trình so sánh cho notebook.

Vì sao notebook dễ gây lỗi khó thấy

Mọi ô trong một notebook dùng chung một tiến trình Python, nên biến tạo ở ô này vẫn sống khi bạn chạy ô khác, theo bất kỳ thứ tự nào. Bạn sửa ô 2, chạy lại ô 5, quên chạy ô 3; kết quả trên màn hình đúng với trạng thái bộ nhớ lúc đó, nhưng không ai, kể cả bạn ngày mai, chạy lại được ra đúng như vậy từ trên xuống. Số thứ tự chạy cạnh mỗi ô là manh mối: nếu số không tăng dần từ trên xuống, notebook đã được chạy lộn thứ tự.

Cách phòng đơn giản: trước khi nộp hay chia sẻ, khởi động lại và chạy tất cả các ô từ đầu. Nếu có ô lỗi, đó là lỗi thật mà trước đó bị che. Bài học AI trên Colab cũng khuyên làm vậy với notebook trên Colab.

Tệp .py làm tốt việc gì

Tệp .py luôn chạy từ trên xuống, mỗi lần chạy là một tiến trình mới, nên kết quả lặp lại được. Bạn import hàm từ tệp này sang tệp khác, viết kiểm thử, chạy bằng một lệnh trong terminal hay theo lịch, và Git so thay đổi từng dòng rõ ràng.

Tài liệu Python giải thích cách để một tệp vừa import được vừa chạy được: khi một mô-đun được import, biến __name__ mang tên mô-đun; khi tệp được chạy trực tiếp, __name__ bằng '__main__'. Đặt phần chạy thử trong if __name__ == "__main__": thì import tệp sẽ không tự chạy phần đó. Đoạn code trong bài này cũng viết theo cách đó.

Notebook hay tệp .py Theo tài liệu Jupyter, VS Code, Python, đọc 12/11/2026 1. Khám pháNotebook:thử ý, xem biểu đồ 2. Chạy lại hếtTừ trên xuống,không lỗi 3. Sang tệp .pyHàm đã ổn,ô # %% 4. Trước khi đẩyXóa đầu ranotebook Notebook để thử, tệp .py để giữ
Notebook hay tệp .py 1. Khám pháNotebook:thử ý, xem biểu đồ 2. Chạy lại hếtTừ trên xuống,không lỗi 3. Sang tệp .pyHàm đã ổn,ô # %% 4. Trước khi đẩyXóa đầu ranotebook Notebook để thử, tệp .py để giữ
Hình 1. Một dự án AI đi từ notebook sang tệp .py: khám phá trong notebook, chạy lại hết từ trên xuống, chuyển hàm đã ổn sang tệp .py với ô # %%, và xóa đầu ra notebook trước khi đẩy lên GitHub.

Ô # %%: nửa notebook, nửa tệp .py

Tài liệu VS Code mô tả một cách dung hòa: trong tệp .py bình thường, bạn chia ô bằng dòng chú thích # %%. Khi tiện ích Python nhận ra ô, nó hiện nút Run Cell và Debug Cell phía trên ô; Run Cell chạy riêng ô đó trong cửa sổ Python Interactive, cần môi trường có cài ipykernel. Tệp vẫn là .py, Git vẫn so được từng dòng, chạy cả tệp bằng python ten_tep.py vẫn được, nhưng khi khám phá bạn chạy từng ô như notebook. VS Code còn cho xuất một notebook ra tệp Python từ thanh công cụ.

Soát notebook và chuyển sang .py

Đoạn Python dưới đây đọc một notebook, báo ba loại vấn đề: ô chạy không theo thứ tự từ trên xuống, ô chưa chạy, và ô còn lưu đầu ra; rồi xuất notebook thành tệp .py, mỗi ô code là một ô # %%, ô markdown thành chú thích.

"""Đọc một notebook Jupyter (.ipynb), soát vài lỗi hay gặp, rồi chuyển thành tệp .py có ô "# %%".

Tệp .ipynb là JSON. Mỗi ô code có "source" (code), "outputs" (kết quả đã lưu) và
"execution_count" (số thứ tự lần chạy, hoặc null nếu chưa chạy).
Chương trình báo:
  - ô chạy không theo thứ tự từ trên xuống (số thứ tự chạy không tăng dần),
  - ô chưa chạy lần nào,
  - ô còn lưu đầu ra (đầu ra có thể chứa dữ liệu, thậm chí khóa API, khi đẩy lên GitHub).
Tệp .py xuất ra dùng dấu "# %%" để chia ô, kiểu mà VS Code nhận ra và cho chạy từng ô.
Notebook mẫu bên dưới là giả lập. Chỉ dùng thư viện chuẩn.
"""
import json


def nguon(o):
    s = o.get("source", "")
    return "".join(s) if isinstance(s, list) else s


def soat(nb):
    van_de, truoc = [], 0
    o_code = [o for o in nb["cells"] if o["cell_type"] == "code"]
    for i, o in enumerate(o_code, 1):
        so = o.get("execution_count")
        if so is None:
            van_de.append(f"ô code {i}: chưa chạy")
        else:
            if so <= truoc:
                van_de.append(f"ô code {i}: chạy lần thứ {so}, trước ô phía trên (lần {truoc})")
            truoc = max(truoc, so)
        if o.get("outputs"):
            van_de.append(f"ô code {i}: còn lưu {len(o['outputs'])} đầu ra")
    return van_de


def sang_py(nb):
    phan = []
    for o in nb["cells"]:
        if o["cell_type"] == "code":
            phan.append("# %%\n" + nguon(o).rstrip("\n"))
        elif o["cell_type"] == "markdown":
            dong = nguon(o).rstrip("\n").split("\n")
            phan.append("# %% [markdown]\n" + "\n".join("# " + d if d else "#" for d in dong))
    return "\n\n".join(phan) + "\n"


def o_code(so_chay, code, dau_ra=None):
    return {"cell_type": "code", "execution_count": so_chay, "metadata": {},
            "source": code, "outputs": dau_ra or []}


NB_MAU = {
    "nbformat": 4, "nbformat_minor": 5, "metadata": {},
    "cells": [
        {"cell_type": "markdown", "metadata": {}, "source": "# Dự đoán điểm\nNạp dữ liệu rồi tính trung bình."},
        o_code(3, "diem = [7, 8, 9]"),
        o_code(1, "tb = sum(diem) / len(diem)"),
        o_code(4, "print(tb)", [{"output_type": "stream", "name": "stdout", "text": "8.0\n"}]),
        o_code(None, "diem.append(10)"),
    ],
}
# Thêm id cho từng ô theo định dạng 4.5
for _i, _o in enumerate(NB_MAU["cells"]):
    _o["id"] = f"o{_i}"

if __name__ == "__main__":
    import sys
    nb = json.load(open(sys.argv[1], encoding="utf-8")) if len(sys.argv) > 1 else NB_MAU
    for v in soat(nb) or ["không thấy vấn đề"]:
        print("-", v)
    print("----- tệp .py -----")
    print(sang_py(nb), end="")

Notebook mẫu có bốn ô code với số thứ tự chạy 3, 1, 4 và chưa chạy. Kết quả: ô 2 bị báo chạy trước ô phía trên, ô 3 còn lưu một đầu ra, ô 4 chưa chạy. Tệp .py xuất ra chạy được từ trên xuống: điểm trung bình của 7, 8, 9 là 8.0. Muốn soát notebook của bạn, chạy python nb_sang_py.py ten.ipynb.

Phần kiểm đi kèm dùng thư viện nbformat, thư viện chính thức của Jupyter: kiểm notebook mẫu hợp lệ theo lược đồ, đọc lại bằng nbformat để so code, số thứ tự chạy và số đầu ra, dựng lại cùng notebook bằng các hàm của nbformat rồi so kết quả soát và tệp .py, và chạy thử tệp .py xuất ra.

Chọn theo việc

  • Khám phá một bộ dữ liệu mới, vẽ biểu đồ, thử vài mô hình: notebook.
  • Bài nộp cần trình bày cả code, kết quả và giải thích: notebook, nhưng chạy lại hết từ đầu trước khi nộp.
  • Hàm xử lý dữ liệu, huấn luyện dùng đi dùng lại: tệp .py, notebook chỉ import và gọi.
  • Chương trình chạy theo lịch, chạy trên máy chủ, có kiểm thử: tệp .py.
  • Muốn chạy từng ô mà vẫn giữ tệp .py cho Git: tệp .py với ô # %% trong VS Code.

Nhiều dự án dùng cả hai: thư mục src/ chứa tệp .py, thư mục notebooks/ chứa vài notebook ngắn để khám phá và trình bày.

Một ví dụ: dự án phân loại bình luận

Giả sử nhóm bạn làm đồ án phân loại bình luận của khách hàng thành khen hay chê. Tuần đầu, mỗi người mở một notebook để đọc dữ liệu, đếm xem có bao nhiêu bình luận mỗi loại, xem vài bình luận bị gán nhãn lạ, thử vài cách làm sạch chữ. Notebook rất hợp giai đoạn này: chạy một ô nạp dữ liệu một lần, rồi thử đi thử lại các ô phía sau mà không phải đọc lại tệp.

Sang tuần thứ hai, nhóm đã chốt được cách làm sạch chữ và cách chia dữ liệu huấn luyện, kiểm tra. Đây là lúc chuyển hai phần đó thành hai hàm trong tệp xu_ly.py, có vài dòng kiểm thử đi kèm. Mọi notebook sau đó chỉ cần import hai hàm này, nên cả nhóm dùng chung một cách làm, sửa một chỗ là mọi notebook được cập nhật. Phần huấn luyện và đánh giá cuối cùng nằm trong huan_luyen.py, chạy bằng một lệnh và ghi kết quả ra tệp, để báo cáo luôn dựa trên một lần chạy đầy đủ.

Notebook trình bày cuối cùng chỉ còn vài ô: nạp kết quả, vẽ biểu đồ, viết nhận xét. Trước khi nộp, nhóm khởi động lại và chạy hết một lần, rồi chạy đoạn Python soát ở trên để chắc không ô nào chạy lộn thứ tự.

Trước khi đẩy notebook lên GitHub

Ba việc nên làm. Khởi động lại và chạy hết từ trên xuống để chắc notebook chạy lại được. Xóa đầu ra nếu không cần trình bày kết quả, nhất là khi có in dữ liệu hay biến cấu hình; đoạn Python ở trên báo ô nào còn đầu ra. Và đặt các hàm đã ổn vào tệp .py để người khác dùng lại được mà không phải chép từ notebook.

Cẩn thận
  • Nộp notebook chạy lộn thứ tự mà không chạy lại từ đầu.
  • Đẩy notebook còn đầu ra chứa dữ liệu cá nhân hay khóa API lên GitHub.
  • Chép một hàm qua lại giữa nhiều notebook thay vì đặt trong tệp .py.
  • Viết cả dự án lớn trong một notebook dài hàng trăm ô.
  • Quên đặt phần chạy thử trong if __name__ == "__main__": khi tệp còn được import.

Câu hỏi thường gặp

Tệp .ipynb lưu những gì?

Code, đầu ra và số thứ tự chạy của từng ô, ở dạng JSON.

Vì sao notebook chạy lại thì lỗi?

Các ô dùng chung bộ nhớ; chạy lộn thứ tự để lại biến mà chạy từ đầu không có.

Chuyển notebook sang .py thế nào?

VS Code có lệnh xuất; đoạn Python trong bài xuất thành ô # %%.

Ô # %% là gì?

Dấu chia ô trong tệp .py để VS Code cho chạy từng ô như notebook.

Học tiếp

Nếu bạn muốn học Python và AI bài bản cùng giảng viên, tham khảo khóa học AI của Big-O Coding.

Muốn học bài bản cùng giảng viên?

Khóa AI – Introduction to Machine Learning: nền tảng Máy học từ thuật toán cơ bản đến Neural Networks và LLM, học bằng Python. Học thử buổi 1 miễn phí.

Xem Khóa AI

Nguồn tham khảo

Chia sẻ: Facebook LinkedIn
Nhắn Zalo tư vấnZalo Gọi 0937 401 483