[Proposal] ScoringModel Abstraction for Provider-Agnostic Document Reranking

[cylin0201]

Motivation

Document reranking is becoming an important part of many RAG pipelines. A common pattern is to first retrieve a broader set of candidate documents using vector search, and then apply a more expensive scoring or reranking step to improve the final context passed to the model.

At the moment, Spring AI does not seem to have a provider-agnostic abstraction for this use case. Developers who want to add reranking usually need to either:

• rely on provider-specific features, such as reranking built into a managed knowledge base,
• call an external reranking API manually,
• or implement custom logic inside a DocumentPostProcessor.

This works, but it makes the application code tightly coupled to a specific provider or implementation strategy. Since Spring AI already provides model abstractions for chat, embeddings, images, and other model types, I thought a similar abstraction for document scoring/reranking might be useful.

Proposal: ScoringModel

I would like to propose a new ScoringModel abstraction that follows the existing Model<TReq, TRes> pattern used in Spring AI:

ScoringModel extends Model<ScoringRequest, ScoringResponse>

The core types would live in spring-ai-model:

Type	Role
ScoringRequest	Contains the query and candidate documents
ScoringResponse	Returns scored results
ScoringResult	Represents a document with its relevance score
ScoringModel	Provider-agnostic scoring interface
ScoringOptions	Base options for provider-specific implementations

The main use case would be document reranking, but I intentionally used the term “scoring” because the abstraction could support both dedicated reranker APIs and other scoring-based implementations.

RAG Integration

For RAG pipelines, this could be integrated through a DocumentPostProcessor:

ScoringDocumentPostProcessor postProcessor = ScoringDocumentPostProcessor.builder()
    .scoringModel(scoringModel)
    .build();

RetrievalAugmentationAdvisor advisor = RetrievalAugmentationAdvisor.builder()
    .documentRetriever(retriever)
    .documentPostProcessors(List.of(postProcessor))
    .build();

This would allow users to plug any ScoringModel into the existing RetrievalAugmentationAdvisor flow without coupling their RAG pipeline to a specific provider.

Current Implementation

I currently have a working implementation for Jina AI.

JinaScoringModel

This implementation uses Jina AI's /v1/rerank endpoint, which is a dedicated reranking API:

JinaScoringModel scoringModel = JinaScoringModel.builder()
    .jinaScoringApi(jinaScoringApi)
    .options(JinaScoringOptions.builder()
        .model("jina-reranker-v2-base-multilingual")
        .build())
    .build();

ScoringResponse response = scoringModel.call("What is Spring AI?", documents);

The current implementation includes:

• core ScoringModel abstractions,
• JinaScoringModel,
• Spring Boot auto-configuration,
• starter support,
• unit tests using MockWebServer,
• and integration tests, including NDCG@k-style evaluation.

Questions for Feedback

I would really appreciate feedback on the following points:

1. Naming
   Does ScoringModel make sense, or would RerankingModel / RerankModel be a better fit for Spring AI?

2. Scope
   Would it be better to start with only the core abstraction and one provider implementation, such as Jina, and leave additional providers for follow-up PRs?

3. Design
   Does aligning this with the existing Model<TReq, TRes> pattern feel appropriate?

4. RAG integration
   Does a ScoringDocumentPostProcessor seem like the right integration point for RetrievalAugmentationAdvisor?

5. Roadmap alignment
   Is this something that could fit into the Spring AI 2.0 direction?

Related

• Issue: [Feature Request] Introduce ScoringModel abstraction for Document Reranking #5776
• PR: GH-5776: Add Jina AI Scoring (Reranker) Module #5887

I would be happy to adjust the design based on maintainer feedback. Thanks!