{"record":{"id":"16bf8d892047a637","repo":"hankcs/HanLP","slug":"unsupported-normalization-method-normalize","errorCode":null,"errorMessage":"Unsupported normalization method {normalize}","messagePattern":"Unsupported normalization method (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"hanlp/layers/embeddings/util.py","lineNumber":74,"sourceCode":"    if unk_id_offset:\n        unk_embeds = torch.zeros(unk_id_offset, pret_matrix.size(1))\n        if init and init != 'zeros':\n            if init == 'uniform':\n                init = embedding_uniform\n            else:\n                raise ValueError(f'Unsupported init {init}')\n            unk_embeds = init(unk_embeds)\n        pret_matrix = torch.cat([pret_matrix, unk_embeds])\n    ids = torch.LongTensor(ids)\n    embedding = pret_matrix.index_select(0, ids)\n    if normalize == 'norm':\n        embedding /= (torch.norm(embedding, dim=1, keepdim=True) + 1e-12)\n    elif normalize == 'l2':\n        embedding = torch.nn.functional.normalize(embedding, p=2, dim=1)\n    elif normalize == 'std':\n        embedding /= torch.std(embedding)\n    else:\n        raise ValueError(f'Unsupported normalization method {normalize}')\n    return embedding\n\n\ndef build_word2vec_with_vocab(embed: Union[str, int],\n                              vocab: Vocab,\n                              extend_vocab=True,\n                              unk=None,\n                              lowercase=False,\n                              trainable=False,\n                              init='zeros',\n                              normalize=None) -> nn.Embedding:\n    \"\"\"Build word2vec embedding and a vocab.\n\n    Args:\n        embed:\n        vocab: The vocabulary from training set.\n        extend_vocab: Unlock vocabulary of training set to add those tokens in pretrained embedding file.\n        unk: UNK token.","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/hankcs/HanLP/blob/ddb1299bddff079e447af52ec12549c50636bfa8/hanlp/layers/embeddings/util.py#L56-L92","documentation":"After selecting pretrained vectors, index_word2vec_with_vocab can normalize them; supported schemes are 'norm' (divide by row L2 norm), 'l2' (F.normalize p=2), and 'std' (divide by global std). Any other normalize string raises, so typos or unsupported schemes fail fast rather than silently skipping normalization.","triggerScenarios":"Passing normalize='none', normalize=None is fine but 'max', 'minmax', 'unit' etc. raise the error.","commonSituations":"Assuming other normalization names from sklearn/gensim apply; typo in config keys.","solutions":["Use one of 'norm', 'l2', 'std'","Pass normalize=None (or omit) to skip normalization"],"exampleFix":"# before\nemb = build_word2vec_with_vocab(p, vocab, normalize='minmax')  # error\n# after\nemb = build_word2vec_with_vocab(p, vocab, normalize='l2')","handlingStrategy":"validation","validationCode":"assert normalize in (None, 'norm', 'l2', 'std'), f'bad normalize: {normalize}'","typeGuard":"def valid_normalize(norm) -> bool:\n    return norm in (None, 'norm', 'l2', 'std')","tryCatchPattern":null,"preventionTips":["Check supported enum values in the function docstring","Use None to disable normalization"],"tags":["hanlp","word2vec","normalization","config-validation"],"backgroundTag":"invalid-config-value","analyzedSha":"ddb1299bddff079e447af52ec12549c50636bfa8","analyzedAt":"2026-08-27T03:36:54.287Z","schemaVersion":2},"datasetVersion":"2026-08-27T08:17:20.692Z"}