何十万曲もの音楽に自動的にタグを付けることは、単純な文字列の書き込みを実行しているように見えるかもしれませんが、究極のデータの一貫性と多言語サポートを追求する場合、私たちはしばしば非常に苦痛なリファクタリングに直面します。AI Music Organizer の第3世代タグアーキテクチャ (V3) が誕生したのは、初期のアーキテクチャにおける責任の混乱によって引き起こされたジレンマに終止符を打つためでした。
I. なぜ従来のタグアーキテクチャは問題を起こすのか？
過去の実装パイプラインでは、完全に異なるいくつかの責任を混同していました。
- 分類器によって出力される生の value（例：モデルが吐き出す “Rock”）
- システム内部で比較を行うための Key
- 最終的にファイル (ID3/FLAC) に書き戻される文字列
- フロントエンド UI に表示される現地のテキスト
これは、極めて深刻なビジネス上のペインポイントを引き起こしました。
- 不安定な Key:
/、,、&などの特殊文字は、サニタイズ（無害化）プロセス中に繰り返し書き換えられ、同じタグが異なるパイプラインで異なる文字列になってしまいます。 - 誤判定による冗長な書き戻し: 基礎となるオーディオファイルのタグが実際にすでに “摇滚”（中国語で Rock）であり、分析エンジンが “Rock” を生成した場合、単純な文字列比較では冗長なパッチ（“摇滚” を “Rock” に変更するよう要求）が生成されてしまいます。
- ユーザーによるカスタマイズが困難: 「サニタイズされた文字列がキーである」ため、ユーザーが英語のオリジナルタグを母国語にハードマッピングしたいと考えた場合、ロジックは非常に脆弱なものになっていました。
II. V3 アーキテクチャの核心: セマンティックキー
V3 アーキテクチャでは、セマンティックキー (Semantic Key) の概念を導入し、上記の4つの責任を明確に分離しました。
1. セマンティックキーが唯一の真実の基準になる
システム内部は、もはや “摇滚” という文字列自体には関心がありません。すべての比較とフローは、分類器によって提供される安定したベースライン（つまり raw classifier value）に完全に基づいています。強力なカスケード関係を持つデータ（例：Funk / Soul---Contemporary R&B）については、グローバルなサニタイズを放棄し、それらを独立した Genre と Style のセマンティックキーに分割するだけに留めました。
2. ロケールマッピングによる2層ストレージの導入
データベースを tag_value_catalog（主要セマンティックテーブル）と tag_value_locale（多言語マッピングテーブル）で構成しました。
- Catalog は、「このタグの概念は誰か？」ということだけに関心を置きます（例：
id: 12, semantic_key: 'Rock'）。 - Locale は、このセマンティック概念を、中国語、英語、日本語などのさまざまなロケールでどのようにレンダリングするかに焦点を当てます（例：
display_value: 'ロック', write_value: 'ロック'）。
[!IMPORTANT]
- セマンティックキーは表示の責任を負いません。
- ロケールマッピングはアイデンティティ（一意の識別）の責任を負いません。
III. 比較の芸術: いつ書き戻すべきか
V3 アーキテクチャにおいて、「今回は本当にファイルのメタデータを変更する必要があるか」を判断するプロセスは、2つのコアフェーズに分割されています。
フェーズ A: セマンティックのアライメント (Merge)
現在分析されている raw classifier value がいくつであっても、システムはまず対応する semantic key を抽出して重複を排除し、未書き込みのドラフト (Draft) とマージします。
フェーズ B: 書き戻しの判断 (Diff)
これが最も重要なステップです！ファイル変更パッチを生成するかどうかは、もはや semantic key には依存しません。代わりに、desired write value（現在のユーザー設定の下で書き込まれることが期待される文字列）を抽出し、file current value（現在ファイルから読み取られている実際の文字列）と直接比較します。
実際のシナリオの例:
- シナリオ 1: ファイルには元々英語の
Rockが保存されており、現在は日本語のインターフェースと日本語のタグを使用するように設定されています。- セマンティックキー:
Rock - ファイルの現在値:
Rock - 書き込み希望値:
ロック - 結論: パッチを生成します！ システムは元のファイルを完璧に書き換えます。
- セマンティックキー:
- シナリオ 2: ファイルはすでに
ロックに書き換えられており、システムは再びRockのセマンティックキーをスキャンします。- セマンティックキー:
Rock - ファイルの現在値:
ロック - 書き込み希望値:
ロック - 結論: パッチは生成しません！ これによりディスク I/O が大幅に節約され、履歴ログの純度が保証されます。
- セマンティックキー:
おわりに
セマンティックキー (Semantic Key) の分離に基づくタグシステムは、非常に伝統的なものに聞こえるかもしれませんが、これはその後の「ユーザー定義マッピングルール」と「複雑な LLM ベクトルの統合」をサポートする基盤となります。ソフトウェアエンジニアリングは往々にしてこのようなものです。結合された責任をクリーンアップすれば、ビジネスロジックは再び爽快なほどに明確になるのです。