Résilience

Construisez des applications IA tolérantes aux pannes avec la logique de retry et les chaînes de fallback multi-provider.

Pourquoi la Résilience ?

Les APIs LLM peuvent échouer à cause de limites de débit, problèmes réseau ou pannes de fournisseur. Les patterns de résilience garantissent que votre application continue de fonctionner même quand des appels API individuels échouent. Orka fournit deux patterns clés : retry automatique avec backoff exponentiel, et chaînes de fallback multi-fournisseur.

# ResilientLLM

ResilientLLM enveloppe n'importe quel adaptateur LLM avec une logique de retry automatique. Il implémente l'interface LLMAdapter, vous pouvez donc l'utiliser comme remplacement direct.

import { ResilientLLM } from 'orkajs/resilience';
import { OpenAIAdapter } from 'orkajs/adapters/openai';
 
const llm = new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! });
 
// Wrap with automatic retry
const resilientLLM = new ResilientLLM(llm, {
  maxRetries: 3,              // Maximum retry attempts
  initialDelayMs: 1000,       // First retry after 1 second
  backoffMultiplier: 2,       // Double delay each retry: 1s, 2s, 4s
  maxDelayMs: 30000,          // Cap delay at 30 seconds
  retryableErrors: [          // Only retry these errors
    'rate limit', 
    '429', 
    '503', 
    'ECONNRESET',
    'timeout'
  ],
  onRetry: (error, attempt, delayMs) => {
    console.log(`Retry ${attempt}/3 in ${delayMs}ms: ${error.message}`);
  },
});
 
// Use as normal LLM
const result = await resilientLLM.generate('What is TypeScript?');
 
// Or use with Orka
const orka = createOrka({
  llm: resilientLLM,
  vectorDB: new MemoryVectorDB(),
});

- Options ResilientLLM

maxRetries: numberdefault: 3

Nombre maximum de tentatives de retry avant d'abandonner.

initialDelayMs: numberdefault: 1000

Délai avant le premier retry en millisecondes.

backoffMultiplier: numberdefault: 2

Multiplie le délai par ce facteur après chaque retry. 2 = backoff exponentiel.

retryableErrors: string[]

Ne retry que si le message d'erreur contient une de ces chaînes. Les erreurs non correspondantes échouent immédiatement.

onRetry?: (error, attempt, delayMs) => void

Callback déclenché avant chaque retry. Utilisez pour le logging ou monitoring.

# Helper withRetry()

Pour une logique de retry ponctuelle sur n'importe quelle fonction async, utilisez le helper withRetry() :

import { withRetry } from 'orkajs/resilience';
 
const result = await withRetry(
  () => orka.ask({ question: 'My question', knowledge: 'docs' }),
  {
    maxRetries: 3,
    initialDelayMs: 1000,
    backoffMultiplier: 2,
    maxDelayMs: 30000,
    retryableErrors: ['rate limit', '429', '503'],
    onRetry: (error, attempt) => {
      console.log(`Attempt ${attempt}: ${error.message}`);
    },
  },
);

# FallbackLLM — Basculement Multi-Provider

FallbackLLM chaîne plusieurs adaptateurs LLM ensemble. Si le principal échoue, il essaie automatiquement le suivant dans la chaîne. Cela fournit une redondance entre différents fournisseurs.

import { FallbackLLM } from 'orkajs/resilience';
import { OpenAIAdapter } from 'orkajs/adapters/openai';
import { AnthropicAdapter } from 'orkajs/adapters/anthropic';
import { OllamaAdapter } from 'orkajs/adapters/ollama';
 
const llm = new FallbackLLM({
  adapters: [
    // Primary: OpenAI (fastest, most reliable)
    new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
    // Secondary: Anthropic (different provider for redundancy)
    new AnthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY! }),
    // Tertiary: Local Ollama (always available, no API limits)
    new OllamaAdapter({ model: 'llama3.2' }),
  ],
  onFallback: (error, failedAdapter, nextAdapter) => {
    console.warn(`⚠️ ${failedAdapter} failed: ${error.message}`);
    console.warn(`   Falling back to ${nextAdapter}`);
    // Send alert to monitoring system
    alerting.send('llm_fallback', { from: failedAdapter, to: nextAdapter });
  },
});
 
const orka = createOrka({ 
  llm, 
  vectorDB: new MemoryVectorDB() 
});
 
// If OpenAI fails, automatically tries Anthropic, then Ollama
const answer = await orka.ask({ question: 'What is TypeScript?' });

- Options FallbackLLM

adapters: LLMAdapter[]required

Tableau d'adaptateurs LLM par ordre de priorité. Le premier adaptateur est essayé en premier.

onFallback?: (error, failedAdapter, nextAdapter) => void

Callback déclenché lors du basculement vers l'adaptateur suivant. Utilisez pour le logging/alerting.

# Combiner Retry + Fallback

Pour une résilience maximale, combinez ResilientLLM (retry) avec FallbackLLM (multi-provider). Cela vous donne le retry au sein de chaque fournisseur ET le fallback entre fournisseurs.

import { FallbackLLM, ResilientLLM } from 'orkajs/resilience';
import { OpenAIAdapter } from 'orkajs/adapters/openai';
import { AnthropicAdapter } from 'orkajs/adapters/anthropic';
 
// Wrap each adapter with retry logic
const resilientOpenAI = new ResilientLLM(
  new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
  { maxRetries: 2, initialDelayMs: 500 }
);
 
const resilientAnthropic = new ResilientLLM(
  new AnthropicAdapter({ apiKey: process.env.ANTHROPIC_API_KEY! }),
  { maxRetries: 2, initialDelayMs: 500 }
);
 
// Chain resilient adapters with fallback
const llm = new FallbackLLM({
  adapters: [resilientOpenAI, resilientAnthropic],
  onFallback: (error, from, to) => console.warn(`Fallback: ${from} -> ${to}`),
});
 
const orka = createOrka({ llm, vectorDB: new MemoryVectorDB() });
 
// Flow: OpenAI (retry 1) -> OpenAI (retry 2) -> Anthropic (retry 1) -> Success

Cela vous donne : OpenAI (retry 1) → OpenAI (retry 2) → Anthropic (retry 1) → Anthropic (retry 2) → Succès ✓

Exemple Production Complet

resilience-example.ts

import { createOrka } from 'orkajs/core';
import { FallbackLLM, ResilientLLM } from 'orkajs/resilience';
import { OpenAIAdapter } from 'orkajs/adapters/openai';
import { AnthropicAdapter } from 'orkajs/adapters/anthropic';
import { OllamaAdapter } from 'orkajs/adapters/ollama';
import { MemoryVectorDB } from 'orkajs/adapters/memory';
 
// Production-grade resilient LLM setup
const llm = new FallbackLLM({
  adapters: [
    // Primary: OpenAI with retry
    new ResilientLLM(
      new OpenAIAdapter({ 
        apiKey: process.env.OPENAI_API_KEY!,
        model: 'gpt-4o-mini',
        timeoutMs: 30000,
      }),
      { maxRetries: 2, initialDelayMs: 1000, retryableErrors: ['429', '503', 'timeout'] }
    ),
    // Secondary: Anthropic with retry
    new ResilientLLM(
      new AnthropicAdapter({ 
        apiKey: process.env.ANTHROPIC_API_KEY!,
        model: 'claude-3-5-sonnet-20241022',
      }),
      { maxRetries: 2, initialDelayMs: 1000 }
    ),
    // Tertiary: Local fallback (always available)
    new OllamaAdapter({ model: 'llama3.2' }),
  ],
  onFallback: (error, from, to) => {
    console.error(`[RESILIENCE] Fallback ${from} -> ${to}: ${error.message}`);
    // Alert your monitoring system
  },
});
 
const orka = createOrka({ llm, vectorDB: new MemoryVectorDB() });
 
// Your app is now resilient to:
// - Rate limits (retry with backoff)
// - Temporary outages (retry)
// - Provider outages (fallback to another provider)
// - Complete cloud failure (fallback to local Ollama)

💡 Conseils Production

Configurez toujours au moins 2 fournisseurs dans FallbackLLM
Utilisez différents fournisseurs cloud (OpenAI + Anthropic) pour une vraie redondance
Incluez un Ollama local en dernier recours (pas de limites API, toujours disponible)
Surveillez les événements de fallback pour détecter les problèmes de fournisseur tôt
Définissez des timeouts appropriés pour échouer rapidement et essayer le fournisseur suivant

Imports Tree-shakeable

// ✅ Import only what you need
import { ResilientLLM, FallbackLLM, withRetry } from 'orkajs/resilience';