jina-v4-vllm-plugin
vLLM out-of-tree model plugin that makes a stock vLLM OpenAI server serve
Jina Embeddings v4 multi-vector (128-dim/token, ColBERT-style late interaction) multimodal
(text + image) embeddings. With the plugin installed, the server's /pooling endpoint returns final
L2-normalized [n,128] per-token multivectors directly — no proxy, no client-side projection.
It registers a JinaV4MultiVector architecture (Qwen2.5-VL backbone + Jina's multi_vector_projector
applied in-engine, mirroring vLLM's in-tree ColQwen3/ColPali pattern) via a vllm.general_plugins
entry point, so it loads in every vLLM process including the v1 EngineCore worker.
Install
pip install jina-v4-vllm-plugin # from PyPI
# into an image that already provides vLLM (e.g. vllm/vllm-openai), skip re-resolving vLLM/torch:
pip install --no-deps jina-v4-vllm-plugin
--no-deps keeps pip from re-resolving vLLM/torch inside the official image. Pin the host vLLM
version the plugin was validated against — see research/docs/COMPAT.md.
Use
vllm serve <jina-v4-checkpoint> \
--runner pooling --pooler-config.task token_embed \
--hf-overrides '{"architectures":["JinaV4MultiVector"]}' \
--chat-template "$(python -c 'import jina_v4_vllm_plugin as p; print(p.chat_template_path())')"
The projector weights (128×2048 + bias) are not in the vLLM checkpoint; the plugin loads them
at startup from JINA_MV_PROJECTOR (default /artifacts/projector/retrieval.npz), or from the
checkpoint itself if baked in. A ready-made baked, drop-in checkpoint is published at
Mazyod/jina-embeddings-v4-vllm-mv.
Build & validation tooling
The Modal build/validate/bake/deploy harness that produced and verified the artifacts lives under
research/ (its own uv project): projector extraction, checkpoint baking, HF-vs-vLLM
parity, the deploy runbook, and the vLLM-version compatibility matrix
(research/docs/COMPAT.md, research/deploy/DEPLOY.md).
Develop
make install # uv sync
make test # packaging contract tests (no GPU/vLLM)
make build # sdist + wheel into dist/
Releases publish to PyPI via GitHub Actions Trusted Publishing (OIDC) — run the Publish to PyPI
workflow (workflow_dispatch, choose patch/minor/major).
Metadata
Release files for jina-v4-vllm-plugin 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| jina_v4_vllm_plugin-0.1.1.tar.gz | 316.2 kB | With provenance | Details for jina_v4_vllm_plugin-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jina_v4_vllm_plugin-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for jina_v4_vllm_plugin-0.1.1-py3-none-any.whl |
Total release size: 323.1 kB
Release files / jina_v4_vllm_plugin-0.1.1.tar.gz
| Download URL | jina_v4_vllm_plugin-0.1.1.tar.gz |
|---|---|
| Size | 316.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2a9c45ed6555563155141ae2b9161097e5c5ba453cf8fed35ac5cefe789e712b
|
|
BLAKE2b-256 checksum How to use checksums |
75c062a41361f004aaa77bbf30fff3ac0fbed28eea62a6db0fb0a47ca621a936
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 11, 2026.
Transparency logRelease files / jina_v4_vllm_plugin-0.1.1-py3-none-any.whl
| Download URL | jina_v4_vllm_plugin-0.1.1-py3-none-any.whl |
|---|---|
| Size | 6.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
98be0623426d3e6d7e8438fcbc14bff0e028973658c912015770edbc3bf3b7a5
|
|
BLAKE2b-256 checksum How to use checksums |
2442bb040fc413d1c180f7385317d02692042d83acef448fb67a0de270e78f37
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 11, 2026.
Transparency logSecurity for jina-v4-vllm-plugin 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for jina_v4_vllm_plugin-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 11, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.