# 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

> onnx/onnx là kho mã của ONNX, một định dạng mở để lưu và trao đổi mô hình AI giữa các framework, công cụ và phần cứng. Gói Python tên onnx cài bằng một lệnh pip. Cài khá dễ, nhưng bạn cần hiểu ONNX là chuẩn và bộ công cụ làm việc với mô hình, không phải ứng dụng chạy ngay.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-30 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/onnx-onnx-chuan-mo-mo-hinh-ai-huong-dan-cai-dat

ONNX (Open Neural Network Exchange) là một định dạng mở dành cho mô hình AI, gồm cả deep learning lẫn machine learning truyền thống. Repo `onnx/onnx` chứa phần đặc tả của định dạng này và gói Python `onnx` để bạn đọc, tạo, kiểm tra mô hình theo định dạng đó. Nói đơn giản: ONNX giống như một “định dạng file chung” cho mô hình AI, để mô hình huấn luyện ở nơi này có thể được dùng ở nơi khác.

Vấn đề nó giải quyết rất thực tế. Mỗi framework (PyTorch, Keras, scikit-learn…) lưu mô hình theo cách riêng. Khi muốn đưa mô hình từ khâu nghiên cứu sang khâu chạy thật, bạn dễ bị kẹt vì công cụ này không đọc được file của công cụ kia. ONNX định nghĩa một đồ thị tính toán có thể mở rộng, cùng danh sách các toán tử (operator) và kiểu dữ liệu chuẩn. Phần tư liệu của dự án nói hiện tại họ tập trung vào khả năng cần cho suy luận (inferencing, hay còn gọi là chấm điểm/scoring).

Repo này hợp với lập trình viên, kỹ sư dữ liệu, và người làm AI muốn hiểu hoặc làm việc với định dạng mô hình chung. Nếu bạn là người làm kinh doanh hay văn phòng, bạn ít khi cài trực tiếp, nhưng sẽ gặp chữ “ONNX” khi một phần mềm hay mô hình nói “hỗ trợ ONNX”. Điểm đáng giá nhất là sự phổ biến: hiện có khoảng 21.675 sao và 4.082 fork trên GitHub, giấy phép Apache-2.0, và repo vẫn được cập nhật trong 3 tháng gần đây.

```repo
- repo | onnx/onnx
- kind | Thư viện
- desc | ONNX là định dạng mở cho mô hình AI (cả deep learning lẫn ML truyền thống), giúp mô hình chạy được giữa nhiều framework, công cụ và phần cứng khác nhau.
- stars | 22k
- lang | Python
- license | Apache-2.0
```

## ONNX làm được gì

### Một định dạng chung cho nhiều loại mô hình

ONNX là định dạng mở cho mô hình AI, bao gồm cả deep learning và ML truyền thống. Lợi ích: bạn không bị “khóa” vào một framework duy nhất. Khi dự án lớn dần, bạn có thể chọn công cụ phù hợp hơn mà không phải làm lại từ đầu.

### Đồ thị tính toán, toán tử và kiểu dữ liệu chuẩn

ONNX định nghĩa một mô hình đồ thị tính toán có thể mở rộng, kèm các toán tử có sẵn và kiểu dữ liệu chuẩn. Nhờ có chuẩn, các công cụ khác nhau hiểu cùng một mô hình theo cùng một cách. Tư liệu trong repo có trang mô tả toán tử (Operators) và đặc tả biểu diễn trung gian (IR) nếu bạn muốn đọc sâu.

### Được nhiều công cụ và phần cứng hỗ trợ

Theo README, ONNX được hỗ trợ rộng rãi trong nhiều framework, công cụ và phần cứng. Việc này giúp rút ngắn đường từ nghiên cứu sang sản phẩm thật. Danh sách công cụ hỗ trợ nằm ở trang onnx.ai/supported-tools.

### Tiện ích làm việc với đồ thị mô hình

README liệt kê ba nhóm tiện ích: suy luận hình dạng và kiểu dữ liệu (Shape and Type Inference), tối ưu đồ thị (nằm ở repo riêng onnx/optimizer), và chuyển đổi phiên bản opset (Opset Version Conversion). Tức là ngoài việc lưu mô hình, bạn còn có công cụ để kiểm tra và chỉnh nó.

### Tài nguyên đi kèm

README trỏ tới tài liệu gói Python, hướng dẫn tạo mô hình ONNX (repo onnx/tutorials) và các mô hình ONNX huấn luyện sẵn trên Hugging Face (onnx-community). Đây là chỗ nên ghé trước khi tự làm từ đầu.

## Cần chuẩn bị gì

Tư liệu chỉ nói rõ một số điều, mình không thêm gì ngoài đó:

- Python: file `pyproject.toml` của repo yêu cầu Python 3.11 trở lên. README còn nói gói cung cấp wheel tương thích abi3, dùng được trên nhiều phiên bản Python từ 3.12 trở đi. Cách chắc ăn nhất là dùng Python mới (3.12 hoặc cao hơn).
- pip: để chạy lệnh cài đặt. README không nêu thêm yêu cầu nào khác cho cách cài bằng pip.
- Tài khoản, API key, GPU: README không yêu cầu. Gói được phát hành trên PyPI.
- Hệ điều hành: README không liệt kê hệ điều hành cụ thể. Nếu gặp vấn đề khi cài, xem file INSTALL.md trong repo, trong đó có các tùy chọn build và lỗi thường gặp.

## Cài đặt từng bước

```steps
- Mở terminal | Mở PowerShell (Windows) hoặc Terminal (macOS/Linux)
- Kiểm tra Python | Xem phiên bản Python đủ mới chưa
- Cài gói onnx | Chạy pip install onnx
- (Tùy chọn) Cài bản reference | Thêm phần phụ thuộc cho bản cài đặt tham chiếu
- Kiểm tra | Chạy thử lệnh import để xác nhận
```

### Mở terminal và kiểm tra Python

Bạn mở terminal ở bất kỳ thư mục nào, không cần vào thư mục repo vì ta cài từ PyPI. Trước tiên kiểm tra Python:

```bash
python --version
```

Lệnh này in ra phiên bản Python. Nếu thấy số thấp hơn 3.11, hãy cài bản Python mới hơn trước. Một số máy dùng lệnh `python3` thay cho `python`; đó là chuyện của máy bạn, không phải của ONNX.

### Cài gói onnx bằng pip

Đây là lệnh chính thức trong README:

```sh
pip install onnx
```

Lệnh tải gói `onnx` từ PyPI và cài vào môi trường Python hiện tại. Người mới hay vấp ở chỗ cài vào Python này nhưng chạy ở Python khác. Nếu bạn dùng môi trường ảo (virtual environment), hãy bật nó trước khi cài.

### Cài thêm bản reference (tùy chọn)

README ghi rằng có thể dùng `onnx[reference]` để lấy các phần phụ thuộc cho bản cài đặt tham chiếu (reference implementation):

```sh
pip install onnx[reference]
```

Nếu terminal của bạn báo lỗi với dấu ngoặc vuông (một số shell như zsh cần đặt trong dấu nháy), bạn bọc cả cụm trong dấu nháy kép. Nếu chỉ muốn thử cơ bản, bước này có thể bỏ qua.

### Muốn thử bản mới sớm hơn

README nhắc có gói `onnx-weekly` được đăng hằng tuần trên PyPI để thử nghiệm sớm. README không đưa lệnh cài riêng, nên bạn xem trang PyPI của gói đó. Với người mới, bản phát hành chính thức `onnx` là lựa chọn an toàn hơn.

### Muốn cài từ mã nguồn?

README không đưa lệnh build từ mã nguồn trong phần chính; hướng dẫn chi tiết, các tùy chọn build thường dùng và lỗi thường gặp nằm trong file INSTALL.md ở thư mục gốc repo. Nếu bạn định đóng góp mã, đọc thêm CONTRIBUTING.md.

```note
ONNX là thư viện chạy trên máy bạn, không bắt nhập API key. Tuy vậy, mô hình bạn tải về từ nơi khác vẫn nên được kiểm tra nguồn gốc trước khi dùng, nhất là khi dùng cho dữ liệu kinh doanh quan trọng.
```

## Kiểm tra đã chạy được chưa

README không ghi lệnh kiểm tra cài đặt riêng cho người dùng cuối. Cách đơn giản và chắc chắn là thử import gói và in phiên bản:

```python
import onnx
print(onnx.__version__)
```

Nếu in ra một số phiên bản mà không báo lỗi, gói đã cài đúng vào môi trường Python bạn đang dùng. Nếu báo `ModuleNotFoundError`, xem phần lỗi thường gặp bên dưới.

Ngoài ra, README có phần kiểm thử dành cho người phát triển: cài pytest rồi chạy pytest.

```sh
pip install pytest
```

```sh
pytest
```

Lưu ý: lệnh `pytest` này dành cho người làm việc trong thư mục mã nguồn repo. Nếu bạn chỉ cài từ PyPI để dùng, bạn không cần chạy nó.

## Dùng vào việc thật

ONNX là hạ tầng, nên các tình huống dưới đây xoay quanh việc đọc, kiểm tra và hiểu mô hình. Mình bám vào những gì tư liệu nói.

> ONNX không phải app để bấm là chạy. Nó là “ngôn ngữ chung” để các công cụ AI hiểu nhau.
>
> — Ông T

### Lập trình viên đang chuyển mô hình từ thử nghiệm sang sản phẩm

Bạn là dev trong một công ty nhỏ. Nhóm dữ liệu huấn luyện mô hình bằng một framework, còn hệ thống của bạn chạy ở môi trường khác. Thay vì viết lại mô hình, nhóm xuất mô hình sang định dạng ONNX. Bạn cài gói `onnx`, mở file mô hình và kiểm tra nó theo đúng cách mà tài liệu Python API Overview trong repo mô tả:

```python
import onnx

model = onnx.load("model.onnx")
onnx.checker.check_model(model)
```

Đây là hai hàm nền tảng của gói onnx: nạp file mô hình và kiểm tra tính hợp lệ. Tên file `model.onnx` chỉ là ví dụ, bạn thay bằng file của mình. Nếu không có lỗi, mô hình đúng định dạng và sẵn sàng đưa sang công cụ khác.

### Người mới học AI muốn tìm mô hình có sẵn

Bạn mới học và chưa muốn huấn luyện gì cả. README trỏ tới các mô hình ONNX huấn luyện sẵn trên Hugging Face (onnx-community) và repo hướng dẫn onnx/tutorials. Bạn làm theo thứ tự: cài `onnx`, vào các trang đó để chọn mô hình hoặc bài hướng dẫn, rồi thử mở mô hình bằng cách ở trên. Kết quả là bạn có một mô hình thật trong tay để quan sát cấu trúc, chưa cần tự huấn luyện.

### Kỹ sư cần hiểu một mô hình dùng toán tử nào

Một mô hình báo lỗi ở công cụ khác vì thiếu hỗ trợ một toán tử. Bạn mở trang Operators trong tài liệu ONNX (có cả bản của phiên bản phát hành mới nhất) để tra từng toán tử và các phiên bản của nó. Nếu mô hình đang ở opset cũ, README cho biết 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. Kết quả là bạn biết lỗi nằm ở đâu thay vì đoán mò.

### Người đóng góp cho cộng đồng

Bạn thấy chuẩn còn thiếu một toán tử cần cho công việc. README hướng dẫn đọc tài liệu AddNewOp.md trong thư mục docs để biết quy trình đề xuất toán tử mới, và CONTRIBUTING.md để biết cách đóng góp mã. Bạn cũng có thể mở Issue hoặc tham gia thảo luận trên Slack của LF AI Foundation. Kết quả là ý kiến của bạn đi vào đúng kênh của dự án.

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

README không liệt kê lỗi cụ thể ở phần cài đặt, nó chỉ trỏ tới INSTALL.md cho phần “Common Errors”. Dưới đây là những lỗi rất dễ gặp với loại gói Python này.

### `ModuleNotFoundError: No module named 'onnx'`

Thường do cài vào một Python, nhưng chạy bằng Python khác (ví dụ có nhiều phiên bản trên máy, hoặc quên bật môi trường ảo). Cách xử lý: bật đúng môi trường ảo, rồi cài lại bằng `pip install onnx` và chạy lại lệnh import trong cùng môi trường đó.

### Pip không tìm thấy phiên bản phù hợp hoặc báo lỗi phiên bản Python

Repo yêu cầu Python 3.11 trở lên, và wheel abi3 nhắm tới Python 3.12 trở đi. Nếu máy bạn dùng Python cũ hơn, pip có thể không cài được. Cách xử lý: cài Python mới hơn rồi thử lại.

### Lỗi với dấu ngoặc vuông khi cài `onnx[reference]`

Một số terminal hiểu dấu `[` `]` theo nghĩa khác. Bọc cả cụm `onnx[reference]` trong dấu nháy rồi chạy lại. Nếu không cần bản reference, dùng `pip install onnx` là đủ.

### Lỗi khi build từ mã nguồn

Cài từ mã nguồn phức tạp hơn cài bằng pip, vì có các tùy chọn build riêng. Nếu bạn gặp lỗi ở bước này, đừng thử các lệnh lấy từ nơi lạ. Mở INSTALL.md trong repo để xem tùy chọn build và phần lỗi thường gặp. Với người mới, quay lại cách cài bằng pip là hướng an toàn nhất.

### Mô hình không kiểm tra được hoặc công cụ khác không đọc được

Nguyên nhân hay là mô hình dùng opset hoặc toán tử mà công cụ đích chưa hỗ trợ. Cách xử lý: tra trang Operators, xem tài liệu chuyển đổi phiên bản opset của repo, và đối chiếu danh sách công cụ hỗ trợ trên onnx.ai.

## 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ợ, và dự án đang được duy trì. Cài đặt chỉ một lệnh pip. Tài liệu đặc tả (IR, toán tử, phiên bản) khá đầy đủ, hợp để học và làm việc nghiêm túc.

Giới hạn: đây không phải ứng dụng dùng ngay cho người không biết lập trình. Theo README, dự án hiện tập trung vào suy luận, nên nếu bạn cần huấn luyện mô hình thì vẫn phải dùng framework khác rồi xuất sang ONNX. README cũng không ghi rõ hệ điều hành hỗ trợ hay yêu cầu phần cứng, bạn cần xem INSTALL.md hoặc tài liệu trên onnx.ai khi cần chắc chắn.

Nên chọn nó khi bạn cần chuyển hoặc chia sẻ mô hình giữa các công cụ, hoặc muốn hiểu định dạng mà nhiều hệ thống AI đang dùng. Nếu bạn chỉ muốn một công cụ AI để hỏi đáp hay viết văn bản, ONNX không phải thứ bạn cần cài. Hãy tìm một ứng dụng hoàn chỉnh thay vì thư viện định dạng này.

## 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 onnx được phát hành trên PyPI để cài bằng pip. README không nhắc đến phí hay gói trả tiền nào.

### Cài ONNX có cần GPU hoặc API key không?

README không yêu cầu GPU hay API key cho việc cài gói onnx. Bạn chỉ cần Python và pip. Nếu bạn dùng mô hình nặng ở công cụ khác thì yêu cầu phần cứng tùy công cụ đó, và tư liệu ở đây chưa nói về việc này.

### Cần phiên bản Python nào?

File pyproject.toml của repo yêu cầu Python 3.11 trở lên. README còn nói gói có wheel abi3, dùng được trên nhiều phiên bản Python từ 3.12 trở đi. Cách chắc ăn là dùng Python mới.

### ONNX chạy được trên Windows không?

Tư liệu trong README không liệt kê hệ điều hành cụ thể. Gói được phát hành trên PyPI và cài bằng pip. Nếu gặp vấn đề trên máy của bạn, hãy xem INSTALL.md trong repo để biết các tùy chọn build và lỗi thường gặp.

### ONNX khác gì PyTorch hay scikit-learn?

PyTorch và scikit-learn là framework để xây dựng mô hình. ONNX là định dạng mở để lưu và trao đổi mô hình giữa các framework và công cụ. README nói hiện tại ONNX tập trung vào khả năng cần cho suy luận (chấm điểm).

### Dữ liệu của tôi có an toàn khi dùng ONNX không?

README không nói về việc gửi dữ liệu ra ngoài. Gói onnx là thư viện cài trên máy bạn, nên việc xử lý diễn ra ở máy bạn. Repo có file SECURITY.md để xem chính sách bảo mật, nhưng tư liệu ở đây chưa có thêm chi tiết.

### Tôi muốn đóng góp hoặc đề xuất toán tử mới thì làm thế nào?

README hướng dẫn đọc CONTRIBUTING.md để bắt đầu đóng góp. Nếu muốn thêm toán tử mới vào đặc tả, hãy đọc tài liệu AddNewOp.md. Bạn cũng có thể mở Issue hoặc tham gia thảo luận trên Slack của LF AI Foundation.
