ONLYOFFICE IA locale avec Ollama ou vLLM : architecture, configuration et supervision

ONLYOFFICE IA locale : branchez Docs 10.0 sur Ollama ou vLLM, réglez aiSettings et le relais /ai-proxy, puis supervisez TTFT et StatsD avec OpenTelemetry.
ONLYOFFICE IA locale avec Ollama ou vLLM : architecture, configuration et supervision

Dans ONLYOFFICE, IA locale veut dire résumé ou traduction de document sans qu’un octet ne quitte le réseau. Pour l’équipe d’exploitation, c’est surtout un nouveau chemin critique : un éditeur web, un relais côté serveur, un moteur d’inférence sur GPU. Quand un utilisateur clique sur « Résumer » et que rien ne vient, il faut savoir lequel des trois maillons a lâché.

Cet article décrit l’architecture d’ONLYOFFICE Docs 10.0 (la version documentée au moment de l’écriture) branché sur Ollama ou vLLM, les paramètres serveur qui comptent, puis la supervision de bout en bout. Tous les paramètres cités viennent de la documentation ONLYOFFICE, vLLM et Ollama. Côté Dynatrace, la méthode vaut pour Dynatrace SaaS comme pour Dynatrace Managed : seule l’adresse OTLP change.

Si vous partez de zéro sur les modèles locaux, commencez par installer et superviser Ollama ou par vLLM en production ; on suppose ici le moteur déjà en place.

Architecture : ONLYOFFICE IA locale en trois maillons

Les fonctions d’IA d’ONLYOFFICE vivent dans un plugin, appelé AI Tools dans le journal des modifications de la version 10.0. Le plugin tourne dans l’éditeur, donc dans le navigateur de l’utilisateur. Il peut joindre le modèle de deux façons :

  • en direct depuis le navigateur : la requête part du poste vers Ollama. C’est pour ce cas que la documentation demande de régler OLLAMA_ORIGINS (en-têtes CORS) ;
  • par le relais /ai-proxy du serveur Docs : la documentation de configuration serveur décrit ce point d’entrée, son délai (aiSettings.timeout) et le fait que les requêtes sortantes passent par le filtrage externalRequest.

Le choix change tout pour la supervision. En direct, le serveur Docs ne voit rien passer et chaque poste doit joindre le moteur. Par le relais, le serveur Docs devient un point de passage unique : on y lit les erreurs, on y applique le filtrage, et le moteur n’a besoin d’être joignable que depuis le serveur.

Ollama et vLLM ne se branchent pas de la même manière. Ollama figure dans la liste des fournisseurs du plugin : on saisit une URL de base (http://localhost:11434 dans le guide officiel) à la place d’une clé d’API. vLLM expose une API compatible OpenAI sous /v1 ; la documentation ONLYOFFICE ne cite pas vLLM, mais elle décrit l’ajout d’un fournisseur personnalisé par un fichier JavaScript qui étend AI.Provider avec une URL, une clé facultative et un suffixe comme v1. C’est cette voie qu’il faut tester pour vLLM.

Les paramètres serveur à connaître

ONLYOFFICE Docs lit sa configuration avec node-config dans /etc/onlyoffice/documentserver/ sous Linux. Ne modifiez pas default.json : placez vos valeurs dans local.json, qui le surcharge. Quatre blocs concernent l’IA et sa supervision.

Extraits de la documentation ONLYOFFICE Server configuration : bloc statsd avec useMetrics false, port 8125 et préfixe ds., bloc aiSettings avec enable, timeout 5m, allowedCorsOrigins et allowBrowserProxy, bloc externalRequest.action avec blockPrivateIP true
  • aiSettings.enable (true par défaut) : à false, le plugin est retiré de /plugins.json et les requêtes /ai-proxy reçoivent un HTTP 403. C’est l’interrupteur d’urgence.
  • aiSettings.timeout ("5m") : délai du relais. Un modèle lent sur CPU peut l’atteindre.
  • aiSettings.allowBrowserProxy (true) : le relais transmet aussi une requête dont la cible ne correspond à aucun fournisseur configuré, par exemple un serveur MCP déclaré dans le navigateur. Le serveur n’ajoute aucun identifiant, exige un jeton de session valide et n’accepte que des cibles http ou https absolues. À false, ces requêtes reçoivent un 403.
  • externalRequest.action.blockPrivateIP (true) : les adresses IP privées sont bloquées. Un moteur posé sur 10.x ou 192.168.x peut donc être refusé par le relais. L’assouplir est une décision de sécurité, à prendre avec l’équipe réseau.
  • statsd.useMetrics (false), statsd.host, statsd.port ("8125"), statsd.prefix ("ds.") : l’export de métriques du serveur Docs.

Le paramètre d’intégration editorConfig.customization.ai.disabled, ajouté en 10.0, désactive l’IA pour une ouverture de document donnée. Les clés et réglages des modèles peuvent aussi se saisir sur la page /info du serveur depuis la version 9.0.

En pratique : brancher et vérifier

Étape 1 — Ouvrir Ollama à l’éditeur

Si le plugin appelle Ollama depuis le navigateur, Ollama doit renvoyer les bons en-têtes CORS. La documentation ONLYOFFICE donne la procédure systemd et la commande de vérification :

Commandes de la documentation ONLYOFFICE Configuring Ollama with CORS : systemctl edit ollama avec OLLAMA_ORIGINS, redémarrage, puis requête OPTIONS sur /api/tags et réponse attendue 204 avec les en-têtes Access-Control-Allow

Les jokers http://* et https://* conviennent à un poste de test, pas à un serveur partagé : la même page recommande de lister les origines explicites en production. Par défaut Ollama n’écoute que sur localhost ; l’ouvrir au réseau (OLLAMA_HOST=0.0.0.0) impose, selon la documentation, un reverse proxy avec TLS et authentification.

Étape 2 — Démarrer vLLM avec une clé

vllm serve NousResearch/Meta-Llama-3-8B-Instruct \
  --dtype auto \
  --api-key token-abc123

curl http://localhost:8000/v1/models -H "Authorization: Bearer token-abc123"

vLLM écoute par défaut sur http://localhost:8000. Attention : la documentation précise que --api-key (ou VLLM_API_KEY) ne protège que les chemins /v1, /v2 et /inference ; /invocations reste ouvert. Mettez vLLM derrière un reverse proxy et n’exposez jamais le port directement aux postes.

Étape 3 — Restreindre et régler le relais

{
  "aiSettings": {
    "timeout": "2m",
    "allowBrowserProxy": false
  },
  "statsd": {
    "useMetrics": true,
    "host": "localhost",
    "port": "8125",
    "prefix": "ds."
  }
}

Ce local.json raccourcit le délai (un échec rapide vaut mieux qu’un utilisateur qui attend cinq minutes), coupe le relais vers des cibles non déclarées et active StatsD. Couper allowBrowserProxy désactive aussi les cibles configurées dans le navigateur, comme un serveur MCP : vérifiez que personne ne s’en sert. Redémarrez les services Docs après modification.

Étape 4 — Vérifier chaque maillon

# Serveur Docs : bases, broker, Redis et stockage (réponse attendue : true)
curl -s https://docs.example.com/healthcheck

# Ollama : modèles disponibles
curl -s http://localhost:11434/api/tags

# vLLM : métriques Prometheus
curl -s http://localhost:8000/metrics | grep vllm:time_to_first_token_seconds

Le contrôle /healthcheck vérifie, selon la documentation, les bases de données, le broker de messages, Redis et le stockage ; il ne teste pas le moteur d’IA. Il faut donc une sonde propre au moteur.

Superviser la chaîne avec OpenTelemetry et Dynatrace

Un seul OpenTelemetry Collector peut recueillir les deux sources : le récepteur statsd de la distribution contrib (stabilité beta, écoute par défaut sur localhost:8125 en UDP) pour ONLYOFFICE, et le récepteur prometheus pour vLLM. Les composants et le format d’export sont détaillés dans les composants du Collector contrib.

receivers:
  statsd:
    endpoint: localhost:8125
  prometheus:
    config:
      scrape_configs:
        - job_name: vllm
          static_configs:
            - targets: ["localhost:8000"]
exporters:
  otlphttp:
    endpoint: https://<env-id>.live.dynatrace.com/api/v2/otlp   # SaaS
    # Managed : https://<votre-domaine>/e/<env-id>/api/v2/otlp
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"
service:
  pipelines:
    metrics:
      receivers: [statsd, prometheus]
      exporters: [otlphttp]

Le jeton doit porter le scope metrics.ingest. Côté vLLM, trois métriques suffisent pour un premier tableau de bord : vllm:time_to_first_token_seconds, vllm:e2e_request_latency_seconds et vllm:num_requests_waiting. Le schéma de la documentation de conception de vLLM montre ce que chacune mesure :

Schéma de la documentation vLLM sur les intervalles d'une requête : file d'attente, prefill puis decode côté Engine Core, TTFT mesuré du côté API Server et latence entre jetons ITL
Source : github.com

Le TTFT est ce que l’utilisateur ressent dans l’éditeur : le délai avant que le texte commence à apparaître. Une hausse de la file d’attente (num_requests_waiting) avec un TTFT qui grimpe signale un GPU saturé, pas une panne d’ONLYOFFICE. Pour Ollama, qui n’expose pas ces histogrammes, une sonde synthétique sur /api/generate rend total_duration, eval_count et eval_duration, en nanosecondes.

Un SLO lisible par le support

Formulez l’objectif du point de vue de l’utilisateur : « 95 % des demandes de résumé produisent un premier mot en moins de 3 secondes sur 28 jours ». Le seuil est un exemple à calibrer sur votre matériel. Le TTFT vLLM sert de SLI ; le 403 de /ai-proxy et le /healthcheck servent au diagnostic. Avec ces trois signaux, l’astreinte sait en une minute si le problème vient du réseau, du serveur Docs ou du moteur, ce qui réduit le MTTR.

Bonnes pratiques

  • Préférez le relais /ai-proxy à l’accès direct : un seul chemin réseau, un seul point de filtrage.
  • Gardez blockPrivateIP actif tant qu’une analyse réseau ne justifie pas d’exception.
  • Réduisez aiSettings.timeout pour échouer vite plutôt que bloquer l’éditeur.
  • Ne comptez pas sur --api-key seul pour vLLM : reverse proxy obligatoire.
  • Documentez l’interrupteur aiSettings.enable dans le runbook d’incident.
  • Supervisez le moteur séparément : /healthcheck ne le couvre pas.

Questions fréquentes

ONLYOFFICE IA locale fonctionne-t-elle avec la version web ?

La page actuelle sur l’agent du plugin traite Ollama et LM Studio comme des fournisseurs locaux saisis par URL, sans distinguer bureau et web. Un ancien guide réservait Ollama aux Desktop Editors : testez sur votre version avant de l’annoncer aux utilisateurs.

Peut-on brancher vLLM sans fournisseur personnalisé ?

La documentation ONLYOFFICE ne cite pas vLLM. Le fournisseur personnalisé (fichier JavaScript étendant AI.Provider) est la voie documentée pour une API compatible OpenAI.

Le serveur Docs envoie-t-il des traces ?

La configuration documente un export StatsD, pas de traces OpenTelemetry. Les traces de bout en bout se construisent côté moteur ou avec une sonde synthétique.

Conclusion

Une IA locale dans ONLYOFFICE garde les documents chez vous, mais ajoute un moteur d’inférence au chemin critique de la bureautique. Choisissez le relais serveur, gardez les filtres par défaut, raccourcissez le délai et suivez le TTFT comme indicateur principal. Pour situer ce composant dans l’ensemble, voir la stack IA open source auto-hébergée et, pour les cibles MCP du relais, sécuriser un serveur MCP. Références : configuration serveur ONLYOFFICE Docs et configuration d’Ollama avec CORS.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC ni aux projets cités. Les marques citées appartiennent à leurs propriétaires. Les outils évoluent vite : vérifiez les commandes et options dans leur documentation officielle.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Previous Post
Ghidra MCP : brancher un agent IA sur des outils locaux, isolation et traçabilité des appels

Ghidra MCP : brancher un agent IA sur des outils locaux, isolation et traçabilité des appels

Next Post
MCP grand public : ce que Google Home MCP apprend aux SRE sur l'authentification, les permissions et l'audit des agents

MCP grand public : ce que Google Home MCP apprend aux SRE sur l’authentification, les permissions et l’audit des agents

Related Posts