Podłączenie dostawcy AI i rejestracja modelu

Trzy warstwy, których nie należy mylić

Podłączenie modelu w Sapphire I.C.D.S. składa się z trzech osobnych rekordów. Dostawca opisuje usługę zewnętrzną: jej stabilny klucz, bazowy URL, zainstalowany adapter i sekret dostępu. Model przechowuje identyfikator modelu u dostawcy oraz jego ograniczenia techniczne. Profil określa zachowanie robocze: instrukcję systemową, budżet kontekstu, rozmiar odpowiedzi i parametry dodatkowe. Taki podział pozwala używać jednego modelu w kilku trybach bez powielania klucza API i bez zastępowania rzeczywistych ograniczeń modelu ustawieniami pojedynczego zadania.

Konfigurację wykonuje się w sekcji administracyjnej AI Settings. Dostęp musi zostać nadany przez Helix. Przed rozpoczęciem pobierz od dostawcy aktualne wartości base URL, model ID i limitów wybranego modelu oraz upewnij się, że odpowiedni adapter jest już zainstalowany w konturze serwerowym Sapphire. Wpisanie nazwy w formularzu nie instaluje biblioteki.

Krok 1. Utworzenie dostawcy

Otwórz sekcję dostawców i utwórz nowy rekord. Pole Vendor key powinno zawierać krótki, stabilny identyfikator maszynowy, na przykład acme_ai. Używaj małych liter alfabetu łacińskiego, cyfr i podkreśleń. Nie umieszczaj tu domeny, planu, regionu ani wersji modelu: klucz łączy ustawienia i powinien przetrwać zwykłe zmiany produktu.

Display name jest przeznaczone dla operatorów i może być czytelną nazwą. W polu Base URL podaj udokumentowany bazowy adres HTTPS API dostawcy, bez ścieżki konkretnego modelu i bez tokenu w query string. Nie kopiuj adresu z konsoli przeglądarki ani nie dodawaj przypadkowej trasy. Jeżeli dostawca oferuje kilka zgodnych API, użyj wariantu obsługiwanego przez zainstalowany adapter.

Vendor key musi odpowiadać wariantowi zainstalowanego dostawcy wykrywanemu przez standardowy loader platformy. Pole Provider library w bieżącym runtime jest zgodnościowym fallback metadata i przy niepustym vendor key zwykle nie wyznacza adaptera. Nie jest to ścieżka do pliku ani mechanizm instalowania nowej biblioteki. Jeśli wymagany provider variant nie jest zainstalowany, przekaż zadanie administratorowi wdrożenia.

W Secret name zwykle pozostawia się nazwę oczekiwaną przez adapter, natomiast w Secret value wpisuje się wydany klucz API. Sekretu nie wolno umieszczać w tytule, URL, opisie, zrzucie ekranu, zgłoszeniu ani JSON profilu. Po zapisaniu interfejs pokazuje wyłącznie fakt obecności sekretu, a nie jego pierwotną wartość. Podczas edycji pozostaw pole wartości puste, jeśli klucz nie wymaga zmiany; nowa niepusta wartość oznacza rotację sekretu. Praktyczna kolejność to utworzenie wyłączonego dostawcy, zapisanie sekretu, sprawdzenie pozostałych pól i dopiero wtedy włączenie rekordu.

Krok 2. Rejestracja modelu

Przejdź do sekcji modeli i wybierz utworzonego dostawcę. Model key musi dokładnie odpowiadać identyfikatorowi przyjmowanemu przez API, łącznie z łącznikami, kropkami i sufiksem wersji. Nie jest to dowolny alias. Do wygodnej nazwy służy osobne pole Display name.

Następnie przenieś trzy limity z oficjalnej specyfikacji modelu. Maximum context to pełny limit okna kontekstowego. Maximum input to największe dopuszczalne wejście. Maximum output ogranicza generowaną odpowiedź. Wszystkie wartości podaje się jako dodatnie liczby całkowite tokenów. Wejście i wyjście osobno nie mogą być większe od pełnego kontekstu. Nie wpisuj marketingowej wartości kontekstu, jeżeli wybrane API lub plan dopuszcza mniej.

Tokenizer variant określa sposób szacowania tokenów. Podaj dokładny obsługiwany wariant, jeśli jest znany. Jeżeli dla nowej rodziny dostępna jest tylko konserwatywna estymacja, użyj uzgodnionej nazwy tego wariantu zamiast zgadywać na podstawie nazwy modelu. Pole jest wymagane: błędny tokenizer powoduje niewłaściwe wyznaczanie momentu kompaktowania i rozmiaru żądania, a nie tylko kosmetyczną różnicę.

Bezpieczna kolejność włączania

1. Utwórz dostawcę z prawidłowym adresem HTTPS i zainstalowanym adapterem.
2. Zapisz sekret i sprawdź, czy lista pokazuje jego obecność.
3. Utwórz model z dokładnym model key i potwierdzonymi limitami.
4. Utwórz osobny profil dla modelu; bez profilu polityka robocza nie jest określona.
5. Najpierw włącz model i dostawcę do ograniczonego testu, a dopiero potem ustaw profil domyślny.

W celu weryfikacji otwórz nową sesję AI, jawnie wybierz utworzony profil i wykonaj krótkie żądanie bez narzędzi, na przykład prośbę o jedną linię tekstu. Nowa sesja wyklucza wpływ starego wyboru profilu i zgromadzonej historii. Po uzyskaniu podstawowej odpowiedzi sprawdź streaming, a dopiero potem scenariusze z narzędziami. Dostępnością narzędzi zarządzają katalog i uprawnienia grup, a nie rekord dostawcy lub modelu.

Typowe błędy

• Błąd uwierzytelnienia: sprawdź obecność, ważność i przypisanie sekretu do właściwego projektu; rotuj go tylko w razie potrzeby.
• Model not found: porównaj model key znak po znaku z dokumentacją API i upewnij się, że konto ma dostęp do modelu.
• Nieprawidłowa trasa: sprawdź base URL, wybrany adapter i brak ścieżki modelu w adresie bazowym.
• Odrzucenie limitów: wszystkie trzy wartości muszą być dodatnie, a input i output nie mogą przekraczać context.
• Model nie jest dostępny podczas pracy: dostawca, model i profil muszą być włączone; profil musi wskazywać tę samą parę i być dostępny dla bieżącego użytkownika.

Nie zmieniaj jednocześnie sekretu, URL, model key i limitów aktywnego profilu. Wprowadzaj zmiany pojedynczo i zapisuj wynik weryfikacji. Przy zmianie generacji modelu bezpieczniej zarejestrować nowy model i profil, przetestować je osobno, a następnie przełączyć profil domyślny. Pozostawia to czytelną drogę powrotu bez zmiany znaczenia istniejących rekordów.

Odbiór i utrzymanie

Po pomyślnym minimalnym żądaniu zapisz w dokumentacji roboczej vendor key, model key, przeznaczenie profilu, źródło limitów i datę sprawdzenia. Nie zapisuj sekretu. Osobno sprawdź zachowanie przy tymczasowo wyłączonym dostawcy: użytkownik powinien otrzymać czytelny błąd zamiast czekać bez końca. Jeżeli usługa ma kilka regionów lub tras zależnych od planu, traktuj je jako świadome konfiguracje zamiast zmieniać base URL podczas diagnostyki.

Okresowo porównuj limity z aktualną dokumentacją dostawcy. Zmiana handlowej nazwy modelu nie zawsze oznacza nowy identyfikator API, a nowy identyfikator nie gwarantuje tego samego tokenizer variant. Każdą taką zmianę przeprowadzaj w pełnym cyklu: osobny rekord, profil, sesja testowa, weryfikacja odpowiedzi i dopiero wtedy przełączenie użytkowników.