Shape suffixy: Malá konvence, která změní váš ML kód k nepoznání

Přiznejme si to — ladění neuronových sítí je dostatečně náročné i bez toho, abychom se prali s nečitelnými názvy proměnných. Určitě jste tam byli: koukáte na outputs a snažíte se vzpomenout, jestli je batch-first nebo batch-last, jestli tam je ta dimension pro sekvenci, nebo jestli ji někdo někde reshapeoval.

Existuje lepší cesta. A je absurdně jednoduchá.

Co jsou shape suffixy?

Shape suffixy jsou malá písmena připojená k názvům tensor proměnných, která popisují jejich dimenze. Místo outputs píšete outputs_bc. Místo activations píšete activations_bcn.

Na první pohled to vypadá jako zbytečná práce. Věřte mi — je to přesně naopak. Je to jedna z nejvlivnějších konvencí, kterou můžete ve svých ML projektech adoptovat.

Abeceda dimenzí

Tady je standardní slovník pro dimension kódy:

• b — batch dimension
• p — pozice neboli index v sekvenci
• n — neuron dimension (typicky výsledek násobení váhovou maticí)
• c — channel dimension
• h — výška (pro obrázkové tensory)
• w — šířka (pro obrázkové tensory)
• d — hloubka (pro 3D data)
• k — kernel dimension

Takže logits_bc vám prozradí, že jde o batch logitů s channel dimenzemi — ideální pro klasifikační úlohy. positional_embeddings_bpn znamená, že máte batch, pozici a neuron dimenze v tomto pořadí.

Proč se tahle konvence vyplatí

Okamžitý kontext. Když vidíte probs_bc, hned víte, že se koukáte na pravděpodobnosti organizované podle batche a třídy. Žádné hádání, žádné hledání dokumentace.

Vestavěná detekce chyb. Tady to začíná být opravdu zajímavé. Když napíšete outputs_bc = torch.matmul(activations_bcn, weights_bcn), nesoulad vyskočí okamžitě. Vaše váhová matice by měla být weights_nc, aby správně násobila s activations_bcn. Názvy samy o sobě fungují jako statický type checker pro tvary tensorů.

Dokumentace, která se sama aktualizuje. Komentáře zastarávají. Nikdo je neaktualizuje při refactoringu. Ale embeddings_bpn zůstává přesný, dokud dodržujete konvenci — protože název proměnné JE ta dokumentace.

Plynulejší code reviews. Recenzenti ve pull requetech vidí dimension mismatche bez nutnosti spouštět kód nebo trasovat funkce. Šetří to čas všem a chytá to bugy dřív.

Praktické patterny k adoptování

Pro concatenace a stacky: Když kombinujete tensory, aktualizujte suffix tak, aby odrážel novou strukturu. Stackujete dva features_bc tensory podle nové dimenze? Teď máte features_bck nebo features_bkc — podle toho, který axis jste zvolili.

Pro redukce: Sečtete position dimension a inputs_bp se stane inputs_b. Uděláte argmax přes channely a logits_bc se stane logits_b. Suffix se zmenší, aby odpovídal realitě.

Pro komplexní tensory: Můžete kombinovat víc dimension kódů: attention_bpp pro attention skóre přes páry pozic, nebo gradients_bpn pro gradienty organizované podle batche, pozice a neuronů.

Jak na to

Tady je ten klíč: konzistence. Zvolte si konvenci, používejte ji všude — inputs, outputs, každý mezitensor. Ano, včetně té jednořádkové proměnné, co jste si vytvořili jen na debugging.

Vaše budoucí já vám poděkuje. A vaši kolegové taky.

Pokud stavíte ML aplikace a chcete čistý, udržovatelný kód, který škáluje s vaším týmem, tyhle malé konvence se kumulují v obrovské produktivní zisky. Je to stejný princip jako dobré pojmenovávání kdekoli v softwarovém vývoji — nechte kód, aby mluvil jako dokumentace.

Dejte tomu týden v vašem dalším projektu. Myslím, že pak budete přemýšlet, jak jste kdy kódovali bez toho.