> For the complete documentation index, see [llms.txt](https://docs.onyxia.sh/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onyxia.sh/~/revisions/zrl1OoKYFGeRjdCmmrF6/admin-doc/ai-configuration.md). # AI integration Onyxia can centralize AI provider settings for a user and inject the selected provider into compatible services at launch time. The feature supports two kinds of providers: * **Region providers** are OpenWebUI gateways configured by the platform administrator. Onyxia exchanges the user's OIDC access token for a short-lived OpenWebUI token. * **Custom providers** are configured by users. OpenAI, OpenAI-compatible, Mistral, and Anthropic API protocols are supported. {% hint style="info" %} Enabling the feature adds **My account > AI**. It does not add AI support to every service automatically. A Helm chart must use the [`ai` x-onyxia context](#inject-the-provider-into-a-service) to receive the selected provider. {% endhint %} ## Enable the feature The feature is disabled by default. Enable it in the Onyxia Web configuration: {% code title="apps/onyxia/values.yaml" %} ```yaml onyxia: web: env: ENABLED_AI: "true" ``` {% endcode %} This is the master switch for both region providers and custom providers. You can enable it without configuring a region provider; users will then only be able to add custom providers. The AI tab requires an authenticated user. User preferences and custom provider credentials are stored with the other Onyxia user settings: * in the user's Vault-backed configuration when the region has Vault; * in browser local storage when the region has no Vault. ## Configure an OpenWebUI gateway Add `data.ai` to the existing region configuration. It accepts either one gateway object or a list of gateway objects. {% code title="apps/onyxia/values.yaml (region excerpt)" %} ```yaml onyxia: api: regions: - id: "default" # Keep the other required region properties here. data: # Keep any existing configuration here. ai: - id: "openwebui" name: "Organization AI gateway" provider: "openai" URL: "https://ai.example.com" oauthProvider: "oidc" oidcConfiguration: clientID: "onyxia-ai" description: en: "Use the models hosted by our organization." fr: "Utilisez les modèles hébergés par notre organisation." accountCreation: title: en: "Activate your AI account" fr: "Activez votre compte IA" description: en: "Open the gateway and sign in once, then return to Onyxia." fr: "Ouvrez la passerelle et connectez-vous une première fois, puis revenez dans Onyxia." buttonLabel: en: "Open the gateway" fr: "Ouvrir la passerelle" ``` {% endcode %} Do not add a trailing slash to `URL`. Onyxia derives the API base URL as `/api`. ### Gateway properties | Property | Required | Description | | ------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `URL` | Yes | Public base URL of the OpenWebUI instance. The user's browser must be able to reach it. | | `oauthProvider` | Yes | OpenWebUI OAuth provider identifier used in `/api/v1/auths/oauth//token/exchange`; commonly `oidc`. | | `id` | Recommended | Stable, unique identifier used to persist the user's model and default-provider selections. If omitted, it is derived from the gateway's position in the list. | | `name` | No | Label displayed in Onyxia. Defaults to the hostname from `URL`. | | `provider` | No | Protocol name injected into charts. Defaults to `openai`, which is appropriate for the OpenWebUI OpenAI-compatible API. | | `description` | No | String or localized Markdown displayed below the gateway name. | | `accountCreation` | No | Localized title, description, and button label displayed when OpenWebUI returns `403` because the user has no account yet. The button opens `URL`. | | `oidcConfiguration` | No | OIDC overrides for this gateway: `issuerURI`, `clientID`, `extraQueryParams`, `scope`, or `idleSessionLifetimeInSeconds`. Unspecified values are inherited from the main Onyxia OIDC configuration. | Use an explicit, stable `id` for every gateway. Changing it makes Onyxia treat the gateway as a new provider and discards the model selection associated with the previous identifier. ### Configure OpenWebUI Onyxia uses the following OpenWebUI endpoints directly from the user's browser: * `POST /api/v1/auths/oauth//token/exchange` with `{ "token": "" }`; * `GET /api/models` with the returned token as a Bearer credential. Configure OpenWebUI to enable token exchange, trust the OIDC client used by Onyxia, and allow the Onyxia origin through CORS: ```dotenv ENABLE_OAUTH_TOKEN_EXCHANGE=true OAUTH_TOKEN_EXCHANGE_TRUSTED_CLIENT_IDS=onyxia-ai CORS_ALLOW_ORIGIN=https://onyxia.example.com ``` Create `onyxia-ai` as a public OIDC client using Authorization Code Flow with PKCE. Configure the Onyxia URL as an allowed redirect URI. A dedicated client is recommended; if `oidcConfiguration` is omitted, add Onyxia's main client ID to `OAUTH_TOKEN_EXCHANGE_TRUSTED_CLIENT_IDS` instead. {% hint style="warning" %} Configure the OIDC client used for the AI gateway so that the identity provider issues standard Bearer access tokens; do not require DPoP-bound access tokens for this client. Onyxia hands the access token to OpenWebUI's token-exchange endpoint, which reuses it without access to the private key held by the browser and therefore cannot present the associated DPoP proof. This restriction only applies to the AI client; other Onyxia OIDC clients can still use DPoP. {% endhint %} The first exchange can return `403` if the user does not yet exist in OpenWebUI. In that case, Onyxia displays the account-creation content. The user must open the gateway, sign in once, return to Onyxia, and select **Refresh credentials**. ## Inject the provider into a service The launcher exposes the user's AI configuration through the [`x-onyxia`](/~/revisions/zrl1OoKYFGeRjdCmmrF6/admin-doc/catalog-of-services/custom-catalogs/onyxia-extension.md) context: | Context path | Value | | ------------------- | ------------------------------------------------------------------------- | | `ai.enabled` | `true` when at least one usable provider is available. | | `ai.activeProvider` | The provider selected as default, or `undefined`. | | `ai.providers` | Other usable providers; the active provider is not repeated in this list. | Each provider contains `id`, `isDefault`, `name`, `provider`, `apiBase`, `apiKey`, `selectedModel`, and, when model discovery succeeded, `models`. The chart decides how these values map to its own `values.yaml`. The following JSON Schema fragment injects the default provider into an `ai` values object: {% code title="values.schema.json" %} ```json { "ai": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": false, "x-onyxia": { "overwriteDefaultWith": "{{ai.enabled}}", "hidden": true } }, "provider": { "type": "string", "default": "", "x-onyxia": { "overwriteDefaultWith": "{{ai.activeProvider.provider}}", "hidden": true } }, "apiBase": { "type": "string", "default": "", "x-onyxia": { "overwriteDefaultWith": "{{ai.activeProvider.apiBase}}", "hidden": true } }, "apiKey": { "type": "string", "default": "", "render": "password", "x-onyxia": { "overwriteDefaultWith": "{{ai.activeProvider.apiKey}}", "hidden": true } }, "model": { "type": "string", "default": "", "x-onyxia": { "overwriteDefaultWith": "{{ai.activeProvider.selectedModel}}", "hidden": true } } } } } ``` {% endcode %} Define matching defaults in `values.yaml` and only create AI-related environment variables or Secrets when `ai.enabled` is `true`. {% hint style="warning" %} `apiKey` is sensitive. Once injected, it becomes part of the Helm values used to launch the service. Store it in a Kubernetes Secret, never a ConfigMap, and do not print it in templates, logs, notes, or post-install instructions. {% endhint %} ## Validation checklist 1. Sign in to Onyxia and open **My account > AI**. 2. Confirm that the gateway appears with the expected name and description. 3. If prompted, open OpenWebUI and sign in once, then refresh the credentials in Onyxia. 4. Confirm that `GET /api/models` loads the model selector. 5. Select a default provider and model. 6. Launch a compatible chart and inspect its generated Helm values to confirm the expected mapping. If the AI tab is missing, verify `ENABLED_AI`. If token exchange or model loading fails, check the browser network panel, OpenWebUI's trusted client list, the `oauthProvider` identifier, and CORS for the exact Onyxia origin. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.onyxia.sh/~/revisions/zrl1OoKYFGeRjdCmmrF6/admin-doc/ai-configuration.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.