Skip to main content

Configure and assign interceptors

After building an interceptor with the Interceptors SDK, you need to register it in DIAL Core and assign it to the deployments where it should run. This guide walks through declaration, scoping, and verification.

Prerequisites​

  • A running interceptor service with at least one endpoint (e.g., http://interceptor-service:5000/openai/deployments/my-interceptor/chat/completions)
  • Access to DIAL Core configuration (dynamic settings) or DIAL Admin

Configuration file locations​

All interceptor configuration lives in DIAL Core's dynamic settings. The exact file depends on your deployment:

Deployment methodConfiguration fileNotes
Docker Composeconfig.json mounted into the Core containerPath set via aidial.config.files env var
Kubernetes / Helmvalues.yaml under core.configRendered into a ConfigMap
DIAL Admin UIManaged via APINo file editing needed

For Docker Compose setups, the config file is typically mounted at /opt/config/config.json inside the container:

volumes:
  - ./config.json:/opt/config/config.json

Step 1: Declare the interceptor​

Add the interceptor to the interceptors section in DIAL Core's config.json. Each interceptor needs a unique key and an endpoint pointing to the interceptor service.

{
  "interceptors": {
    "pii-redactor": {
      "endpoint": "http://interceptor-service:5000/openai/deployments/pii-anonymizer/chat/completions",
      "displayName": "PII Redaction",
      "description": "Anonymizes personally identifiable information in requests and responses"
    }
  }
}
AttributeRequiredDescription
endpointYesFull URL to the interceptor's chat completion or embeddings endpoint
displayNameNoHuman-readable name shown in DIAL Admin
descriptionNoInterceptor purpose description

The endpoint URL follows the standard DIAL endpoint pattern. It must match the deployment name used when registering the interceptor in the DIALApp:

http://<HOST>:<PORT>/openai/deployments/<DEPLOYMENT_NAME>/chat/completions

For example, if app.py registers the interceptor as app.add_chat_completion("pii-anonymizer", ...), the endpoint is:

http://interceptor-service:5000/openai/deployments/pii-anonymizer/chat/completions

Warning

Chat completion interceptors must only be assigned to chat completion deployments. Embeddings interceptors must only be assigned to embeddings deployments. Mixing them causes runtime errors.

Step 2: Choose the scope​

Assign the declared interceptor at the appropriate level. You can combine levels — when all three are configured, the execution order is Global → Application type → Local.

Local scope​

Apply to a specific model or application. Add the interceptor key to the deployment's interceptors array.

{
  "models": {
    "gpt-4o": {
      "endpoint": "http://model-provider:5000/compat/openai/openai/deployments/gpt-4o/chat/completions",
      "interceptors": ["pii-redactor"]
    }
  }
}

Global scope​

Apply to every deployment in the DIAL instance. Add the interceptor key to the top-level globalInterceptors array.

{
  "globalInterceptors": ["pii-redactor"]
}

Application type scope​

Apply to all instances of a specific application type (e.g., all Quick Apps). Add the interceptor key to dial:applicationTypeInterceptors in the type schema.

{
  "applicationTypeSchemas": [
    {
      "$id": "https://dial.epam.com/application_types/quick_app/v1",
      "dial:applicationTypeDisplayName": "Quick App",
      "dial:applicationTypeInterceptors": ["pii-redactor"]
    }
  ]
}

Step 3: Verify the interceptor is active​

Send a chat completion request to a deployment that has the interceptor assigned. Confirm the interceptor is processing requests by checking:

  • Interceptor logs — the interceptor service should log incoming requests at DEBUG level.
  • Response behavior — for observable interceptors (e.g., PII redaction, content filtering), verify the response reflects the interceptor's transformation.
  • DIAL Admin — open the model or application and check its Interceptors grid. See Models › Interceptors.

Optional: Interceptor configuration​

If an interceptor supports per-deployment configuration, it exposes a /configuration endpoint that returns a JSON Schema. Register the configuration endpoint and provide default values in the interceptor declaration:

{
  "interceptors": {
    "pii-redactor": {
      "endpoint": "http://interceptor-service:5000/openai/deployments/pii-anonymizer/chat/completions",
      "features": {
        "configurationEndpoint": "http://interceptor-service:5000/openai/deployments/pii-anonymizer/configuration"
      },
      "defaults": {
        "custom_fields": {
          "interceptor_configuration": {
            "labels_to_redact": ["PERSON", "ORG", "GPE"]
          }
        }
      }
    }
  }
}

DIAL Core sends the configuration to the interceptor in the custom_fields.interceptor_configuration field of each chat completion request.

Managing interceptors via DIAL Admin​

As an alternative to editing config.json directly, DIAL administrators can manage interceptors through the DIAL Admin UI:

Interceptor templates, under Builders, need the optional Admin Backend.

Further reading​