Introduction
OpenRouter centralise l'accès à plus de 200 modèles de langage via une API unique. Pour un développeur expert, il s'agit d'un outil stratégique permettant d'optimiser les coûts, la latence et la disponibilité des modèles. Ce tutoriel vous guide dans la construction d'un client TypeScript robuste avec routage dynamique, streaming SSE et mécanismes de fallback automatique. Vous apprendrez à gérer les erreurs de manière professionnelle et à implémenter une logique de sélection de modèles basée sur des critères métier.
Prérequis
- Node.js 20+
- TypeScript 5.4+
- Compte OpenRouter avec clé API
- Connaissances solides en async/await et gestion d'erreurs
Configuration du client de base
import { OpenAI } from 'openai';
export const openrouter = new OpenAI({
baseURL: 'https://openrouter.ai/api/v1',
apiKey: process.env.OPENROUTER_API_KEY,
defaultHeaders: {
'HTTP-Referer': 'https://votre-app.com',
'X-Title': 'MonAppIA'
}
});Ce client réutilisable configure OpenRouter comme provider OpenAI-compatible. Les headers sont obligatoires pour le suivi et le classement des applications sur la plateforme.
Appel simple avec routage
export async function generateCompletion(prompt: string, model = 'anthropic/claude-3.5-sonnet') {
const response = await openrouter.chat.completions.create({
model,
messages: [{ role: 'user', content: prompt }],
temperature: 0.7,
max_tokens: 1024
});
return response.choices[0].message.content;
}Fonction de base permettant de router vers n'importe quel modèle OpenRouter. Utilisez des identifiants comme 'openai/gpt-4o' ou 'google/gemini-1.5-pro' pour changer de provider instantanément.
Implémentation du streaming
export async function* streamCompletion(prompt: string, model: string) {
const stream = await openrouter.chat.completions.create({
model,
messages: [{ role: 'user', content: prompt }],
stream: true
});
for await (const chunk of stream) {
const content = chunk.choices[0]?.delta?.content;
if (content) yield content;
}
}Le streaming SSE est natif. Cette fonction génératrice permet une consommation token par token côté client avec une latence minimale.
Logique de fallback avancée
export async function generateWithFallback(prompt: string) {
const models = ['anthropic/claude-3.5-sonnet', 'openai/gpt-4o', 'google/gemini-1.5-pro'];
for (const model of models) {
try {
return await generateCompletion(prompt, model);
} catch (error) {
console.warn(`Échec sur ${model}, tentative suivante...`);
continue;
}
}
throw new Error('Tous les modèles ont échoué');
}Mécanisme de fallback séquentiel critique en production. Il garantit une haute disponibilité même si un provider rencontre une panne.
Sélection dynamique de modèle
interface ModelCriteria {
maxCost: number;
minContext: number;
preferredProvider?: string;
}
export function selectModel(criteria: ModelCriteria): string {
if (criteria.maxCost < 0.5) return 'meta-llama/llama-3.1-70b';
if (criteria.minContext > 100000) return 'google/gemini-1.5-pro';
return 'anthropic/claude-3.5-sonnet';
}Fonction de routage intelligent basée sur des critères métier. Elle permet d'optimiser automatiquement le coût et les performances selon le contexte de la requête.
Bonnes pratiques
- Toujours définir des headers HTTP-Referer et X-Title
- Implémenter des timeouts et retries avec backoff exponentiel
- Logger les model_id et les coûts pour chaque requête
- Utiliser des modèles de fallback de différentes familles
- Valider les réponses avec Zod ou un schéma strict
Erreurs courantes à éviter
- Oublier les headers de traçabilité (erreur 403)
- Ne pas gérer les rate limits spécifiques à chaque modèle
- Utiliser des identifiants de modèles invalides sans validation préalable
- Ignorer les réponses partielles lors du streaming
Pour aller plus loin
Découvrez nos formations avancées sur l'architecture LLM et le routing intelligent : https://learni-group.com/formations