[Frontend][Doc][5/N] Improve all pooling task | Polish encode (pooling) api & Document.

[noooop]

TL;DR

• pooling_task required for llm.encode
• /pooling endpoint support all pooling tasks
• softmax, activation -> use_activation

Improve all pooling task (0.11.1 cut)

• [Model][0/N] Improve all pooling task | clean up #25817
• [Frontend][1/N] Improve all pooling task | Support FP16 Embedding Base64 (Still uses fp32 by default). #26414
• [Model][2/N] Improve all pooling task | Support multi-vector retrieval #25370
• [Frontend][3/N] Improve all pooling task | Support binary embedding response #27066
• [Frontend][4/N] Improve all pooling task | Add plugin pooling task #26973
• [Frontend][Doc][5/N] Improve all pooling task | Polish encode (pooling) api & Document. #25524

These PRs are mostly conflicting with each other, so combining them into a series would better inform reviewers about what happened. And what else needs to be done after that?

Purpose

Following #25370

• Split the encode task into two tasks: token_embed and token_classify
  • token_embed is the same as embed, using normalize as activation
  • token_classify is the same as classify, default using softmax as activation (we actually allow classify and token_classify to use any activation function by setting act_fn. )

Address: #27413 (comment)

• /pooling endpoint support all pooling tasks.

Test Plan

Test Result

---

Essential Elements of an Effective PR Description Checklist

• The purpose of the PR, such as "Fix some issue (link existing issues this PR will resolve)".
• The test plan, such as providing test command.
• The test results, such as pasting the results comparison before and after, or e2e results
• (Optional) The necessary documentation update, such as updating supported_models.md and examples for a new model.
• (Optional) Release notes update. If your change is user facing, please update the release notes draft in the Google Doc.

[noooop]

@DarkLight1337

We continue our previous discussion here

following #25370

Split the encode task into two tasks: token_embed and token_classify

• token_embed is the same as embed, using normalize as activation
• token_classify is the same as classify, default using softmax as activation

For online scenarios (/pooling):

• Keep one api now (/pooling), but we need to adaptively select token_embed or token_classify using something like encode2pooling_task method somewhere

• split the /pooling api into /pooling_token_embed and /pooling_token_classify. （I personally feel that /pooling_token_embed and /pooling_token_classify looks terrible, the online /pooling API is not suitable for major changes yet. We can collect usage scenarios for a while.）

[DarkLight1337]

I think for online API, the user should be able to pass the task in the request.

[mergify]

Documentation preview: https://vllm--25524.org.readthedocs.build/en/25524/

[noooop]

/gemini review

[noooop]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors the pooling API by splitting the encode task into more specific tasks (token_embed, token_classify) and renaming the activation parameter to use_activation for clarity. The documentation, examples, and tests are updated to reflect these changes. The changes are generally well-executed and improve the API's usability. However, I've identified a critical issue in the task inference logic for the new generic /pooling endpoint that could lead to unexpected failures. My review includes a suggestion to fix this logic.

[hmellor]

Since activation was user facing, we should probably deprecate it when changing it to use_activation

[noooop]

Since activation was user facing, we should probably deprecate it when changing it to use_activation

Anyway, I’d like to merge this PR quickly before the release. It’s mainly documentation changes.

This feature has been a bit of a mess, and it’s been changing with every recent release. It should finally be stable now after this latest change.

[DarkLight1337]

I agree with @hmellor , we should still keep the old field with a deprecation

[DarkLight1337]

Otherwise we would break back-compatibility, which is definitely not what a "doc PR" should do

[noooop]

cc @DarkLight1337

Let’s land this.