가이드

작성자 Matt Connor 2026-08-15 · 업데이트됨 2026-08-16

Ollama num_predict 설정 및 토큰 제한 방법

Q: Ollama에서 num_ctx와 num_predict의 차이점은 무엇입니까?

num_ctx은 컨텍스트 윈도우의 크기이며, 모델이 읽을 수 있는 양(프롬프트와 지금까지 생성된 모든 내용의 합)을 결정합니다. 키/값 캐시가 이 크기에 비례하여 커지므로 메모리 사용량에 영향을 줍니다. num_predict은 모델이 한 번의 응답으로 작성할 수 있는 토큰의 개수를 설정합니다. 이는 메모리가 아닌 시간을 소모하며, 미리 예약되는 자원은 없습니다. 생성된 토큰은 두 설정 모두에 영향을 미치므로, 어느 한쪽이라도 제한에 도달하면 응답이 중단될 수 있습니다.

Q: 왜 num_predict 설정이 무시되는 것처럼 보입니까?

요청과 함께 전송된 값이 모델에 저장된 값을 덮어쓰기 때문입니다. Modelfile에 PARAMETER num_predict 512를 설정하더라도, 채팅 프론트엔드나 코딩 에이전트에서 해당 모델을 호출하면 클라이언트가 자체적인 options 객체를 전송하여 우선권을 갖게 됩니다. ollama show --parameters은 저장된 모델을 읽을 뿐 HTTP를 통해 전달되는 값을 알 수 없으므로 여전히 사용자가 설정한 값을 출력합니다. "options": {"num_predict": 32}을 사용하여 curl로 요청을 하나 보내고, 응답으로 eval_count가 32로 돌아오는지 확인하십시오. 이를 통해 서버가 정상적으로 동작하고 있음을 확인하고, 애플리케이션 측에서 원인을 찾아야 합니다.

Q: 출력 결과가 num_predict 때문에 잘렸는지 어떻게 알 수 있습니까?

"stream": false를 포함하여 요청을 보내고 done_reason을 확인하십시오. 값이 stop이면 모델이 스스로 생성을 마친 것입니다. 값이 length이면 공간이 부족하여 중단된 것입니다. 그 후 eval_count와 설정한 제한 값을 비교하십시오. 두 값이 정확히 일치하면 num_predict에 의해 중단된 것이며, eval_count이 더 작다면 컨텍스트 윈도우가 먼저 가득 찬 것입니다. 스트리밍 시에는 두 필드가 "done": true와 함께 마지막 청크에 포함되어 전달되지만, 많은 클라이언트 라이브러리가 이를 코드에 전달하기 전에 삭제합니다.

Q: num_predict를 높이면 모델이 더 긴 답변을 작성합니까?

아닙니다. 이는 단지 상한선을 제거할 뿐입니다. 응답이 stop 중 done_reason에서 끝난다면 모델이 스스로 생성을 마친 것이므로, 제한 값을 높여도 결과는 달라지지 않습니다. 이 경우 답변의 길이는 프롬프트의 문제입니다. 특정 구조, 섹션 개수, 또는 상세 수준을 명시적으로 요구하십시오. done_reason이 length로 돌아올 때만 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는 모델이 읽을 수 있는 양입니다. 이는 프롬프트와 지금까지 생성된 모든 내용을 포함하는 컨텍스트 윈도우의 크기입니다. 이 값을 높이면 모델이 토큰에 대해 유지하는 키/값 캐시가 윈도우 크기에 비례하여 커지므로 메모리 사용량이 증가합니다. 하드웨어에 맞는 num_ctx 설정하기는 별도의 작업이며 고유한 실패 유형을 가집니다.

num_predict은 모델이 쓸 수 있는 양입니다. 이는 할당값이 아니라 정지 규칙입니다. 이 값을 높이면 RAM이 아닌 실제 소요 시간이 증가하며, 사전에 예약되는 자원은 없습니다.

이 두 설정은 한 지점에서 만납니다. 생성된 토큰은 생성되는 즉시 컨텍스트 윈도우 내부로 들어갑니다. 따라서 설정한 제한값에 도달하지 않았더라도 윈도우가 가득 차면 응답이 중단될 수 있습니다. 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-capped

ollama show --parameters은 저장된 매개변수와 그 값을 줄마다 출력합니다. 출력 결과에 num_predict가 없다면 해당 모델에는 고정된 제한값이 없으며 Ollama의 기본값이 적용됩니다. ollama show --modelfile qwen3-capped는 전체 정의를 출력하며, 기존 모델에 포함된 매개변수를 복사하는 가장 빠른 방법이기도 합니다.

이 방법은 모든 호출자가 상속받기를 원하는 값에 적합한 계층입니다. 하지만 값을 최종적으로 고정하려는 의도라면 이 계층은 적절하지 않습니다. 변경이 가능하기 때문입니다.

옵션 객체 내에서 요청별로 설정하기

모든 생성 엔드포인트는 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'

이 명령은 "length"과 32를 출력해야 합니다. jq가 없다면 sudo apt install -y jq으로 먼저 설치하십시오. "length"과 32이라는 응답이 나온다면 서버는 옵션을 정상적으로 따르고 있으며, 귀하의 애플리케이션이 다른 값을 보내고 있다는 뜻입니다. 서버가 수신하는 요청을 직접 확인하려면 환경 변수에 OLLAMA_DEBUG=1를 설정하여 서버를 재시작한 뒤, 애플리케이션이 통신하는 동안 journalctl -u ollama -f을 모니터링하십시오.

음수 값과 복사해서는 안 되는 숫자

num_predict은(는) 음수 값도 허용하며, 이는 개수가 아니라 특수한 의미를 지닌 표식(sentinel)입니다. 한 음수 값은 "제한을 두지 말고 계속 생성하라"는 의미입니다. 다른 값은 "남은 컨텍스트를 채우라"는 의미로 사용되었습니다. 2026년 8월 기준으로 Ollama Modelfile 참조 문서는 기본값을 -1(무제한 생성)로 명시하고 있으며, 동일한 표의 이전 버전에서는 컨텍스트를 채우는 용도로 -2을(를) 나열하기도 했습니다.

이 모든 내용은 버전마다 달라질 수 있으므로 주의해야 합니다. 참조 문서에서는 2024년 말에 항목이 수정되기 전까지 오랫동안 기본값을 128로 기록했기 때문에, 많은 가이드가 여전히 이 옛날 숫자를 반복하고 있습니다. 현재 실행 중인 버전에 맞는 Modelfile 매개변수 참조 문서를 읽고, 위에서 설명한 eval_count 확인 절차를 통해 동작을 검증하십시오. 본인의 서버에서 직접 검증한 값이 이 게시물을 포함한 그 어떤 곳에서 읽은 값보다 정확합니다.

CPU 전용 VPS에서 출력 길이가 주요 비용인 이유

생성 과정은 속도가 크게 다른 두 단계로 나뉩니다. 프롬프트 토큰은 한 번에 여러 개씩 배치 단위로 평가됩니다. 반면 출력 토큰은 한 번에 하나씩 생성되며, 각 토큰마다 모델 가중치 전체를 통과하는 과정이 필요합니다. CPU 전용 VPS에서는 이 과정이 메모리 대역폭에 의해 제한되므로, 생성된 토큰 하나가 프롬프트 토큰 하나보다 훨씬 더 많은 비용을 소모합니다.

스트리밍 없이 응답을 요청하면 수치를 바로 확인할 수 있습니다.

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

지속 시간은 나노초 단위입니다. 해당 블록은 특정 서버의 측정값이 아니라 Ollama API 문서에 게시된 샘플 응답이며, 26개의 프롬프트 토큰을 처리하는 데 약 0.1초가 걸린 반면 237개의 출력 토큰을 생성하는 데는 약 4.3초가 소요되었습니다. 사용자의 실제 생성 속도는 eval_count을 eval_duration로 나눈 뒤 초 단위로 변환한 값이며, 다른 설정을 조정하기 전에 사용자의 하드웨어에서 초당 토큰 수 측정하기를 한 번 수행해 보는 것이 좋습니다. 해당 속도는 기기만큼이나 모델에 따라서도 달라지므로, 긴 답변이 실제 비용 문제라면 VPS에서 Nemotron 3.5 Lightning 사용하기와 같이 빠른 디코딩을 위해 설계된 모델을 사용하여 낮은 제한 설정으로 인해 잃어버린 시간을 일부 만회할 수 있습니다.

나머지는 산술 계산으로 결정됩니다. 초당 8개의 토큰을 생성할 경우, 2,000개의 토큰으로 구성된 답변은 4분 이상 기기를 점유하게 되며, 모델은 사용자가 단락 하나를 원했는지 알지 못합니다. 일부 모델은 루프에 빠져 무언가 중단시킬 때까지 문구를 반복하기도 합니다. 제한이 없으면 단일 요청 하나가 컨텍스트 윈도우가 소진될 때까지 코어를 계속 점유합니다. 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와 함께 짧은 답변이 나오는 것은 프롬프트 문제입니다. length과 함께 짧은 답변이 나오는 것은 제한 설정 문제입니다.

값 선택하기

대화형 채팅의 경우, 제한을 두지 않고 응답이 길어지면 Ctrl+C를 눌러 중단하십시오. 어차피 화면을 지켜보고 있기 때문입니다.
스크립트로 실행하는 작업은 반드시 제한을 설정하십시오. 루프 안에서 생성 제한이 없으면 10분이면 끝날 배치 작업이 다음 날 아침까지 실행될 수 있습니다.
구조화된 출력을 얻으려면 예상되는 가장 큰 유효 문서보다 높게 제한을 설정하십시오. 그런 다음 done_reason of length가 발생하면 이를 심각한 오류로 간주하고, 반환된 내용을 파싱하는 대신 재시도하십시오.
코딩 에이전트의 경우, 에이전트가 모든 요청마다 자체 옵션을 전송하므로 해당 값은 에이전트의 설정 파일에 두어야 합니다. 코딩 에이전트를 Ollama에 연결하기에서 해당 설정이 어디에 있는지 다룹니다.

제한은 단어나 문자가 아닌 토큰 수를 기준으로 하므로 어림짐작하지 마십시오. 제한 없이 대표적인 답변을 하나 생성한 뒤 eval_count을 확인하고, 그보다 여유 있게 제한을 설정하십시오. 모델 제품군마다 토큰화 방식이 다르므로, Llama 모델에 적합한 값이 동일한 VPS의 Qwen 3 모델에서는 답변을 잘라버릴 수 있습니다.

FAQ

Ollama에서 num_ctx와 num_predict의 차이점은 무엇입니까?

num_ctx은 컨텍스트 윈도우의 크기이며, 모델이 읽을 수 있는 양(프롬프트와 지금까지 생성된 모든 내용의 합)을 결정합니다. 키/값 캐시가 이 크기에 비례하여 커지므로 메모리 사용량에 영향을 줍니다. num_predict은 모델이 한 번의 응답으로 작성할 수 있는 토큰의 개수를 설정합니다. 이는 메모리가 아닌 시간을 소모하며, 미리 예약되는 자원은 없습니다. 생성된 토큰은 두 설정 모두에 영향을 미치므로, 어느 한쪽이라도 제한에 도달하면 응답이 중단될 수 있습니다.

왜 num_predict 설정이 무시되는 것처럼 보입니까?

요청과 함께 전송된 값이 모델에 저장된 값을 덮어쓰기 때문입니다. Modelfile에 PARAMETER num_predict 512를 설정하더라도, 채팅 프론트엔드나 코딩 에이전트에서 해당 모델을 호출하면 클라이언트가 자체적인 options 객체를 전송하여 우선권을 갖게 됩니다. ollama show --parameters은 저장된 모델을 읽을 뿐 HTTP를 통해 전달되는 값을 알 수 없으므로 여전히 사용자가 설정한 값을 출력합니다. "options": {"num_predict": 32}을 사용하여 curl로 요청을 하나 보내고, 응답으로 eval_count가 32로 돌아오는지 확인하십시오. 이를 통해 서버가 정상적으로 동작하고 있음을 확인하고, 애플리케이션 측에서 원인을 찾아야 합니다.

출력 결과가 num_predict 때문에 잘렸는지 어떻게 알 수 있습니까?

"stream": false를 포함하여 요청을 보내고 done_reason을 확인하십시오. 값이 stop이면 모델이 스스로 생성을 마친 것입니다. 값이 length이면 공간이 부족하여 중단된 것입니다. 그 후 eval_count와 설정한 제한 값을 비교하십시오. 두 값이 정확히 일치하면 num_predict에 의해 중단된 것이며, eval_count이 더 작다면 컨텍스트 윈도우가 먼저 가득 찬 것입니다. 스트리밍 시에는 두 필드가 "done": true와 함께 마지막 청크에 포함되어 전달되지만, 많은 클라이언트 라이브러리가 이를 코드에 전달하기 전에 삭제합니다.

num_predict의 기본값은 무엇입니까?

외부 문서보다는 설치된 환경에서 직접 확인하십시오. 2026년 8월 기준 Ollama Modelfile 참조 문서에 따르면 기본값은 -1이며, 이는 생성 제한이 없음을 의미합니다. 이 항목은 수년간 128로 기재되어 오다가 2024년 말에 수정되었습니다. 음수 값은 개수가 아닌 특정 상태를 나타내는 지표이며, 과거 버전의 동일한 표에는 남은 컨텍스트를 채우는 용도로 -2가 기재되기도 했습니다. 사용 중인 버전에 맞는 Modelfile 매개변수 참조를 확인한 뒤, ollama show --parameters과 curl 요청을 통해 직접 검증하십시오.

num_predict를 높이면 모델이 더 긴 답변을 작성합니까?

아닙니다. 이는 단지 상한선을 제거할 뿐입니다. 응답이 stop 중 done_reason에서 끝난다면 모델이 스스로 생성을 마친 것이므로, 제한 값을 높여도 결과는 달라지지 않습니다. 이 경우 답변의 길이는 프롬프트의 문제입니다. 특정 구조, 섹션 개수, 또는 상세 수준을 명시적으로 요구하십시오. done_reason이 length로 돌아올 때만 num_predict을 높이십시오.

#ollama #local-llm#parameters#tokens #self-hosting