GLM-5.3 핸즈온 가이드: 항상 켜져 있는 사고, 세 가지 노력 수준, 그리고 API 지원 매트릭스

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

설명: 2026년 8월 GLM-5.3 가이드: 세 가지 사고_노력 수준, 사고 요약, 병렬 도구 호출, 구조화된 출력 및 자동 캐싱을 통한 항상 켜져 있는 사고 — 검증된 AIHubMix Chat / Responses / Messages 예제 포함.

이 기사는 GLM-5.3의 주요 API 변경 사항 및 사용 노트를 다룹니다. GLM-5.3은 2026-08-14에 출시된 Z.ai의 주력 모델로, GLM-5.2와 동일한 기본 모델을 사용하며 모든 개선은 후속 훈련에서 발생합니다. 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 매개변수 유효하지 않음: 값은 [1,131072] 범위 내여야 합니다."

2. GLM-5.3 vs GLM-5.2: 항상 켜져 있는 사고, reasoning_effort를 통한 강도

GLM-5.3에서 GLM-5.2에 비해 가장 중요한 두 가지 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를 권장합니다.

검증됨: thinking: {"type": "disabled"}를 AIHubMix를 통해 전송하면 200이 반환되며 사고가 여전히 발생함 (reasoning_content는 평소와 같이 반환됨) — 값은 공식 채널 의미에 따라 자동으로 변환되며 거부되지 않습니다. 클라이언트가 "토큰을 절약하기 위해 사고를 끄다"에 의존했다면 reasoning_effort: "low"로 전환하십시오.

검증됨: reasoning_effort에 대한 열외 값도 오류 없이 200을 반환합니다 (공식 문서에 따라 기본값 max로 되돌아감); low와 max는 동일한 산술 질문에 대해 예상되는 경량 사고 경향을 보여줍니다 (27 vs 39 reasoning tokens).

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, 기본값 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)   # 관찰됨: "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.",
)

# 관찰된 response.output 항목 유형: ["reasoning", "message"]
# reasoning 항목: {"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."}
    ],
)

# 관찰된 response.content 블록 유형: ["thinking", "text"]

검증됨: 사고 블록은 기본적으로 반환됩니다; thinking: {"type": "disabled"}를 이 API에 적용하면 사고가 여전히 발생하며 200을 반환합니다 (공식 "비활성화는 낮음으로 변환되며 요청이 계속됨" 채널 의미와 일치합니다).

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"]},
        },
    }],
)

# 관찰됨: finish_reason "tool_calls", 도구 호출에서 get_weather 호출 포함

검증됨: 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"]},
    }],
)

# 관찰됨: 단일 턴에서 2개의 병렬 function_call 출력 항목 반환 (각 도시마다 하나씩)

검증됨: 한 턴에서 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?"}],
)

# 관찰됨: stop_reason "tool_use"; content에 tool_use 블록 포함

❗ 검증됨: 이 API에서는 여전히 도구 호출을 생성합니다 tool_choice: {"type": "none"} 이후 — 도구를 비활성화하려면 tools 매개변수를 완전히 제거하거나 Chat Completions API에서 tool_choice: "none"를 사용하십시오.

4. 구조화된 출력

response_format는 text 및 json_object를 지원하며; 상류에서는 json_schema 모드를 나열하지 않습니다. 엄격한 스키마 준수가 필요할 경우, 프롬프트에 JSON 스키마를 포함하고 클라이언트 측에서 검증하십시오.

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"},
)

# 관찰된 응답 내용: {"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"}},
)

# 관찰된 출력 텍스트: {"answer": "Paris"}

Messages

# 프롬프트에 JSON 구조를 지정하십시오; 관찰된 출력은 유효한 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\"."}
    ],
)

# 관찰된 응답 텍스트: {"answer": "Paris"}

5. 컨텍스트 캐싱은 자동입니다

암묵적 캐싱은 기본적으로 활성화되어 있으며 전달할 매개변수가 없습니다; 반복적인 긴 접두사는 사용량에서 캐시 적중을 보고합니다 (필드 이름은 API에 따라 다릅니다).

Chat Completions

# 동일한 긴 접두사를 가진 두 번째 호출의 사용
"prompt_tokens_details": {"cached_tokens": 960}

검증됨: 두 번의 연속 호출 중 두 번째 호출이 960개의 캐시된 토큰에 적중했습니다.

Responses

# 동일한 긴 접두사를 가진 두 번째 호출의 사용
"input_tokens_details": {"cached_tokens": 960}

Messages

# 적중은 사용량.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를 400으로 거부하며 유효 범위 [0,1]를 명시합니다. 반면 Chat Completions / Responses는 동일한 범위를 벗어난 값을 조용히 200으로 수용합니다. API 간 마이그레이션 시, 게이트웨리가 범위를 벗어난 샘플링 값을 잡아주리라 기대하지 마십시오.

# Messages API에서 temperature=3 -> HTTP 400
"temperature 매개변수 유효하지 않음: 값은 [0,1] 범위 내여야 합니다."

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

아래의 모든 셀은 2026-08-14에 AIHubMix 라이브 API를 통해 실제 호출로 검증되었습니다; 셀은 각 API에 대한 매개변수/필드 철자를 보여줍니다.

자주 묻는 질문

AIHubMix에서 GLM-5.3 모델 ID는 무엇인가요? [1m] 접미사가 필요한가요?
모델 ID는 coding-glm-5.3입니다 — 그대로 사용하십시오. glm-5.3[1m]은 Claude Code 클라이언트를 위한 Z.ai의 모델 이름 구문이며 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 스키마를 포함하고 클라이언트 측에서 검증하십시오.

coding-glm-5.3는 생산 릴리스인가요?
현재 한정된 미리보기 경로입니다 (Z.ai의 모델 API 문서는 공식 API가 "곧 출시 예정"이라고 표시합니다); AIHubMix는 상업 API가 출시되는 대로 후속 조치를 취할 것입니다. 현재 가격 및 상태는 모델 페이지를 참조하십시오.

가격 및 실시간 상태는 GLM-5.3 모델 페이지를 참조하십시오; 더 많은 모델은 모델 갤러리를 방문하십시오.