Passer au contenu principal
FIM One traite automatiquement les documents téléchargés afin que les agents IA puissent comprendre leur contenu. Lorsqu’un modèle supporte la vision, les documents sont traités avec une fidélité visuelle complète — les pages PDF sont rendues sous forme d’images, et les images intégrées dans les documents Office sont extraites avec des références positionnelles. Lorsque la vision n’est pas disponible, le système bascule vers l’extraction de texte. Le contenu visuel persiste d’un tour de conversation à l’autre, de sorte que le modèle conserve le contexte visuel des documents téléchargés tout au long de la conversation entière — pas seulement au tour où le fichier a été téléchargé.
Le mode vision est automatique par défaut. Si le modèle que vous avez configuré a le support de la vision activé, les documents téléchargés utiliseront le pipeline de traitement le plus riche disponible pour ce format.

​
Matrice de support des formats

Chaque format de document dispose d’un pipeline de traitement dédié. Le comportement change selon que le modèle supporte la vision.
FormatExtraction de texteMode Vision (supports_vision=ON)Secours (supports_vision=OFF)
PDFpdfplumber (texte page par page)Traitement intelligent : les pages riches en texte extraient le texte + les images intégrées (efficace en tokens) ; les pages numérisées/image uniquement sont rendues en PNG pleine page via PyMuPDFExtraction de texte uniquement ; l’agent lit via l’outil read_uploaded_file
DOCX / DOCmarkitdown (conversion Markdown)Images intégrées extraites avec marqueurs positionnels [Figure N] via python-docxExtraction de texte uniquement ; images perdues
PPTX / PPTmarkitdown (texte de chaque diapositive)Images intégrées extraites avec marqueurs [Figure N] et séparateurs de diapositives via python-pptxExtraction de texte uniquement ; visuels de diapositive perdus
XLSX / XLSmarkitdown (structure de tableau préservée)Identique au mode texte (les tableaux ne bénéficient pas de la vision)Identique
Images (JPG, PNG, GIF, WebP)N/AEnvoyées en tant que blocs de contenu vision image_urlAnnotées comme [Attached image: filename] — le modèle est conscient mais ne peut pas voir le contenu
Fichiers texte (TXT, MD, PY, JS, HTML, CSV, JSON)Lecture / analyse directeN/A (le texte est du texte)Identique
Pour une fidélité visuelle maximale, exportez les fichiers DOCX ou PPTX en PDF avant de les télécharger. Le mode vision PDF rend la mise en page complète de la page — texte, images, graphiques et formatage — tout en une seule image.

​
Fonctionnement

Lorsqu’un utilisateur télécharge un document dans une conversation, FIM One exécute un pipeline de traitement basé sur le type de fichier et les capacités du modèle :
1

Détection du type de fichier

Le système identifie le format du document par extension de fichier et type MIME, puis sélectionne le pipeline d’extraction approprié. Chaque fichier téléchargé est marqué avec son UUID file_id, qui est injecté dans le contexte du message afin que l’agent puisse y accéder directement via l’outil read_uploaded_file.
2

Extraction de texte

Indépendamment du support de la vision, le système extrait toujours le contenu textuel. Pour les PDF, pdfplumber est utilisé pour l’extraction page par page. Les formats Office utilisent markitdown pour la conversion en Markdown. Les fichiers texte sont lus directement.
3

Traitement de la vision (si supporté)

Lorsque le modèle a supports_vision=true et que le document est d’un type supporté :
  • PDF (traitement intelligent) : Chaque page est analysée — les pages riches en texte extraient le texte plus les images intégrées séparément (économisant des tokens), tandis que les pages numérisées ou contenant uniquement des images sont rendues en PNG pleine page à la résolution configurée pour une fidélité maximale
  • DOCX / PPTX : Les images intégrées sont extraites du XML du document avec des marqueurs de position [Figure N]
  • Images : Transmises directement en tant que blocs de contenu de vision
4

Assemblage du contenu

Le texte extrait et le contenu de vision sont assemblés dans le format de message attendu par le modèle. Le texte et les images sont entrelacés afin que le modèle puisse corréler les informations visuelles et textuelles.
5

Persistance multi-tours

Le contenu de vision des fichiers téléchargés est stocké dans les métadonnées du message et persiste à travers les tours de conversation. Que les images proviennent d’une photo téléchargée par l’utilisateur ou aient été extraites d’un document, elles restent disponibles pour que le modèle les référence dans les messages suivants.

​
Configuration du Mode Vision

Il existe trois façons de contrôler le traitement des documents, énumérées de la plus spécifique à la plus générale.

​
1. Basculement par modèle

Accédez à Admin > Models > Edit > Advanced et basculez la case à cocher Vision Support. C’est le contrôle principal — il indique au système si un modèle spécifique peut accepter du contenu image.

​
2. Variable d’environnement global

Définissez DOCUMENT_PROCESSING_MODE dans votre environnement pour remplacer le comportement par défaut au niveau du système : 
# Use vision when the model supports it (default)
DOCUMENT_PROCESSING_MODE=auto

# Always attempt vision processing, regardless of model config
DOCUMENT_PROCESSING_MODE=vision

# Never use vision — text extraction only
DOCUMENT_PROCESSING_MODE=text

​
3. Paramètre par Requête

Passez le paramètre doc_mode dans l’API de chat pour contrôler le traitement pour une seule requête : 
{
  "message": "Analyze this financial report",
  "doc_mode": "vision",
  "attachments": [...]
}
Le mode auto (par défaut) utilise la vision lorsque le modèle a supports_vision=true et que le document est un type qui bénéficie du traitement par vision. C’est le paramètre recommandé pour la plupart des déploiements.

​
Variables d’environnement

VariablePar défautDescription
DOCUMENT_PROCESSING_MODEautoStratégie de traitement : auto (utiliser la vision si disponible), vision (toujours afficher), text (ne jamais afficher)
DOCUMENT_VISION_DPI150Résolution du rendu PDF en points par pouce. Les valeurs plus élevées produisent une meilleure qualité mais consomment plus de jetons
DOCUMENT_VISION_MAX_PAGES20Nombre maximum de pages PDF à afficher sous forme d’images. Les pages au-delà de cette limite reviennent à l’extraction de texte

​
Considérations sur le coût des jetons

Le contenu visuel consomme beaucoup plus de jetons que le texte brut. Comprendre les compromis de coûts vous aide à configurer le système de manière appropriée. Estimations approximatives :
ScénarioCoût approximatif en jetons
Une page PDF à 150 DPI1 000 — 2 000 jetons
PDF de 10 pages en mode vision10 000 — 20 000 jetons
Même PDF de 10 pages en texte uniquement2 000 — 5 000 jetons
Une image DOCX intégrée500 — 1 500 jetons
Pour les documents volumineux, le mode vision peut augmenter les coûts de 4 à 10 fois par rapport au traitement en texte uniquement. Utilisez DOCUMENT_VISION_MAX_PAGES pour limiter le nombre de pages rendues sous forme d’images, et envisagez d’utiliser le mode text pour les workflows sensibles aux coûts.

​
Conseils d’optimisation des coûts

  • Définissez DOCUMENT_VISION_MAX_PAGES à une limite raisonnable (par exemple, 10) pour un usage général
  • Réduisez DOCUMENT_VISION_DPI de 150 à 100 si la qualité d’image est acceptable — cela réduit la consommation de jetons d’environ 40%
  • Utilisez le mode text pour les documents où la mise en page n’a pas d’importance (par exemple, rapports en texte brut, feuilles de calcul)
  • Utilisez le mode vision de manière sélective pour les documents où la mise en page visuelle est critique (par exemple, factures, formulaires, diagrammes)

​
Décisions de conception et limitations

​
Pourquoi pas LibreOffice pour le rendu pleine page ?

LibreOffice peut produire des rendus de page pixel-parfaits des fichiers DOCX et PPTX, mais cela ajoute environ 4 GB à l’image Docker. À la place, FIM One extrait les images intégrées directement du XML du document en utilisant python-docx et python-pptx — les deux sont déjà des dépendances transitives de markitdown, donc cela n’ajoute aucun surcoût d’installation supplémentaire. Le compromis : Nous obtenons les images intégrées réelles en qualité complète mais perdons le contexte de mise en page. Les marqueurs positionnels [Figure N] aident le LLM à corréler le texte et les images, mais la relation spatiale est approximative plutôt qu’exacte.

​
Qu’est-ce qui est perdu sans LibreOffice ?

Élément perduImpact
Formatage du texte (gras, italique, tailles de police)Le LLM reçoit uniquement du texte brut
Positionnement spatial image-texteLes marqueurs [Figure N] se rapprochent mais ne montrent pas le placement exact
Graphiques générés par Office (non intégrés en tant qu’images)Les graphiques définis en XML ne sont pas extraits
En-têtes et pieds de page dans DOCXPartiellement préservés par markitdown

​
Vision PDF vs. Vision DOCX/PPTX

La qualité du traitement de la vision varie selon le format :
  • PDF — Traitement intelligent page par page. Les pages riches en texte extraient le contenu textuel plus les images intégrées séparément, ce qui est nettement plus efficace en termes de jetons. Les pages numérisées ou contenant uniquement des images (par exemple, documents photographiés, contrats numérisés) sont rendues sous forme d’images PNG pleine page pour une fidélité visuelle maximale. Cette approche adaptative équilibre automatiquement la qualité et le coût des jetons.
  • DOCX / PPTX — Contenu textuel plus images intégrées extraites. Bon pour la plupart des documents professionnels, mais la mise en page et le formatage ne sont pas préservés.
Recommandation : Pour les documents où la mise en page visuelle est importante (formulaires, factures, présentations avec graphiques complexes), exportez en PDF avant de télécharger.

​
Secours Automatique

Si un modèle est configuré avec support de la vision mais rejette réellement le contenu d’image à l’exécution, le système réessaie automatiquement la demande sans images de document. Les images téléchargées par l’utilisateur (par exemple, les captures d’écran jointes par l’utilisateur) sont conservées lors de la nouvelle tentative — seules les images dérivées de documents sont supprimées.
Ce mécanisme de secours empêche les défaillances de tâches causées par des paramètres de vision mal configurés. Si vous voyez un modèle revenir régulièrement au secours, vérifiez sa configuration de support de vision dans Admin > Models.

​
Garde-fous de sécurité

​
Protection de l’intégrité des fichiers

Lorsque l’agent ne peut pas lire un fichier (par exemple, un PDF basé sur des images sans vision activée), une barrière de sécurité au niveau du système empêche l’agent de substituer le contenu d’autres fichiers. Sans cette protection, l’agent pourrait lire un fichier accessible différent et présenter son contenu comme s’il provenait du document cible. La barrière de sécurité garantit que lorsqu’un fichier n’est pas lisible, l’agent signale honnêtement la limitation plutôt que de fabriquer une réponse à partir de sources non liées.

​
Guidance d’erreur descriptive

Lorsqu’un fichier ne peut pas être lu par l’outil read_uploaded_file, le message d’erreur inclut :
  • Le type de fichier détecté et la raison pour laquelle il n’a pas pu être traité
  • Une suggestion d’activer la vision sur le modèle si le fichier est basé sur une image
  • Les approches alternatives que l’utilisateur peut essayer (par exemple, exporter vers un format différent)
Cela aide les utilisateurs à comprendre et à résoudre les problèmes de traitement de fichiers sans essais et erreurs.

​
Meilleures pratiques

​
Pour les administrateurs

  • Activez la vision de manière sélective. N’activez supports_vision que sur les modèles qui supportent véritablement l’entrée d’images. Une mauvaise configuration gaspille des tokens dans le cycle de retry de secours.
  • Commencez par le mode auto. Le comportement par défaut est correct pour la plupart des déploiements — la vision est utilisée quand elle est bénéfique et disponible.
  • Surveillez l’utilisation des tokens. Après avoir activé la vision, observez le tableau de bord de consommation des tokens. Si les coûts augmentent de manière inattendue, ajustez DOCUMENT_VISION_MAX_PAGES ou DOCUMENT_VISION_DPI.
  • Utilisez l’image sandbox pré-construite. Le Dockerfile.sandbox inclut les packages de data-science courants (pdfplumber, Pillow, pandas, etc.) nécessaires pour l’exécution de code IA sur les documents. Construisez-la via docker compose ou manuellement avec docker build -f Dockerfile.sandbox -t fim-sandbox . pour assurer que l’exécution de code fonctionne dans les conteneurs --network=none.

​
Pour les utilisateurs finaux

  • Le PDF donne les meilleurs résultats. Lorsque la fidélité visuelle est importante, exportez vos documents Office en PDF avant de les télécharger.
  • Les feuilles de calcul conviennent telles quelles. Les fichiers XLSX sont extraits sous forme de tableaux structurés — la vision n’ajoute aucun avantage.
  • Les grands PDF peuvent être tronqués. Si votre document dépasse la limite DOCUMENT_VISION_MAX_PAGES, seules les N premières pages seront rendues sous forme d’images. Les pages restantes sont toujours disponibles sous forme de texte extrait.
  • La qualité de l’image est importante. Pour les téléchargements d’images autonomes, utilisez des originaux haute résolution si possible. Les images compressées ou basse résolution réduisent la capacité du modèle à extraire les détails.