Jina Reranker Integration#

The Jina reranker plugin (models/jina/models/rerank/rerank.py) implements the RerankModel interface from the Dify plugin SDK to call Jina's /v1/rerank endpoint. It supports both text-only reranking (_invoke) and multimodal reranking (_invoke_multimodal).

Request Formatting#

The request payload includes 1:

• model — the model name passed in
• query — the search query string
• documents — each document is passed through transform_jina_input_text, which wraps the text as {"text": ...} for models that require it (e.g. jina-clip-v1, jina-clip-v2, jina-embeddings-v4, jina-reranker-m0) or passes the raw string otherwise
• top_n — optional limit on returned results
• return_documents: False — explicitly set; see below

For multimodal invocations, transform_jina_input_multi_modal is used instead, transforming each document into {"text": ...} or {"image": ...} depending on content type 2.

The base URL defaults to https://api.jina.ai/v1 but can be overridden via a base_url credential 3.

The return_documents: false Decision#

This is the critical design choice in this plugin. Jina changed the default value of return_documents to false in their API 4. Before PR #1800, the plugin relied on result["document"]["text"] from the API response to populate RerankDocument.text. When Jina stopped returning document bodies by default, the plugin threw string indices must be integers, not 'str' 4.

The fix (merged 2025-10-08, plugin version bumped 0.0.8 → 0.0.9) 5 makes two complementary changes:

1. Explicitly sets "return_documents": False in the request payload — the plugin no longer asks Jina to return document text at all.
2. Uses the local docs input as the source of truth for document text — after getting back a ranked list of indices, the plugin reads docs[original_index] directly 6:

original_index = result["index"]
RerankDocument(text=docs[original_index], score=result["relevance_score"], ...)

This approach is more robust and cheaper (less data transferred over the wire), and avoids any future drift between API-returned text and the locally held document content.

Response Handling#

The API response is expected under results["results"], where each entry has 7:

• index — the original position of the document in the input docs list
• relevance_score — the ranking score from Jina

The plugin applies score_threshold filtering client-side: only documents whose relevance_score >= score_threshold are included in the final RerankResult 8. If docs is empty, it short-circuits and returns an empty result immediately 9.

HTTP errors are mapped to Dify's unified error types: InvokeConnectionError, InvokeServerUnavailableError, InvokeAuthorizationError, and InvokeBadRequestError 10.

Credential Validation#

validate_credentials exercises the full _invoke path with a hardcoded geography question and two sample documents at score_threshold=0.8 11. Any exception is re-raised as CredentialsValidateFailedError.

Key Files#