CtrlK

Community Documentation Log in Get started

tessl/maven-org-springframework-ai--spring-ai-transformers

ONNX-based Transformer models for text embeddings within the Spring AI framework

Overview

Eval results

Files

Spring Boot Configuration

Name: tessl/maven-org-springframework-ai--spring-ai-transformers
Author: tessl

Configure the TransformersEmbeddingModel using Spring Boot's application properties or YAML files. The auto-configuration module provides property-based configuration that eliminates the need for manual bean creation and initialization.

Capabilities

Configuration Properties Overview

All configuration properties use the spring.ai.embedding.transformer prefix. The auto-configuration automatically creates and initializes a TransformersEmbeddingModel bean based on these properties.

/**
 * Configuration properties prefix for Transformer Embedding model.
 */
public static final String CONFIG_PREFIX = "spring.ai.embedding.transformer";

Property Naming Conventions:

# Dot notation (properties files)
spring.ai.embedding.transformer.cache.enabled=true

# Environment variable (uppercase with underscores)
SPRING_AI_EMBEDDING_TRANSFORMER_CACHE_ENABLED=true

# System property (dot notation)
-Dspring.ai.embedding.transformer.cache.enabled=true

Metadata Mode Configuration

Control how Document metadata is included in embeddings. Applies only to embed(Document) method.

/**
 * Specifies what parts of the Document's content and metadata will be used
 * for computing the embeddings.
 */
private MetadataMode metadataMode = MetadataMode.NONE;

public MetadataMode getMetadataMode();
public void setMetadataMode(MetadataMode metadataMode);

application.properties:

spring.ai.embedding.transformer.metadata-mode=NONE
# Options: NONE, EMBED, ALL
# Default: NONE

application.yaml:

spring:
  ai:
    embedding:
      transformer:
        metadata-mode: NONE  # NONE, EMBED, or ALL

Default: NONE (document text only, no metadata)

MetadataMode Values:

// NONE: Embed text content only (default)
spring.ai.embedding.transformer.metadata-mode=NONE

// EMBED: Include metadata in embedding
spring.ai.embedding.transformer.metadata-mode=EMBED

// ALL: Include all metadata fields
spring.ai.embedding.transformer.metadata-mode=ALL

Usage Examples:

# Development: No metadata
spring.ai.embedding.transformer.metadata-mode=NONE

# Production: Include relevant metadata for better search
spring.ai.embedding.transformer.metadata-mode=EMBED

# Testing: All metadata for debugging
spring.ai.embedding.transformer.metadata-mode=ALL

Edge Cases:

# Invalid value - application fails to start
spring.ai.embedding.transformer.metadata-mode=INVALID
# Error: Failed to convert property value of type 'java.lang.String' to required type 'MetadataMode'

# Empty value - uses default (NONE)
spring.ai.embedding.transformer.metadata-mode=

# Case sensitivity - must be uppercase
spring.ai.embedding.transformer.metadata-mode=none  # ERROR
spring.ai.embedding.transformer.metadata-mode=NONE  # CORRECT

Tokenizer Configuration

Configure the HuggingFace tokenizer resource and options.

/**
 * Configurations for the HuggingFaceTokenizer used to convert sentences into tokens.
 */
public static class Tokenizer {

    /**
     * URI of a pre-trained HuggingFaceTokenizer created by the ONNX engine (e.g. tokenizer.json).
     */
    private String uri = TransformersEmbeddingModel.DEFAULT_ONNX_TOKENIZER_URI;

    /**
     * HuggingFaceTokenizer options such as 'addSpecialTokens', 'modelMaxLength',
     * 'truncation', 'padding', 'maxLength', 'stride' and 'padToMultipleOf'.
     * Leave empty to fall back to the defaults.
     */
    private final Map<String, String> options = new HashMap<>();

    public String getUri();
    public void setUri(String uri);
    public Map<String, String> getOptions();
}

Tokenizer URI

application.properties:

# Tokenizer resource URI
spring.ai.embedding.transformer.tokenizer.uri=classpath:/tokenizers/custom-tokenizer.json

# From classpath
spring.ai.embedding.transformer.tokenizer.uri=classpath:/tokenizers/tokenizer.json

# From filesystem (absolute path)
spring.ai.embedding.transformer.tokenizer.uri=file:///path/to/tokenizer.json

# From URL
spring.ai.embedding.transformer.tokenizer.uri=https://example.com/tokenizers/tokenizer.json

# Using environment variable
spring.ai.embedding.transformer.tokenizer.uri=${TOKENIZER_URI:classpath:/tokenizers/default.json}

application.yaml:

spring:
  ai:
    embedding:
      transformer:
        tokenizer:
          uri: classpath:/tokenizers/custom-tokenizer.json

Default URI: https://raw.githubusercontent.com/spring-projects/spring-ai/main/models/spring-ai-transformers/src/main/resources/onnx/all-MiniLM-L6-v2/tokenizer.json

Tokenizer Options

application.properties:

# Tokenizer options (all values are strings)
spring.ai.embedding.transformer.tokenizer.options.addSpecialTokens=true
spring.ai.embedding.transformer.tokenizer.options.modelMaxLength=512
spring.ai.embedding.transformer.tokenizer.options.truncation=true
spring.ai.embedding.transformer.tokenizer.options.padding=true
spring.ai.embedding.transformer.tokenizer.options.maxLength=512
spring.ai.embedding.transformer.tokenizer.options.stride=128
spring.ai.embedding.transformer.tokenizer.options.padToMultipleOf=8

application.yaml:

spring:
  ai:
    embedding:
      transformer:
        tokenizer:
          uri: classpath:/tokenizers/custom-tokenizer.json
          options:
            addSpecialTokens: "true"
            modelMaxLength: "512"
            truncation: "true"
            padding: "true"
            maxLength: "512"
            stride: "128"
            padToMultipleOf: "8"

Common Tokenizer Options:

# addSpecialTokens: Add CLS, SEP tokens
# Values: "true" | "false"
# Default: tokenizer's built-in default
spring.ai.embedding.transformer.tokenizer.options.addSpecialTokens=true

# modelMaxLength: Maximum sequence length
# Values: numeric string (e.g., "512", "1024")
# Default: tokenizer's built-in default
spring.ai.embedding.transformer.tokenizer.options.modelMaxLength=512

# truncation: Truncate sequences exceeding max length
# Values: "true" | "false"
# Default: tokenizer's built-in default
spring.ai.embedding.transformer.tokenizer.options.truncation=true

# padding: Pad short sequences
# Values: "true" | "false" | "max_length" | "longest"
# Default: tokenizer's built-in default
spring.ai.embedding.transformer.tokenizer.options.padding=max_length

# maxLength: Explicit max length for padding/truncation
# Values: numeric string
# Default: derived from modelMaxLength
spring.ai.embedding.transformer.tokenizer.options.maxLength=512

# stride: Stride for sliding window tokenization
# Values: numeric string
# Default: 0 (no stride)
spring.ai.embedding.transformer.tokenizer.options.stride=128

# padToMultipleOf: Round padding length to multiple
# Values: numeric string (typically 8 for hardware optimization)
# Default: no rounding
spring.ai.embedding.transformer.tokenizer.options.padToMultipleOf=8

Configuration Examples:

# Example 1: Strict truncation (for consistent embedding size)
spring.ai.embedding.transformer.tokenizer.options.truncation=true
spring.ai.embedding.transformer.tokenizer.options.maxLength=256
spring.ai.embedding.transformer.tokenizer.options.padding=max_length

# Example 2: No special tokens (for custom models)
spring.ai.embedding.transformer.tokenizer.options.addSpecialTokens=false

# Example 3: Sliding window with stride
spring.ai.embedding.transformer.tokenizer.options.maxLength=512
spring.ai.embedding.transformer.tokenizer.options.stride=256
spring.ai.embedding.transformer.tokenizer.options.truncation=true

# Example 4: Hardware-optimized padding
spring.ai.embedding.transformer.tokenizer.options.padding=true
spring.ai.embedding.transformer.tokenizer.options.padToMultipleOf=8

Edge Cases:

# Invalid boolean value - behavior depends on tokenizer
spring.ai.embedding.transformer.tokenizer.options.truncation=invalid
# May be ignored or cause error during initialization

# Non-numeric value for numeric option
spring.ai.embedding.transformer.tokenizer.options.maxLength=abc
# Likely causes error during initialization

# Conflicting options - last one wins (in properties file)
spring.ai.embedding.transformer.tokenizer.options.padding=true
spring.ai.embedding.transformer.tokenizer.options.padding=false
# Result: false (properties file loads sequentially)

# Empty option value
spring.ai.embedding.transformer.tokenizer.options.truncation=
# May be ignored or treated as false

# Case sensitivity
spring.ai.embedding.transformer.tokenizer.options.Truncation=true  # Wrong case
# Option ignored (correct: truncation with lowercase 't')

Cache Configuration

Control resource caching behavior for models and tokenizers.

/**
 * Controls caching of remote, large resources to local file system.
 */
public static class Cache {

    /**
     * Enable the Resource caching.
     */
    private boolean enabled = true;

    /**
     * Resource cache directory. Used to cache remote resources, such as the ONNX
     * models, to the local file system. Applicable only for cache.enabled == true.
     * Defaults to {java.io.tmpdir}/spring-ai-onnx-generative.
     */
    private String directory = DEFAULT_CACHE_DIRECTORY;

    public boolean isEnabled();
    public void setEnabled(boolean enabled);
    public String getDirectory();
    public void setDirectory(String directory);
}

application.properties:

# Enable/disable caching
spring.ai.embedding.transformer.cache.enabled=true
# Default: true

# Cache directory location
spring.ai.embedding.transformer.cache.directory=/var/cache/spring-ai-models
# Default: {java.io.tmpdir}/spring-ai-onnx-generative

# Using environment variables
spring.ai.embedding.transformer.cache.directory=${CACHE_DIR:/var/cache/models}

# Using user home directory
spring.ai.embedding.transformer.cache.directory=${user.home}/.spring-ai/cache

# Using relative path (relative to working directory)
spring.ai.embedding.transformer.cache.directory=./cache

application.yaml:

spring:
  ai:
    embedding:
      transformer:
        cache:
          enabled: true
          directory: /var/cache/spring-ai-models

Default Enabled: true (caching enabled)

Default Directory: {java.io.tmpdir}/spring-ai-onnx-generative

Environment-Specific Configuration:

# application-dev.properties
spring.ai.embedding.transformer.cache.enabled=false  # Disable for development
spring.ai.embedding.transformer.cache.directory=./dev-cache

# application-test.properties
spring.ai.embedding.transformer.cache.enabled=true
spring.ai.embedding.transformer.cache.directory=${java.io.tmpdir}/test-cache

# application-prod.properties
spring.ai.embedding.transformer.cache.enabled=true
spring.ai.embedding.transformer.cache.directory=/var/cache/spring-ai-models

Use Cases:

# Development: Disable caching for frequently changing models
spring.ai.embedding.transformer.cache.enabled=false

# Production: Enable with persistent directory
spring.ai.embedding.transformer.cache.enabled=true
spring.ai.embedding.transformer.cache.directory=/persistent/cache

# Testing: Enable with temporary directory
spring.ai.embedding.transformer.cache.enabled=true
spring.ai.embedding.transformer.cache.directory=${java.io.tmpdir}/test-cache

# Containerized: Use volume-mounted directory
spring.ai.embedding.transformer.cache.enabled=true
spring.ai.embedding.transformer.cache.directory=/mnt/cache

Edge Cases:

# Directory with no write permissions - fails during initialization
spring.ai.embedding.transformer.cache.directory=/root/cache
# Error: Permission denied

# Directory on full disk - fails during model download
spring.ai.embedding.transformer.cache.directory=/full/disk/cache
# Error: No space left on device

# Very long path - may fail on some filesystems
spring.ai.embedding.transformer.cache.directory=/very/long/path/...
# Windows max path: 260 characters

# Network-mounted directory - works but slower
spring.ai.embedding.transformer.cache.directory=/mnt/nfs/cache
# Higher latency but shared across instances

# Disable caching but specify directory - directory ignored
spring.ai.embedding.transformer.cache.enabled=false
spring.ai.embedding.transformer.cache.directory=/some/dir
# Directory setting has no effect when caching is disabled

ONNX Model Configuration

Configure the ONNX model resource, output layer name, and GPU settings.

/**
 * ONNX model configuration.
 */
public static class Onnx {

    /**
     * Existing, pre-trained ONNX generative. Commonly exported from
     * https://sbert.net/docs/pretrained_models.html. Defaults to
     * sentence-transformers/all-MiniLM-L6-v2.
     */
    private String modelUri = TransformersEmbeddingModel.DEFAULT_ONNX_MODEL_URI;

    /**
     * Defaults to: 'last_hidden_state'.
     */
    private String modelOutputName = TransformersEmbeddingModel.DEFAULT_MODEL_OUTPUT_NAME;

    /**
     * Run on a GPU or with another provider (optional).
     * https://onnxruntime.ai/docs/get-started/with-java.html#run-on-a-gpu-or-with-another-provider-optional
     *
     * The GPU device ID to execute on. Only applicable if >= 0. Ignored otherwise.
     */
    private int gpuDeviceId = -1;

    public String getModelUri();
    public void setModelUri(String modelUri);
    public int getGpuDeviceId();
    public void setGpuDeviceId(int gpuDeviceId);
    public String getModelOutputName();
    public void setModelOutputName(String modelOutputName);
}

application.properties:

# ONNX model URI
spring.ai.embedding.transformer.onnx.model-uri=https://example.com/models/custom-bert.onnx
# Default: https://github.com/.../all-MiniLM-L6-v2/model.onnx

# From classpath
spring.ai.embedding.transformer.onnx.model-uri=classpath:/models/model.onnx

# From filesystem
spring.ai.embedding.transformer.onnx.model-uri=file:///path/to/model.onnx

# Using environment variable
spring.ai.embedding.transformer.onnx.model-uri=${MODEL_URI:classpath:/models/default.onnx}

# Model output tensor name
spring.ai.embedding.transformer.onnx.model-output-name=last_hidden_state
# Default: last_hidden_state

# GPU device ID
spring.ai.embedding.transformer.onnx.gpu-device-id=0
# Values: -1 (CPU), 0 (first GPU), 1 (second GPU), etc.
# Default: -1 (CPU)

# Using environment variable for GPU
spring.ai.embedding.transformer.onnx.gpu-device-id=${GPU_DEVICE_ID:-1}

application.yaml:

spring:
  ai:
    embedding:
      transformer:
        onnx:
          model-uri: https://example.com/models/custom-bert.onnx
          model-output-name: last_hidden_state
          gpu-device-id: 0  # -1 for CPU, 0+ for GPU device ID

Default Model URI: https://github.com/spring-projects/spring-ai/raw/main/models/spring-ai-transformers/src/main/resources/onnx/all-MiniLM-L6-v2/model.onnx

Default Output Name: last_hidden_state

Default GPU Device ID: -1 (CPU inference)

GPU Configuration Examples:

# CPU only (default)
spring.ai.embedding.transformer.onnx.gpu-device-id=-1

# First GPU
spring.ai.embedding.transformer.onnx.gpu-device-id=0

# Second GPU (multi-GPU system)
spring.ai.embedding.transformer.onnx.gpu-device-id=1

# Environment-based GPU selection
spring.ai.embedding.transformer.onnx.gpu-device-id=${CUDA_VISIBLE_DEVICES:0}

# Fallback to CPU if GPU unavailable (in properties - won't work, needs code)
# Better approach: handle in custom bean configuration

Model Output Name Examples:

# BERT-based models
spring.ai.embedding.transformer.onnx.model-output-name=last_hidden_state  # Token embeddings
spring.ai.embedding.transformer.onnx.model-output-name=pooler_output      # CLS token

# Sentence-BERT models
spring.ai.embedding.transformer.onnx.model-output-name=sentence_embedding # Sentence-level
spring.ai.embedding.transformer.onnx.model-output-name=token_embeddings   # Token-level

# Custom models - check with ONNX model inspector
spring.ai.embedding.transformer.onnx.model-output-name=embeddings

Edge Cases:

# Invalid GPU ID - fails during initialization
spring.ai.embedding.transformer.onnx.gpu-device-id=999
# Error: Invalid device ID or CUDA error

# Non-numeric GPU ID - fails to parse
spring.ai.embedding.transformer.onnx.gpu-device-id=gpu0
# Error: NumberFormatException

# Invalid model output name - fails during initialization
spring.ai.embedding.transformer.onnx.model-output-name=nonexistent
# Error: Output 'nonexistent' not found in model

# Empty model URI - uses default
spring.ai.embedding.transformer.onnx.model-uri=
# May use default or fail

# Invalid model URI - fails during initialization
spring.ai.embedding.transformer.onnx.model-uri=invalid://url
# Error: Unknown protocol or network error

Profile-Specific GPU Configuration:

# application-dev.properties
spring.ai.embedding.transformer.onnx.gpu-device-id=-1  # CPU for development

# application-test.properties
spring.ai.embedding.transformer.onnx.gpu-device-id=-1  # CPU for consistent tests

# application-prod.properties
spring.ai.embedding.transformer.onnx.gpu-device-id=0   # GPU for production

Complete Configuration Example

application.properties Example

# ========================================
# Spring AI Transformers Configuration
# ========================================

# Metadata handling
spring.ai.embedding.transformer.metadata-mode=NONE

# Tokenizer configuration
spring.ai.embedding.transformer.tokenizer.uri=classpath:/models/tokenizer.json
spring.ai.embedding.transformer.tokenizer.options.modelMaxLength=512
spring.ai.embedding.transformer.tokenizer.options.truncation=true
spring.ai.embedding.transformer.tokenizer.options.padding=max_length
spring.ai.embedding.transformer.tokenizer.options.addSpecialTokens=true

# Cache configuration
spring.ai.embedding.transformer.cache.enabled=true
spring.ai.embedding.transformer.cache.directory=/var/cache/spring-ai

# ONNX model configuration
spring.ai.embedding.transformer.onnx.model-uri=classpath:/models/custom-model.onnx
spring.ai.embedding.transformer.onnx.model-output-name=last_hidden_state
spring.ai.embedding.transformer.onnx.gpu-device-id=0

application.yaml Example

spring:
  ai:
    embedding:
      transformer:
        # Metadata handling
        metadata-mode: NONE

        # Tokenizer configuration
        tokenizer:
          uri: classpath:/models/tokenizer.json
          options:
            modelMaxLength: "512"
            truncation: "true"
            padding: "max_length"
            addSpecialTokens: "true"

        # Cache configuration
        cache:
          enabled: true
          directory: /var/cache/spring-ai

        # ONNX model configuration
        onnx:
          model-uri: classpath:/models/custom-model.onnx
          model-output-name: last_hidden_state
          gpu-device-id: 0

Environment-Specific Configuration

# ========================================
# application-dev.properties
# ========================================
spring.ai.embedding.transformer.onnx.gpu-device-id=-1
spring.ai.embedding.transformer.cache.enabled=false
spring.ai.embedding.transformer.onnx.model-uri=file:///local/dev/models/model.onnx

# ========================================
# application-test.properties
# ========================================
spring.ai.embedding.transformer.onnx.gpu-device-id=-1
spring.ai.embedding.transformer.cache.enabled=true
spring.ai.embedding.transformer.cache.directory=${java.io.tmpdir}/test-cache
spring.ai.embedding.transformer.onnx.model-uri=classpath:/test-models/model.onnx

# ========================================
# application-prod.properties
# ========================================
spring.ai.embedding.transformer.onnx.gpu-device-id=${GPU_DEVICE_ID:0}
spring.ai.embedding.transformer.cache.enabled=true
spring.ai.embedding.transformer.cache.directory=/var/cache/spring-ai-models
spring.ai.embedding.transformer.onnx.model-uri=${MODEL_URI:https://example.com/models/prod-model.onnx}

Kubernetes ConfigMap Example

apiVersion: v1
kind: ConfigMap
metadata:
  name: embedding-config
data:
  application.properties: |
    spring.ai.embedding.transformer.onnx.model-uri=https://models.example.com/model.onnx
    spring.ai.embedding.transformer.tokenizer.uri=https://models.example.com/tokenizer.json
    spring.ai.embedding.transformer.cache.enabled=true
    spring.ai.embedding.transformer.cache.directory=/cache
    spring.ai.embedding.transformer.onnx.gpu-device-id=0

Docker Environment Variables

# docker-compose.yml environment section
environment:
  - SPRING_AI_EMBEDDING_TRANSFORMER_ONNX_GPUDEVICEID=0
  - SPRING_AI_EMBEDDING_TRANSFORMER_CACHE_DIRECTORY=/cache
  - SPRING_AI_EMBEDDING_TRANSFORMER_CACHE_ENABLED=true
  - SPRING_AI_EMBEDDING_TRANSFORMER_ONNX_MODELURI=classpath:/models/model.onnx

Using Auto-Configuration

With Spring Boot auto-configuration, the TransformersEmbeddingModel bean is created automatically. Simply inject it into your components:

import org.springframework.ai.transformers.TransformersEmbeddingModel;
import org.springframework.stereotype.Service;

@Service
public class EmbeddingService {

    private final TransformersEmbeddingModel embeddingModel;

    // Constructor injection (recommended)
    public EmbeddingService(TransformersEmbeddingModel embeddingModel) {
        this.embeddingModel = embeddingModel;
    }

    public float[] generateEmbedding(String text) {
        // Model is already initialized by Spring Boot
        return embeddingModel.embed(text);
    }
}

Key Points:

No need to call afterPropertiesSet() - Spring Boot handles initialization
No need to create the bean manually - auto-configuration does it
Configuration is driven entirely by application properties
Bean is a singleton shared across the application

Verifying Configuration:

@Component
public class ConfigurationLogger implements CommandLineRunner {
    
    private final TransformersEmbeddingModel model;
    
    public ConfigurationLogger(TransformersEmbeddingModel model) {
        this.model = model;
    }
    
    @Override
    public void run(String... args) {
        System.out.println("Embedding dimensions: " + model.dimensions());
        // Verify model is configured correctly
    }
}

Conditional Configuration

Auto-configuration only activates when the TransformersEmbeddingModel class is on the classpath. To disable auto-configuration:

Disable via Properties

# Option 1: Exclude auto-configuration class
spring.autoconfigure.exclude=org.springframework.ai.model.transformers.autoconfigure.TransformersEmbeddingModelAutoConfiguration

# Option 2: Set property to different value
spring.ai.embedding.model=openai
# (any value other than "transformers" disables auto-configuration)

Disable via Java

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.ai.model.transformers.autoconfigure.TransformersEmbeddingModelAutoConfiguration;

@SpringBootApplication(exclude = {
    TransformersEmbeddingModelAutoConfiguration.class
})
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

Types

TransformersEmbeddingModelProperties

package org.springframework.ai.model.transformers.autoconfigure;

@ConfigurationProperties(TransformersEmbeddingModelProperties.CONFIG_PREFIX)
public class TransformersEmbeddingModelProperties {

    public static final String CONFIG_PREFIX = "spring.ai.embedding.transformer";

    public static final String DEFAULT_CACHE_DIRECTORY =
        new File(System.getProperty("java.io.tmpdir"), "spring-ai-onnx-generative")
            .getAbsolutePath();

    private final Tokenizer tokenizer = new Tokenizer();
    private final Cache cache = new Cache();
    private final Onnx onnx = new Onnx();
    private MetadataMode metadataMode = MetadataMode.NONE;

    public Cache getCache();
    public Onnx getOnnx();
    public Tokenizer getTokenizer();
    public MetadataMode getMetadataMode();
    public void setMetadataMode(MetadataMode metadataMode);
}

Tokenizer Properties

public static class Tokenizer {
    private String uri = TransformersEmbeddingModel.DEFAULT_ONNX_TOKENIZER_URI;
    private final Map<String, String> options = new HashMap<>();

    public String getUri();
    public void setUri(String uri);
    public Map<String, String> getOptions();
}

Cache Properties

public static class Cache {
    private boolean enabled = true;
    private String directory = DEFAULT_CACHE_DIRECTORY;

    public boolean isEnabled();
    public void setEnabled(boolean enabled);
    public String getDirectory();
    public void setDirectory(String directory);
}

Onnx Properties

public static class Onnx {
    private String modelUri = TransformersEmbeddingModel.DEFAULT_ONNX_MODEL_URI;
    private String modelOutputName = TransformersEmbeddingModel.DEFAULT_MODEL_OUTPUT_NAME;
    private int gpuDeviceId = -1;

    public String getModelUri();
    public void setModelUri(String modelUri);
    public int getGpuDeviceId();
    public void setGpuDeviceId(int gpuDeviceId);
    public String getModelOutputName();
    public void setModelOutputName(String modelOutputName);
}

ConfigurationProperties Annotation

/**
 * Annotation for binding external configuration to a bean.
 */
@ConfigurationProperties
public @interface ConfigurationProperties {
    /**
     * The prefix of the properties to bind.
     */
    String value() default "";
    
    /**
     * Same as value(), alternative syntax.
     */
    String prefix() default "";
}

Property Precedence

Configuration properties can be set in multiple ways with the following precedence (highest to lowest):

1. Command-line arguments (highest priority)
   --spring.ai.embedding.transformer.onnx.gpu-device-id=0

2. Java System properties
   -Dspring.ai.embedding.transformer.onnx.gpu-device-id=0

3. OS environment variables
   SPRING_AI_EMBEDDING_TRANSFORMER_ONNX_GPUDEVICEID=0

4. Profile-specific properties (application-{profile}.properties)
   application-prod.properties

5. application.properties in current directory
   ./application.properties

6. application.properties in classpath
   src/main/resources/application.properties

7. Default values in properties class (lowest priority)
   Default values defined in code

Example:

# Command-line overrides all
java -jar app.jar \
  --spring.ai.embedding.transformer.onnx.gpu-device-id=1 \
  --spring.profiles.active=prod

# Even if application-prod.properties has:
# spring.ai.embedding.transformer.onnx.gpu-device-id=0
# The command-line value (1) takes precedence

Environment Variable Naming:

# Properties use dot notation
spring.ai.embedding.transformer.onnx.gpu-device-id=0

# Environment variables use uppercase with underscores
SPRING_AI_EMBEDDING_TRANSFORMER_ONNX_GPUDEVICEID=0

# Conversion rules:
# - Replace dots (.) with underscores (_)
# - Convert to uppercase
# - Remove hyphens (-) and convert next letter to uppercase

Validation

Spring Boot validates configuration properties at startup:

Property Type Validation

# Invalid integer value
spring.ai.embedding.transformer.onnx.gpu-device-id=invalid
# Error: Failed to bind properties
# Reason: Failed to convert property value of type 'java.lang.String' to required type 'int'

Enum Validation

# Invalid enum value
spring.ai.embedding.transformer.metadata-mode=INVALID
# Error: Failed to bind properties
# Reason: No enum constant MetadataMode.INVALID

Required Properties

// No required properties - all have defaults
// Application starts even with no configuration

Custom Validation

@Configuration
@Validated
public class CustomValidationConfig {
    
    @Bean
    @ConditionalOnProperty("spring.ai.embedding.transformer.onnx.gpu-device-id")
    public void validateGpuId(@Value("${spring.ai.embedding.transformer.onnx.gpu-device-id}") int gpuId) {
        if (gpuId < -1) {
            throw new IllegalArgumentException("GPU device ID must be >= -1");
        }
        if (gpuId > 7) {
            // Assume max 8 GPUs
            throw new IllegalArgumentException("GPU device ID must be <= 7");
        }
    }
}

Common Validation Errors

# Invalid metadata mode (must be NONE, EMBED, or ALL)
spring.ai.embedding.transformer.metadata-mode=none
# Error: No enum constant MetadataMode.none (case-sensitive)

# Invalid GPU device ID format
spring.ai.embedding.transformer.onnx.gpu-device-id=gpu0
# Error: NumberFormatException

# Cache directory creation failure
spring.ai.embedding.transformer.cache.directory=/root/cache
# Error during initialization: Permission denied

# Model/tokenizer resource not found
spring.ai.embedding.transformer.onnx.model-uri=classpath:/nonexistent.onnx
# Error during initialization: Resource not found

Troubleshooting

Properties Not Taking Effect

Problem: Configuration changes don't apply

Solutions:

# 1. Verify property file is loaded
java -jar app.jar --spring.config.location=file:./application.properties

# 2. Check active profiles
java -jar app.jar --spring.profiles.active=prod

# 3. Enable debug logging
java -jar app.jar --debug --logging.level.org.springframework.boot=DEBUG

# 4. Verify property names (case-sensitive, exact match)
# Wrong:
spring.ai.embedding.transformer.onnx.gpuDeviceId=0
# Correct:
spring.ai.embedding.transformer.onnx.gpu-device-id=0

Property Precedence Issues

Problem: Unexpected property values

Solution: Check precedence chain

# List all properties with precedence
java -jar app.jar --debug 2>&1 | grep "spring.ai.embedding"

Environment Variable Issues

Problem: Environment variables not working

Solutions:

# Check environment variable is set
echo $SPRING_AI_EMBEDDING_TRANSFORMER_ONNX_GPUDEVICEID

# Verify naming conversion
# Property: spring.ai.embedding.transformer.onnx.gpu-device-id
# Env var:  SPRING_AI_EMBEDDING_TRANSFORMER_ONNX_GPUDEVICEID
#           (no hyphen, uppercase, underscores)

# Set environment variable correctly
export SPRING_AI_EMBEDDING_TRANSFORMER_ONNX_GPUDEVICEID=0

Profile-Specific Configuration Not Loading

Problem: Profile-specific properties ignored

Solutions:

# Activate profile explicitly
java -jar app.jar --spring.profiles.active=prod

# Check profile-specific file exists
# application-prod.properties (in classpath or current directory)

# Verify file naming
# Correct: application-prod.properties
# Wrong: application.prod.properties

Startup Failures

Problem: Application fails to start after configuration change

Solutions:

# 1. Revert to defaults
# Remove all custom properties and test

# 2. Enable debug mode
debug=true
logging.level.org.springframework.boot.autoconfigure=DEBUG

# 3. Check specific error messages
# Model loading errors
spring.ai.embedding.transformer.onnx.model-uri=classpath:/models/model.onnx

# GPU initialization errors
spring.ai.embedding.transformer.onnx.gpu-device-id=-1  # Fallback to CPU

# Cache directory errors
spring.ai.embedding.transformer.cache.directory=${user.home}/.spring-ai/cache

Best Practices

1. Externalize Configuration

# Use environment variables for deployment-specific values
spring.ai.embedding.transformer.onnx.gpu-device-id=${GPU_DEVICE_ID:0}
spring.ai.embedding.transformer.cache.directory=${CACHE_DIR:/var/cache}

2. Use Profiles for Environments

# Base configuration: application.properties
spring.ai.embedding.transformer.cache.enabled=true

# Dev: application-dev.properties
spring.ai.embedding.transformer.onnx.gpu-device-id=-1
spring.ai.embedding.transformer.cache.directory=./cache

# Prod: application-prod.properties
spring.ai.embedding.transformer.onnx.gpu-device-id=0
spring.ai.embedding.transformer.cache.directory=/var/cache/models

3. Document Custom Properties

# ========================================
# Embedding Model Configuration
# ========================================
# GPU Device: 0 = first GPU, -1 = CPU
spring.ai.embedding.transformer.onnx.gpu-device-id=0

# Cache Location: Persistent storage for production
spring.ai.embedding.transformer.cache.directory=/var/cache/spring-ai

4. Validate Configuration

@Component
public class ConfigurationValidator implements CommandLineRunner {
    
    @Value("${spring.ai.embedding.transformer.onnx.gpu-device-id}")
    private int gpuDeviceId;
    
    @Value("${spring.ai.embedding.transformer.cache.directory}")
    private String cacheDir;
    
    @Override
    public void run(String... args) {
        // Log configuration
        System.out.println("GPU Device ID: " + gpuDeviceId);
        System.out.println("Cache Directory: " + cacheDir);
        
        // Validate cache directory exists and is writable
        File cacheDirFile = new File(cacheDir);
        if (!cacheDirFile.exists() || !cacheDirFile.canWrite()) {
            throw new IllegalStateException("Cache directory not writable: " + cacheDir);
        }
    }
}

5. Use Configuration Processor

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-configuration-processor</artifactId>
    <optional>true</optional>
</dependency>

Benefit: IDE autocomplete for property names

tessl i tessl/maven-org-springframework-ai--spring-ai-transformers@1.1.1

docs

examples

guides

reference

auto-configuration.md

embedding-generation.md

model-configuration.md

resource-caching.md

spring-boot-configuration.md

index.md

tile.json

tessl/maven-org-springframework-ai--spring-ai-transformers