GLM-5.3 실전 가이드: 항상 켜져 있는 사고 기능, 세 가지 노력 수준, API 지원 매트릭스

제목: GLM-5.3 실전 가이드: 항상 켜져 있는 사고 기능, 세 가지 노력 수준 및 API 지원 매트릭스

설명: 2026년 8월 GLM-5.3 가이드: 세 가지 reasoning_effort 수준의 항상 켜진 사고 기능, 추론 요약, 병렬 도구 호출, 구조화된 출력, 자동 캐싱, 그리고 검증된 AIHubMix Chat / Responses / Messages 예제.

이 글은 GLM-5.3의 주요 API 변경 사항과 사용 시 유의점을 다룹니다. GLM-5.3은 2026-08-14에 출시된 Z.ai의 플래그십 모델로, GLM-5.2와 정확히 동일한 기본 모델을 사용하며 모든 성능 향상은 사후 학습(post-training)에서 비롯됩니다. AIHubMix에서 모델 ID는 coding-glm-5.3이며(현재 기간 한정 프리뷰 경로), Chat Completions, Responses, Claude 호환 Messages API에서 사용할 수 있습니다. 참고: Z.ai 공식 출시 블로그.

각 섹션의 "검증됨" 결론과 샘플 응답은 2026-08-14에 AIHubMix API(Chat Completions / Responses / Messages)를 실제 호출하여 얻은 결과입니다.

1. 모델 사양 한눈에 보기

검증됨: max_tokens: 999999 요청 시 400이 반환되며 오류 본문에 유효 범위가 명시됨 — 상한이 실제로 검증되었으며 조용히 잘리는 것이 아님.

# max_tokens=999999 -> HTTP 400
"max_tokens parameter invalid: value must be within [1,131072]"

2. GLM-5.3 vs GLM-5.2: 항상 켜진 사고 기능, reasoning_effort를 통한 강도 조절

GLM-5.2 대비 GLM-5.3에서 가장 중요한 API 변경 사항은 다음 두 가지입니다:

1. thinking.type이 더 이상 disabled를 지원하지 않음 — 사고 기능을 끌 수 없습니다. 공식 마이그레이션 권장 사항은, 기존에 {"type": "disabled"}를 보내던 애플리케이션을 {"type": "enabled"}로 바꾸고 reasoning_effort를 "low"로 설정하는 것입니다.
2. reasoning_effort가 세 가지 수준으로 좁혀짐: low (가벼움) / high (강화) / max (깊음, 기본값). GLM-5.2 시기의 7개 값 호환성 매핑은 더 이상 적용되지 않으며, Z.ai는 코딩 작업에 max를 권장합니다.

검증됨: AIHubMix를 통해 thinking: {"type": "disabled"}를 보내면 200이 반환되고 사고는 여전히 수행됨(reasoning_content도 평소처럼 반환됨) — 이 값은 거부되지 않고, 공식 채널 의미에 따라 자동 변환됩니다. 클라이언트가 "토큰 절약을 위해 사고를 끄는" 방식에 의존했다면 reasoning_effort: "low"로 바꾸십시오.

검증됨: reasoning_effort에 열거형 범위를 벗어난 값을 보내도 오류 없이 200이 반환됨(공식 문서에 따라 기본값 max으로 대체). low와 max를 같은 산술 문제에 적용했을 때 예상대로 사고량이 줄어드는 경향이 나타남(추론 토큰 27개 vs 39개).

Chat Completions

사고 내용은 reasoning_content 필드로 반환되며, 스트리밍에서는 delta.reasoning_content로 전달됩니다.

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

completion = client.chat.completions.create(
    model="coding-glm-5.3",
    reasoning_effort="max",          # low / high / max, default max
    extra_body={"thinking": {"type": "enabled"}},
    messages=[
        {"role": "user", "content": "Compute the square root of (17*23-19*11), rounded down. Digits only."}
    ],
)

print(completion.choices[0].message.reasoning_content)
print(completion.choices[0].message.content)   # Observed: "13"

검증됨: usage.completion_tokens_details.reasoning_tokens가 사고 사용량을 보고함 — 같은 질문에 대해 reasoning_effort="low"일 때 27, "max"일 때 39.

Responses

사고 내용은 reasoning 출력 항목으로 반환되며, 텍스트는 summary 배열 안의 summary_text에 담깁니다.

from openai import OpenAI

client = OpenAI(
    base_url="https://aihubmix.com/v1",
    api_key="<AIHUBMIX_API_KEY>",
)

response = client.responses.create(
    model="coding-glm-5.3",
    input="What is the capital of France? City name only.",
)

# Observed response.output item types: ["reasoning", "message"]
# reasoning item: {"type": "reasoning", "summary": [{"type": "summary_text", "text": "The user is asking..."}]}
# usage.output_tokens_details.reasoning_tokens: 80

검증됨: 기본 요청(reasoning 파라미터를 전혀 보내지 않은 경우)에도 summary_text를 포함한 reasoning 항목이 이미 포함됨 — 별도의 명시적 옵트인이 필요 없음.

Messages

사고 내용은 기본 thinking 콘텐츠 블록으로 반환됩니다.

from anthropic import Anthropic

client = Anthropic(
    api_key="<AIHUBMIX_API_KEY>",
    base_url="https://aihubmix.com"
)

response = client.messages.create(
    model="coding-glm-5.3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "What is the capital of France? City name only."}
    ],
)

# Observed response.content block types: ["thinking", "text"]

검증됨: thinking 블록은 기본적으로 반환됨; 이 API에서도 thinking: {"type": "disabled"}를 보내면 200이 반환되고 사고는 여전히 수행됨(공식의 "disabled는 low로 변환되며 요청은 계속 처리됨" 채널 의미와 일치).

3. 도구 호출과 병렬 도구

세 API 모두에서 함수 호출이 정상 작동하는 것을 검증했으며, Responses API에서는 한 턴 안에서 병렬 도구 호출도 관찰했습니다(Z.ai는 GLM-5.3에 대해 supports_parallel_tool_calls: true를 명시적으로 선언함). 상위 제한: tools에는 최대 128개의 함수; tool_choice는 기본적으로 auto만 지원합니다.

Chat Completions

completion = client.chat.completions.create(
    model="coding-glm-5.3",
    messages=[{"role": "user", "content": "What's the weather in Beijing today?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get weather for a city",
            "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
        },
    }],
)

# Observed: finish_reason "tool_calls", with a get_weather call in tool_calls

검증됨: tool_choice: "none"이 작동함 — 같은 날씨 질문에 도구 호출 없이 일반 텍스트가 반환됨.

Responses

response = client.responses.create(
    model="coding-glm-5.3",
    input="Check today's weather in Shanghai and Beijing",
    parallel_tool_calls=True,
    tools=[{
        "type": "function",
        "name": "get_weather",
        "description": "Get weather for a city",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
)

# Observed: a single turn returns 2 parallel function_call output items (one for each city)

검증됨: 한 턴에서 병렬 도구 호출 2개 — 공식 supports_parallel_tool_calls: true 선언과 일치.

Messages

response = client.messages.create(
    model="coding-glm-5.3",
    max_tokens=4096,
    tools=[{
        "name": "get_weather",
        "description": "Get weather for a city",
        "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
    }],
    messages=[{"role": "user", "content": "What's the weather in Beijing today?"}],
)

# Observed: stop_reason "tool_use"; content contains a tool_use block

❗ 검증됨: 이 API에서는 tool_choice: {"type": "none"}을 설정해도 모델이 여전히 도구 호출을 생성함 — 도구를 비활성화하려면 tools 파라미터를 완전히 제거하거나, 대신 Chat Completions API에서 tool_choice: "none"을 사용하십시오.

4. 구조화된 출력

response_format은 text와 json_object를 지원하며, 업스트림은 json_schema 모드를 나열하지 않습니다. 엄격한 스키마 준수가 필요하면 JSON Schema를 프롬프트에 포함하고 클라이언트 측에서 검증하십시오.

Chat Completions

completion = client.chat.completions.create(
    model="coding-glm-5.3",
    messages=[
        {"role": "user", "content": "What is the capital of France? Answer in JSON with the key \"answer\"."}
    ],
    response_format={"type": "json_object"},
)

# Observed response content: {"answer": "Paris"}

검증됨: 출력이 요청한 키를 포함하는 유효한 JSON임.

Responses

response = client.responses.create(
    model="coding-glm-5.3",
    input="What is the capital of France? Answer in JSON with the key \"answer\".",
    text={"format": {"type": "json_object"}},
)

# Observed output text: {"answer": "Paris"}

Messages

# Specify the JSON structure in the prompt; observed output is valid JSON
response = client.messages.create(
    model="coding-glm-5.3",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "What is the capital of France? Answer in JSON with the key \"answer\"."}
    ],
)

# Observed response text: {"answer": "Paris"}

5. 컨텍스트 캐싱은 자동

암시적 캐싱은 기본적으로 켜져 있으며 별도로 전달할 파라미터가 없습니다. 반복되는 긴 프리픽스는 usage에 캐시 적중으로 보고됩니다(필드 이름은 API마다 다름).

Chat Completions

# usage of the second call with an identical long prefix
"prompt_tokens_details": {"cached_tokens": 960}

검증됨: 연속으로 호출한 두 번째 요청에서 960개의 캐시된 토큰이 적중됨.

Responses

# usage of the second call with an identical long prefix
"input_tokens_details": {"cached_tokens": 960}

Messages

# hits are reported via usage.cache_read_input_tokens
"cache_read_input_tokens": 0

검증됨: 이번 검증에서는 이 API의 캐시 적중을 재현하지 못했습니다(캐시는 채널별로 워밍되며, 로드 밸런서 전환 시 미스가 발생할 수 있음). 적중 집계 필드는 Anthropic 의미 체계를 따릅니다.

6. 샘플링 및 파라미터 검증

샘플링은 GLM 계열 엔드포인트 규칙을 따릅니다: temperature 범위는 [0, 1]이며 기본값은 1.0입니다(참고 — OpenAI 프로토콜의 [0, 2]보다 좁음); top_p 범위는 [0.01, 1]이며 기본값은 0.95입니다. Z.ai는 둘 중 하나만 조정할 것을 권장합니다.

검증됨: 파라미터 검증은 API마다 다릅니다 — Messages API는 범위를 벗어난 temperature: 3을 유효 범위 [0,1]을 명시한 400 오류로 거부하지만, Chat Completions / Responses는 같은 범위 밖 값을 200으로 조용히 수용합니다. API 간 이전 시 게이트웨이가 범위를 벗어난 샘플링 값을 대신 잡아주리라 기대하지 마십시오.

# Messages API with temperature=3 -> HTTP 400
"temperature parameter invalid: value must be within [0,1]"

7. 기능 × API 지원 매트릭스

아래의 모든 셀은 2026-08-14에 AIHubMix 실시간 API를 통해 실제 호출로 검증되었으며, 각 셀에는 API별 파라미터/필드 표기가 표시됩니다.

FAQ

AIHubMix에서 GLM-5.3 모델 ID는 무엇인가요? [1m] 접미사가 필요한가요?
모델 ID는 coding-glm-5.3이며 그대로 사용하면 됩니다. glm-5.3[1m]은 Z.ai의 Claude Code 클라이언트용 모델 이름 문법이며 AIHubMix 호출과는 관계가 없습니다. 세 API 모두 어떤 접미사도 필요하지 않습니다.

사고 기능을 끌 수 있나요?
아니요. GLM-5.3의 사고 기능은 항상 켜져 있으며 thinking.type은 enabled만 지원합니다. 저희 테스트에서 disabled를 보내면 200이 반환되고 사고는 여전히 수행되었습니다(공식 의미 체계에 따라 low 수준으로 변환됨). 사고 토큰을 절약하려면 reasoning_effort: "low"를 보내십시오.

GLM-5.3은 GLM-5.2와 어떤 관계인가요?
동일한 기본 모델입니다 — 모든 향상은 사후 학습에서 비롯됩니다(공식 문구: "GLM-5.2와 동일한 기본 모델을 사용하며, 모든 향상은 사후 학습에서 나온 것"). API의 두 가지 핵심 변경 사항은 사고 기능을 더 이상 끌 수 없다는 점, 그리고 reasoning_effort가 low/high/max(기본값 max) 세 가지 수준으로 좁혀졌다는 점입니다.

엄격한 json_schema 구조화된 출력이 필요하면 어떻게 하나요?
업스트림은 response_format: json_schema 모드를 나열하지 않습니다. 저희 테스트에서는 json_object JSON 모드가 세 API 모두에서 유효한 JSON을 생성했습니다. 엄격한 스키마가 필요하다면 JSON Schema를 프롬프트에 포함하고 클라이언트 측에서 검증하십시오.

Is coding-glm-5.3 the production release?
It is currently a limited-time preview route (Z.ai's model API docs mark the official API as "coming soon"); AIHubMix will follow up as soon as the commercial API ships. See the model page for current pricing and status.

최신 가격과 실시간 상태는 GLM-5.3 모델 페이지에서 확인할 수 있으며, 다른 모델은 모델 갤러리에서 살펴보실 수 있습니다.