Skip to content

[Docs] Add migration guide for switching between model providers (e.g., OpenAI → Ollama) #5721

@sachin-gupta99

Description

@sachin-gupta99

Summary

There is currently no documentation or guide for migrating between model providers in Spring AI. For example, switching from spring-ai-starter-model-openai to spring-ai-starter-model-ollama requires changes across dependencies, configuration properties, and potentially prompt templates — but there's no centralized resource explaining the steps.

Context

I recently migrated my microservice from OpenAI to Ollama. The process involved:

  1. Swapping the Maven dependency (spring-ai-starter-model-openaispring-ai-starter-model-ollama)
  2. Updating application.yaml properties (model name, base URL, embedding config)
  3. Adjusting prompt templates for differences in model behavior
  4. Handling differences in streaming response formats

While each step is individually documented, there's no unified migration guide that walks through provider switching end-to-end.

Proposal

Add a documentation page (or section within existing docs) covering:

  • Common migration paths (OpenAI ↔ Ollama, OpenAI ↔ Azure OpenAI, etc.)
  • Dependency changes required
  • Configuration property mappings between providers
  • Known behavioral differences (e.g., streaming, token counting, embedding dimensions)
  • A checklist for verifying the migration

Why this matters

As teams evaluate cost, latency, and data privacy trade-offs, switching model providers is a common need. A migration guide would significantly reduce friction for adopters.

Spring Boot version: 4.0.2
Spring AI version: 2.0.0-M2

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions