Tải về và chạy một dự án AI từ GitHub (môi trường ảo, thư viện)

Bài này dựa trên tài liệu chính thức của Python (venv, importlib.metadata) và pip, đọc ngày 11/11/2026. Ví dụ dùng Python; dự án viết bằng ngôn ngữ khác có các bước tương tự với công cụ riêng của ngôn ngữ đó.

Bước 1: clone và đọc README

Tải kho về máy bằng git clone <địa chỉ kho> rồi vào thư mục vừa tạo. Nếu chưa dùng Git, xem Git và GitHub là gì. Trước khi gõ lệnh cài đặt nào, mở README và tìm bốn thông tin:

Đọc cả phần giấy phép (LICENSE) nếu bạn định dùng code cho đồ án hay công việc; xem đọc README và LICENSE.

Bước 2: tạo môi trường ảo cho riêng dự án

Tài liệu Python định nghĩa môi trường ảo là một môi trường Python nhẹ, tách biệt, có bộ gói riêng; mặc định chỉ những gói cài vào nó mới dùng được. Nhờ vậy dự án A cần numpy bản này và dự án B cần bản khác không giẫm chân nhau, và bạn không làm rối Python của cả máy.

Tạo môi trường ảo tên .venv trong thư mục dự án:

python -m venv .venv

Kích hoạt, theo tài liệu:

Sau khi kích hoạt, dấu nhắc lệnh thường hiện tên môi trường. Tài liệu Python còn lưu ý hai điều quan trọng: môi trường ảo không nên đưa vào hệ quản lý mã nguồn như Git, vì nó được tạo ra để bỏ đi và tạo lại từ đầu, ví dụ từ tệp requirements; và môi trường ảo nhìn chung không mang sang máy khác được, vì các script bên trong chứa đường dẫn tuyệt đối. Thêm .venv/ vào .gitignore của bạn.

Bước 3: cài thư viện

Với dự án có tệp requirements.txt, tài liệu pip hướng dẫn:

python -m pip install -r requirements.txt

Trên Windows có thể thay python bằng py. Gọi pip qua python -m pip bảo đảm cài vào đúng Python của môi trường ảo đang kích hoạt, tránh tình huống cài vào một Python khác trên máy.

Tệp requirements là danh sách tham số cho pip install, mục đích chính là cài lặp lại được: nó ghi lại phiên bản các gói để người khác dựng lại đúng môi trường đó. Khi dự án của bạn chạy ổn, tạo tệp này bằng python -m pip freeze > requirements.txt để người khác cũng chạy được.

Một số dự án dùng pyproject.toml thay cho requirements.txt; khi đó README thường hướng dẫn cài bằng pip install với đường dẫn thư mục dự án. Làm đúng theo README của dự án đó.

Bước 4: kiểm môi trường trước khi chạy

Thay vì chạy rồi gặp ModuleNotFoundError giữa chừng, bạn có thể so tệp requirements với các gói đã cài. Đoạn Python dưới đây làm việc đó bằng importlib.metadata có sẵn trong Python: đọc từng dòng yêu cầu (hiểu các dạng ==, >=, <, ~=), chuẩn hóa tên gói (scikit_learn và scikit-learn là một), rồi báo gói nào đủ, thiếu hay sai phiên bản. Nó chỉ đọc, không cài gì. Khi chạy không kèm tham số, đoạn code dùng một danh sách mẫu để minh họa; chạy kèm đường dẫn tệp requirements thì kiểm môi trường thật.

"""So tệp requirements.txt của một dự án với các gói đã cài, để biết thiếu gì trước khi chạy.

Chạy với môi trường thật: python soat_moi_truong.py requirements.txt
Chỉ đọc, không cài gì. Hiểu các dạng thường gặp: ten, ten==1.2, ten>=1.2, ten<2, ten~=1.2, ten[extra]>=1.0.
"""
import re
import sys
from importlib import metadata

MAU = re.compile(r"^([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]*\])?\s*(==|>=|<=|~=|>|<)?\s*([0-9][0-9A-Za-z.*+-]*)?")


def chuan_ten(ten):
    return re.sub(r"[-_.]+", "-", ten).lower()


def so(phien_ban):
    return tuple(int(x) for x in re.findall(r"\d+", phien_ban)[:3])


def doc_yeu_cau(van_ban):
    ds = []
    for dong in van_ban.splitlines():
        dong = dong.split("#", 1)[0].strip()
        if not dong or dong.startswith(("-", "git+", "http")):
            continue  # bỏ qua tùy chọn pip và cài từ địa chỉ: cần xem bằng tay
        m = MAU.match(dong)
        if m:
            ds.append((chuan_ten(m.group(1)), m.group(2), m.group(3), dong))
    return ds


def dat(da_co, phep, can):
    a, b = so(da_co), so(can)
    return {"==": a == b, ">=": a >= b, "<=": a <= b, ">": a > b, "<": a < b, "~=": a >= b and a[:1] == b[:1]}[phep]


def so_khop(yeu_cau, da_cai):
    ket_qua = []
    for ten, phep, can, dong in yeu_cau:
        co = da_cai.get(ten)
        if co is None:
            ket_qua.append(f"THIẾU      {dong}")
        elif phep and can and not dat(co, phep, can):
            ket_qua.append(f"SAI PHIÊN  {dong} (đang có {co})")
        else:
            ket_qua.append(f"OK         {dong} (đang có {co})")
    return ket_qua


def da_cai_that():
    return {chuan_ten(d.metadata["Name"]): d.version for d in metadata.distributions() if d.metadata["Name"]}


MAU_YEU_CAU = """# requirements.txt của một dự án phân loại ảnh
numpy>=1.26
pandas==2.2.3
torch>=2.4   # cần GPU? xem README
scikit_learn~=1.5
-r requirements-dev.txt
"""
MAU_DA_CAI = {"numpy": "2.1.0", "pandas": "2.1.4", "scikit-learn": "1.6.1"}


def chay_thu():
    kq = so_khop(doc_yeu_cau(MAU_YEU_CAU), MAU_DA_CAI)
    print("\n".join(kq))
    return kq


if __name__ == "__main__":
    if len(sys.argv) > 1:
        with open(sys.argv[1], encoding="utf-8") as f:
            print("\n".join(so_khop(doc_yeu_cau(f.read()), da_cai_that())))
    else:
        chay_thu()

Kết quả với danh sách mẫu:

OK         numpy>=1.26 (đang có 2.1.0)
SAI PHIÊN  pandas==2.2.3 (đang có 2.1.4)
THIẾU      torch>=2.4
OK         scikit_learn~=1.5 (đang có 1.6.1)

Chú ý cách so phiên bản: so theo từng con số, không theo chữ, nên 2.10 lớn hơn 2.9. So theo chữ sẽ cho kết quả ngược. Dòng -r requirements-dev.txt trong tệp mẫu bị bỏ qua có chủ đích; dòng cài từ địa chỉ git hay tùy chọn của pip cần xem bằng tay.

Bước 5: chạy ví dụ nhỏ nhất trước

Chạy đúng lệnh ví dụ trong README, với dữ liệu mẫu nhỏ nhất. Mục tiêu của lần chạy đầu không phải kết quả đẹp mà là biết môi trường đã đúng. Khi ví dụ chạy được, mới đổi sang dữ liệu của bạn, đổi tham số, sửa code.

Chạy lệnh từ thư mục gốc của dự án: nhiều dự án đọc tệp theo đường dẫn tương đối, chạy từ thư mục khác sẽ báo không tìm thấy tệp.

Ghi lại cách bạn đã chạy được

Khi dự án đã chạy, dành vài phút ghi lại, vì ba tuần sau chính bạn sẽ quên. Một tệp ghi chú ngắn trong thư mục dự án nên có:

• phiên bản Python đã dùng (in bằng python --version);
• danh sách gói chính xác, lưu bằng python -m pip freeze > da-chay-duoc.txt (đặt tên khác requirements.txt để không ghi đè tệp gốc của tác giả);
• lệnh đã chạy và dữ liệu mẫu đã dùng;
• những chỗ bạn phải sửa so với README, ví dụ phải hạ phiên bản một gói hay đổi một đường dẫn.

Nếu bạn sửa code để dự án chạy được, đó là lúc nên fork kho về tài khoản của mình và commit thay đổi, kèm lời mô tả nói rõ đã sửa gì. Nếu chỗ sửa có ích cho người khác (ví dụ README thiếu một bước), bạn có thể gửi đề xuất cho tác giả; bài đóng góp cho dự án AI mã nguồn mở chỉ cách bắt đầu.

Lỗi hay gặp và cách xử lý

Với tệp mô hình, xem Hugging Face là gì: đó là nơi phần lớn dự án AI mở để trọng số.

Chạy mã của người lạ an toàn

Một kho trên GitHub là mã chưa ai kiểm cho bạn. Vài thói quen tối thiểu:

• Chọn kho có người duy trì rõ ràng, còn được cập nhật, có issue được trả lời; bài tìm repo AI hay chỉ cách đánh giá.
• Đọc lướt các script cài đặt và tệp chạy chính trước khi chạy, nhất là các đoạn tải tệp từ mạng hay chạy lệnh hệ thống.
• Luôn cài trong môi trường ảo, không cài thư viện của dự án lạ vào Python của cả máy, và không chạy bằng quyền quản trị.
• Không đặt khóa API thật vào dự án thử nghiệm của người khác cho tới khi bạn hiểu code dùng khóa đó thế nào.

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

Học tiếp

• Trước khi dùng code của người khác cho đồ án hay công việc, đọc đọc README và LICENSE.
• Muốn tải mô hình và dữ liệu cho dự án, đọc Hugging Face là gì.
• Muốn ôn lại clone và commit, đọc Git và GitHub là gì.

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.

Nguồn tham khảo

• Python docs: venv — Creation of virtual environments
• pip User Guide: Requirements Files
• GitHub Docs: About remote repositories
• Python docs: importlib.metadata