fix(nvidia_nim): preserve image passages and stop sending top_k to /v1/ranking

[atomic]

TLDR

Problem this solves:

• Image passages were silently converted into JSON text
• Native ranking rejected LiteLLM's generated top_k field

How it solves it:

• Preserve native text and image passage fields on /v1/ranking
• Stop sending top_k; validate top_n and apply it client-side
• Sort converted results by relevance before truncating to top_n

User Flow

Before: a developer reranking an image gets an error or a misleading text-only result

1. They send POST https://your-litellm-proxy/v1/rerank with an image data URL in documents and top_n: 1
2. The native ranking API receives the image object as serialized JSON text and an unsupported top_k field
3. The request fails with HTTP 400; without top_n, it may return 200 while ranking the serialized URL instead of the image

After: the same request ranks the image and returns the requested number of results

1. They send the same POST https://your-litellm-proxy/v1/rerank request
2. The native ranking API receives the original image passage and no unsupported result-limit field
3. The request returns HTTP 200, and LiteLLM returns the best single result

Relevant issues

Fixes #34165

Linear ticket

Resolves LIT-5403

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

Live before/after QA against real NVIDIA NIM. Before leg is a local proxy booted from this PR's merge base 7e80e094c4 (port 38472), after leg from head 1d7c23a424 (port 38693), each in its own worktree and venv, both serving nvidia_nim/ranking/nvidia/llama-nemotron-rerank-vl-1b-v2 with a real NVIDIA API key. NVIDIA's API catalog hosts this model at /v1/retrieval/nvidia/llama-nemotron-rerank-vl-1b-v2/reranking while the ranking route targets the self-hosted NIM surface {api_base}/v1/ranking, so both legs share one byte-verbatim localhost forwarder to that hosted URL: every validation and score below comes from NVIDIA's live service through identical infrastructure on both legs

The User Flow request, one image data URL document plus one text document with top_n: 1, sent to each proxy:

curl -sS http://localhost:$PORT/v1/rerank \
  -H "Authorization: Bearer sk-qa-34177" -H "Content-Type: application/json" \
  -d '{"model": "nemotron-rerank-vl", "query": "a solid red square image",
       "documents": [{"image": "data:image/png;base64,<64x64 red square>"},
                     {"text": "a poem about the deep blue sea"}],
       "top_n": 1}'

Before, merge base 7e80e094c4: the provider rejects the top_k LiteLLM injected

HTTP 400
{"error":{"message":"{\"error\":\"Your request cannot be validated, it is incorrect. detail={'type': 'extra_forbidden', 'loc': ['body', 'top_k'], 'msg': 'Extra inputs are not permitted', 'input': 1}\"}. Received Model Group=nemotron-rerank-vl\nAvailable Model Group Fallbacks=None","type":"None","param":"None","code":"400"}}

After, head 1d7c23a424: HTTP 200 with exactly the one requested result

HTTP 200
{"id":"37023ed0-aa6a-41f2-ad32-9d8f61adbb57","results":[{"index":0,"relevance_score":-4.9140625}],"meta":{"billed_units":{"total_tokens":284}}}

Dropping top_n from the same request isolates the image bug. Before returns 200 but its own response echoes the image document back as a stringified JSON text passage, so the model scored a text blob; after preserves the image passage

before: results[0].document = {"text": "{\"image\": \"data:image/png;base64,iVBOR...\"}"}  relevance_score=-5.14453125  total_tokens=177
after:  results[0] is the image document ranked first                                   relevance_score=-4.9140625   total_tokens=284

The after leg's score -4.9140625 and 284 billed tokens exactly match a direct curl to NVIDIA's hosted endpoint with the raw image passage, confirming the image reached the model intact. The alias route /rerank reproduces both verdicts, before 400 and after 200

Observations from the run:

• Hosted error reads extra_forbidden, issue quoted unknown field; same rejection
• Hosted catalog has no generic /v1/ranking path; pre-existing
• Hosted retrieval endpoint rejects top_k as well; not PR-caused

Type

🐛 Bug Fix

Caveats (if any)

• /v1/retrieval/{model}/reranking keeps its text-only passage behavior
• top_n is enforced client-side, so the full ranking still crosses the wire

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

[CLAassistant]

All committers have signed the CLA.

[greptile-apps]

Greptile Summary

The PR updates NVIDIA NIM reranking behavior:

• Preserves native image passages only for the /v1/ranking configuration while retaining text-only conversion for the legacy retrieval route.
• Removes unsupported result-limit fields from native ranking requests and applies validated top_n truncation client-side.
• Adds regression coverage for image passage conversion, result sorting and truncation, invalid limits, and retrieval-route compatibility.

Confidence Score: 5/5

The PR appears safe to merge.

The previously reported shared-transform regression is fixed: retrieval configurations retain text-only passage handling, while image preservation is confined to freshly selected native ranking configurations, and no blocking failure remains.

Important Files Changed

Filename	Overview
litellm/llms/nvidia_nim/rerank/ranking_transformation.py	Adds ranking-specific passage support and client-side top_n handling without exposing the behavior to the legacy retrieval route.
litellm/llms/nvidia_nim/rerank/transformation.py	Introduces route-specific passage-field filtering that preserves the retrieval endpoint’s prior text-only conversion semantics.
tests/test_litellm/llms/nvidia_nim/rerank/test_nvidia_nim_rerank_transformation.py	Adds mocked regression tests covering native ranking behavior and the legacy retrieval contract.

_{Reviews (9): Last reviewed commit: "Merge branch 'litellm_internal_staging' ..." | Re-trigger Greptile}

[atomic]

@greptileai

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing atomic:fix/nvidia-nim-ranking-image-passages-top-n (1d7c23a) with litellm_internal_staging (7e80e09)¹}

Footnotes

1. No successful run was found on litellm_internal_staging (5e620af) during the generation of this report, so 7e80e09 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[shivamrawat1]

@greptile review again with new commit

[atomic]

@greptileai

[atomic]

@greptileai

[atomic]

@greptileai

[atomic]

@shivamrawat1 following up on this one — Greptile re-reviewed after the latest commits and now gives it 5/5 ("appears safe to merge"). The P1 it originally raised is resolved: image-passage support is scoped to NvidiaNimRankingConfig, so the /v1/retrieval/{model}/reranking route keeps its previous text-only passage behavior, with tests covering both routes.

Current state:

• 77 checks green. The one red is codecov/patch — the new tests live in tests/llm_translation/test_nvidia_nim.py, which isn't part of the Codecov-instrumented run, so the patch shows as uncovered. Happy to move or duplicate them under tests/test_litellm/ if you'd prefer the coverage signal.
• CodSpeed: no performance change across 31 benchmarks.
• Branch is mergeable against litellm_internal_staging.

I still need to get the CLA sorted on my side, so no rush on merging — but a review whenever you have a moment would be much appreciated, and I'll have the CLA signed before it'd block anything.

Fixes #34165.

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 2208813. Configure here.}

[mateo-berri]

@greptileai

[mateo-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 1d7c23a. Configure here.}

[mateo-berri]

LGTM. Thank you for the contribution!