Tích hợp Google Cloud Storage#

Tích hợp Google Cloud Storage kết nối các bucket GCS của bạn với Ultralytics Platform. Hình ảnh vẫn nằm trong các bucket của bạn — Platform lập chỉ mục trực tiếp tại đó, vì vậy bạn có thể duyệt, chú thích và train các model YOLO mà không cần tải lên một bản sao.

Tạo Service Account chỉ có quyền đọc#

Platform chỉ đọc dữ liệu từ storage của bạn — không bao giờ ghi, sửa đổi hoặc xóa các object. Hãy tạo một service account riêng chỉ có quyền đọc:

1. Trong Google Cloud console, hãy vào IAM & Admin > Service Accounts và tạo một service account.
2. Gán cho service account vai trò Storage Object Viewer (roles/storage.objectViewer) trên các bucket bạn muốn kết nối.
3. Mở service account, chọn Keys > Add key > Create new key, chọn JSON rồi tải xuống file key.

Kết nối với Platform#

1. Vào Settings > Integrations và chọn Google Cloud Storage từ danh sách tích hợp.
2. Dán nội dung của JSON key cho service account.
3. Nhấp Find available buckets, sau đó chọn các bucket cần kết nối. Nếu service account không thể liệt kê bucket, hãy nhập thủ công tên một bucket đã biết.
4. Nhấp Connect. Platform xác minh rằng có thể liệt kê và đọc từng bucket đã chọn trước khi lưu bất kỳ thông tin nào.

Bạn cần có vai trò quản trị viên hoặc chủ sở hữu workspace để kết nối cloud storage. Một kết nối hỗ trợ tối đa 50 bucket, và tính năng tìm bucket liệt kê tối đa 300 bucket mà service account có thể xem.

Trình duyệt của bạn đọc file key đã dán và chỉ gửi ba trường Platform cần — client_email, private_key, và project_id. Phần còn lại của JSON không bao giờ rời khỏi trang.

Khi kết nối lại cùng service account sau này, các bucket mới sẽ được thêm vào tích hợp hiện có. Credential đã lưu chỉ được thay thế khi credential mới vẫn có thể đọc mọi bucket bạn đã kết nối trước đó.

Tạo Dataset từ Bucket GCS#

1. Nhấp New Dataset và mở tab Cloud.
2. Chọn một bucket đã kết nối và 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 và lập chỉ mục các nội dung tìm thấy:

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

Dataset sau đó hoạt động như mọi dataset khác: duyệt và annotate, đặt ở chế độ public hoặc private, chia sẻ với team của bạn và train trên đó thông qua managed training. Các file gốc được stream theo nhu cầu, và hình ảnh đã lập chỉ mục không tiêu tốn storage quota của Platform.

Import thất bại#

Nếu một lần import thất bại — do thư mục trống, sai đường dẫn hoặc quyền đã 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 một dataset mới trỏ đến đường dẫn đã chỉnh sửa.

Thao tác retry sẽ liệt kê lại thư mục thay vì tiếp tục từ vị trí trước đó: các object được thêm từ lần thử đầu tiên sẽ được lấy vào, còn các object không còn tồn tại sẽ bị loại khỏi dataset.

Training#

Managed training hoạt động thông qua quy trình training thông thường. Trong suốt thời gian chạy, training sử dụng các bản sao riêng của Platform từ những hình ảnh đã được cố định, và credential Google Cloud của bạn không bao giờ bị lộ cho các workload training.

Ngắt kết nối một Connection#

Việc ngắt kết nối sẽ xóa credential đã lưu mà không tác động đến bất kỳ dữ liệu nào trong Google Cloud. Các dataset được tạo từ những bucket đó vẫn nằm trong workspace của bạn cùng class, label và annotation, nhưng không thể tải, xem trước hoặc train trên hình ảnh cho đến khi service account tương tự được kết nối lại.

Sử dụng REST API với integration ID 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")

Nếu muốn thu hồi quyền truy cập trực tiếp tại nguồn, hãy xóa key của service account trong Google Cloud.

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

Các dataset được hỗ trợ bởi GCS hiện không bao gồm những tính năng yêu cầu Platform sở hữu bản sao hình ảnh của bạn: tự động chú thích, phân tích clustering, nhân bản dataset và snapshot phiên bản bất biến.

Xóa dataset được hỗ trợ bởi GCS hoặc từng hình ảnh trong đó chỉ xóa các tham chiếu của Platform — các object của bạn không bao giờ bị tác động.

Xem thêm các tích hợp Amazon S3 và Azure Blob Storage.

FAQ#