Operational Examples

이 문서는 실제 운영 중 자주 발생하는 상황을 예제로 정리합니다. 각 예제는 발화, 기대 흐름, 실제 로그에서 볼 항목, 1차 판정, 개선 위치를 함께 제시합니다.

PDF-safe Operational Examples Triage

PDF-safe Issue Report Packet

0. 예제 판독 순서

운영 예제는 “어떤 기능이 실패했는가”보다 “어느 단계에서 기대와 실제가 갈라졌는가”를 먼저 봅니다.

순서	확인 항목	주요 로그/근거	수정 대상 후보
1	발화와 STT raw가 일치하는가	`STT raw text`	STT/음성 환경
2	raw와 processed가 의미를 유지하는가	`STT processed text`	STT 후처리/substitution
3	기대 token으로 매칭되는가	`[DICTIONARY_MATCH]`, `parsedLlamaResponse`	dictionary/로컬 LLM
4	Cloud가 개입했다면 Case/rewrite가 맞는가	`API Response`, `rewrite_query`	Cloud prompt/router
5	token은 맞지만 실행 전 차단됐는가	`ApiCallValidator`, `errorcode`	Error Handler/기기 상태
6	API 호출과 응답이 맞는가	`DeviceCommunicator Input/Output`	FunctionCallHandler/SoC API
7	TTS/화면만 다른가	`ttsText`, `setLauncherScreen`	string resource/화면 분기

리포트는 아래 단위로 묶습니다.

Context:
  app/db/branch/language/network/device state

Input:
  original utterance / STT raw / STT processed

Routing:
  dictionary match / parsed token / Cloud case / rewrite_query

Execution:
  validator / device API input-output / TTS / screen

Decision:
  root cause / owner / positive-negative regression cases

예제 1: 날씨 발화가 스케줄로 매칭되는 경우

발화: 오늘 날씨 알려줄래?
기대: 날씨 질의 경로
실제: <sk_48>(action=4)

확인 로그:

STT raw text: 오늘 날씨 알려줄래
STT processed text: 오늘 날씨 알려줄래
[DICTIONARY_MATCH][contains_token.json] key=<sk_48>(action=4), matched_phrases=...
parsedLlamaResponse: [ <sk_48>(action=4) ]

판정:

STT 문제 아님.
processed text도 정상.
contains_token 조건이 너무 넓어 일반 동작어 "알려줘"가 스케줄 요청으로 오매칭된 케이스입니다.

개선 위치:

app/src/main/assets/contains_token.json
app/src/androidTest/assets/test_data/...

예제 2: Cloud Case 2는 맞지만 온디바이스 재진입이 실패하는 경우

발화: Please show me the air quality map history
Cloud response:
{
  "case": 2,
  "rewrite_query": "Check the air quality map history, please"
}
온디바이스 재진입 후 error_answer

판정:

Cloud Case 분류는 정상입니다.
하지만 rewrite_query가 온디바이스 dictionary에서 기대 토큰으로 매칭되지 않았습니다.
Cloud prompt와 온디바이스 dictionary 사이의 표현 계약이 맞지 않는 케이스입니다.

분리 기준:

1. rewrite_query가 기능명/action/slot을 포함하지 않음
   -> Cloud prompt rewrite rule 수정

2. rewrite_query는 좋은 명령형 문장인데 dictionary가 못 잡음
   -> 온디바이스 dictionary positive case 추가

3. rewrite_query가 다른 기능 token으로 매칭됨
   -> dictionary negative case 추가 또는 Cloud rewrite 표현 제한

리포트에 반드시 포함할 로그:

API Response: case/function/available_function/rewrite_query
Cloud rewrite_query enters local routing pipeline
[DICTIONARY_MATCH]
parsedLlamaResponse
expected token / actual token

예제 3: SK_46 보안모드 토큰은 맞지만 실행 전 차단되는 경우

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

확인 로그:

parsedLlamaResponse: [ <sk_46> ]
ApiCallValidator(preApiCallValidate) called with llmResponses: [LLMResponse(token=<sk_46>)]
DeviceCommunicator Device API Output Result - errorcode : [E02]
ApiCallValidator(checkError) called for E02

판정:

딕셔너리/LLM 문제 아님.
토큰은 정상이고, 현재 errorcode 때문에 SafeCareFail 또는 MoveFunctionFail로 실행 전 차단된 것입니다.

예제 4: Device API 호출은 됐지만 기기가 동작하지 않는 경우

발화: 전체 청정 시작해줘
토큰: 정상
Device API input: 정상
기기 동작: 없음

판정:

온디바이스 LLM/딕셔너리/FunctionCallHandler는 정상일 수 있습니다.
API output이 실패이거나 스키마가 명세와 다르면 SoC/API 영역으로 분리합니다.

예제 5: TTS 문구만 사양과 다른 경우

토큰: 기대와 일치
Device API: 기대와 일치
TTS: 문구만 다름

판정:

기능 실행 문제 아님.
FunctionCallHandler의 리소스 선택 또는 strings.xml 문구 문제입니다.

예제 6: STT raw에 한글+숫자 결합이 들어오는 경우

발화 추정: 오십분
STT raw: 오0분

발화 추정: 이백킬로미터
STT raw: 이00킬로터

판정:

Cloud/딕셔너리 이전의 STT raw 품질 문제입니다.
온디바이스 로컬 라우팅은 processed text를 볼 수 있지만, Cloud user content는 originalSttResult 기반이므로 Cloud에도 이 raw 표현이 전달될 수 있습니다.

예제 7: 등록된 스케줄 조회와 일반 스케줄 등록의 충돌

발화 A: 등록된 스케줄 보여줘
기대: <sk_48>(get=True)

발화 B: 스케줄 등록해줘
기대: <sk_48>(action=4)

발화 C: 청정 스케줄 등록해줘
기대: <sk_48>(action=1)

판정:

같은 "스케줄" 단어가 들어가도 조회/일반등록/청정등록은 서로 다른 기능입니다.
상태조회 그룹, 일반 요청 그룹, 청정 대상 그룹을 분리해야 합니다.

예제 8: 올타임 모드 설명 질문이 상태조회로 빠지는 경우

PDF-safe Dictionary Collision Triage

발화: What is the all time mode?
기대: <sk_107>(type=12)  // 올타임 모드 설명
실제 가능: <sk_49>(get=True)  // 올타임 모드 상태조회

1차 판정:

TTS 문구부터 수정하지 않습니다.
먼저 parsedLlamaResponse가 어떤 token인지 확인합니다.

로그 판독:

STT raw text: What is the all time mode
STT processed text: What is the all time mode
[DICTIONARY_MATCH][contains_token.json] key=<sk_49>(get=True), matched_phrases=[[what], [all time mode]]
parsedLlamaResponse: [ <sk_49>(get=True) ]
ttsText: All time mode is currently off.

원인:

설명 질문에 대한 exact phrase가 mapping.json에 없고,
상태조회 contains_token 조건이 더 넓게 잡혀 설명 의도를 상태조회로 흡수한 케이스입니다.