GLM-5.2
GLM-5.2
GLM-5.2은 Z.ai의 플래그십 Mixture-of-Experts 모델로, DeepSeek Sparse Attention (DSA) 기반으로 동작해요. 번개처럼 빠른 인덱서가 쿼리당 희소한 키 토큰 세트(top-2048)를 골라내서, 컨텍스트가 길어져도 어텐션 비용이 거의 일정하게 유지돼요. FP8(zai-org/GLM-5.2-FP8)과 풀 BF16(zai-org/GLM-5.2) 두 가지 정밀도로 제공되며, 둘 다 78개 transformer 레이어, 256개 라우팅 전문가(토큰당 8개 활성), 1M 토큰 컨텍스트 윈도우, 그리고 기본 제공 EAGLE 스타일 추측 디코딩을 위한 단일 MTP(Multi-Token Prediction) 레이어를 갖춰요.
FP8 배포가 권장되며, BF16(~1.5 TB)은 8×B300 노드나 멀티노드 구성이 필요해요. Blackwell용 NVIDIA NVFP4 빌드(nvidia/GLM-5.2-NVFP4)는 MoE 전문가들의 linear 가중치와 활성화만 4-bit로 양자화해서(공유 전문가는 양자화되지 않음) GPQA Diamond, SciCode, IFBench에서 FP8 기준선 대비 ~1포인트 이내의 정확도를 유지해요. AMD MI355X(gfx950)용 MXFP4 빌드(amd/GLM-5.2-MXFP4)도 있어요.
이 문서는 SGLang으로 GLM-5.2를 배포하는 방법, 구성 팁, 추론·함수 호출·HiCache·Claude Code 통합 같은 고급 사용법을 설명해요.
원문 페이지에는 하드웨어와 배포 전략(저지연·균형·고처리량), 그리고 추가 기능 노브를 골라 배포 명령어를 자동 생성해 주는 대화형 Deploy 패널과 Playground가 포함되어 있어요. 위키에서는 렌더링되지 않으니 아래 섹션의 지침을 직접 참고하면 돼요.
출처: 문서
본문
Deployment
설치 방법과 하드웨어 플랫폼은 공식 SGLang 설치 가이드를 참고하세요. 아래 두 경로는 명령 패널의 Python / Docker 토글에 해당해요.
Python (pip / uv):
pip install --upgrade pip
pip install uv
uv pip install --prerelease=allow sglang
그다음 아래 명령 패널의 Python 출력을 해당 환경에서 실행하면 돼요.
Docker:
docker pull lmsysorg/sglang:latest
이미지 실행 방법은 Install → Method 3: Using Docker를 참고하고, 안쪽의 sglang serve ...를 아래 명령 생성기가 만들어 주는 것으로 바꿔 끼우면 돼요.
하드웨어와 레시피를 골라 실행 명령을 생성해요. 세 가지 서빙 전략이 일반적인 운영 지점을 다룬답니다:
- Low-Latency — 단일 사용자에게 가장 빠른 응답. 채팅에 적합해요.
- Balanced — 여러 사용자가 동시에 있어도 좋은 속도. 일반적인 멀티 사용자 서빙에 사용해요.
- High-Throughput — 많은 사용자에 걸쳐 초당 최대 토큰 수. 배치 작업에 최적이에요.
Playground
Playground는 검증된 매트릭스를 넘어선 SGLang 기능을 실험하는 곳이에요. 위 Deploy 패널은 SGLang 팀이 승인한 조합만 내보내지만, Playground에서는 Deploy 패널이 현재 보여주는 셀 위에 추가 노브를 켤 수 있어요.
1. 모델 소개
GLM-5.2은 Z.ai의 플래그십 Mixture-of-Experts 모델로, DeepSeek Sparse Attention (DSA) 기반으로 동작해요. 번개처럼 빠른 인덱서가 쿼리당 희소한 키 토큰 세트(top-2048)를 골라내므로 컨텍스트가 커져도 어텐션 비용이 거의 일정하게 유지돼요. FP8(zai-org/GLM-5.2-FP8)과 풀 BF16(zai-org/GLM-5.2) 두 정밀도로 제공되며, 둘 다 78개 transformer 레이어, 256개 라우팅 전문가(토큰당 8개 활성), 1M 토큰 컨텍스트 윈도우, 단일 MTP(Multi-Token Prediction) 레이어를 갖춰요. FP8 배포가 권장되고, BF16(~1.5 TB)은 8×B300 노드 또는 멀티노드 구성이 필요해요. Blackwell용으로 NVIDIA는 NVFP4 빌드(nvidia/GLM-5.2-NVFP4)를 제공하는데, MoE 전문가의 linear 가중치와 활성화만 4-bit로 양자화하고(공유 전문가는 양자화하지 않음) GPQA Diamond, SciCode, IFBench에서 FP8 기준선 대비 ~1포인트 이내의 정확도를 유지해요. AMD MI355X(gfx950)용으로 AMD는 MXFP4 빌드(amd/GLM-5.2-MXFP4, Quark 양자화)를 제공해요 — 아래 AMD GPU 구성 팁을 참고하세요. 이 레시피는 검증된 amd/GLM-5.1-MXFP4 MI355X 레시피를 바탕으로 추론한 것이며 GLM-5.2에서는 아직 벤치마크되지 않았어요(verified: false).
| 모델 | 구조 | 컨텍스트 |
|---|---|---|
| GLM-5.2-FP8 | MoE · DSA · 256 experts (top-8) · MTP · FP8 | 1,048,576 |
| GLM-5.2 | MoE · DSA · 256 experts (top-8) · MTP · BF16 | 1,048,576 |
| GLM-5.2-NVFP4 | MoE · DSA · 256 experts (top-8) · MTP · NVFP4 | 1,048,576 |
| GLM-5.2-MXFP4 | MoE · DSA · 256 experts (top-8) · MTP · MXFP4 | 1,048,576 |
권장 생성 설정: temperature=1.0, top_p=0.95 (체크포인트의 generation_config.json 기본값; 참고용이며 클라이언트 코드에 하드코딩하지 마세요).
리소스: GLM-5.2-FP8 · GLM-5.2 (BF16) · GLM-5.2-NVFP4 · GLM-5.2-MXFP4.
2. 구성 팁
-
DeepSeek Sparse Attention (DSA). GLM-5.2는
glm_moe_dsa아키텍처를 사용해요. SGLang은 DSA 어텐션 백엔드(flashmla_sparseprefill,fa3decode,sgl-kernel인덱서 topk)를 자동 선택하므로 지원 하드웨어에서는 어텐션 백엔드 플래그가 필요 없어요. SGLang은 DSA 모델의 KV-cache dtype도 자동 선택해요 — Blackwell(B200/GB300/B300, 그러면 DSA를 TensorRT-LLM 백엔드로 라우팅)에서는fp8_e4m3, Hopper(H200)에서는bf16— 그래서--kv-cache-dtype플래그가 필요 없어요. Hopper에서--kv-cache-dtype fp8_e4m3을--dsa-prefill-backend flashmla_sparse_q8 --dsa-decode-backend flashmla_kv와 함께 조합하면 네이티브 FP8 희소 prefill 커널을 선택해요(fp8→bf16 역양자화 왕복 없이 fp8 KV 캐시에 직접 계산; GLM-5.2의 64개 query head가 커널의 네이티브 타일에 맞음) — 커널 세부 정보는 DeepSeek-V3.2 페이지를 참고하세요. 선택적인SGLANG_ENABLE_DSA_Q8KV8_*성능 환경 변수는python/sglang/srt/environ.py에 문서화되어 있어요. -
MTP / 추측 디코딩. 체크포인트에는 nextn 레이어가 하나 들어 있어요. 더 낮은 지연 시간을 위해 EAGLE MTP를 활성화하세요(저지연용
--speculative-algorithm EAGLE --speculative-num-steps 5 --speculative-eagle-topk 1 --speculative-num-draft-tokens 6; 균형용1-1-2). config의index_share_for_mtp_iteration은 draft 단계 간에 DSA 인덱서의 topk를 재사용해요(--speculative-eagle-topk 1에서만 유효). draft 길이를 accept 길이에 맞게 튜닝하세요. GLM-5.2의 MTP 헤드는 강력해서 accept 길이가 높게 유지돼요(많은 워크로드에서 4+, 저지연 실행에서는 5–6에 근접). 서버가 보고하는 accept length를 보고--speculative-num-steps/--speculative-num-draft-tokens를 그에 맞게 조정하세요: accept 길이가 draft 토큰 수에 가깝게 유지되면 더 올릴 여지가 있고(단계당 더 많은 토큰 수용), 많이 낮아지면 낮추세요 — 거부된 draft 토큰마다 검증 계산이 낭비되기 때문이에요. -
메모리. FP8 가중치는 큽니다(MoE 총합이지 활성 파라미터가 아님). H200(TP8)에서는
--mem-fraction-static 0.8정도에서 시작해 올리며 튜닝하고, 4-GPU GB300 단일 노드 구성(TP4)에서는 더 올리세요. -
DP-Attention + DeepEP은 균형/고처리량 전략을 위해 어텐션을 데이터 병렬 랭크에 퍼뜨리고 MoE를 DeepEP로 라우팅해요.
-
BF16 가중치는 더 많은 GPU가 필요해요. 풀 프리시전 빌드(
zai-org/GLM-5.2, ~1.5 TB)는 단일 8×H200 / 8×B200 / 4×GB300 노드에 들어가지 않아요. 8×B300(TP8, ~2.1 TB HBM)에서는 단일 노드에 들어가요 — 검증됨; 더 작은 GPU에서는 멀티노드 구성이 필요하고(예: TP16에서 2×8×H200 또는 2×8×B200, TP8에서 2×4×GB300), 이 멀티노드 BF16 레시피는 아직 제안/추론 상태예요(verified: false). FP8이 권장 배포예요. DSA / MTP / chunked-prefill 안내는 FP8과 동일하게 적용해요. B300에서는 BF16 저지연이 FP8과 같지만(sm103 FP8 경로가 아직 최적화되지 않음), 균형/고처리량 지점에서는 FP8이 이겨요. -
PD Disaggregation (prefill/decode). GLM-5.2는 DSA 모델이며 prefill/decode 분리 하에서 실행돼요 — 위 Playground의 PD Disagg 카드를 켜고(Prefill/Decode 역할 + 전송 백엔드 선택 후
sglang_router.launch_router --pd-disaggregation으로 앞단을 구성) 사용할 수 있어요. Mooncake 백엔드는 InfiniBand HCA를 자동 감지하므로 기본적으로 디바이스 플래그가 필요 없어요. 자동 감지가 잘못된 디바이스를 골랐거나 KV 전송 연결이 실패할 때만--disaggregation-ib-device mlx5_0(자신의 NIC)을 추가하세요. H200 Docker에서 컨테이너에 IB HCA를 노출하세요(--privileged --ulimit memlock=-1, 또는--device /dev/infiniband:/dev/infiniband --cap-add IPC_LOCK) — IB 미노출 시 Mooncake는 조용히 TCP로 폴백돼요. -
Chunked-prefill 크기는 상황에 따라 달라요. 긴 입력(8K+)에서는 기본
--chunked-prefill-size 2048이 너무 작아 균형 지점이 prefill-바운드로 남아요(queuing이 TTFT를 지배). 균형 레시피에서--chunked-prefill-size 32768로 올리면 테스트에서 8×H200과 8×B200(8K-in / 1K-out)에서 대략 +34–78% 출력 처리량, −39–59% TTFT를 얻었어요. 고처리량에서는 중립적(거기선 decode-바운드)이므로 기본값을 유지하세요.--max-running-requests는 KV 용량을 추적하는 것이지 튜닝 남용 대상이 아니에요: 단일 8-GPU 노드에는 동시 8K+1K FP8 요청 ~60–90개가 맞으니, 균형은--max-running-requests 80근처로 고정하고 고처리량은 더 넓게 돌리세요. -
AMD GPU (MI300X / MI325X / MI355X). FP8(
zai-org/GLM-5.2-FP8)은 세 플랫폼 모두에서 단일 노드tp=8로 실행돼요. BF16(zai-org/GLM-5.2, ~1.51 TB)은 MI325X(2 TB HBM)와 MI355X(2.3 TB)에서만 단일 노드로 들어가요; MI300X(1.5 TB)는 한 노드에 BF16 가중치와 KV 캐시를 함께 담을 수 없으므로 거기서는 FP8을 사용하세요(또는 검증 후 멀티노드 BF16 구성). DSA tilelang 백엔드(--dsa-prefill-backend tilelang --dsa-decode-backend tilelang)를 사용하고--chunked-prefill-size 131072와--watchdog-timeout 1200(가중치 로딩 20분)을 추가하세요. FP8은 BF16 대비 약 절반의 메모리를 사용해요(~89 GB/GPU vs ~175 GB/GPU). GLM-5.2와 DeepSeek-V3.2는 같은 모델 구조를 공유하므로, 다른 DSA / HiSparse 팁은 DeepSeek-V3.2 cookbook을 참고하세요. -
MI355X MXFP4 (gfx950 전용). AMD는 MI355X용 Quark 양자화
amd/GLM-5.2-MXFP4빌드를 제공해요.--trust-remote-code(Quark의 커스텀 quant config)가 필요하고tp=4로 실행되며(4-bit MoE 가중치가 4-GPU 슬라이스에 맞음)--kv-cache-dtype fp8_e4m3, DSA triton 백엔드(--dsa-prefill-backend triton --dsa-decode-backend triton, SGLang ROCm 기본값이기도 함), 그리고 위 FP8/BF16 레시피와 같은--chunked-prefill-size,--watchdog-timeout을 사용해요.tp=4에서 이 형태(FP8 KV 캐시에서 랭크당 16 query head)는 gfx950 희소-MLA 커널이 튜닝된 형태예요. 위tp=8레시피는 발표 수치를 측정한 그대로 tilelang을 유지해요. 이 레시피는 검증된amd/GLM-5.1-MXFP4MI355X 배포(같은 DSA 구조 계열)에서 가져온 것이며 GLM-5.2에서는 아직 벤치마크되지 않아서, Deploy 패널은 미검증으로 표시해요.
- AMD에서의 MTP / EAGLE 추측 디코딩. 5단계 MTP는
lmsysorg/sglang-rocm:v0.5.20-rocm720-mi35x-20260920로 MI355X의amd/GLM-5.2-MXFP4에서 검증됐어요. TP8/EP1에서는 Low-Latency, HiCache와 함께 TP4/EP4에서는 High-Throughput(--enable-hierarchical-cache --hicache-ratio 1.0)을 선택하세요. HiCache는 기본kernel,page_first,write_through설정을 사용해요. MTP는 MI300X/MI325X의 GLM-5.2와 다른 MI355X 체크포인트 정밀도에서는 아직 검증되지 않았어요.
3. 고급 사용법
3.1 추론(reasoning)
GLM-5.2는 하이브리드 추론 모델이에요. glm45 추론 파서를 활성화(위 Playground의 Parsers 카드에서 Reasoning Parser 토글)하면 thinking과 최종 답변을 분리할 수 있어요 — thinking은 message.reasoning_content에, 답변은 message.content에 담겨요. Thinking은 기본적으로 켜져 있으며, chat_template_kwargs: {"enable_thinking": False}로 끌 수 있어요(템플릿 변수는 enable_thinking이지 thinking이 아니에요).
추론 노력(Reasoning effort). chat_template_kwargs: {"reasoning_effort": ...}를 전달하면 Reasoning Effort: <level> 시스템 줄을 주입해요(thinking이 켜져 있을 때만). 템플릿은 Max와 High 두 수준만 실제로 연결하며, reasoning_effort를 아예 전달하지 않으면 가장 높은 Max를 받아요. "high"가 노력을 낮추는 유일한 값이며, 다른 모든 값("low", "medium" 포함)은 Max로 폴백돼요:
reasoning_effort |
주입되는 시스템 줄 | 효과 |
|---|---|---|
| (전달 안 함 / 미설정) | Reasoning Effort: Max |
기본값 — 가장 높은 추론 |
"high" |
Reasoning Effort: High |
추론을 낮춤 |
"low", "medium", 기타 모든 값 |
Reasoning Effort: Max |
Max로 폴백(별도 수준 아님) |
추론 예시 (Python):
from openai import OpenAI
client = OpenAI(base_url="http://localhost:30000/v1", api_key="EMPTY")
resp = client.chat.completions.create(
model="zai-org/GLM-5.2-FP8",
messages=[{"role": "user", "content": "What is 15% of 240?"}],
extra_body={"chat_template_kwargs": {"enable_thinking": True, "reasoning_effort": "high"}},
)
msg = resp.choices[0].message
print("Reasoning:", getattr(msg, "reasoning_content", None))
print("Answer:", msg.content)
출력 예시:
Reasoning: 1. **Identify the core question:** The user wants to find 15% of 240.
2. **Convert the percentage to a decimal:** 15% = 0.15
3. **Multiply by the total:** 0.15 * 240 = 36
(Quick mental math: 10% of 240 = 24; 5% = 12; 24 + 12 = 36.)
Answer: 15% of 240 is **36**.
Here is how you can calculate it:
0.15 × 240 = 36
3.2 함수 호출(Tool Calling)
glm47 함수 호출 파서를 활성화(위 Playground의 Parsers 카드에서 Tool Call Parser 토글)하면 message.tool_calls로 구조화된 함수 호출이 드러나요. GLM-5.2는 더 새로운 <tool_call>…<arg_key>…<arg_value>… 형식을 출력하므로 glm47 파서가 필요해요 — 이전 glm45 파서는 이 형식을 파싱하지 못해요(호출이 content에 원시 텍스트로 남아요). thinking 모드에서는 턴이 reasoning_content도 채우므로 두 필드를 모두 출력하세요.
함수 호출 예시 (Python):
from openai import OpenAI
client = OpenAI(base_url="http://localhost:30000/v1", api_key="EMPTY")
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}]
resp = client.chat.completions.create(
model="zai-org/GLM-5.2-FP8",
messages=[{"role": "user", "content": "What's the weather in Paris?"}],
tools=tools,
)
msg = resp.choices[0].message
print("Reasoning:", getattr(msg, "reasoning_content", None))
print("Tool calls:", msg.tool_calls)
출력 예시:
Reasoning: The user wants to know the weather in Paris. I'll call the get_weather function with "Paris" as the city.
Tool calls: [
{
"id": "call_13fcd52146934b7781d06d4a",
"type": "function",
"function": {"name": "get_weather", "arguments": "{\"city\": \"Paris\"}"}
}
]
3.3 HiCache (계층적 KV 캐싱)
장문·prefix 집약 워크로드에서는 계층적 KV 캐싱을 활성화해 차가운 KV 블록을 호스트 메모리로 넘길 수 있어요(위 Playground의 Hierarchical KV Cache 카드 토글). GLM-5.2의 1M 토큰 윈도우를 고려하면 유용하며, --hicache-ratio를 재사용 패턴에 맞는 쓰기 정책과 짝지어 사용하세요.
3.4 Claude Code 통합
GLM-5.2의 강력한 추론 + 함수 호출 능력은 Anthropic의 에이전틱 CLI인 Claude Code를 위한 좋은 백엔드가 돼요. SGLang은 모든 서버에서 Anthropic 호환 /v1/messages 엔드포인트를 노출하므로, Claude Code는 환경 변수만으로 코드 변경 없이 GLM-5.2 서버와 대화할 수 있어요. 서버를 --reasoning-parser glm45 --tool-call-parser glm47로 시작하고(위 Deployment 패널의 아무 레시피나 동작), 그다음:
export ANTHROPIC_BASE_URL="http://127.0.0.1:30000"
export ANTHROPIC_AUTH_TOKEN="dummy"
export API_TIMEOUT_MS="3000000"
export CLAUDE_CODE_AUTO_COMPACT_WINDOW="1000000"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export CLAUDE_CODE_ATTRIBUTION_HEADER=0
export ANTHROPIC_DEFAULT_HAIKU_MODEL="glm-5.2[1m]"
export ANTHROPIC_DEFAULT_SONNET_MODEL="glm-5.2[1m]"
export ANTHROPIC_DEFAULT_OPUS_MODEL="glm-5.2[1m]"
claude
이 중 두 가지가 GLM-5.2에 특히 중요해요:
CLAUDE_CODE_ATTRIBUTION_HEADER=0— Claude Code는 시스템 프롬프트 앞에 요청별 attribution 블록을 붙여요. GLM-5.2의 채팅 템플릿은tools를system앞에 렌더링하므로 요청별 해시가 턴 간 첫 토큰이 되어 radix prefix 캐시가 매 턴마다 전체 system + history를 다시 prefill해요. 이 env는 블록을 제거해 prefix 캐시 재사용을 복원해요.- 모델 이름으로
glm-5.2[1m]—[1m]접미사는 클라이언트 측 힌트로, GLM-5.2의 1,048,576 토큰 윈도우에 맞는 Claude Code의 1M 컨텍스트 베타를 활성화해요. 이게 없으면 컨텍스트가 1M보다 훨씬 아래로 제한돼요. SGLang은model필드를 검증하지 않으므로 서버 측에서는 어떤 이름이든 허용돼요.
전체 설정(스트리밍, tool-use, count_tokens, ~/.claude/settings.json에 env 저장, 트러블슈팅)은 Anthropic-Compatible API를 참고하세요.
3.5 컨텍스트 병렬 처리(Context Parallelism)
Prefill 컨텍스트 병렬 처리는 장문 컨텍스트에서 TTFT를 줄이는 데 도움이 돼요. GLM-5.2에서 prefill 컨텍스트 병렬 처리를 활성화하려면 다음 인자를 추가하세요:
--attn-cp-size 8 \
--enable-prefill-cp \
--cp-strategy interleave \
이는 어텐션 forward 중 시퀀스를 --attn-cp-size 랭크에 균등하게 분할해요. prefill CP의 트레이드오프는 인덱서 topk와 어텐션 커널 전에 추가 all-gather 연산이 들어가서 decode(통합 배포) 또는 짧은 prefill의 지연 시간을 늘린다는 점이에요.
PD Disaggregation으로 배포할 때 prefill 노드는 LayerSplit 기법을 켤 수 있어요:
--enable-dsa-cache-layer-split \
--attn-cp-size 8 \
--cp-strategy interleave \
LayerSplit을 사용하면 각 랭크의 KV 캐시를 CP 어텐션 그룹에 걸쳐 분할하고 필요할 때 prefetch할 수 있어요. 이렇게 하면 KV 캐시 메모리를 최대 75% 줄여 prefill 쪽 처리량을 높일 수 있어요.
3.6 HiCache DRAM 오프로드를 사용한 에이전틱 장문 컨텍스트 (NVFP4, MTP)
B300 (TP8):
python3 -m sglang.launch_server \
--model-path nvidia/GLM-5.2-NVFP4 \
--trust-remote-code \
--tp 8 \
--ep-size 1 \
--quantization modelopt_fp4 \
--kv-cache-dtype fp8_e4m3 \
--bf16-gemm-backend cutedsl \
--max-prefill-tokens 8192 \
--chunked-prefill-size 8192 \
--mem-fraction-static 0.85 \
--tool-call-parser glm47 \
--reasoning-parser glm45 \
--speculative-algorithm EAGLE \
--speculative-num-steps 3 \
--speculative-eagle-topk 1 \
--speculative-num-draft-tokens 4 \
--enable-hierarchical-cache \
--hicache-size 270 \
--hicache-write-policy write_back \
--hicache-io-backend direct \
--hicache-mem-layout page_first_direct
B200 (TP8): 같은 명령에 --mem-fraction-static 0.83과 --hicache-size 169를 사용해요. 더 낮은 동시성(c1/c4/c8)에서는 대신 --hicache-ratio 0.75를 써요.