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ź zwracana jest z flagą done_reason ustawioną na length.

To pełna funkcjonalność tego parametru. 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 utrzymuje dla tych tokenów, rośnie wraz z oknem. Dobieranie rozmiaru num_ctx do sprzętu to osobne zadanie z własnymi scenariuszami awarii.

num_predict określa, ile model może zapisać. Jest to reguła zatrzymania, a nie alokacja zasobów. Zwiększenie tej wartości kosztuje czas rzeczywisty, a nie pamięć RAM; ż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 trwałe zapisanie wartości 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 konfigurację:

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 stosowana jest wartość domyślna Ollama. ollama show --modelfile qwen3-capped wyświetla pełną definicję, co stanowi najszybszy sposób na skopiowanie parametrów, z którymi dostarczany jest istniejący model.

Jest to właściwa warstwa dla wartości, którą mają dziedziczyć wszyscy użytkownicy. Nie jest to jednak odpowiednie miejsce, jeśli oczekuje się, że wartość 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, w którym 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 używa tego samego klucza options o tym samym znaczeniu. Wartość zdefiniowana w tym miejscu dotyczy wyłącznie danego wywołania. Jest to warstwa wykorzystywana przez narzędzia: interfejsy czatu, skrypty, wrappery SDK czy 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 tej 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 ustawienie /set w tym miejscu nie wpływa na inne klienty.

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 jest trzecią regułą. 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 problemu. 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, o której zapomniałeś. 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" i 32 oznacza, że serwer uwzględnia 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 z aplikacją.

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 generowanie nieskończone, 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 przez długi czas podawała wartość domyślną 128, zanim wpis został poprawiony pod koniec 2024 roku, dlatego wiele poradników wciąż powiela starą liczbę. Należy zapoznać się z dokumentacją parametrów Modelfile dla wersji, która jest aktualnie uruchomiona, a następnie potwierdzić zachowanie za pomocą testu eval_count opisanego powyżej. Wartość zweryfikowana samodzielnie na własnym serwerze jest ważniejsza niż wartość przeczytana w jakimkolwiek źródle, włącznie z tym wpisem.

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.

Wystarczy poprosić o odpowiedź bez strumieniowania, aby zobaczyć liczby:

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

Czas trwania podano w nanosekundach. W tym bloku, który stanowi przykładową odpowiedź opublikowaną w dokumentacji API Ollama, a nie pomiar 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. Własną szybkość generowania oblicza się dzieląc eval_count przez eval_duration przeliczone na sekundy, a pomiar liczby tokenów na sekundę na własnym sprzęcie warto wykonać raz przed przystąpieniem do jakiejkolwiek optymalizacji. Szybkość ta zależy w równym stopniu od modelu, co od maszyny, więc jeśli długie odpowiedzi generują realne koszty, model stworzony do szybkiego dekodowania, taki jak Nemotron 3.5 Lightning na VPS, pozwala odzyskać część czasu, który w przeciwnym razie chroniony jest niskim limitem.

Resztę załatwia arytmetyka. Przy 8 tokenach na sekundę odpowiedź o długości 2 000 tokenów blokuje maszynę na ponad cztery minuty, a model nie wie, że oczekiwano tylko akapitu. Niektóre modele wpadają również w pętlę, powtarzając frazę, dopóki coś ich nie zatrzyma. Bez limitu pojedyncze żądanie obciąża rdzeń, dopóki nie wyczerpie się okno kontekstowe. num_predict to ustawienie, które nakłada ograniczenie; jest ono kluczowe w przypadku małego samodzielnie hostowanego VPS z Ollama, gdzie jedno długie żądanie zajmuje zasoby całej maszyny.

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 zamykającego nawiasu klamrowego. 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ładna zgodność oznacza, że zatrzymało go num_predict, a mniejsza liczba oznacza, że najpierw wypełnił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 je ukrywa, wyślij jedno żądanie z curl, aby sprawdzić, co faktycznie przekazał serwer.

Jeden dodatkowy punkt pozwala zaoszczędzić zmarnowane 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 nieograniczony i użyj Ctrl+C, aby przerwać niekontrolowaną odpowiedź. Monitorujesz ekran na bieżąco.
• W przypadku zadań skryptowych ustaw limit. Brak limitu w pętli powoduje, że zadanie wsadowe, które powinno zająć dziesięć minut, może być uruchomione jeszcze następnego dnia.
• 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. Wskazanie agenta programistycznego na 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 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 (KV cache) rośnie wraz z tym parametrem. num_predict określa, ile tokenów model może wygenerować w jednej odpowiedzi. Wpływa to głównie na czas przetwarzania, a nie na pamięć, ponieważ zasoby nie są rezerwowane z wyprzedzeniem. Wygenerowane tokeny wliczają się do obu limitów, więc odpowiedź może zostać przerwana przez osiągnięcie 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 wyś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 tego, co dociera 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 przerwane 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 wyczerpał limit. 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 mniejsze, oznacza to, że wypełniło się okno kontekstowe. Podczas 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?

Sprawdź ją w swojej instalacji, zamiast polegać na artykułach. Według stanu na sierpień 2026, dokumentacja Modelfile w Ollama podaje wartość domyślną jako -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 wymieniały również -2 dla wypełniania 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ę przy done_reason z stop, oznacza to, że model uznał zadanie za zakończone, a wyższy limit niczego nie zmieni. Długość odpowiedzi w takim przypadku zależy od promptu: poproś o konkretną strukturę, liczbę sekcji lub określony poziom szczegółowości. Zwiększ num_predict tylko wtedy, gdy done_reason zwraca length.