Dokumentacja

Profile modeli, kontekst i Extra JSON

Co określa profil

Rekord modelu w Sapphire I.C.D.S. opisuje możliwości techniczne, natomiast profil określa sposób ich użycia. Dla jednego modelu można utworzyć na przykład rygorystyczny profil wsparcia, zwięzły profil klasyfikacji i rozszerzony profil analizy. Każdy może mieć własną instrukcję systemową, długość odpowiedzi i budżet kontekstu, ale wszystkie ustawienia muszą mieścić się w limitach zarejestrowanego modelu.

W sekcji AI Settings → Profiles wybierz dostawcę i model. Muszą należeć do tej samej pary: profil nie może połączyć modelu z innym dostawcą. Profile key to stabilny identyfikator maszynowy, na przykład support_ru. Nie używaj nazwiska pracownika ani tymczasowego numeru zadania. Włączony profil jest dostępny do wyboru, a profil domyślny zostaje użyty, gdy klient nie wskaże konkretnego rekordu. Ustaw default dopiero po testach.

Instrukcja systemowa i format odpowiedzi

System prompt definiuje rolę i stałe reguły wybranego trybu. Zapisz go jako możliwy do zweryfikowania kontrakt: zakres zadań, język, format wyniku, ograniczenia i kryterium zakończenia. Nie umieszczaj tu kluczy API, danych osobowych, całej bazy wiedzy ani instrukcji, które operator musi zmieniać dla każdego żądania.

Podczas uruchomienia system zaczyna od instrukcji systemowej profilu i dodaje włączone instrukcje zarządzane przez administrację jako obowiązkową politykę firmową. Historia sesji i jej podsumowanie pozostają danymi. Pamięć i wiedza nie są ładowane w całości; model pobiera je na żądanie za pomocą dozwolonych narzędzi. Zwiększanie system prompt nie zastępuje więc konfiguracji instrukcji, pamięci, wiedzy ani uprawnień do narzędzi.

Response format ustawiaj tylko w postaci rozumianej przez wybrany adapter i model. Dla zwykłego dialogu bezpiecznym punktem wyjścia jest tekst. Jeżeli potrzebny jest strukturalny JSON, najpierw potwierdź obsługę przez model i odbiorcę: sam wpis w profilu nie gwarantuje zgodności ze schematem biznesowym.

Reasoning, Temperature i Top P

Reasoning effort stosuj wyłącznie dla modeli, które dokumentują taki tryb. Nie kopiuj wartości z innej rodziny modeli. Temperature i Top P mają osobne przełączniki. Gdy parametr jest wyłączony, profil nie powinien narzucać go dostawcy; jest to lepsze niż przypadkowe wysłanie zera. Zwykle wystarczy sterować zmiennością jednym mechanizmem, a drugi pozostawić wyłączony. Ekstrakcja faktów i klasyfikacja wymagają zazwyczaj stabilniejszych ustawień, a generowanie wariantów może być swobodniejsze, lecz dozwolony zakres zawsze należy sprawdzić w dokumentacji modelu.

Jak obliczany jest kontekst

Rekord modelu zawiera trzy górne granice: pełny kontekst, maksymalne wejście i maksymalne wyjście. Profil określa cztery wartości robocze. Max output tokens ogranicza pojedynczą odpowiedź. Active context tokens to budżet dostępny dla agenta Sapphire. Compaction reserve tokens to część zarezerwowana na bezpieczne kompaktowanie. Automatyczny próg wynosi:

active_context_tokens - compaction_reserve_tokens

Rezerwa musi być dodatnia i ściśle mniejsza od aktywnego budżetu. Aktywny kontekst nie może przekraczać maksymalnego wejścia modelu, limit odpowiedzi maksymalnego wyjścia, a ich suma musi mieścić się w pełnym kontekście. Na przykład przy kontekście 128000, wejściu 120000 i wyjściu 8192 można ustawić aktywny budżet 64000, rezerwę 16000 i odpowiedź 4096. Próg kompaktowania wyniesie 48000. To przykład arytmetyczny, a nie uniwersalna rekomendacja.

Maximum agent rounds ogranicza cykle model–narzędzie, a Maximum agent runtime całkowity czas w sekundach. Wartość 0 oznacza brak tylko tego limitu profilowego; nie usuwa limitów dostawcy, anulowania przez użytkownika, ochrony przed brakiem postępu ani ograniczeń systemowych. Dla scenariuszy krytycznych lub kosztownych ustaw jawne wartości skończone i zmierz rzeczywiste działanie przed ich zwiększeniem.

Streaming i zmiana modelu

Przełącznik streaming określa preferowany sposób dostarczania odpowiedzi. Nie zmieni synchronicznego API w strumieniowe, jeśli dostawca nie obsługuje streamingu. Przy zmianie modelu utwórz nowy profil albo uważnie przelicz wszystkie budżety. Stanu kompaktowania powiązanego z jedną parą dostawca–model nie można uznać za przenośny do innej pary.

Extra JSON bez ukrytych niespodzianek

Extra JSON to opcjonalny obiekt JSON dla dodatkowych parametrów udokumentowanych przez konkretnego dostawcę. Jest punktem rozszerzenia, a nie drugim profilem. Zacznij od pustego obiektu:

{}

Jeżeli API rzeczywiście wymaga dodatkowej opcji, dodaj tylko ją. Neutralny przykład struktury:

{
  "metadata": {
    "integration": "sapphire-docs"
  }
}

Przykład jest dopuszczalny tylko wtedy, gdy wybrane API obsługuje metadata. JSON musi być obiektem z podwójnymi cudzysłowami, bez komentarzy i końcowych przecinków. Nie umieszczaj w nim sekretu, wartości Authorization, base URL, model key, identyfikatorów użytkownika ani treści poufnej.

Nie powielaj w Extra JSON podstawowych pól żądania, takich jak model, narzędzia, wybór narzędzia, wiadomości wejściowe, temperature, Top P czy max output tokens. Konflikt utrudnia diagnostykę i może zmienić zachowanie po aktualizacji adaptera. enable_tools nie służy do obchodzenia zarządzania narzędziami, a zarządzanej polityki kontekstu nie należy zastępować dowolną opcją. Narzędzia są dopuszczane przez katalog serwera, uprawnienia grup i wybór sesji.

Weryfikacja profilu

Zapisz profil jako włączony, ale nie ustawiaj go jako domyślnego.
Utwórz nową sesję i jawnie wybierz profil.
Sprawdź krótką odpowiedź, instrukcję systemową i wymagany format.
Wykonaj długi test, obserwując próg kontekstu i kompaktowanie.
Sprawdź zatrzymanie po liczbie rund i czasie, jeśli limity są niezerowe.
Dodawaj do Extra JSON po jednym kluczu i powtarzaj test.
Dopiero wtedy ustaw profil jako default.

Jeżeli żądanie jest odrzucane, najpierw wyczyść Extra JSON, wyłącz opcjonalne parametry sampling i powtórz test minimalny. Następnie sprawdź limity oraz obsługę reasoning i response format. Taka kolejność oddziela błąd rejestracji podstawowej od niezgodnej opcji dodatkowej.

Jak dobrać wielkość budżetu

Zacznij od zmierzonego scenariusza roboczego, a nie od maksimum modelu. Oszacuj instrukcję systemową, typową historię, oczekiwane wyniki narzędzi i zapas na odpowiedź. Zbyt duży aktywny kontekst podnosi koszt i czas przetwarzania, a zbyt mały powoduje częste kompaktowanie. Rezerwa musi pozwalać utworzyć poprawne podsumowanie przed osiągnięciem twardej granicy, dlatego nie powinna być wartością wyłącznie symboliczną.

Rozdzielaj profile, gdy zadania istotnie różnią się długością, reasoning lub wymaganiami czasowymi. Jeden profil uniwersalny trudniej zweryfikować i bezpiecznie zmienić. Dokumentuj przeznaczenie profilu, lecz nie koduj routingu ani uprawnień w system prompt: wybór profilu i dopuszczenie narzędzi są kontrolowane przez inne warstwy.