Registry

Registry là danh mục chung chứa các phiên bản artifact tốt nhất của bạn. Một project liệt kê các artifact do các thí nghiệm của bạn tạo ra; một registry liệt kê các artifact được chọn giữa các project.

Một registry chứa các collections. Mỗi collection đại diện cho một tài sản — một mô hình bạn huấn luyện lại theo thời gian, một bộ đánh giá chuẩn — và giữ các phiên bản của nó mà bạn đã chọn để phát hành. Bạn link một phiên bản artifact vào một collection. Một link là con trỏ đến phiên bản nguồn: không có gì được sao chép. Sau đó, bạn thăng tiến một phiên bản đã link qua các giai đoạn vòng đời bằng cách di chuyển các alias như staging và production.

Ví dụ, một registry có tên models có thể chứa một collection cho mỗi model có thể triển khai, và một registry có tên datasets chứa một collection cho mỗi benchmark. Cách bạn chia các tài sản giữa các registry và collection là do bạn quyết định.

Một collection có dòng phiên bản riêng (v0, v1, …) độc lập với số phiên bản của các source artifacts, và các phiên bản của nó có thể trỏ đến các source artifacts khác nhau trong các dự án khác nhau. Alias đặt tên cho đúng một phiên bản cho mỗi collection.

Một registry có thể là cục bộ — được lưu trữ cạnh dữ liệu Trackio khác của bạn dưới dạng một project có tên registry-models (tiền tố registry- được dành riêng) — hoặc được hỗ trợ bởi một bucket Hugging Face, đây là yếu tố giúp registry có thể được truy cập từ các máy khác và từ các run ghi log vào một Space. Xem Remote registries.

Tạo một registry

Tạo một registry bằng Api.create_registry():

import trackio

registry = trackio.Api().create_registry("models", description="Our deployable models")

description tùy chọn được lưu trữ trên registry và có thể đọc được dưới dạng registry.description.

Các registry không bao giờ được tạo ra một cách ngầm. Việc liên kết vào một registry không tồn tại sẽ gây ra lỗi.

Sử dụng Api.registry() để lấy một registry hiện có. Nó cũng sẽ gây ra lỗi nếu registry không tồn tại.

Tạo một bộ sưu tập

Một collection là một tập hợp các phiên bản artifact liên kết với nhau trong một registry, có một lịch sử phiên bản duy nhất. Các phiên bản có thể đến từ các artifact nguồn khác nhau: nếu một model dựa trên resnet và một model dựa trên unet là các ứng viên cho cùng một sản phẩm có thể triển khai, hãy liên kết chúng vào một collection và chúng sẽ trở thành các phiên bản kế tiếp của nó. Nếu chúng là các sản phẩm riêng biệt, hãy cấp cho mỗi sản phẩm một collection riêng.

Bạn thường không tạo bộ sưu tập thủ công: việc liên kết vào một bộ sưu tập chưa tồn tại sẽ tự động tạo ra nó. Hãy tạo một bộ sưu tập một cách rõ ràng khi bạn muốn đặt mô tả ngay từ đầu:

registry.create_collection("my-model", "model", description="The model we deploy")

Các kiểu tập hợp

Mỗi collection chấp nhận một type duy nhất của artifact, được cố định khi collection được tạo. Type này đến từ chính artifact — trường type bạn truyền vào trackio.Artifact hoặc trackio.log_artifact — do đó, một collection được tạo bởi liên kết đầu tiên sẽ kế thừa type của artifact đó.

Ví dụ, nếu bạn liên kết một artifact "dataset" vào một collection chấp nhận các artifact "model", Trackio sẽ gây ra một lỗi.

Bản thân registry chấp nhận mọi loại: một bộ sưu tập model và một bộ sưu tập dataset có thể cùng tồn tại trong cùng một registry.

Liên kết một phiên bản artifact với một bộ sưu tập

Xuất bản một phiên bản artifact bằng Run.link_artifact():

import trackio

trackio.Api().create_registry("models")

run = trackio.init(project="my-experiments")
artifact = trackio.log_artifact("model.pt", name="resnet", type="model")

run.link_artifact(artifact, "registry-models/my-model", aliases=["staging"])

Đường dẫn đích là "registry-<registry>/<collection>". Đoạn đầu tiên là tên đầy đủ của registry, bao gồm cả tiền tố.

link_artifact nhận chính đối tượng artifact, nên phiên bản bạn đang giữ chính là phiên bản được phát hành:

Bạn cũng có thể liên kết từ chính artifact bằng Artifact.link(), rất tiện lợi khi run không nằm trong phạm vi:

artifact.link("registry-models/my-model", aliases=["staging"])

Artifact.link yêu cầu artifact đã được ghi log hoặc tải về trước đó — nó sẽ không tự động ghi log bản nháp cho bạn — và liên kết không ghi nhận bất kỳ phiên phát hành nào.

Sản phẩm được liên kết

link_artifact trả về artifact tại vị trí registry của nó. name của nó là collection, project của nó là registry, và version cùng aliases của nó là của collection. Nội dung của nó — manifest, manifest_digest, size, metadata — là của phiên bản nguồn, và các thuộc tính source_project, source_name, source_version, cùng source_qualified_name trỏ ngược lại phiên bản đó:

linked = run.link_artifact(artifact, "registry-models/my-model")
linked.qualified_name         # "registry-models/my-model:v0"
linked.source_qualified_name  # "my-experiments/resnet:v0"

Việc liên kết một artifact đã được liên kết sẽ liên kết trực tiếp đến phiên bản nguồn của nó (kèm theo cảnh báo), do đó các liên kết không bao giờ được nối tiếp.

Người dùng giải quyết vị trí registry trực tiếp bằng use_artifact, mà không cần biết dự án hay artifact nào đã tạo ra nó:

model = run.use_artifact("registry-models/my-model:production")
model.download()  # fetches the source version's files

Spec sau collection chấp nhận một phiên bản collection ("v1"), một alias ("production"), hoặc không có gì để chỉ phiên bản liên kết mới nhất. Việc tải xuống một artifact liên kết sẽ lấy các byte của phiên bản nguồn mà nó trỏ tới.

Vị trí của Registry hiện chỉ có thể được phân giải bởi các lần chạy cục bộ, và chỉ khi bản thể nguồn (source artifact) có sẵn trên máy cục bộ. Các nguồn được lưu trữ trên một Space, trong một bucket, hoặc trên một máy chủ tự lưu trữ (self-hosted) có thể được xuất bản vào một registry dựa trên bucket, nhưng việc phân giải các liên kết đó trong một quy trình sau đó hiện chưa được hỗ trợ. Bản thể được liên kết (linked artifact) được trả về trực tiếp bởi link_artifact vẫn giữ nguyên nguồn Space hoặc máy chủ tự lưu trữ của nó và có thể tải xuống từ đó.

Phiên bản bộ sưu tập

Mỗi liên kết mới sẽ nhận số phiên bản tiếp theo trong bộ sưu tập, bắt đầu từ v0. Các phiên bản của bộ sưu tập là độc lập với số phiên bản của chính các artifact nguồn, vì các phiên bản được liên kết thường đến từ các artifact và dự án khác nhau.

Việc liên kết một phiên bản nguồn đã có trong bộ sưu tập sẽ không tạo ra phiên bản mới. Bạn sẽ nhận lại phiên bản hiện có, và bất kỳ aliases nào bạn truyền vào vẫn sẽ được di chuyển. Số phiên bản không bao giờ được sử dụng lại, do đó một my-model:v3 đã được công bố sẽ không bao giờ thay đổi ý nghĩa một cách âm thầm.

Nâng cấp một phiên bản có các alias

Một alias tham chiếu đến một phiên bản trong mỗi collection. Việc gán một alias mà một phiên bản khác đang giữ sẽ di chuyển alias đó — chính hành động di chuyển này là sự thăng cấp. Các bên tiêu thụ phân giải my-model:production sẽ theo dõi alias, nên không có gì thay đổi ở các hệ thống phía sau khi alias di chuyển.

Hầu hết các đợt thăng cấp diễn ra vào thời điểm phát hành: bạn liên kết một phiên bản mới và đặt alias trong cùng một cuộc gọi.

run.link_artifact(artifact, "registry-models/my-model", aliases=["staging"])

Để nâng cấp một phiên bản đã có sẵn trong bộ sưu tập, hãy liên kết lại nó với alias. Việc liên kết lại không tạo ra thứ gì mới — bạn sẽ nhận lại phiên bản bộ sưu tập hiện có, và các alias bạn truyền sẽ được chuyển sang phiên bản đó. Tìm nguồn của phiên bản trong các liên kết của bộ sưu tập, lấy nó, và liên kết lại:

registry.collection("my-model").links
# [..., {"collection_version": 1, "source_project": "my-experiments",
#        "source_artifact": "resnet", "source_version": 3, ...}]

candidate = run.use_artifact("resnet:v3")
run.link_artifact(candidate, "registry-models/my-model", aliases=["production"])

Bạn cũng có thể lấy trực tiếp từ registry:

candidate = run.use_artifact("registry-models/my-model:v1")
run.link_artifact(candidate, "registry-models/my-model", aliases=["production"])

Việc hoàn tác một alias về phiên bản cũ hơn hoạt động theo cách tương tự.

Trackio quản lý alias latest cho bạn: nó luôn trỏ đến phiên bản liên kết mới nhất.

Hủy liên kết một phiên bản

Xóa một liên kết bằng Artifact.unlink(), được gọi trên artifact đã liên kết:

linked = run.link_artifact(artifact, "registry-models/my-model")
linked.unlink()

Artifact nguồn và các tệp của nó không bị thay đổi — chỉ có sự thuộc về collection bị xóa. Mọi alias trên link cũng bị xóa theo, và số phiên bản của collection không bao giờ được dùng lại, nên my-model:v0 không thể sau đó mang ý nghĩa khác. Nếu phiên bản bạn xóa đang giữ latest, alias đó sẽ chuyển sang phiên bản còn lại cao nhất, nên latest vẫn trỏ đến phiên bản mới nhất trong collection.

Các registry từ xa

Một registry cục bộ chỉ tồn tại trên máy đã tạo ra nó. Để chia sẻ một catalog giữa các máy — hoặc để xuất bản từ một run ghi log vào một Space hoặc một server tự host — hãy dùng một Hugging Face bucket làm nền tảng cho registry bằng cách truyền bucket_id:

registry = trackio.Api().create_registry(
    "models", description="Our deployable models", bucket_id="my-org/models-registry"
)

Bucket sẽ được tạo (riêng tư) nếu chưa tồn tại. Đặt TRACKIO_REGISTRY_BUCKET_ID để nó trở thành mặc định cho mọi lệnh gọi registry trong một tiến trình, nhờ đó các script không cần phải truyền tham số này.

Việc lấy, kiểm tra và xuất bản đều sử dụng cùng một đối số:

registry = trackio.Api().registry("models", bucket_id="my-org/models-registry")

run = trackio.init(project="my-experiments", space_id="my-org/my-dashboard")
artifact = trackio.log_artifact("model.pt", name="resnet", type="model")

run.link_artifact(
    artifact,
    "registry-models/my-model",
    aliases=["staging"],
    bucket_id="my-org/models-registry",
)

Mọi người có quyền truy cập vào bucket đều ghi trực tiếp vào đó bằng thông tin xác thực Hugging Face của riêng mình — không có server nào nằm trên đường dẫn, do đó một registry không bị ràng buộc với bất kỳ Space nào và tồn tại lâu hơn tất cả chúng. Artifact.link và Artifact.unlink nhận bucket_id theo cách tương tự, và một artifact đã liên kết sẽ ghi nhớ bucket mà nó đến, nên linked.unlink() sẽ quay về đúng registry.

Bucket riêng của registry được cố tình không đặt trùng với bucket của run: một registry là danh mục xuyên dự án, nên bạn đặt tên cho nó một cách rõ ràng thay vì kế thừa vị trí mà các metrics có thể được lưu.

Những gì nằm trong bucket

Mỗi đột biến được lưu trữ dưới dạng một đối tượng bất biến, và trạng thái là một phép gập (fold) của nhật ký đó:

trackio/registries/<registry>/registry.json            name, description, created_at
trackio/registries/<registry>/events/<event_uid>.json  one object per mutation

Việc đọc một registry từ xa sẽ gộp các sự kiện đó vào cơ sở dữ liệu dự chiếu cục bộ dưới registry-cache/, đây là một bộ nhớ đệm: xóa nó và lần đọc tiếp theo sẽ xây dựng lại từ bucket.

Sự đồng thời

Bộ nhớ đối tượng không có thao tác so-sánh-và-đổi (compare-and-swap), do đó các tác giả không thể khóa — họ chỉ có thể thêm các đối tượng mà không ai khác đang ghi. Hai hệ quả, cả hai đều do thiết kế:

• Số phiên bản được gán bởi quá trình fold, không phải bởi writer. Các liên kết đồng thời được sắp xếp theo event id (timestamp, sau đó là writer, sau đó là sequence), do đó mỗi liên kết nhận được một số riêng biệt, không bao giờ được dùng lại. Một phiên bản do một writer báo cáo có thể thay đổi khi các sự kiện của một writer đồng thời khác được fold vào.
• Các thao tác đổi tên alias áp dụng nguyên tắc người ghi cuối cùng thắng theo cùng thứ tự đó, bao gồm cả latest. Hai người cùng lúc đẩy lên production sẽ được giải quyết theo thứ tự sự kiện.

Liên kết giữ nguyên vai trò là con trỏ thuần túy: không có gì được sao chép vào bucket của registry, do đó lưu trữ của dự án nguồn phải luôn ở trạng thái có thể truy cập được. Việc phân giải các liên kết có nguồn ở xa hiện chưa được hỗ trợ. Việc sao chép (ghim) các byte của một phiên bản vào registry là một bước tiếp theo đã được lên kế hoạch.

Kiểm tra một registry

Registry xử lý các danh sách bộ sưu tập và các phiên bản liên kết của chúng. Các thao tác đọc trả về các bản sao Collection:

registry = trackio.Api().registry("models")

registry.collections()
# [Collection(name="my-model", type="model", num_links=2, latest_version=1, ...)]

registry.collection("my-model").links
# [{"collection_version": 1, "source_project": "my-experiments",
#   "source_artifact": "resnet", "source_version": 4,
#   "aliases": ["latest", "production"], ...}]

Mỗi liên kết ghi lại nguồn gốc của phiên bản (source_project, source_artifact, source_version), tọa độ lưu trữ của nguồn khi không phải là cục bộ (source_space_id, source_bucket_id, hoặc source_server_base_url), và các alias hiện có trên đó. Một liên kết là một con trỏ thuần túy đến phiên bản nguồn đó.

Giao diện dòng lệnh

Các lệnh trackio registry bao phủ cùng quy trình phát hành và kiểm tra mà không yêu cầu một script Python:

trackio registry create models --description "Models we deploy"
trackio registry create-collection models/churn-model --type model

trackio registry link models/churn-model my-experiments/resnet:v3 --alias staging
trackio registry promote models/churn-model production v0

trackio registry list models
trackio registry show models/churn-model
trackio registry events models

trackio registry unlink models/churn-model v0

link xác định nguồn dữ liệu từ dữ liệu Trackio cục bộ. Lệnh này chấp nhận một phiên bản hoặc alias cụ thể và mặc định là latest khi bỏ qua hậu tố. Registry vẫn có thể được hỗ trợ bởi bucket; hãy truyền --bucket-id my-org/models-registry vào bất kỳ lệnh nào. Sử dụng --json để có đầu ra có cấu trúc phù hợp cho script.

CLI chấp nhận cả models/churn-model và cú pháp đích đầy đủ registry-models/churn-model của API Python. Xem Lệnh CLI để tham khảo đầy đủ các lệnh.

Duyệt các registry trong bảng điều khiển

Khởi chạy bảng điều khiển registry độc lập, chỉ đọc để xem mô tả registry, các bộ sưu tập, các phiên bản liên kết, các alias, vị trí nguồn và các sự kiện kiểm toán:

trackio show registry

Hoặc chạy từ Python bằng trackio.show(dashboard="registry"). Bảng điều khiển registry tách biệt khỏi bảng điều khiển project vì registry lưu trữ các artifact xuyên suốt nhiều project.

Nguồn Local hiển thị các registry được lưu trên máy chủ dashboard. Chọn HF Bucket để chọn một bucket Hugging Face có thể truy cập hoặc nhập id bucket như my-org/models-registry. Trên một Space, việc truy cập bucket riêng tư sử dụng thông tin xác thực Hugging Face của người xem đã đăng nhập. Dashboard tự lưu trữ chỉ sử dụng token Hugging Face đã lưu của nó cho những người xem đã mở URL truy cập ghi của dashboard. Dashboard chỉ đọc công khai không bao giờ phơi bày bucket thông qua token do máy chủ sở hữu. Việc duyệt registry không được bao gồm trong các bản chụp tĩnh của dashboard.

Lịch sử kiểm toán

Mọi thao tác thay đổi đều thêm một sự kiện vào nhật ký kiểm toán của registry: tạo registry và collection (create), link, promote, thay đổi mô tả (update), và unlink. Nhật ký này trả lời các câu hỏi như “phiên bản nào đã được triển khai trong tháng trước, và run nào đã xuất bản nó?”:

registry.events()
# [{"id": 1, "ts": "...", "kind": "create", "payload": {...}},
#  {"id": 2, "ts": "...", "kind": "link",
#   "payload": {"collection": "my-model", "collection_version": 0,
#               "source_project": "my-experiments", "run_name": "exp-1", ...}},
#  {"id": 3, "ts": "...", "kind": "promote",
#   "payload": {"alias": "staging", "collection_version": 0,
#               "previous_version": None, ...}}]

Sự kiện liên kết và quảng bá ghi lại lần phát hành. Sự kiện quảng bá cũng ghi lại phiên bản mà alias đã chuyển từ đó.