← Docs hub

LLM 운영 Wiki

이 Wiki는 LLM 운영 담당자가 실제 SQE/필드 테스트와 현지 운영 중 발생하는 STT/LLM/기능 사양/Cloud 연동 이슈를 스스로 1차 분석할 수 있도록 만든 운영 자료입니다.

대상 저장소:

• On-device Agent: ~/work/2.A1_LLM_Aent/skmagic_ondeviceai_agent
• Cloud LLM Lambda: ~/work/8.cloudLLM/backend-cloud-llm-lambda

전체 목표

이 문서를 학습한 후에는 다음 작업을 수행할 수 있어야 합니다.

• 기능 발화가 제품에서 어떤 경로로 처리되는지 설명할 수 있다.
• 발화 실패를 STT, 딕셔너리, On-device LLM, Cloud LLM, Device API, TTS, 상태관리 이슈로 분리할 수 있다.
• logcat과 Cloud 테스트 결과를 근거로 이슈 재현 리포트를 작성할 수 있다.
• 기능 개선 요청서를 “발화 원문, STT 결과, 기대 토큰, 실제 토큰, 기대 동작, 실제 동작, 로그 근거” 기준으로 작성할 수 있다.

문서 구성

과정 운영 문서

PDF 읽는 경로

PDF는 목적에 따라 읽는 경로를 다르게 잡습니다.

요구사항 추적표

초기 요청 항목이 어느 문서에 반영되어 있는지 확인하기 위한 추적표입니다. 말레이시아 현지 운영팀이 운영 기준을 이해할 수 있도록 Cloud/RAG와 현지 운영 항목은 별도 표기합니다.

핵심 SVG

• 주간 운영 맵 - PDF-safe
• 제품 음성 E2E 전체 구성도
• On-device와 Cloud LLM 책임 경계
• STT/전처리/딕셔너리/LLM 처리 파이프라인
• Cloud LLM Case 및 온디바이스 재진입 구조
• 필드 이슈 원인 분류 매트릭스
• 현지 운영 검증 루프
• STT On-device/Cloud 입력 분기 - PDF-safe
• 전체 상태/멀티턴 공통 흐름
• 온디바이스 딕셔너리 처리 흐름 - PDF-safe
• Cloud LLM Lambda/RAG 구조 - PDF-safe
• Cloud rewrite prompt 강화 기준 - PDF-safe
• 딕셔너리 충돌 분석 절차 - PDF-safe
• 기능별 SK 토큰 구현 설계도 읽는 법 - PDF-safe
• 운영 산출물 생명주기 - PDF-safe
• PDF 표 분할 기준 - PDF-safe
• 로그 근거 확인 사다리 - PDF-safe
• PDF 읽는 경로 - PDF-safe
• 말레이시아 현지 운영 의사결정 라우터 - PDF-safe
• ApiCallValidator MR8 요약
• 기능별 SK 토큰 구현 인덱스

챕터별 판단 흐름 SVG

아래 SVG는 각 Day 문서 본문에도 삽입되어 있습니다. 단순 요약이 아니라 입력 → 처리 단계 → 분기 기준 → 확인 로그 → 산출물을 한 장에서 확인하도록 구성했습니다. 먼저 Day별 대표 SVG로 판단 흐름을 잡고, 더 깊은 기능 단위 분석은 기능별 SK 토큰 구현 인덱스와 Source-level 문서로 내려갑니다.

Day 1: F 이벤트, STT raw/processed, 로컬 토큰화, Cloud 재진입, TTS 이후 resume 판단을 한 흐름으로 확인합니다.

• 음성 입력부터 STT까지
• 로컬 기능 실행 경로
• Cloud fallback과 재진입
• 상태관리 핵심 플래그

Day 2: 어떤 JSON이 먼저 잡았는지, 왜 다른 토큰으로 빠졌는지, positive/negative/regression을 어떻게 묶는지 확인합니다.

• 딕셔너리 처리 순서
• 오매칭 분석 경로
• 딕셔너리 테스트 매트릭스

Day 3: Cloud에 전달되는 원문/시스템 정보, Case 2 rewrite 재진입, 말레이시아 RAG 판단 기준을 확인합니다.

• Cloud request 구성
• Case 응답 계약
• RAG 선택 기준

Day 4: STT/딕셔너리/Cloud/Validator/API/TTS 중 어느 단계 문제인지 로그 근거로 분리합니다.

• 이슈 분석 순서
• Validator gate
• 담당 영역 매핑

Day 5: 릴리즈 전 최소 검증 세트와 실패 시 개선 요청서에 반드시 들어가야 할 근거를 확인합니다.

• 릴리즈 스모크 테스트
• 이슈 리포트 품질 기준

Day별 챕터 SVG

각 Day 문서의 모든 ## 챕터에는 섹션 요약 SVG가 1개 이상 연결되어 있습니다. svg/day-sections/ 아래 SVG는 챕터별 이해 보조 자료이며, 본문 흐름을 읽을 때 해당 챕터의 목적, 입력, 판정 기준, 산출물을 빠르게 확인하는 용도입니다.

Source/Templates 섹션 SVG

소스레벨 문서와 템플릿 문서도 모든 ## 챕터에 PDF-safe 섹션 요약 SVG를 연결했습니다. svg/source-sections/ 아래 SVG는 “이 항목에서 무엇을 확인하고, 어떤 근거로 판단하고, 다음 액션이 무엇인지”를 먼저 보여주는 용도입니다.

소스레벨 상세 문서

아래 문서는 본문에서 “어느 파일의 어느 역할을 봐야 하는가”를 설명하기 위한 소스레벨 자료입니다.

PDF 출력용 구조

LLM 운영 PDF는 큰 원본 구조도보다 svg/pdf-safe/ 그림을 우선 사용합니다.

• PDF Export Guide
• PDF-safe Weekly Operation Map
• PDF-safe E2E Source Trace
• PDF-safe STT On-device/Cloud Boundary
• PDF-safe Cloud LLM Contract
• PDF-safe Cloud Lambda/RAG Map
• PDF-safe Cloud Rewrite Quality Gate
• PDF-safe Cloud Rewrite Prompt Hardening
• PDF-safe Dictionary Pipeline Map
• PDF-safe Dictionary Quality Gate
• PDF-safe Dictionary Collision Triage
• PDF-safe Function Flow Index Reader
• PDF-safe Operational Artifact Lifecycle
• PDF-safe Table Split Rule
• PDF-safe Log Evidence Ladder
• PDF-safe Reading Path Map
• PDF-safe Malaysia Decision Router
• PDF-safe Malaysia Operation Loop
• PDF-safe Operational Examples Triage
• PDF-safe Issue Report Packet
• PDF-safe Error Handler Decision
• PDF-safe ApiCallValidator Current/Target
• PDF Export Boundary Rules
• PDF Quality Gate Checklist

활용 방식

각 요일 문서는 다음 형식으로 읽습니다.

1. 핵심 구조 확인
2. SVG 기반 흐름 확인
3. 코드/로그 기준 상세 확인
4. 운영 예제 적용
5. 결과 분석
6. 산출물 작성
7. 점검 질문 확인

누락 방지 체크리스트

문제를 분석할 때 아래 항목 중 하나라도 비어 있으면 원인 분류가 흔들릴 수 있습니다.

공통 로그 관찰 포인트

On-device Agent에서 주로 확인할 로그는 아래입니다.

STT raw text
STT processed text
[DICTIONARY_MATCH]
parsedLlamaResponse
Cutted parsedLlamaResponse
HI_NAMUH_LLMResponseParser
ApiCallValidator(preLlmCallValidate)
ApiCallValidator(preApiCallValidate)
FunctionCallHandler
mappingTtsTextAndDeviceApi
DeviceCommunicator Device API Input Parameter
DeviceCommunicator Device API Output Result
ttsText
resetState
determineMultiTurn
skipResume

Cloud LLM에서 주로 확인할 항목은 아래입니다.

request body: device_id, messages
system prompt
user content
case
response
rewrite_query
prepared_question_list_number
RAG judge result
File RAG result
Web Search result
final OpenAI-style response

Cloud rewrite_query를 검증할 때는 case=2 여부만 보지 않습니다.

1. Cloud user content가 실제 originalSttResult와 같은지 확인
2. Case Router가 제품 기능을 Case 2로 분류했는지 확인
3. rewrite_query가 사용자 명령형이며 기능명/action/slot을 보존했는지 확인
4. rewrite_query를 온디바이스 로컬 파이프라인에 다시 넣었을 때 기대 <sk_xx>가 나오는지 확인
5. 실패 시 Cloud prompt/router 문제인지, 온디바이스 dictionary 공백인지 분리

이슈 분류 빠른 판단표

템플릿

• E2E 테스트 결과 템플릿
• 이슈 분석 리포트 템플릿
• Cloud LLM 테스트 결과 템플릿