Integration Amazon S3

Tích hợp Amazon S3 kết nối các bucket S3 của bạn với Ultralytics Platform. Ảnh vẫn nằm trong bucket của bạn — Platform lập chỉ mục tại chỗ, cho phép bạn duyệt, gán nhãn và huấn luyện model YOLO mà không cần tải lên bản sao. Khi bật AI features, Platform cũng có thể sử dụng ảnh để gán nhãn thông minh, tự động gán nhãn, tìm kiếm ảnh tương tự và huấn luyện trên đám mây.

Tạo người dùng IAM#

Quyền đọc đáp ứng mọi nhu cầu ngoại trừ tạo ảnh, thao tác này cũng tạo object. Platform không bao giờ sửa đổi hoặc xóa object của bạn. Sử dụng một người dùng IAM chuyên dụng — tuyệt đối không dùng thông tin xác thực root:

1. Trong AWS console, vào IAM > Users và tạo user không có quyền truy cập console.

2. Gắn chính sách cấp quyền liệt kê và đọc cho các bucket bạn muốn kết nối:

   {
       "Version": "2012-10-17",
       "Statement": [
           { "Effect": "Allow", "Action": "s3:ListAllMyBuckets", "Resource": "*" },
           {
               "Effect": "Allow",
               "Action": ["s3:ListBucket", "s3:GetObject"],
               "Resource": ["arn:aws:s3:::my-bucket", "arn:aws:s3:::my-bucket/*"]
           }
       ]
   }

   s3:ListAllMyBuckets là tùy chọn — token này cho phép Platform tìm các bucket để bạn không phải nhập tên bucket.

   Để tạo ảnh, hãy cho phép thêm s3:PutObject:

   {
       "Effect": "Allow",
       "Action": "s3:PutObject",
       "Resource": [
           "arn:aws:s3:::my-bucket/generated/*",
           "arn:aws:s3:::my-bucket/*/generated/*",
           "arn:aws:s3:::my-bucket/.ultralytics-write-check"
       ]
   }

   S3 không có quyền chỉ tạo mới, vì vậy quyền ghi được giới hạn trong các thư mục generated/ và khóa .ultralytics-write-check mà Platform dùng để kiểm tra quyền ghi (yêu cầu kiểm tra này luôn bị từ chối nên không có dữ liệu nào được lưu). Các thao tác ghi của Platform không bao giờ ghi đè.

3. Mở tab Security credentials của user, tạo access key, rồi sao chép access key ID và secret access key.

Kết nối với Platform#

1. Vào Settings > Integrations và chọn Amazon S3 trong danh sách integration.
2. Nhập access key ID, secret access key và region của bucket (ví dụ: us-east-1).
3. Nhấp Find available buckets, rồi chọn các bucket cần kết nối. Nếu policy không cho phép khám phá bucket, hãy nhập thủ công tên một bucket đã biết.
4. Nhấp Connect. Platform xác minh khả năng liệt kê và đọc từng bucket đã chọn trước khi lưu bất kỳ nội dung nào, đồng thời kiểm tra xem khóa có thể ghi vào bucket hay không bằng một yêu cầu mà S3 luôn từ chối, vì vậy không có dữ liệu nào được lưu.

Mỗi thông tin xác thực đã kết nối có công tắc AI features. Sau khi thay đổi chính sách IAM, hãy kết nối lại cùng người dùng IAM để kiểm tra lại quyền ghi.

Bạn cần có vai trò admin hoặc owner của workspace để kết nối bộ lưu trữ đám mây. Mỗi lần, bạn có thể thêm tối đa 50 bucket; tính năng khám phá liệt kê tối đa 300 bucket mà khóa có thể truy cập.

Khi kết nối lại cùng IAM user sau này, các bucket mới sẽ được thêm vào integration hiện có. Thông tin xác thực đã lưu chỉ được thay thế khi thông tin mới vẫn có thể đọc tất cả bucket bạn đã kết nối. Nếu không thể đọc bucket nào, thông báo lỗi sẽ nêu tên bucket đó, kể cả các bucket đã kết nối trước đó bằng cùng IAM user.

AI Features#

Mỗi thông tin xác thực đã kết nối có công tắc AI features trong Settings > Integrations, mặc định được bật. Khi bật, GPU của Ultralytics và các nhà cung cấp model AI có thể sử dụng ảnh thuộc thông tin xác thực đó để:

• Gán nhãn thông minh SAM và tự động gán nhãn cho một ảnh hoặc theo batch
• Tìm kiếm ảnh tương tự và phân tích clustering
• Huấn luyện trên đám mây
• Tạo ảnh, trên các bucket có quyền ghi

Các nhà cung cấp model AI chỉ tham gia vào quá trình tạo hình ảnh, trong đó Google Gemini lập kế hoạch prompt từ ảnh nguồn, và các model gán nhãn trả phí, chạy bằng khóa nhà cung cấp của chính workspace bạn. Platform không lưu bản sao hình ảnh: các tính năng đọc hình ảnh theo yêu cầu, tính năng huấn luyện trên đám mây dùng bản sao tạm thời trong suốt thời gian chạy, còn tính năng tìm kiếm hình ảnh tương tự lưu embedding của từng ảnh và xóa embedding khi ảnh rời khỏi Platform.

Tắt công tắc để ngăn ảnh được đưa lên GPU của Ultralytics và các nhà cung cấp model AI. Tắt công tắc sẽ ngăn các tác vụ AI mới; các tác vụ đang chạy sẽ hoàn tất. Dataset sử dụng thông tin xác thực đó sẽ hiển thị AI features off cùng liên kết đến phần cài đặt này, và từng tính năng không khả dụng sẽ giải thích lý do. Gán nhãn thủ công, chia sẻ và huấn luyện cục bộ vẫn hoạt động; các nhãn, model và kết quả tìm kiếm bạn đã tạo vẫn được giữ lại.

Bạn cần có vai trò quản trị viên hoặc chủ sở hữu trong workspace để thay đổi trạng thái của công tắc. Bạn cũng có thể thiết lập tùy chọn này bằng REST API, sử dụng ID tích hợp do GET /api/integrations/buckets trả về:

curl -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"processing": false}' \
  https://platform.ultralytics.com/api/integrations/buckets/INTEGRATION_ID

Tạo ảnh#

Tạo ảnh tương tự hoạt động trên dataset Amazon S3 có bucket mà người dùng IAM có quyền ghi, khi AI features được bật. Ảnh bạn thêm sẽ được ghi vào thư mục generated/ bên trong thư mục của dataset, sau đó được thêm vào dataset như mọi ảnh đã lập chỉ mục khác. Platform chỉ tạo object mới tại đó, không bao giờ ghi đè hoặc xóa object hiện có. Nếu thao tác thông báo cần quyền ghi, hãy cấp quyền nếu cần rồi kết nối lại cùng người dùng IAM trong Settings > Integrations.

Tạo dataset từ bucket S3#

1. Nhấp vào New Dataset rồi mở tab Cloud.
2. Chọn một bucket đã kết nối rồi duyệt đến thư mục chứa dữ liệu của bạn.
3. Xác nhận thư mục, điều chỉnh tên dataset rồi tạo dataset.

Platform liệt kê thư mục một lần rồi lập chỉ mục những gì tìm thấy:

• Ảnh — các object .jpg, .jpeg, .png, .webp và .avif được lập chỉ mục; kích thước được đọc bằng các request có giới hạn. Platform không lưu thêm bản sao của ảnh nguồn.
• Nhãn — các sidecar YOLO .txt được phân tích thành annotation trên Platform, khớp theo cấu trúc chuẩn images/ → labels/ hoặc theo các file cùng thư mục.
• Metadata — file YAML cung cấp tên class và hình dạng keypoint của pose, giống hệt như khi tải lên archive. Ưu tiên data.yaml và data.yml nếu thư mục chứa nhiều file.
• Tác vụ — hệ thống xác định tác vụ bằng cách lấy mẫu các file nhãn, nhờ đó nhận diện thư mục segment, pose và OBB dựa trên cấu trúc nhãn thay vì tác vụ bạn chọn trong hộp thoại.
• Các tập dữ liệu — Tên thư mục train, val và test trong object key sẽ tự động gán các tập dữ liệu.

Sau đó, dataset hoạt động như mọi dataset khác: duyệt và gán nhãn, đặt ở chế độ công khai hoặc riêng tư, chia sẻ với team và huấn luyện bằng dịch vụ huấn luyện được quản lý. Ảnh gốc được truyền theo yêu cầu và ảnh đã lập chỉ mục không tính vào hạn mức lưu trữ trên Platform.

Import thất bại#

Nếu quá trình import thất bại — do thư mục trống, đường dẫn sai chính tả hoặc quyền truy cập bị thu hồi — dataset sẽ hiển thị lỗi trên trang của dataset. Editor có thể nhấp Retry import để khởi động lại bằng bucket và thư mục đã lưu, hoặc tạo dataset mới trỏ đến đường dẫn đã sửa.

Khi thử lại, hệ thống sẽ liệt kê lại thư mục thay vì tiếp tục từ điểm dừng: các đối tượng được thêm kể từ lần thử đầu tiên sẽ được lấy vào, còn các đối tượng không còn ở đó sẽ bị loại khỏi dataset.

Huấn luyện#

Huấn luyện được quản lý hoạt động theo quy trình huấn luyện thông thường khi AI features được bật. Trong suốt thời gian chạy, quá trình huấn luyện sử dụng các bản sao riêng của Platform từ những ảnh đã ghim; thông tin xác thực AWS của bạn không bao giờ bị lộ cho workload huấn luyện. Khi tắt AI features, hộp thoại huấn luyện giải thích lý do không khả dụng tính năng huấn luyện trên đám mây và đề xuất huấn luyện cục bộ.

Ngắt kết nối#

Ngắt kết nối sẽ xóa thông tin xác thực đã lưu mà không tác động đến bất kỳ nội dung nào trong AWS. Các dataset được tạo từ những bucket đó vẫn nằm trong workspace của bạn cùng với class, nhãn và chú thích, nhưng không thể tải, xem trước hoặc dùng ảnh để training cho đến khi kết nối lại cùng IAM user. Khi đã ngắt kết nối, bạn vẫn có thể đổi tên dataset, chỉnh sửa nhãn hoặc xóa dataset.

Để ngắt kết nối, vào Settings > Integrations, chọn Amazon S3, nhấp Disconnect bên cạnh thông tin xác thực rồi xác nhận. Khi mở một trong các dataset đó, bạn sẽ thấy Amazon S3 Disconnected cùng liên kết quay lại phần cài đặt này; dataset sẽ tự động hoạt động trở lại khi bạn kết nối lại.

Bạn cũng có thể ngắt kết nối bằng REST API, sử dụng ID integration do GET /api/integrations/buckets trả về:

curl -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/integrations/buckets/INTEGRATION_ID

from ultralytics_platform import Platform

client = Platform()  # reads ULTRALYTICS_API_KEY
integrations = client.storage_integrations.list()
client.storage_integrations.delete("INTEGRATION_ID")

Thay vào đó, để thu hồi quyền truy cập từ phía nguồn, hãy vô hiệu hóa hoặc xóa access key trong AWS IAM.

Các giới hạn hiện tại#

Dataset dùng S3 không hỗ trợ các tính năng cần bản sao ảnh do Platform sở hữu: sao chép dataset, snapshot phiên bản bất biến, làm mờ khuôn mặt và dán ảnh từ dataset khác. Gán nhãn thông minh, tự động gán nhãn, tìm kiếm ảnh tương tự, phân cụm, huấn luyện trên đám mây và tạo ảnh cần bật AI features.

Khi xóa dataset dùng S3 hoặc từng ảnh riêng lẻ trong dataset, Platform chỉ xóa các tham chiếu của mình — các đối tượng của bạn không bị tác động.

Xem thêm các integration Google Cloud Storage và Azure Blob Storage.

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