API Keys

Các API keys trên Ultralytics Platform cho phép truy cập theo chương trình một cách bảo mật cho việc huấn luyện từ xa, suy luận (inference) và tự động hóa. Hãy tạo các key có tên với mã hóa AES-256-GCM cho các mục đích sử dụng khác nhau.

Tạo API Key

Tạo một API key mới:

1. Đi tới Settings > API Keys
2. Nhấp vào Create Key
3. Nhập tên cho key (ví dụ: "Training Server")
4. Nhấp vào Create Key

Tên Key

Đặt cho key của bạn một cái tên mô tả:

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

Hiển thị Key

Sau khi tạo, key được hiển thị một lần duy nhất:

Định dạng Key

Các API keys tuân theo định dạng này:

• Tiền tố (Prefix): ul_ để xác định các key của Ultralytics
• Phần thân (Body): 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

• Các key được lưu trữ với mã hóa AES-256-GCM
• Xác thực sử dụng hàm băm SHA-256 để tra cứu tiền tố nhanh và so sánh hàm băm
• Các giá trị key đầy đủ không bao giờ được lưu trữ dưới dạng văn bản thuần (plaintext)

Sử dụng API Keys

Biến môi trường

Thiết lập key của bạn dưới dạng biến môi trường:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI

Thiết lập key bằng YOLO CLI:

yolo settings api_key="YOUR_API_KEY"

Trong Code

Sử dụng key trong các script Python của bạn:

import os

# From environment (recommended)
api_key = os.environ.get("ULTRALYTICS_API_KEY")

# Or directly (not recommended for production)
api_key = "YOUR_API_KEY"

HTTP Headers

Bao gồm key trong các yêu cầu API:

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

Xem REST API Reference cho tất cả các endpoint khả dụng.

Remote Training

Bật tính năng truyền phát số liệu (metric streaming) bằng key của bạn.

pip install "ultralytics>=8.4.35"

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

Xem Cloud Training để biết hướng dẫn huấn luyện từ xa đầy đủ.

Quản lý Keys

Xem các Key

Tất cả cá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 đã giải mã đầy đủ (có thể sao chép), thời gian tạo tương đối và nút thu hồi (revoke).

Thu hồi Key

Thu hồi một key nếu 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 (Regenerate) Key

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

1. Tạo một 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 Keys không gian làm việc (Workspace)

Các API keys được phân theo không gian làm việc hiện đang hoạt động:

• Không gian làm việc cá nhân: Các 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: Các key xác thực trong bối cảnh nhóm

Khi chuyển đổi giữa các không gian làm việc trong thanh bên, phần API Keys sẽ hiển thị các key cho không gian làm việc đó. Vai trò Editor trở lên là bắt buộc để quản lý các API keys của không gian làm việc. Xem Teams để biết chi tiết về vai trò.

Các thực tiễn bảo mật tốt nhất

Nên

• Lưu trữ các key trong biến môi trường
• Sử dụng các key riêng biệt cho các môi trường khác nhau
• Thu hồi các key không sử dụng ngay lập tức
• Luân phiên (Rotate) các key định kỳ
• Sử dụng tên mô tả để xác định mục đích của key

Không nên

• Commit các key vào hệ thống quản lý phiên bản (version control)
• Chia sẻ các key giữa các ứng dụng
• Ghi log các key trong kết quả đầu ra của ứng dụng
• Nhúng các key vào code phía client

Luân phiên Key

Luân phiên các key định kỳ để 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ệ

Giải pháp:

1. Xác minh key được sao chép chính xác (bao gồm cả 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 ultralytics>=8.4.35

Từ chối quyền (Permission Denied)

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 không gian làm việc phù hợp
2. Kiểm tra xem key có thuộc về không gian làm việc chính xác hay không
3. Tạo một key mới nếu cần

Giới hạn tỷ lệ (Rate Limited)

Giải pháp:

1. Giảm tần suất yêu cầu — xem bảng giới hạn tỷ lệ để biết giới hạn cho mỗi endpoint
2. Triển khai exponential backoff sử dụng header Retry-After
3. Sử dụng một endpoint chuyên dụng cho thông lượng suy luận không giới hạn

Câu hỏi thường gặp (FAQ)

Tôi có thể tạo bao nhiêu key?

Không có giới hạn cứng đối với số lượng API keys. Hãy tạo bao nhiêu tùy ý cho các ứng dụng và môi trường khác nhau.

Các key có hết hạn không?

Các khóa không tự động hết hạn. Chúng vẫn có hiệu lực cho đến khi bị thu hồi. Hãy cân nhắc việc xoay vòng khóa để đảm bảo tính bảo mật.

Tôi có thể xem khóa của mình sau khi tạo không?

Có, giá trị đầy đủ của khóa có thể được nhìn thấy trong danh sách khóa tại Settings > API Keys. Nền tảng sẽ giải mã và hiển thị các khóa để bạn có thể sao chép chúng bất cứ lúc nào.

Khóa có giới hạn theo vùng không?

Khóa hoạt động trên các vùng nhưng chỉ truy cập dữ liệu trong vùng tài khoản của bạn.

Tôi có thể chia sẻ khóa với các thành viên trong nhóm không?

Cách làm tốt hơn: Yêu cầu mỗi thành viên trong nhóm tự tạo khóa riêng. Đối với không gian làm việc nhóm, mỗi thành viên có vai trò Editor trở lên đều có thể tạo khóa giới hạn trong phạm vi không gian làm việc đó.