Verbindung des KI-Anbieters und Registrierung des Modells

Drei Ebenen, die nicht vermischt werden sollten

Die Verbindung eines Modells in Sapphire I.C.D.S. besteht aus drei separaten Einträgen. Anbieter beschreibt einen externen Dienst: seinen stabilen Schlüssel, die Basis-URL, den installierten Adapter und das Zugriffsgeheimnis. Modell speichert die Modell-ID dieses Anbieters und seine technischen Grenzen. Profil definiert das bereits funktionierende Verhalten: die Systemanweisung, den Kontextbudget, die Antwortgröße und zusätzliche Parameter. Diese Trennung ermöglicht die Nutzung desselben Modells in mehreren Modi, ohne API-Schlüssel zu duplizieren oder die tatsächlichen Modellbeschränkungen durch die Einstellungen eines einzelnen Tasks zu überschreiben.

Die Konfiguration erfolgt im Verwaltungsbereich KI-Einstellungen. Der Zugriff muss über Helix gewährt werden. Bevor Sie beginnen, holen Sie sich vom Anbieter die aktuellen Werte für Base URL, Model ID und die Limits des ausgewählten Modells und stellen Sie sicher, dass der entsprechende Adapter bereits im Sapphire Server-Kontext installiert ist. Die Zeichenkette in einem Formular installiert nicht von selbst eine Bibliothek.

Schritt 1. Erstellung des Anbieters

Öffnen Sie den Anbieterbereich und erstellen Sie einen neuen Eintrag. Das Feld Vendor key muss eine kurze, stabile Maschinen-ID enthalten, z. B. acme_ai. Verwenden Sie nur Kleinbuchstaben des lateinischen Alphabets, Ziffern und Unterstriche. Fügen Sie keinen Domainnamen, Tarif, Region oder Modellversion hinzu: Der Schlüssel verknüpft die Einstellungen und muss normale Produktänderungen überdauern.

Display name ist für Bediener bestimmt und kann menschenlesbar sein. In Base URL geben Sie die dokumentierte Basis-HTTPS-Adresse des Anbieter-APIs an, ohne den Pfad eines spezifischen Modells und ohne Token in der Query String. Kopieren Sie die URL nicht aus der Browserkonsole und fügen Sie keinen zufälligen Endpfad hinzu. Wenn der Anbieter verschiedene kompatible APIs anbietet, verwenden Sie die Variante, für die ein Adapter installiert ist.

Vendor key muss mit dem 'variant' des installierten Anbieters übereinstimmen, der den nativen Lader der Plattform erkennt. Das Feld Provider library ist im aktuellen Laufzeitumfeld ein kompatives Fallback-Metadatum und bestimmt normalerweise keinen Adapter bei einem nicht leeren Vendor Key. Dies ist kein Dateipfad und kein Mechanismus zur Installation einer neuen Bibliothek. Wenn die benötigte Provider-Variante nicht installiert ist, geben Sie den Task an den Bereitstellungsadministrator weiter.

In Secret name lässt man normalerweise den für diesen Adapter angenommenen Geheimnisnamen, und in Secret value gibt man den übermittelten API-Schlüssel ein. Das Geheimnis sollte nicht im Namen, der URL, der Beschreibung, dem Screenshot, Ticket oder JSON-Profil enthalten sein. Nach dem Speichern zeigt die Oberfläche nur das Vorhandensein des Geheimnisses an, nicht seinen ursprünglichen Wert. Beim Bearbeiten lassen Sie das Wertefeld leer, wenn der Schlüssel nicht geändert werden muss; ein neues, nicht leeres Wert bedeutet eine Geheimnisrotation. Der praktikable Ablauf ist daher: Zuerst den Anbieter deaktiviert erstellen, dann das Geheimnis speichern, die anderen Felder überprüfen und erst danach den Eintrag aktivieren.

Schritt 2. Registrierung des Modells

Gehen Sie zum Modellbereich und wählen Sie den gerade erstellten Anbieter aus. Model key muss exakt mit der ID übereinstimmen, die die API akzeptiert, einschließlich Bindestrichen, Punkten und Versionssuffix. Dies ist kein beliebiger Spitzname. Für einen benutzerfreundlichen Namen gibt es ein separates Feld Display name.

Übertragen Sie dann die drei Limits aus der offiziellen Modellkarte. Maximum context — die volle Grenze des Kontextfensters. Maximum input — maximal zulässiger Input. Maximum output — Grenze der generierten Antwort. Alle Werte werden als positive ganze Zahlen in Tokens angegeben. Input und Output dürfen einzeln nicht größer sein als der Gesamtkontext. Geben Sie keinen Wertersetzung für den Kontext ein, wenn die ausgewählte API oder der Tarif weniger zulässt.

Tokenizer variant bestimmt die Methode zur Token-Bewertung. Geben Sie die genaue unterstützte Variante an, falls bekannt. Wenn für eine neue Familie derzeit nur eine konservative Bewertung verfügbar ist, verwenden Sie den vereinbarten Namen dieser Variante und nicht willkürlich einen Modellnamen. Das Feld ist obligatorisch: Ein falscher Tokenisierer führt nicht zu einem kosmetischen Fehler, sondern zu einer falschen Berechnung des Kompaktierungsmoments und der zulässigen Anforderungsgröße.

Sichere Aktivierungsreihenfolge

1. Erstellen Sie den Anbieter mit der korrekten HTTPS-URL und dem installierten Adapter.
2. Speichern Sie das Geheimnis und stellen Sie sicher, dass im Verzeichnis das Vorhandensein angezeigt wird.
3. Erstellen Sie das Modell mit dem exakten Model Key und bestätigten Limits.
4. Erstellen Sie ein separates Profil für dieses Modell; ohne Profil ist die Arbeitsrichtlinie nicht definiert.
5. Aktivieren Sie zuerst das Modell und den Anbieter für einen eingeschränkten Test, und weisen Sie dann das Standardprofil zu.

Zum Testen öffnen Sie eine neue KI-Sitzung, wählen explizit das erstellte Profil aus und führen Sie eine kurze Anfrage ohne Tools durch, z. B. die Bitte um eine einzelne Textzeile. Eine neue Sitzung eliminiert den Einfluss der alten Profilauswahl und des akkumulierten Verlaufs. Nach der Basisantwort überprüfen Sie den Streaming-Modus und erst danach Szenarien mit Tools. Die Verfügbarkeit von Tools wird vom Katalog und den Gruppenrechten gesteuert, nicht vom Anbieter- oder Modell-Eintrag.

Typische Fehler

• Authentifizierungsfehler: Überprüfen Sie das Vorhandensein des Geheimnisses, dessen Gültigkeit und die Zugehörigkeit zum benötigten Projekt; rotieren Sie nur bei Bedarf.
• Model not found: Vergleichen Sie den Model Key Zeichen für Zeichen mit der API-Dokumentation und stellen Sie sicher, dass das Modell dem Konto zugelassen ist.
• Ungültiger Pfad: Überprüfen Sie die Base URL, den ausgewählten Adapter und das Fehlen des Modellpfads in der Basisadresse.
• Fehler beim Speichern der Limits: Alle drei Werte müssen positiv sein, und Input und Output dürfen nicht den Kontext überschreiten.
• Modell erscheint nicht im Betrieb: Anbieter, Modell und Profil müssen aktiviert sein; das Profil muss auf dasselbe Paar verweisen und dem aktuellen Benutzer zugänglich sein.

Ändern Sie niemals gleichzeitig Geheimnis, URL, Model Key und Limits in einem aktiven Profil. Führen Sie Änderungen einzeln durch und protokollieren Sie das Überprüfungsergebnis. Für den Wechsel einer Modellgeneration ist es sicherer, ein neues Modell und ein neues Profil zu registrieren, diese separat zu testen und erst dann das Standardprofil umzuschalten. Dies lässt einen klaren Rückweg ohne Verfälschung der Bedeutung bestehender Einträge.

Abnahme und Wartung

Nach einer erfolgreichen minimalen Anfrage protokollieren Sie in der Arbeitsdokumentation den Vendor Key, Model Key, die Profilzuweisung, die Quelle der Limits und das Prüfdatum. Das Geheimnis selbst nicht aufzeichnen. Überprüfen Sie separat das Verhalten bei einem vorübergehend deaktivierten Anbieter: Der Benutzer sollte eine verständliche Fehlermeldung erhalten und nicht eine unendliche Wartezeit. Wenn ein Dienst mehrere Regionen oder Tarifpfade hat, behandeln Sie diese als bewusste Konfigurationen und ändern Sie nicht die Base URL während der Diagnose.

Überprüfen Sie regelmäßig die Limits anhand der aktuellen Dokumentation des Anbieters. Eine Änderung des kommerziellen Modellnamens bedeutet nicht immer eine neue API-ID, und eine neue ID garantiert keinen früheren Tokenizer Variant. Jede solche Änderung durchläuft denselben Zyklus: separater Eintrag, Profil, Test-Sitzung, Antwortprüfung und erst danach die Benutzerumschaltung.