đŹđ§ 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 tableauimagesd'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
LlmMessageportant unMultiModalContentavec images est composé en payload structuré par chaque provider dont les capacités déclarentVision(la base partagéeOpenAICompatibleProviderBasefait la traduction une fois).AddOrkeonMultiModalactive 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.