model_name / version_name

MLdebugger SDKでは、model_nameとversion_nameを使用してモデルとその学習バージョンを識別します。 このページでは、これらの識別子の概念と正しい使い方を説明します。

概要

識別子	スコープ	用途
model_name	Organization内で一意	モデルアーキテクチャの識別
version_name	model_name内で一意	学習条件・データセットの識別
n_epoch	version_name内のメタデータ	エポック別のデータ区別

Organization

定義

Organizationは、MLdebuggerにおけるモデルとデータの管理単位です。 すべてのmodel_nameはOrganization内でスコープされます。

Personal Organization

現在、ユーザーが新規にOrganizationを作成する機能は提供していません。 各ユーザーにはPersonal Organizationが自動的に割り当てられ、これがデフォルトのOrganizationとして使用されます。

Organizationの管理

Personal Organizationはユーザーアカウント作成時に自動生成されます。 チーム向けのOrganization機能については、今後のアップデートで提供予定です。

model_name

定義

model_nameは、Organization内でモデルを一意に識別する文字列です。

tracer = ClassificationTracer(
    model,
    model_name="resnet18_cifar10",  # モデルの識別子
    version_name="v1",
)

特徴

Organization内で一意

• 同一Organizationで同じmodel_nameを複数のプロジェクトで使用できません
• 異なるプロジェクトには異なるmodel_nameを付与してください

Model Quotaの消費

• 新しいmodel_nameを作成するとModel Quotaを1消費します
• 契約プランによってQuotaの上限が異なります

アーキテクチャハッシュとの紐づけ

• 同一model_nameは同一モデルアーキテクチャに紐づきます
• 初回使用時にモデルのアーキテクチャハッシュが記録されます

命名の推奨事項

# 良い例
model_name = "resnet18_cifar10_classification"
model_name = "yolov8_coco_detection"
model_name = "project_a_main_model"

# 避けるべき例
model_name = "model"          # 汎用的すぎる
model_name = "test"           # 本番とテストの区別がつかない
model_name = "v1"             # version_nameと混同しやすい

アーキテクチャ変更時の注意

モデルのアーキテクチャを変更した場合は、新しいmodel_nameを使用する必要があります。

# ResNet18を使用
tracer = ClassificationTracer(model_resnet18, model_name="resnet18_project", ...)

# ResNet50に変更した場合 → 新しいmodel_nameが必要
tracer = ClassificationTracer(model_resnet50, model_name="resnet50_project", ...)

同一model_nameで異なるアーキテクチャ

同一model_nameで異なるアーキテクチャのモデルを使用すると、エラーが発生します。

version_name

定義

version_nameは、model_name内で学習バージョンを一意に識別する文字列です。

tracer = ClassificationTracer(
    model,
    model_name="resnet18_cifar10",
    version_name="v1_lr0001",  # 学習バージョンの識別子
)

特徴

model_name内で一意

• 同一model_name内で同じversion_nameは一つだけ存在できます
• 異なるmodel_nameでは同じversion_nameを使用できます

データセット・ハイパーパラメータの区別

• データセットを変更した場合は新しいversion_nameを使用
• ハイパーパラメータを変更した場合も新しいversion_nameを使用

学習再開時の同一version_name使用

• 学習を中断→再開する場合は同一version_nameを再利用可能
• データが追加的に記録されます

命名の推奨事項

# 良い例: 条件が分かる名前
version_name = "v1_lr0001_batch32"
version_name = "20251219_experiment_a"
version_name = "baseline"

# 用途別の例
version_name = "train_augmented"     # データ拡張あり
version_name = "train_no_augment"    # データ拡張なし
version_name = "finetune_v1"         # ファインチューニング

同一version_nameでの条件コンフリクト

同一version_nameで異なる学習条件のデータを収集すると、データがコンフリクトする可能性があります。

# 危険: 同じversion_nameで異なる条件のデータを収集
tracer = ClassificationTracer(model, "model_a", "v1")
# ... lr=0.001で学習したデータを収集 ...

# 後日、同じversion_nameでlr=0.01のデータを収集 → コンフリクト！
tracer = ClassificationTracer(model, "model_a", "v1")
# ... lr=0.01で学習したデータを収集 ...

条件変更時は新しいversion_nameを

学習条件を変更した場合は、必ず新しいversion_nameを使用してください。

n_epoch

定義

n_epochは、エポック別のデータを区別するためのオプションパラメータです。

tracer(
    image,
    label,
    input_ids=indices,
    dataset_type="train",
    n_epoch=5,  # エポック番号
)

特徴

オプションのメタデータ

• n_epochは必須ではありません
• 指定しない場合、全データが同一エポックとして扱われます

無指定時の内部値

n_epochを指定しない場合、内部的にはn_epoch=Noneとして管理されます。

後からn_epochを指定してデータを収集することも可能です。その場合、過去に無指定で収集したデータはn_epoch=Noneを明示的に指定することで参照できます。

# 最初は n_epoch を指定せずにデータ収集
tracer(image, label, input_ids=indices, dataset_type="train")
# → 内部的には n_epoch=None として保存

# 後から n_epoch を指定してデータ収集
tracer(image, label, input_ids=indices, dataset_type="train", n_epoch=1)

# 評価時に無指定時のデータを対象にする場合
result = evaluator.request_evaluation(n_epoch=None)

"latest"エイリアス

評価時にn_epoch="latest"を指定すると、最新エポックのデータのみを評価対象にできます。

result = evaluator.request_evaluation(n_epoch="latest")

version_name再利用時の活用

同一version_nameで学習を継続する場合、n_epochで区別できます。

# 初回学習: epoch 0-4
for epoch in range(5):
    for batch in dataloader:
        tracer(..., n_epoch=epoch)

# 継続学習: epoch 5-9
for epoch in range(5, 10):
    for batch in dataloader:
        tracer(..., n_epoch=epoch)

# 最新エポック(9)のみ評価
result = evaluator.request_evaluation(n_epoch="latest")

"latest"の注意点

latestの定義はtimestampに基づく

n_epoch="latest"は、収集した推論データのtimestampに基づいて最新エポックを判定します。 n_epochの数値の大小ではありません。

問題が発生するケース:

同じversion_nameでエポックを1からやり直した場合、過去に記録したn_epochの最大値（例: 9）はlatestとして扱われなくなります。 新しく記録したn_epoch=1のデータが最新のtimestampを持つため、latestはそのデータを指します。

# 初回学習: epoch 0-9 を記録（2025年1月）
for epoch in range(10):
    tracer(..., n_epoch=epoch)

# 数ヶ月後、同じversion_nameでepoch 0から再開（2025年3月）
for epoch in range(5):
    tracer(..., n_epoch=epoch)

# latest は epoch=4 を指す（timestamp が最新のため）
# epoch=9 のデータは latest として扱われない
result = evaluator.request_evaluation(n_epoch="latest")

これにより、意図しないデータが評価対象になったり、データのコンフリクトが発生する可能性があります。

対処法:

• 学習を新しくやり直す場合は、新しいversion_nameを使用する
• 評価時にn_epochを明示的に指定する
• DataFilter/Logger起動時にresult_nameとn_epochを指定する

詳細はDataFilteringを参照してください。

使い分けのまとめ

シナリオ	model_name	version_name	n_epoch
新しいモデルアーキテクチャ	新規	任意	-
新しいデータセットで学習	既存	新規	-
ハイパーパラメータ変更	既存	新規	-
学習の中断→再開	既存	既存	指定推奨
エポック別の評価	既存	既存	指定

次のステップ

• Getting Started - 基本的な使い方
• Evaluation と Result - 評価の詳細設定