API key#

API key của Ultralytics Platform cho phép truy cập theo chương trình một cách an toàn để huấn luyện từ xa, suy luận và tự động hóa. Tạo các key có tên riêng, được mã hóa bằng AES-256-GCM cho từng trường hợp sử dụng.

Tạo API key#

Tạo API key mới:

1. Đi tới Settings > API Keys
2. Nhấp vào Add Key và chọn Ultralytics làm nhà cung cấp
3. Nhập tên cho key (ví dụ: "Training Server")
4. Nhấp vào Create Key

Tên key#

Đặt tên mô tả cho key:

• training-server - Dành cho máy huấn luyện từ xa
• ci-pipeline - Dành cho tích hợp CI/CD
• local-dev - Dành cho phát triển cục bộ

Hiển thị key#

Sau khi tạo, key sẽ hiển thị trong hộp thoại xác nhận:

Key của nhà cung cấp dành cho agent và gán nhãn#

Tab Settings > API Keys cũng lưu key cho các nhà cung cấp model bên ngoài được Agents sử dụng và các model trả phí trong gán nhãn theo prompt lớp; tính năng gán nhãn đọc key đã lưu trong không gian làm việc của dataset. Chỉ chủ sở hữu không gian làm việc mới có thể thêm, thay thế hoặc xóa các key này; thành viên nhóm có thể xem những nhà cung cấp nào đang được kết nối. Hãy yêu cầu chủ sở hữu kết nối nhà cung cấp còn thiếu. Để kết nối nhà cung cấp với tư cách chủ sở hữu:

1. Nhấp vào Add Key.
2. Chọn nhà cung cấp tương ứng với model ngôn ngữ hoặc thị giác-ngôn ngữ trong quy trình của bạn, hoặc model gán nhãn mà bạn muốn chạy.
3. Dán API key của nhà cung cấp vào API Key, sau đó nhấp vào Save Key. Liên kết Get an API key trong hộp thoại sẽ mở trang cấp key của nhà cung cấp.

Key Ultralytics không xác thực với các nhà cung cấp model bên ngoài. Chi phí sử dụng nhà cung cấp được tính qua tài khoản nhà cung cấp liên kết với key đã lưu. Dùng nút chỉnh sửa trên hàng key để thay thế key của nhà cung cấp.

Định dạng key#

API key có định dạng sau:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• Tiền tố: ul_ xác định key Ultralytics
• Phần thân: 40 ký tự thập lục phân ngẫu nhiên
• Tổng cộng: 43 ký tự

Bảo mật key#

• Key được lưu trữ bằng mã hóa AES-256-GCM, không bao giờ ở dạng văn bản thuần
• 11 ký tự đầu tiên (ul_ cộng với 8 ký tự thập lục phân) làm tiền tố hiển thị, giúp nhận diện key mà không để lộ key

Sử dụng API key#

Biến môi trường#

Đặt key làm biến môi trường:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

Xác thực và lưu key bằng YOLO CLI trên Python>=3.11:

yolo login YOUR_API_KEY

Xóa key đã lưu bằng yolo logout.

HTTP header#

Đưa key vào các yêu cầu API:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/...

Hoặc truyền key vào Python SDK (pip install "ultralytics-platform>=0.1.45"), SDK sẽ đọc ULTRALYTICS_API_KEY hoặc key được lưu bằng yolo login khi bỏ qua api_key:

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

Xem Tài liệu tham khảo REST API để biết tất cả endpoint hiện có.

Huấn luyện từ xa#

Bật tính năng truyền metric bằng key của bạn.

Cài đặt hoặc cập nhật gói Ultralytics trên Python>=3.11 trước khi bắt đầu:

pip install -U ultralytics

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

Xem Huấn luyện trên cloud để biết hướng dẫn đầy đủ về huấn luyện từ xa.

Quản lý key#

Xem key#

Tất cả key được liệt kê trong tab Settings > API Keys:

Mỗi hàng key hiển thị tên key, tiền tố key, ngày tạo, nút sao chép toàn bộ key và nút xóa (thùng rác).

Thu hồi key#

Thu hồi key đã bị xâm phạm hoặc không còn cần thiết:

1. Tìm key trong mục API Keys
2. Nhấp vào nút xóa (thùng rác)
3. Nhấp vào Remove Key để xác nhận

Tạo lại key#

Nếu key bị xâm phạm:

1. Tạo key mới với cùng tên
2. Cập nhật ứng dụng của bạn
3. Thu hồi key cũ

API key của không gian làm việc#

API key được giới hạn trong không gian làm việc đang hoạt động:

• Không gian làm việc cá nhân: Key xác thực với tư cách tài khoản cá nhân của bạn
• Không gian làm việc nhóm: Key xác thực với tư cách chủ sở hữu không gian làm việc nhóm, với đầy đủ quyền của chủ sở hữu trong không gian làm việc đó

Khi chuyển đổi không gian làm việc trong thanh bên, mục API Keys sẽ hiển thị key của không gian làm việc đó. Vì key của không gian làm việc có quyền của chủ sở hữu, chỉ chủ sở hữu không gian làm việc mới có thể tạo, xem hoặc thu hồi key. Xem Nhóm để biết chi tiết về vai trò.

Key worker On Premise#

Kết nối host On Premise sẽ cấp một key worker riêng. Key worker được quản lý từ tích hợp On Premise thay vì tab này, không bao giờ được liệt kê cùng API key của bạn và sẽ bị thu hồi khi ngắt kết nối host — thao tác này cũng hủy các job đang chờ và đang chạy của host đó.

Các biện pháp bảo mật tốt nhất#

Nên làm#

• Lưu key trong biến môi trường
• Sử dụng key riêng cho từng môi trường
• Nhanh chóng thu hồi các key không còn sử dụng
• Luân chuyển key định kỳ
• Dùng tên mô tả để xác định mục đích của key

Đừng#

• Commit key vào hệ thống quản lý phiên bản
• Chia sẻ key giữa các ứng dụng
• Ghi key vào output của ứng dụng
• Nhúng key vào mã phía client

Xoay vòng key#

Xoay vòng key định kỳ để bảo mật:

1. Tạo key mới với cùng tên
2. Cập nhật ứng dụng để sử dụng key mới
3. Xác minh ứng dụng hoạt động chính xác
4. Thu hồi key cũ

Khắc phục sự cố#

Lỗi key không hợp lệ#

Error: Invalid API key

Giải pháp:

1. Xác minh key được sao chép chính xác (bao gồm tiền tố ul_)
2. Kiểm tra xem key đã bị thu hồi chưa
3. Xác nhận biến môi trường đã được thiết lập
4. Đảm bảo bạn đang sử dụng Python>=3.11 và ultralytics>=8.4.120

Không có quyền truy cập#

Error: Permission denied for this operation

Giải pháp:

1. Xác minh bạn là chủ sở hữu tài nguyên hoặc có quyền truy cập workspace phù hợp
2. Kiểm tra key thuộc đúng workspace
3. Nếu bạn quản lý key trong workspace nhóm, hãy xác nhận bạn là chủ sở hữu workspace — các vai trò khác nhận được Workspace owner access required
4. Tạo key mới nếu cần

Bị giới hạn tốc độ#

Error: Rate limit exceeded

Giải pháp:

1. Giảm tần suất yêu cầu — xem bảng giới hạn tốc độ để biết giới hạn theo từng danh mục
2. Triển khai exponential backoff bằng header Retry-After
3. Sử dụng endpoint chuyên dụng khi bạn cần năng lực suy luận được tách biệt

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