LLM Token Visualizer

프롬프트를 수정하면서 다음 토큰 분포(Top-N)와 2단계 홉 흐름을 살펴보고, 선택한 경로로 바로 이어서 생성할 수 있는 간단한 웹 앱입니다. System/User 메시지와 어시스턴트 프리픽스를 분리해 관리할 수 있으며, 스트리밍된 결과를 실시간으로 확인할 수 있습니다.

스크린샷

입력 & 토큰 선택

출력 결과

주요 기능

• 프롬프트 워크스페이스: 시스템 메시지, 사용자 메시지, 어시스턴트 프리픽스를 각각 편집하고 자동 저장합니다.
• 모델 및 샘플링 제어: 온도, Top-N, 홉 수, 최대 출력 토큰을 UI 슬라이더로 조정합니다.
• 토큰 홉 시각화: Hop 1 상위 후보를 카드로 보여주고, 선택한 토큰을 기준으로 실시간 Hop 2를 동기화하여 경로를 미리 확인합니다.
• 경로 기반 생성: 선택한 토큰 경로를 프리픽스에 이어 붙여 한 번에 생성까지 실행하며, 스트리밍 응답을 출력합니다.
• 어시스턴트 프리픽스: 프리픽스를 입력하면 해당 텍스트 이후에 올 토큰들을 예측합니다.
• 프리셋: 요약/질문·답변/톤 변환 예시 프롬프트를 한 번에 불러올 수 있습니다.
• 개별 출력 삭제: 출력 모니터의 각 카드를 개별적으로 삭제할 수 있습니다.

실행 환경

• Node.js 18+ (ESM 모듈 사용)
• OpenAI API 키 (UI에 직접 입력하거나 환경 변수로 설정)

설치 및 실행

npm install
npm run dev

서버는 기본적으로 http://localhost:3000에서 실행됩니다.

환경 변수

• OPENAI_API_KEY: OpenAI API 키. 설정하지 않으면 UI 입력값(x-openai-key 헤더)만 사용합니다.
• PORT: 서버가 바인딩될 포트 (기본값: 3000).
• DEBUG_LOGPROBS: 1로 설정하면 로그 확률 파싱 실패 시 응답 일부를 콘솔에 출력합니다.

사용 방법

1. 서버를 실행한 뒤 브라우저에서 http://localhost:3000을 엽니다.
2. 상단 워크스페이스에 시스템과 사용자 메시지를 입력하고, 필요하다면 어시스턴트 프리픽스를 추가합니다.
3. 우측 컨트롤에서 모델(gpt-4.1-mini(기본), gpt-3.5-turbo, gpt-4.1, gpt-4.1-nano)과 샘플링 파라미터(온도, Top-N, 홉 수, 최대 출력 토큰)를 조정합니다.
4. 토큰 갱신을 누르면 Hop 1 후보가 카드로 표시되며, 선택된 토큰을 기준으로 실시간 Hop 2가 갱신됩니다.
5. 원하는 경로를 선택한 뒤 선택 경로 생성을 누르면 선택한 토큰 경로를 프리픽스로 사용해 답변을 스트리밍으로 확인할 수 있습니다.
6. 입력한 프롬프트와 키는 브라우저 로컬 스토리지에 저장되므로 새로고침 후에도 유지됩니다. 초기화가 필요하면 모두 초기화를 클릭하세요.

프로젝트 구조

• server.js: Express 서버 및 OpenAI 연동, /api/step(Top-N 토큰 조회)과 /api/complete(스트리밍 생성) 엔드포인트 제공.
• public/index.html: 앱 레이아웃 및 UI 텍스트.
• public/app.js: 프론트엔드 로직, 토큰 시각화 및 생성 요청 처리.
• public/styles.css: 스타일과 레이아웃.

알려진 제한 사항

Assistant Prefill 불완전 지원

OpenAI Chat Completions API는 Anthropic Claude와 달리 assistant prefill(어시스턴트 메시지 미리 채우기)을 공식 지원하지 않습니다. 이 앱에서는 프롬프트 엔지니어링 기법으로 이를 우회합니다:

• 사용자 메시지 끝에 답변: {prefix} 형태로 프리픽스를 추가
• 시스템 메시지에 "해당 프리픽스 이후부터 이어서 작성하라"는 지시문 삽입

이 방식은 대부분의 경우 잘 작동하지만, 모델이 지시를 완벽히 따르지 않을 수 있습니다. 프리픽스가 반복되거나 무시되는 경우가 간헐적으로 발생할 수 있습니다.

토큰 경계 문제

한글과 같은 멀티바이트 문자는 여러 토큰으로 분할될 수 있습니다. 홉 토큰 중 불완전한 UTF-8 바이트 시퀀스가 포함된 경우, 앱에서 자동으로 제거하여 출력 품질을 유지합니다.

트러블슈팅

• OPENAI_API_KEY가 없다는 오류: 환경 변수로 설정하거나 UI의 API 키 입력란에 키를 붙여 넣으세요.
• 로그 확률이 비어 있음: 시스템 메시지나 모델을 바꿔 시도하거나 DEBUG_LOGPROBS=1로 디버그 로그를 확인하세요.
• 프리픽스가 반복되거나 무시됨: 위의 "Assistant Prefill 불완전 지원" 항목을 참고하세요. 시스템 메시지를 조정하거나 다른 모델을 시도해 보세요.