API Keys#

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

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 được hiển thị trong hộp thoại xác nhận:

Provider Keys cho các Agents#

Tab Settings > API Keys tương tự cũng lưu trữ các khóa cho các nhà cung cấp model bên ngoài được sử dụng bởi Agents. Chỉ chủ sở hữu workspace mới có thể thêm, thay thế hoặc xóa các khóa này; các thành viên trong nhóm có thể xem nhà cung cấp nào đã được kết nối. 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 là chủ sở hữu:

1. Nhấp vào Add Key.
2. Chọn nhà cung cấp khớp với ngôn ngữ hoặc vision-language model trong luồng công việc của bạn.
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 của hộp thoại sẽ mở trang khóa của nhà cung cấp.

Một khóa Ultralytics không xác thực các nhà cung cấp model bên ngoài. Việc sử dụng nhà cung cấp được lập hóa đơn thông qua tài khoản nhà cung cấp liên kết với khóa đã lưu. Sử dụng điều khiển chỉnh sửa của hàng khóa để thay thế khóa nhà cung cấp.

Định dạng key#

API key tuân theo định dạng sau:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• Tiền tố: ul_ xác định các key của 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 túy
• 11 ký tự đầu tiên (ul_ cộng với 8 ký tự hex) đóng vai trò là tiền tố hiển thị, vì vậy có thể nhận diện key mà không làm 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 khóa bằng cách sử dụng YOLO CLI trên Python>=3.11:

yolo login YOUR_API_KEY

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

HTTP Headers#

Đưa key vào các request API:

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

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

from ultralytics_platform import Platform

client = Platform(api_key="YOUR_API_KEY")

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

Training từ xa#

Bật tính năng streaming 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 Cloud Training để đọc 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ê trên tab Settings > API Keys:

Mỗi thẻ key hiển thị tên key, giá trị key có thể sao chép, thời điểm tạo tương đối và nút thu hồi.

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 phần API Keys
2. Nhấp vào nút Revoke (thùng rác)
3. Xác nhận thu hồi

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 các ứng dụng của bạn
3. Thu hồi key cũ

API Key của workspace#

API key được giới hạn trong workspace hiện đang hoạt động:

• Workspace cá nhân: Key xác thực dưới danh nghĩa tài khoản cá nhân của bạn
• Team workspace: Key xác thực dưới danh nghĩa chủ sở hữu team workspace, với đầy đủ quyền của chủ sở hữu trong workspace đó

Khi chuyển workspace trong sidebar, phần API Keys sẽ hiển thị các key của workspace đó. Vì key của workspace mang quyền của chủ sở hữu, chỉ chủ sở hữu workspace mới có thể tạo, xem hoặc thu hồi key. Xem Teams để biết chi tiết về vai trò.

On Premise Worker Key#

Kết nối một host On Premise sẽ tạo một worker key riêng. Worker key đượ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 với API key của bạn và được thu hồi bằng cách ngắt kết nối host — thao tác này cũng hủy các job đang xếp hàng và đang chạy của host đó.

Best Practices về bảo mật#

Nên làm#

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

Không nên làm#

• Commit key vào hệ thống quản lý phiên bản
• Dùng chung key giữa các ứng dụng
• Ghi key vào output của ứng dụng
• Nhúng key vào code phía client

Rotate key#

Định kỳ rotate key để tăng cường bảo mật:

1. Tạo key mới với cùng tên
2. Cập nhật các ứng dụng để sử dụng key mới
3. Xác minh các ứ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 key chưa bị thu hồi
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

Từ chối 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 resource 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 đang quản lý key trong team workspace, hãy xác nhận bạn là chủ sở hữu workspace — các vai trò khác sẽ nhận Workspace owner access required
4. Tạo key mới nếu cần

Bị giới hạn tần suất#

Error: Rate limit exceeded

Giải pháp:

1. Giảm tần suất request — xem bảng giới hạn tần suất để 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 một endpoint chuyên dụng khi bạn cần năng lực inference tách biệt

FAQ#