BroadRouter

추론 모델의 max_tokens 설정: 토큰 예산을 정하는 방법

BroadNet Inference 팀 · 6분 분량 · 게시

추론 모델에서 max_tokens는 생각과 답변을 함께 제한하므로, 한도가 빠듯하면 보이는 텍스트가 나오기 전에 응답이 끝날 수 있습니다. 작업 유형별로 전체 completion 토큰을 측정하고, max_tokens를 95번째 백분위수에 20%를 더한 값으로 정하고, 프롬프트와 max_tokens의 합을 컨텍스트 윈도우 안에 두고, 잘린 응답은 하드 상한까지 예산을 두 배로 늘려 재시도하세요.

추론 모델은 답하기 전에 생각하며, 대부분의 OpenAI 호환 API에서는 둘 다 하나의 예산, 즉 max_tokens에서 나옵니다. 비추론 모델처럼 짧은 답변에 수백 토큰 정도로 설정하면 일부 응답이 finish_reason: "length"와 함께 비어서 돌아옵니다. 빠른 해결 방법은 추론 모델이 빈 답변을 반환하는 이유에 있습니다. 이 글은 믿을 수 있는 예산을 정하는 방법을 다룹니다. 측정하고, 백분위수로 크기를 정하고, 컨텍스트 윈도우를 지키고, 그래도 잘리는 응답을 처리하는 것입니다.

추론에 드는 비용과 줄이는 방법은 추론 토큰: 보이는 것보다 많은 출력 요금을 내는 이유를 참고하세요.

왜 답변 전에 예산이 바닥나나요?

모델은 순서대로 생성합니다. 먼저 추론을, 그다음 보이는 답변을 씁니다. 둘의 모든 토큰이 max_tokens에 포함됩니다. BroadNet 문서는 DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B에 대해 “the reasoning counts toward max_tokens”(번역: 추론은 max_tokens에 포함됩니다)라고 하고, 한도가 작으면 “the answer comes back empty”(번역: 답변이 비어서 돌아옵니다)라고 설명합니다. OpenAI Chat Completions 레퍼런스도 max_completion_tokens를 같은 방식으로, “including visible output tokens and reasoning tokens”(번역: 보이는 출력 토큰과 추론 토큰을 포함하는) 상한으로 정의합니다.

따라서 물어야 할 질문은 “답변이 얼마나 긴가?”가 아닙니다. “이 작업에서, 이 effort로, 추론과 답변을 합치면 얼마나 긴가?”입니다. 이 값은 생각보다 크게 달라집니다. OpenAI 가이드는 문제에 따라 모델이 “anywhere from a few hundred to tens of thousands of reasoning tokens”(번역: 수백 개에서 수만 개에 이르는 추론 토큰)를 생성할 수 있다고 말합니다.

max_tokens를 크게 잡으면 비용이 더 드나요?

아닙니다. 이 오해가 예산을 너무 빠듯하게 잡는 가장 흔한 이유입니다. max_tokens는 상한입니다. 과금은 실제로 생성된 토큰에 대해 이루어집니다. 1,800토큰이 필요한 응답은 상한이 4,000이든 40,000이든 비용이 같습니다.

빠듯한 상한이 실제로 만드는 비용은 다음과 같습니다.

상한과 필요량 지불하는 것 얻는 것
상한이 필요량보다 큼 생성된 토큰 답변
상한이 필요량보다 작음 상한 전체, 모두 추론 쓸 수 없는 결과와 재시도

예를 들어 보겠습니다. 호출의 4분의 1이 1,000토큰 넘게 필요하다고 가정합시다. max_tokens=1000이면 그런 호출은 각각 생각에 쓴 출력 1,000토큰을 과금하고, 아무것도 돌려주지 않고, 재시도됩니다. 재시도 자체를 빼고도 전체 호출 평균으로 호출당 250토큰의 출력이 낭비되며, 두 번째 요청의 지연 시간도 더해집니다. 상한이 4,000이면 낭비가 없습니다. Qwen3.8 27B의 출력은 100만 토큰당 $2.17 요금이므로, 사용량이 많으면 낭비가 쌓입니다.

높은 상한의 실제 위험은 폭주하는 응답입니다. 루프에 빠지거나 지나치게 생각해 필요보다 훨씬 많이 생성하는 모델입니다. 하드 상한이 이를 막습니다. 상한은 아래처럼 데이터로 정하세요.

작업에 필요한 양은 어떻게 측정하나요?

한 작업 유형의 실제 프롬프트를 넉넉한 상한으로 실행하고, completion 토큰과 추론 비중을 기록하세요. 모델이 보고하는 경우 usage.completion_tokens_details.reasoning_tokens가 추론 부분을 알려 주며, BroadNet 문서에 이 필드가 나와 있습니다.

import os
from openai import OpenAI

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])
MODEL = "broadnet/qwen3.8-27b"

def measure(prompts, ceiling=16_000, **kw):
    """Run real prompts with a generous ceiling and return per-call token counts."""
    rows = []
    for p in prompts:
        r = client.chat.completions.create(model=MODEL, max_tokens=ceiling,
                                           messages=[{"role": "user", "content": p}], **kw)
        u, d = r.usage, r.usage.completion_tokens_details
        reasoning = (d.reasoning_tokens or 0) if d else 0
        rows.append({"reasoning": reasoning, "answer": u.completion_tokens - reasoning,
                     "finish": r.choices[0].finish_reason})
    return rows

def pct(values, q):
    values = sorted(values)
    return values[min(len(values) - 1, int(q * len(values)))]

def recommend(rows, margin=1.2):
    total = [r["reasoning"] + r["answer"] for r in rows]
    return {"p50": pct(total, 0.5), "p95": pct(total, 0.95), "max": max(total),
            "max_tokens": int(pct(total, 0.95) * margin),
            "cut_off": sum(r["finish"] == "length" for r in rows)}

# print(recommend(measure(my_prompts)))                       # default effort
# print(recommend(measure(my_prompts, reasoning_effort="low")))

믿을 수 있는 숫자를 얻기 위한 규칙입니다.

  1. 실행 한 번에 작업 유형 하나. 분류, 추출, 코드 리뷰, 계획 수립은 분포가 매우 다릅니다. 전역 max_tokens 하나로는 재시도에 돈을 낭비하거나 폭주하는 응답을 통과시키게 됩니다.
  2. 실제 프롬프트 50개 이상. 샘플 10개의 95번째 백분위수는 그냥 가장 큰 값입니다.
  3. 사용하는 effort마다 실행하세요. reasoning_effort="low"는 분포를 바꿉니다. BroadNet은 low를 문서화하고 있으니, 다른 값은 의존하기 전에 테스트하세요.
  4. cut_off가 0이 아니면 상한을 올려 다시 실행하세요. 잘린 샘플은 실제 길이를 숨깁니다.
  5. 모델이나 프롬프트가 바뀌면 다시 실행하세요. 새 모델 버전은 더 많이 또는 더 적게 생각할 수 있습니다.

그런 다음 recommend() 결과로 작업별 max_tokens를 정하세요. 95번째 백분위수에 20%를 더하면 대부분의 호출은 상한보다 한참 아래에 머물고, 드물게 긴 호출만 아래의 재시도 경로로 갑니다. 무료 추론 토큰 예산 도구는 숫자만 있으면 이 계산을 브라우저에서 해 줍니다.

컨텍스트 윈도우는 예산을 어떻게 제한하나요?

컨텍스트 윈도우에는 프롬프트와 답변이 함께 들어갑니다. BroadNet 가격 피드는 context_length를 “the most tokens one request can hold, prompt and answer together”(번역: 요청 하나가 담을 수 있는 최대 토큰 수, 프롬프트와 답변 합계)로 정의합니다. 따라서 다음과 같습니다.

max_tokens ≤ 컨텍스트 길이 − 프롬프트 토큰

모델 컨텍스트 200,000토큰 프롬프트일 때 max_tokens 여유
GLM 5.3 1,048,576 848,576
DeepSeek V4.1 Flash 1,048,576 848,576
Qwen3.8 27B 262,144 62,144

긴 컨텍스트 작업에서 중요한 부분입니다. Qwen3.8 27B에서 기록이 250,000토큰까지 늘어난 에이전트는 생각과 답변에 쓸 여유가 약 12,000토큰뿐입니다. 긴 컨텍스트 작업은 추론도 더 많이 필요한 경향이 있으므로, 시작할 때 한 번이 아니라 호출할 때마다 남은 여유를 확인하세요. 컨텍스트 윈도우와 컨텍스트 윈도우 계산기에서 들어가는지 확인할 수 있습니다.

그래도 응답이 잘리면 어떻게 해야 하나요?

모든 호출에서 finish_reason을 확인하세요. length라면 content에 텍스트가 일부 있더라도 답변이 없거나 불완전합니다. 완전한 것처럼 파싱하지 마세요. 잘린 JSON 객체는 후속 오류의 흔한 원인입니다(구조화된 출력).

컨텍스트가 허용하는 여유 안에서, 하드 상한까지 예산을 두 배로 늘려 재시도하세요.

import json, urllib.request

FEED = json.load(urllib.request.urlopen("https://inference.broadnet.ai/pricing.json"))
CONTEXT = {m["id"]: m.get("context_length") for m in FEED["models"]}

def ask(model, messages, budget=4_000, hard_cap=32_000, **kw):
    """Retry a cut-off reply with a doubled budget, never past the cap or the context window."""
    while True:
        r = client.chat.completions.create(model=model, messages=messages,
                                           max_tokens=budget, **kw)
        if r.choices[0].finish_reason != "length":
            return r
        room = CONTEXT[model] - r.usage.prompt_tokens        # context holds prompt + answer
        nxt = min(budget * 2, hard_cap, room)
        if nxt <= budget:
            raise RuntimeError(f"still cut off at max_tokens={budget}")
        print(f"cut off at {budget}, retrying with {nxt}")
        budget = nxt

작업에 따라 두 배로 늘리는 대신 쓸 수 있는 방법이 두 가지 있습니다.

  • 같은 예산으로 reasoning_effort="low"로 재시도하세요. 단순한 작업에서는 모델이 지나치게 생각하는 경우가 많으며, effort를 낮추면 상한을 키우지 않고도 해결됩니다.
  • 작업을 나누세요. 응답이 높은 상한에 계속 걸린다면 대개 요청이 한 번에 너무 많은 것을 요구하는 것입니다.

잘림은 작업 유형과 함께 모두 로그로 남기세요. 비율이 오른다면 프롬프트, 모델, 입력 데이터 중 무언가가 바뀐 것이며 예산을 다시 측정해야 합니다. 재시도는 새로운 추론이므로 다시 과금됩니다. 장시간 실행 에이전트: 타임아웃과 재시도처럼 시도 횟수를 제한하세요.

스트리밍을 쓰면 무엇이 달라지나요?

stream=True에서는 추론이 첫 번째 보이는 토큰보다 먼저 일어나므로, 추론 모델이 처음에 멈춘 것처럼 보일 수 있습니다. 채팅 UI에서는 콘텐츠가 도착할 때까지 ‘생각 중’ 상태를 보여 주고, 클라이언트 타임아웃은 답변만이 아니라 생각하는 시간까지 고려해 정하세요.

일부 서버는 추론 텍스트 자체를 별도 필드로 스트리밍하기도 합니다. 필드 이름은 표준이 아닙니다. DeepSeek 자체 API는 reasoning_content를 쓰고, vLLM은 필드 이름을 reasoning_content에서 reasoning으로 바꾸면서 기존 클라이언트 코드가 “could silently read an empty”(번역: 아무 경고 없이 빈) 필드를 읽을 수 있다고 경고했습니다. BroadNet 문서에는 추론 텍스트 필드가 나와 있지 않으므로, 사용하는 모델의 원시 응답을 확인하기 전에는 그런 필드에 기능을 의존하지 마세요. 읽는다면 방어적으로 읽으세요.

for chunk in stream:
    if chunk.choices:
        delta = chunk.choices[0].delta
        thinking = getattr(delta, "reasoning", None) or getattr(delta, "reasoning_content", None)
        # log or display `thinking` only if your provider actually sends it
        if delta.content:
            print(delta.content, end="")
    elif chunk.usage:                                  # last chunk, with include_usage
        print("\nreasoning tokens:", getattr(chunk.usage.completion_tokens_details, "reasoning_tokens", None))

마지막 청크의 usage를 받으려면 stream_options={"include_usage": True}가 필요하며, BroadNet은 이를 문서화하고 있습니다. 스트림에 대한 자세한 내용은 스트리밍 가이드와 SSE 설명을 참고하세요.

어떤 파라미터 이름을 보내야 하나요?

API 파라미터 추론 포함 여부
OpenAI Chat Completions max_completion_tokens(max_tokens는 지원 중단) 예
OpenAI Responses max_output_tokens 예
BroadNet Inference(Chat Completions) 문서에 나온 대로 max_tokens 예
vLLM 서버 max_tokens, 선택적으로 thinking_token_budget 예

제공업체 간에 코드를 옮길 때는 해당 업체가 문서화한 이름을 보내고, 테스트 호출 한 번으로 한도가 적용되는지 확인하세요. 조용히 무시된 한도는 폭주하는 응답이 오기 전까지 아무 문제 없어 보입니다. 바뀌는 다른 파라미터는 마이그레이션 체크리스트에서 다룹니다.

BroadNet Inference가 맞는 경우

BroadNet의 추론 모델 세 개는 모델이 제공하는 경우 usage에 추론 토큰을 보고하므로, 위의 측정 방법이 그대로 동작합니다. DeepSeek V4.1 Flash와 GLM 5.3은 컨텍스트가 1,048,576토큰으로 여유가 가장 큽니다. Qwen3.8 27B는 262,144토큰입니다. 작업에 추론이 필요 없다면 Gemma 4 VL 26B는 추론 모델로 표시되어 있지 않아 예산 문제를 아예 피할 수 있습니다. 정액 DeepSeek V4.1 Flash 플랜에서는 생각 토큰에 토큰당 요금이 붙지 않지만, 잘린 응답은 여전히 시간을 잡아먹으므로 같은 예산 관리가 필요합니다. BroadNet은 별도의 추론 상한을 문서화하지 않습니다. 필요하다면 이를 제공하는 제공업체나 자체 호스팅 서버를 쓰세요.

자주 묻는 질문

추론 모델이 빈 응답을 반환하는 이유는 무엇인가요?

모델이 답변을 쓰기 전에 숨겨진 추론에 max_tokens 예산을 모두 썼기 때문입니다. 이때 finish_reason은 "length"입니다. max_tokens를 높이거나 reasoning_effort를 낮추거나, 둘 다 하세요. 빠른 해결 방법을 담은 짧은 가이드가 이 글에 링크되어 있습니다.

추론 모델의 max_tokens는 얼마로 설정해야 하나요?

먼저 측정하세요. 넉넉한 상한으로 실제 프롬프트를 50개 이상 실행하고, 해당 작업의 completion_tokens 95번째 백분위수를 구한 뒤 약 20%를 더하세요. BroadNet 문서는 최소 1,000토큰 이상을 권하며, OpenAI는 자사 모델을 처음 쓸 때 25,000토큰을 확보하라고 제안합니다.

max_tokens를 높이면 비용이 더 드나요?

그 자체로는 아닙니다. 과금은 상한이 아니라 모델이 생성한 토큰에 대해 이루어집니다. 상한을 높여서 비용이 늘어나는 것은 원래라면 잘렸을 응답뿐이며, 그 경우에도 잘린 응답은 어차피 재시도 비용을 만들었을 것입니다.

max_completion_tokens와 max_tokens는 같은 것인가요?

OpenAI에서는 max_completion_tokens가 지원 중단된 max_tokens를 대체하며, 추론 토큰을 포함한다고 명시합니다. 많은 OpenAI 호환 제공업체는 대신 max_tokens를 문서화합니다. BroadNet 문서는 max_tokens를 쓰며, 추론이 여기에 포함된다고 설명합니다.

추론을 답변과 따로 제한할 수 있나요?

서버가 지원하는 경우에만 가능합니다. vLLM에는 thinking_token_budget 파라미터가 있고, 일부 제공업체는 자체 파라미터를 둡니다. BroadNet은 별도의 추론 상한이 아니라 reasoning_effort를 low로 설정하는 방법을 문서화하므로, 둘을 합쳐 예산을 잡으세요.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기