# Cosa cambia quando si migrano le richieste OpenRouter a un'altra API compatibile con OpenAI? > Cambiare URL base e chiave API è solo il primo passo. I campi chat standard sono spesso portabili, ma ID modello, header ed estensioni di routing OpenRouter, fallback, streaming, contabilità, input multimodali, errori e limiti vanno testati dietro un adattatore. # Cosa cambia quando si migrano le richieste OpenRouter a un'altra API compatibile con OpenAI? Per una chat semplice, la migrazione può iniziare con nuovo URL base, chiave e ID modello. In produzione, routing, header, slug, fallback, metadati e selezione provider di OpenRouter richiedono sostituti; streaming e strumenti richiedono test di contratto. La compatibilità OpenAI è un dialetto di trasporto, non la promessa di cataloghi, estensioni, fatturazione o operazioni identici. ## Inventariare il contratto realmente usato Cerca in codice, configurazione e log ogni campo inviato a OpenRouter. La configurazione documentata usa `https://openrouter.ai/api/v1`, autenticazione Bearer e header di attribuzione facoltativi, oltre a possibili estensioni di routing. Crea l'inventario prima di modificare: | Superficie | Spesso portabile | Da verificare | |---|---|---| | Chat | `messages`, temperature, limite output | Parametri e valori predefiniti | | Modelli | Intento applicativo | Slug specifico | | Strumenti | Nome e JSON schema | Parallelismo, strict, argomenti in streaming | | Routing | Nessuno | Preferenze, fallback, transforms | | Header | Autorizzazione | Attribuzione e metadati OpenRouter | | Uso | Token | Costo, cache, ricerca della richiesta | | Operazioni | Famiglie HTTP | Limiti, tentativi, tempi, corpo errore | ## Introdurre prima un adattatore Non spargere URL e slug nel codice. Incapsula le differenze ed esponi alias applicativi. ```python from openai import OpenAI def make_client(base_url: str, api_key: str) -> OpenAI: return OpenAI(base_url=base_url, api_key=api_key) MODEL_MAP = { "coding_default": { "openrouter": "provider/model-slug", "target": "target-model-id", } } ``` L'adattatore traduce inoltre i campi, normalizza gli errori ed emette eventi comuni. ## Sostituire la semantica di modelli e routing Gli ID modello non sono standardizzati. Mappa ogni alias al modello di destinazione e verifica contesto, strumenti, output strutturato, modalità e prezzo nel catalogo corrente. La destinazione può esprimere routing e fallback diversamente o non offrirli. Decidi se ricrearli nell'orchestrazione, usare il router di destinazione o rimuoverli. Un cambiamento silenzioso modifica costo e qualità. ## Rimuovere o tradurre le estensioni OpenRouter Controlla header e campi specifici. Gli header di attribuzione facoltativi possono in genere essere rimossi; preferenze, elenchi fallback, plugins, transforms e controlli metadati richiedono una mappatura esplicita. Durante i test rifiuta estensioni sconosciute. Ignorarle silenziosamente nasconde un cambio di comportamento. ## Testare strumenti e streaming come contratto Testa: * accettazione del nome e del JSON schema; * modalità tool choice e chiamate parallele; * eventi incrementali degli argomenti; * motivi di fine e rifiuti; * argomenti non validi e tentativi. Confronta eventi analizzati, non chunk grezzi. Includi annullamento, errori a metà stream, uso finale, delta vuoti e riconnessione. ## Ricostruire la contabilità OpenRouter documenta metadati con modello, provider, token e costo totale. La destinazione può restituire l'uso nella risposta, offrire una ricerca separata o richiedere calcolo client. Normalizza nel registro: ```json { "request_id": "internal_123", "provider_request_id": "external_456", "gateway": "target", "model": "resolved-model-id", "input_tokens": 1200, "output_tokens": 340, "cost_usd": 0.0123 } ``` Separa stime e addebiti riconciliati. Ricontrolla i limiti prima di migrare gli agenti di produzione. ## Verificare le richieste multimodali Immagini, audio e video dipendono da modello ed endpoint. Due gateway possono differire per parti del contenuto, upload, URL, job asincroni e oggetti di output. Crea fixture per ogni modalità. Una chat testuale riuscita non prova la compatibilità media. ## Testare il comportamento operativo Misura header dei limiti, codici ripetibili, timeout, coda, regioni, idempotenza, log e supporto. Usa la documentazione corrente della destinazione. Un rollout pratico ha quattro fasi: 1. Riprodurre offline un set di riferimento. 2. Eseguire traffico sicuro in ombra. 3. Avviare un piccolo canary a basso rischio. 4. Espandere solo se errori, latenza, costo e asserzioni restano entro soglia. Mantieni un rollback semplice fino a una prova con carico rappresentativo. ## Decidere se la consolidazione conviene OpenRouter resta adatto quando il suo catalogo LLM e il routing corrispondono al prodotto. Atlas Cloud può essere interessante se un accesso compatibile con OpenAI per testo, immagini e video semplifica lo stack. Nessun vantaggio elimina i test. Decidi in base a requisiti misurati, non al diff più piccolo. ## Conclusione Cambia la configurazione e verifica ogni presupposto non standard su modelli, routing, strumenti, streaming, uso e operazioni. Un adattatore con test di riferimento mantiene reversibile la migrazione e impedisce che una richiesta valida nasconda una regressione semantica. ## FAQ ### Posso migrare cambiando solo base_url e api_key? A volte per una chat semplice, ma le integrazioni di produzione dipendono spesso anche da slug, opzioni di routing, header, streaming, campi d'uso o semantica di fallback. ### Quali campi OpenRouter sono meno portabili? Preferenze provider, elenchi di fallback, header di attribuzione, transforms, plugins e metadati specifici sono punti comuni. Tienili fuori dal modello di richiesta principale. ### Le API compatibili con OpenAI usano gli stessi nomi dei modelli? No. La compatibilità riguarda in genere la forma della richiesta, non l'identità del catalogo. Mappa esplicitamente gli alias applicativi agli ID correnti di ogni gateway. ### Come si testa lo streaming dopo la migrazione? Registra sequenze di eventi per delta di testo, argomenti degli strumenti, motivi di fine, uso, annullamento ed errori. Confronta eventi analizzati, non blocchi di byte grezzi. ### Qual è il rollout più sicuro? Usa un adattatore, riproduci un set di riferimento, esegui un piccolo campione in ombra, poi un canary a basso rischio con soglie di rollback per errori, latenza, costo e asserzioni. ### Quando conviene restare su OpenRouter? Quando l'ampio catalogo LLM, i controlli di routing e gli strumenti operativi esistenti valgono più della consolidazione altrove. Decidi in base a requisiti misurati, non solo alla compatibilità dichiarata.