diff --git a/models/registry/aliases.mdx b/models/registry/aliases.mdx index a9e9b7a1c2..a3d6ca1284 100644 --- a/models/registry/aliases.mdx +++ b/models/registry/aliases.mdx @@ -3,9 +3,9 @@ title: Reference an artifact version with aliases description: "Use default, custom, and protected aliases to reference specific artifact versions in W&B Registry." --- -Reference a specific [artifact version](/models/artifacts/create-a-new-artifact-version/) with one or more aliases. [W&B automatically assigns aliases](/models/registry/aliases/#default-aliases) to each artifact you link with the same name. You can also [create one or more custom aliases](/models/registry/aliases/#custom-aliases) to reference a specific artifact version. +Aliases give you a stable, human-readable way to point to a specific [artifact version](/models/artifacts/create-a-new-artifact-version/) in W&B Registry, so you can track which version is current, in production, or otherwise notable without having to remember version numbers. [W&B automatically assigns aliases](/models/registry/aliases/#default-aliases) to each artifact you link with the same name, and you can also [create one or more custom aliases](/models/registry/aliases/#custom-aliases) to reference a specific artifact version. This page explains the default aliases that W&B assigns automatically, how to create your own custom aliases, and how to use protected aliases to safeguard important versions. -Aliases appear as rectangles with the name of that alias in the rectangle in the Registry UI. If an [alias is protected](/models/registry/aliases/#protected-aliases), it appears as a gray rectangle with a lock icon. Otherwise, the alias appears as an orange rectangle. Aliases are not shared across registries. +Aliases appear as rectangles with the name of that alias in the rectangle in the Registry UI. If an [alias is protected](/models/registry/aliases/#protected-aliases), it appears as a gray rectangle with a lock icon. Otherwise, the alias appears as an orange rectangle. Aliases aren't shared across registries. **When to use an alias versus using a tag** @@ -19,7 +19,7 @@ When you add an alias to an artifact version, you can optionally start a [Regist ## Default aliases -W&B automatically assigns the following aliases to each artifact version you link with the same name: +W&B automatically assigns the following aliases to each artifact version you link with the same name, so you can identify a version without configuring anything: * The `latest` alias to the most recent artifact version you link to a collection. * A unique version number. W&B counts each artifact version (zero indexing) you link. W&B uses the count number to assign a unique version number to that artifact. @@ -28,19 +28,19 @@ For example, if you link an artifact named `zoo_model` three times, W&B creates ## Custom aliases -Create one or more custom aliases for a specific artifact versions based on your unique use case. For example: +Custom aliases let you label artifact versions with names that reflect your workflow, such as the dataset a model was trained on or which version is performing best. For example: - You might use aliases such as `dataset_version_v0`, `dataset_version_v1`, and `dataset_version_v2` to identify which dataset a model was trained on. - You might use a `best_model` alias to keep track of the best performing artifact model version. -Any user with a [**Member** or **Admin** registry role](/models/registry/configure_registry/#registry-roles) on a registry can add or remove a custom alias from a linked artifact in that registry. Users with the [**Restricted Viewer** or **Viewer** roles](/models/registry/configure_registry/#registry-roles) cannot add or remove aliases. +Any user with a [**Member** or **Admin** registry role](/models/registry/configure_registry/#role-permissions) on a registry can add or remove a custom alias from a linked artifact in that registry. Users with the [**Restricted Viewer** or **Viewer** roles](/models/registry/configure_registry/#role-permissions) can't add or remove aliases. [Protected aliases](/models/registry/aliases/#protected-aliases) provide a way to label and identify which artifact versions to protect from modification or deletion. -You can create a custom alias with the W&B Registry or the Python SDK. Based on your use case, click on a tab below that best fits your needs. +You can create a custom alias with the W&B Registry or the Python SDK. Click the tab that fits your workflow. @@ -50,28 +50,28 @@ You can create a custom alias with the W&B Registry or the Python SDK. Based on 4. Click the **+** button to add one or more aliases next to the **Aliases** field. -When you link an artifact version to a collection with the Python SDK you can optionally provide a list of one or more aliases as an argument to the `alias` parameter in [`link_artifact()`](/models/ref/python/experiments/run.md/#link_artifact). W&B creates an alias ([non protected alias](#custom-aliases)) for you if the alias you provide does not already exist. +When you link an artifact version to a collection with the Python SDK, you can optionally provide a list of one or more aliases as an argument to the `aliases` parameter in [`link_artifact()`](/models/ref/python/experiments/run/#method-runlink_artifact). W&B creates an alias ([non protected alias](#custom-aliases)) for you if the alias you provide doesn't already exist. -The following code snippet demonstrates how to link an artifact version to a collection and add aliases to that artifact version with the Python SDK. Replace values within `<>` with your own: +The following code snippet demonstrates how to link an artifact version to a collection and add aliases to that artifact version with the Python SDK. Replace the bracketed placeholders with your own values: ```python import wandb # Initialize a run -with wandb.init(entity = "", project = "") as run: +with wandb.init(entity = "[TEAM-ENTITY]", project = "[PROJECT-NAME]") as run: # Create an artifact object # The type parameter specifies both the type of the # artifact object and the collection type - artifact = wandb.Artifact(name = "", type = "") + artifact = wandb.Artifact(name = "[NAME]", type = "[TYPE]") # Add the file to the artifact object. # Specify the path to the file on your local machine. - artifact.add_file(local_path = "") + artifact.add_file(local_path = "[LOCAL-PATH-TO-ARTIFACT]") # Specify the collection and registry to link the artifact to - REGISTRY_NAME = "" - COLLECTION_NAME = "" + REGISTRY_NAME = "[REGISTRY-NAME]" + COLLECTION_NAME = "[COLLECTION-NAME]" target_path=f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}" # Link the artifact version to the collection @@ -79,16 +79,17 @@ with wandb.init(entity = "", project = "") as run: run.link_artifact( artifact = artifact, target_path = target_path, - aliases = ["", ""] + aliases = ["[ALIAS-1]", "[ALIAS-2]"] ) ``` ### Protected aliases -Use a [protected alias](/models/registry/aliases/#protected-aliases) to both label and identify artifact versions that should not be modified or deleted. For example, consider using a `production` protected alias to label and identify artifact versions that are in used in your organization's machine learning production pipeline. -[Registry admin](/models/registry/configure_registry/#registry-roles) users and [service accounts](/support/models/articles/what-is-a-service-account-and-why-is-it-) with the **Admin** role can create protected aliases and add or remove protected aliases from an artifact version. Users and service accounts with **Member**, **Viewer**, and **Restricted Viewer** roles cannot unlink a protected version or delete a collection that contains a protected alias. See [Configure registry access](/models/registry/configure_registry/) for details. +Protected aliases combine labeling with a guardrail: besides identifying a version, they prevent that version from being modified or deleted, which is useful for releases that downstream systems depend on. For example, consider a `production` protected alias to label and identify artifact versions that are in use in your organization's machine learning production pipeline. + +[Registry admin](/models/registry/configure_registry/#role-permissions) users and [service accounts](/support/models/articles/what-is-a-service-account-and-why-is-it-) with the **Admin** role can create protected aliases and add or remove protected aliases from an artifact version. Users and service accounts with **Member**, **Viewer**, and **Restricted Viewer** roles can't unlink a protected version or delete a collection that contains a protected alias. See [Configure registry access](/models/registry/configure_registry/) for details. Common protected aliases include: @@ -107,7 +108,7 @@ The following steps describe how to create a protected alias in the W&B Registry After creation, each protected alias appears as a gray rectangle with a lock icon in the **Protected Aliases** section. -Unlike custom aliases that are not protected, creating protected aliases is available exclusively in the W&B Registry UI and not programmatically with the Python SDK. To add a protected alias to an artifact version, you can use the W&B Registry UI or the Python SDK. +Unlike custom aliases that aren't protected, you can create protected aliases only in the W&B Registry UI, not programmatically with the Python SDK. To add a protected alias to an artifact version, you can use the W&B Registry UI or the Python SDK. The following steps describe how to add a protected alias to an artifact version with the W&B Registry UI: @@ -117,10 +118,11 @@ The following steps describe how to add a protected alias to an artifact version 3. Within the **Versions** section, select the **View** button for a specific artifact version. 4. Click the **+** button to add one or more protected aliases next to the **Aliases** field. -After a protected alias is created, an admin can add it to an artifact version programmatically with the Python SDK. See the W&B Registry and Python SDK tabs in [Create a custom alias](#custom-aliases) section above for an example on how to add a protected alias to an artifact version. +After an admin creates a protected alias, the admin can add it to an artifact version programmatically with the Python SDK. For an example of how to add a protected alias to an artifact version, see [Custom aliases](#custom-aliases). ## Find existing aliases -You can find existing aliases with the [global search bar in the W&B Registry](/models/registry/search_registry/#search-for-registry-items). To find a protected alias: + +Once you have aliases in place, you can find them with the [global search bar in the W&B Registry](/models/registry/search_registry/#search-for-registry-items). To find a protected alias: 1. Navigate to the W&B Registry. 2. Specify the search term in the search bar at the top of the page. Press Enter to search. @@ -129,6 +131,8 @@ Search results appear below the search bar if the term you specify matches an ex ## Example +The following end-to-end example shows how to create an artifact, link it to a registry collection, and attach custom aliases in a single workflow. + The following code example is a continuation of this [W&B Registry Tutorial notebook](https://colab.research.google.com/github/wandb/examples/blob/master/colabs/wandb_registry/zoo_wandb.ipynb). To use the following code, you must first [retrieve and process the Zoo dataset as described in the notebook](https://colab.research.google.com/github/wandb/examples/blob/master/colabs/wandb_registry/zoo_wandb.ipynb#scrollTo=87fecd29-8146-41e2-86fb-0bb4e3e3350a). Once you have the Zoo dataset, you can create an artifact version and add custom aliases to it. @@ -167,4 +171,4 @@ with wandb.init(entity = "smle-reg-team-2", project = "zoo_experiment") as run: 1. First, you create an artifact object (`wandb.Artifact()`). 2. Next, you add two dataset PyTorch tensors to the artifact object with `wandb.Artifact.add_file()`. -3. Lastly, you link the artifact version to the `Model` collection in the `Zoo_Classifier_Models` registry with `link_artifact()`. You also add two custom aliases to the artifact version by passing `production-us` and `production-eu` as arguments to the `aliases` parameter. +3. Finally, you link the artifact version to the `Model` collection in the `Zoo_Classifier_Models` registry with `link_artifact()`. You also add two custom aliases to the artifact version by passing `production-us` and `production-eu` as arguments to the `aliases` parameter. diff --git a/models/registry/configure_registry.mdx b/models/registry/configure_registry.mdx index 4b6fb55329..c75c0ef31e 100644 --- a/models/registry/configure_registry.mdx +++ b/models/registry/configure_registry.mdx @@ -3,30 +3,35 @@ title: Configure registry access description: "Configure W&B Registry access by managing users and teams, assigning roles, and setting role-based permissions." --- -A registry admin can [configure registry roles](/models/registry/configure_registry/#configure-registry-roles), [add users](/models/registry/configure_registry/#add-a-user-or-a-team-to-a-registry), or [remove users](/models/registry/configure_registry/#remove-a-user-or-team-from-a-registry) from a registry by configuring the registry's settings. +This page shows registry admins how to control access to a W&B Registry by managing its members and their permissions. Use these procedures to add or remove users and teams, assign or change registry roles, and understand the permissions each role provides. + +A registry admin can [configure registry roles](/models/registry/configure_registry/#configure-registry-roles), [add users](/models/registry/configure_registry/#add-a-user-or-a-team-to-a-registry), or [remove users](/models/registry/configure_registry/#remove-a-user-or-team-from-a-registry) from a registry through the registry's settings. ## Manage users +The following sections describe how to add users or teams to a registry, remove them, and change a registry's owner. + ### Add a user or a team Registry admins can add individual users or entire teams to a registry. To add a user or team to a registry: 1. Navigate to the W&B Registry. 2. Select the registry you want to add a user or team to. -3. Click on the gear icon on the upper right hand corner to access the registry settings. +3. Click the gear icon in the upper right corner to access the registry settings. 4. In the **Registry access** section, click **Add access**. -5. Specify one or more user names, emails, or the team names to the **Include users and teams** field. +5. Specify one or more user names, emails, or team names in the **Include users and teams** field. 6. Click **Add access**. -Learn more about [configuring user roles in a registry](/models/registry/configure_registry/#configure-registry-roles), or [registry role permissions](/models/registry/configure_registry#role-permissions). +For more information, see [Role permissions](#role-permissions). ### Remove a user or team + A registry admin can remove individual users or entire teams from a registry. To remove a user or team from a registry: 1. Navigate to the W&B Registry at https://wandb.ai/registry/. 2. Select the registry you want to remove a user from. -3. Click on the gear icon on the upper right hand corner to access the registry settings. -4. Navigate to the **Registry access** section and type in the username, email, or team you want to remove. +3. Click the gear icon in the upper right corner to access the registry settings. +4. Navigate to the **Registry access** section and type the username, email, or team you want to remove. 5. Click the **Delete** button. @@ -35,61 +40,66 @@ Removing a user from a team also removes that user's access to the registry. ### Change the owner of a registry -A registry admin can designate any member as a registry's owner, including a **Restricted Viewer** or a **Viewer**. Registry ownership is primarily for accountability purposes and does not confer any additional permissions beyond those granted by the user's assigned role. +A registry admin can designate any member as a registry's owner, including a **Restricted Viewer** or a **Viewer**. Registry ownership is for accountability and doesn't confer any additional permissions beyond those granted by the user's assigned role. To change the owner: + 1. Navigate to the W&B Registry at https://wandb.ai/registry/. 2. Select the registry you want to configure. -3. Click the gear icon on the upper right hand corner. +3. Click the gear icon in the upper right corner. 4. Scroll to the **Registry members and roles** section. 5. Hover over the row for a member. 6. Click the **action ()** menu at the end of the row, then click **Make owner**. -## Configure Registry roles +## Configure registry roles -This section shows how to configure roles for Registry members. For more information about Registry roles, including the cabilities of each role, order of precedence, defaults, and more, see [Details about Registry roles](#details-about-registry-roles). +This section shows how to configure roles for registry members. The role you assign determines what actions a user or team can perform in the registry. For more information about registry roles, including the capabilities of each role, order of precedence, and defaults, see [Details about registry roles](#details-about-registry-roles). 1. Navigate to the W&B Registry at https://wandb.ai/registry/. 2. Select the registry you want to configure. -3. Click the gear icon on the upper right hand corner. +3. Click the gear icon in the upper right corner. 4. Scroll to the **Registry members and roles** section. 5. Within the **Member** field, search for the user or team you want to edit permissions for. 6. In the **Registry role** column, click the user's role. 7. From the dropdown, select the role you want to assign to the user. -## Details about Registry roles +## Details about registry roles -The following sections give more information about Registry roles. +The following sections give more information about registry roles. Your [role in a team](/platform/app/settings-page/teams/#team-roles-and-permissions) has no impact or relationship to your role in any registry. ### Default roles -W&B automatically assigns a default **registry role** to a user or team when they are added to a registry. This role determines what they can do in that registry. -| Entity | Default registry role
(Dedicated Cloud / Self-Managed) | Default registry role
(Multi-tenant Cloud) | +W&B automatically assigns a default **registry role** to a user or team when you add them to a registry. This role determines what they can do in that registry. + +| Entity | Default registry role
(Dedicated Cloud and Self-Managed) | Default registry role
(Multi-tenant Cloud) | |----------------------------------------|---------------------------------------------------------------------------|------------------------------------------------------------| -| Team | Restricted Viewer (Server v0.75.0+)
Viewer (Server v0.74.x and below) | Restricted Viewer | -| User or service account (non admin) | Restricted Viewer (Server v0.75.0+)
Viewer (Server v0.74.x and below) | Restricted Viewer | -| Service account (non admin) | Member1 | Member1 | +| Team | Restricted Viewer (Server v0.75.0+)
Viewer (Server v0.74.x and earlier) | Restricted Viewer | +| User or service account (non-admin) | Restricted Viewer (Server v0.75.0+)
Viewer (Server v0.74.x and earlier) | Restricted Viewer | +| Service account (non-admin) | Member1 | Member1 | | Org admin | Admin | Admin | -1: Service accounts cannot have **Viewer** or **Restricted Viewer** roles. See [Service account access](#service-account-access) for how a service account's access is determined. +1: Service accounts can't have **Viewer** or **Restricted Viewer** roles. See [Service account access](#service-account-access) for how a service account's access is determined. -A registry admin can assign or modify roles for users and teams in the registry. -See [Configure user roles in a registry](/models/registry/configure_registry/#configure-registry-roles) for more information. +A registry admin can assign or modify roles for users and teams in the registry. For more information, see [Configure registry roles](#configure-registry-roles). + +{/* Backward-compatibility anchor: external pages (for example, automations docs) and localized pages link to #registry-roles. Keep this anchor so those inbound links continue to resolve to the role definitions below. */} + ### Role permissions -The following table lists each Registry role, along with the permissions provided by each role: + +The following table lists each registry role, along with the permissions each role provides: | Permission | Permission Group | Restricted Viewer
(Multi-tenant Cloud, by invitation) | Viewer | Member | Admin | |-----------------------------------------------------------------------------------------------------------------------|------------------|------------------------------------------------------------|:------:|:------:|:-----:| | View a collection's details | Read | ✓ | ✓ | ✓ | ✓ | | View a linked artifact's details | Read | ✓ | ✓ | ✓ | ✓ | -| Usage: Consume an artifact in a registry with use_artifact | Read | | ✓ | ✓ | ✓ | +| Usage: Consume an artifact in a registry with `use_artifact` | Read | | ✓ | ✓ | ✓ | | Download a linked artifact | Read | | ✓ | ✓ | ✓ | | Download files from an artifact's file viewer | Read | | ✓ | ✓ | ✓ | | Search a registry | Read | ✓ | ✓ | ✓ | ✓ | @@ -115,27 +125,31 @@ The following table lists each Registry role, along with the permissions provide | Add users to a registry | Admin | | | | ✓ | | Assign or change a user's role in a registry | Admin | | | | ✓ | -### Inherited Registry role -The registry's membership list shows each user's inherited (effective) registry role (in light gray) next to the role dropdown in their row. +### Inherited registry role + +The registry's membership list shows each user's inherited (effective) registry role next to the role dropdown in their row. Registry membership list showing the user's effective registry role -A user's effective role in a particular registry matches their _highest_ role among their role in the organization, the registry, and the team that owns the registry, whether inherited or explicitly assigned. For example: +A user's effective role in a particular registry matches their _highest_ role among the organization, the registry, and the team that owns the registry. This applies whether the role is inherited or explicitly assigned. For example: - A team **Admin** or organization **Admin** with the **Viewer** role in a particular registry owned by the team is effectively an **Admin** of the registry. - A registry **Viewer** with the **Member** role in the team is effectively a **Member** of the registry. - A team **Viewer** with the **Member** role in a particular registry is effectively a **Member** of the registry. ### Restricted Viewer role details -The **Restricted Viewer** role is Generally Available (GA). For Dedicated Cloud and Self-Managed, Server v0.75.0 or newer is required. + +The **Restricted Viewer** role is useful for granting broad visibility into a registry without exposing artifact contents. The following sections describe its availability, behavior, and SDK compatibility. + +The **Restricted Viewer** role is Generally Available (GA). For Dedicated Cloud and Self-Managed, Server v0.75.0 or later is required. This role provides read-only access to registry artifacts without the ability to create, update, or delete collections, automations, or other registry resources. Unlike a **Viewer**, a **Restricted Viewer**: -- Cannot download artifact files or access file contents. -- Cannot use artifacts with `wandb.Run.use_artifact()` in the W&B SDK. +- Can't download artifact files or access file contents. +- Can't use artifacts with `wandb.Run.use_artifact()` in the W&B SDK. #### SDK compatibility @@ -143,13 +157,13 @@ Unlike a **Viewer**, a **Restricted Viewer**: **SDK version requirement** -To use the W&B SDK to access artifacts as a **Restricted Viewer**, you must use W&B SDK version 0.19.9 or higher. Otherwise, some SDK commands will result in permission errors. +To use the W&B SDK to access artifacts as a **Restricted Viewer**, you must use W&B SDK version 0.19.9 or later. Otherwise, some SDK commands result in permission errors. When a **Restricted Viewer** uses the SDK, certain functions are not available or work differently. -The following methods are not available and result in permission errors: +The following methods aren't available and result in permission errors: - [`Run.use_artifact()`](/models/ref/python/experiments/run/#method-runuse_artifact) - [`Artifact.download()`](/models/ref/python/experiments/artifact/#method-artifactdownload) - [`Artifact.file()`](/models/ref/python/experiments/artifact/#method-artifactfile) @@ -165,7 +179,7 @@ The following methods are limited to artifact metadata: A user can have different roles in different registries. For example, a user can be a **Restricted Viewer** in Registry A but a **Viewer** in Registry B. In this case: -- The same artifact linked to both registries will have different access levels -- In Registry A, the user is a **Restricted Viewer** and cannot download files or use the artifact -- In Registry B, the user is a **Viewer** and can download files and use the artifact -- In other words, access is determined by the registry in which the artifact is accessed +- The same artifact linked to both registries has different access levels. +- In Registry A, the user is a **Restricted Viewer** and can't download files or use the artifact. +- In Registry B, the user is a **Viewer** and can download files and use the artifact. +- In other words, the registry in which the user accesses the artifact determines access. diff --git a/models/registry/create_collection.mdx b/models/registry/create_collection.mdx index 238f960436..485f76578e 100644 --- a/models/registry/create_collection.mdx +++ b/models/registry/create_collection.mdx @@ -4,59 +4,60 @@ description: "Create a collection of linked artifact versions within a W&B Regis --- -A *collection* is a set of linked artifact versions within a registry. Each collection represents a distinct task or use case. +This page explains how to create a collection within a W&B Registry and configure the artifact types it accepts. Collections let you group related artifact versions for a specific task or use case. + +A *collection* is a set of linked artifact versions within a registry. Each collection represents a distinct task or use case. For example, within a registry you might have multiple collections. Each collection contains a different dataset such as MNIST, CIFAR-10, or ImageNet. -As another example, you might have a registry called "chatbot" that contains a collection for model artifacts, another collection for dataset artifacts, and another collection for fine-tuned model artifacts. +As another example, you might have a registry called `chatbot` that contains a collection for model artifacts, another collection for dataset artifacts, and another collection for fine-tuned model artifacts. How you organize a registry and their collections is up to you. -If you are familiar with W&B Model Registry, you might aware of registered models. Registered models in the Model Registry are now referred to as collections in the W&B Registry. +If you're familiar with W&B Model Registry, you might know about registered models. The W&B Registry now refers to registered models as collections. ## Collection types -Each collection accepts one, and only one, *type* of artifact. The type you specify restricts what sort of artifacts you, and other members of your organization, can link to that collection. +Each collection accepts one, and only one, *type* of artifact. The type you specify restricts which artifacts you, and other members of your organization, can link to that collection. You can think of artifact types similar to data types in programming languages such as Python. In this analogy, a collection can store strings, integers, or floats but not a mix of these data types. -For example, suppose you create a collection that accepts "dataset" artifact types. This means that you can only link future artifact versions that have the type "dataset" to this collection. Similarly, you can only link artifacts of type "model" to a collection that accepts only model artifact types. +For example, suppose you create a collection that accepts `dataset` artifact types. You can only link future artifact versions of type `dataset` to this collection. Similarly, you can only link artifacts of type `model` to a collection that accepts only model artifact types. -You specify an artifact's type when you create that artifact object. Note the `type` field in `wandb.Artifact()`: +You specify an artifact's type when you create that artifact object. See the `type` field in `wandb.Artifact()`. Replace the placeholders `[TEAM-ENTITY]`, `[PROJECT]`, `[ARTIFACT-NAME]`, and `[ARTIFACT-TYPE]` with your own values: ```python import wandb # Initialize a run with wandb.init( - entity = "", - project = "" + entity = "[TEAM-ENTITY]", + project = "[PROJECT]" ) as run: # Create an artifact object artifact = wandb.Artifact( - name="", - type="" + name="[ARTIFACT-NAME]", + type="[ARTIFACT-TYPE]" ) ``` - When you create a collection, you can select from a list of predefined artifact types. The artifact types available to you depend on the registry that the collection belongs to. -Before you link an artifact to a collection or create a new collection, [investigate the types of artifacts that collection accepts](#check-the-types-of-artifact-that-a-collection-accepts). +Before you link an artifact to a collection or create a new collection, [check which artifact types the collection accepts](#check-the-artifact-types-a-collection-accepts). -### Check the types of artifact that a collection accepts +### Check the artifact types a collection accepts -Before you link to a collection, inspect the artifact type that the collection accepts. You can inspect the artifact types that collection accepts programmatically with the W&B Python SDK or interactively with the W&B App +Before you link to a collection, inspect the artifact type that the collection accepts. This helps you avoid link errors caused by mismatched artifact types. You can inspect the artifact types that a collection accepts programmatically with the W&B Python SDK or interactively with the W&B App. -An error message appears if you try to create link an artifact to a collection that does not accept that artifact type. +An error message appears if you try to link an artifact to a collection that doesn't accept that artifact type. @@ -65,34 +66,36 @@ You can find the accepted artifact types on the registry card on the homepage or For both methods, first navigate to your W&B Registry. -Within the homepage of the W&B Registry, you can view the accepted artifact types by scrolling to the registry card of that registry. The gray horizontal ovals within the registry card lists the artifact types that registry accepts. +Within the homepage of the W&B Registry, you can view the accepted artifact types by scrolling to the registry card of that registry. The labels within the registry card list the artifact types that the registry accepts. Artifact types selection -For example, the following image shows multiple registry cards on the W&B Registry homepage. Within the **Model** registry card, you can see two artifact types: **model** and **model-new**. +For example, the following image shows multiple registry cards on the W&B Registry homepage. Within the **Model** registry card, you can see two artifact types: `model` and `model-new`. To view accepted artifact types within a registry's settings page: -1. Click on the registry card you want to view the settings for. -2. Click on the gear icon in the upper right corner. +1. Click the registry card you want to view the settings for. +2. Click the gear icon in the upper right corner. 3. Scroll to the **Accepted artifact types** field. Programmatically view the artifact types that a registry accepts with the W&B Python SDK: +Replace `[REGISTRY-NAME]` with the name of your registry: + ```python import wandb -registry_name = "" +registry_name = "[REGISTRY-NAME]" artifact_types = wandb.Api().project(name=f"wandb-registry-{registry_name}").artifact_types() -print(artifact_type.name for artifact_type in artifact_types) +print([artifact_type.name for artifact_type in artifact_types]) ``` -Note that you do not initialize a run with the following code snippet. This is because it is unnecessary to create a run if you are only querying the W&B API and not tracking an experiment, artifact and so on. +The following code snippet doesn't initialize a run. You don't need to create a run if you're only querying the W&B API and not tracking an experiment, artifact, and so on. @@ -104,9 +107,9 @@ Once you know what type of artifact a collection accepts, you can [create a coll ## Create a collection -Interactively or programmatically create a collection within a registry. You can not change the type of artifact that a collection accepts after you create it. +Interactively or programmatically create a collection within a registry. Choose the method that best fits your workflow: programmatic creation is useful for automated pipelines, while interactive creation is useful for individual setup in the W&B App. You can't change the type of artifact that a collection accepts after you create it. -### Programmatically create a collection +### Create a collection programmatically Use the `wandb.Run.link_artifact()` method to link an artifact to a collection. Specify both the collection and the registry to the `target_path` field as a path that takes the form of: @@ -114,47 +117,49 @@ Use the `wandb.Run.link_artifact()` method to link an artifact to a collection. f"wandb-registry-{registry_name}/{collection_name}" ``` -Where `registry_name` is the name of the registry and `collection_name` is the name of the collection. Ensure to append the prefix `wandb-registry-` to the registry name. +Where `registry_name` is the name of the registry and `collection_name` is the name of the collection. Append the prefix `wandb-registry-` to the registry name. -W&B automatically creates a collection for you if you try to link an artifact to a collection that does not exist. If you specify a collection that does exists, W&B links the artifact to the existing collection. +W&B automatically creates a collection for you if you try to link an artifact to a collection that doesn't exist. If you specify a collection that exists, W&B links the artifact to the existing collection. -The following code snippet shows how to programmatically create a collection. Ensure to replace the values enclosed in `<>` with your own: +The following code snippet shows how to programmatically create a collection. Replace the placeholders `[TEAM-ENTITY]`, `[PROJECT]`, `[ARTIFACT-NAME]`, `[ARTIFACT-TYPE]`, `[REGISTRY-NAME]`, and `[COLLECTION-NAME]` with your own values: ```python import wandb # Initialize a run -with wandb.init(entity = "", project = "") as run: +with wandb.init(entity = "[TEAM-ENTITY]", project = "[PROJECT]") as run: # Create an artifact object artifact = wandb.Artifact( - name = "", - type = "" + name = "[ARTIFACT-NAME]", + type = "[ARTIFACT-TYPE]" ) - registry_name = "" - collection_name = "" + registry_name = "[REGISTRY-NAME]" + collection_name = "[COLLECTION-NAME]" target_path = f"wandb-registry-{registry_name}/{collection_name}" # Link the artifact to a collection run.link_artifact(artifact = artifact, target_path = target_path) ``` -### Interactively create a collection +After this code runs, the artifact links to the specified collection, and W&B creates the collection automatically if it doesn't already exist. + +### Create a collection interactively The following steps describe how to interactively create a collection using the W&B Registry: 1. Navigate to the W&B Registry at https://wandb.ai/registry/. 2. Select a registry. -3. Click on the **Create collection** button in the upper right hand corner. -4. Provide a name for your collection in the **Name** field. +3. Click the **Create collection** button in the upper-right corner. +4. Provide a name for your collection in the **Name** field. 5. Select a type from the **Type** dropdown. Or, if the registry enables custom artifact types, provide one or more artifact types that this collection accepts. -6. Optionally provide a description of your collection in the **Description** field. -7. Optionally add one or more tags in the **Tags** field. +6. Optional: Provide a description of your collection in the **Description** field. +7. Optional: Add one or more tags in the **Tags** field. 8. Click **Link version**. 9. From the **Project** dropdown, select the project where your artifact is stored. 10. From the **Artifact** collection dropdown, select your artifact. 11. From the **Version** dropdown, select the artifact version you want to link to your collection. -12. Click on the **Create collection** button. \ No newline at end of file +12. Click the **Create collection** button. diff --git a/models/registry/create_registry.mdx b/models/registry/create_registry.mdx index 8e6724cf95..7c96b4a298 100644 --- a/models/registry/create_registry.mdx +++ b/models/registry/create_registry.mdx @@ -3,80 +3,78 @@ title: Create a registry description: "Create a W&B Registry with configurable visibility and accepted artifact types using the App UI or Python SDK." --- -A registry offers flexibility and control over the artifact types that you can use, allows you to restrict the registry's visibility, and more. +This page shows organization and team admins how to create a W&B Registry and configure its visibility and accepted artifact types. A registry gives you control over which artifact types you can use and who can access it. ## Create a registry -Create a registry either programmatically using the W&B Registry UI or the W&B Python SDK. +You can create a registry either interactively using the W&B Registry UI or programmatically using the W&B Python SDK. - + 1. Navigate to the W&B Registry at https://wandb.ai/registry/. -2. Click on the **Create registry** button. +2. Click the **Create registry** button. 3. Provide a name for the registry in the **Name** field. -4. Optionally provide a description about the registry. -5. Select who can view the registry from the **Registry visibility** dropdown. See [Registry visibility types](./configure_registry#registry-visibility-types) for more information on registry visibility options. +4. Optional: Provide a description of the registry. +5. Select who can view the registry from the **Registry visibility** dropdown. See [Visibility types](#visibility-types) for more information about registry visibility options. 6. Select either **All types** or **Specify types** from the **Accepted artifacts type** dropdown. -7. (If you select **Specify types**) Add one or more artifact types that your registry accepts. -8. Click on the **Create registry** button. + a. If you select **Specify types**, add one or more artifact types that your registry accepts. +7. Click the **Create registry** button. -Use the [`wandb.Api().create_registry()`](/models/ref/python/#method-apicreate_registry) method to create a registry programmatically. Provide a name and [visibility](#visibility-types) for the registry for the `name` and `visibility` parameters, respectively. +Use the [`wandb.Api().create_registry()`](/models/ref/python/#method-apicreate_registry) method to create a registry programmatically. Provide a name and [visibility](#visibility-types) using the `name` and `visibility` parameters. -Copy and paste the code block below. Replace the values enclosed in `<>` with your own: +Copy and paste the code block below. Replace `[REGISTRY-NAME]` with a name for your registry, and replace `[VISIBILITY]` with either `restricted` or `organization`: ```python import wandb registry = wandb.Api().create_registry( - name="", - visibility="< 'restricted' | 'organization' >", + name="[REGISTRY-NAME]", + visibility="[VISIBILITY]", ) ``` -See the [`wandb.Api().create_registry()`](/models/ref/python/#method-apicreate_registry) method reference for a full list of parameters that you can provide when you create a registry. +See the [`wandb.Api().create_registry()`](/models/ref/python/#method-apicreate_registry) method reference for a full list of parameters that you can provide when you create a registry. -An artifact type cannot be removed from a registry once it is saved in the registry's settings. +After you save an artifact type in the registry's settings, you can't remove it from the registry. -For example, the following image shows a registry called `Fine_Tuned_Models` that a user is about to create. The registry is **Restricted** to only members that are manually added to the registry. - +For example, the following image shows a registry called `Fine_Tuned_Models` that a user is about to create. The registry is **Restricted** to only members who are manually added to the registry. ## Visibility types -The *visibility* of a registry determines who can access that registry. Restricting the visibility of a registry helps ensure that only specified members can access that registry. +The *visibility* of a registry determines who can access it. Restricting visibility ensures that only specified members have access. -There are two type registry visibility options for a registry: +A registry has two visibility options: | Visibility | Description | -| --- | --- | -| Restricted | Only invited organization members can access the registry.| -| Organization | Everyone in the org can access the registry. | +| --- | --- | +| Restricted | Only invited organization members can access the registry. | +| Organization | Everyone in the organization can access the registry. | A team admin or registry admin can set the visibility of a registry. -The user who creates a registry with Restricted visibility is added to the registry automatically as its registry admin. +W&B automatically adds the user who creates a registry with Restricted visibility to the registry as its registry admin. ## Configure the visibility of a registry -A team admin or registry admin can assign the visibility of a registry during or after the creation of a registry. +A team admin or registry admin can assign the visibility of a registry during or after creating it. Use the following procedure to change the visibility of a registry you have already created. To restrict the visibility of an existing registry: 1. Navigate to the W&B Registry at https://wandb.ai/registry/. 2. Select a registry. -3. Click on the gear icon on the upper right hand corner. -4. From the **Registry visibility** dropdown, select the desired registry visibility. +3. Click the gear icon in the upper right corner. +4. From the **Registry visibility** dropdown, select a visibility option. 5. If you select **Restricted visibility**: - 1. Add members of your organization that you want to have access to this registry. Scroll to the **Registry members and roles** section and click on the **Add member** button. - 2. Within the **Member** field, add the email or username of the member you want to add. - 3. Click **Add new member**. - + a. Add members of your organization who you want to have access to this registry. Scroll to the **Registry members and roles** section and click the **Add member** button. + b. In the **Member** field, add the email or username of the member you want to add. + c. Click **Add new member**. -See [Create a registry](./create_registry#create-a-custom-registry) for more information on how assign the visibility of a registry when a team admin creates it. +For more information about assigning visibility when a team admin creates a registry, see [Create a registry](#create-a-registry). diff --git a/models/registry/delete_registry.mdx b/models/registry/delete_registry.mdx index 7d9ff20ea2..7f75e6d28d 100644 --- a/models/registry/delete_registry.mdx +++ b/models/registry/delete_registry.mdx @@ -3,20 +3,23 @@ title: Delete registry description: "Delete a W&B Registry as a Team admin or Registry admin using the Python SDK or the W&B App UI." --- -This page shows how a Team admin or Registry admin can delete a registry. +This page shows how a Team admin or Registry admin can delete a registry, either programmatically with the Python SDK or interactively in the W&B App UI. Delete a registry when it's no longer needed so that it doesn't clutter your organization's Registry list. + +Permissions to delete a registry depend on your role: - A Team admin can delete any registry in the organization. - A Registry admin can delete a registry that they created. -Deleting a registry also deletes collections that belong to that registry, but does not delete artifacts linked to the registry. Such an artifact remains in the original project that the artifact was logged to. - +Deleting a registry also deletes collections that belong to that registry, but doesn't delete artifacts linked to the registry. Such artifacts remain in the original project that they were logged to. -Use the `wandb` API's `delete()` method to delete a registry programmatically. The following example illustrates how to: +Use the `wandb` API's `delete()` method to delete a registry programmatically. The following example illustrates how to: 1. Fetch the registry you want to delete with `api.registry()`. -1. Call the `delete()` method on the returned registry object to delete the registry. +2. Call the `delete()` method on the returned registry object to delete the registry. + +Replace `[REGISTRY-NAME]` with the name of your registry. ```python import wandb @@ -25,7 +28,7 @@ import wandb api = wandb.Api() # Fetch the registry you want to delete -fetched_registry = api.registry("") +fetched_registry = api.registry("[REGISTRY-NAME]") # Deleting a registry fetched_registry.delete() @@ -34,8 +37,8 @@ fetched_registry.delete() 1. Navigate to the W&B Registry at https://wandb.ai/registry/. 2. Select the registry you want to delete. -3. Click the gear icon in the upper right corner to view the registry's settings. -4. To delete the registry, click the trash can icon in the upper right corner of the settings page. +3. Click the gear icon in the upper-right corner to view the registry's settings. +4. To delete the registry, click the trash can icon in the upper-right corner of the settings page. 5. Confirm the registry to delete by entering its name in the modal that appears, then click **Delete**. \ No newline at end of file diff --git a/models/registry/download_use_artifact.mdx b/models/registry/download_use_artifact.mdx index 1290b7946e..bc73a800bd 100644 --- a/models/registry/download_use_artifact.mdx +++ b/models/registry/download_use_artifact.mdx @@ -3,14 +3,14 @@ title: Download an artifact from a registry description: "Download an artifact linked to a W&B Registry collection by constructing its path and using the Python SDK." --- -Use the W&B Python SDK to download an artifact linked to a registry. To download and use an artifact, you need to know the name of the registry, the name of the collection, and the alias or index of the artifact version you want to download. +Use the W&B Python SDK to download an artifact linked to a registry so you can reuse versioned assets such as models, datasets, or other files in your runs. To download and use an artifact, you need the registry name, the collection name, and the alias or index of the artifact version you want to download. -Once you know the properties of the artifact, you can [construct the path to the linked artifact](#construct-path-to-linked-artifact) and download the artifact. Alternatively, you can [copy and paste a pre-generated code snippet](#copy-and-paste-pre-generated-code-snippet) from the W&B App UI to download an artifact linked to a registry. +Once you know the properties of the artifact, you can [construct the path to the linked artifact](#construct-path-to-linked-artifact) and download the artifact. Alternatively, you can [copy and paste a pre-generated code snippet](#copy-and-paste-pre-generated-code-snippet) from the W&B App UI to download an artifact linked to a registry. ## Construct path to linked artifact -To download an artifact linked to a registry, you must know the path of that linked artifact. The path consists of the registry name, collection name, and the alias or index of the artifact version you want to access. +To download an artifact linked to a registry, you must know the path of that linked artifact. The path consists of the registry name, collection name, and the alias or index of the artifact version you want to access. Once you have the registry, collection, and alias or index of the artifact version, you can construct the path to the linked artifact using the following string template: @@ -25,7 +25,7 @@ f"wandb-registry-{REGISTRY}/{COLLECTION}:{ALIAS}" Replace the values within the curly braces `{}` with the name of the registry, collection, and the alias or index of the artifact version you want to access. -Use the `wandb.Run.use_artifact()` method to access the artifact and download its contents once you have the path of the linked artifact. The following code snippet shows how to use and download an artifact linked to the W&B Registry. Ensure to replace values within `<>` with your own: +Once you have the path of the linked artifact, use the `wandb.Run.use_artifact()` method to access the artifact and download its contents. The following code snippet shows how to use and download an artifact linked to the W&B Registry. Replace values within `<>` with your own: ```python import wandb @@ -37,14 +37,13 @@ ALIAS = '' with wandb.init(entity = '', project = '') as run: artifact_name = f"wandb-registry-{REGISTRY}/{COLLECTION}:{ALIAS}" # artifact_name = '' # Copy and paste Full name specified in the W&B Registry UI - fetched_artifact = run.use_artifact(artifact_or_name = artifact_name) - download_path = fetched_artifact.download() + fetched_artifact = run.use_artifact(artifact_or_name = artifact_name) + download_path = fetched_artifact.download() ``` -The `wandb.Run.use_artifact()` method both creates a [run](/models/runs) and marks the artifact you download as the input to that run. -Marking an artifact as the input to a run enables W&B to track the lineage of that artifact. +The `wandb.Run.use_artifact()` method both creates a [run](/models/runs) and marks the artifact you download as the input to that run, which enables W&B to track the artifact's lineage. -If you do not want to create a run, you can use the `wandb.Api()` object to access the artifact: +If you don't want to create a run, use the `wandb.Api()` object to access the artifact: ```python import wandb @@ -61,7 +60,7 @@ artifact = api.artifact(name = artifact_name)
Example: Use and download an artifact linked to the W&B Registry -The following code example shows how a user can download an artifact linked to a collection called `phi3-finetuned` in the **Fine-tuned Models** registry. The alias of the artifact version is set to `production`. +The following code example shows how to download an artifact linked to a collection called `phi3-finetuned` in the **Fine-tuned Models** registry. The alias of the artifact version is set to `production`. ```python import wandb @@ -79,10 +78,10 @@ with wandb.init(entity=TEAM_ENTITY, project = PROJECT_NAME) as run: artifact_name = f"wandb-registry-{REGISTRY}/{COLLECTION}:{ALIAS}" # Access an artifact and mark it as input to your run for lineage tracking - fetched_artifact = run.use_artifact(artifact_or_name = artifact_name) + fetched_artifact = run.use_artifact(artifact_or_name = artifact_name) # Download artifact. Returns path to downloaded contents - downloaded_path = fetched_artifact.download() + downloaded_path = fetched_artifact.download() ```
@@ -91,9 +90,9 @@ with wandb.init(entity=TEAM_ENTITY, project = PROJECT_NAME) as run: See [`wandb.Run.use_artifact()`](/models/ref/python/experiments/run#use_artifact) and [`Artifact.download()`](/models/ref/python/experiments/artifact#download) in the API Reference for parameters and return type. -**Users with a personal entity that belong to multiple organizations** +**Users with a personal entity who belong to multiple organizations** -Users with a personal entity that belong to multiple organizations must also specify either the name of their organization or use a team entity when accessing artifacts linked to a registry. +Users with a personal entity who belong to multiple organizations must also specify either the name of their organization or use a team entity when accessing artifacts linked to a registry. ```python import wandb @@ -117,7 +116,9 @@ artifact = api.artifact(name = artifact_name) ## Copy and paste pre-generated code snippet -W&B creates a code snippet that you can copy and paste into your Python script, notebook, or terminal to download an artifact linked to a registry. +If you prefer not to construct the artifact path yourself, W&B creates a code snippet that you can copy and paste into your Python script, notebook, or terminal to download an artifact linked to a registry. + +Follow these steps to locate and copy the snippet from the W&B App UI: 1. Navigate to the W&B Registry. 2. Select the name of the registry that contains your artifact. diff --git a/models/registry/lineage.mdx b/models/registry/lineage.mdx index 7d9ab1ddae..f585cfaa76 100644 --- a/models/registry/lineage.mdx +++ b/models/registry/lineage.mdx @@ -3,88 +3,92 @@ description: Use lineage graphs to visualize a linked artifact's history and aud title: Lineage graphs and audit history --- -Use a lineage graph to visualize a linked artifact's history. Audit a collection's history to track changes made to artifacts in that collection. +Use a lineage graph to visualize a linked artifact's history. Audit a collection's history to track changes made to artifacts in that collection. These views help ML practitioners and Registry administrators understand how artifacts evolved across runs and who modified collection contents over time. ## Lineage graphs +This section explains what a lineage graph shows and how to open one for an artifact in a collection. + Within a collection in the W&B Registry, you can view a history of the artifacts that an ML experiment uses. This history is called a _lineage graph_. A lineage graph shows: -* Artifacts used as [inputs to a run](/models/artifacts/explore-and-traverse-an-artifact-graph#track-the-input-of-a-run). -* Artifacts created as [outputs from a run](/models/artifacts/explore-and-traverse-an-artifact-graph#track-the-output-of-a-run). - -In other words, a lineage graph shows the input and output of a run. +- Artifacts used as [inputs to a run](/models/artifacts/explore-and-traverse-an-artifact-graph#track-the-input-of-a-run). +- Artifacts created as [outputs from a run](/models/artifacts/explore-and-traverse-an-artifact-graph#track-the-output-of-a-run). -For example, the following image shows a typical lineage graph for artifacts created and used throughout an ML experiment: +For example, the following image shows a lineage graph for artifacts created and used throughout an ML experiment: - Registry lineage + Registry lineage From left to right, the image shows: 1. Multiple runs log the `split_zoo_dataset:v0` artifact. -2. The "zesty-snowball-7" run uses the `split_zoo_dataset:v0` artifact for training. -3. The output of the "zesty-snowball-7" run is a model artifact called `zoo-qne08r7u:v0`. -4. A run called "glamorous-planet-8" uses the model artifact `zoo-qne08r7u:v0` to evaluate the model. +2. The `zesty-snowball-7` run uses the `split_zoo_dataset:v0` artifact for training. +3. The output of the `zesty-snowball-7` run is a model artifact called `zoo-qne08r7u:v0`. +4. A run called `glamorous-planet-8` uses the model artifact `zoo-qne08r7u:v0` to evaluate the model. To view a lineage graph for an artifact in a collection: 1. Navigate to the W&B Registry. 2. Select the collection that contains the artifact. -3. From the dropdown, select the artifact version you want to view its lineage graph. +3. From the dropdown, select the artifact version whose lineage graph you want to view. 4. Select the **Lineage** tab. 5. Select a node to view detailed information about the run or artifact. +The **Lineage** tab displays the selected artifact version's input and output history. To inspect an individual run or artifact, select its node. + -See [Enable lineage graph tracking](/models/artifacts/explore-and-traverse-an-artifact-graph#enable-lineage-graph-tracking) to learn how to track the input and output of a run using the W&B Python SDK. +To learn how to track the input and output of a run using the W&B Python SDK, see [Enable lineage graph tracking](/models/artifacts/explore-and-traverse-an-artifact-graph#enable-lineage-graph-tracking). -The following image shows the expanded detailed view of a run (`zesty-snowball-7`) when you select a node in the lineage graph: +The following image shows the expanded view of a run (`zesty-snowball-7`) when you select a node in the lineage graph: - Expanded lineage node + Expanded lineage node -The following image shows the expanded detailed view of an artifact (`zoo-qne08r7u:v0`) when you select an artifact node in the lineage graph: +The following image shows the expanded view of an artifact (`zoo-qne08r7u:v0`) when you select an artifact node in the lineage graph: - Expanded artifact node details + Expanded artifact node details -You can also view lineage graphs for artifacts you log to W&B that are not part of a collection. See [Explore artifact graphs](/models/artifacts/explore-and-traverse-an-artifact-graph) for more information. +You can also view lineage graphs for artifacts you log to W&B that aren't part of a collection. For more information, see [Explore artifact graphs](/models/artifacts/explore-and-traverse-an-artifact-graph). - + ### Create a custom view Click **Custom** in the top-right corner of the lineage graph to create a custom view. You can filter and customize the lineage graph with the following options: -* **Filter by artifact type**: Filter by artifact type values logged to W&B. For example, if you log an artifact with the type "dataset", then "dataset" is available as a filter value. -* **Filter by run job type**: Filter by run job type values logged to W&B. For example, if you log a run with the job type "training", then "training" is available as a filter value. -* **Include extended lineage**: Display items that are not in the direct lineage for the base version. -* **Include generated artifacts**: Items created programmatically will show. -* **Expand clusters**: Similar items with similar connections will not be grouped together. -* **Downstream hops**: Descendant generations relative to the active node. -* **Upstream hops**: Ancestor generations relative to the active node. +- **Filter by artifact type**: Filter by artifact type values logged to W&B. For example, if you log an artifact with the type "dataset", then "dataset" is available as a filter value. +- **Filter by run job type**: Filter by run job type values logged to W&B. For example, if you log a run with the job type "training", then "training" is available as a filter value. +- **Include extended lineage**: Display items that are not in the direct lineage for the base version. +- **Include generated artifacts**: Items created programmatically will show. +- **Expand clusters**: Similar items with similar connections will not be grouped together. +- **Downstream hops**: Descendant generations relative to the active node. +- **Upstream hops**: Ancestor generations relative to the active node. To reset the lineage graph to its default view, click the backward arrow button. ## Audit a collection's history -View actions that members of your organization take on that collection. You can view: +This section explains how to review the action history of a collection so you can track who changed what and when. + +View actions that members of your organization take on that collection. You can view the following actions: -- If an alias was added or removed from an artifact version. -- If an artifact version was added or removed from a collection. +- Whether someone added or removed an alias from an artifact version. +- Whether someone added or removed an artifact version from a collection. -For both actions, you can view the user that performed the action and the date the action occurred. +For both actions, you can view the user who performed the action and the date the action occurred. To view a collection's action history: 1. Navigate to the W&B Registry. -2. Select the collection you want to view its action history. +2. Select the collection whose action history you want to view. 3. Select the dropdown menu next to the collection name. 4. Select the **Action History** option. diff --git a/models/registry/link_version.mdx b/models/registry/link_version.mdx index a1abe8999e..6cf5e2e9f1 100644 --- a/models/registry/link_version.mdx +++ b/models/registry/link_version.mdx @@ -4,20 +4,22 @@ description: "Link an artifact version to a collection in W&B Registry to share --- -To make an artifact version available to your organization, *link* it to a [collection](/models/registry/create_collection) in +This page describes how to publish an artifact version to a registry collection so that other teams in your organization can discover and use it. Use this workflow when you have a trained model, dataset, or other artifact that's ready to share beyond the project where it was logged. + +To make an artifact version available to your organization, link it to a [collection](/models/registry/create_collection) in the W&B Registry. Linking moves the version from a [private, project-level scope to a shared, organization-level scope](/models/registry/create_registry#visibility-types). You -can link an artifact version [programmatically by using the W&B Python SDK or interactively in the W&B App](/models/registry/link_version#link-an-artifact-to-a-collection). +can link an artifact version [programmatically with the W&B Python SDK or interactively in the W&B App](/models/registry/link_version#link-an-artifact-to-a-collection). When you link an artifact, W&B creates a reference between the source artifact and the collection entry. The linked version points to the source artifact version that was logged to a run within a project. You can view both the linked version in the collection and the source version in the project where it was logged. ## Link an artifact to a collection -Based on your use case, follow the instructions described in the tabs below to link an artifact version. +You can link an artifact version programmatically with the W&B Python SDK or interactively in the W&B App. Based on your use case, follow the instructions described in the following tabs to link an artifact version. Before you start, check the following: -* The types of artifacts that collection permits. For more information about collection types, see "Collection types" within [Create a collection](./create_collection). +* The types of artifacts that the collection permits. For more information about collection types, see "Collection types" within [Create a collection](./create_collection). * The registry that the collection belongs to already exists. To check that the registry exists, navigate to the [Registry App and search for](/models/registry/search_registry) the name of the registry. @@ -37,7 +39,7 @@ Programmatically link an artifact version to a collection with [`wandb.Run.link_ -Use `wandb.Run.link_artifact()` to link an artifact version [within the context of a run](#link-an-artifact-version-within-the-context-of-a-run). Use `wandb.Artifact.link()` to link an *existing artifact version* [outside the context of a run](#link-an-artifact-version-outside-the-context-of-a-run). +Use `wandb.Run.link_artifact()` to link an artifact version [within the context of a run](#link-an-artifact-version-within-the-context-of-a-run). Use `wandb.Artifact.link()` to link an existing artifact version [outside the context of a run](#link-an-artifact-version-outside-the-context-of-a-run). @@ -45,14 +47,14 @@ Use `wandb.Run.link_artifact()` to link an artifact version [within the context `wandb.Artifact.link()` does not require you to initialize a run with `wandb.init()`. `wandb.Run.link_artifact()` requires you to initialize a run with `wandb.init()`. */} -For both approaches, specify the name of the artifact (`wandb.Artifact(name=""`), the type of artifact (`wandb.Artifact(type=""`), and the `target_path` (`wandb.Artifact(target_path=""`)) of the collection and registry you want to link the artifact version to. +For both approaches, specify the name of the artifact (`wandb.Artifact(name="[NAME]"`), the type of artifact (`wandb.Artifact(type="[TYPE]"`), and the `target_path` (`wandb.Artifact(target_path="[TARGET-PATH]"`)) of the collection and registry you want to link the artifact version to. -The target path consists of the prefix `"wandb-registry"`, the name of the registry, and the name of the collection separated by a forward slashes: +The target path consists of the prefix `"wandb-registry"`, the name of the registry, and the name of the collection, separated by forward slashes: {/* Use the `target_path` parameter to specify the collection and registry you want to link the artifact version to. The target path consists of the prefix "wandb-registry", the name of the registry, and the name of the collection separated by a forward slashes: */} ```text -wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME} +wandb-registry-[REGISTRY-NAME]/[COLLECTION-NAME] ``` ### Link an artifact version within the context of a run @@ -60,15 +62,15 @@ wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME} Use `wandb.Run.link_artifact()` to link an artifact version within the context of a run. To do so, first initialize a run with `wandb.init()`. Next, create an artifact object and add files to it. Finally, use the `wandb.Run.link_artifact()` method to link the artifact version to the collection. -When you use this approach, a run is created in your W&B project. The artifact version is linked to the collection and is associated with that run. +When you use this approach, W&B creates a run in your project. The artifact version is linked to the collection and associated with that run. -Copy and paste the code snippet below. Replace values enclosed in `<>` with your own: +Copy and paste the following code snippet. Replace values enclosed in `[]` with your own: ```python import wandb -entity = "" # Your team entity -project = "" # The name of the project that contains your artifact +entity = "[TEAM-ENTITY]" # Your team entity +project = "[PROJECT-NAME]" # The name of the project that contains your artifact # Initialize a run with wandb.init(entity = entity, project = project) as run: @@ -76,15 +78,15 @@ with wandb.init(entity = entity, project = project) as run: # Create an artifact object # The type parameter specifies both the type of the # artifact object and the collection type - artifact = wandb.Artifact(name = "", type = "") + artifact = wandb.Artifact(name = "[NAME]", type = "[TYPE]") # Add the file to the artifact object. # Specify the path to the file on your local machine. - artifact.add_file(local_path = "") + artifact.add_file(local_path = "[LOCAL-PATH-TO-ARTIFACT]") # Specify the collection and registry to link the artifact to - REGISTRY_NAME = "" - COLLECTION_NAME = "" + REGISTRY_NAME = "[REGISTRY-NAME]" + COLLECTION_NAME = "[COLLECTION-NAME]" target_path=f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}" # Link the artifact to the collection @@ -94,12 +96,12 @@ with wandb.init(entity = entity, project = project) as run: ### Link an artifact version outside the context of a run Use `wandb.Artifact.link()` to link an existing artifact version outside the context of a run. With this approach, -you do not need to initialize a run with `wandb.init()`. This means that a run is not created in your W&B project. In other +you don't need to initialize a run with `wandb.init()`. This means that W&B doesn't create a run in your project. In other words, the artifact version is linked to the collection without being associated with a run. First, create an artifact object and add files to it. Next, use the `wandb.Artifact.link()` method to link the artifact version to the collection. -Copy and paste the code snippet below. Replace values enclosed in `<>` with your own: +Copy and paste the following code snippet. Replace values enclosed in `[]` with your own: ```python import wandb @@ -107,15 +109,15 @@ import wandb # Create an artifact object # The type parameter specifies both the type of the # artifact object and the collection type -artifact = wandb.Artifact(name = "", type = "") +artifact = wandb.Artifact(name = "[NAME]", type = "[TYPE]") # Add the file to the artifact object. # Specify the path to the file on your local machine. -artifact.add_file(local_path = "") +artifact.add_file(local_path = "[LOCAL-PATH-TO-ARTIFACT]") # Specify the collection and registry to link the artifact to -REGISTRY_NAME = "" -COLLECTION_NAME = "" +REGISTRY_NAME = "[REGISTRY-NAME]" +COLLECTION_NAME = "[COLLECTION-NAME]" target_path=f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}" # Link the artifact to the collection @@ -134,20 +136,20 @@ artifact.link(target_path = target_path) 3. Select the **action ()** menu next to **View details**. 4. From the dropdown, select **Link new version**. 5. From the sidebar that appears, select the name of a team from the **Team** dropdown. -5. From the **Project** dropdown, select the name of the project that contains your artifact. -6. From the **Artifact** dropdown, select the name of the artifact. -7. From the **Version** dropdown, select the artifact version you want to link to the collection. +6. From the **Project** dropdown, select the name of the project that contains your artifact. +7. From the **Artifact** dropdown, select the name of the artifact. +8. From the **Version** dropdown, select the artifact version you want to link to the collection. {/* TO DO insert gif */} -1. Navigate to your project's artifact browser on the W&B App at: `https://wandb.ai///artifacts` +1. Navigate to your project's artifact browser on the W&B App at: `https://wandb.ai/[ENTITY]/[PROJECT]/artifacts` 2. Select the Artifacts icon in the project sidebar. -3. Click on the artifact version you want to link to your registry. +3. Click the artifact version you want to link to your registry. 4. Within the **Version overview** section, click the **Link to registry** button. -5. From the modal that appears on the right of the screen, select an artifact from the **Select a register model** menu dropdown. +5. From the modal that appears, select an artifact from the **Select a register model** menu dropdown. 6. Click **Next step**. -7. (Optional) Select an alias from the **Aliases** dropdown. +7. Optional: Select an alias from the **Aliases** dropdown. 8. Click **Link to registry**. {/* Update this gif */} @@ -166,34 +168,34 @@ artifact.link(target_path = target_path) * Linked version: the artifact version that is published to the registry. This is a pointer to the source artifact, and is the exact same artifact version, just made available in the scope of the registry. */} -You can [view a linked artifact's metadata, version data, usage, lineage information](/models/registry/link_version#view-linked-artifacts-in-a-registry") and more in the Registry App. +You can [view a linked artifact's metadata, version data, usage, and lineage information](/models/registry/link_version#view-linked-artifacts-in-a-registry) in the Registry App. ## View linked artifacts in a registry -View information about linked artifacts such as metadata, lineage, and usage information in the W&B Registry. +After you link an artifact version, it becomes available to your organization through the registry. View information about linked artifacts such as metadata, lineage, and usage information in the W&B Registry. 1. Navigate to the W&B Registry. 2. Select the name of the registry that you linked the artifact to. 3. Select the name of the collection. 4. If the collection's artifacts log metrics, compare metrics across versions by clicking **Show metrics**. -4. From the list of artifact versions, select the version you want to access. Version numbers are incrementally assigned to each linked artifact version starting with `v0`. -5. To view details about an artifact version, click the version. From the tabs in this page, you can view that version's metadata (including logged metrics), lineage, and usage information. +5. From the list of artifact versions, select the version you want to access. W&B assigns version numbers incrementally to each linked artifact version, starting with `v0`. +6. To view details about an artifact version, click the version. From the tabs on this page, you can view that version's metadata (including logged metrics), lineage, and usage information. -Make note of the **Full Name** field within the **Version** tab. The full name of a linked artifact consists of the registry, collection name, and the alias or index of the artifact version. +Record the **Full Name** field within the **Version** tab. The full name of a linked artifact consists of the registry, collection name, and the alias or index of the artifact version. ```text title="Full name of a linked artifact" -wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}:v{INTEGER} +wandb-registry-[REGISTRY-NAME]/[COLLECTION-NAME]:v[INTEGER] ``` You need the full name of a linked artifact to access the artifact version programmatically. -## Troubleshooting +## Troubleshooting -Below are some common things to double check if you are not able to link an artifact. +If you can't link an artifact, the following sections describe common causes and how to resolve them. -### Logging artifacts from a personal account +### Artifacts logged from a personal account -Artifacts logged to W&B with a personal entity can not be linked to the registry. Make sure that you log artifacts using a team entity within your organization. Only artifacts logged within an organization's team can be linked to the organization's registry. +You can't link artifacts logged to W&B with a personal entity to the registry. Make sure that you log artifacts with a team entity within your organization. Only artifacts logged within an organization's team can be linked to the organization's registry. @@ -203,30 +205,30 @@ Ensure that you log an artifact with a team entity if you want to link that arti #### Find your team entity -W&B uses the name of your team as the team's entity. For example, if your team is called **team-awesome**, your team entity is `team-awesome`. +W&B uses the name of your team as the team's entity. For example, if your team is called `team-awesome`, your team entity is `team-awesome`. -You can confirm the name of your team by: +To confirm the name of your team, follow these steps: 1. Navigate to your team's W&B profile page. -2. Copy the site's URL. It has the form of `https://wandb.ai/`. Where `` is the both the name of your team and the team's entity. +2. Copy the site's URL. It has the form `https://wandb.ai/[TEAM]`, where `[TEAM]` is both the name of your team and the team's entity. #### Log from a team entity -1. Specify the team as the entity when you initialize a run with [`wandb.init()`](/models/ref/python/functions/init). If you do not specify the `entity` when you initialize a run, the run uses your default entity which may or may not be your team entity. +1. Specify the team as the entity when you initialize a run with [`wandb.init()`](/models/ref/python/functions/init). If you don't specify the `entity` when you initialize a run, the run uses your default entity, which may or may not be your team entity. ```python import wandb - with wandb.init(entity='', project='') as run: + with wandb.init(entity='[TEAM-ENTITY]', project='[PROJECT-NAME]') as run: # Log your artifact here ``` 2. Log the artifact to the run either with `wandb.Run.log_artifact()` or by creating an Artifact object and then adding files to it with: ```python - artifact = wandb.Artifact(name="", type="") + artifact = wandb.Artifact(name="[ARTIFACT-NAME]", type="[TYPE]") ``` To log artifacts, see [Construct artifacts](/models/artifacts/construct-an-artifact/). -3. If an artifact is logged to your personal entity, you will need to re-log it to an entity within your organization. +3. If you logged an artifact to your personal entity, you need to re-log it to an entity within your organization. ### Confirm the path of a registry in the W&B App UI @@ -234,22 +236,22 @@ Create an empty collection to confirm the path of the registry in the W&B App UI 1. Navigate to the W&B Registry at https://wandb.ai/registry/. 2. Click the registry you want to link an artifact to. -4. Click on the empty collection. If an empty collection does not exist, create a new collection. -5. Within the code snippet that appears, identify the `target_path` field within `.link_artifact()`. -6. (Optional) Delete the collection. +3. Click the empty collection. If an empty collection doesn't exist, create a new collection. +4. Within the code snippet that appears, identify the `target_path` field within `.link_artifact()`. +5. Optional: Delete the collection. Create an empty collection -For example, after completing the steps outlined, you find the code block with the `target_path` parameter: +For example, after you complete the preceding steps, you find the code block with the `target_path` parameter: ```python target_path = "smle-registries-bug-bash/wandb-registry-Golden Datasets/raw_images" ``` -Breaking this down into its components, you can see what you will need to use to create the path to link your artifact programmatically: +Break this down into its components to see what you need to use to create the path to link your artifact programmatically: ```python ORG_ENTITY_NAME = "smle-registries-bug-bash" diff --git a/models/registry/organize-with-tags.mdx b/models/registry/organize-with-tags.mdx index 704effedb6..c4bfac367f 100644 --- a/models/registry/organize-with-tags.mdx +++ b/models/registry/organize-with-tags.mdx @@ -4,20 +4,22 @@ description: Use tags to organize collections or artifact versions within collec title: Organize versions with tags --- -Create and add tags to organize your collections or artifact versions within your registry. Add, modify, view, or remove tags to a collection or artifact version with the W&B App UI or the W&B Python SDK. +Tags help you organize and find collections or artifact versions within a registry. Unlike aliases, tags are flexible labels that can be shared across multiple versions or collections, which makes them useful for grouping related items and for search. + +This page shows how to add, modify, view, and remove tags on a collection or artifact version using either the W&B App UI or the W&B Python SDK. **When to use a tag versus using an alias** Use aliases when you need to reference a specific artifact version uniquely. For example, use an alias such as 'production' or 'latest' to ensure that `artifact_name:alias` always points to a single, specific version. -Use tags when you want more flexibility for grouping or searching. Tags are ideal when multiple versions or collections can share the same label, and you don’t need the guarantee that only one version is associated with a specific identifier. +Use tags when you want more flexibility for grouping or searching. Tags are ideal when multiple versions or collections can share the same label, and you don't need the guarantee that only one version is associated with a specific identifier. ## Add a tag to a collection -Use the W&B App UI or Python SDK to add a tag to a collection: +Tagging a collection makes it easier to group related collections and to find them later through search. Use the W&B App UI or Python SDK to add a tag to a collection. @@ -34,9 +36,9 @@ Use the W&B App UI to add a tag to a collection: ```python import wandb -COLLECTION_TYPE = "" -REGISTRY_NAME = "" -COLLECTION_NAME = "" +COLLECTION_TYPE = "[COLLECTION-TYPE]" +REGISTRY_NAME = "[REGISTRY-NAME]" +COLLECTION_NAME = "[COLLECTION-NAME]" full_name = f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}" @@ -55,9 +57,9 @@ collection.save() ## Update tags that belong to a collection -Update a tag programmatically by reassigning or by mutating the `tags` attribute. W&B recommends, and it is good Python practice, that you reassign the `tags` attribute instead of in-place mutation. +When you need to change a collection's existing tags, you can update them programmatically by either reassigning or mutating the `tags` attribute. W&B recommends that you reassign the `tags` attribute rather than mutate it in place, which is also a common Python best practice. -For example, the following code snippet shows common ways to update a list with reassignment. For brevity, we continue the code example from the [Add a tag to a collection section](#add-a-tag-to-a-collection): +The following code snippet shows common ways to update the list of tags through reassignment. For brevity, it continues the code example from [Add a tag to a collection](#add-a-tag-to-a-collection): ```python collection.tags = [*collection.tags, "new-tag", "other-tag"] @@ -82,7 +84,7 @@ collection.tags.clear() ## View tags that belong to a collection -Use the W&B App UI to view tags added to a collection: +Reviewing a collection's tags helps you confirm how it has been organized and labeled. Use the W&B App UI to view the tags added to a collection. 1. Navigate to the [W&B Registry](https://wandb.ai/registry). 2. Click on a registry card. @@ -105,7 +107,7 @@ For example, in the following image, a tag called "sample-tag-1" was added to th ## Remove a tag from a collection -Use the W&B App UI to remove a tag from a collection: +Remove a tag when it no longer applies to a collection or when you want to reorganize how collections are grouped. Use the W&B App UI to remove a tag from a collection. 1. Navigate to the [W&B Registry](https://wandb.ai/registry). 2. Click on a registry card. @@ -115,11 +117,13 @@ Use the W&B App UI to remove a tag from a collection: ## Add a tag to an artifact version -Add a tag to an artifact version linked to a collection with the W&B App UI or with the Python SDK. +You can also tag individual artifact versions within a collection. This makes it easier to label versions with status indicators such as `staging` or `experimental` and to locate them later. Add a tag to an artifact version that is linked to a collection with the W&B App UI or with the Python SDK. -1. Navigate to the W&B Registry at https://wandb.ai/registry +Use the W&B App UI to add a tag to an artifact version: + +1. Navigate to the [W&B Registry](https://wandb.ai/registry). 2. Click on a registry card. 3. Click **View details** next to the name of the collection you want to add a tag to. 4. Scroll down to **Versions**. @@ -129,21 +133,21 @@ Add a tag to an artifact version linked to a collection with the W&B App UI or w -Fetch the artifact version you want to add or update a tag to. Once you have the artifact version, you can access the artifact object's `tag` attribute to add or modify tags to that artifact. Pass in one or more tags as list to the artifacts `tag` attribute. +Fetch the artifact version you want to add or update a tag on. After you have the artifact version, access the artifact object's `tags` attribute to add or modify tags on that artifact. Pass in one or more tags as a list to the artifact's `tags` attribute. -Like other artifacts, you can fetch an artifact from W&B without creating a run or you can create a run and fetch the artifact within that run. In either case, ensure to call the artifact object's `save` method to update the artifact on the W&B servers. +Like other artifacts, you can fetch an artifact from W&B without creating a run, or you can create a run and fetch the artifact within that run. In either case, call the artifact object's `save` method to update the artifact on the W&B servers. -Copy and paste an appropriate code cells below to add or modify an artifact version's tag. Replace the values in `<>` with your own. +Copy and paste one of the following code cells to add or modify an artifact version's tag. Replace the bracketed placeholders with your own values. The following code snippet shows how to fetch an artifact and add a tag without creating a new run: ```python title="Add a tag to an artifact version without creating a new run" import wandb -ARTIFACT_TYPE = "" -REGISTRY_NAME = "" -COLLECTION_NAME = "" -VERSION = "" +ARTIFACT_TYPE = "[TYPE]" +REGISTRY_NAME = "[REGISTRY-NAME]" +COLLECTION_NAME = "[COLLECTION-NAME]" +VERSION = "[ARTIFACT-VERSION]" artifact_name = f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}:v{VERSION}" @@ -158,11 +162,11 @@ The following code snippet shows how to fetch an artifact and add a tag by creat ```python title="Add a tag to an artifact version during a run" import wandb -REGISTRY_NAME = "" -COLLECTION_NAME = "" -VERSION = "" +REGISTRY_NAME = "[REGISTRY-NAME]" +COLLECTION_NAME = "[COLLECTION-NAME]" +VERSION = "[ARTIFACT-VERSION]" -with wandb.init(entity = "", project="") as run: +with wandb.init(entity = "[ENTITY]", project="[PROJECT]") as run: artifact_name = f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}:v{VERSION}" @@ -177,10 +181,9 @@ with wandb.init(entity = "", project="") as run: ## Update tags that belong to an artifact version +When you need to change the tags on an existing artifact version, you can update them programmatically by either reassigning or mutating the `tags` attribute. W&B recommends that you reassign the `tags` attribute rather than mutate it in place, which is also a common Python best practice. -Update a tag programmatically by reassigning or by mutating the `tags` attribute. W&B recommends, and it is good Python practice, that you reassign the `tags` attribute instead of in-place mutation. - -For example, the following code snippet shows common ways to update a list with reassignment. For brevity, we continue the code example from the [Add a tag to an artifact version section](#add-a-tag-to-an-artifact-version): +The following code snippet shows common ways to update the list of tags through reassignment. For brevity, it continues the code example from [Add a tag to an artifact version](#add-a-tag-to-an-artifact-version): ```python artifact.tags = [*artifact.tags, "new-tag", "other-tag"] @@ -206,14 +209,16 @@ artifact.tags.clear() ## View tags that belong to an artifact version -View tags that belong to an artifact version that is linked to a registry with the W&B App UI or with the Python SDK. +Reviewing an artifact version's tags helps you confirm its labels and intended use. View the tags that belong to an artifact version linked to a registry with the W&B App UI or with the Python SDK. +Use the W&B App UI to view the tags that belong to an artifact version: + 1. Navigate to the [W&B Registry](https://wandb.ai/registry). 2. Click on a registry card. 3. Click **View details** next to the name of the collection you want to add a tag to. -4. Scroll down to **Versions** section. +4. Scroll down to the **Versions** section. If an artifact version has one or more tags, you can view those tags within the **Tags** column. @@ -222,21 +227,21 @@ If an artifact version has one or more tags, you can view those tags within the -Fetch the artifact version to view its tags. Once you have the artifact version, you can view tags that belong to that artifact by viewing the artifact object's `tag` attribute. +Fetch the artifact version to view its tags. After you have the artifact version, view tags that belong to that artifact through the artifact object's `tags` attribute. -Similar to other artifacts, you can fetch an artifact from W&B without creating a run or you can create a run and fetch the artifact within that run. +Like other artifacts, you can fetch an artifact from W&B without creating a run, or you can create a run and fetch the artifact within that run. -Copy and paste an appropriate code cells below to add or modify an artifact version's tag. Replace the values in `<>` with your own. +Copy and paste one of the following code cells to add or modify an artifact version's tag. Replace the bracketed placeholders with your own values. The following code snippet shows how to fetch and view an artifact version's tags without creating a new run: ```python title="Add a tag to an artifact version without creating a new run" import wandb -ARTIFACT_TYPE = "" -REGISTRY_NAME = "" -COLLECTION_NAME = "" -VERSION = "" +ARTIFACT_TYPE = "[TYPE]" +REGISTRY_NAME = "[REGISTRY-NAME]" +COLLECTION_NAME = "[COLLECTION-NAME]" +VERSION = "[ARTIFACT-VERSION]" artifact_name = f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}:v{VERSION}" @@ -250,11 +255,11 @@ The following code snippet shows how to fetch and view artifact version's tags b ```python title="Add a tag to an artifact version during a run" import wandb -REGISTRY_NAME = "" -COLLECTION_NAME = "" -VERSION = "" +REGISTRY_NAME = "[REGISTRY-NAME]" +COLLECTION_NAME = "[COLLECTION-NAME]" +VERSION = "[ARTIFACT-VERSION]" -with wandb.init(entity = "", project="") as run: +with wandb.init(entity = "[ENTITY]", project="[PROJECT]") as run: artifact_name = f"wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME}:v{VERSION}" @@ -268,17 +273,19 @@ with wandb.init(entity = "", project="") as run: ## Remove a tag from an artifact version +Remove a tag from an artifact version when the tag no longer applies. Use the W&B App UI to remove a tag from an artifact version: + 1. Navigate to the [W&B Registry](https://wandb.ai/registry). 2. Click on a registry card. -3. Click **View details** next to the name of the collection you want to add a tag to -4. Scroll down to **Versions** -5. Click **View** next to an artifact version -6. Within the **Version** tab, hover your mouse over the name of the tag -7. Click on the cancel button (**X** icon) +3. Click **View details** next to the name of the collection you want to add a tag to. +4. Scroll down to **Versions**. +5. Click **View** next to an artifact version. +6. Within the **Version** tab, hover your mouse over the name of the tag. +7. Click on the cancel button (**X** icon). {/* ## Search existing tags -Use the W&B App UI to search existing tags in collections and artifact versions: +After you've added tags, you can use them to quickly find collections and artifact versions. Use the W&B App UI to search existing tags across collections and artifact versions: 1. Navigate to the [W&B Registry](https://wandb.ai/registry). 2. Click on a registry card. @@ -287,16 +294,16 @@ Use the W&B App UI to search existing tags in collections and artifact versions: ## Find artifact versions with a specific tag -Use the W&B Python SDK to find artifact versions that have a set of tags: +When you want to programmatically locate every artifact version that shares a set of tags, use the W&B Python SDK. This is useful for building automation around tagged versions, such as promoting all versions tagged `ready-for-review`. ```python import wandb api = wandb.Api() tagged_artifact_versions = api.artifacts( - type_name = "", - name = "", - tags = ["", ""] + type_name = "[ARTIFACT-TYPE]", + name = "[ARTIFACT-NAME]", + tags = ["[TAG-1]", "[TAG-2]"] ) for artifact_version in tagged_artifact_versions: diff --git a/models/registry/registry_cards.mdx b/models/registry/registry_cards.mdx index eef9724778..ce904dec6d 100644 --- a/models/registry/registry_cards.mdx +++ b/models/registry/registry_cards.mdx @@ -3,52 +3,47 @@ title: Annotate collections description: "Add descriptions and documentation to W&B Registry collections to help users understand their purpose and contents." --- -Add human-friendly text to your collections to help users understand the purpose of the collection and the artifacts it contains. - - -Depending on the collection, you might want to include information about the training data, model architecture, task, license, references, and deployment. The following lists some topics worth documenting in a collection: - +Add human-friendly text to your collections to help collaborators and downstream users understand the purpose of the collection and the artifacts it contains. Well-annotated collections make it easier for others to discover, evaluate, and reuse your artifacts. +Depending on the collection, you might want to include information about the training data, model architecture, task, license, references, and deployment. The following sections describe topics worth documenting in a collection. W&B recommends including at minimum these details: * **Summary**: The purpose of the collection. The machine learning framework used for the machine learning experiment. -* **License**: The legal terms and permissions associated with the use of the machine learning model. It helps model users understand the legal framework under which they can utilize the model. Common licenses include Apache 2.0, MIT, and GPL. +* **License**: The legal terms and permissions associated with the use of the machine learning model. It helps model users understand the legal framework under which they can use the model. Common licenses include Apache 2.0, MIT, and GPL. * **References**: Citations or references to relevant research papers, datasets, or external resources. If your collection contains training data, consider including these additional details: -* **Training data**: Describe the training data used -* **Processing**: Processing done on the training data set. -* **Data storage**: Where is that data stored and how to access it. - +* **Training data**: Describe the training data used. +* **Processing**: Processing done on the training dataset. +* **Data storage**: Where the data is stored and how to access it. If your collection contains a machine learning model, consider including these additional details: * **Architecture**: Information about the model architecture, layers, and any specific design choices. -* **Task**: The specific type of task or problem that the machine that the collection model is designed to perform. It's a categorization of the model's intended capability. +* **Task**: The specific type of task or problem that the collection's model is designed to perform. It's a categorization of the model's intended capability. * **Deserialize the model**: Provide information on how someone on your team can load the model into memory. -* **Deployment**: Details on how and where the model is deployed and guidance on how the model is integrated into other enterprise systems, such as a workflow orchestration platforms. - +* **Deployment**: Details on how and where the model is deployed and guidance on how the model is integrated into other enterprise systems, such as workflow orchestration platforms. ## Add a description to a collection -Interactively or programmatically add a description to a collection with the W&B Registry UI or Python SDK. +After you've decided what to document, add a description to the collection so that the information is visible to others. You can add a description interactively through the W&B Registry UI or programmatically with the Python SDK. 1. Navigate to the [W&B Registry](https://wandb.ai/registry/). -2. Click on a collection. +2. Click a collection. 3. Select **View details** next to the name of the collection. -4. Within the **Description** field, provide information about your collection. Format text within with [Markdown markup language](https://www.markdownguide.org/). +4. Within the **Description** field, provide information about your collection. Format the text with [Markdown markup language](https://www.markdownguide.org/). -Use the [`wandb.Api().artifact_collection()`](/models/ref/python/public-api/api#artifact_collection) method to access a collection's description. Use the returned object's `description` property to add, or update, a description to the collection. +Use the [`wandb.Api().artifact_collection()`](/models/ref/python/public-api/api#artifact_collection) method to access a collection's description. Use the returned object's `description` property to add or update a description to the collection. -Specify the collection's type for the `type_name` parameter and the collection's full name for the `name` parameter. A collection's name consists of the prefix “wandb-registry”, the name of the registry, and the name of the collection separated by a forward slashes: +Specify the collection's type for the `type_name` parameter and the collection's full name for the `name` parameter. A collection's full name prepends the prefix `wandb-registry-` to the registry name, followed by a forward slash and the collection name: ```text -wandb-registry-{REGISTRY_NAME}/{COLLECTION_NAME} +wandb-registry-[REGISTRY-NAME]/[COLLECTION-NAME] ``` -Copy and paste the following code snippet into your Python script or notebook. Replace values enclosed in angle brackets (`<>`) with your own. +Copy and paste the following code snippet into your Python script or notebook. Replace `[COLLECTION-TYPE]` with the collection's type and `[COLLECTION-NAME]` with the full name of the collection. ```python import wandb @@ -56,19 +51,19 @@ import wandb api = wandb.Api() collection = api.artifact_collection( - type_name = "", - name = "" + type_name = "[COLLECTION-TYPE]", + name = "[COLLECTION-NAME]" ) collection.description = "This is a description." -collection.save() +collection.save() ``` -For example, the following image shows a collection that documents a model's architecture, intended use, performance information and more. +After you save a description, it appears on the collection's card in the registry, where teammates can read it when they browse or evaluate the collection. For example, the following image shows a collection that documents a model's architecture, intended use, performance information, and more. - Collection card + Collection card diff --git a/models/registry/search_registry.mdx b/models/registry/search_registry.mdx index 0373478456..c2141cb62d 100644 --- a/models/registry/search_registry.mdx +++ b/models/registry/search_registry.mdx @@ -3,22 +3,24 @@ title: Find registry items description: "Learn how to search for registries, collections, and artifact versions in the W&B Registry using the global search bar or queries." --- +This page describes how to locate registry items, either interactively through the W&B App or programmatically through the W&B Python SDK. Use these techniques to find a specific registry, collection, or artifact version. You can also filter a large set of items to those that match specific criteria. + Use the [global search bar in the W&B Registry](./search_registry#search-for-registry-items) to find a registry, collection, artifact version tag, collection tag, or alias. You can use queries to [filter registries, collections, and artifact versions](/models/registry/search_registry#query-registry-items) based on specific criteria using the W&B Python SDK. -The syntax and available operators you can use to query W&B Registry is similar, but not identical, to MongoDB queries. +The syntax and available operators you can use to query W&B Registry are similar, but not identical, to MongoDB queries. Only items that you have permission to view appear in the search results. ## Search for registry items -Use the W&B App to search for a registry item: +The following steps describe how to use the W&B App to search for a registry item: 1. Navigate to the W&B Registry. 2. Specify the search term in the search bar at the top of the page. Press Enter to search. -Search results appear below the search bar if the term you specify matches an existing registry, collection name, artifact version tag, collection tag, or alias. +Search results appear if the term you specify matches an existing registry, collection name, artifact version tag, collection tag, or alias. ## Query registry items @@ -40,15 +42,15 @@ The following sections describe the available registry [query names](/models/reg The following table lists query names you can use based on the type of item you want to filter: -| | query name | +| Item type | Query name | | ----- | ----- | -| registries | `name`, `description`, `created_at`, `updated_at` | -| collections | `name`, `tag`, `description`, `created_at`, `updated_at` | -| versions | `tag`, `alias`, `created_at`, `updated_at`, `metadata` | +| Registries | `name`, `description`, `created_at`, `updated_at` | +| Collections | `name`, `tag`, `description`, `created_at`, `updated_at` | +| Versions | `tag`, `alias`, `created_at`, `updated_at`, `metadata` | ### Supported operators -W&B supports the following comparison and logical operators for filtering registry items: +Use operators within a query predicate to express the comparison or logical relationship between a field and its value. W&B supports the following comparison and logical operators for filtering registry items. #### Comparison operators @@ -75,14 +77,15 @@ W&B supports the following comparison and logical operators for filtering regist | Operator | Description | | ----- | ----- | | `$regex` | Regular expression pattern matching | -| `$exists` | Field exists/doesn't exist | +| `$exists` | Field exists or doesn't exist | | `$contains` | String contains value | ### Example queries -The following code examples demonstrate some common search scenarios. +The following code examples demonstrate some common search scenarios. Use them as starting points and adapt the filters to match your own registry items. + +To use the `wandb.Api().registries()` method, first import the W&B Python SDK ([`wandb`](/models/ref/python/)) library so that the API client is available in your environment: -To use the `wandb.Api().registries()` method, first import the W&B Python SDK ([`wandb`](/models/ref/python/)) library: ```python import wandb @@ -102,11 +105,11 @@ registry_filters = { registries = api.registries(filter=registry_filters) ``` -Filter all collections, independent of registry, that contains the string `yolo` in the collection name: +Filter all collections, independent of registry, that contain the string `yolo` in the collection name: ```python # Filter all collections, independent of registry, that -# contains the string `yolo` in the collection name +# contain the string `yolo` in the collection name collection_filters = { "name": {"$regex": "yolo"} } @@ -115,11 +118,11 @@ collection_filters = { collections = api.registries().collections(filter=collection_filters) ``` -Filter all collections, independent of registry, that contains the string `yolo` in the collection name and possesses `cnn` as a tag: +Filter all collections, independent of registry, that contain the string `yolo` in the collection name and have `cnn` as a tag: ```python -# Filter all collections, independent of registry, that contains the -# string `yolo` in the collection name and possesses `cnn` as a tag +# Filter all collections, independent of registry, that contain the +# string `yolo` in the collection name and have `cnn` as a tag collection_filters = { "name": {"$regex": "yolo"}, "tag": "cnn" @@ -129,11 +132,11 @@ collection_filters = { collections = api.registries().collections(filter=collection_filters) ``` -Find all artifact versions that contains the string `model` and has either the tag `image-classification` or an `latest` alias: +Find all artifact versions that contain the string `model` and have either the tag `image-classification` or the `production` alias: ```python -# Find all artifact versions that contains the string `model` and -# has either the tag `image-classification` or an `latest` alias +# Find all artifact versions that contain the string `model` and +# have either the tag `image-classification` or the `production` alias registry_filters = { "name": {"$regex": "model"} } @@ -150,26 +153,27 @@ version_filters = { artifacts = api.registries(filter=registry_filters).collections().versions(filter=version_filters) ``` -Each item in the `artifacts` iterable in the previous code snippet is an instance of the `Artifact` class. This means that you can access each artifact's attributes, such as `name`, `collection`, `aliases`, `tags`, `created_at`, and more: +Each item in the `artifacts` iterable is an instance of the `Artifact` class. This means that you can access each artifact's attributes, such as `name`, `collection`, `aliases`, `tags`, and `created_at`: ```python for art in artifacts: print(f"artifact name: {art.name}") - print(f"collection artifact belongs to: { art.collection.name}") + print(f"collection artifact belongs to: {art.collection.name}") print(f"artifact aliases: {art.aliases}") print(f"tags attached to artifact: {art.tags}") print(f"artifact created at: {art.created_at}\n") ``` -For a complete list of an artifact object's attributes, see the [Artifacts Class](/models/ref/python/experiments/artifact/) in the API Reference docs. + +For more information about an artifact object's attributes, see [Artifact](/models/ref/python/experiments/artifact/). Filter all artifact versions, independent of registry or collection, created between 2024-01-08 and 2025-03-04 at 13:10 UTC: ```python -# Find all artifact versions created between 2024-01-08 and 2025-03-04 at 13:10 UTC. +# Find all artifact versions created between 2024-01-08 and 2025-03-04 at 13:10 UTC. artifact_filters = { "alias": "latest", - "created_at" : {"$gte": "2024-01-08", "$lte": "2025-03-04 13:10:00"}, + "created_at": {"$gte": "2024-01-08", "$lte": "2025-03-04 13:10:00"}, } # Returns an iterable of all artifact versions that match the filters