Een AI-provider aansluiten en een model registreren

Drie niveaus die u niet door elkaar moet halen

Het aansluiten van een model in Sapphire I.C.D.S. bestaat uit drie afzonderlijke records. De provider beschrijft de externe dienst: de stabiele sleutel, basis-URL, geïnstalleerde adapter en het toegangsgeheim. Het model bewaart de modelidentificatie bij die provider en de technische grenzen ervan. Het profiel bepaalt het daadwerkelijke werkgedrag: systeeminstructie, contextbudget, antwoordomvang en aanvullende parameters. Dankzij deze scheiding kan één model in verschillende modi worden gebruikt zonder de API-sleutel te dupliceren of de werkelijke modelgrenzen te vervangen door instellingen van één taak.

De configuratie vindt plaats in het beheergedeelte AI Settings. Toegang daartoe moet via Helix zijn verleend. Vraag vóór aanvang bij de provider de actuele base URL, model ID en limieten van het gekozen model op en controleer of de bijbehorende adapter al in de Sapphire-serveromgeving is geïnstalleerd. Tekst in een formulierveld installeert niet uit zichzelf een bibliotheek.

Stap 1. De provider aanmaken

Open het providergedeelte en maak een nieuw record. Het veld Vendor key moet een korte, stabiele machine-identificatie bevatten, bijvoorbeeld acme_ai. Gebruik Latijnse kleine letters, cijfers en het onderstrepingsteken. Neem geen domein, abonnement, regio of modelversie op: de sleutel koppelt configuraties en moet gewone productwijzigingen overleven.

Display name is bedoeld voor operators en mag leesbaar zijn. Vul bij Base URL het gedocumenteerde HTTPS-basisadres van de API van de provider in, zonder pad naar een specifiek model en zonder token in de query string. Kopieer geen URL uit de browserconsole en voeg geen willekeurige eindroute toe. Als de leverancier verschillende compatibele API's aanbiedt, gebruikt u de variant waarvoor de adapter is geïnstalleerd.

Vendor key moet overeenkomen met de variant van de geïnstalleerde provider die de standaardlader van het platform detecteert. Het veld Provider library is in de huidige runtime compatibele fallback metadata en bepaalt bij een niet-lege vendor key normaal gesproken niet de adapter. Het is geen bestandspad en geen mechanisme om een nieuwe bibliotheek te installeren. Als de vereiste provider variant niet is geïnstalleerd, draagt u de taak over aan de deploymentbeheerder.

Bij Secret name blijft doorgaans de voor deze adapter afgesproken naam van het geheim staan; bij Secret value voert u de verstrekte API-sleutel in. Plaats het geheim niet in de naam, URL, beschrijving, schermafbeelding, ticket of profiel-JSON. Na het opslaan toont de interface alleen dat het geheim aanwezig is, niet de oorspronkelijke waarde. Laat het waardeveld tijdens bewerken leeg als de sleutel niet hoeft te veranderen; een nieuwe niet-lege waarde roteert het geheim. Een praktische volgorde is: maak de provider eerst uitgeschakeld aan, bewaar het geheim, controleer de overige velden en schakel het record pas daarna in.

Stap 2. Het model registreren

Ga naar het modelgedeelte en selecteer de zojuist aangemaakte provider. Model key moet exact overeenkomen met de identificatie die de API accepteert, inclusief streepjes, punten en versiesuffix. Dit is geen vrij te kiezen alias. Voor een handige naam is er een afzonderlijk veld Display name.

Neem vervolgens drie grenzen over uit de officiële modelinformatie. Maximum context is de volledige limiet van het contextvenster. Maximum input is de maximaal toegestane invoer. Maximum output begrenst het gegenereerde antwoord. Alle waarden worden als positieve gehele aantallen tokens opgegeven. Invoer en uitvoer mogen afzonderlijk niet groter zijn dan de volledige context. Gebruik niet de geadverteerde contextwaarde als de gekozen API of het abonnement minder toestaat.

Tokenizer variant bepaalt hoe tokens worden geschat. Vul de exact ondersteunde variant in als die bekend is. Als voor een nieuwe familie alleen een conservatieve schatting beschikbaar is, gebruikt u de afgesproken variantnaam daarvan in plaats van naar de modelnaam te raden. Dit veld is verplicht: een verkeerde tokenizer veroorzaakt niet alleen een cosmetische afwijking, maar een onjuiste berekening van het compactiemoment en de toegestane aanvraaggrootte.

Veilige volgorde van inschakelen

1. Maak de provider aan met de juiste HTTPS-URL en geïnstalleerde adapter.
2. Bewaar het geheim en controleer of de lijst aangeeft dat het aanwezig is.
3. Maak het model aan met de exacte model key en bevestigde limieten.
4. Maak een afzonderlijk profiel voor dit model; zonder profiel is geen werkbeleid bepaald.
5. Schakel model en provider eerst in voor een beperkte controle en wijs pas daarna het standaardprofiel toe.

Open voor de controle een nieuwe AI-sessie, selecteer expliciet het aangemaakte profiel en voer een korte aanvraag zonder hulpmiddelen uit, bijvoorbeeld het verzoek om één regel tekst terug te geven. Een nieuwe sessie voorkomt invloed van een eerdere profielkeuze en opgebouwde geschiedenis. Controleer na het basisantwoord de streamingmodus en pas daarna scenario's met hulpmiddelen. De beschikbaarheid van hulpmiddelen wordt beheerd door de catalogus en groepsrechten, niet door het provider- of modelrecord.

Veelvoorkomende fouten

• Authenticatiefout: controleer of het geheim aanwezig en geldig is en bij het juiste project hoort; roteer het alleen indien nodig.
• Model not found: vergelijk de model key teken voor teken met de API-documentatie en bevestig dat het account het model mag gebruiken.
• Onjuiste route: controleer de base URL, geselecteerde adapter en afwezigheid van een modelpad in het basisadres.
• Limieten worden bij opslaan geweigerd: alle drie waarden moeten positief zijn en input en output mogen context niet overschrijden.
• Het model verschijnt niet tijdens gebruik: provider, model en profiel moeten zijn ingeschakeld; het profiel moet naar hetzelfde paar verwijzen en beschikbaar zijn voor de huidige gebruiker.

Wijzig niet tegelijk het geheim, de URL, model key en limieten van een actief profiel. Voer wijzigingen één voor één door en leg het verificatieresultaat vast. Bij een nieuwe modelgeneratie is het veiliger een nieuw model en profiel te registreren, die afzonderlijk te testen en vervolgens het standaardprofiel om te schakelen. Zo blijft er een duidelijke terugweg zonder de betekenis van bestaande records te veranderen.

Acceptatie en onderhoud

Leg na een geslaagde minimale aanvraag de vendor key, model key, het doel van het profiel, de bron van de limieten en de controledatum vast in de werkdocumentatie. Noteer het geheim niet. Test afzonderlijk het gedrag wanneer de provider tijdelijk uitgeschakeld is: de gebruiker moet een duidelijke fout krijgen en niet eindeloos wachten. Als een dienst meerdere regio's of abonnementsroutes heeft, legt u die vast als bewuste configuraties in plaats van tijdens diagnose de base URL te wijzigen.

Controleer de limieten periodiek aan de hand van de actuele documentatie van de leverancier. Een wijziging van de commerciële modelnaam betekent niet altijd een nieuwe API-identificatie, en een nieuwe identificatie garandeert niet dezelfde tokenizer variant. Laat elke dergelijke wijziging dezelfde cyclus doorlopen: afzonderlijk record, profiel, testsessie, controle van het antwoord en pas daarna omschakeling van gebruikers.