Skip to main content

F-01 Vision

Brick F of the Enterprise AI Platform. Technology: vLLM serving open VLMs (Qwen2-VL, Llama 3.2 Vision, Pixtral) + LiteLLM vision routing to external providers. French version: ../../fr/bricks/F-01-vision.md.

Role and responsibilities​

  • Understand images, scans, screenshots and PDF pages rendered as images: captioning, OCR-free extraction, visual question answering, chart reading.
  • Normalize vision parameters across providers (detail level, max image size, image count per request) through the Capability Resolver of brick B.
  • POST /v1/multimodal/vision accepts detail (auto, low, high), forwarded as image_url.detail to the OpenAI compatible adapter; the local OCR adapter does not support it and the request gets a translated 422 parameter_unsupported.
  • Resize and tile images before the call so the token budget computed by the Context Manager is respected.

Position and interactions​

  • Execution path: realtime (synchronous request) and batch (document pipelines).
  • Media first goes through POST /v1/media (scan, classification, encryption) and F-11 multimodal DLP when the classification requires it.
  • The call is routed by the Model Router: local vLLM deployment for confidential data, LiteLLM to an external provider when policy allows.

Open source and developed parts​

  • Open source reused: vLLM (multimodal inputs), LiteLLM (image content parts), Pillow for resizing.
  • Developed in the platform: Vision endpoint, tiling and token estimation per provider, classification-aware routing, Usage Event emission.

Data model​

Control Plane tables (schema eai): eai.media, eai.multimodal_jobs, eai.usage_events, eai.price_cards.

Every tenant table has tenant_id uuid NOT NULL and a row level security policy on current_setting('app.tenant_id', true)::uuid. ClickHouse usage_events is the analytics replica of eai.usage_events (ReplacingMergeTree keyed by event_id).

Contract: contracts/v1/multimodal-contract.schema.json (schema_version 1.0). Usage is always reported with contracts/v1/usage-event.schema.json, audit with contracts/v1/audit-event.schema.json.

API endpoints​

MethodPath
POST/v1/media
POST/v1/multimodal/vision
GET/v1/media/{id}

POST /v1/media​

Request:

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

Response:

{
  "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​

Request:

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

Response:

{
  "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}​

Response:

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

SDK examples​

Python​

from enterprise_ai import EnterpriseAI

client = EnterpriseAI(base_url="<control-plane-url>", api_key="eai_live_xxx", tenant="acme", locale="en")
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: "en" });
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.ENGLISH)
    .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("en"))
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​

Environment variables: EAI_VISION_MODEL, EAI_LITELLM_URL.

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

Security​

  • Images are decoded in a sandboxed worker with pixel limits (decompression bomb protection).
  • Confidential or secret media can only be sent to models whose residency and classification ceiling allow it.
  • Tenant resolved from the credential, never from the body; PostgreSQL row level security on every tenant table.
  • Every mutation and policy decision writes a hash chained audit event (G-11).
  • Errors use the standard envelope with message_i18n en and fr.

Observability​

  • Span gen_ai.vision with the attribute gen_ai.usage.input_tokens.
  • Opik trace span with image thumbnails redacted according to DLP findings.
  • W3C traceparent propagated, X-Request-Id returned, spans carry eai.tenant_id, eai.project, eai.agent_id, eai.run_id.

FinOps units​

  • usage_type vision: units images, image resolution (in labels), input_tokens and output_tokens. Image tokens are computed with the provider tile formula for the estimate, measured from the provider response.

Failure modes and resilience​

  • Provider rejects the image size -> automatic downscale then one retry.
  • Local VLM saturated -> fallback chain defined in /v1/routes, only to models allowed for the classification.
  • Model without vision capability -> error effort_not_supported style explicit rejection by the Capability Resolver, never a silent drop of the image.

Standalone adoption​

A client of a client can call only POST /v1/media and POST /v1/multimodal/vision with an API key scoped models:invoke, without agents or RAG.

Acceptance tests​

  1. An invoice image returns structured fields and a Usage Event with images=1.
  2. A secret-classified image routed to an external provider is denied with policy_denied.
  3. A 20000x20000 image is rejected with validation_error before any model call.

Implementation roadmap