Ollama num_predict: jak ograniczyć liczbę tokenów

Działanie parametru num_predict w Ollama

num_predict to opcja w Ollama, która ogranicza liczbę tokenów generowanych przez model w pojedynczej odpowiedzi. Limit dotyczy wyłącznie tokenów wyjściowych, więc długość promptu nie jest wliczana do tego ograniczenia. Po osiągnięciu limitu generowanie zostaje przerwane w bieżącym miejscu, czasami w połowie słowa, a odpowiedź zwraca flagę done_reason ustawioną na length.

To pełny zakres działania tej funkcji. Trudność polega na tym, że Ollama oferuje trzy niezależne miejsca do zdefiniowania tej wartości, a ustawienie znajdujące się najbliżej żądania ma priorytet. Niemal każde zgłoszenie o treści "num_predict nie działa" wynika z faktu, że jedna warstwa konfiguracji po cichu nadpisuje drugą.

num_predict to nie to samo co num_ctx

Te dwie opcje są mylone częściej niż jakakolwiek inna para w Ollama, a pomyłka ta generuje realne straty czasu podczas debugowania.

num_ctx określa, ile model może przeczytać. Jest to rozmiar okna kontekstowego, które mieści prompt oraz wszystko, co zostało do tej pory wygenerowane. Zwiększenie tej wartości kosztuje pamięć, ponieważ pamięć podręczna kluczy/wartości (key/value cache), którą model przechowuje dla tych tokenów, rośnie wraz z oknem. Dopasowanie num_ctx do sprzętu to osobne zadanie z własnymi scenariuszami błędów.

num_predict określa, ile model może zapisać. Jest to reguła zatrzymania, a nie alokacja. Zwiększenie tej wartości kosztuje czas rzeczywisty (wall-clock time), a nie pamięć RAM, i żadne zasoby nie są rezerwowane z wyprzedzeniem.

Parametry te spotykają się w jednym punkcie. Wygenerowane tokeny trafiają do okna kontekstowego w miarę ich tworzenia, więc odpowiedź może zostać przerwana również dlatego, że okno się zapełniło, a nie dlatego, że osiągnięto limit. Ollama zgłasza length w obu przypadkach, dlatego liczbą, która pozwala je rozróżnić, jest eval_count, co zostało omówione w dalszej części.

Ustawienie wartości za pomocą Modelfile

Plik Modelfile pozwala na stałe zapisać wartość w tworzonym modelu. Należy utworzyć plik:

FROM qwen3:8b
PARAMETER num_ctx 8192
PARAMETER num_predict 512

Następnie należy zbudować model i sprawdzić jego parametry:

ollama create qwen3-capped -f Modelfile
ollama show --parameters qwen3-capped

ollama show --parameters wyświetla jeden wiersz dla każdego zapisanego parametru wraz z jego wartością. Jeśli num_predict nie znajduje się w tym wyniku, model nie posiada narzuconego limitu i stosowane są wartości domyślne Ollama. ollama show --modelfile qwen3-capped wyświetla pełną definicję, co jest również najszybszym sposobem na skopiowanie parametrów, z którymi dostarczany jest istniejący model. Tworzenie modelu z limitem w ten sposób prawie nie zajmuje dodatkowego miejsca na dysku, ponieważ nowy wpis wykorzystuje ponownie pliki wag (blobs) pobrane wcześniej przez model bazowy, zamiast je kopiować. Warto wiedzieć, gdzie Ollama przechowuje te pliki, zanim dysk systemowy VPS zostanie zapełniony.

Jest to właściwa warstwa dla wartości, którą mają dziedziczyć wszyscy użytkownicy modelu. Nie jest to jednak właściwa warstwa, jeśli oczekuje się, że wartość ta będzie ostateczna, ponieważ tak nie jest.

Ustawienie parametru w obiekcie options dla każdego żądania

Każdy punkt końcowy generowania przyjmuje obiekt options, wewnątrz którego umieszcza się num_predict:

curl http://localhost:11434/api/generate -d '{
  "model": "qwen3:8b",
  "prompt": "Explain what a reverse proxy does.",
  "stream": false,
  "options": { "num_predict": 128 }
}'

/api/chat wykorzystuje ten sam klucz options o identycznym znaczeniu. Wartość zdefiniowana w tym miejscu dotyczy wyłącznie pojedynczego wywołania. Jest to warstwa wykorzystywana przez narzędzia: interfejsy czatu, skrypty, wrappery SDK oraz agenty programistyczne. Wszystkie one przesyłają obiekt options, niezależnie od tego, czy udostępniają użytkownikowi pole do jego edycji.

Ustawienie dla jednej sesji za pomocą parametru /set

Wewnątrz ollama run sesja interaktywna konfiguruje opcje dla pozostałej części bieżącej sesji:

>>> /set parameter num_predict 256
>>> /show parameters

/show parameters wyświetla dane, które sesja wyśle wraz z następną wiadomością, co stanowi najszybszy sposób na potwierdzenie wprowadzenia zmian. Wartość pozostaje aktywna do momentu wpisania /bye. Aby ją zachować, /save qwen3-capped zapisuje bieżącą sesję wraz z parametrami jako nowy model. Żadne dane /set w tym miejscu nie są przesyłane do innych klientów.

Które ustawienie ma pierwszeństwo i dlaczego Twoje jest ignorowane

Kolejność jest krótka. Opcje przesłane wraz z żądaniem mają pierwszeństwo przed wszystkim innym. Linia PARAMETER num_predict w pliku Modelfile modelu stanowi rozwiązanie zapasowe, używane, gdy żądanie nie zawiera żadnej wartości. W przypadku braku obu, stosowane są wbudowane wartości domyślne Ollama.

/set parameter nie stanowi trzeciej reguły. Sesja interaktywna jest klientem API, więc to, co w niej ustawisz, jest wysyłane jako options danego żądania, co jest dokładnie powodem, dla którego nadpisuje ono Modelfile dla tej sesji.

Oto wyjaśnienie awarii. Dodajesz PARAMETER num_predict 512, przebudowujesz model, a odpowiedzi nadal osiągają tysiące tokenów. Twoje ustawienie jest obecne, a ollama show --parameters to potwierdza. Jest ono nadpisywane przy każdym żądaniu, ponieważ klient wysyła własny obiekt options zawierający własną liczbę, często wartość wpisaną w ekranie ustawień miesiące temu i zapomnianą. ollama show odczytuje zapisany model. Nie może pokazać tego, co dociera przez HTTP.

Zweryfikuj stronę serwera za pomocą jednego polecenia. Wyślij żądanie, które wygeneruje długą odpowiedź, wymuś niski limit i odczytaj dwa pola:

curl -s http://localhost:11434/api/generate -d '{
  "model": "qwen3-capped",
  "prompt": "Describe the Linux boot process in detail.",
  "stream": false,
  "options": { "num_predict": 32 }
}' | jq '.done_reason, .eval_count'

Powinno to wyświetlić "length" oraz 32. Zainstaluj jq za pomocą sudo apt install -y jq, jeśli go brakuje. Odpowiedź "length" oraz 32 oznacza, że serwer respektuje opcję, a Twoja aplikacja wysyła coś innego. Aby uzyskać własny raport serwera dotyczący żądania, zrestartuj go z OLLAMA_DEBUG=1 w środowisku i monitoruj journalctl -u ollama -f podczas komunikacji aplikacji z serwerem.

Wartości ujemne oraz liczby, których nie należy kopiować

num_predict akceptuje również wartości ujemne, które pełnią rolę wskaźników, a nie liczników. Jedna wartość ujemna oznacza „brak limitu, kontynuuj generowanie”. Inna oznaczała „wypełnij pozostały kontekst”. Według stanu na sierpień 2026 dokumentacja Ollama Modelfile podaje wartość domyślną -1, czyli nieskończone generowanie, a wcześniejsze wersje tej samej tabeli wskazywały -2 dla wypełniania kontekstu.

Należy traktować te informacje jako zależne od wersji, ponieważ ulegały one zmianom. Dokumentacja techniczna przez długi czas podawała 128 jako wartość domyślną, zanim wpis został poprawiony pod koniec 2024 roku, dlatego wiele poradników wciąż powiela tę nieaktualną liczbę. Należy zapoznać się z dokumentacją parametrów Modelfile dla wersji, która jest aktualnie uruchomiona, a następnie potwierdzić działanie za pomocą testu eval_count opisanego powyżej. Wartość zweryfikowana samodzielnie na własnym serwerze jest bardziej wiarygodna niż jakakolwiek wartość znaleziona w zewnętrznych źródłach, w tym w niniejszym wpisie.

Dlaczego długość wygenerowanej odpowiedzi jest głównym kosztem na VPS bez GPU

Generowanie przebiega w dwóch fazach o skrajnie różnych prędkościach. Tokeny promptu są przetwarzane w partiach, wiele naraz. Tokeny wyjściowe są generowane pojedynczo, a każdy z nich wymaga pełnego przejścia przez wagi modelu. Na VPS bez GPU to przejście jest ograniczone przepustowością pamięci, dlatego wygenerowanie jednego tokena kosztuje znacznie więcej niż przetworzenie jednego tokena promptu. Ponieważ to przejście wymaga odczytania każdej wagi, liczba bajtów zajmowanych przez każdą wagę wyznacza górny limit szybkości generowania tokenów, dlatego wersja q4 dekoduje szybciej niż ten sam model w q8 lub fp16.

Poproś o odpowiedź bez strumieniowania, a liczby staną się oczywiste:

"prompt_eval_count": 26,
"prompt_eval_duration": 107345000,
"eval_count": 237,
"eval_duration": 4289432000

Czas trwania podano w nanosekundach. W tym bloku, który jest przykładową odpowiedzią opublikowaną w dokumentacji API Ollama, a nie pomiarem konkretnego serwera, 26 tokenów promptu zajęło około 0,1 sekundy, podczas gdy 237 tokenów wyjściowych zajęło około 4,3 sekundy. Twoja własna szybkość generowania to eval_count podzielone przez eval_duration przeliczone na sekundy, a pomiar liczby tokenów na sekundę na własnym sprzęcie warto wykonać raz przed dostrajaniem czegokolwiek innego. Ta szybkość zależy od modelu w takim samym stopniu, jak od maszyny, więc jeśli długie odpowiedzi stanowią realny koszt, model stworzony do szybkiego dekodowania, taki jak Nemotron 3.5 Lightning na VPS, pozwala odzyskać część czasu, który w przeciwnym razie chroni niski limit.

Arytmetyka robi resztę. Przy 8 tokenach na sekundę odpowiedź o długości 2000 tokenów zajmuje maszynę na ponad cztery minuty, a model nie wie, że oczekiwałeś tylko akapitu. Model wnioskujący zużywa część tego budżetu na myślenie, zanim napisze pierwsze słowo, o które prosiłeś, a to myślenie jest generowane token po tokenie, tak jak wszystko inne, więc wysiłek wnioskowania, o który prosisz jest kolejnym czynnikiem wpływającym na ten sam rachunek. Niektóre modele wpadają również w pętlę, powtarzając frazę, dopóki coś ich nie zatrzyma. Bez limitu to jedno żądanie obciąża rdzeń, dopóki nie wyczerpie się okno kontekstowe. num_predict to ustawienie, które nakłada ograniczenie, co ma największe znaczenie na małym samodzielnie hostowanym VPS z Ollama, gdzie jedno długie żądanie zajmuje całą maszynę.

Ucięte wyjście to zazwyczaj limit, a nie błąd modelu

Objawy wyglądają na awarię modelu. Odpowiedź urywa się w połowie zdania. JSON nie poddaje się parsowaniu, ponieważ brakuje nawiasu zamykającego. Odruchowo wini się model lub kwantyzację. Najpierw należy przeczytać odpowiedź.

done_reason odpowiada bezpośrednio na pytanie. stop oznacza, że model zakończył pracę samodzielnie, emitując token końca sekwencji lub dopasowując jeden z ciągów w opcji stop. length oznacza, że generowanie zostało przerwane z powodu braku miejsca. Gdy widzisz length, porównaj eval_count ze swoim limitem: dokładne dopasowanie oznacza, że zatrzymał go num_predict, a mniejsza liczba oznacza, że najpierw wyczerpało się okno kontekstowe.

Podczas strumieniowania te pola docierają w ostatnim fragmencie, tym zawierającym "done": true. Wiele bibliotek klienckich odrzuca ten fragment i przekazuje kodowi tylko tekst, dlatego to samo ucięcie wygląda na niewyjaśnione wewnątrz aplikacji, a jest oczywiste w curl. Jeśli biblioteka ukrywa te dane, wyślij jedno żądanie z curl, aby sprawdzić, co faktycznie zwrócił serwer.

Jeszcze jedna uwaga pozwala zaoszczędzić stracone popołudnie. Zwiększenie num_predict nie sprawia, że model pisze więcej. Usuwa jedynie górny limit. Jeśli odpowiedź kończy się na 200 tokenach przy done_reason wynoszącym stop, model uznał, że skończył, a większy limit niczego nie zmieni. Krótkie odpowiedzi z stop to problem z promptowaniem. Krótkie odpowiedzi z length to problem z limitem.

Wybór wartości

• W przypadku interaktywnego czatu pozostaw limit bez ograniczeń i użyj Ctrl+C, aby zatrzymać niekontrolowaną odpowiedź. Monitorujesz ekran na bieżąco.
• W przypadku zadań skryptowych ustaw limit. Brak ograniczeń w pętli sprawia, że zadanie wsadowe, które powinno zająć dziesięć minut, może nadal działać następnego dnia rano.
• W przypadku wyjścia strukturalnego ustaw limit powyżej największego oczekiwanego poprawnego dokumentu, a następnie traktuj done_reason z length jako błąd krytyczny i ponów próbę zamiast analizować otrzymane dane.
• W przypadku agenta programistycznego wartość ta powinna znajdować się w konfiguracji samego agenta, ponieważ przesyła on własne opcje przy każdym żądaniu. Wskazywanie agentowi programistycznemu instancji Ollama opisuje, gdzie znajdują się te ustawienia.

Limit zlicza tokeny, a nie słowa czy znaki, więc nie należy go szacować. Wygeneruj jedną reprezentatywną odpowiedź bez limitu, odczytaj eval_count i ustaw limit z odpowiednim zapasem powyżej tej wartości. Rodziny modeli tokenizują tekst w różny sposób, więc wartość pasująca do modelu Llama może uciąć tę samą odpowiedź pochodzącą z modelu Qwen 3 na tym samym VPS.

FAQ

Jaka jest różnica między num_ctx a num_predict w Ollama?

num_ctx to rozmiar okna kontekstowego, który określa, ile danych model może odczytać: prompt oraz wszystko, co zostało do tej pory wygenerowane. Wpływa to na zużycie pamięci, ponieważ pamięć podręczna kluczy i wartości (key/value cache) rośnie wraz z tym parametrem. num_predict określa, ile tokenów model może zapisać w jednej odpowiedzi. Parametr ten wpływa na czas generowania, a nie na pamięć, i nie rezerwuje zasobów z wyprzedzeniem. Wygenerowane tokeny wliczają się do obu limitów, więc odpowiedź może zostać przerwana przez przekroczenie któregokolwiek z nich.

Dlaczego moje ustawienie num_predict wydaje się być ignorowane?

Ponieważ wartość przesłana w żądaniu nadpisuje wartość zapisaną w modelu. Jeśli umieścisz PARAMETER num_predict 512 w pliku Modelfile, a następnie użyjesz tego modelu z poziomu interfejsu czatu lub agenta programistycznego, klient prześle własny obiekt options, którego wartość będzie nadrzędna. ollama show --parameters nadal wyświetla Twoją wartość, ponieważ odczytuje zapisany model i nie widzi danych przesyłanych przez HTTP. Wyślij jedno żądanie z curl przy użyciu "options": {"num_predict": 32} i sprawdź, czy eval_count zwraca 32; potwierdzi to, że serwer działa poprawnie, a problem leży po stronie aplikacji.

Jak sprawdzić, czy wyjście zostało ucięte przez num_predict?

Wyślij żądanie z "stream": false i odczytaj done_reason. Wartość stop oznacza, że model zakończył pracę samodzielnie. Wartość length oznacza, że zabrakło miejsca. Następnie porównaj eval_count ze swoim limitem: jeśli wartości są identyczne, oznacza to, że num_predict zatrzymało proces, a jeśli eval_count jest mniejsza, oznacza to, że wypełniło się okno kontekstowe. W przypadku strumieniowania oba pola docierają w ostatnim fragmencie z "done": true, co wiele bibliotek klienckich odrzuca, zanim kod otrzyma do nich dostęp.

Jaka jest domyślna wartość num_predict?

Należy sprawdzić ją w swojej instalacji, zamiast polegać na artykułach. Według stanu na sierpień 2026 dokumentacja Modelfile w Ollama podaje wartość domyślną -1, co oznacza brak limitu generowania. Wpis ten został poprawiony pod koniec 2024 roku po latach dokumentowania wartości 128. Wartości ujemne są sygnałami sterującymi, a nie licznikami, a starsze wersje tej samej tabeli podawały również -2 dla wypełnienia pozostałego kontekstu. Sprawdź dokumentację parametrów Modelfile dla swojej wersji, a następnie potwierdź ją za pomocą ollama show --parameters i jednego żądania curl.

Czy zwiększenie num_predict sprawi, że model będzie pisał dłuższe odpowiedzi?

Nie. Zwiększenie tego parametru jedynie usuwa górny limit. Jeśli odpowiedź kończy się na done_reason z stop, oznacza to, że model uznał zadanie za zakończone, a wyższy limit niczego nie zmieni. Długość odpowiedzi zależy w takim przypadku od promptu: należy poprosić o konkretną strukturę, liczbę sekcji lub określony poziom szczegółowości. Zwiększ num_predict tylko wtedy, gdy done_reason zwraca length.