DIAL Generic RAG configuration

Generic RAG is configured in its two services, in the application type registered in DIAL Core, and in the properties of each application. This page covers the prerequisites, registration, background jobs, security, and a Helm example. It is for platform engineers who deploy Generic RAG and assumes you know Application type schemas. Everything here is checked against backend 0.3.3 and frontend 0.1.0.

Where each setting lives

Place	What it sets	Reference
Environment variables of the backend	DIAL Core, PostgreSQL, Elasticsearch, the file cache, the job key, chat responses, and logs	Backend
Environment variables of the frontend	DIAL Core, embedding in DIAL Admin, and sign-in	Frontend
Application type in DIAL Core	The backend's endpoints, the channel API route, MCP, and the editor URL	Register the application type
Properties of each application	The pipeline: metadata, parsers, indexes, retriever, and generator	Channel configuration
Models in DIAL Core	The backend's built-in embeddings, when you use them	Register the built-in embeddings

Prerequisites

DIAL Core 0.44.0 or later, as the upstream README requires
PostgreSQL with the vector extension. The backend doesn't create the extension. Run create extension if not exists vector; in its database, as the upstream Docker Compose setup does. The backend applies its own table migrations at startup.
Elasticsearch, optional. Only for indexes whose storage backend is elastic
An API key for background jobs, recommended. See Background jobs.

Register the application type

Deploy the backend. See the Helm example. In the steps below, <GENERIC_RAG_URL> is its URL inside your network, such as http://generic-rag-backend. <FRONTEND_URL> is the frontend's URL that users' browsers open.

Register the type in DIAL Core. Add it to applicationTypeSchemas in the DIAL Core configuration:

{
  "applicationTypeSchemas": [
    {
      "$schema": "https://dial.epam.com/application_type_schemas/schema#",
      "$id": "https://dial.epam.com/application_type_schemas/generic-rag",
      "dial:applicationTypeCompletionEndpoint": "<GENERIC_RAG_URL>/openai/deployments/generic-rag/chat/completions",
      "dial:applicationTypeConfigurationEndpoint": "<GENERIC_RAG_URL>/openai/deployments/generic-rag/configuration",
      "dial:applicationTypeSchemaEndpoint": "<GENERIC_RAG_URL>/application-type-schema",
      "dial:applicationTypeDisplayName": "Generic RAG",
      "dial:applicationTypeEditorUrl": "<FRONTEND_URL>",
      "dial:applicationTypeRoutes": {
        "channel": {
          "dial:paths": ["/channel(/[^/]+)*$"],
          "dial:rewritePath": true,
          "dial:methods": ["GET", "POST", "PUT", "DELETE"],
          "dial:upstreams": [{"dial:endpoint": "<GENERIC_RAG_URL>"}]
        }
      },
      "dial:applicationTypeMcp": {
        "dial:endpoint": "<GENERIC_RAG_URL>/mcp/streamable-http",
        "dial:transport": "HTTP",
        "dial:mcpConfigDelivery": "HEADER",
        "dial:forwardPerRequestKey": true
      },
      "dial:appendApplicationPropertiesHeader": false
    }
  ]
}

To register it in DIAL Admin instead, create an Application Runner with the same endpoints, and add the route in its App Routes.

Check the result. GET /v1/application_type_schemas/schemas on DIAL Core lists the type, with the channel properties from the backend.

Property	What it does for Generic RAG
`$id`	The type's ID. Applications refer to it as `applicationTypeSchemaId`.
`dial:applicationTypeCompletionEndpoint`	Chat completions. The path segment `generic-rag` is fixed in the backend.
`dial:applicationTypeConfigurationEndpoint`	The JSON schema of the per-request options of an application
`dial:applicationTypeSchemaEndpoint`	DIAL Core downloads the channel configuration schema from it.
`dial:applicationTypeEditorUrl`	The frontend. DIAL Admin opens it in an application's Parameters tab. Leave it out if you don't deploy the frontend.
`dial:applicationTypeRoutes`	The channel API route. `dial:rewritePath` makes the backend receive `/channel/...`.
`dial:applicationTypeMcp`	The MCP server. `dial:forwardPerRequestKey` must be `true`. The backend reads the properties from DIAL Core itself, so `dial:mcpConfigDelivery` has no effect on it.
`dial:appendApplicationPropertiesHeader`	`false`. The backend doesn't read properties from headers.

Then create applications of the type. See Build a document Q&A app with Generic RAG.

Register the built-in embeddings

The backend serves the epam/bge-small-en model as an embeddings deployment. To use it in a text_embeddings indexer, register it in DIAL Core's models and give your roles access to it:

{
  "models": {
    "generic-rag-embeddings": {
      "type": "embedding",
      "endpoint": "<GENERIC_RAG_URL>/openai/deployments/generic-rag-embeddings/embeddings"
    }
  }
}

An indexer then names it with "deployment_name": "generic-rag-embeddings". The model runs on the backend's CPU and reports no token usage.

Background jobs

Background jobs let uploads return before indexing ends, and they're the only way to build and import channel archives. They need DIAL_API_KEY, a DIAL Core API key.

How a job runs. The backend queues jobs in PostgreSQL, and every backend process runs a worker. The worker calls the application's channel API through DIAL Core with DIAL_API_KEY, so the work runs with a per-request key of that API key.
Which applications. A job is used only for applications whose channel API the key can call. The backend checks this with GET /channel/config and caches the answer for an hour per application. Other applications index during the upload request.
Models and limits. Background indexing calls models as the API key, so its role needs access to the models that the indexes use, and its limits apply.
Concurrency and retries. A worker runs up to 2 reindex jobs at a time, and one archive job of each kind. A failed job runs again, up to 3 attempts in all.
Duplicates. A second reindex of a document while one is queued fails with "Similar job was already created, please wait until it completes or cancel it."

The job dashboard at /dashboard on the backend shows the queue and can cancel and requeue jobs.

Secure the backend

Only DIAL Core should reach it. The backend takes the application ID from the X-DIAL-APPLICATION-ID header that DIAL Core sets. It has no check of its own on which client sends it.
Unauthenticated pages. /dashboard, /docs, /openapi/channel, /application-type-schema, and /health need no credentials. DIAL Core routes none of them to users.
Restrict it with network policy. Let only DIAL Core, and the backend itself through DIAL Core, call it.

The frontend's protection is its sign-in and ALLOWED_FRAME_ANCESTORS; see Frontend.

Example: Helm values

Neither service is part of the dial chart. Deploy each with the dial-extension chart 3.1.1. The backend listens on the chart's default container port, 5000:

image:
  repository: epam/ai-dial-generic-rag-backend
  tag: 0.3.3
env:
  DIAL_URL: <DIAL_CORE_URL>
  DB_HOST: <POSTGRES_HOST>
  DB_NAME: <POSTGRES_DATABASE>
  DB_USERNAME: <POSTGRES_USER>
secrets:
  DB_PASSWORD: <POSTGRES_PASSWORD>
  DIAL_API_KEY: <DIAL_API_KEY>
livenessProbe:
  enabled: true
readinessProbe:
  enabled: true

The frontend listens on port 3000 and has no health endpoint, so the example leaves the probes off. Users' browsers load it, so expose it, for example with the chart's ingress:

image:
  repository: epam/ai-dial-generic-rag-frontend
  tag: 0.1.0
containerPorts:
  http: 3000
env:
  DIAL_API_URL: <DIAL_CORE_URL>
  ALLOWED_FRAME_ANCESTORS: <DIAL_ADMIN_URL>
  NEXTAUTH_URL: <FRONTEND_URL>
  AUTH_KEYCLOAK_CLIENT_ID: <CLIENT_ID>
  AUTH_KEYCLOAK_HOST: <KEYCLOAK_URL>
  AUTH_KEYCLOAK_REALM: <REALM>
secrets:
  NEXTAUTH_SECRET: <NEXTAUTH_SECRET>
  AUTH_KEYCLOAK_SECRET: <CLIENT_SECRET>
ingress:
  enabled: true

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

Each chart's Service listens on port 80 by default (service.ports.http). Use the backend Service's URL as <GENERIC_RAG_URL>. Configure the frontend's ingress for your cluster.

Troubleshooting

Symptom	What to check
The backend exits at startup and logs a validation error	The backend variables. For example, "either 'password' or 'msi_enabled' should be set" means neither `DB_PASSWORD` nor `DB_MSI_ENABLED` is set.
The backend exits at startup after it logs "Connecting to Elasticsearch at: ..."	`ELASTICSEARCH_URL` and the credentials. Unset the URL if you don't use Elasticsearch.
"Application ID is not set" with `403`	The request didn't come through DIAL Core.
"Application properties not found"	The application has no properties.
"... unsupported file type (supported: ...)"	The channel's parsers
"Operation will overwrite existing file, which is not allowed."	A document with this name is in the folder. Upload with `overwrite=true`.
"Value of metadata violates JSON schema: ..."	The metadata against the channel's `metadata_schema`
"Unable to process request configuration"	The request's `custom_fields.configuration`. The Request configuration debug stage shows the error.
"Could not create channel archive."	Background jobs for this application
"Similar job was already created, ..."	Wait for the queued job, or cancel it in the dashboard.
"... field name is not known or its use for sorting is not supported ..."	The `sort` field. Only document fields and filterable string or date metadata fields sort.
"The archive is not compatible with the channel."	The archive's `metadata_schema`, `parsers`, or `indexes` differ from the channel's.

Where each setting lives​

Prerequisites​

Register the application type​

Register the built-in embeddings​

Background jobs​

Secure the backend​

Example: Helm values​

Troubleshooting​