Docling Serve (docling)
Service de conversion de documents (PDF, Office, HTML, images avec OCR) utilisé par l'ingestion des bases de connaissances (EAI_DOCLING_URL).
Généré depuis catalog/services/docling.yaml : ne pas modifier à la main.
Résumé
| Version | 1.38.2 |
| Usage | installer et configurer, configurer et connecter |
| Couche | fonctionnelle (catalogue IA) |
| Catégorie | Inférence IA |
| Méthodes d'installation | python, podman |
| Connexion externe | non |
| Réservé au bac à sable | non |
Licence
| Identifiant SPDX | MIT |
| Politique de licence | licence socle (MIT ou Apache-2.0) |
| Exception de licence | - |
| Composant de la plateforme | docling |
Paquets et artefacts
Un paquet que publie le projet du service (son image, son archive binaire, son paquet Python ou système) porte la licence du service ; un paquet tiers porte la licence écrite sur sa ligne, lue dans les métadonnées officielles du projet amont.
| Type | Paquet | Version | Licence | Détails |
|---|---|---|---|---|
| image de conteneur | quay.io/docling-project/docling-serve-cpu | v1.38.2 | MIT | clé d'image docling, utilisée par docling-serve, condensé sha256:7a480a1604fa3b42efeddc7db9527690d9f9bc903226136013e2bfe6b1a4dfb0 |
| paquet Python | docling-serve | 1.38.2 | MIT | interpréteurs, par ordre de préférence python3.12, python3.11, python3.10 |
Les images sont épinglées par étiquette dans le descripteur, et par condensé (digest) quand le descripteur en déclare un (le bundle hors ligne refuse alors une image téléchargée qui ne le porte pas) ; le condensé est enregistré dans le miroir du Manager à l'import du bundle hors ligne, et chaque téléchargement ou chargement est vérifié par rapport à lui.
Systèmes et architectures pris en charge
| Méthode | Systèmes d'exploitation | Architectures |
|---|---|---|
python | famille RHEL (dnf), famille Debian (apt), Arch Linux (pacman) | x86_64, aarch64 (non restreintes par le descripteur) |
podman | famille RHEL (dnf), famille Debian (apt), Arch Linux (pacman) | x86_64, aarch64 (non restreintes par le descripteur) |
Systèmes hôtes certifiés : RHEL 8/9/10, Rocky Linux 8/9/10, AlmaLinux 8/9/10, Oracle Linux 8/9, CentOS Stream 9/10, Ubuntu 22.04/24.04, Debian 12, Arch Linux (rolling). Le contrôle préalable des hôtes accepte ces systèmes (une autre version d'une famille connue donne un avertissement, une version en fin de vie est refusée) et les architectures x86_64 et aarch64.
Prérequis
Hôte
- au moins 4096 Mo de mémoire (avertissement,
memory).
Réseau et ports
| Composant | Nom du port | Port | Ouvert dans le pare-feu de l'hôte |
|---|---|---|---|
docling-serve | api | 5001/tcp | oui |
Services et connexions nécessaires
Ce service n'a aucune dépendance.
Méthodes et modes d'installation
| Méthode | Défaut | Ce que la méthode utilise |
|---|---|---|
python | oui | un environnement virtuel Python qui contient les paquets Python du descripteur |
podman | - | les images de conteneur du descripteur, exécutées par Podman sous systemd |
Composants
| Composant | Type | Méthodes d'installation | Ports |
|---|---|---|---|
Serveur Docling (docling-serve) | maître | python, podman | 5001/tcp |
Serveur unique (standalone) (par défaut)
Un seul serveur de conversion.
Ce que le mode déploie :
| Composant | Placement |
|---|---|
docling-serve | min 1, max 1 |
Répliqué (replicated)
Plusieurs serveurs sans état derrière le répartiteur de charge.
Ce que le mode déploie :
| Composant | Placement |
|---|---|
docling-serve | min 2, recommandé 2 |
Installer ce service
L'assistant d'installation du Navin Manager planifie, valide et exécute l'installation ; il faut la permission services:install sur le cluster.
-
Ouvrez l'assistant. Dans Clusters, choisissez l'action de ligne Installer des services du cluster cible. L'assistant s'ouvre sur sa première étape, Service.
-
Choisissez le service. À l'étape Service, sélectionnez Docling Serve. La carte affiche la licence
MIT. Choisissez la Méthode parmipython,podman(par défautpython). -
Choisissez les hôtes et le mode. À l'étape Hôtes, cochez les hôtes, puis choisissez le Mode :
standalone(par défaut),replicated. Chaque mode déploie les composants listés dans Méthodes et modes d'installation. -
Liaisons. Ce service n'a aucune dépendance : l'étape Liaisons n'a rien à lier.
-
Configurez. À l'étape Configuration, relisez les paramètres (voir Paramètres de configuration). Les mots de passe laissés vides avec une valeur générée par défaut sont générés et scellés par le Manager.
-
Relisez et installez. À l'étape Installation, le Manager valide le plan et affiche l'ordre d'installation ; quand il indique « Le plan est valide. Prêt pour l'installation. », choisissez Installer. Un mode hautement disponible n'est installé que si ses contrôles HA réussissent.
-
Vérifiez. L'opération se termine quand les contrôles de santé de chaque instance réussissent (voir Contrôles de santé) ; le service apparaît alors en marche dans Services.
Connecter un service existant
| Schémas | https, http |
| Port par défaut | 5001 |
| Authentification | facultative |
| Contrôle de santé | /health |
| Méthode d'authentification | Champs | Description |
|---|---|---|
api_key | api_key | Clé de DOCLING_SERVE_API_KEY, envoyée dans l'en-tête X-Api-Key. |
none | - | Sans DOCLING_SERVE_API_KEY, l'API de conversion est ouverte à quiconque l'atteint. |
Documentation officielle : https://github.com/docling-project/docling-serve/blob/main/docs/configuration.md
Haute disponibilité
| Cluster | réplicas (replication) |
| Haute disponibilité | externe (external) |
| Bascule | répartiteur (load-balancer) |
| Réplication | aucun (none) |
| Quorum | aucun (none) |
| Découverte | aucun (none) |
| Point d'entrée | répartiteur (load-balancer) |
| Documentation officielle | https://github.com/docling-project/docling-serve/blob/main/docs/deployment.md |
Topologie par mode
| Modes | Niveau le plus haut du catalogue | Répartition | Composant du quorum | Domaines de panne | Description |
|---|---|---|---|---|---|
standalone | autonome (standalone) | unique (single) | - | 1 | Une instance, sans tolérance aux pannes. |
replicated | ha (ha) | actif-actif (active-active) | - | 2 | Réplicas sans état derrière le répartiteur (HAProxy et keepalived). |
Remarques
- Le mode du catalogue fait tourner le moteur local dans chaque serveur : une conversion en cours est perdue avec son serveur et une tâche asynchrone n'est connue que du serveur qui l'a reçue. Le moteur RQ distribué (Redis et workers OCR) de la documentation officielle n'est pas déployé par ce mode.
Paramètres de configuration
Réseau
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|---|---|---|---|---|---|---|
Port de l'API (port) | port | 5001 | - | non | non | oui | Port de l'API de conversion. |
TLS (tls_enabled) | bool | false | - | non | non | oui | Servir l'API et la console web en HTTPS avec un certificat de l'autorité du Manager (options uvicorn --ssl-certfile et --ssl-keyfile de docling-serve run, UVICORN_SSL_CERTFILE et UVICORN_SSL_KEYFILE dans le conteneur) ; les contrôles de santé et les liens passent alors en https. |
Traitement
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|---|---|---|---|---|---|---|
Processus de travail (workers) | int | 2 | min 1, max 32 | non | non | oui | Processus de conversion du serveur. (recommandé clamp(floor(host.cpu_count / 4), 1, 8)) |
Pages maximales (max_pages) | int | 1000 | min 1, max 100000 | non | non | non | Nombre maximal de pages converties par document. |
Interface web (enable_ui) | bool | true | - | non | non | non | Servir la console web /ui (DOCLING_SERVE_ENABLE_UI) : un ensemble statique du paquet qui appelle l'API publique avec les mêmes règles. |
Sécurité
| Paramètre | Type | Défaut | Valeurs permises | Obligatoire | Secret | Redémarrage | Description |
|---|---|---|---|---|---|---|---|
Clé d'API (api_key) | password | généré | - | non | oui | oui | Clé que chaque requête de l'API de conversion doit porter dans l'en-tête X-Api-Key (DOCLING_SERVE_API_KEY), générée à l'installation et donnée aux consommateurs par le point d'accès api (EAI_DOCLING_API_KEY) ; la sonde /health reste ouverte. |
Points d'accès
| Point d'accès | Schéma | Composant | Port | Chemin | Paramètre TLS | Paramètres de liaison | Secrets de liaison | Commande de provisionnement |
|---|---|---|---|---|---|---|---|---|
api | http | docling-serve | 5001 (port) | - | tls_enabled | - | api_key | - |
Fichiers de configuration client
Fichiers rendus pour le téléchargement de la configuration client :
docling.env(client.env.j2)
Commandes
| Commande | Composant | Cible | Description |
|---|---|---|---|
Journaux récents (logs) | docling-serve | hôte choisi | Dernières lignes du journal du serveur. |
Contrôles de santé
Vivacité (par instance)
| Composant | Contrôle | Détails |
|---|---|---|
docling-serve | HTTP {{ 'https' if config.tls_enabled else 'http' }}://{{ host.ip or '127.0.0.1' }}:{{ config.port }}/health | Attendu 200 ; 60 tentatives ; intervalle 2 s ; délai 5 s |
Contrôles préalables
| Contrôle | Type | Signification | Sévérité | Composants |
|---|---|---|---|---|
memory | memory_mb {"min": 4096} | au moins 4096 Mo de mémoire | avertissement | tous les composants |
api_port_free | port_free {"param": "port"} | port 5001 libre sur l'hôte | bloquant | tous les composants |
Désinstallation
Chemins supprimés quand les données sont purgées : {{ paths.data }}, {{ paths.log }}.
Liens rapides
- Console web :
{{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/ui - Documentation de l'API :
{{ 'https' if config.tls_enabled else 'http' }}://{{ host.fqdn }}:{{ config.port }}/docs
Documentation amont
- Site : https://github.com/docling-project/docling-serve
- Sources : https://github.com/docling-project/docling-serve
- Haute disponibilité : https://github.com/docling-project/docling-serve/blob/main/docs/deployment.md
- Authentification : https://github.com/docling-project/docling-serve/blob/main/docs/configuration.md