hankcs/HanLP · error · TypeError

alpha must be float, list of float, or torch.FloatTensor, {}

Error message

alpha must be float, list of float, or torch.FloatTensor, {} provided.

What it means

In udify's focal-loss code path, `alpha` balances class weights and must be a float, a list of floats, or a torch.FloatTensor. When alpha is another type (e.g. an int, numpy scalar, string, or None handled elsewhere), the branch resolution fails and a TypeError is raised showing the offending type.

Source

Thrown at hanlp/components/parsers/ud/udify_util.py:226

        if isinstance(alpha, (float, int)):

            # shape : (2,)
            alpha_factor = torch.tensor(
                [1.0 - float(alpha), float(alpha)], dtype=weights.dtype, device=weights.device
            )

        elif isinstance(alpha, (list, numpy.ndarray, torch.Tensor)):

            # shape : (c,)
            alpha_factor = torch.tensor(alpha, dtype=weights.dtype, device=weights.device)

            if not alpha_factor.size():
                # shape : (1,)
                alpha_factor = alpha_factor.view(1)
                # shape : (2,)
                alpha_factor = torch.cat([1 - alpha_factor, alpha_factor])
        else:
            raise TypeError(
                ("alpha must be float, list of float, or torch.FloatTensor, {} provided.").format(
                    type(alpha)
                )
            )
        # shape : (batch, max_len)
        alpha_factor = torch.gather(alpha_factor, dim=0, index=targets_flat.view(-1)).view(
            *targets.size()
        )
        weights = weights * alpha_factor

    if label_smoothing is not None and label_smoothing > 0.0:
        num_classes = logits.size(-1)
        smoothing_value = label_smoothing / num_classes
        # Fill all the correct indices with 1 - smoothing value.
        one_hot_targets = torch.zeros_like(log_probs_flat).scatter_(
            -1, targets_flat, 1.0 - label_smoothing
        )
        smoothed_targets = one_hot_targets + smoothing_value

View on GitHub (pinned to ddb1299bdd)

Solutions

Pass a Python float (alpha=0.25), a list of floats, or a torch.FloatTensor
Convert numpy scalars: alpha=float(alpha)
If you want plain cross entropy, set gamma=0 and alpha=None instead of a non-float alpha placeholder

Example fix

# before
loss = sequence_cross_entropy_with_logits(logits, targets, weights, gamma=2.0, alpha=1)
# after
loss = sequence_cross_entropy_with_logits(logits, targets, weights, gamma=2.0, alpha=1.0)

Defensive patterns

Strategy: type-guard

Validate before calling

assert alpha is None or isinstance(alpha, (float, int)) and not isinstance(alpha, bool) or isinstance(alpha, (list, torch.FloatTensor)), f'bad alpha type {type(alpha)}'
if isinstance(alpha, int) and not isinstance(alpha, bool):
    alpha = float(alpha)

Type guard

def is_valid_alpha(a) -> bool:
    return a is None or isinstance(a, float) or (
        isinstance(a, list) and all(isinstance(x, float) for x in a)
    ) or isinstance(a, torch.FloatTensor)

Try / catch

try:
    loss = sequence_cross_entropy_with_logits(..., alpha=alpha)
except TypeError as e:
    if 'alpha must be float' in str(e):
        alpha = float(alpha)  # retry with normalized type
        loss = sequence_cross_entropy_with_logits(..., alpha=alpha)
    else:
        raise

Prevention

Normalize numeric hyperparameters to float at config-load time
Never pass ints/numpy scalars straight into typed loss APIs

When it happens

Trigger: Calling sequence_cross_entropy_with_logits with alpha=1 (int), alpha=np.float32(0.25), or alpha="0.25"; alpha=None with gamma set goes down a different path, but any non-float/list/tensor type lands here.

Common situations: Passing integer alpha (like alpha=1) instead of 1.0; passing numpy types from a data pipeline; copying focal-loss hyperparameters from papers that use strings.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

AI-assisted analysis of hankcs/HanLP@ddb1299bdd (2026-08-27). Data as JSON: /api/errors/a42352141fa7b24e. Report an issue: GitHub.