DIAL RAG configuration

DIAL RAG takes its settings from environment variables, a YAML profile, and each request. This page covers how they combine, the bundled profiles, registration in DIAL Core, and a Helm example. It is for platform engineers who deploy DIAL RAG and assumes you know Applications in DIAL Core. Everything here is checked against DIAL RAG 0.43.0.

Where each setting lives

Place	What it sets	Reference
Environment variables	The DIAL Core URL, index storage, CPU pools, logging, and the defaults of every request setting	Environment variables
YAML profile	The same settings as the environment variables, read from the file in `DIAL_RAG__CONFIG_PATH`	Profiles
`custom_fields.configuration` of a request	Request settings for that request only	Configuration
Commands in a user message	A few request settings for that request	Commands
DIAL Core configuration	The application entry that routes requests to DIAL RAG	Register DIAL RAG in DIAL Core

How settings combine

At startup, environment variables override the YAML profile, and the profile overrides the built-in defaults. For each request, DIAL RAG then merges, in this order:

The service settings from the environment variables, the profile, and the defaults.
The request's custom_fields.configuration, validated against the configuration schema. An unknown field fails the request with 400.
The settings from commands in the conversation's user messages.

A later source replaces a value and merges into an object. A request that changes the chunk size, the multimodal embeddings model, or the image retrievers in use gets its documents re-indexed. See Index storage.

Nested variables

A setting's variable is DIAL_RAG__ followed by the setting's path, with __ between the levels. Names aren't case-sensitive. DIAL_URL, ENABLE_DEBUG_COMMANDS, and the logging variables have no prefix.

# One field of the chat model's settings
DIAL_RAG__REQUEST__QA_CHAIN__CHAT_CHAIN__LLM__DEPLOYMENT_NAME=gpt-4.1-2025-04-14

# A whole object as JSON
DIAL_RAG__REQUEST__INDEXING__DESCRIPTION_INDEX='{"llm": {"deployment_name": "gpt-4.1-mini-2025-04-14"}, "estimated_task_tokens": 4000}'

# Turn off the description index
DIAL_RAG__REQUEST__INDEXING__DESCRIPTION_INDEX=null

Setting one field of an unset object turns the object on with its defaults for the other fields. For example, DIAL_RAG__REQUEST__INDEXING__MULTIMODAL_INDEX__EMBEDDINGS_MODEL alone turns on the multimodal index.

Profiles

The image holds eight YAML profiles in /config and loads /config/azure_description.yaml by default. Each turns on one image retriever, or none, and sets the models. To use another profile, set DIAL_RAG__CONFIG_PATH. To change one model, keep the profile and override the model's variable.

Profile	Image retriever	Image model	Answer and query model
`aws_description.yaml`	Page image search	`anthropic.claude-haiku-4-5-20251001-v1:0`	`anthropic.claude-v3-5-sonnet-v2`
`aws_embedding.yaml`	Multimodal search	`amazon.titan-embed-image-v1`	`anthropic.claude-v3-5-sonnet-v2`
`azure_description.yaml`	Page image search	`gpt-4.1-mini-2025-04-14`	`gpt-4.1-2025-04-14`
`azure_embedding.yaml`	Multimodal search	`azure-ai-vision-embeddings`	`gpt-4.1-2025-04-14`
`azure_with_gcp_embedding.yaml`	Multimodal search	`multimodalembedding@001`	`gpt-4.1-2025-04-14`
`gcp_description.yaml`	Page image search	`gemini-2.5-flash`	`gemini-2.5-pro`
`gcp_embedding.yaml`	Multimodal search	`multimodalembedding@001`	`gemini-2.5-pro`
`text_only.yaml`	None	—	`gpt-4.1-2025-04-14`, with no page images passed to it

The names are deployment names in DIAL Core. Use a profile only when your DIAL Core has deployments with these names, or override the names.

A profile can set any setting, not only the request settings. A custom profile is a YAML file in the same shape:

request:
  indexing:
    multimodal_index: null
    description_index:
      llm:
        deployment_name: gpt-4.1-mini-2025-04-14
  qa_chain:
    chat_chain:
      llm:
        deployment_name: gpt-4.1-2025-04-14
        max_prompt_tokens: 16000
    query_chain:
      llm:
        deployment_name: gpt-4.1-2025-04-14
        max_prompt_tokens: 8000

Register DIAL RAG in DIAL Core

Add DIAL RAG to applications in the DIAL Core configuration. In the example, <DIAL_RAG_URL> is its URL inside your network, such as http://dial-rag:5000.

{
  "applications": {
    "dial-rag": {
      "displayName": "DIAL RAG",
      "description": "Answers questions about the attached documents",
      "endpoint": "<DIAL_RAG_URL>/openai/deployments/dial-rag/chat/completions",
      "inputAttachmentTypes": ["*/*"],
      "maxInputAttachments": 10,
      "features": {
        "configurationEndpoint": "<DIAL_RAG_URL>/openai/deployments/dial-rag/configuration"
      }
    }
  }
}

Field	What it does for DIAL RAG
`endpoint`	The path segment `dial-rag` is fixed in DIAL RAG. The application's own name in DIAL Core can differ.
`inputAttachmentTypes`	Without it, users can't attach documents. `/` lets DIAL RAG reject the formats it can't read.
`maxInputAttachments`	Optional. The upstream example allows 10 attachments.
`features.configurationEndpoint`	Optional. Lets clients read the configuration schema at `GET /v1/deployments/dial-rag/configuration`.

DIAL RAG calls models, file storage, and the limits API with the caller's per-request key. Give the callers' roles access and token limits for the models DIAL RAG uses; see Roles.

Store indexes in DIAL file storage

The image keeps indexes only in memory by default. The upstream README lists DIAL_RAG__INDEX_STORAGE__USE_DIAL_FILE_STORAGE=True as required for a deployment. With it, indexes survive restarts and replicas share them.

DIAL RAG then writes indexes to its own bucket in DIAL file storage. Plan storage for them: each index holds the document's text chunks, embeddings, and the converted document itself.

Example: Helm values

DIAL RAG isn't part of the dial chart. Deploy it with the dial-extension chart 3.1.1, whose default container port is 5000:

image:
  repository: epam/ai-dial-rag
  tag: 0.43.0
env:
  DIAL_URL: <DIAL_CORE_URL>
  DIAL_RAG__CONFIG_PATH: /config/azure_description.yaml
  DIAL_RAG__INDEX_STORAGE__USE_DIAL_FILE_STORAGE: "true"
livenessProbe:
  enabled: true
readinessProbe:
  enabled: true

helm install dial-rag dial/dial-extension --version 3.1.1 -f values.yaml --namespace dial

The chart's probes call /health, which DIAL RAG serves. The chart's Service listens on port 80 by default (service.ports.http). Use the Service's URL as <DIAL_RAG_URL> in the registration.

Troubleshooting

Symptom	What to check
"Invalid configuration: ..." with `400`	The request's `custom_fields.configuration` against the configuration schema
"Unable to load document content. Try another document format."	The document's format; see Documents
"Document text is too large: ..."	The document's extracted text is over `max_document_text_size`, 5 MiB by default.
"The document is empty"	The document produced no text and has no pages to read as images.
"Not enough tokens day token limit for the ..."	The caller's daily token limit for the image model. Indexing reserves its estimated tokens first.
"Rate limit exceeded." with `429`	The caller's minute token limit for a model
"Index is missing.", "Index settings mismatch: ...", or "Document was modified"	The request sets `allow_indexing` to `false`, and no usable index exists. See Indexing errors.
"Index URL ... does not match the expected index path ..."	An index attachment points into the DIAL RAG bucket at a path DIAL RAG doesn't manage. See Index attachments.
An HTTP status and reason in the "Access document" stage	The caller can't read the document in DIAL file storage.

Where each setting lives​

How settings combine​

Nested variables​

Profiles​

Register DIAL RAG in DIAL Core​

Store indexes in DIAL file storage​

Example: Helm values​

Troubleshooting​