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. Ảnh vẫn nằm trong bucket của bạn — Platform lập chỉ mục ngay tại chỗ, để bạn có thể duyệt, gán nhãn và huấn luyện 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ừ bộ nhớ của bạn — không bao giờ ghi, sửa đổi hoặc xóa object. Hãy tạo một service account riêng chỉ có quyền đọc:

1. Trong Google Cloud console, vào IAM & Admin > Service Accounts rồi tạo service account.
2. Cấp vai trò Storage Object Viewer (roles/storage.objectViewer) cho service account 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 file key xuống.

Kết nối với Platform#

1. Vào Settings > Integrations rồi chọn Google Cloud Storage trong danh sách tích hợp.
2. Dán nội dung của file key JSON của service account.
3. Nhấp vào Find available buckets, rồi 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 mà bạn đã biết.
4. Nhấp vào 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ỳ thông tin nào.

Bạn cần có vai trò admin hoặc owner của workspace để kết nối cloud storage. Bạn có thể thêm tối đa 50 bucket mỗi lần; quá trình dò tìm liệt kê tối đa 300 bucket mà service account có thể truy cập.

Trình duyệt đọc file key bạn 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.

Nếu 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ó. Thông tin xác thực đã lưu chỉ được thay thế khi thông tin thay thế vẫn có thể đọc mọi 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ả những bucket đã kết nối trước đây bằng cùng service account.

Tạo Dataset từ Bucket GCS#

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.
• Chia tập dữ liệu — tên thư mục train, val và test trong đường dẫn object 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#

Quy trình training được quản lý hoạt động thông qua luồng 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 ảnh đã được cố định phiên bản; thông tin xác thực Google Cloud của bạn không bao giờ bị lộ cho workload training.

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 Google Cloud. 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 service account. 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 Google Cloud Storage, 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 Google Cloud Storage 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 xóa khóa service account trong Google Cloud.

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

Dataset dùng GCS hiện không hỗ trợ các tính năng cần bản sao ảnh do Platform quản lý: tự động gán nhãn, phân tích phân cụm, sao chép dataset và ảnh chụp phiên bản bất biến.

Khi xóa dataset dùng GCS 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 Amazon S3 và Azure Blob Storage.

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