Ollama num_predict 설정으로 출력 토큰 제한하기
Ollama에서 num_predict를 사용하여 모델의 최대 출력 토큰 수를 제한하는 방법을 설명합니다. Modelfile, API 요청, 실행 시 설정 우선순위를 확인하고 done_reason 필드를 통해 응답이 중단된 이유를 정확히 파악하는 방법을 정리했습니다.
Ollama에서 num_predict의 역할
num_predict은 모델이 한 번의 응답으로 생성할 수 있는 토큰의 최대 개수를 제한하는 Ollama 옵션입니다. 이 설정은 출력 토큰만을 계산하므로, 프롬프트 길이는 제한에 포함되지 않습니다. 모델이 설정한 제한에 도달하면 생성이 즉시 중단되며, 때로는 단어 중간에 끊기기도 합니다. 이때 응답의 done_reason 값은 length로 설정되어 반환됩니다.
이 기능의 전부는 이것이 전부입니다. 다만 Ollama는 이 값을 설정할 수 있는 세 곳의 서로 다른 위치를 제공하며, 요청과 가장 가까운 설정이 우선권을 갖습니다. "num_predict가 작동하지 않는다"는 대부분의 보고는 한 설정 계층이 다른 계층을 조용히 덮어쓰고 있기 때문에 발생합니다.
num_predict는 num_ctx가 아니다
Ollama에서 이 두 옵션은 다른 어떤 옵션 쌍보다 자주 혼동되며, 이로 인해 실제 디버깅 시간이 늘어난다.
num_ctx은 모델이 읽을 수 있는 양이다. 프롬프트와 지금까지 생성된 모든 내용을 담는 context window의 크기다. 모델이 해당 토큰을 유지하기 위해 사용하는 key/value cache가 window 크기에 따라 증가하므로, 값을 높이면 메모리 사용량이 늘어난다. 하드웨어에 맞는 num_ctx 크기 조정은 별도로 수행해야 하며, 고유한 실패 원인이 있다.
num_predict은 모델이 쓸 양이다. 이는 할당량이 아니라 중지 규칙이다. 값을 높이면 RAM이 아니라 wall-clock 시간이 늘어나며, 사전에 메모리를 예약하지 않는다.
두 옵션은 한 지점에서 만난다. 생성된 토큰은 생성되는 즉시 context window 안에 들어간다. Ollama v0.40.11에서는 대부분의 모델에서 context shift가 기본적으로 활성화되어 있으므로, window가 가득 차면 이전 토큰을 삭제하고 생성을 계속한다. shift가 꺼져 있거나 요청에서 "shift": false을 전송했거나 모델이 shift를 지원하지 않는 경우에는, 설정한 상한에 도달해서가 아니라 window가 가득 차서 응답이 중단될 수도 있다. Ollama는 두 경우 모두 length을 보고하므로, 두 경우를 구분하는 값은 eval_count이며 아래에서 자세히 설명한다.
Modelfile을 사용하여 한 번에 설정하기
Modelfile은 생성하는 모델에 값을 고정합니다. 파일을 작성하십시오:
FROM qwen3:8b
PARAMETER num_ctx 8192
PARAMETER num_predict 512그런 다음 빌드하고 빌드된 내용을 확인하십시오:
ollama create qwen3-capped -f Modelfile
ollama show --parameters qwen3-cappedollama show --parameters은 저장된 매개변수와 그 값을 한 줄씩 출력합니다. 해당 출력에 num_predict가 없다면 모델에 고정된 제한이 없으며 Ollama의 기본값이 적용됩니다. ollama show --modelfile qwen3-capped는 전체 정의를 출력하며, 이는 기존 모델에 포함된 매개변수를 복사하는 가장 빠른 방법이기도 합니다. 이런 방식으로 제한된 모델을 생성하면 디스크 공간을 거의 차지하지 않습니다. 새 항목은 가중치 블롭(weight blobs)을 복사하는 대신 기본 모델이 이미 다운로드한 블롭을 재사용하기 때문입니다. Ollama가 해당 블롭을 보관하는 위치는 VPS 루트 디스크가 가득 차기 전에 알아두는 것이 좋습니다.
이 계층은 모든 호출자가 상속받기를 원하는 값에 적합합니다. 하지만 이 설정이 최종적일 것이라고 기대한다면 잘못된 계층입니다. 왜냐하면 그렇지 않기 때문입니다.
요청별로 options 객체에 설정하기
모든 생성 엔드포인트는 options 객체를 인자로 받으며, 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은 동일한 의미를 가진 동일한 options 키를 사용합니다. 여기에 설정된 값은 해당 호출에만 적용되며 다른 곳에는 영향을 주지 않습니다. 이 계층은 채팅 프런트엔드, 스크립트, SDK 래퍼, 코딩 에이전트와 같은 도구들이 사용하는 영역입니다. 이 도구들은 사용자가 설정 화면을 보는지 여부와 관계없이 모두 options 객체를 전송합니다.
/set 매개변수를 사용하여 단일 세션에 설정하기
ollama run 내부에서 대화형 세션은 해당 세션이 유지되는 동안 옵션을 설정합니다:
>>> /set parameter num_predict 256
>>> /show parameters/show parameters는 다음 메시지와 함께 전송될 내용을 출력하므로, 변경 사항이 적용되었는지 확인하는 가장 빠른 방법입니다. 이 값은 /bye을 입력하기 전까지 유지됩니다. 설정을 유지하려면 /save qwen3-capped를 사용하여 현재 세션과 매개변수를 포함한 내용을 새 모델로 저장하십시오. 여기서 /set한 내용은 다른 클라이언트에 영향을 주지 않습니다.
어떤 설정이 우선 적용되는가, 그리고 설정이 무시된 것처럼 보이는 이유
순서는 간단합니다. 요청과 함께 전송된 옵션이 다른 모든 설정보다 우선합니다. 모델의 Modelfile에 있는 PARAMETER num_predict 줄은 요청에 값이 없을 때 사용하는 대체 설정입니다. 둘 다 없으면 Ollama의 기본값이 적용됩니다.
/set parameter은 세 번째 규칙이 아닙니다. 대화형 세션은 API 클라이언트이므로, 여기에서 설정한 값은 해당 요청의 options으로 전송됩니다. 따라서 해당 세션에서는 Modelfile의 설정을 정확히 덮어씁니다.
이제 이 동작으로 설명되는 실패 사례를 살펴보겠습니다. PARAMETER num_predict 512을 추가하고 모델을 다시 빌드했는데도 응답이 수천 개의 토큰까지 계속 생성됩니다. 설정은 존재하며 ollama show --parameters으로도 확인할 수 있습니다. 하지만 모든 요청에서 재정의되고 있습니다. 클라이언트가 자체 숫자를 담은 자체 options 객체를 전송하기 때문입니다. 이 숫자는 몇 달 전에 설정 화면에 입력한 뒤 잊은 값인 경우가 많습니다. ollama show는 저장된 모델을 읽습니다. HTTP를 통해 실제로 도착한 내용을 표시할 수는 없습니다.
서버 측 동작은 다음 한 가지 명령으로 확인할 수 있습니다. 긴 응답이 생성되도록 요청하고, 제한을 낮게 강제한 뒤 두 필드를 읽습니다.
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'상세한 응답은 32토큰을 훨씬 넘기므로 "length" 및 32가 출력될 것으로 예상할 수 있습니다. jq이 설치되어 있지 않다면 먼저 sudo apt install -y jq으로 설치합니다. 32가 항상 보장되는 것은 아닙니다. eval_count은 서버가 실제로 생성한 출력 토큰 수일 뿐이기 때문입니다. 모델이 일찍 응답을 끝내면 "stop"과 더 작은 개수가 출력됩니다. 이 경우에는 더 많은 내용을 요청하는 프롬프트를 사용해야 합니다. "length" 및 32이 출력된다면 요청에 지정한 값이 qwen3-capped에 저장된 512보다 우선 적용된 것입니다. 이는 서버가 요청별 옵션을 적용한다는 사실을 보여줍니다. 하지만 애플리케이션이 어떤 값을 전송하는지는 알려 주지 않습니다. 따라서 이제 클라이언트를 확인해야 합니다. 요청에 대한 서버 자체의 기록을 확인하려면 환경 변수에 OLLAMA_DEBUG=1를 지정하여 서버를 다시 시작하고, 애플리케이션이 서버와 통신하는 동안 journalctl -u ollama -f을 확인합니다.
음수 값과 복사하면 안 되는 숫자
num_predict은 음수 값도 허용하며, 음수 값은 개수가 아니라 sentinel로 처리됩니다. 한 음수 값은 “이 값을 제한으로 적용하지 말고 계속 생성”하라는 의미입니다. 다른 음수 값은 “남은 context를 채우기”라는 의미로 사용되어 왔습니다. 2026년 10월 기준 Ollama Modelfile reference에서는 기본값을 -1, 즉 무한 생성으로 설명하며, 같은 표의 이전 버전에서는 context를 채우는 값으로 -2도 제시했습니다.
이 내용은 변경되었으므로 버전에 따라 다르게 적용된다고 보아야 합니다. reference에서는 오랫동안 기본값을 128로 문서화했지만, 이후 해당 항목이 -1로 수정되었습니다. 따라서 여전히 이전 숫자를 반복하는 가이드가 많습니다. 동작도 변경되었습니다. 2026년 10월 25일 기준 최신 릴리스인 Ollama v0.40.11은 GGUF 모델을 유한한 budget이 필요한 upstream llama-server process로 전달합니다. 따라서 모든 음수 값과 num_ctx의 10배를 초과하는 모든 제한값을 num_ctx의 10배로 바꿉니다. 그러므로 위의 qwen3-capped 모델에서 “무한”은 81,920 tokens를 의미하며, -2는 더 이상 -1와 다르게 동작하지 않습니다. 실제로 실행하는 버전에 해당하는 Modelfile parameter reference를 읽은 다음, 위의 eval_count check로 동작을 확인하십시오. 자신의 시스템에서 확인한 값이 어디에서 읽은 값보다 우선하며, 이 글의 내용도 예외가 아닙니다.
CPU 전용 VPS에서 출력 길이가 주요 비용인 이유
Ollama는 직접 제어하는 머신에서 무료로 실행할 수 있으므로 로컬 생성은 사용량 제한이 없으며, 긴 답변에 대한 비용은 시간으로 지불됩니다. 생성 과정은 서로 다른 두 가지 속도로 진행되는 두 단계로 나뉩니다. 프롬프트 토큰은 한 번에 여러 개씩 배치 단위로 평가됩니다. 출력 토큰은 한 번에 하나씩 생성되며, 각 토큰은 모델 가중치를 한 번 통과해야 합니다. CPU 전용 VPS에서는 이 과정이 메모리 대역폭에 의해 제한되므로, 생성된 토큰 하나가 프롬프트 토큰 하나보다 훨씬 많은 비용을 발생시킵니다. 이 과정에서 토큰이 사용하는 모든 가중치를 읽어야 하기 때문에(밀집 모델은 전체 가중치를, Nemotron 3.5 Lightning과 같은 전문가 혼합 모델은 토큰당 약 3B의 매개변수만 활성화하는 라우팅된 전문가만 읽음), 각 가중치가 차지하는 바이트 수가 토큰 속도의 상한선을 결정합니다. 이것이 바로 q4 빌드가 q8이나 fp16 모델보다 빠르게 디코딩되는 이유입니다.
스트리밍 없이 응답을 요청하면 수치는 다음과 같이 나타납니다.
"prompt_eval_count": 11,
"prompt_eval_duration": 13074791,
"eval_count": 18,
"eval_duration": 52479709지속 시간은 나노초 단위입니다. 특정 서버의 측정값이 아닌 2026년 10월 기준 Ollama API 문서에 게시된 샘플 응답인 해당 블록에서는 11개의 프롬프트 토큰이 약 0.013초, 18개의 출력 토큰이 약 0.052초 소요되었습니다. 이는 프롬프트 토큰당 약 1.2밀리초, 출력 토큰당 약 2.9밀리초에 해당합니다. 따라서 한 줄짜리 답변에서도 생성된 각 토큰은 읽힌 토큰보다 두 배 이상의 비용이 들며, 긴 답변에서는 출력 단계가 전체 시간을 점유하게 됩니다. 사용자의 생성 속도는 eval_count을 eval_duration로 나누어 초 단위로 변환한 값이며, 자신의 하드웨어에서 초당 토큰 수를 측정하는 것은 다른 설정을 조정하기 전에 한 번 수행할 가치가 있습니다. 이 속도는 머신만큼이나 모델에 의존적이므로, 긴 답변이 실제 비용을 유발한다면 VPS에서 Nemotron 3.5 Lightning과 같이 빠른 디코딩을 위해 설계된 모델을 사용하는 것이 낮은 제한 설정으로 확보하는 시간을 일부 보충해 줍니다.
나머지는 산술 계산이 해결합니다. 초당 8개의 토큰 속도에서 2,000개의 토큰으로 구성된 답변은 머신을 4분 이상 점유하게 되며, 모델은 사용자가 단락 하나를 원했는지 알지 못합니다. 추론 모델은 사용자가 요청한 단어를 작성하기 전에 예산의 일부를 사고하는 데 사용하며, 이 사고 과정 또한 다른 모든 것과 마찬가지로 토큰 단위로 생성됩니다. 따라서 요청하는 추론 수준은 동일한 비용을 결정하는 또 다른 요인입니다. 일부 모델은 무언가 중단시킬 때까지 구문을 반복하는 루프에 빠지기도 합니다. 제한이 없으면 단일 요청이 num_ctx 토큰의 10배에 도달할 때까지 코어를 점유하게 되는데, 이는 컨텍스트 시프트로 인해 전체 윈도우가 종료되지 않기 때문입니다. num_predict는 이를 제한하는 설정이며, 하나의 긴 요청이 머신 전체를 점유할 수 있는 소규모 자체 호스팅 Ollama VPS에서 가장 중요합니다.
출력 잘림 현상은 보통 제한 설정 때문이며 모델 오류가 아닙니다
증상만 보면 모델이 실패한 것처럼 보입니다. 문장 중간에 멈추는 답변, 닫는 중괄호가 없어 파싱되지 않는 JSON 등이 그 예입니다. 본능적으로 모델이나 양자화 탓을 하기 쉽지만, 우선 응답 내용을 확인해야 합니다.
done_reason은 질문에 직접적으로 답변한 경우입니다. stop는 모델이 종료 토큰을 출력했거나 stop 옵션에 지정된 문자열 중 하나와 일치하여 제한 이전에 생성이 끝났음을 의미하며, 이 경우 일치하는 지점에서 답변이 종료됩니다. length는 공간이 부족하여 생성이 중단되었음을 의미합니다. length가 표시되면 eval_count 값을 제한 설정과 비교하십시오. 두 값이 정확히 일치하면 num_predict에 의해 중단된 것이며, 더 작은 숫자라면 컨텍스트 윈도우가 먼저 가득 찬 것입니다. 후자는 컨텍스트 시프트 기능이 꺼져 있을 때만 발생합니다.
스트리밍을 사용하면 해당 필드들은 "done": true을 포함하는 마지막 청크에 전달됩니다. 많은 클라이언트 라이브러리가 이 청크를 폐기하고 텍스트만 코드에 전달하기 때문에, 애플리케이션 내부에서는 잘림 현상이 설명되지 않는 것처럼 보이지만 curl로 확인하면 원인이 명확히 드러납니다. 라이브러리가 이를 숨기고 있다면 curl을 사용하여 요청을 보내 서버가 실제로 무엇을 응답했는지 확인하십시오.
오후 시간을 낭비하지 않기 위한 한 가지 팁이 더 있습니다. num_predict을 높인다고 해서 모델이 더 길게 작성하지는 않습니다. 이는 단지 상한선을 제거할 뿐입니다. stop 중 done_reason에서 답변이 끝난다면, 모델이 스스로 완료를 결정했거나 stop 문자열 중 하나가 일치한 것이므로 제한을 늘려도 아무런 변화가 없습니다. stop가 표시된 짧은 답변은 프롬프팅이나 정지 문자열 문제이며, length이 표시된 짧은 답변은 제한 설정 문제입니다.
값 선택하기
- 대화형 채팅의 경우, 제한을 두지 않고 응답이 길어지면 Ctrl+C를 눌러 중단하십시오. 어차피 화면을 지켜보고 있기 때문입니다.
- 스크립트로 실행하는 작업은 반드시 제한을 설정하십시오. 반복문 안에서 제한 없는 생성을 수행하면 10분이면 끝날 배치 작업이 다음 날 아침까지 실행되는 상황이 발생합니다.
- 구조화된 출력을 얻으려면 예상되는 가장 큰 유효 문서보다 높게 제한을 설정하십시오. 그런 다음
done_reason가length에 도달하면 이를 심각한 오류로 간주하고, 반환된 내용을 파싱하는 대신 재시도하십시오. - 코딩 에이전트의 경우, 에이전트가 모든 요청마다 자체 옵션을 전송하므로 해당 값은 에이전트의 설정에 포함되어야 합니다. 코딩 에이전트에서 Ollama 지정하기에서 해당 설정이 어디에 위치하는지 다룹니다.
이 제한은 단어나 문자가 아닌 토큰 수를 기준으로 하므로, 어림짐작하지 마십시오. 제한 없이 대표적인 답변을 하나 생성한 뒤 eval_count을 확인하고, 그보다 여유 있게 제한 값을 설정하십시오. 모델 제품군마다 토큰화 방식이 다르므로, Llama 모델에 적합한 값이 동일한 VPS에서 실행되는 Qwen 3 모델의 답변을 잘라버릴 수도 있습니다.
FAQ
num_ctx와 num_predict의 차이는 무엇입니까?
num_ctx는 컨텍스트 창의 크기입니다. 따라서 모델이 읽을 수 있는 양을 결정합니다. 여기에는 프롬프트와 지금까지 생성된 모든 내용이 포함됩니다. key/value cache가 함께 커지므로 메모리를 사용합니다. num_predict는 모델이 한 번의 응답에서 작성할 수 있는 토큰 수를 설정합니다. 메모리보다 시간이 더 필요하며, 사전에 메모리를 예약하지는 않습니다. 생성된 토큰은 두 값 모두에 반영됩니다. 따라서 context shift가 꺼져 있으면 두 값 중 하나 때문에 응답이 중간에 끝날 수 있습니다.
num_predict 설정이 무시되는 것처럼 보이는 이유는 무엇입니까?
요청으로 전달한 값이 모델에 저장된 값을 재정의하기 때문입니다. Modelfile에 PARAMETER num_predict 512을 넣은 다음 chat front end나 coding agent에서 해당 모델을 사용하면, 클라이언트가 자체 options 객체를 전송하고 그 안의 숫자가 적용됩니다. ollama show --parameters는 저장된 모델을 읽기 때문에 사용자가 설정한 값을 계속 출력합니다. HTTP로 실제 도착한 내용은 확인할 수 없습니다. curl을 사용해 "options": {"num_predict": 32}로 긴 응답이 필요한 프롬프트를 포함한 요청을 하나 보내고, done_reason와 eval_count을 확인합니다. eval_count가 32인 length가 표시되면 요청의 값이 저장된 값을 재정의했다는 뜻입니다. 서버 자체는 정상적으로 동작하므로 원인을 애플리케이션에서 찾아야 합니다. 더 작은 수가 포함된 stop은 모델이 먼저 생성을 끝냈다는 뜻일 뿐입니다. 더 많은 내용을 요청하는 프롬프트로 다시 시도합니다.
num_predict 때문에 출력이 중간에 끝났는지 어떻게 확인합니까?
"stream": false을 포함해 요청을 보내고 done_reason을 확인합니다. stop 값은 모델이 자체적으로 생성을 끝냈거나 stop 문자열 중 하나가 응답을 끝냈다는 뜻입니다. length 값은 생성 공간이 부족해졌다는 뜻입니다. 그런 다음 eval_count를 설정한 상한과 비교합니다. 두 값이 정확히 같으면 num_predict이 생성을 중단한 것입니다. eval_count가 더 작으면 컨텍스트 창이 먼저 가득 찬 것입니다. 스트리밍을 사용할 때는 두 필드가 "done": true와 함께 마지막 chunk로 전달됩니다. 많은 client library는 코드가 이 내용을 확인하기 전에 해당 chunk를 버립니다.
num_predict의 기본값은 무엇입니까?
문서에서 추측하지 말고 사용 중인 설치 환경에서 직접 확인합니다. 2026년 10월 기준 Ollama Modelfile reference는 기본값을 -1으로 설명합니다. 이는 생성에 상한이 없다는 뜻입니다. 해당 항목은 128을 오랫동안 기본값으로 문서화한 뒤 수정되었습니다. Ollama v0.40.11에서는 이 무제한 기본값이 다른 음수 값과 마찬가지로 실제로는 num_ctx의 10배에서 중단됩니다. 음수 값은 개수가 아니라 sentinel입니다. 이전 버전의 같은 표에는 남은 컨텍스트를 채우는 값으로 -2도 기재되어 있었습니다. 사용 중인 버전에 맞는 Modelfile parameter reference를 확인한 다음, ollama show --parameters과 curl 요청 하나로 실제 값을 확인합니다.
num_predict를 높이면 모델이 더 긴 답변을 작성합니까?
아닙니다. 상한만 제거합니다. 응답이 stop의 done_reason로 끝난다면 모델이 생성을 완료했거나 stop 문자열 중 하나가 일치한 것입니다. 이 경우 상한을 높여도 달라지지 않습니다. 이때 길이는 프롬프트의 문제입니다. 원하는 구조, 섹션 수 또는 구체적인 상세 수준을 지정해 요청합니다. done_reason이 length로 반환될 때만 num_predict를 높입니다.