← Docs hub

Day 4: SQE/필드테스트 이슈 분석 및 개선 대응

1. 학습 목표

Day 4는 실제 SQE/필드테스트에서 발생하는 이슈를 소스와 로그 기준으로 분류하는 방법을 정리합니다. LLM 운영 담당자가 “음성이 안 됩니다”라고 보고하는 수준을 넘어서, STT/딕셔너리/Cloud/기능 사양/Device API/상태관리 중 어느 영역 문제인지 1차 판단할 수 있게 만드는 것이 목표입니다.

이 장을 읽은 후에는 다음을 수행할 수 있어야 합니다.

• STT raw, processed, dictionary, token, Cloud response, Device API, TTS를 순서대로 확인한다.
• ApiCallValidator로 인해 기능 실행이 차단된 케이스를 LLM 오분류와 구분한다.
• 필드 이슈를 담당 영역별로 분류한다.
• 개선 필요, 사양상 정상, 테스트 기대값 오류를 구분한다.
• 유관 부서가 바로 재현 가능한 개선 요청서를 작성한다.

참조:

• ApiCallValidator And Error Handling
• E2E Test And Log Analysis Runbook
• Operational Examples
• 필드 이슈 원인 분류 매트릭스
• ApiCallValidator MR8 요약
• 이슈 분석 순서
• Validator gate
• 담당 영역 매핑

2. 본문 개요

실제 필드 이슈는 다음 순서로 분석합니다.
가장 위험한 보고 방식은 "음성이 안 됨"처럼 원인이 섞인 보고입니다.
이렇게 보고하면 STT팀, 딕셔너리 담당, Cloud 담당, SoC 담당 중 누가 봐야 하는지 알 수 없습니다.

우리는 발화 원문부터 TTS 결과까지 로그를 순서대로 따라가고,
어느 단계에서 기대와 실제가 달라졌는지 찾는 방식으로 분석해야 합니다.

3. 이슈 분류 체계

4. ApiCallValidator 소스레벨

preLlmCallValidate()

LLM 실행 전 상태를 봅니다.

확인 API:

getLockModeEnable
getPrivacyModeEnable
getSoundMute
getVoiceRecognitionEnable
getSoundVoiceVolume
getErrorStatus

차단 예:

홈 잠금 ON
프라이버시 모드 ON
음소거 ON
음성인식 OFF
음량 0
LLM 실행 중지급 errorcode

preApiCallValidate()

토큰이 나온 후 기능 실행 전 검증합니다.

LLMResponse(token=<sk_46>)
  -> getErrorStatus()
  -> validationRules[<sk_46>]
  -> movementRules + safeCareRules
  -> 에러 있으면 ErrorGroup별 TTS

핵심 포인트:

토큰이 맞아도 실행이 안 되는 것은 정상일 수 있습니다.
기기 상태상 실행하면 안 되는 기능을 막는 것이 ApiCallValidator의 역할입니다.

5. 대표 분석 케이스

케이스 A: 보안모드가 안 켜짐

로그:

parsedLlamaResponse: [ <sk_46> ]
ApiCallValidator(preApiCallValidate) called with llmResponses: [LLMResponse(token=<sk_46>)]
DeviceCommunicator Output Result - errorcode : [E02]
ApiCallValidator(checkError) called for E02
ttsText: 현재 보안 모드 실행이 불가능합니다...

판정:

딕셔너리/LLM은 정상입니다.
E02가 SafeCareFail 또는 관련 rule로 잡혀 보안모드 실행이 차단된 케이스입니다.

케이스 B: 공기질맵 히스토리 요청이 이해 실패 후 Cloud로 감

로그:

parsedLlamaResponse: [ <sk_29>(get=True) ]
FunctionCallHandler - Handling get state call: <sk_29>
mappingTtsTextAndDeviceApi: error_answer
UNDERSTANDING ERROR TO CLOUD
API Response: case=2, rewrite_query=...

판정:

토큰은 잡혔지만 FunctionCallHandler에 해당 get 분기/TTS가 없거나 불완전했던 케이스일 수 있습니다.
Cloud로 넘어간 것은 로컬 이해 실패 fallback입니다.

케이스 C: 스케줄 발화 오매칭

로그:

STT processed: 오후 세시에 스케줄 설정해줘
[DICTIONARY_MATCH][contains_token.json] key=<sk_...>
actual token: scanning clean

판정:

STT는 맞고 dictionary condition이 잘못 동작한 케이스입니다.
스케줄/청정/스캐닝 관련 phrase group 충돌을 확인해야 합니다.

6. 개선 필요 여부 판단

7. 필드 이슈 분석 절차

1. 발화 원문 확보
2. 동일 조건 3회 재현
3. STT raw 확인
4. STT processed 확인
5. dictionary match 확인
6. parsed token 확인
7. Cloud fallback 여부 확인
8. Cloud response 확인
9. ApiCallValidator 결과 확인
10. Device API input/output 확인
11. TTS/화면 결과 확인
12. 원인 분류
13. 개선 필요 여부 판단
14. 담당 영역 지정
15. 개선 요청서 작성

8. 담당 영역 매핑

담당 영역을 잘못 지정하는 대표 실수:

1. STT raw가 틀렸는데 dictionary 문제로 요청하는 경우
2. token은 맞고 errorcode로 차단됐는데 LLM 오분류로 요청하는 경우
3. Cloud Case 2는 맞지만 rewrite_query 로컬 재진입이 실패했는데 Cloud만 수정하는 경우
4. Device API input은 맞고 output이 다른데 On-device 로직만 수정하는 경우
5. TTS 문구만 다른데 기능 실행 실패로 보고하는 경우

8-1. 개선 요청서 및 유관 부서 협업 프로세스

말레이시아 현지 운영팀이 이슈를 전달할 때는 “증상 설명”이 아니라 아래 흐름으로 담당 영역을 좁힌 뒤 요청해야 합니다.

1. 현지 운영팀: 발화 원문, 언어, 앱/DB/기기 상태, logcat 확보
2. 현지 운영팀: STT raw/processed/token/Cloud/API/TTS 단계별 표 작성
3. 현지 운영팀: 1차 원인 분류와 재현 횟수 기록
4. On-device 담당: dictionary, FunctionCallHandler, Validator, resource 확인
5. Cloud 담당: Case, rewrite_query, prompt, RAG 근거 확인
6. SoC/API 담당: Device API input/output, 기기 상태, errorcode 확인
7. 사양 담당: 지원/미지원, 국가별 정책, 기대값 확정
8. 수정 담당: 변경 후 동일 발화와 주변 negative case 재검증

요청서에 반드시 포함할 값:

9. 실습

운영 예제:

발화: 보안모드 켜줘
토큰: <sk_46>
errorcode: E02
TTS: 현재 보안 모드 실행이 불가능합니다...

판정:

기능 인식은 정상입니다.
현재 기기 상태에서 보안모드 실행이 불가능하므로 Error Handler 차단이 정상일 수 있습니다.

API 동작 예:

토큰: 정상
FunctionCallHandler 분기: 정상
DeviceCommunicator input: 정상
DeviceCommunicator output: 실패 또는 비정상

판정:

On-device 라우팅 문제가 아니라 SoC/API 응답 문제일 수 있습니다.
이 경우 Device API input/output 원문을 첨부해야 합니다.

아래 케이스를 분석합니다.

1. "오늘 날씨 알려줄래"가 스케줄로 잡힘
2. "Please show me the air quality map history"가 처음에 이해 실패 후 Cloud로 감
3. "보안모드 켜줘"가 에러 안내를 말함
4. "공간이 몇 개 있어"가 맵 없음/공간 없음/공간 있음에 따라 다르게 동작
5. "Register the schedule"이 일반 스케줄 요청으로 분류됨

각 케이스 산출물:

발화:
STT raw:
STT processed:
기대 토큰:
실제 토큰:
Cloud 여부:
ApiCallValidator 여부:
Device API 여부:
TTS:
원인 분류:
개선 필요 여부:
담당 영역:

10. 정리 과제

1. 이슈 분류표
2. ApiCallValidator 검증 흐름 요약
3. 실제/가상 이슈 3건 분석 리포트
4. 담당 영역 매핑표
5. 개선 요청서 초안

11. 점검 질문

1. 토큰이 맞는데 기능이 실행되지 않는 대표 이유는 무엇인가?
2. ErrorGroup은 왜 필요한가?
3. OtherErrors는 사용자 발화와 직접 연결되지 않아도 왜 관리해야 하는가?
4. Cloud Case 2 후 실패는 어느 영역 문제로 봐야 하는가?
5. 사양상 정상과 개선 필요를 어떻게 구분하는가?