> This page is for version 0.5.0 · 26.06.
> For other versions, use one of these documentation indexes:
> - Nightly (default): https://docs.nvidia.com/nemo/automodel/nightly/llms.txt
> - Latest: https://docs.nvidia.com/nemo/automodel/latest/llms.txt
> - 0.5.0 · 26.06: https://docs.nvidia.com/nemo/automodel/v0.5/llms.txt
> - 0.4.0 · 26.04: https://docs.nvidia.com/nemo/automodel/v0.4/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/automodel/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/automodel/_mcp/server.

# nemo_automodel.components.loss.listmle

ListMLE ranking loss over a teacher's top-k tokens.

Distillation objectives such as `masked_soft_cross_entropy` match the teacher's probability *mass*. A drafter in
speculative decoding is instead accepted or rejected on whether its ranking of
the next few candidates agrees with the target's, so ViSpec (arXiv:2509.15235)
adds a Plackett-Luce ranking term next to the distribution term. It is shared
here rather than kept beside one algorithm because both the EAGLE-1/2 and the
ViSpec objectives use it.

## Module Contents

### Functions

| Name                                                                   | Description                                          |
| ---------------------------------------------------------------------- | ---------------------------------------------------- |
| [`listmle_loss`](#nemo_automodel-components-loss-listmle-listmle_loss) | ListMLE ranking loss over the target's top-k tokens. |

### API

```python
nemo_automodel.components.loss.listmle.listmle_loss(
    logits: torch.Tensor,
    target_probs: torch.Tensor,
    topk: int
) -> torch.Tensor
```

ListMLE ranking loss over the target's top-k tokens.

Scores the student on reproducing the target's *ordering* of its `topk`
most likely tokens: the Plackett-Luce likelihood of drawing those tokens,
under the student's logits, in the target's own descending-probability
order.

**Parameters:**

**`logits`** `torch.Tensor`

Tensor of shape \[tokens, vocab] -- the student's logits at the
supervised positions.

---

**`target_probs`** `torch.Tensor`

Tensor of shape \[tokens, vocab] -- the target's
probabilities at the same positions.

---

**`topk`** `int`

Number of top target tokens to rank.

---

**Returns:** `torch.Tensor`

Scalar Tensor: the mean over `tokens` of the summed negative