Configuration OpenAI

Apercu

OpenAI est un service cloud fournissant des grands modeles de langage (LLM) haute performance, dont GPT-4. Fess peut utiliser l’API OpenAI pour realiser la fonctionnalite de mode de recherche IA.

L’utilisation d’OpenAI permet de generer des reponses de haute qualite avec les modeles d’IA les plus avances.

Caracteristiques principales

  • Reponses de haute qualite : Generation de reponses precises avec les derniers modeles GPT

  • Evolutivite : Mise a l’echelle facile grace au service cloud

  • Amelioration continue : Performances ameliorees grace aux mises a jour regulieres des modeles

  • Fonctionnalites riches : Prise en charge de diverses taches comme la generation de texte, le resume, la traduction

Modeles pris en charge

Principaux modeles disponibles avec OpenAI :

  • gpt-5 - Dernier modele haute performance

  • gpt-5-mini - Version allegee de GPT-5 (bon rapport cout-efficacite)

  • gpt-4o - Modele multimodal haute performance

  • gpt-4o-mini - Version allegee de GPT-4o

  • o3-mini - Modele leger specialise dans le raisonnement

  • o4-mini - Modele leger de nouvelle generation specialise dans le raisonnement

Note

Pour les derniers modeles disponibles, consultez OpenAI Models.

Note

Lors de l’utilisation de modeles de la serie o1/o3/o4 ou de la serie gpt-5, Fess utilise automatiquement le parametre max_completion_tokens de l’API OpenAI. Aucune modification de configuration n’est necessaire.

Prerequis

Avant d’utiliser OpenAI, preparez les elements suivants.

  1. Compte OpenAI : Creez un compte sur https://platform.openai.com/

  2. Cle API : Generez une cle API dans le tableau de bord OpenAI

  3. Configuration de facturation : Configurez les informations de facturation car l’utilisation de l’API est payante

Obtention de la cle API

  1. Connectez-vous a OpenAI Platform

  2. Accedez a la section « API keys »

  3. Cliquez sur « Create new secret key »

  4. Entrez un nom pour la cle et creez-la

  5. Enregistrez la cle affichee en lieu sur (elle ne sera affichee qu’une seule fois)

Avertissement

La cle API est une information confidentielle. Faites attention aux points suivants :

  • Ne pas la commiter dans un systeme de gestion de versions

  • Ne pas l’afficher dans les logs

  • La gerer via des variables d’environnement ou des fichiers de configuration securises

Installation du plugin

Dans Fess 15.6, la fonctionnalite d’integration OpenAI est fournie sous forme de plugin. Pour l’utiliser, l’installation du plugin fess-llm-openai est necessaire.

  1. Telechargez fess-llm-openai-15.6.0.jar

  2. Placez le fichier JAR dans le repertoire app/WEB-INF/plugin/ du repertoire d’installation de Fess:

    cp fess-llm-openai-15.6.0.jar /path/to/fess/app/WEB-INF/plugin/

  3. Redemarrez Fess

Note

La version du plugin doit correspondre a la version de Fess.

Configuration de base

Dans Fess 15.6, les elements de configuration sont repartis dans les deux fichiers suivants selon leur usage.

  • app/WEB-INF/conf/fess_config.properties - Configuration principale de Fess et configuration specifique au fournisseur LLM

  • system.properties - Selection du fournisseur LLM (rag.llm.name), a configurer via l’administration (Administration > Systeme > General) ou directement dans le fichier

Configuration minimale

app/WEB-INF/conf/fess_config.properties :

# Activer la fonctionnalite de mode de recherche IA
rag.chat.enabled=true

# Cle API OpenAI
rag.llm.openai.api.key=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Modele a utiliser
rag.llm.openai.model=gpt-5-mini

system.properties (configurable egalement via Administration > Systeme > General) :

# Definir le fournisseur LLM sur OpenAI
rag.llm.name=openai

Configuration recommandee (environnement de production)

app/WEB-INF/conf/fess_config.properties :

# Activer la fonctionnalite de mode de recherche IA
rag.chat.enabled=true

# Cle API OpenAI
rag.llm.openai.api.key=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Configuration du modele (utiliser un modele haute performance)
rag.llm.openai.model=gpt-4o

# Point de terminaison API (generalement pas besoin de modifier)
rag.llm.openai.api.url=https://api.openai.com/v1

# Configuration du timeout
rag.llm.openai.timeout=120000

# Limite du nombre de requetes simultanees
rag.llm.openai.max.concurrent.requests=5

system.properties (configurable egalement via Administration > Systeme > General) :

# Configuration du fournisseur LLM
rag.llm.name=openai

Elements de configuration

Tous les elements de configuration disponibles pour le client OpenAI. Sauf rag.llm.name, tous se configurent dans fess_config.properties.

Propriete Description Valeur par defaut Emplacement
rag.llm.name Nom du fournisseur LLM (specifier openai) ollama system.properties
rag.llm.openai.api.key Cle API OpenAI (Requis) fess_config.properties
rag.llm.openai.model Nom du modele a utiliser gpt-5-mini fess_config.properties
rag.llm.openai.api.url URL de base de l’API https://api.openai.com/v1 fess_config.properties
rag.llm.openai.timeout Timeout de la requete (millisecondes) 120000 fess_config.properties
rag.llm.openai.availability.check.interval Intervalle de verification de disponibilite (secondes) 60 fess_config.properties
rag.llm.openai.max.concurrent.requests Nombre maximum de requetes simultanees 5 fess_config.properties
rag.llm.openai.chat.evaluation.max.relevant.docs Nombre maximum de documents pertinents lors de l’evaluation 3 fess_config.properties
rag.llm.openai.concurrency.wait.timeout Timeout d’attente des requetes simultanees (ms) 30000 fess_config.properties
rag.llm.openai.reasoning.token.multiplier Multiplicateur de max tokens pour les modeles de raisonnement 4 fess_config.properties
rag.llm.openai.history.max.chars Nombre maximum de caracteres pour l’historique de conversation 8000 fess_config.properties
rag.llm.openai.intent.history.max.messages Nombre maximum de messages d’historique pour la detection d’intention 8 fess_config.properties
rag.llm.openai.intent.history.max.chars Nombre maximum de caracteres d’historique pour la detection d’intention 4000 fess_config.properties
rag.llm.openai.history.assistant.max.chars Nombre maximum de caracteres pour les messages de l’assistant 800 fess_config.properties
rag.llm.openai.history.assistant.summary.max.chars Nombre maximum de caracteres pour le resume de l’assistant 800 fess_config.properties
rag.llm.openai.chat.evaluation.description.max.chars Nombre maximum de caracteres pour la description de document en evaluation 500 fess_config.properties
rag.chat.enabled Activation de la fonctionnalite de mode de recherche IA false fess_config.properties

Configuration par type de prompt

Dans Fess, des parametres individuels peuvent etre configures pour chaque type de prompt. La configuration s’effectue dans fess_config.properties.

Patterns de configuration

La configuration par type de prompt se specifie selon les patterns suivants :

  • rag.llm.openai.{promptType}.temperature - Caractere aleatoire de la generation (0.0 a 2.0). Ignore pour les modeles de raisonnement (serie o1/o3/o4/gpt-5)

  • rag.llm.openai.{promptType}.max.tokens - Nombre maximum de tokens

  • rag.llm.openai.{promptType}.context.max.chars - Nombre maximum de caracteres du contexte (defaut : 16000 pour answer/summary, 10000 pour les autres)

Types de prompt

Types de prompt disponibles :

Type de prompt Description
intent Prompt pour determiner l’intention de l’utilisateur
evaluation Prompt pour evaluer la pertinence des resultats de recherche
unclear Prompt de reponse pour les requetes peu claires
noresults Prompt de reponse lorsqu’il n’y a pas de resultats de recherche
docnotfound Prompt de reponse lorsque le document n’est pas trouve
answer Prompt pour generer une reponse
summary Prompt pour generer un resume
faq Prompt pour generer une FAQ
direct Prompt pour repondre directement
queryregeneration Prompt de regeneration de requetes

Valeurs par defaut

Valeurs par defaut pour chaque type de prompt. La configuration de temperature est ignoree pour les modeles de raisonnement (serie o1/o3/o4/gpt-5).

Type de prompt Temperature Max Tokens Remarques
intent 0.1 256 Detection d’intention deterministe
evaluation 0.1 256 Evaluation de pertinence deterministe
unclear 0.7 512
noresults 0.7 512
docnotfound 0.7 256
direct 0.7 1024
faq 0.7 1024
answer 0.5 2048 Generation de reponse principale
summary 0.3 2048 Generation de resume
queryregeneration 0.3 256 Regeneration de requetes

Exemple de configuration

# Configuration de la temperature pour le prompt answer
rag.llm.openai.answer.temperature=0.7

# Nombre maximum de tokens pour le prompt answer
rag.llm.openai.answer.max.tokens=2048

# Configuration de la temperature pour le prompt summary (configurer bas pour le resume)
rag.llm.openai.summary.temperature=0.3

# Configuration de la temperature pour le prompt intent (configurer bas pour la determination d'intention)
rag.llm.openai.intent.temperature=0.1

Prise en charge des modeles de raisonnement

Lors de l’utilisation de modeles de raisonnement de la serie o1/o3/o4 ou de la serie gpt-5, Fess utilise automatiquement le parametre max_completion_tokens de l’API OpenAI a la place de max_tokens. Aucune modification de configuration supplementaire n’est necessaire.

Note

Les modeles de raisonnement (serie o1/o3/o4/gpt-5) ignorent le parametre temperature et utilisent une valeur fixe (1). De plus, lors de l’utilisation de modeles de raisonnement, le max_tokens par defaut est multiplie par reasoning.token.multiplier (defaut : 4).

Parametres supplementaires pour les modeles de raisonnement

Lors de l’utilisation de modeles de raisonnement, les parametres supplementaires suivants peuvent etre configures dans fess_config.properties :

Propriete Description Valeur par defaut
rag.llm.openai.{promptType}.reasoning.effort Parametre d’effort de raisonnement pour les modeles de serie o (low, medium, high) low (intent/evaluation/docnotfound/unclear/noresults/queryregeneration), non defini (autres)
rag.llm.openai.{promptType}.top.p Seuil de probabilite pour la selection de tokens (0.0 a 1.0) (Non defini)
rag.llm.openai.{promptType}.frequency.penalty Penalite de frequence (-2.0 a 2.0) (Non defini)
rag.llm.openai.{promptType}.presence.penalty Penalite de presence (-2.0 a 2.0) (Non defini)

{promptType} peut etre intent, evaluation, answer, summary, etc.

Exemple de configuration

# Configurer l'effort de raisonnement sur high avec o3-mini
rag.llm.openai.model=o3-mini
rag.llm.openai.reasoning.effort=high

# Configurer top_p et les penalites avec gpt-5
rag.llm.openai.model=gpt-5
rag.llm.openai.top.p=0.9
rag.llm.openai.frequency.penalty=0.5

Configuration via variables d’environnement

Pour des raisons de securite, il est recommande de configurer la cle API via des variables d’environnement.

Environnement Docker

docker run -e RAG_LLM_OPENAI_API_KEY=sk-xxx... codelibs/fess:15.6.0

docker-compose.yml

services:
  fess:
    image: codelibs/fess:15.6.0
    environment:
      - RAG_CHAT_ENABLED=true
      - RAG_LLM_NAME=openai
      - RAG_LLM_OPENAI_API_KEY=${OPENAI_API_KEY}
      - RAG_LLM_OPENAI_MODEL=gpt-5-mini

Environnement systemd

/etc/systemd/system/fess.service.d/override.conf :

[Service]
Environment="RAG_LLM_OPENAI_API_KEY=sk-xxx..."

Utilisation d’Azure OpenAI

Pour utiliser les modeles OpenAI via Microsoft Azure, modifiez le point de terminaison API.

# Point de terminaison Azure OpenAI
rag.llm.openai.api.url=https://your-resource.openai.azure.com/openai/deployments/your-deployment

# Cle API Azure
rag.llm.openai.api.key=your-azure-api-key

# Nom du deploiement (specifie comme nom de modele)
rag.llm.openai.model=your-deployment-name

Note

Lors de l’utilisation d’Azure OpenAI, le format des requetes API peut differer legerement. Consultez la documentation Azure OpenAI pour plus de details.

Guide de selection des modeles

Guide pour la selection du modele selon l’usage.

Modele Cout Qualite Usage
gpt-5-mini Moyen Elevee Usage equilibre (recommande)
gpt-4o-mini Bas-Moyen Elevee Usage prioritaire au cout
gpt-5 Eleve Maximale Raisonnement complexe, haute qualite requise
gpt-4o Moyen-Eleve Maximale Lorsque la prise en charge multimodale est requise
o3-mini / o4-mini Moyen Maximale Taches de raisonnement comme les mathematiques et la programmation

Estimation des couts

L’API OpenAI est facturee a l’usage.

Note

Pour les derniers prix, consultez OpenAI Pricing.

Controle des requetes simultanees

Dans Fess, le nombre de requetes simultanees vers l’API OpenAI peut etre controle via rag.llm.openai.max.concurrent.requests dans fess_config.properties. La valeur par defaut est 5.

# Configurer le nombre maximum de requetes simultanees
rag.llm.openai.max.concurrent.requests=5

Cette configuration permet d’eviter les requetes excessives vers l’API OpenAI et de prevenir les erreurs de limitation de debit.

Limites par niveau OpenAI

Les limites varient selon le niveau de votre compte OpenAI :

  • Free : 3 RPM (requetes/minute)

  • Tier 1 : 500 RPM

  • Tier 2 : 5,000 RPM

  • Tier 3+ : Limites plus elevees

Ajustez rag.llm.openai.max.concurrent.requests de maniere appropriee selon le niveau de votre compte OpenAI.

Depannage

Erreur d’authentification

Symptome : Erreur « 401 Unauthorized »

Points a verifier :

  1. Verifier si la cle API est correctement configuree

  2. Verifier si la cle API est valide (verifier dans le tableau de bord OpenAI)

  3. Verifier si la cle API a les permissions necessaires

Erreur de limitation de debit

Symptome : Erreur « 429 Too Many Requests »

Solution :

  1. Reduire la valeur de rag.llm.openai.max.concurrent.requests:

    rag.llm.openai.max.concurrent.requests=3

  2. Mettre a niveau le niveau de votre compte OpenAI

Depassement de quota

Symptome : Erreur « You exceeded your current quota »

Solution :

  1. Verifier l’usage dans le tableau de bord OpenAI

  2. Verifier les parametres de facturation et augmenter la limite si necessaire

Timeout

Symptome : La requete expire

Solution :

  1. Augmenter le temps de timeout

    rag.llm.openai.timeout=180000

  2. Envisager un modele plus rapide (gpt-5-mini, etc.)

Configuration de debogage

Pour investiguer les problemes, ajustez le niveau de log de Fess pour afficher des logs detailles lies a OpenAI.

app/WEB-INF/classes/log4j2.xml :

<Logger name="org.codelibs.fess.llm.openai" level="DEBUG"/>

Notes de securite

Lors de l’utilisation de l’API OpenAI, faites attention aux points de securite suivants.

  1. Confidentialite des donnees : Le contenu des resultats de recherche est envoye aux serveurs OpenAI

  2. Gestion des cles API : La fuite de cles peut entrainer une utilisation non autorisee

  3. Conformite : Si les donnees contiennent des informations confidentielles, verifiez les politiques de votre organisation

  4. Politique d’utilisation : Respectez les conditions d’utilisation d’OpenAI

Informations de reference