Configure AI

Artificial intelligence is an option of Portail ZAPP: it adds assistants (summaries, suggestions, writing help, the chatbot of public knowledge bases) and semantic search. Every feature of the application works without it. It is disabled at installation: nothing is sent to an AI service until you choose a provider.

The AI configuration screen (menu Administration › Instance and operations › AI) is reserved for Administrators.

Choose the providers

The General tab holds two independent choices:

Active chat provider: the service that writes (assistants, chatbot). Possible choices: OpenAi, Anthropic, AzureOpenAi, Mistral, Ollama, Groq;
Active embedding provider: the service that measures how close texts are in meaning, for semantic search and so that the chatbot finds the relevant article passages. Possible choices: OpenAi, AzureOpenAi, Mistral, Ollama (Anthropic and Groq do not offer one).

Each also offers None (AI disabled). Click Save: the choice applies without a restart and is recorded in the history of the Configuration screen.

If your subscription includes the publisher's AI

When the instance license includes the publisher's AI, the General tab shows the AI provided by the publisher box, and both lists offer AI provided by the publisher as their first choice. This choice needs no key and no model.

Usage is deducted from a token credit. The box shows the Remaining credit (balance out of the total of current top-ups) and displays Credit used up when none is left.
Credit used up: the AI assistants stop answering. Semantic search keeps working.
To use your own AI, choose another provider and fill in its tab: the count stops and the remaining credit is kept.

Without this license, for example on an instance installed on your own servers, neither the box nor this choice appears. Credit tracking and its alerts are on the Usage screen.

Set up a provider

Each provider has its own tab, with its own Save button. Saving a tab does not activate it: the active provider is chosen in General.

API key: supplied by the service. It is never displayed again; leave the field empty to keep the saved key;
Base URL: the API address, pre-filled with the service's own; change it only to go through a relay;
Chat model and, except for Anthropic and Groq, which do not compute embeddings, Embedding model: the provider's model names, pre-filled with a common value;
Azure OpenAI asks instead for the Endpoint of your resource, the names of your Chat deployment and Embedding deployment (fields marked with an asterisk, required), and the API version;
Ollama is a server you host yourself: no key, only its Base URL and its models. Texts then do not leave your infrastructure.

For security, the addresses that can be reached depend on the provider:

OpenAI and Azure OpenAI: a public address or an address on your private network — for example an OpenAI-compatible gateway you host, or an Azure OpenAI resource behind a private endpoint (Private Endpoint);
Anthropic, Mistral and Groq: a public address only;
Ollama: the machine itself (localhost, the default) or your private network.

Reserved addresses (link-local, a cloud host's metadata) are always refused. Calls follow no redirect: the key is never sent to an address other than the one entered. If your server reaches the Internet only through a proxy, declare it at installation (HTTPS_PROXY and NO_PROXY variables): calls then go through it.

With the other providers, the texts being processed (content of a ticket, an article…) are sent to their service when a user requests an AI action.

If you change the embedding provider or model, then click Reindex all published articles on the page of each knowledge base: articles already indexed were indexed with the previous model.

Document reading and image (Capabilities tab)

Besides chat and embeddings, AI offers two capabilities, each with its own provider. They stay disabled until you choose one for them, including on an instance that is already configured: choosing a chat provider turns on neither document reading nor image.

The Capabilities tab has one section per capability:

Document reading: a PDF or an image of a document, scanned ones included, becomes text per page with its tables and, on request, extracted fields. OpenAI, Anthropic and Mistral (Mistral OCR) read PDFs and images; Azure OpenAI reads images only (PNG, JPEG);
Image: generate an image from a prompt, or edit an image with an optional mask. OpenAI and Azure OpenAI.

Each section has:

Provider: None (AI disabled) or one of the providers that really offer the capability; AI provided by the publisher first if your license includes it;
Model: empty for the provider's default model. With Azure OpenAI, enter the name of your deployment, which is required. With the publisher's AI, the publisher chooses the model;
Maximum file size (MB): from 1 to 20 MB, 10 by default. A larger file is refused before anything is sent.

The API key is not entered here: the key from the provider's tab, encrypted at rest, is used for all its capabilities.

What is sent to the provider and what is kept is described in "Read documents with AI" and "Produce images with AI". Speech transcription will get its section once its providers are delivered.

Choose a provider or a model per feature (Features tab)

By default, each feature that calls AI (ticket triage, drafting help, invoice reading…) uses its capability's provider and model. The Features tab lists the features that called AI over the last 90 days, under their technical name, with their Effective provider and model. You can assign them others: for example a light model for triage and a stronger one for drafting.

To add an override, click Override on the feature's row (its feature and capability are already filled in), or Add an override below the list and enter its code. The New override form opens:

Capability: Chat, Document reading or Image;
Provider: The capability's provider to change only the model (the feature then follows the capability; the model only applies to its current provider: if the capability changes provider, the feature uses the new one's default model), or another provider;
Model: empty for the provider's default model;
Monthly cap: in the capability's unit (tokens for chat, pages for document reading, images for image). Once reached, the feature is refused until next month; empty, no cap.

The Overridden badge marks a feature set this way. Edit opens the Edit override form: you can change every field there, feature and capability included, and Save updates that override (it does not create a second one). Cancel editing closes the form without changing anything. Remove gives the feature back its capability's provider and model. A feature with no override behaves exactly as before.

A feature has at most one override per capability: if the chosen feature and capability already have one, saving is refused and the message names the feature; edit the existing override instead.

A capability set to None turns off all its features, overridden ones included.
If the provider chosen for a feature is no longer available (expired license for the publisher's AI, for example), the feature goes back to its capability's provider.
Embeddings cannot be overridden per feature (Cannot be overridden): indexing and search must use the same model.
A feature's provider must be set up in its tab (key, address): without a key, the call fails.

When AI is disabled ("None")

To turn AI off completely, set both choices to None (AI disabled): this is the situation of a freshly installed instance. No call then goes to an external service, and nothing is recorded in AI usage.

Active chat provider set to None: the AI disabled badge is shown at the top of the screen.

All AI buttons disappear: Service Desk, Knowledge base, Change management, Problem management, Release management, Event management. Screens remain complete and everything is done by hand.
The chatbot bubble no longer appears on public knowledge bases.

Active embedding provider set to None: the Semantic search disabled badge is shown. Searching knowledge bases uses full-text search (on words), and the chatbot no longer finds article passages to support its answers.

The two choices are independent: with an embedding provider but no chat provider, the assistants disappear but semantic search continues, and so do calls to the embedding provider.

In every case, provider keys and settings remain saved: selecting a provider again is enough to restore everything.