Aller au contenu principal

F-01 Vision

Brique F de la plateforme Enterprise AI. Technologie : vLLM sert des VLM ouverts (Qwen2-VL, Llama 3.2 Vision, Pixtral) + routage vision LiteLLM vers les fournisseurs externes. Version anglaise : ../../en/bricks/F-01-vision.md.

Rôle et responsabilités​

  • Comprendre images, scans, captures d'écran et pages PDF rendues en images : description, extraction sans OCR, questions visuelles, lecture de graphiques.
  • Normaliser les paramètres de vision entre fournisseurs (niveau de détail, taille max, nombre d'images par requête) via le Capability Resolver de la brique B.
  • POST /v1/multimodal/vision accepte detail (auto, low, high), transmis comme image_url.detail à l'adaptateur compatible OpenAI ; l'adaptateur OCR local ne le prend pas en charge et la requête reçoit un refus 422 traduit parameter_unsupported.
  • Redimensionner et découper les images avant l'appel pour respecter le budget de tokens calculé par le Context Manager.

Position et interactions​

  • Chemin d'exécution : temps réel (requête synchrone) et batch (pipelines documentaires).
  • Le média passe d'abord par POST /v1/media (scan, classification, chiffrement) puis par la DLP multimodale F-11 si la classification l'exige.
  • L'appel est routé par le Model Router : déploiement vLLM local pour les données confidentielles, LiteLLM vers un fournisseur externe si la politique l'autorise.

Part open source et part développée​

  • Open source réutilisé : vLLM (entrées multimodales), LiteLLM (parties de contenu image), Pillow pour le redimensionnement.
  • Développé dans la plateforme : Endpoint vision, découpage et estimation de tokens par fournisseur, routage selon la classification, émission des Usage Events.

Modèle de données​

Tables du Control Plane (schéma eai) : eai.media, eai.multimodal_jobs, eai.usage_events, eai.price_cards.

Chaque table de tenant a tenant_id uuid NOT NULL et une politique de sécurité au niveau des lignes sur current_setting('app.tenant_id', true)::uuid. ClickHouse usage_events est la réplique analytique de eai.usage_events (ReplacingMergeTree par event_id).

Contrat : contracts/v1/multimodal-contract.schema.json (schema_version 1.0). L'usage est toujours remonté avec contracts/v1/usage-event.schema.json, l'audit avec contracts/v1/audit-event.schema.json.

Endpoints d'API​

MéthodeChemin
POST/v1/media
POST/v1/multimodal/vision
GET/v1/media/{id}

POST /v1/media​

Requête :

{
  "filename": "invoice-scan.png",
  "mime_type": "image/png",
  "operation": "vision_understanding",
  "classification": "internal",
  "content_base64": "iVBORw0KGgo..."
}

Réponse :

{
  "media_id": "med_01HZX3K9",
  "media_type": "image",
  "mime_type": "image/png",
  "size_bytes": 482113,
  "resolution": "1654x2339",
  "classification": "internal",
  "dlp": {
    "status": "clean",
    "findings": 0
  },
  "storage": {
    "uri": "s3://eai-media/tenant/med_01HZX3K9",
    "encrypted": true
  }
}

POST /v1/multimodal/vision​

Requête :

{
  "model": "vision-default",
  "media_id": "med_01HZX3K9",
  "prompt": "Extract the invoice number, date and total.",
  "dlp_mode": "detect"
}

Réponse :

{
  "job_id": "mmj_7Q2",
  "status": "succeeded",
  "output": {
    "text": "Invoice INV-2291, 2026-10-02, 1240.00 EUR"
  },
  "usage": {
    "images": 1,
    "input_tokens": 1105,
    "output_tokens": 38
  },
  "cost": {
    "estimated": {
      "amount": "0.0042",
      "currency": "EUR"
    },
    "measured": {
      "amount": "0.0039",
      "currency": "EUR"
    },
    "billed": null
  }
}

GET /v1/media/{id}​

Réponse :

{
  "media_id": "med_01HZX3K9",
  "media_type": "image",
  "operation": "upload",
  "mime_type": "image/png",
  "classification": "internal",
  "created_at": "2026-10-29T10:00:00Z"
}

Exemples SDK​

Python​

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_live_xxx", tenant="acme", locale="fr")
client.multimodal.upload(open("invoice-scan.png", "rb").read(), "invoice-scan.png", "image/png", classification="internal")
client.multimodal.vision.analyze("Extract the invoice number, date and total.", media_id="med_01HZX3K9", model="vision-default")
client.multimodal.get_media(media_id="med_01HZX3K9")

TypeScript​

import { EnterpriseAI } from "@enterprise-ai/sdk";

const client = new EnterpriseAI({ baseUrl: "<control-plane-url>", apiKey: process.env.EAI_API_KEY, tenant: "acme", locale: "fr" });
await client.media.upload({ file: new Blob([await readFile("invoice-scan.png")], { type: "image/png" }), filename: "invoice-scan.png", operation: "vision_understanding", classification: "internal" });
await client.multimodal.vision({ model: "vision-default", media_id: "med_01HZX3K9", prompt: "Extract the invoice number, date and total." });
await client.media.get("med_01HZX3K9");

Java​

EnterpriseAIClient client = EnterpriseAIClient.builder()
    .baseUrl("<control-plane-url>")
    .apiKey(System.getenv("EAI_API_KEY"))
    .tenant("acme")
    .locale(Locale.FRENCH)
    .build();
client.media().upload(Map.of("content_base64", Base64.getEncoder().encodeToString(Files.readAllBytes(Path.of("invoice-scan.png"))), "mime_type", "image/png", "filename", "invoice-scan.png", "classification", "internal"));
client.multimodal().vision(Map.of("model", "vision-default", "media_id", "med_01HZX3K9", "prompt", "Extract the invoice number, date and total."));
client.media().get("med_01HZX3K9");

Go​

client, err := eai.NewClient(eai.WithBaseURL("<control-plane-url>"), eai.WithAPIKey(os.Getenv("EAI_API_KEY")), eai.WithTenant("acme"), eai.WithLocale("fr"))
if err != nil { log.Fatal(err) }
ctx := context.Background()
_, err = client.Media.Upload(ctx, map[string]any{"content_base64": base64.StdEncoding.EncodeToString(scan), "mime_type": "image/png", "filename": "invoice-scan.png", "classification": "internal"})
_, err = client.Multimodal.Vision(ctx, map[string]any{"model": "vision-default", "media_id": "med_01HZX3K9", "prompt": "Extract the invoice number, date and total."})
_, err = client.Media.Get(ctx, "med_01HZX3K9")

// worker package: run a media worker consuming multimodal jobs
w, err := worker.New(worker.Config{Source: jobs, Handler: handle, Client: client, Concurrency: 2})
if err != nil { log.Fatal(err) }
err = w.Run(ctx)

Configuration​

Variables d'environnement : EAI_VISION_MODEL, EAI_LITELLM_URL.

Clés de valeurs Helm (deploy/helm/enterprise-ai/values.yaml) : controlPlane.config.EAI_VISION_MODEL, vllm.models[].multimodal, litellm.config.model_list.

Sécurité​

  • Les images sont décodées dans un worker isolé avec limite de pixels (protection contre les bombes de décompression).
  • Les médias confidentiels ou secrets ne partent que vers des modèles dont la résidence et le plafond de classification l'autorisent.
  • Tenant déduit de l'identifiant d'accès, jamais du corps ; sécurité au niveau des lignes PostgreSQL sur chaque table de tenant.
  • Chaque mutation et décision de politique écrit un événement d'audit chaîné par hachage (G-11).
  • Les erreurs utilisent l'enveloppe standard avec message_i18n en et fr.

Observabilité​

  • Span gen_ai.vision avec l'attribut gen_ai.usage.input_tokens.
  • Span de trace Opik avec miniatures d'images masquées selon les résultats DLP.
  • traceparent W3C propagé, X-Request-Id renvoyé, les spans portent eai.tenant_id, eai.project, eai.agent_id, eai.run_id.

Unités FinOps​

  • usage_type vision : unités images, résolution (dans labels), input_tokens et output_tokens. Les tokens image sont calculés avec la formule de tuiles du fournisseur pour l'estimation, mesurés depuis la réponse du fournisseur.

Modes de défaillance et résilience​

  • Le fournisseur refuse la taille d'image -> réduction automatique puis une nouvelle tentative.
  • VLM local saturé -> chaîne de fallback définie dans /v1/routes, uniquement vers des modèles autorisés pour la classification.
  • Modèle sans capacité vision -> rejet explicite par le Capability Resolver, jamais de suppression silencieuse de l'image.

Adoption autonome​

Un client de client peut appeler uniquement POST /v1/media et POST /v1/multimodal/vision avec une clé API de scope models:invoke, sans agents ni RAG.

Tests d'acceptation​

  1. Une image de facture renvoie des champs structurés et un Usage Event avec images=1.
  2. Une image classée secret routée vers un fournisseur externe est refusée avec policy_denied.
  3. Une image de 20000x20000 est rejetée avec validation_error avant tout appel de modèle.

Feuille de route d'implémentation