← Docs hub

LLM 운영 계획

1. 학습 목표

이 운영 계획의 목표는 LLM 운영 담당자가 단순히 발화 테스트를 수행하는 수준을 넘어서, STT 결과가 On-device LLM과 Cloud LLM을 거쳐 실제 제품 기능으로 실행되는 과정을 구조적으로 이해하도록 만드는 것이다.

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

• 음성 지원 가능 범위와 미지원 범위를 구분한다.
• STT 오인식, 딕셔너리 오매칭, Cloud LLM 오분류, 기능 사양/API 이슈를 구분한다.
• logcat과 테스트 결과를 기반으로 원인을 1차 분류한다.
• 개선 요청서를 기능/원인/재현 조건/기대 결과 기준으로 작성한다.

2. 전체 시스템 관점

제품의 음성 처리 흐름은 아래 순서로 설명한다.

사용자 음성
→ STT
→ On-device dictionary / On-device LLM
→ SK 기능 토큰
→ ApiCallValidator
→ FunctionCallHandler
→ Device API
→ TTS

Cloud LLM은 모든 기능을 직접 실행하는 서버가 아니다. Cloud LLM은 온디바이스가 이해하지 못한 발화나 일반 질의, 최신 정보/RAG가 필요한 질의를 보완하고, 기능 실행이 필요한 경우 rewrite_query를 만들어 다시 온디바이스 로컬 파이프라인에 태우는 역할을 한다.

참조 SVG:

• svg/pdf-safe/pdf_week_curriculum_map.svg
• svg/pdf-safe/pdf_stt_cloud_input_boundary.svg
• svg/ondevice_function_flows/00_common_state_multiturn_flow.svg
• svg/pdf-safe/pdf_cloud_lambda_rag_map.svg

3. 월요일: 제품 기능 사양 및 LLM 구조

핵심 메시지

제품 음성 기능은 STT, LLM, Device API가 연결된 E2E 시스템이다. 특정 발화가 실패했을 때 “LLM이 틀렸다”로 단정하면 안 되고, 어느 단계에서 틀어졌는지를 분리해야 한다.

핵심 내용

• 음성 지원 가능 범위
• 지원/미지원 케이스 구분
• SK 토큰 기반 기능 실행 구조
• On-device LLM 역할
• Cloud LLM 역할
• STT-LLM-TTS E2E 처리 흐름
• 멀티턴, skipResume, isCloudContinue가 전체 흐름에 미치는 영향

운영 예제

같은 발화를 아래 3개 관점으로 분리해서 본다.

1. STT raw/processed 결과가 맞는가?
2. <sk_xx> 토큰이 기대대로 나왔는가?
3. FunctionCallHandler가 기대 API/TTS를 수행했는가?

산출물

• 기능별 지원/미지원 목록 초안
• E2E 단계별 로그 체크리스트

4. 화요일: 온디바이스 딕셔너리 및 E2E TEST

핵심 메시지

딕셔너리는 단어를 많이 넣는 작업이 아니라, 오인식과 오매칭의 균형을 관리하는 작업이다.

핵심 내용

• mapping.json: 정확 발화 매칭
• contains.json: 부분 문자열 기반 보정
• contains_token.json: 기능명과 동작어 조합 기반 매칭
• 3keyword_contains_token.json: 3개 축 조합 기반 오매칭 방지
• substitution_dict.json: STT 오인식 보정
• 지역명/건물명/공간명 처리 방식
• 공간명 normalize와 숫자 처리 범위
• E2E 테스트 수행 방법
• logcat에서 확인할 주요 키워드

주요 로그

[DICTIONARY_MATCH]
parsedLlamaResponse
LLMResponseParser
ApiCallValidator(preApiCallValidate)
FunctionCallHandler
mappingTtsTextAndDeviceApi
DeviceCommunicator Device API Input Parameter

운영 예제

• 정상 발화 10개
• STT 오인식 발화 10개
• 유사 기능 오매칭 가능 발화 10개
• 상태조회/설정이 충돌하는 발화 10개

산출물

• 딕셔너리 테스트 결과표
• 오매칭 원인 분류표
• 수정 필요/불필요 판단 근거

5. 수요일: Cloud LLM 개선 작업 및 테스트

핵심 메시지

Cloud LLM은 일반 대화, 기능 재해석, 준비 질문, 미지원 기능 안내를 Case 구조로 반환한다. 제품 기능 실행은 Cloud가 직접 수행하는 것이 아니라, rewrite_query를 통해 온디바이스 경로로 다시 연결된다.

핵심 내용

• Cloud LLM Lambda 구조
• API Gateway 입력 형식
• lambda_function.py 처리 흐름
• Gemini full_rag() 구조
• File RAG와 Web Search RAG 역할
• 국내 프롬프트 구조
• 말레이시아 Custom RAG 분석 관점
• Case 1/2/3/4 분류 기준
• Cloud 결과 테스트 방법

Case 기준

Case 1: 일반 답변/스몰톡/설명
Case 2: 제품 기능 재해석, rewrite_query 반환
Case 3: 준비 질문 번호 반환
Case 4: 음성 미지원 기능 안내

운영 예제

• 일반 질문이 Case 1로 가는지 확인
• 제품 기능 우회 발화가 Case 2로 가는지 확인
• Cloud가 만든 rewrite_query가 온디바이스 딕셔너리에 다시 매칭되는지 확인
• 최신 정보/RAG 필요 질문에서 File RAG/Web Search 동작을 확인

산출물

• Cloud 테스트 결과표
• Case 오분류 리포트
• 프롬프트 개선 요청서

6. 목요일: SQE/필드테스트 이슈 분석 및 개선 대응

핵심 메시지

필드 이슈는 재현 조건과 로그 근거가 없으면 개선 우선순위를 정할 수 없다. 이슈는 STT, 딕셔너리, Cloud LLM, 기능 사양, Device API, 상태관리로 나누어야 한다.

분류 기준

STT 이슈:
raw text부터 틀림

딕셔너리 이슈:
STT는 맞지만 <sk_xx> 토큰이 틀림

Cloud LLM 이슈:
Case/rewrite_query가 틀림

기능 사양 이슈:
토큰은 맞지만 지원/미지원 판단이 사양과 다름

Device API 이슈:
FunctionCallHandler는 정상 호출했지만 Device API 응답/동작이 다름

상태관리 이슈:
멀티턴, resume, skipResume, isCloudContinue, DeviceStatus 전환이 꼬임

핵심 내용

• logcat 기반 원인 분석
• ApiCallValidator 사전 차단 구조
• Device error code와 기능 실행 가능 여부
• 재현 테스트 작성 방법
• 개선 필요 여부 판단
• 유관 부서 협업 프로세스

산출물

• 이슈 원인 분류표
• 재현 절차
• 기대 결과/실제 결과
• 개선 요청서 초안

7. 금요일: 종합 점검 및 말레이시아 현지 운영 가이드 정리

핵심 메시지

현지 운영은 “테스트를 많이 하는 것”이 아니라, 이슈를 일관된 기준으로 분류하고 재현 가능한 증거로 정리하는 것이다.

핵심 내용

• 실제 SQE 주요 이슈 케이스 리뷰
• STT/LLM/기능 사양/Cloud 연동 이슈별 원인 분석
• 현지 운영 기준 정리
• 테스트 결과 보고서 작성
• 운영 FAQ

종합 점검 흐름

1. 발화 입력
2. STT raw/processed 확인
3. 딕셔너리 매칭 로그 확인
4. <sk_xx> 토큰 확인
5. ApiCallValidator 결과 확인
6. FunctionCallHandler 분기 확인
7. Device API 호출 확인
8. TTS/화면/상태 결과 확인
9. 원인 분류
10. 개선 요청 여부 판단

최종 산출물

• 현지 LLM 운영 기준
• 이슈 분류 템플릿
• 주요 기능 회귀 테스트 목록
• 개선 요청서 예시

8. 첨부 SVG 사용 가이드

전체 구조

• svg/pdf-safe/pdf_week_curriculum_map.svg
• svg/pdf-safe/pdf_stt_cloud_input_boundary.svg
• svg/ondevice_function_flows/00_common_state_multiturn_flow.svg

온디바이스 기능별 구현

• function_flows_index.md
• svg/ondevice_function_flows/sk_39_implementation_flow.svg
• svg/ondevice_function_flows/sk_46_implementation_flow.svg
• svg/ondevice_function_flows/sk_48_implementation_flow.svg

Cloud LLM

• svg/pdf-safe/pdf_cloud_lambda_rag_map.svg

딕셔너리

• svg/pdf-safe/pdf_dictionary_pipeline_map.svg

Error Handler

• svg/architecture/api_call_validator_mr8_summary.svg
• svg/pdf-safe/pdf_api_validator_current_target.svg

9. 핵심 운영 원칙

• 발화 실패는 반드시 단계별로 분리해서 본다.
• STT raw가 틀리면 딕셔너리 수정으로 해결할 수 없는 경우가 많다.
• 딕셔너리는 positive case보다 negative case가 더 중요할 수 있다.
• Cloud LLM은 기능 실행 서버가 아니라 기능 재해석과 일반 응답 보완 경로다.
• 기능 토큰이 맞아도 Device API 상태, 에러코드, 맵/공간/네트워크 상태에 따라 실행되지 않을 수 있다.
• 개선 요청은 “발화, STT, 토큰, 로그, 기대 결과, 실제 결과”가 함께 있어야 한다.