Hy3

Hy3는 Tencent Hy 팀이 개발한 295B 파라미터 Mixture-of-Experts(MoE) 모델이에요. 이 문서는 Ascend NPU에서 SGLang으로 Hy3를 배포하는 방법을 안내합니다.

출처: 문서

본문

소개 (Introduction)

Hy3는 Tencent Hy 팀이 개발한 295B 파라미터 Mixture-of-Experts(MoE) 모델로, 활성 파라미터 21B와 MTP 레이어 파라미터 3.8B를 갖추고 있어요. 토큰당 top-8 활성화를 사용하는 192개 전문가, GQA 어텐션(64개 헤드, 8개 KV 헤드, 헤드 차원 128), 256K 컨텍스트 길이를 갖추고 있습니다. 이 모델은 reasoning_effort를 통한 내장 추론, 도구 호출, 투기 디코딩(speculative decoding)을 위한 다중 토큰 예측(MTP)을 지원합니다. Hy3는 비슷한 크기의 모델을 크게 능가하며 2~5배 많은 파라미터를 가진 플래그십 오픈소스 모델과 견줄 만합니다. 특히 에이전트 워크플로우, 장문 컨텍스트 작업, 프로덕션 신뢰성에서 눈에 띄는 개선을 보여줍니다.

이 문서는 SGLang을 사용하여 Ascend NPU에서 Hy3를 배포하는 방법을 보여줘요. 단일 노드(Ascend A3 시리즈)와 다중 노드(Ascend A2 시리즈) PD mixed 모드 및 투기 디코딩을 포함합니다.

지원 기능 (Supported features)

기능 (Feature)	사용 예시 (Example usage)
Tensor Parallelism	`--tp-size 16`
NPU Graph	기본 활성화됨; `--disable-cuda-graph`로 비활성화; 범위는 `--cuda-graph-bs-decode`로 제어; 예: `--cuda-graph-bs-decode 4 8 16 20 24 28 32 36 40`
Speculative Decoding	`--speculative-algorithm EAGLE \` `--speculative-num-steps 2 \` `--speculative-eagle-topk 1 \` `--speculative-num-draft-tokens 3`
Overlap Schedule	`export SGLANG_ENABLE_OVERLAP_PLAN_STREAM=1`
Reasoning Mode	`extra_body={"chat_template_kwargs": {"reasoning_effort": "high"}}` — 깊은 사고 과정(chain-of-thought); `"reasoning_effort": "low"` — 짧은 사고 체인; `"reasoning_effort": "no_think"` — 직접 응답, 사고 없음
Tool Calling	`--tool-call-parser auto --reasoning-parser auto`

Example usage 열의 값은 설명을 위한 예시일 뿐이에요. 하드웨어, 배포 모드, 워크로드에 맞게 조정하세요. 파라미터 세부 사항은 기능 설명을 참고하세요.

기능 간 호환성과 충돌 정보는 기능 호환성 (Feature Compatibility)을 참고하세요.

사전 요구사항 (Prerequisites)

환경 (Environment)

이 튜토리얼을 따르기 전에 아래 문서에서 환경 설정을 완료하세요:

Ascend NPU 퀵스타트 — 가장 빠르게 시작하는 방법이에요. 공식 컨테이너 이미지 실행, SGLang 서버 시작, 테스트 요청 전송을 안내합니다. Ascend에서 SGLang이 처음이라면 추천해요.
NPU 지원 SGLang 설치 — 전체 설치 가이드예요. 컴포넌트 버전 매핑(CANN, TorchNPU, Triton, kernels 등), 소스 또는 Dockerfile에서 빌드, 권장 시스템 설정(CPU 전원 구성, NUMA, swap)을 다룹니다. 공식 이미지 대신 설치하거나 커스터마이즈해야 할 때 사용하세요.

모델 가중치 (Model weights)

Hy3는 총 295B 파라미터를 갖고 있어요. 모델 가중치를 다운로드해야 한다면 다운로드 전에 모델 크기를 확인해서 충분한 공간을 확보하세요.

Hy3 (BF16, 597.60GB)

BF16 변형(597.60GB)은 16 × 64GB 디바이스 메모리(--tp-size 16)에 배포할 수 있어요. 이는 Ascend A3 시리즈 전체 1노드(8장 카드 × 2 die) 또는 Ascend A2 시리즈 2노드(각 8장 카드 × 1 die)에 해당합니다.

모델 가중치는 컨테이너 안에서 접근 가능한 공유 디렉터리에 다운로드하는 것을 권장해요. 하드웨어 사양은 Ascend NPU 참조 — 하드웨어를 확인하세요.

설치 (Installation)

NPU 런타임 환경에 필요한 종속성은 Docker 이미지에 통합되어 온라인 플랫폼에 업로드되어 있어서, 바로 pull할 수 있어요.

**안정 릴리스(stable releases)**와 **데일리 빌드(daily builds)**를 모두 사용할 수 있어요. 아래 명령은 안정 릴리스 태그 기준이에요. 자세한 내용은 Docker 이미지 버전을 참고하세요.

Ascend A3 시리즈:

docker pull quay.io/ascend/sglang:cann9.0.0-a3-v0.5.16

docker run -itd --shm-size=64g --name ${NAME} \
--privileged=true --net=host \
-v /var/queue_schedule:/var/queue_schedule \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v /usr/local/sbin:/usr/local/sbin \
-v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
-v /usr/local/Ascend/firmware:/usr/local/Ascend/firmware \
--device=/dev/davinci0:/dev/davinci0  \
--device=/dev/davinci1:/dev/davinci1  \
--device=/dev/davinci2:/dev/davinci2  \
--device=/dev/davinci3:/dev/davinci3  \
--device=/dev/davinci4:/dev/davinci4  \
--device=/dev/davinci5:/dev/davinci5  \
--device=/dev/davinci6:/dev/davinci6  \
--device=/dev/davinci7:/dev/davinci7  \
--device=/dev/davinci8:/dev/davinci8  \
--device=/dev/davinci9:/dev/davinci9  \
--device=/dev/davinci10:/dev/davinci10  \
--device=/dev/davinci11:/dev/davinci11  \
--device=/dev/davinci12:/dev/davinci12  \
--device=/dev/davinci13:/dev/davinci13  \
--device=/dev/davinci14:/dev/davinci14  \
--device=/dev/davinci15:/dev/davinci15  \
--device=/dev/davinci_manager:/dev/davinci_manager \
--device=/dev/hisi_hdc:/dev/hisi_hdc \
--entrypoint=bash \
quay.io/ascend/sglang:cann9.0.0-a3-v0.5.16

Ascend A2 시리즈:

docker pull quay.io/ascend/sglang:cann9.0.0-910b-v0.5.16

docker run -itd --shm-size=64g --name ${NAME} \
--privileged=true --net=host \
-v /var/queue_schedule:/var/queue_schedule \
-v /etc/ascend_install.info:/etc/ascend_install.info \
-v /usr/local/sbin:/usr/local/sbin \
-v /usr/local/Ascend/driver:/usr/local/Ascend/driver \
-v /usr/local/Ascend/firmware:/usr/local/Ascend/firmware \
--device=/dev/davinci0:/dev/davinci0  \
--device=/dev/davinci1:/dev/davinci1  \
--device=/dev/davinci2:/dev/davinci2  \
--device=/dev/davinci3:/dev/davinci3  \
--device=/dev/davinci4:/dev/davinci4  \
--device=/dev/davinci5:/dev/davinci5  \
--device=/dev/davinci6:/dev/davinci6  \
--device=/dev/davinci7:/dev/davinci7  \
--device=/dev/davinci_manager:/dev/davinci_manager \
--device=/dev/hisi_hdc:/dev/hisi_hdc \
--entrypoint=bash \
quay.io/ascend/sglang:cann9.0.0-910b-v0.5.16

모델 가중치가 이미 공유 디렉터리에 다운로드되어 있다면 -v로 모델 경로를 컨테이너에 마운트하세요. 예: -v /path/to/models:/models.
${NAME}을 자신의 컨테이너 이름으로 바꾸거나, --name을 제거해서 기본 이름을 사용하세요.
큰 배치 크기의 16-NPU 배포에서는 --shm-size=64g를 권장해요.

온라인 서비스 배포 (Online service deployment)

단일 노드 온라인 배포 (Single-node online deployment)

단일 노드 배포는 같은 노드 안에서 prefill과 decode를 모두 수행합니다(PD mixed 모드). 295B 파라미터의 Hy3는 Ascend A3 시리즈 서버의 16개 논리 NPU 전체(물리 NPU 8개 × 각 2개 논리 코어, 논리 NPU당 64GB HBM)를 필요로 해요.

서버를 실행하기 전에 다음 환경 변수를 설정하세요:

# Performance tuning
export SGLANG_SET_CPU_AFFINITY=1
echo performance | tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
sysctl -w vm.swappiness=0
sysctl -w kernel.numa_balancing=0

# CANN environment (adjust paths to match your installation)
source /usr/local/Ascend/ascend-toolkit/set_env.sh
source /usr/local/Ascend/nnal/atb/set_env.sh

# Ascend NPU settings
export ASCEND_USE_FIA=1
export STREAMS_PER_DEVICE=32
export HCCL_BUFFSIZE=3000
export HCCL_OP_EXPANSION_MODE=AIV
export HCCL_SOCKET_IFNAME=lo
export GLOO_SOCKET_IFNAME=lo

# SGLang settings
export SGLANG_ENABLE_OVERLAP_PLAN_STREAM=1
export DEEP_NORMAL_MODE_USE_INT8_QUANT=1

서버를 실행하세요:

MODEL_PATH="/path/to/Hy3"

python3 -m sglang.launch_server \
    --model-path ${MODEL_PATH} \
    --attention-backend ascend \
    --reasoning-parser auto \
    --tool-call-parser auto \
    --device npu \
    --tp-size 16 \
    --host 0.0.0.0 \
    --port 9999 \
    --mem-fraction-static 0.84 \
    --dtype bfloat16 \
    --base-gpu-id 0 \
    --prefill-max-requests 40 \
    --max-running-requests 40 \
    --cuda-graph-bs-decode 4 8 16 20 24 28 32 36 40 \
    --speculative-algorithm EAGLE \
    --speculative-num-steps 2 \
    --speculative-eagle-topk 1 \
    --speculative-num-draft-tokens 3

Ascend A2 시리즈에서 다중 노드 PD mixed 배포 (Multi-node PD mixed deployment on Ascend A2 Series)

각 Ascend A2 시리즈 노드는 8개 NPU(NPU당 64GB HBM)를 제공해요. Hy3는 PD mixed 모드(prefill과 decode가 같은 2노드 클러스터에 배치됨)에서 2 × Ascend A2 시리즈 노드에 걸친 16개 논리 NPU 전체를 필요로 해요.

각 노드에서 서버를 실행하기 전에 다음 환경 변수를 설정하세요:

# ============================================================
# Before running, update the following variables:
#   HCCL_SOCKET_IFNAME: network interface name for HCCL (use `ifconfig` to find)
#   GLOO_SOCKET_IFNAME: network interface name for Gloo
# ============================================================

# Performance tuning
export SGLANG_SET_CPU_AFFINITY=1
echo performance | tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor
sysctl -w vm.swappiness=0
sysctl -w kernel.numa_balancing=0

# CANN environment (adjust paths to match your installation)
source /usr/local/Ascend/ascend-toolkit/set_env.sh
source /usr/local/Ascend/nnal/atb/set_env.sh

# Ascend NPU settings
export ASCEND_USE_FIA=1
export STREAMS_PER_DEVICE=32
export HCCL_BUFFSIZE=3000
export HCCL_OP_EXPANSION_MODE=AIV
export HCCL_SOCKET_IFNAME=<network-interface>
export GLOO_SOCKET_IFNAME=<network-interface>

# SGLang settings

기능 검증 (Functional verification)

서비스가 시작된 후 prompt를 보내서 모델을 호출할 수 있어요. 응답에는 사고 과정을 담은 reasoning_content 필드와 최종 답을 담은 content 필드가 포함됩니다.

서버가 로그에 The server is fired up and ready to roll!를 출력하면 요청을 받을 준비가 된 거예요. 더 많은 테스트 예시(Health Check, Generate, Chat Completions, 포트 사용 안내)는 서비스 테스트를 참고하세요.

정확도 평가 (Accuracy evaluation)

정확도 평가 방법과 데이터셋은 Ascend NPU에서 정확도 평가를 참고하세요.

성능 (Performance)

성능 데이터와 벤치마크 명령은 Ascend NPU에서 성능 테스트를 참고하세요.

모범 사례 (Best practices)

모범 사례 구성 참조 (Best practice configuration reference)

Hy3는 아직 별도의 모범 사례 페이지가 없어요. 위의 단일 노드 온라인 배포와 Ascend A2 시리즈 다중 노드 PD mixed 배포 섹션이 지원되는 PD mixed 사례에 대한 사용할 수 있는 스크립트를 제공합니다. 최적화 기능 전체 목록과 파라미터·호환성 세부 사항은 Ascend NPU 최적화를 참고하세요.

추론 모드 선택 (Reasoning mode selection)

Hy3는 chat_template_kwargs를 통해 세 가지 추론 모드를 지원합니다:

`reasoning_effort`	동작 (Behavior)	권장 대상 (Recommended for)
`no_think`	사고 과정 없이 직접 응답	간단한 Q&A, 저지연 작업
`low`	짧은 사고 체인	중간 수준 추론 작업
`high`	전체 사고 과정(chain-of-thought)	수학, 코딩, 복잡한 추론

대화형 또는 지연에 민감한 애플리케이션에서는 no_think를 사용해 출력 토큰 수를 크게 줄이세요.

성능 튜닝 (Performance tuning)

지원되는 기능의 전체 목록은 지원 기능을, 자세한 최적화 안내는 Ascend NPU 최적화를 참고하세요.

FAQ

일반적인 환경, 설치, 파라미터 문제는 Ascend NPU FAQ를 참고하세요. 이 섹션은 모델별 문제만 다룹니다.

Hy3

Hy3

본문