Initialize and Configure the AI Content Assistant Using Properties Files

This page describes how to set up and configure the AI Content Assistant using properties files in your project.

Info: The AI Content Assistant is available only to users assigned the xm.chatbot.user role.

Info: If you are upgrading to version 16.6 or 16.8, review the AI Module upgrade instructions.

Installation

Add the following dependencies to your project's cms-dependencies POM file:

<dependency>
    <groupId>com.bloomreach.xm.ai</groupId>
    <artifactId>content-ai-service-impl-incubating</artifactId>
</dependency>

<dependency>
    <groupId>com.bloomreach.xm.ai</groupId>
    <artifactId>content-ai-service-rest-incubating</artifactId>
</dependency>

<dependency>
    <groupId>com.bloomreach.xm.ai</groupId>
    <artifactId>content-ai-service-client-bootstrap</artifactId>
</dependency>

<dependency>
    <groupId>com.bloomreach.xm.ai</groupId>
    <artifactId>content-ai-service-client-assistant-angular</artifactId>
</dependency>

Configure Using Properties Files

Configure the Content Assistant for production by specifying properties in one or more of the following locations. Properties are resolved in order of precedence (highest to lowest):

System properties set on the command line
A properties file named xm-ai-service.properties available on the classpath
The project's platform.properties file

Info: For more details on managing properties files and system properties:

For Bloomreach Cloud, see Set Environment Configuration Properties

For On-premise, see HST-2 Container Configuration

Multiple Configurations

You can define configuration for multiple model providers and vector stores in properties files. Only one provider can be active at a time.

Global Configuration Options

Set the active model provider using the brxm.ai.provider property. Supported values:

OpenAI
GoogleGenAiVertex
Ollama
LiteLLM

Info: If you set brxm.ai.provider to an empty value, all AI backend services are disabled, including the Vector Store and Ingestion process.

Additional global properties:

brxm.ai.chat.max-messages: Sets the maximum number of messages per conversation. Accepts an integer. Default is 100.
brxm.ai.chat.pdf.max-size-bytes: Sets the maximum allowed PDF size (in bytes) for reference in a conversation. Accepts an integer. Default is 1MB (1048576 bytes).
brxm.ai.tools.search.max-results: Sets the maximum number of search results returned by the assistant. Accepts an integer between 1 and 20. Default is 5. Values outside this range or non-numeric values are logged as errors and disable search functionality in the assistant.

Model Provider Configuration

Configure provider-specific properties as required for your selected model provider. Only one embedding model can be registered. If no embedding model is configured, the Vector Store and Ingestion process will not initialize.

OpenAI

Info: You need an OpenAI API key to use ChatGPT models. Register at the OpenAI signup page and generate an API key on the API Keys page.

Property	Required	Type	Description	Default	Example
`spring.ai.openai.api.url`	yes	url	OpenAI endpoint		`https://api.openai.com/v1`
`spring.ai.openai.api_key`	yes	string	OpenAI API key
`spring.ai.openai.chat.options.model`	yes	model name	OpenAI-supported model. See models		`gpt-4o`
`spring.ai.openai.chat.options.temperature`	no	double	Model temperature (controls response randomness). Lower values recommended.	`0.0`	`0.1`
`spring.ai.openai.chat.options.maxTokens`	no	integer	Maximum tokens per conversation	`4096`	`15000`
`spring.ai.openai.embedding.options.model`	no	model name	OpenAI embeddings model	Latest OpenAI embeddings model	`text-embedding-3-large`
`spring.ai.openai.embedding.options.dimensions`	no	integer	Output embedding dimensions (supported in text-embedding-3 and later)	Depends on model (e.g., `3072` for `text-embedding-3-large`)	`1024`
`spring.ai.openai.embedding.options.encoding-format`	no	string	Embedding format: `float` or `base64`	`float`	`base64`

GoogleGenAiVertex

Info: To authenticate with VertexAI, configure Application Default Credentials (ADC) using the ADC setup guide.

Property	Required	Type	Description	Default	Example
`spring.ai.google.genai.project-id`	yes	string	Google Cloud Platform project ID		`myprojectid`
`spring.ai.google.genai.location`	yes	string	Google Cloud Platform region		`mylocation`
`spring.ai.google.genai.chat.model`	yes	model name	Google GenAI Chat model		`gemini-3.5-flash`
`spring.ai.google.genai.chat.temperature`	no	double	Model temperature (controls response randomness). Lower values recommended.	`0.0`	`0.3`
`spring.ai.google.genai.chat.max-output-tokens`	no	integer	Maximum tokens per conversation	`4096`	`15000`
`spring.ai.vertex.ai.embedding.project-id`	no	string	Google Cloud Platform project ID		`myprojectid`
`spring.ai.vertex.ai.embedding.location`	no	string	Google Cloud Platform region		`mylocation`
`spring.ai.vertex.ai.embedding.text.options.model`	no	model name	Google GenAI Text Embedding model		`text-embedding-004`
`spring.ai.vertex.ai.embedding.text.options.dimensions`	no	integer	Output embedding dimensions (supported for model version 004 and later)	Depends on model	`1024`
`spring.ai.vertex.ai.embedding.text.options.auto-truncate`	no	boolean	Truncate input text if set to true	`true`	`false`

Ollama

Info: Ollama can be downloaded and run locally.

Ollama does not currently support tool calling (last tested with gemma3).

Property	Required	Type	Description	Default	Example
`spring.ai.ollama.api.url`	yes	url	Ollama endpoint		`https://myollama/`
`spring.ai.ollama.chat.options.model`	yes	model name	Ollama model. See supported models		`gemma3`
`spring.ai.ollama.chat.options.model.pull.strategy`	yes	enum	Model pull strategy at startup		`WHEN_MISSING`
`spring.ai.ollama.embedding.options.model`	no	model name	Supported embedding model		`nomic-embed-text`
`spring.ai.ollama.embedding.options.truncate`	no	boolean	Truncate input to fit context length	`true`	`false`

LiteLLM

Info: LiteLLM is a model gateway. You can install it locally or use a managed service.

Property	Required	Type	Description	Default	Example
`spring.ai.litellm.api.url`	yes	url	LiteLLM endpoint		`https://mylitellm/`
`spring.ai.litellm.api_key`	yes	string	LiteLLM API key
`spring.ai.litellm.chat.options.model`	yes	model name	Enabled model name in LiteLLM		`openai/gpt-4o`
`spring.ai.litellm.chat.options.temperature`	no	double	Model temperature (controls response randomness). Lower values recommended.	`0.0`	`0.1`
`spring.ai.litellm.chat.options.max-tokens`	no	integer	Maximum tokens per conversation	`4096`	`15000`
`spring.ai.litellm.embedding.options.model`	no	model name	Enabled embeddings model in LiteLLM	Latest provider embeddings model	`openai/text-embedding-3-large`
`spring.ai.litellm.embedding.options.dimensions`	no	integer	Output embedding dimensions	Depends on model	`1024`
`spring.litellm.openai.embedding.options.encoding-format`	no	string	Embedding format: `float` or `base64`	`float`	`base64`

Vector Store and Ingestion Configuration

For details on configuring the Vector Store and Ingestion, see Initialize and configure the Vector Store and Ingestion.

Maintenance Scripts

The AI module provides Groovy scripts for maintaining your Vector Store. For more information, see Maintenance Groovy Scripts.