- Trước khi đọc tài liệu, biết mình đang dùng phiên bản nào của thư viện; tài liệu của phiên bản khác có thể sai với máy bạn.
- Đọc theo thứ tự: chữ ký hàm, mô tả từng tham số, ví dụ, rồi các ghi chú và cảnh báo.
- Dùng AI để giải thích và tóm tắt trang tài liệu bạn dán vào, không để nó trả lời từ trí nhớ về một thư viện.
- Mọi lời gọi hàm AI gợi ý, soát tên tham số với chữ ký thật trước khi dùng.
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 pandas bản 3.1.1. Đọc tài liệu tiếng Anh nói chung có bài riêng: đọc tài liệu tiếng Anh với AI.
Vì sao AI hay sai về thư viện
Mô hình ngôn ngữ học từ rất nhiều code và bài hướng dẫn, viết cho nhiều phiên bản khác nhau của cùng một thư viện. Khi bạn hỏi, nó không mở tài liệu ra đọc; nó đoán dòng code có khả năng nhất. Kết quả thường đúng, nhưng có ba kiểu sai lặp đi lặp lại:
- Tên tham số gần đúng: reversed thay cho reverse, flag thay cho flags. Nghe hợp lý, gõ sai một chữ là lỗi.
- Cách gọi của phiên bản khác: cú pháp đúng ở bản cũ nhưng bản mới đã đổi.
- Tham số không tồn tại: một tùy chọn nghe như nên có, nhưng thư viện không có.
Cả ba đều có chung cách chữa: so với chữ ký thật của hàm trong phiên bản bạn đã cài.
Bước 1: biết mình đang dùng phiên bản nào
Chạy pip show tên-thư-viện, hoặc in thuộc tính phiên bản của thư viện trong Python. Ghi lại con số đó. Với thư viện chuẩn của Python, phiên bản là phiên bản Python.
Tài liệu của nhiều thư viện có ô chọn phiên bản ở góc trang. Trang read_csv trên pandas.pydata.org mà bài này đọc là tài liệu bản ổn định hiện tại; nếu máy bạn cài bản cũ hơn, chọn đúng bản đó. Khi hỏi AI, nói luôn phiên bản: "với pandas 3.1, đọc CSV dùng dấu chấm phẩy thế nào?" cho câu trả lời sát hơn câu hỏi không có phiên bản.
Bước 2: đọc một trang tài liệu theo thứ tự
Trang tài liệu của một hàm thường có bốn phần. Đọc theo thứ tự này:
- Chữ ký: tên hàm và danh sách tham số với giá trị mặc định. Để ý các ký hiệu đặc biệt. Trong chữ ký Python, dấu sao đứng một mình nghĩa là mọi tham số sau nó phải truyền theo tên; dấu gạch chéo nghĩa là mọi tham số trước nó chỉ truyền theo vị trí; hai dấu sao trước một tên nghĩa là hàm nhận thêm tham số tùy ý theo tên.
- Mô tả tham số: đọc kỹ những tham số bạn định dùng, nhất là kiểu dữ liệu và giá trị mặc định.
- Ví dụ: chép ví dụ ra chạy thử trước khi sửa theo ý mình.
- Ghi chú và cảnh báo: những thay đổi theo phiên bản, những trường hợp đặc biệt.
Ví dụ thật: trang read_csv của pandas ghi chữ ký bắt đầu bằng filepath_or_buffer, rồi một dấu sao, rồi sep và các tham số khác. Nghĩa là trong bản tài liệu đó, sep phải viết sep=';', không được truyền theo vị trí. Một dòng code AI viết theo kiểu read_csv('diem.csv', ';') sẽ báo lỗi, dù trông rất bình thường.
Bước 3: dùng AI để hiểu trang tài liệu, không để thay nó
Khi một trang tài liệu khó hiểu, dán nguyên phần liên quan vào chatbot:
Đây là trích đoạn tài liệu chính thức của [thư viện] phiên bản [x.y], hàm [tên hàm]: [dán].
Hãy giải thích bằng tiếng Việt:
1. Ý nghĩa các ký hiệu trong chữ ký hàm.
2. Ba tham số mình hay cần nhất cho việc [mô tả việc], kèm giá trị mặc định.
3. Viết một ví dụ nhỏ CHỈ dùng tham số có trong trích đoạn trên.
Nếu điều mình hỏi không có trong trích đoạn, nói rõ là không có.
Câu cuối là chìa khóa: buộc AI làm việc trên văn bản bạn đưa, thay vì trí nhớ của nó.
Bước 4: soát lời gọi AI gợi ý
Đoạn code dưới đây nhận một lời gọi hàm dạng chữ, như AI gợi ý, và soát nó mà không chạy: tìm hàm thật trong thư viện bạn đã cài, đọc chữ ký bằng inspect.signature, báo tên tham số không có kèm tên gần nhất, báo nếu số đối số theo vị trí hay cách truyền không hợp, và in phiên bản thư viện. Nếu hàm nhận thêm tham số tùy ý theo tên, hoặc không đọc được chữ ký, nó nói rõ là không kiểm được thay vì đoán.
"""Soát một lời gọi hàm do AI gợi ý so với chữ ký THẬT của hàm trong thư viện bạn đã cài.
AI hay đưa tên tham số nghe hợp lý nhưng không có (reversed thay cho reverse, flag thay cho flags), hoặc cách gọi đúng
ở phiên bản cũ mà sai ở phiên bản bạn đang dùng. Chương trình:
- đọc lời gọi bằng ast (không chạy nó), tìm hàm thật bằng importlib, đọc chữ ký bằng inspect.signature;
- báo tên tham số không có trong chữ ký, gợi ý tên gần nhất; báo nếu số đối số theo vị trí hay cách truyền không hợp;
- báo phiên bản thư viện, vì tài liệu phải đọc đúng phiên bản đó;
- nếu hàm nhận **kwargs hay không đọc được chữ ký thì nói rõ là không kiểm được, cần mở tài liệu.
Chỉ dùng thư viện chuẩn (thư viện cần soát thì phải đã cài).
"""
import ast
import builtins
import difflib
import importlib
import inspect
import platform
import sys
BI_DANH = {"pd": "pandas", "np": "numpy"}
def tim_ham(ten):
"""'pd.read_csv' -> (hàm, tên gói gốc). Thử nhập phần dài nhất có thể là module, phần còn lại là thuộc tính."""
phan = ten.split(".")
phan[0] = BI_DANH.get(phan[0], phan[0])
for i in range(len(phan), 0, -1):
try:
doi_tuong = importlib.import_module(".".join(phan[:i]))
except ImportError:
continue
for p in phan[i:]:
doi_tuong = getattr(doi_tuong, p)
return doi_tuong, phan[0]
return getattr(builtins, phan[0]), "builtins"
def phien_ban(goi):
if goi == "builtins" or goi in sys.stdlib_module_names:
return f"Python {platform.python_version()} (thư viện chuẩn)"
return f"{goi} {getattr(importlib.import_module(goi), '__version__', '(không rõ phiên bản)')}"
def soat(loi_goi):
nut = ast.parse(loi_goi.strip(), mode="eval").body
if not isinstance(nut, ast.Call):
raise ValueError("không phải một lời gọi hàm")
ten = ast.unparse(nut.func)
ham, goi = tim_ham(ten)
kq = {"ham": ten, "phien_ban": phien_ban(goi), "sai_ten": [], "goi_y": {}, "loi": None, "kiem_duoc": True}
try:
chu_ky = inspect.signature(ham)
except (ValueError, TypeError):
kq["kiem_duoc"] = False
kq["loi"] = "không đọc được chữ ký, mở tài liệu để kiểm"
return kq
ts = chu_ky.parameters.values()
if any(p.kind is p.VAR_KEYWORD for p in ts):
kq["kiem_duoc"] = False
kq["loi"] = "hàm nhận **kwargs, tên tham số lạ có thể bị chuyển đi nơi khác; mở tài liệu để kiểm"
else:
hop_le = [p.name for p in ts if p.kind in (p.POSITIONAL_OR_KEYWORD, p.KEYWORD_ONLY)]
for k in nut.keywords:
if k.arg and k.arg not in hop_le:
kq["sai_ten"].append(k.arg)
kq["goi_y"][k.arg] = difflib.get_close_matches(k.arg, hop_le, n=1)
try:
chu_ky.bind(*[None] * len(nut.args), **{k.arg: None for k in nut.keywords if k.arg})
except TypeError as e:
kq["loi"] = str(e)
return kq
MAU = ["sorted(ds, key=len, reversed=True)",
r"re.sub(r'\s+', ' ', s, flag=re.I)",
"pd.read_csv('diem.csv', ';', encoding='utf-8')",
"json.dumps(du_lieu, indent=2, pretty=True)",
"math.isclose(a, b, rel_tol=1e-9)"]
if __name__ == "__main__":
for lg in MAU:
kq = soat(lg)
print(lg, "\n ", kq["phien_ban"], "| tên sai:", kq["sai_ten"], "| gợi ý:", kq["goi_y"],
"| lỗi:", kq["loi"], "| kiểm được:", kq["kiem_duoc"])
Với năm lời gọi mẫu, chương trình báo reversed sai và gợi ý reverse; flag sai và gợi ý flags; read_csv truyền dấu chấm phẩy theo vị trí là thừa đối số vị trí; json.dumps nhận thêm tham số tùy ý nên không kiểm được tên pretty; còn math.isclose đúng. Phần kiểm đi kèm so mọi kết luận "có vấn đề" hay "không có vấn đề" với việc gọi thật hàm đó trên 600 lời gọi ngẫu nhiên tới năm hàm của thư viện chuẩn và pandas; và với json.dumps, gọi thật với pretty=True đúng là vẫn báo lỗi, đúng chỗ công cụ đã nói cần mở tài liệu.
Khi không soát được bằng chữ ký
Tài liệu Python về inspect.signature viết rằng hàm này báo lỗi khi không thể đưa ra chữ ký; chẳng hạn trên Python 3.13, nó không đọc được chữ ký của lớp datetime.date. Còn với hàm có hai dấu sao như json.dumps, chữ ký không cho biết tên nào được chấp nhận: tên lạ không bị chặn ở chữ ký, và chỉ khi chạy mới biết. Trang tài liệu json không có tham số nào tên pretty, và gọi thử với pretty=True thì báo lỗi. Trong cả hai trường hợp, cách duy nhất là đọc tài liệu và chạy thử một ví dụ nhỏ.
Chữ ký cũng không nói gì về ý nghĩa. Tên tham số đúng mà giá trị sai, như truyền chuỗi khi hàm cần số, vẫn lọt qua. Chạy thử với dữ liệu nhỏ luôn là bước cuối.
Đọc tài liệu khi học một thư viện mới
Với một thư viện hoàn toàn mới, đừng bắt đầu từ trang tham chiếu từng hàm. Hầu hết thư viện lớn có trang bắt đầu nhanh và phần hướng dẫn theo chủ đề; đọc chúng trước để biết các khái niệm chính và cách tác giả muốn bạn dùng thư viện. Sau đó mới tra trang tham chiếu cho hàm cụ thể. AI hợp với việc tóm tắt trang hướng dẫn dài thành danh sách khái niệm, miễn là bạn dán nội dung trang vào và kiểm lại các ví dụ. Khi chuyển sang một ngôn ngữ khác, cách học có trong bài học một ngôn ngữ lập trình mới cùng AI.
Ghi phiên bản vào dự án
Khi làm bài tập lớn hay dự án nhóm, ghi phiên bản các thư viện vào một tệp requirements.txt, mỗi dòng một thư viện kèm số phiên bản. Cả nhóm cài đúng một bộ, và khi hỏi AI, bạn dán luôn tệp đó để nó biết đang nói về phiên bản nào. Code chạy được trên máy bạn mà báo lỗi trên máy bạn cùng nhóm thường là do hai máy cài hai phiên bản khác nhau; tệp này giúp loại trừ nguyên nhân đó ngay từ đầu. Khi nâng phiên bản một thư viện, đọc phần ghi chú thay đổi của bản mới trước, rồi chạy lại toàn bộ code.
Một thói quen nhỏ: mở tài liệu ngay trong Python
Hàm help có sẵn trong Python in ra chữ ký và chuỗi mô tả của hàm trên chính máy bạn, nghĩa là đúng phiên bản bạn đang dùng. Gõ help kèm tên hàm trong cửa sổ lệnh Python trước khi hỏi AI là cách nhanh nhất để kiểm một tên tham số. Nhiều trình soạn code cũng hiện chữ ký khi bạn gõ dấu mở ngoặc; đừng bỏ qua dòng gợi ý đó.
- Dùng dòng code AI gợi ý mà không biết thư viện trên máy là phiên bản nào.
- Đọc tài liệu của phiên bản khác với phiên bản đã cài.
- Hỏi AI về một thư viện mà không dán trang tài liệu liên quan.
- Bỏ qua dấu sao và dấu gạch chéo trong chữ ký hàm.
- Tin rằng tên tham số nghe hợp lý thì chắc chắn có.
- Coi lời gọi đúng chữ ký là đã đúng, không chạy thử với dữ liệu nhỏ.
Câu hỏi thường gặp
Vì sao code ChatGPT viết báo lỗi unexpected keyword argument?
Vì tên tham số không có trong hàm ở phiên bản bạn dùng; so với chữ ký thật hoặc tài liệu đúng phiên bản.
Làm sao xem chữ ký một hàm Python?
Dùng help hoặc inspect.signature với hàm đó, hoặc đọc trang tài liệu chính thức đúng phiên bản.
Dấu sao trong chữ ký hàm Python nghĩa là gì?
Mọi tham số đứng sau dấu sao phải truyền theo tên.
Có nên hỏi AI thay vì đọc tài liệu?
Hỏi AI để hiểu trang tài liệu bạn dán vào, rồi kiểm lời gọi với chữ ký thật.
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.
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í.

