# Kayıt Defteri

**registry**, en iyi artefakt sürümlerinizin paylaşılan kataloğudur. Bir proje, deneylerinizin ürettiği artefaktları listeler; bir registry ise **çeşitli** projelerden seçilen artefaktları listeler.

Bir kayıt defteri **koleksiyonlar** içerir. Her koleksiyon bir varlığı temsil eder — zaman içinde yeniden eğittiğiniz bir model, altın bir değerlendirme seti — ve yayınlamayı seçtiğiniz sürümlerini barındırır. Bir artefakt sürümünü bir koleksiyona *bağlarsınız*. Bağlantı, kaynak sürüme işaret eden bir imleçtir: hiçbir şey kopyalanmaz. Ardından, `staging` ve `production` gibi takma adları taşıyarak bağlantılı bir sürümü yaşam döngüsü aşamaları boyunca ilerletirsiniz.

Örneğin, `models` adlı bir kayıt defteri, dağıtılabilir her model için bir koleksiyon; `datasets` adlı bir kayıt defteri ise her benchmark için bir koleksiyon içerebilir. Varlıkların kayıt defterleri ve koleksiyonlar arasında nasıl bölündüğü size kalmıştır.

![How projects, artifact versions, collections, links, and aliases relate](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/trackio/registry-overview.png)

Bir koleksiyonun, kaynak artefaktların sürüm numaralarından bağımsız olan kendi sürüm hattı (`v0`, `v1`, …) vardır ve sürümleri, farklı projelerdeki farklı kaynak artefaktlara işaret edebilir. Takma adlar, koleksiyon başına tam olarak bir sürüm adlandırır.

Bir kayıt defteri ya da **yereldir** — diğer Trackio verilerinizin yanında `registry-models` adlı bir proje olarak saklanır (`registry-` öneki ayrılmıştır) — ya da bir **Hugging Face kovasına** dayanır; bu da onu diğer makinelerden ve bir Space'e kayıt yapan çalışmalardan erişilebilir kılar. [Uzak kayıt defterleri](#remote-registries) bölümüne bakın.

## Bir kayıt defteri oluşturun

`Api.create_registry()` ile bir kayıt defteri oluşturun:

```python
import trackio

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

İsteğe bağlı `description`, kayıt defterinde saklanır ve `registry.description` olarak okunabilir.

Kayıt defterleri asla örtük olarak oluşturulmaz. Var olmayan bir kayıt defterine bağlanmaya çalışmak bir hata oluşturur.

Mevcut bir kayıt defterini almak için `Api.registry()` kullanın. Kayıt defteri mevcut değilse bu yöntem bir hata fırlatır.

## Bir koleksiyon oluşturun

*Koleksiyon*, bir kayıt defteri içinde tek bir sürüm geçmişine sahip bağlantılı artefakt sürümlerinin bir kümesidir. Sürümler farklı kaynak artefaktlardan gelebilir: resnet tabanlı ve unet tabanlı modeller aynı dağıtılabilir ürün için adaysa, bunları tek bir koleksiyona bağlayın ve bu koleksiyonun ardışık sürümleri haline gelsinler. Ayrı ürünlerse, her birine kendi koleksiyonunu verin.

Genellikle koleksiyonları manuel olarak oluşturmazsınız: var olmayan bir koleksiyona bağlantı oluşturulduğunda koleksiyon otomatik olarak oluşturulur. Bir açıklama baştan ayarlamak istediğinizde koleksiyonu açıkça oluşturun:

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

### Koleksiyon türleri

Her koleksiyon, koleksiyon oluşturulurken belirlenen tek bir *type* türünde artefaktı kabul eder. Tür, artefaktın kendisinden gelir — `trackio.Artifact` veya `trackio.log_artifact` fonksiyonlarına ilettiğiniz `type` alanı — bu nedenle ilk bağlantıyla oluşturulan bir koleksiyon, o artefaktın türünü benimser.

Örneğin, `"model"` artefaktlarını kabul eden bir koleksiyona `"dataset"` artefaktı bağlarsanız, Trackio bir hata oluşturur.

Kayıt defteri (registry) her türü kabul eder: bir model koleksiyonu ve bir veri seti koleksiyonu aynı kayıt defterinde yan yana bulunabilir.

## Bir artefakt sürümünü bir koleksiyona bağlayın

Bir artefakt sürümünü [Run.link_artifact()](/docs/trackio/v0.45.0/tr/api#trackio.Run.link_artifact) ile yayınlayın:

```python
import trackio

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

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

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

Hedef yol `"registry-<registry>/<collection>"`'dir. İlk segment, öneki dahil olmak üzere kayıt defterinin tam adıdır.

`link_artifact`, yayınlanan sürümün elinizdeki sürümle birebir aynı olmasını sağlamak için artifact nesnesinin kendisini alır:

| Kullanım senaryosu | Nasıl | Kaydedilen içerik |
| --- | --- | --- |
| Az önce kaydettiğiniz artefaktı bağlayın | `run.link_artifact(artifact, ...)` | Çalışma tarafından yayınlanan bağlantı |
| Belirli bir mevcut sürümü bağla | `run.link_artifact(run.use_artifact("resnet:v3"), ...)` | Çalışma `resnet:v3`'ü tüketir, ardından çalışmanın yayınladığı bir bağlantı |
| Kaydedilmemiş bir artefaktı bağlayın | `run.link_artifact(draft_artifact, ...)` | Artefakt, önce çalışmanın projesine kaydedilir, ardından bağlantı kurulur |

Ayrıca, çalıştırma kapsamda değilse kullanışlı olan [Artifact.link()](/docs/trackio/v0.45.0/tr/api#trackio.Artifact.link) ile artefaktın kendisinden de bağlantı verebilirsiniz:

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

`Artifact.link`, artefactin zaten kaydedilmiş ya da alınmış olmasını gerektirir — taslak sizin için kaydetmez — ve bağlantı bir yayınlama çalışması kaydetmez.

### Bağlantılı artefakt

`link_artifact`, artefakti kayıt defteri konumunda döndürür. `name` alanı koleksiyonu, `project` alanı kayıt defterini belirtirken `version` ve `aliases` alanları koleksiyonunkilerdir. İçeriği — `manifest`, `manifest_digest`, `size`, `metadata` — kaynak sürümünkidir ve `source_project`, `source_name`, `source_version` ile `source_qualified_name` özellikleri bu kaynağa geri işaret eder:

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

Bağlı bir artefaktın bağlantısı, kaynak sürümünü doğrudan bağlar (bir uyarıyla birlikte), bu nedenle bağlantılar asla zincirleme olmaz.

Tüketiciler, hangi proje veya artefaktın ürettiğini bilmeden, bir kayıt defteri konumunu doğrudan `use_artifact` ile çözer:

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

Koleksiyondan sonraki spec, bir koleksiyon sürümünü (`"v1"`), bir takma adını (`"production"`) veya en yeni bağlantılı sürüm için hiçbir şeyi kabul eder. Bağlı bir artefaktın indirilmesi, işaret ettiği kaynak sürümün baytlarını alır.

Kayıt yeri konumları şu anda yalnızca yerel çalıştırmalar tarafından çözümlenebilir ve yalnızca kaynak artefakt yerel olarak mevcut olduğunda. Bir Space'te, bir kovada veya kendi kendine barındırılan bir sunucuda saklanan kaynaklar, kova destekli bir kayda yayımlanabilir, ancak bu bağlantıların sonraki bir işlemde çözümlenmesi henüz desteklenmemektedir. `link_artifact` tarafından doğrudan döndürülen bağlantılı artefakt, Space veya kendi kendine barındırılan kaynağını korur ve ondan indirme yapabilir.

### Koleksiyon sürümleri

Her yeni bağlantı, koleksiyondaki sıradaki sürüm numarasını alır ve `v0` ile başlar. Koleksiyon sürümleri, kaynak artefaktların kendi sürüm numaralarından bağımsızdır çünkü bağlantılı sürümler genellikle farklı artefaktlardan ve projelerden gelir.

Koleksiyonda zaten bulunan bir kaynak sürümünü bağlamak yeni bir sürüm oluşturmaz. Mevcut sürümü geri alırsınız ve geçirdiğiniz `aliases` yine taşınır. Sürüm numaraları asla yeniden kullanılmaz, bu nedenle yayınlanmış bir `my-model:v3` asla sessizce anlam değiştiremez.

## Alias'lerle bir sürümü yükselt

Bir takma ad, her koleksiyon için bir sürüme işaret eder. Başka bir sürümün zaten sahip olduğu bir takma adı atamak, takma adı oradan taşır — bu taşıma *terfi* işlemidir. `my-model:production` çözümleyen tüketiciler takma adı takip eder, bu nedenle takma ad taşındığında aşağı akışta hiçbir şey değişmez.

Çoğu terfi yayınlama sırasında gerçekleşir: yeni bir sürüm bağlarsınız ve takma adı aynı çağrıda yerleştirirsiniz.

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

Koleksiyonda *zaten* bulunan bir sürümü ilerletmek için, onu takma adla yeniden bağlayın. Yeniden bağlama işlemi yeni bir şey oluşturmaz; mevcut koleksiyon sürümünü geri alırsınız ve ilettiğiniz takma adlar ona taşınır. Sürümün kaynağını koleksiyonun bağlantılarında bulun, onu getirin ve yeniden bağlayın:

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

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

Bunu doğrudan kayıt defterinden de alabilirsiniz:

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

Bir takma adın (alias) eski bir sürüme geri alınması aynı şekilde çalışır.

Trackio, `latest` takma adını sizin için yönetir: her zaman en yeni bağlantılı sürüme işaret eder.

## Bir sürümü bağlantısını kaldır

Bağlı artefakt üzerinde çağrılan [Artifact.unlink()](/docs/trackio/v0.45.0/tr/api#trackio.Artifact.unlink) ile bir bağlantı kaldırın:

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

Kaynak artefakt ve dosyaları dokunulmaz kalır — yalnızca koleksiyon üyeliği kaldırılır. Bağlantıdaki tüm takma adlar da onunla birlikte gider ve koleksiyon sürüm numarası asla yeniden kullanılmaz, bu nedenle `my-model:v0` daha sonra başka bir şeyi ifade edemez. Kaldırdığınız sürüm `latest` takma adını içeriyorsa, bu takma ad en yüksek kalan sürüme taşınır, böylece `latest` koleksiyondaki en yeni sürüme işaret etmeye devam eder.

## Uzak kayıt defterleri

Yerel bir kayıt defteri yalnızca onu yazan makinede bulunur. Bir kataloğu makineler arasında paylaşmak — veya bir Space'e veya kendi barındırdığınız bir sunucuya kayıt tutan bir çalışmadan yayınlamak — için kayıt defterini `bucket_id` parametresini geçirerek **Hugging Face bucket** ile destekleyin:

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

Var olmayan bir varlık kovası oluşturulur (özel). Bir işlemdeki tüm kayıt defteri çağrılarının varsayılanı olarak ayarlamak için `TRACKIO_REGISTRY_BUCKET_ID` değerini belirleyin; böylece betiklerin bunu ayrıca iletmesine gerek kalmaz.

Alma, inceleme ve yayınlama işlemlerinin tümü aynı argümanı alır:

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

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

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

Buckete erişimi olan herkes, kendi Hugging Face kimlik bilgileriyle doğrudan ona yazar — yolda bir sunucu olmadığından, bir kayıt defteri herhangi bir Space'e bağlı değildir ve hepsinden uzun ömürlüdür. `Artifact.link` ve `Artifact.unlink`, `bucket_id` parametresini aynı şekilde kabul eder ve bağlantılı bir artefakt, geldiği bucketı hatırlar; bu nedenle `linked.unlink()` doğru kayıt defterine geri döner.

Kayıt defterinin kendi kovası, çalıştırmanın kovasıyla *aynı* değildir: bir kayıt defteri proje arası bir kataloğudur, bu nedenle metriklerin nereye gittiğini devralmak yerine adını açıkça belirtirsiniz.

### Kova içinde neler var

Her mutasyon, tek bir değiştirilemez nesne olarak saklanır ve durum, bu günlüğün katlanmasıdır:

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

Uzak bir kayıt defterini okumak, bu olayları `registry-cache/` altındaki yerel bir projeksiyon veritabanına katlar; bu bir önbellektir: silerseniz, sonraki okuma onu bucket'tan yeniden oluşturur.

### Eşzamanlılık

Nesne depolamasında karşılaştırma ve değiştirme (compare-and-swap) yoktur, bu nedenle yazarlar kilit alamaz — yalnızca başka birinin yazmadığı nesneleri ekleyebilirler. İki sonuç, ikisi de tasarım gereği:

- **Sürüm numaraları, yazar tarafından değil, katlama işlemi tarafından atanır.** Eşzamanlı bağlantılar, olay kimliklerine göre sıralanır (zaman damgası, ardından yazar, ardından sıra numarası), bu nedenle her birine benzersiz ve asla yeniden kullanılmayan bir numara verilir. Bir yazarın bildirdiği bir sürüm, eşzamanlı bir yazarın olayları katlandığında değişebilir.
- **Alias taşımaları son yazar kazanır** kuralı, aynı sıralamaya göre, `latest` dahil olmak üzere uygulanır. İki kişinin aynı anda `production` ortamına yükseltme yapması, olay sırasına göre çözümlenir.

Bağlantılar saf işaretçiler olarak kalır: kayıt defteri kovasına hiçbir şey kopyalanmaz, bu nedenle kaynak projenin depolaması erişilebilir kalmalıdır. Kaynağı uzak olan bağlantıların çözümlenmesi henüz desteklenmemektedir. Bir sürümün baytlarını kayıt defterine kopyalama (sabitleme) işlemi planlanan bir sonraki adım olarak ele alınacaktır.

## Bir kayıt defterini denetleyin

[Registry](/docs/trackio/v0.45.0/tr/api#trackio.Registry) handle, koleksiyonları ve bunlara bağlı sürümleri listeler. Okumalar [Collection](/docs/trackio/v0.45.0/tr/api#trackio.Collection) anlık görüntülerini döndürür:

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

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

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

Her bağlantı, sürümün nereden geldiğini (`source_project`, `source_artifact`, `source_version`), yerel değilse kaynağın depolama koordinatlarını (`source_space_id`, `source_bucket_id` veya `source_server_base_url`) ve üzerinde bulunan geçerli takma adları kaydeder. Bir bağlantı, o kaynak sürümüne giden saf bir işaretçidir.

## Komut satırı arayüzü

`trackio registry` komutları, bir Python betiği gerektirmeden aynı yayınlama ve inceleme iş akışını kapsar:

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

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

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

trackio registry unlink models/churn-model v0
```

`link`, kaynağını yerel Trackio verisinden çözer. Açık bir sürüm veya takma ad kabul eder ve sonek atlandığında varsayılan olarak `latest` kullanılır. Kayıt defteri yine de bucket destekli olabilir; herhangi bir komuta `--bucket-id my-org/models-registry` parametresini iletin. Betikler için uygun yapılandırılmış çıktı almak için `--json` kullanın.

CLI hem `models/churn-model` hem de Python API'sinin tam `registry-models/churn-model` hedef sözdizimini kabul eder. Tam komut referansı için [CLI Komutları](cli_commands#registry-commands) bölümüne bakın.

## Panelde kayıt defterlerini görüntüle

Kayıt açıklamalarını, koleksiyonları, bağlantılı sürümleri, takma adları, kaynak konumlarını ve denetim olaylarını görüntülemek için bağımsız, salt okunur kayıt panosunu başlatın:

```bash
trackio show registry
```

Veya Python'dan `trackio.show(dashboard="registry")` ile başlatın. Kayıt defteri panosu, kayıt defterlerinin projeler arası artefaktları kataloglaması nedeniyle proje panosundan ayrıdır.

**Local** kaynağı, gösterge paneli makinesinde saklanan kayıt defterlerini gösterir. Erişilebilir bir Hugging Face kovasını seçmek için **HF Bucket** seçeneğini işaretleyin veya `my-org/models-registry` gibi bir kova kimliği girin. Bir Space'te özel kova erişimi, oturum açan izleyicinin Hugging Face kimlik bilgilerini kullanır. Kendi kendine barındırılan bir gösterge paneli, yalnızca yazma erişim URL'sini açan izleyiciler için kayıtlı Hugging Face jetonunu kullanır. Halka açık salt okunur gösterge panelleri, kovaları sunucu tarafından sahip olunan bir jeton aracılığıyla asla ifşa etmez. Kayıt defteri gezintisi, statik gösterge paneli anlık görüntülerine dahil değildir.

## Denetim geçmişi

Her mutasyon, kayıt defterinin denetim günlüğüne bir olay ekler: kayıt defteri ve koleksiyon oluşturma (`create`), `link`, `promote`, açıklama değişiklikleri (`update`) ve `unlink`. Günlük, "geçen ay üretimde hangi sürüm vardı ve bu sürümü hangi çalışma yayınladı?" gibi soruları yanıtlar:

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

Link ve promote olayları, yayınlama çalışmasını kaydeder. Promote olayları ayrıca, takma adın hangi sürümden taşındığını da kaydeder.