Table of Contents

🇬🇧 English version

Contenu multi-modal (vision)

Les contenus image circulent de bout en bout, des abstractions MultiModalContent (Domain) jusqu'aux payloads des providers — blocs de contenu Anthropic, parts de contenu OpenAI (Ă©crites une seule fois pour les quatorze providers compatibles OpenAI) et tableau images d'Ollama. Ce guide dĂ©crit le flux, les formats Ă©mis sur le fil, l'activation opt-in et les limites.

Vue d'ensemble du flux

MultiModalContent (Domain)            LlmMessage (Domain)              Payload provider (Infrastructure)
┌──────────────────────────┐   ┌───────────────────────────────┐   ┌─────────────────────────────────────┐
│ TextContentPart          │   │ Role = "user"                 │   │ Anthropic : blocs "text"/"image"    │
│ ImageContentPart         │ → │ Content = repli texte         │ → │ OpenAI    : parts "text"/"image_url"│
│ (bytes ou URI)           │   │ MultiModalContent = parts     │   │ Ollama    : content + "images"      │
└──────────────────────────┘   └───────────────────────────────┘   └─────────────────────────────────────┘
  • MultiModalContent (value object immuable, Orkeon.Domain.SharedKernel.ValueObjects.Content) porte les parts texte/image/audio/fichier.
  • LlmMessage.User(MultiModalContent) crĂ©e un message utilisateur qui transporte les parts et un repli texte (Content = ToTextOnly()) pour les providers sans vision.
  • ContentConverter (Orkeon.Infrastructure.LLMs.Converters) compose les fragments de payload propres Ă  chaque API (ToAnthropicContentBlocks, ToOpenAIContentParts, ToOllamaMessage).

Composer et envoyer une image

using Orkeon.Domain.SharedKernel.ValueObjects;
using Orkeon.Domain.SharedKernel.ValueObjects.Content;

// 1. Depuis des bytes (envoyés en base64)
var content = MultiModalContent.Empty()
    .AddText("Décris ce graphique")
    .AddImage(ImageContentPart.FromBytes(pngBytes, "image/png"));

// 2. Ou depuis une URL http(s) (le vendeur tĂ©lĂ©charge l'image — pas sur Ollama, voir plus bas)
var contentFromUrl = MultiModalContent.Empty()
    .AddText("Que montre cette photo ?")
    .AddImage(ImageContentPart.FromUri(new Uri("https://example.com/photo.jpg"), "image/jpeg"));

// 3. Envoi via n'importe quel ILlmProvider qui déclare Vision
var response = await provider.ChatAsync([LlmMessage.User(content)]);

Charger une image depuis le VFS (IMultiModalContentLoader)

Le chargeur lit le fichier via IFileSystemService (chemins virtuels, droits auditĂ©s), infĂšre le type MIME de l'extension et valide les contraintes configurĂ©es (Orkeon:MultiModal — taille max, formats autorisĂ©s) :

var loader = provider.GetRequiredService<IMultiModalContentLoader>();
var image = await loader.LoadImageAsync("/workspace/chart.png");

var content = MultiModalContent.Empty()
    .AddText("Analyse ce graphique")
    .AddImage(image);

Erreurs claires garanties :

Situation Exception
Extension non supportée (.bmp, .tiff, 
) NotSupportedException (liste les extensions supportées)
Fichier introuvable FileNotFoundException
Hors mount / droits insuffisants FileAccessDeniedException
Taille > MaxImageSizeBytes ou format exclu par les options InvalidOperationException
Orkeon:MultiModal:Enabled = false InvalidOperationException

Formats émis sur le fil

Anthropic (API Messages) — blocs de contenu :

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Décris ce graphique" },
    { "type": "image", "source": { "type": "base64", "media_type": "image/png", "data": "iVBOR..." } }
  ]
}

Les images par URL http(s) utilisent "source": {"type": "url", "url": "https://..."}. Les data URLs base64 (data:image/png;base64,...) sont dépaquetées en source base64.

OpenAI (Chat Completions) — parts de contenu :

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Décris ce graphique" },
    { "type": "image_url", "image_url": { "url": "data:image/png;base64,iVBOR..." } }
  ]
}

Les images par URL http(s) ou data URL passent telles quelles dans image_url.url ; les bytes bruts sont encodĂ©s en data URL base64. Les mĂȘmes parts sont Ă©crites par chaque provider compatible OpenAI (OpenAI, Azure OpenAI, DeepSeek, Gemini, Grok, HuggingFace, Kimi, Mammouth, MiniMax, Mistral, OpenRouter, Qwen, Together AI, Z.AI).

Ollama (/api/chat) — pas de parts de contenu : le message garde une chaĂźne content simple et les images voyagent en chaĂźnes base64 nues (sans prĂ©fixe data:, sans type de mĂ©dia) :

{ "role": "user", "content": "Décris ce graphique", "images": ["iVBOR..."] }

Un message portant une part non textuelle fait passer Ollama de /api/generate Ă  /api/chat. Ollama ne tĂ©lĂ©charge jamais d'URL distante : une image rĂ©fĂ©rencĂ©e seulement par URL est ignorĂ©e avec un avertissement structurĂ© (
 image(s) referenced by URL) — chargez plutĂŽt les octets. Ollama ne prend ni audio ni fichier : une telle part lĂšve NotSupportedException avant tout envoi, comme chez Anthropic et les providers compatibles OpenAI.

Activation (opt-in)

Le sous-systùme reste opt-in — voir Sous-systùmes opt-in :

services.AddOrkeonFileSystem(configuration);   // prérequis du loader (VFS)
services.AddOrkeonMultiModal(configuration);   // lie Orkeon:MultiModal
// ou : services.AddOrkeonMultiModal();        // options par défaut

Options (Orkeon:MultiModal, MultiModalOptions) : Enabled (true), MaxImageSizeBytes (20 Mo par défaut), SupportedImageFormats (png, jpeg, gif, webp par défaut), MaxAudioDurationSeconds (300), SupportedAudioFormats (wav, mp3, ogg). Aucune image n'est redimensionnée : une image au-delà de la taille limite échoue à la validation.

L'envoi des payloads vision par les providers ne dépend pas de l'activation DI : un LlmMessage portant un MultiModalContent avec images est composé en payload structuré par chaque provider dont les capacités déclarent Vision (la base partagée OpenAICompatibleProviderBase fait la traduction une fois). AddOrkeonMultiModal active la validation (IContentValidationService) et le chargeur VFS (IMultiModalContentLoader).

Providers et formats supportés

Capacité Supporté
Providers vision (capacité Vision = true) Les 16 : Anthropic, OpenAI, Azure OpenAI, DeepSeek (natif sur deepseek-flash depuis V4.1 ; deepseek-v4-pro reste texte seul), Gemini, Grok, HuggingFace, Kimi, MiniMax (par modÚle : le MiniMax-M3 par défaut voit, MiniMax-M2 non), Mistral, Ollama (images natif, par modÚle), Qwen, Together AI (par modÚle : le zai-org/GLM-5.3-Flash par défaut voit), Z.AI (par modÚle : le glm-5.3-flashx par défaut et glm-5.3-flash voient, glm-5.2 non), OpenRouter (par modÚle) et Mammouth AI (par modÚle, d'aprÚs la liste text, image du vendeur)
ModĂšle sans vision derriĂšre un provider vision Le refus du vendeur lui-mĂȘme, attribuĂ© par CapabilityMismatchHint sur les providers compatibles OpenAI et Ollama (la capacitĂ© est dĂ©clarĂ©e par provider, la rĂ©alitĂ© est par modĂšle)
Provider sans la capacité (un ILlmProvider tiers qui ne déclare rien) Dégradation vers le repli texte LlmMessage.Content, avec un avertissement structuré nommant les parts abandonnées
Types MIME image image/png, image/jpeg, image/gif, image/webp
Sources d'image Bytes bruts (base64), URL http(s), data URL base64
Audio / fichiers vers les providers Non supportĂ© — NotSupportedException explicite sur Anthropic, les providers compatibles OpenAI et Ollama

Sur Anthropic et les providers compatibles OpenAI, un type MIME non supportĂ© (ex. image/bmp), un schĂ©ma d'URI non supportĂ© (ex. ftp://) ou une part audio/fichier dans un payload vision lĂšvent une exception explicite — aucune dĂ©gradation silencieuse en texte. Ollama refuse une part audio/fichier de la mĂȘme façon.

Interop Microsoft.Extensions.AI

Orkeon convertit les parts image/audio/fichier vers les types natifs de Microsoft.Extensions.AI DataContent (octets) et UriContent (URI), et inversement, au sein d'Orkeon.Infrastructure ; le convertisseur est interne, ce n'est pas une API Ă  appeler.

Tests

  • ContentConverterPayloadTests — composition des blocs Anthropic / parts OpenAI, chargement VFS, erreurs sur formats non supportĂ©s.
  • AnthropicVisionPayloadTests / OpenAIVisionPayloadTests / ProviderVisionPayloadTests (chaque provider compatible OpenAI) / OllamaChatEndpointTests — vĂ©rification du JSON rĂ©ellement Ă©mis sur le fil (handler HTTP factice).
  • MultiModalContentLoaderTests — contraintes d'options (taille, formats, Enabled).
  • OptInSubsystemsRegistrationTests — enregistrement DI opt-in.