Terugvallen op een ander model¶

Het concept achter modellen en routering staat in Modellen en routering.

Is het model dat je vraagt niet beschikbaar, dan kan Core de beurt op het volgende model uitvoeren zonder dat jij het verzoek opnieuw stuurt. Welk model dat is, komt uit een routeringsconfiguratie die je beheerder voor je organisatie instelt. Deze pagina beschrijft wat je applicatie daarvan merkt: wat je sleutel ziet, wat wel en niet terugvalt en wat het antwoord erover zegt. Een beheerder stelt de configuratie in op Fallback-routering.

Wat een routeringsconfiguratie is¶

Een routeringsconfiguratie is een benoemde lijst met ketens. Elke keten noemt één model en, op volgorde, de één tot vier modellen die in plaats daarvan geprobeerd worden:

{
  "name": "default",
  "chains": [
    { "primary": "gpt-5.6-sol", "fallbacks": ["claude-sonnet-5", "gemini-3.8-flash"] }
  ]
}

Je beheerder maakt hem aan op je organisatie en maakt hem vervolgens óf de standaard van de organisatie — dan gebruikt elke sleutel van de organisatie hem — óf noemt hem op één sleutel, wat de standaard voor alleen die sleutel overschrijft. Een sleutel kan ook helemaal uitgezet worden voor terugvallen. Welke configuratie een sleutel noemt, is sleutelconfiguratie, PATCH /keys/{key_id}; een sleutel met management kan de configuraties zelf ook aanmaken, opvragen, lezen, hernoemen, vervangen en verwijderen, en hun versies opvragen en lezen (.../{id}/versions), op /routing-configs voor haar eigen organisatie en /organisations/{id}/routing-configs voor een organisatie eronder — wat /tenants/{id}/routing-configs een persoon biedt, waar aanmaken en bewerken ook draft: true nemen voor een wijziging waarop geen sleutel terugvalt totdat ze gepubliceerd is, uitgewerkt in Organisaties beheren via de API. De console biedt hetzelfde op Routering.

Wat je sleutel ziet¶

GET /key noemt de configuratie die voor je sleutel geldt, of null als hij nergens op terugvalt:

{ "routing_config": { "id": "rcf_0KQ2mR...", "name": "default" } }

GET /models geeft bij elk model dat je mag aanroepen de keten die je beurten erop echt volgen — al beperkt tot wat het beleid van je sleutel toestaat:

{ "id": "gpt-5.6-sol", "object": "model", "fallbacks": ["claude-sonnet-5"] }

Een lege fallbacks betekent dat een beurt op dat model nergens op terugvalt.

Een model in de keten waarvan de uitfaseerdatum voorbij is, staat er als zijn vervanger, of ontbreekt als de policy van je organisatie of sleutel uitgefaseerde modellen blokkeert. De lijst toont de keten zoals een beurt hem op dit moment doorloopt.

Beide tonen de eigen configuratie van je sleutel, omdat ze geen agent noemen. Een beurt waarvan de agent of het verzoek een andere configuratie noemt, valt langs die terug (hieronder).

Een configuratie voor één agent of één beurt¶

Eén sleutel die meerdere assistenten bedient, kan elke assistent een eigen keten geven. Naast de sleutel en de organisatie kunnen twee plekken een configuratie noemen:

Een agentversie kan routing_config_id dragen. Elke beurt van die versie valt dan langs die configuratie terug in plaats van langs die van de sleutel.
Eén POST /responses-verzoek kan het ook dragen, alleen voor die beurt:

curl -s -X POST "$CORE_URL/responses" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"agent": {"id": "support"}, "input": "Vat deze week samen.",
         "routing_config_id": "rcf_..."}'

De dichtstbijzijnde wint in haar geheel: die van het verzoek, dan die van de agentversie, dan die van de sleutel, dan de standaard van de organisatie. Ketens worden nooit samengevoegd. Een configuratie die niet van je organisatie is of geen gepubliceerde versie heeft, geeft een 422 op routing_config_id, op het verzoek en op de agentversie. Een sleutel waarop fallback uit staat, valt nergens op terug, wat de agent of het verzoek ook noemt.

Een beurt op een oudere agentversie waarvan de configuratie inmiddels is verwijderd, valt nergens op terug, ook niet op de configuratie van de sleutel.

Configuraties aanmaken en koppelen in de console staat in Fallback-routering.

Wat wel en niet terugvalt¶

Een beurt gaat door naar het volgende model als het huidige niet kon antwoorden: een time-out, een 429 of een 5xx van de provider, of een verbinding die nooit tot stand kwam. Core probeert elk model zoals altijd — eerst opnieuw proberen, dan het volgende model in de keten.

Drie fouten blijven staan, omdat het volgende model precies hetzelfde zou antwoorden:

een 4xx anders dan 429, die over het verzoek zelf gaat;
een model dat helemaal niet in de catalogus staat;
een beurt die persoonsgegevens niet kon verbergen vóór het versturen.

Twee grenzen zijn het weten waard:

Een gestreamde beurt valt alleen terug vóór het eerste stukje tekst. Is er eenmaal tekst naar je onderweg geweest, dan zou opnieuw beginnen op een ander model die tekst herhalen, dus mislukt de beurt in plaats daarvan.
De keten wordt één keer doorlopen, van links naar rechts, en alleen de keten van het model dat je vroeg. De eigen keten van een fallback wordt nooit geraadpleegd, dus een configuratie kan nooit rondlopen.

Wat het antwoord je vertelt¶

model is het model dat werkelijk antwoordde:

{
  "status": "completed",
  "model": "claude-sonnet-5"
}

Er staat geen tweede veld naast. In de Responses-API betekent model het model dat het antwoord maakte en niet de naam die je typte, dus een beurt die terugviel zegt dat door het model te noemen dat draaide. Een beurt die op elk model in de keten mislukte noemt het model dat je vroeg — dan is status failed met de error.code van de mislukking van het laatste model, precies zoals zonder configuratie: model_error, model_timeout, of model_rate_limited als de keten op een snelheidslimiet eindigde. Een gestreamde beurt draagt hetzelfde veld in het antwoordobject binnen response.completed of response.failed; er is geen apart event voor een terugval, en het event response.created noemt het model dat je vroeg, omdat er nog geen ronde geantwoord heeft.

Is een beurt eenmaal teruggevallen, dan blijft hij voor de rest van zijn toolrondes op het model dat antwoordde — één beurt, één stem. Je verbruiksregels worden geschreven op het model dat werkelijk draaide, zodat waarvoor je betaalt en wat antwoordde hetzelfde zijn.

Een achtergrondrun begint bij elke keer dat een worker hem oppakt weer bij het model dat je vroeg: een storing van een minuut geleden kan voorbij zijn.