Creazione di un livello di instradamento AI multi-provider resiliente con Vercel AI SDK

Quando si distribuiscono modelli linguistici di grandi dimensioni (LLM) in produzione, l'affidabilità rappresenta spesso il collo di bottiglia principale. Affidarsi a un singolo provider di modelli introduce rischi di single-point-of-failure: limiti di velocità delle API (HTTP 429), tempi di inattività temporanei del servizio (HTTP 500/503) o improvvisi picchi di latenza.

Per garantire tempi di attività e l'efficienza dei costi, i team hanno bisogno d'un livello di instradamento dinamico in grado di eseguire automaticamente il failover su modelli di fallback o cambiare provider in base ai parametri di input.

In questa guida, implementeremo un livello di instradamento multi-provider resiliente e type-safe utilizzando Vercel AI SDK e Zod.

L'architettura della resilienza LLM

Un livello di instradamento resiliente opera su tre principi fondamentali:

Failover sequenziali: Se il provider principale fallisce, il sistema tenta automaticamente di nuovo la richiesta utilizzando un provider secondario.
Selezione dinamica: I prompt brevi vengono inviati a modelli veloci ed economici, mentre gli input più grandi vengono instradati a modelli con contesti più ampi.
Validazione Type-Safe: Indipendentemente dal modello che gestisce la richiesta, lo schema di output rimane identico e validato.

               +-------------------+
               |  Incoming Request |
               +-------------------+
                         |
                         v
             +-----------------------+
             | Dynamic Route Selector|
             +-----------------------+
               /                   \
        (Short Input)          (Long Input)
             /                       \
            v                         v
   +-----------------+       +-----------------+
   |  Primary Model  |       |  Primary Model  |
   | (OpenAI Luna)   |       | (Gemini-3.1-Pro)|
   +-----------------+       +-----------------+
            |                         |
       (On Failure)              (On Failure)
            v                         v
   +-----------------+       +-----------------+
   | Fallback Model  |       | Fallback Model  |
   | (Gemini-3.5-Fl) |       | (Claude-Sonnet5)|
   +-----------------+       +-----------------+
            \                         /
             \                       /
              v                     v
            +-------------------------+
            |  Zod Schema Validation  |
            +-------------------------+
                        |
                        v
               +-------------------+
               | Validated Output  |
               +-------------------+

Implementazione dei fallback con Vercel AI SDK

Vercel AI SDK fornisce un wrapper fallback integrato che consente di specificare un elenco prioritario di modelli. Se una chiamata al primo modello fallisce, l'SDK riprova automaticamente utilizzando i modelli successivi nell'array.

Ecco come inizializzare un modello resiliente con provider di fallback:

import { fallback } from 'ai';
import { openai } from '@ai-sdk/openai';
import { google } from '@ai-sdk/google';
import { anthropic } from '@ai-sdk/anthropic';

// Initialize a resilient model that crosses three distinct providers
export const resilientModel = fallback([
  openai('terra'),
  anthropic('claude-sonnet-5'),
  google('gemini-3.1-pro')
]);

Quando si chiama generateText o generateObject con resilientModel, l'SDK gestisce automaticamente gli errori, i timeout e i tentativi.

Fallback locali con Ollama

Per disponibilità offline, ambienti ibridi o esecuzione a costo zero durante i test locali, è possibile integrare modelli ospitati localmente tramite Ollama. Vercel AI SDK tratta i modelli Ollama come provider di prima classe, consentendo di passare direttamente dalle API cloud al silicio locale.

Ecco come configurare un fallback ibrido da cloud a locale:

import { fallback } from 'ai';
import { openai } from '@ai-sdk/openai';
import { ollama } from '@ai-sdk/ollama';

// Fallback to a locally hosted Llama 4 Scout model if the OpenAI API is unreachable
export const hybridModel = fallback([
  openai('luna'),
  ollama('llama4-scout')
]);

Estrazione di dati strutturati Type-Safe

Una delle sfide dell'instradamento multi-provider consiste nell'assicurarsi che modelli diversi aderiscano esattamente alla stessa struttura di output. L'uso di Zod con l'API generateObject risolve questo problema.

Definiamo uno schema per estrarre metadati strutturati dai profili degli sviluppatori:

import { generateObject } from 'ai';
import { z } from 'zod';
import { resilientModel } from './models';

const ProfileSchema = z.object({
  fullName: z.string(),
  skills: z.array(z.string()),
  yearsOfExperience: z.number(),
  certifications: z.array(
    z.object({
      name: z.string(),
      issuer: z.string()
    })
  )
});

export async function extractProfile(text: string) {
  try {
    const { object } = await generateObject({
      model: resilientModel,
      schema: ProfileSchema,
      prompt: `Extract structured profile details from the following resume text:\n\n${text}`
    });

    return object;
  } catch (error) {
    console.error('Failed to extract profile after exhausting all fallbacks:', error);
    throw new Error('Profile extraction failed');
  }
}

Poiché l'output viene analizzato e validato da Zod in fase di esecuzione, il codice dell'applicazione può fare affidamento sulla struttura restituita, indipendentemente dal modello della catena di fallback che ha avuto successo.

Instradamento dinamico basato sulla dimensione del contesto

Sebbene i fallback sequenziali proteggano da tempi di inattività completi, non ottimizzano i costi o i limiti dei token. Ad esempio, inviare un documento da 100.000 token a un modello con un limite di 128.000 token va bene, ma inviarlo a un modello con un limite di 16.000 token genererà un errore immediato.

Possiamo creare un router dinamico che ispeziona la dimensione dell'input prima di scegliere la catena di modelli:

import { LanguageModel, generateText } from 'ai';
import { openai } from '@ai-sdk/openai';
import { google } from '@ai-sdk/google';
import { anthropic } from '@ai-sdk/anthropic';

// Define specialized model chains
const standardChain = fallback([
  openai('luna'),
  google('gemini-3.5-flash')
]);

const highContextChain = fallback([
  google('gemini-3.1-pro'),
  anthropic('claude-sonnet-5')
]);

// Estimate token count (simple word-count approximation for demo)
function estimateTokens(text: string): number {
  return text.trim().split(/\s+/).length * 1.3;
}

export async function smartRouteRequest(promptText: string) {
  const tokenEstimate = estimateTokens(promptText);
  
  // Route to the appropriate chain based on input size
  const model = tokenEstimate > 50000 ? highContextChain : standardChain;

  return generateText({
    model,
    prompt: promptText
  });
}

Questo schema mantiene bassi i costi indirizzando le attività standard a modelli economici e veloci, riservando i modelli premium con finestre di contesto più ampie a carichi di lavoro più pesanti.

Telemetria e osservabilità

Per monitorare la frequenza con cui il livello di instradamento attiva i modelli di fallback, è possibile collegarsi alle funzionalità di telemetria sperimentali di Vercel AI SDK. Questo raccoglie metriche sull'uso dei token, sulla latenza e sui tassi di successo dei provider:

import { generateText } from 'ai';
import { resilientModel } from './models';

const response = await generateText({
  model: resilientModel,
  prompt: 'Analyze this log output...',
  experimental_telemetry: {
    isEnabled: true,
    functionId: 'analyze-logs',
    metadata: {
      environment: 'production'
    }
  }
});

Queste tracce vengono raccolte nei collettori OpenTelemetry standard, offrendo al team visibilité completa sui failover e sullo stato del provider.

Conclusione e compromessi

Un livello di instradamento multi-provider aumenta l'affidabilità. Tuttavia, è importante considerare i compromessi:

Differenze di stile: I modelli di fallback possono mostrare stili di scrittura, sfumature di formattazione o conformità diverse.
Avvii a freddo: Riprovare una richiesta non riuscita su un modello secondario aggiunge latenza all'esperienza dell'utente.
Chiavi API dei provider: L'infrastruttura deve configurare e gestire chiavi API, livelli di limiti di velocità e account di fatturazione per più provider.

Utilizzando le API unificate di Vercel AI SDK, è possibile creare un'architettura di instradamento altamente resiliente in grado di proteggere le applicazioni di produzione dai tempi di inattività dei singoli provider.