본문으로 건너뛰기

Session & User ID 설정하기

Session ID와 User ID를 설정하면 LLM 호출을 세션·사용자 단위로 묶어서 추적할 수 있습니다. 설정 방법은 두 가지이며, 여러 방법이 동시에 적용된 경우 우선순위에 따라 하나만 반영됩니다.

코드(API) 방식​

요청 핸들러에서 set_session_id(), set_user_id()를 호출하면, 해당 요청 컨텍스트 안에서 발생하는 모든 LLM 호출에 Session ID와 User ID가 적용됩니다.

from whatap.llm import set_user_id, set_session_id

@app.post("/chat")
async def chat(req):
    set_user_id(req.user.id)                 # 누가
    set_session_id(req.conversation_id)      # 어느 대화
    ...

두 함수는 활성 트랜잭션 컨텍스트에 값을 기록합니다. 따라서 요청 핸들러 안이나 계측된 워크플로우 안에서 호출해야 하며, 트랜잭션 밖(모듈 로드 시점, 워커 시작 전 등)에서 호출하면 아무 동작도 하지 않습니다. 반환값(bool)으로 적용 여부를 확인할 수 있습니다.

스코프 지정​

요청 핸들러가 아닌 곳(백그라운드 작업, 배치)에서 구간을 명시하려면 컨텍스트 매니저를 사용합니다. 블록을 나가면 이전 값으로 복원됩니다.

from whatap.llm import session, user

with user(user_id):
    with session(conversation_id):
        client.chat.completions.create(...)

HTTP 헤더 방식​

Session ID와 User ID가 HTTP 요청 헤더로 전달되는 경우, whatap.conf 설정만으로 별도의 코드 수정 없이 적용할 수 있습니다.

whatap.conf
llm_session_header=X-Conversation-Id
llm_user_header=X-User-Id

위 예시에서는 X-Conversation-Id 헤더 값이 Session ID로, X-User-Id 헤더 값이 User ID로 사용됩니다.

자동 계측 지원 프레임워크​

다음 프레임워크는 별도 설정 없이 Session ID와 User ID가 자동으로 수집됩니다.

프레임워크수집 방식
hermes-agent게이트웨이 인바운드(GatewayRunner._handle_message)에서 이벤트 정보로부터 자동 수집합니다. User ID는 메신저 플랫폼의 사용자 식별자(telegram, slack, whatsapp 등 어댑터가 채우는 값)이며, Session ID는 hermes가 대화 이력을 묶는 세션 키를 그대로 사용합니다.
최종 수정: