ONNX: định dạng chung để chuyển mô hình AI giữa các công cụ — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về onnx/onnx — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: onnx/onnx: Chuẩn mở để mang mô hình AI giữa các framework — hướng dẫn cài đặt và dùng →

Tóm tắt nhanh
ONNX (Open Neural Network Exchange) là một chuẩn mở để lưu và trao đổi mô hình AI, gồm cả học sâu lẫn học máy truyền thống. Gói Python onnx giúp bạn đọc, tạo, kiểm tra và chỉnh sửa các mô hình đó. Cài đặt khá dễ: chỉ cần Python và một lệnh pip install onnx.
ONNX là một định dạng mở để mô tả mô hình AI. Mô hình học sâu hay học máy truyền thống đều có thể lưu theo định dạng này. Nhờ vậy, mô hình làm ở công cụ này có thể mang sang công cụ khác để chạy, không phải làm lại từ đầu. Repo onnx/onnx vừa là bản đặc tả của định dạng, vừa là gói Python tên onnx để làm việc với nó.
Vấn đề ONNX giải quyết rất đời thường. Nhóm nghiên cứu thích một framework để huấn luyện, còn hệ thống thật lại chạy bằng công cụ hoặc phần cứng khác. Nếu mỗi bên dùng một kiểu lưu riêng, bạn sẽ mất rất nhiều công chuyển đổi. ONNX đóng vai "ngôn ngữ chung" ở giữa. README nói rõ hiện tại dự án tập trung vào phần suy luận (inferencing, tức là dùng mô hình đã huấn luyện để cho ra kết quả).
Repo này hợp với lập trình viên mới, kỹ sư dữ liệu và người làm sản phẩm AI cần hiểu hoặc xử lý file mô hình. Nếu bạn chỉ muốn dùng một ứng dụng AI có sẵn, bạn không cần cài nó. Điểm đáng giá nhất là sự ủng hộ rộng: hiện có khoảng 21.675 sao và 4.082 fork, giấy phép Apache-2.0, và repo vẫn được cập nhật trong 3 tháng gần đây.
onnx/onnx
ONNX là định dạng mở cho mô hình AI, giúp mô hình huấn luyện ở công cụ này chạy được ở công cụ khác. Cài bằng một lệnh pip.
I.ONNX làm được gì
Dưới đây là những việc chính, theo đúng những gì README và tài liệu repo nêu.
- Một định dạng mô hình mở. ONNX định nghĩa một đồ thị tính toán có thể mở rộng. Bạn có một cách lưu mô hình thống nhất, không bị khoá vào một công cụ duy nhất.
- Bộ toán tử và kiểu dữ liệu chuẩn. ONNX định nghĩa sẵn các toán tử (operator) có sẵn và các kiểu dữ liệu chuẩn. Hai công cụ cùng hiểu một toán tử thì mô hình mới chạy đúng ở cả hai nơi.
- Hỗ trợ rộng. README cho biết ONNX có mặt trong nhiều framework, công cụ và phần cứng. Danh sách đầy đủ nằm ở trang onnx.ai/supported-tools. Nhờ đó đường từ nghiên cứu đến sản xuất ngắn hơn.
- Suy luận hình dạng và kiểu (Shape and Type Inference). Công cụ này giúp suy ra kích thước và kiểu dữ liệu của các điểm trong đồ thị. Bạn dễ phát hiện mô hình sai ở đâu hơn.
- Chuyển đổi phiên bản opset. Repo có tiện ích đổi mô hình giữa các phiên bản bộ toán tử, hữu ích khi công cụ đích chỉ hỗ trợ phiên bản cũ hơn.
- Tối ưu đồ thị. README trỏ tới một repo riêng là
onnx/optimizercho việc tối ưu đồ thị. Đây không nằm trong góionnxchính. - Triển khai tham chiếu (tuỳ chọn). Cài thêm
onnx[reference]để có các thư viện phụ thuộc cho phần reference implementation. - Tài liệu và mô hình mẫu. Có tài liệu gói Python, tutorial tạo mô hình ONNX, và kho mô hình huấn luyện sẵn trên Hugging Face (onnx-community).
II.Cần chuẩn bị gì
Tư liệu chỉ nêu một số điều kiện, nên mình chỉ liệt kê những gì có:
- Python. File
pyproject.tomlyêu cầu Python từ 3.11 trở lên. README nói thêm rằng gói cung cấp wheel abi3, một bản wheel chạy được trên nhiều phiên bản Python, "từ 3.12 trở đi". Hai thông tin này hơi khác nhau, nên cách an toàn là dùng Python 3.12 trở lên. Nếu bạn đang dùng 3.11, hãy xem INSTALL.md trong repo để biết chắc. - pip để cài gói từ PyPI.
- Tài khoản, API key, GPU: README không yêu cầu gì. Chưa có thông tin về yêu cầu phần cứng.
- Hệ điều hành: README không liệt kê cụ thể. Nếu bạn gặp vấn đề khi cài, xem phần Common Errors trong INSTALL.md.
III.Cài đặt từng bước
- Mở terminalDùng PowerShell hoặc Command Prompt trên Windows, Terminal trên macOS/Linux
- Kiểm tra PythonXem bạn đã có Python phiên bản đủ mới chưa
- Cài gói onnxChạy pip install onnx
- Cài thêm phần tham chiếu (tuỳ chọn)Dùng onnx[reference] nếu cần
- Thử importChạy một dòng Python để chắc là cài xong
A.Mở terminal và kiểm tra Python
Bạn gõ lệnh trong cửa sổ terminal, không gõ vào trình soạn thảo hay trình duyệt. Trên Windows, bấm phím Windows, gõ "PowerShell" rồi Enter. Sau đó kiểm tra Python:
python --versionNếu ra số phiên bản từ 3.12 trở lên thì ổn. Nếu báo không tìm thấy lệnh, bạn cần cài Python trước (README không hướng dẫn phần này). Một số máy macOS/Linux dùng lệnh python3 thay cho python.
B.Cài gói onnx
README ghi rằng các bản phát hành chính thức được đưa lên PyPI. Cài bằng lệnh sau:
pip install onnxPip sẽ tự tải về và cài. Nếu máy có nhiều Python, bạn dễ cài nhầm vào Python khác với cái bạn đang chạy. Bạn nên dùng môi trường ảo (virtual environment) cho từng dự án, cho gọn máy.
C.Cài thêm phần tham chiếu (tuỳ chọn)
Nếu bạn cần các thư viện phụ thuộc cho reference implementation, README ghi lệnh:
pip install onnx[reference]Với người mới, thường chỉ cần lệnh pip install onnx ở trên là đủ. Trong shell zsh (macOS), có thể bạn phải đặt dấu nháy quanh onnx[reference] vì dấu ngoặc vuông có ý nghĩa đặc biệt.
D.Bản weekly để thử sớm (tuỳ chọn)
README nói có các gói onnx-weekly trên PyPI để thử nghiệm và kiểm tra sớm. Bản này không ổn định bằng bản chính thức, nên chưa cần thì đừng dùng.
E.Cài từ mã nguồn
Muốn tự build từ mã nguồn thì lấy repo về bằng:
git clone https://github.com/onnx/onnx.git
cd onnxCác bước build chi tiết, tuỳ chọn build và lỗi thường gặp nằm trong file INSTALL.md của repo. README không chép lệnh build ra, nên bạn cần đọc file đó. Người chỉ muốn dùng thì không cần làm bước này.
Chỉ cài gói từ nguồn chính thức là PyPI với tên đúng là onnx. Hãy gõ cẩn thận, vì gói có tên gần giống có thể không phải của dự án này.
IV.Kiểm tra đã chạy được chưa
README không có lệnh kiểm tra riêng cho người dùng cuối. Cách đơn giản và chắc chắn là thử import gói:
python -c "import onnx; print(onnx.__version__)"Nếu in ra số phiên bản mà không có lỗi đỏ, nghĩa là cài thành công. Nếu báo ModuleNotFoundError, nghĩa là Python bạn đang chạy chưa có gói onnx. Xem phần lỗi bên dưới.
Ngoài ra README có hướng dẫn chạy bộ kiểm thử của dự án, dành cho người muốn đóng góp. Bạn cài pytest, rồi chạy trong thư mục mã nguồn:
pip install pytestpytestNếu bạn chỉ cài từ PyPI để dùng thì không cần chạy bước này.
V.Dùng vào việc thật
Tư liệu của repo thiên về đặc tả và tài liệu hơn là ví dụ lệnh. Vì thế các tình huống dưới đây bám theo những khả năng README nêu, và chỉ dùng vài lệnh Python rất cơ bản. Muốn xem đầy đủ API, bạn mở tài liệu Python API Overview của repo.
A.Dev mới cần kiểm tra file mô hình nhận được
Bạn vừa nhận một file model.onnx từ đồng nghiệp làm AI. Trước khi đưa vào hệ thống, bạn muốn biết file có đúng chuẩn không. Mở Python và thử:
import onnx
model = onnx.load("model.onnx")
onnx.checker.check_model(model)
print("File mô hình hợp lệ")onnx.load đọc file, check_model kiểm tra cấu trúc có đúng đặc tả không. Nếu có lỗi, Python sẽ báo ngay chỗ sai thay vì để hệ thống thật hỏng giữa chừng. Đây là bước kiểm tra nhanh, rất đáng làm.
ONNX giống như định dạng PDF của mô hình AI: ai tạo ra cũng được, miễn là bên nhận mở được.
Ông T
B.Nhóm sản phẩm muốn đổi công cụ chạy mô hình
Công ty bạn có một mô hình đã huấn luyện ở một framework, nhưng phần mềm khách hàng lại chạy trên công cụ khác. Nếu hai bên cùng hỗ trợ ONNX, bạn lưu mô hình ra ONNX rồi mang sang chạy ở công cụ đích. Bạn vào trang onnx.ai/supported-tools để xem công cụ nào được hỗ trợ trước khi quyết định. Kết quả là bạn giảm công viết lại mô hình, và các bên làm việc trên cùng một file.
C.Người học AI tìm mô hình có sẵn để thử
Bạn là người mới, chưa muốn tự huấn luyện. README trỏ tới kho mô hình ONNX huấn luyện sẵn trên Hugging Face (onnx-community) và các tutorial tạo mô hình ONNX. Bạn tải một mô hình về, dùng đoạn mã kiểm tra ở trên để chắc nó đọc được, rồi theo tutorial để chạy thử. Cách này giúp bạn học từ mô hình thật mà không tốn công huấn luyện.
D.Dev cần mô hình tương thích với công cụ cũ hơn
Công cụ đích của bạn chỉ hỗ trợ phiên bản opset cũ. Repo có tiện ích chuyển đổi phiên bản opset, được mô tả trong tài liệu version_converter của repo. Bạn đọc tài liệu đó để biết cách gọi, rồi chuyển mô hình về phiên bản phù hợp. Sau đó kiểm tra lại bằng check_model. Kết quả là mô hình chạy được ở nơi chỉ hỗ trợ bản cũ, và bạn không phải làm lại từ đầu.
VI.Lỗi hay gặp và cách xử lý
A.pip báo không tìm thấy phiên bản phù hợp
Thường do Python của bạn quá cũ hoặc là kiến trúc máy không có sẵn wheel. File pyproject.toml yêu cầu Python 3.11 trở lên, và wheel abi3 nói từ 3.12. Hãy chạy python --version, nâng Python lên bản mới hơn nếu cần, rồi cài lại. Nếu vẫn lỗi, đọc phần Common Errors trong INSTALL.md.
B.ModuleNotFoundError: No module named 'onnx'
Bạn đã cài, nhưng chạy bằng Python khác. Trên máy có nhiều Python hoặc môi trường ảo, pip và python có thể trỏ tới hai nơi khác nhau. Hãy cài và chạy trong cùng một môi trường, và nhớ kích hoạt môi trường ảo trước khi chạy.
C.zsh báo lỗi khi cài onnx[reference]
Trên macOS, zsh hiểu dấu ngoặc vuông theo nghĩa khác. Bạn đặt cả tên gói trong dấu nháy, ví dụ pip install "onnx[reference]". Nếu chỉ cần dùng cơ bản thì cài onnx thường là đủ.
D.Lỗi khi build từ mã nguồn
Build từ mã nguồn cần thêm công cụ biên dịch, vì repo có file CMakeLists.txt. Nếu không bắt buộc, bạn nên cài từ PyPI cho nhẹ. Cần build thì làm theo INSTALL.md, nơi có phần tuỳ chọn build và lỗi thường gặp.
E.check_model báo mô hình không hợp lệ
Đây không hẳn là lỗi cài đặt. Có thể file bị hỏng khi tải, hoặc mô hình dùng toán tử hay phiên bản opset không khớp. Hãy tải lại file, hoặc hỏi người làm ra mô hình. Bạn cũng có thể thử chuyển phiên bản opset như đã nói ở trên.
VII.Có nên dùng không
Điểm mạnh. ONNX là chuẩn mở, giấy phép Apache-2.0, được nhiều framework, công cụ và phần cứng hỗ trợ. Cài đặt chỉ một lệnh pip, không cần tài khoản hay key. Repo vẫn được cập nhật đều và có cộng đồng, tài liệu lẫn mô hình mẫu.
Giới hạn. README nói rõ hiện tại dự án tập trung vào suy luận, nên đây không phải nơi để bạn huấn luyện mô hình. README cũng thiên về đặc tả, ít ví dụ cho người mới, nên bạn sẽ phải đọc thêm tài liệu và tutorial. Bạn cũng cần kiểm tra công cụ mình dùng có hỗ trợ ONNX và toán tử cần thiết hay không.
Khi nào chọn cách khác. Nếu bạn chỉ dùng một framework duy nhất từ huấn luyện đến chạy, định dạng riêng của framework đó có thể đã đủ. Nếu bạn chỉ muốn dùng ứng dụng AI, không làm việc với file mô hình, thì bạn không cần ONNX. Còn nếu bạn cần chuyển mô hình giữa các công cụ khác nhau, đây là lựa chọn rất đáng cân nhắc.
Câu hỏi thường gặp
ONNX có miễn phí không?
Có. Repo dùng giấy phép Apache-2.0 và gói được phát hành trên PyPI. README không nhắc tới phí hay tài khoản nào.
Cài ONNX có cần GPU không?
Tư liệu không nêu yêu cầu GPU hay phần cứng nào để cài gói onnx. Chưa có thông tin về hiệu năng trên từng loại phần cứng.
ONNX cần phiên bản Python nào?
File pyproject.toml yêu cầu Python 3.11 trở lên. README nói thêm gói có wheel abi3 chạy trên nhiều phiên bản Python từ 3.12 trở đi. Dùng Python 3.12 trở lên là cách chắc chắn nhất.
Cài ONNX bằng lệnh nào?
Chạy pip install onnx. Nếu cần phần phụ thuộc cho triển khai tham chiếu, dùng pip install onnx[reference]. Hướng dẫn chi tiết hơn nằm trong INSTALL.md của repo.
ONNX khác gì một framework như PyTorch hay Keras?
ONNX là định dạng và đặc tả để trao đổi mô hình, không phải framework để huấn luyện. README nói dự án hiện tập trung vào suy luận. Chủ đề của repo có nhắc tới PyTorch, Keras và scikit-learn, nhưng tư liệu không mô tả chi tiết cách chuyển đổi từng loại.
Chạy được trên Windows không?
README không liệt kê hệ điều hành cụ thể. Nếu gặp lỗi khi cài, hãy xem phần Common Errors trong INSTALL.md của repo. Chưa có thông tin rõ hơn trong tư liệu.
Tôi muốn đóng góp hoặc đề xuất thêm toán tử thì làm sao?
README mời cộng đồng tham gia và trỏ tới hướng dẫn đóng góp CONTRIBUTING.md. Muốn thêm toán tử mới, bạn đọc tài liệu AddNewOp.md trong thư mục docs của repo.


