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
Bedrock (available from 17.3.0)

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.

Info: Under Spring AI 2.0, the OpenAI base URL must include the /v1 path segment (for example https://api.openai.com/v1). If you set spring.ai.openai.api.url explicitly, make sure it ends in /v1.

Property	Required	Type	Description	Default	Example
`spring.ai.openai.api.url`	yes	url	OpenAI endpoint. Must include the `/v1` path segment.		`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), range `0`–`2`. Only sent to OpenAI when explicitly configured with a valid value. From 17.3.0 it is no longer forced to `0.0` when unset, so leaving it empty yields the model's own default (non-deterministic output). Set it explicitly for deterministic results on classic models. Leave empty for reasoning models (`gpt-5` and later), which reject an explicit temperature.	(omitted — model default)	`0.1`
`spring.ai.openai.chat.options.max-completion-tokens`	no	integer	Maximum number of tokens generated per response. Preferred over `max-tokens` and required by reasoning models (`gpt-5` and later). Always sent to OpenAI as `max_completion_tokens`. Falls back to the `max-tokens` value when unset. (available from 17.3.0)	`4096`	`15000`
`spring.ai.openai.chat.options.max-tokens`	no	integer	Legacy. Superseded by `max-completion-tokens`. When set (and `max-completion-tokens` is unset) its value is still transmitted, but always as `max_completion_tokens`.	`4096`	`15000`
`spring.ai.openai.chat.options.reasoning-effort`	no	string	Reasoning models only. Only sent when configured. Accepted values are model-specific (`low`/`medium`/`high` are common; some models also accept `none`, `minimal`, or `xhigh`). Must be set (for example `none` where supported) for the assistant's tool calling to work on reasoning models. Classic models (`gpt-4.x`) reject this parameter — leave it empty. (available from 17.3.0)		`medium`
`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`

Info: OpenAI reasoning models (gpt-5 and later). When configuring a reasoning model:

Leave spring.ai.openai.chat.options.temperature empty — reasoning models reject an explicit temperature.

Set spring.ai.openai.chat.options.max-completion-tokens (reasoning tokens count toward this limit, so allow enough headroom).

Set spring.ai.openai.chat.options.reasoning-effort to a value supported by your model. It must be set (for example none) for the assistant's tool calling — including the Search Agent — to work.

Ensure spring.ai.openai.api.url includes the /v1 path segment.

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`

AWS Bedrock

Info: AWS Bedrock support is available from 17.3.0. It ships in the incubating content-ai-service-impl-incubating artifact — no additional dependency is required. Set brxm.ai.provider=Bedrock to activate it. Bedrock is configured through properties files or the JCR console only; it is not available in the Essentials configuration wizard.

Chat uses Bedrock's model-agnostic Converse API, so any Converse-capable model (Claude, Amazon Nova, Llama, OpenAI gpt-oss, and others) can be used. Embeddings use Amazon Titan or Cohere, selected automatically from the embedding model id prefix (amazon.titan-embed or cohere.embed).

Info: Authentication. Credentials are resolved through the standard AWS credential chain. You can, in order of convenience:

Provide a Bedrock API key / bearer token via the AWS_BEARER_TOKEN_BEDROCK environment variable (honored by the default AWS credential chain), or

Set static credentials with the spring.ai.bedrock.aws.access-key / .secret-key (and optional .session-token) properties, or

Rely on an IAM role or any other source in the default AWS credential provider chain.

The AWS region is always required. The identity you authenticate as needs the bedrock:Converse, bedrock:ConverseStream, and bedrock:InvokeModel* IAM actions, and the target models must be enabled for your account in the Bedrock console (Model access).

Property	Required	Type	Description	Default	Example
`spring.ai.bedrock.aws.region`	yes	string	AWS region hosting your Bedrock models.		`us-east-1`
`spring.ai.bedrock.aws.access-key`	no	string	AWS access key. Omit to use the default AWS credential chain (including `AWS_BEARER_TOKEN_BEDROCK`).
`spring.ai.bedrock.aws.secret-key`	no	string	AWS secret key. Required if `access-key` is set.
`spring.ai.bedrock.aws.session-token`	no	string	AWS session token for temporary credentials.
`spring.ai.bedrock.converse.chat.options.model`	yes	model id	Bedrock model id (or inference-profile id) for a Converse-capable model. See the model-id note below.		`us.anthropic.claude-sonnet-4-5-20250929-v1:0`
`spring.ai.bedrock.converse.chat.options.temperature`	no	double	Model temperature (controls response randomness). Opt-in — only sent when configured. Some models (for example Claude Sonnet-class) reject an explicit temperature; omit it for those.		`0.1`
`spring.ai.bedrock.converse.chat.options.max-tokens`	no	integer	Maximum number of tokens generated per response.	`4096`	`15000`
`spring.ai.bedrock.embedding.options.model`	no	model id	Embedding model id. Titan (`amazon.titan-embed…`) or Cohere (`cohere.embed…`) is selected automatically from the id prefix. Leave unset for a chat-only setup (no Vector Store / Ingestion).		`amazon.titan-embed-text-v2:0`

Info: Choosing models.

Model ids. Newer Anthropic Claude models require a cross-region inference-profile prefix — for example us.anthropic.claude-… or global.anthropic.claude-…. Direct model ids work for models such as gpt-oss. Gateway-style ids (for example bedrock_mantle/… or openai/…) are not supported. Pick a tool-capable model so the Search Agent and other assistant tools work.

Embeddings. Amazon Titan Text Embeddings v2 and Cohere Embed v3 both produce 1024-dimension vectors. The dimensions value of your vector store (for example brxm.ai.vectorstore.pgvector.dimensions) must match the dimension of the embedding model you select.

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.