[Bugfix][Model] Reject encoder-backbone jina-embeddings-v5 checkpoints with a clear error (fixes #50337) (#50352)

Signed-off-by: seewoo <seewoo@ucsc.edu>
Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Sebastian Woo
2026-07-31 11:43:31 +08:00
committed by GitHub
co-authored by Claude
parent b49eaf205a
commit bebf918044
2 changed files with 96 additions and 0 deletions
@@ -0,0 +1,64 @@
# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
"""Backbone validation for Jina Embeddings V5 (issue #50337).
The V5 family ships two backbones under one `architectures` entry: `-small` is
a Qwen3 decoder (which vLLM implements), while `-nano` is a bidirectional
EuroBERT encoder (which it does not). Upstream ships a separate
`configuration_*.py` per repository, so the only signal distinguishing them is
`is_decoder`, which the encoder variant sets to False.
"""
from types import SimpleNamespace
from typing import cast
import pytest
from transformers import PretrainedConfig
from vllm.config import ModelConfig
from vllm.model_executor.models.config import (
MODELS_CONFIG_MAP,
JinaEmbeddingsV5ModelConfig,
)
def _model_config(hf_config: PretrainedConfig) -> ModelConfig:
"""Minimal stand-in for ModelConfig; only hf_config is read."""
return cast(ModelConfig, SimpleNamespace(hf_config=hf_config))
@pytest.mark.cpu_test
def test_registered_for_the_architecture():
"""The handler only runs if it is wired to the architecture name."""
assert MODELS_CONFIG_MAP["JinaEmbeddingsV5Model"] is JinaEmbeddingsV5ModelConfig
@pytest.mark.cpu_test
def test_encoder_backbone_is_rejected():
"""An encoder checkpoint must fail fast, naming the reason.
Without this, loading proceeds until every `q_norm`/`k_norm` weight is
reported as uninitialized, which does not point at the actual problem.
"""
model_config = _model_config(PretrainedConfig(is_decoder=False))
with pytest.raises(NotImplementedError, match="is_decoder=False"):
JinaEmbeddingsV5ModelConfig.verify_and_update_model_config(model_config)
@pytest.mark.cpu_test
def test_supported_decoder_backbone_is_accepted():
"""The Qwen3-based variants must keep loading.
`-small` omits `is_decoder` entirely, so an absent attribute has to be
treated as a decoder. The first assertion pins that assumption: if
PretrainedConfig ever gains an `is_decoder=False` default, this fails here
rather than silently rejecting a supported checkpoint.
"""
absent = PretrainedConfig()
assert not hasattr(absent, "is_decoder")
JinaEmbeddingsV5ModelConfig.verify_and_update_model_config(_model_config(absent))
JinaEmbeddingsV5ModelConfig.verify_and_update_model_config(
_model_config(PretrainedConfig(is_decoder=True))
)
+32
View File
@@ -474,6 +474,37 @@ class JambaForSequenceClassificationConfig(VerifyAndUpdateConfig):
pooler_config.use_activation = False
class JinaEmbeddingsV5ModelConfig(VerifyAndUpdateConfig):
"""Config handler for Jina Embeddings V5 embedding models."""
@staticmethod
def verify_and_update_model_config(model_config: "ModelConfig") -> None:
"""Reject checkpoints whose backbone is not the Qwen3 decoder.
The V5 family ships more than one backbone under a single
`architectures` entry: the `-small` variants are Qwen3 decoders, while
`-nano` is a bidirectional EuroBERT encoder. Upstream ships a separate
`configuration_*.py` per repository, so the config carries no backbone
field and the encoder variants are only identifiable by
`is_decoder=False`. `JinaEmbeddingsV5Model` extends `Qwen3ForCausalLM`
and has no path to an encoder backbone, so without this check such a
checkpoint fails later with every `q_norm` and `k_norm` weight reported
as uninitialized, which does not point at the actual problem.
Raises:
NotImplementedError: If the checkpoint uses an encoder backbone.
"""
if getattr(model_config.hf_config, "is_decoder", True):
return
raise NotImplementedError(
"This jina-embeddings-v5 checkpoint uses a bidirectional encoder "
"backbone (is_decoder=False). JinaEmbeddingsV5Model is built on "
"Qwen3 and cannot serve it, so only the Qwen3-based decoder "
"variants are supported, such as jina-embeddings-v5-text-small."
)
class JinaForRankingConfig(VerifyAndUpdateConfig):
@staticmethod
def verify_and_update_model_config(model_config: "ModelConfig") -> None:
@@ -915,6 +946,7 @@ MODELS_CONFIG_MAP: dict[str, type[VerifyAndUpdateConfig]] = {
"GteNewForSequenceClassification": GteNewModelConfig,
"GteNewModel": GteNewModelConfig,
"JambaForSequenceClassification": JambaForSequenceClassificationConfig,
"JinaEmbeddingsV5Model": JinaEmbeddingsV5ModelConfig,
"JinaForRanking": JinaForRankingConfig,
"JinaVLForRanking": JinaVLForSequenceClassificationConfig,
"KimiK3ForConditionalGeneration": KimiK3ForConditionalGenerationConfig,