Multimodal

Élargissez votre contexte en envoyant images, audio et documents via desadaptateurs multimodaux natifs.

Comment Ça Marche

Le support multimodal dans Orka AI repose sur les types ChatMessage et ContentPart. Au lieu d'envoyer un prompt texte simple, vous composez des messages avec des parties de contenu mixtes : texte, images (URL ou base64) et audio.

Contenu Textuel

Texte brut standard UTF-8 pour les prompts et instructions système.

text

Vision Distante

Images via URL. Supporte le contrôle de granularité (auto, low, high).

image_url

Image Embarquée

Encodage binaire direct (PNG, JPEG, WebP). Idéal pour les données transitoires.

image_base64

Données Audio

Traitement natif WAV/MP3 pour l'analyse sonore ou la voix (OpenAI).

audio

# Analyse d'Image (URL)

La façon la plus simple d'analyser une image est de passer son URL. Le LLM téléchargera et traitera l'image automatiquement. Cela fonctionne avec OpenAI (GPT-4o, GPT-4o-mini) et Anthropic (Claude 3.5 Sonnet, Claude 3 Opus).

import { createOrka } from '@orka-js/core';
import { OpenAIAdapter } from 'orkajs';
 
const orka = createOrka({
  llm: new OpenAIAdapter({
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-4o'  // Must use a vision-capable model
  })
});
 
const result = await orka.getLLM().generate('', {
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'What do you see in this image? Describe it in detail.' },
        {
          type: 'image_url',
          image_url: {
            url: 'https://example.com/photo.jpg',
            detail: 'high'  // 'auto' | 'low' | 'high'
          }
        }
      ]
    }
  ]
});
 
console.log(result.content);
// "The image shows a sunset over the ocean with..."

`auto`

Le modèle décide du niveau de détail en fonction de la taille de l'image. Meilleur choix par défaut.

`low`

Plus rapide et moins cher. Utilise une miniature 512×512. Bon pour la classification simple.

`high`

Analyse en pleine résolution. Idéal pour l'OCR, les descriptions détaillées et la lecture de petits textes.

# Analyse d'Image (Base64)

Pour les fichiers locaux ou les images générées dynamiquement, encodez-les en base64. Cela évite le besoin d'une URL publique et fonctionne avec OpenAI et Anthropic.

import { readFileSync } from 'fs';
 
// Read local image file
const imageBuffer = readFileSync('./screenshot.png');
const base64Image = imageBuffer.toString('base64');
 
const result = await orka.getLLM().generate('', {
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Extract all text from this screenshot.' },
        {
          type: 'image_base64',
          data: base64Image,
          mimeType: 'image/png'  // 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp'
        }
      ]
    }
  ]
});
 
console.log(result.content);

# Images Multiples

Vous pouvez envoyer plusieurs images dans un seul message pour la comparaison, l'analyse ou le traitement de documents multi-pages.

const result = await orka.getLLM().generate('', {
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Compare these two UI designs. Which one is better and why?' },
        {
          type: 'image_url',
          image_url: { url: 'https://example.com/design-a.png', detail: 'high' }
        },
        {
          type: 'image_url',
          image_url: { url: 'https://example.com/design-b.png', detail: 'high' }
        }
      ]
    }
  ]
});

# Entrée Audio (OpenAI)

Les modèles GPT-4o d'OpenAI supportent l'entrée audio. Envoyez des données audio au format WAV ou MP3 pour la transcription, l'analyse ou l'interaction vocale.

import { readFileSync } from 'fs';
 
const audioBuffer = readFileSync('./recording.wav');
const base64Audio = audioBuffer.toString('base64');
 
const result = await orka.getLLM().generate('', {
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Transcribe this audio and summarize the key points.' },
        {
          type: 'audio',
          data: base64Audio,
          format: 'wav'  // 'wav' | 'mp3'
        }
      ]
    }
  ]
});
 
console.log(result.content);
// "The speaker discusses three main topics: ..."

⚠️ Limitations Audio

L'entrée audio est actuellement supportée uniquement par OpenAI (modèles GPT-4o)
Anthropic (Claude) supporte l'entrée audio à partir de Calude 4.6 Sonnet
Les meilleurs modèles Gemini pour l'audio sont (3.1 Pro) & (3 Flash)
La durée maximale de l'audio dépend du modèle et de votre plan API

# Avec System Prompt

Combinez le contenu multimodal avec des system prompts pour des tâches d'analyse spécialisées.

const result = await orka.getLLM().generate('', {
  messages: [
    {
      role: 'system',
      content: 'You are an expert radiologist. Analyze medical images with precision and provide structured reports.'
    },
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Please analyze this X-ray image.' },
        {
          type: 'image_url',
          image_url: { url: 'https://example.com/xray.jpg', detail: 'high' }
        }
      ]
    }
  ]
});

# Conversations Multi-tours

Construisez des conversations multi-tours qui font référence aux images partagées précédemment.

const result = await orka.getLLM().generate('', {
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Here is a photo of my living room.' },
        { type: 'image_url', image_url: { url: 'https://example.com/room.jpg' } }
      ]
    },
    {
      role: 'assistant',
      content: 'I can see a modern living room with a gray sofa, wooden coffee table...'
    },
    {
      role: 'user',
      content: 'What color should I paint the walls to complement the furniture?'
    }
  ]
});

Compatibilité des Fournisseurs

Capacité Média	Contexte Technique	Disponibilité
Image (URL / Base64)	Traitement vision standard pour OCR & analyse.	OpenAI Anthropic Mistral Ollama
Traitement Audio	Analyse vocale native et reconnaissance sonore.	OpenAI Anthropic Mistral Ollama
Support Multi-Images	Vision comparative ou analyse de documents multi-pages.	OpenAI Anthropic Mistral Ollama

Cas d'Usage

OCR de Documents

Extraction haute précision de textes à partir de scans et notes manuscrites via Vision LLM.

Vision / Data

Analyse UI/UX

Audit de captures d'écran pour l'accessibilité, la cohérence design et le mapping de composants.

Vision / Design

Extraction de Graphiques

Convertit les graphiques visuels et tableaux complexes en JSON structuré pour analyse.

Vision / Analytics

Intelligence Vocale

Transcription audio native avec résumé contextuel de réunions et mémos vocaux.

Audio / NLP

Types TypeScript

import type { ChatMessage, ContentPart } from 'orkajs';
 
// ChatMessage
interface ChatMessage {
  role: 'system' | 'user' | 'assistant';
  content: string | ContentPart[];
}
 
// ContentPart — union type
type ContentPart =
  | { type: 'text'; text: string }
  | { type: 'image_url'; image_url: { url: string; detail?: 'auto' | 'low' | 'high' } }
  | { type: 'image_base64'; data: string; mimeType: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp' }
  | { type: 'audio'; data: string; format: 'wav' | 'mp3' };

Bonnes Pratiques

1. Choisissez le Bon Niveau de Détail

Utilisez 'low' pour les tâches de classification simples pour économiser des tokens et des coûts. Utilisez 'high' pour l'OCR et l'analyse détaillée.

2. Optimisez la Taille des Images

Redimensionnez les grandes images avant l'envoi pour réduire l'utilisation de tokens. La plupart des modèles fonctionnent bien avec des images de moins de 2048×2048.

3. Utilisez Base64 pour les Données Sensibles

Pour les images privées ou sensibles, utilisez l'encodage base64 au lieu des URLs pour éviter d'exposer les données publiquement.

Multimodal

Pour des workflows multimodaux avancés, utilisez le package dédié @orka-js/multimodal. Il fournit des agents spécialisés, des utilitaires pour le traitement vision et audio, et des workflows cross-modaux.

npm install @orka-js/multimodal

# Utilitaires Vision

Fonctions haut niveau pour les tâches vision courantes : analyse d'image, description, OCR et comparaison.

import { analyzeImage, describeImage, extractTextFromImage, compareImages } from '@orka-js/multimodal';
import { OpenAIAdapter } from '@orka-js/openai';
 
const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY!, model: 'gpt-4o' });
 
// Analyze an image
const analysis = await analyzeImage(llm, {
  type: 'url',
  url: 'https://example.com/photo.jpg'
}, { prompt: 'What emotions are expressed in this image?' });
 
console.log(analysis.analysis);
// "The image conveys a sense of joy and celebration..."
 
// Get structured description
const description = await describeImage(llm, {
  type: 'url',
  url: 'https://example.com/photo.jpg'
});
 
console.log(description);
// { description: "A sunset over the ocean", objects: ["sun", "ocean", "clouds"], colors: ["orange", "purple"], scene: "outdoor" }
 
// Extract text (OCR)
const ocr = await extractTextFromImage(llm, {
  type: 'base64',
  data: base64Image,
  mimeType: 'image/png'
});
 
console.log(ocr.text);
// "Invoice #12345\nDate: 2024-01-15..."
 
// Compare two images
const comparison = await compareImages(llm, 
  { type: 'url', url: 'https://example.com/before.jpg' },
  { type: 'url', url: 'https://example.com/after.jpg' }
);
 
console.log(comparison.analysis);
// "The main differences are..."

# Utilitaires Audio (Whisper & TTS)

Transcrivez l'audio avec OpenAI Whisper et générez de la parole avec TTS. L'adaptateur OpenAI inclut maintenant des méthodes audio intégrées.

import { OpenAIAdapter } from '@orka-js/openai';
import { transcribeAudio, synthesizeSpeech } from '@orka-js/multimodal';
import { readFileSync, writeFileSync } from 'fs';
 
const adapter = new OpenAIAdapter({
  apiKey: process.env.OPENAI_API_KEY!,
  whisperModel: 'whisper-1',
  ttsModel: 'tts-1',
  ttsVoice: 'nova'
});
 
// Direct adapter methods
const transcription = await adapter.transcribe(
  readFileSync('./audio.wav'),
  { language: 'en', responseFormat: 'verbose_json' }
);
 
console.log(transcription.text);
// "Hello, this is a test recording..."
console.log(transcription.words);
// [{ word: "Hello", start: 0.0, end: 0.5 }, ...]
 
// Text-to-Speech
const audioBuffer = await adapter.textToSpeech(
  'Welcome to OrkaJS! This is a test of the text-to-speech feature.',
  { voice: 'nova', responseFormat: 'mp3', speed: 1.0 }
);
 
writeFileSync('./output.mp3', Buffer.from(audioBuffer));
 
// Using multimodal utilities
const result = await transcribeAudio(adapter, {
  type: 'base64',
  data: base64Audio,
  format: 'wav'
}, { includeTimestamps: true });
 
const speech = await synthesizeSpeech(adapter, 'Hello world!', {
  voice: 'alloy',
  format: 'mp3'
});

# VisionAgent

Un agent spécialisé pour les tâches de compréhension d'image avec support du traitement par lots.

import { VisionAgent } from '@orka-js/multimodal';
import { OpenAIAdapter } from '@orka-js/openai';
 
const agent = new VisionAgent({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY!, model: 'gpt-4o' }),
  systemPrompt: 'You are an expert image analyst.',
  detail: 'high',
  temperature: 0.3
});
 
// Ask questions about images
const answer = await agent.ask(
  { type: 'url', url: 'https://example.com/chart.png' },
  'What trend does this chart show?'
);
 
// Run batch tasks
const results = await agent.runTasks([
  { type: 'analyze', image: { type: 'url', url: 'https://example.com/1.jpg' } },
  { type: 'ocr', image: { type: 'url', url: 'https://example.com/document.png' } },
  { type: 'describe', image: { type: 'url', url: 'https://example.com/photo.jpg' } }
]);
 
results.forEach(r => console.log(r.task, r.result));

# AudioAgent

Un agent spécialisé pour le traitement audio : transcription, text-to-speech et workflows audio.

import { AudioAgent } from '@orka-js/multimodal';
import { OpenAIAdapter } from '@orka-js/openai';
 
const agent = new AudioAgent({
  adapter: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
  defaultLanguage: 'en',
  defaultVoice: 'nova',
  defaultFormat: 'mp3'
});
 
// Transcribe audio
const transcription = await agent.transcribe({
  type: 'url',
  url: 'https://example.com/meeting.mp3'
});
 
console.log(transcription.result);
// "In today's meeting, we discussed..."
 
// Generate speech
const speech = await agent.speak('Hello, how can I help you today?');
// speech.result is an ArrayBuffer
 
// Transcribe and process
const processed = await agent.transcribeAndProcess(
  { type: 'base64', data: audioBase64 },
  async (text) => {
    // Process the transcription (e.g., summarize with LLM)
    return `Summary: ${text.slice(0, 100)}...`;
  }
);

# MultimodalAgent

Combine les capacités vision et audio pour des workflows multimodaux complexes. Transcrit automatiquement l'audio et traite les images ensemble.

import { MultimodalAgent } from '@orka-js/multimodal';
import { OpenAIAdapter } from '@orka-js/openai';
 
const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY!, model: 'gpt-4o' });
 
const agent = new MultimodalAgent({
  llm,
  audioAdapter: llm, // OpenAI adapter supports both
  systemPrompt: 'You are a helpful multimodal assistant.',
  maxTokens: 2048
});
 
// Process mixed inputs
const result = await agent.process({
  text: 'Analyze this image and audio together.',
  images: [{ type: 'url', url: 'https://example.com/presentation.png' }],
  audio: [{ type: 'base64', data: audioBase64 }]
});
 
console.log(result.response);
// "Based on the presentation slide and the audio explanation..."
console.log(result.transcriptions);
// ["The speaker explains that..."]
 
// Ask with context
const answer = await agent.ask(
  'What are the key points?',
  {
    images: [{ type: 'url', url: 'https://example.com/slide1.png' }],
    audio: [{ type: 'base64', data: voiceNote }]
  }
);
 
// Analyze multiple images
const imageAnalysis = await agent.analyzeImages(
  [
    { type: 'url', url: 'https://example.com/before.jpg' },
    { type: 'url', url: 'https://example.com/after.jpg' }
  ],
  'Compare these two images and describe the changes.'
);

✅ Détection des Capacités

Utilisez les fonctions helper pour vérifier si un adaptateur supporte des capacités spécifiques :

import { isVisionCapable, isAudioCapable } from '@orka-js/multimodal';
 
if (isVisionCapable(llm)) {
  // Safe to use vision features
  const result = await analyzeImage(llm, image);
}
 
if (isAudioCapable(adapter)) {
  // Safe to use audio features
  const transcription = await transcribeAudio(adapter, audio);
}