콘텐츠로 이동

5. 주석 (Annotation)

프로파일러는 런타임 API 호출 내역을 관측할 수 있지만, 애플리케이션 고유의 비즈니스 로직이나 모델 구조까지 스스로 파악하지는 못합니다. 주석(Annotation)은 코드의 고유한 구조와 실행 맥락을 트레이스 타임라인상에 명시적으로 시각화하는 메커니즘입니다.

본 장에서는 범위(Range)와 시점(Mark) 주석을 적용하는 방법, 주요 주석 배치 위치, 프로덕션 환경에서의 오버헤드 관리 전략을 다룹니다. 정확한 함수 시그니처는 Python API 레퍼런스를 참고하십시오.

Contents

Section Objective
5.1 주석의 필요성 주석 미적용 트레이스의 한계와 주석 추가의 효과
5.2 Range (구간 주석) 컨텍스트 매니저와 Push/Pop으로 구간 설정
5.3 독립적 Range (Non-scoped Range) 함수 경계를 넘나들거나 서로 교차하는 구간 측정
5.4 Mark (시점 주석) 단일 이벤트 시점 기록
5.5 주석 배치 지침 병목 분석을 위해 주석을 적용해야 하는 주요 경계
5.6 프로덕션 코드에서의 주석 관리 조건부 실행 처리 및 오버헤드 최적화 패턴
5.7 PyTorch 프로파일러 연동 Kineto 연동 모드에서의 주석 동작 방식 및 주의사항

5.1 주석의 필요성

주석이 적용되지 않은 추론 프로그램의 프로파일링 트레이스는 단순히 저수준 API 호출만 무수히 나열된 결과로 나타납니다. 이러한 타임라인만으로는 Prefill과 Decode 단계의 경계나 개별 요청 단위의 범위를 구별할 수 없어, 특정 연산이나 로직에서 얼마만큼의 지연 시간이 발생하는지 진단하기 어렵습니다.

Range 주석 몇 개만 추가해도 타임라인의 구조가 드러납니다. 코드를 거의 고치지 않고 분석 효율을 크게 높이는 방법입니다.


5.2 Range (구간 주석)

1
2
3
4
5
6
7
8
import hapti

with hapti.annotate("prefill"):
    logits = model.prefill(prompt)

with hapti.annotate("decode"):
    for _ in range(max_tokens):
        token = model.step()

hapti.annotate()는 Python의 컨텍스트 매니저로 작동합니다. 지정된 블록에 진입할 때 Range 구간을 열고 블록을 벗어날 때 자동으로 닫히며, 코드 실행 중 예외가 발생하더라도 안전하게 처리됩니다.

Push/Pop으로 명시적 Range 제어

일반적인 Python 코드 블록 구조를 벗어나는 구간 제어가 필요한 경우, 명시적 Push/Pop 진입점을 활용할 수 있습니다.

1
2
3
hapti.range_push("decode")
...
hapti.range_pop()

Push/Pop 쌍 일치 원칙

range_push()와 range_pop()은 스레드별 스택으로 관리됩니다. 조기 반환(return)이나 예외 처리 미흡으로 pop 호출이 누락되면 해당 Range가 열린 상태로 유지되어 이후의 모든 구간이 그 하위로 잘못 중첩됩니다. 안전한 블록 제어가 가능한 hapti.annotate() 사용을 권장하며, 디버깅 시에는 두 함수가 반환하는 중첩 깊이 수치를 확인하십시오.

계층적 중첩 구조

Range 구간은 중첩이 가능하며, 계층적인 서브 스코프 구조를 형성하면 타임라인의 가독성이 크게 향상됩니다.

1
2
3
4
5
with hapti.annotate("request"):
    with hapti.annotate("prefill"):
        ...
    with hapti.annotate("decode"):
        ...

5.3 독립적 Range (Non-scoped Range)

range_start()와 range_stop()은 엄격한 스택 중첩 구조에 제약을 받지 않는 독립적인 구간 측정용 API입니다. 특정 함수 내에서 시작하여 다른 함수에서 종료되거나, 복수의 Range가 서로 교차 및 중첩되는 경우에 활용됩니다.

1
2
3
handle = hapti.range_start("request-42")
...
hapti.range_stop(handle)

Push/Pop 스택 방식과 달리 프로세스 전역 핸들 기반으로 관리되므로, 두 개의 range_start() 구간이 서로 겹치거나 다른 스레드에서 구간을 종료 처리하는 것도 가능합니다.


5.4 Mark (시점 주석)

Mark는 일정 지속 시간을 갖는 구간이 아니라, 특정 시점에 발생한 단일 이벤트를 타임라인상에 표시합니다.

1
hapti.mark("first token")

타임라인상에서 특정 이벤트 지점을 신속히 식별하고자 할 때 활용합니다(예: 주요 실행 경계, 첫 번째 토큰 생성 시점, 캐시 축출 발생 시점 등). 단, 연산 구간의 소요 시간 측정이 목적이라면 Range 주석을 사용해야 합니다.


5.5 주석 배치 지침

성능 병목의 원인을 탐색할 때 주요 기준점이 되는 핵심 경계 위주로 주석을 지정하는 것이 좋습니다.

적용 대상 영역 배치 사유 및 유용성
Prefill / Decode 단계 분리 두 실행 단계의 연산 특성 및 오버헤드 프로파일이 완전히 상이함
요청 및 배치(Batch) 경계 개별 요청/배치 간 성능 편차 및 처리 지연 시간 비교 가능
주요 모델 레이어 (Attention, MLP, Sampling) 모델 연산 블록별 세부 지연 시간 및 소요 비중 파악
CPU 제어 및 데이터 전처리 구간 주석 미적용 시 타임라인상에 유휴 공백으로 나타나 원인 파악이 어려움

이너 루프 주석 남발 주의

고빈도로 반복 실행되는 핫 이너 루프 내부에는 주석을 가급적 적용하지 마십시오. 모든 주석 호출은 개별 레코드로 생성 및 기록됩니다. 토큰 단위당 1~2개 수준의 주석은 무방하나, 레이어 세부 연산마다 무분별하게 추가할 경우 트레이스가 지나치게 복잡해지고 불필요한 측정 오버헤드가 유발됩니다.


5.6 프로덕션 코드에서의 주석 관리

프로파일링 모드가 비활성화된 일반 실행 상태에서 주석 API 호출의 오버헤드는 극히 미미하지만, 연산 오버헤드를 완전히 차단하고 코드 의존성을 정돈하기 위해 다음과 같은 조건부 패턴을 적용할 수 있습니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import contextlib

import hapti

# 설정 플래그로 주석 사용 여부 결정
if PROFILE_ENABLED:
    ctx = hapti.annotate("decode")
else:
    ctx = contextlib.nullcontext()

with ctx:
    ...

또한, 프로파일러 연동부 코드를 자체 헬퍼 모듈로 감싸 패키지 의존성을 격리하는 구조도 권장됩니다.

런처 비활성화 시 동작 안전성

import hapti 모듈은 haprof 런처 환경이 아닌 일반 환경에서도 항상 정상 동작합니다. 프로파일링이 활성화되지 않은 실행 환경에서는 주석 API 호출이 데이터 기록 없이 안전한 No-op으로 무시됩니다.


5.7 PyTorch 프로파일러 연동

이미 torch.profiler 기반의 관측 환경을 구축하여 사용 중인 경우, Kineto 플러그인을 등록하면 LPU 디바이스 실행 내역이 독립된 트레이스가 아니라 PyTorch 프로파일러 출력 타임라인에 함께 통합되어 출력됩니다. Kineto 플러그인의 동작 메커니즘과 haprof 간 선택 기준은 6장 PyTorch 프로파일러 연동을 참고하십시오.

Kineto 연동 시 hapti 주석 제약

hapti.annotate()를 통해 작성된 주석은 haprof 기반 독립 트레이스 수집 시에만 기록됩니다. PyTorch Kineto 연동 경로에서는 해당 주석을 수집하지 않으므로, torch.profiler 타임라인상에 사용자 범위를 표기하려면 PyTorch 표준 인터페이스인 torch.profiler.record_function()을 사용해야 합니다. 두 수집 모드를 모두 활용하는 코드베이스라면 두 주석 방식을 병행 적용하는 것을 권장합니다.


다음 단계