Refactor 기록¶
이 페이지는 대화 품질과 runtime 구조를 개선한 과정을 찾기 위한 역사 문서 인덱스입니다. 각 상세 문서는 변경 당시의 문제, 판단과 검증을 보존합니다.
현재 기본값과 구현 계약은 Graph Builder Runtime, Scenario 규칙은 Scenario v2 작성 가이드를 기준으로 확인합니다. 이 기록의 과거 코드와 기본값을 현재 동작으로 해석하지 않습니다.
개선 방향¶
리팩터링은 다음 책임을 분리하는 방향으로 진행했습니다.
| 개념 | 답하는 질문 | 현재 표현 |
|---|---|---|
| Dialog act | 사용자가 현재 발화로 무엇을 하는가? | NLUResult.dialogue_act |
| Intent | 사용자가 무엇을 이루려 하는가? | NLUResult.intent |
| Slot | 여러 턴에 걸쳐 어떤 값을 수집하는가? | 전역 slots + collect_slots |
| Policy | 지금 어떤 처리가 필요한가? | Global·Task·Post Policy |
| Executor | 현재 node를 어떻게 실행하는가? | General·Task·Skill Executor |
| Routing | 최종적으로 어디로 이동하는가? | TransitionEngine |
공통 원칙:
- 흐름과 도메인 문구는 Scenario가 소유합니다.
- NLU 해석, Policy 판단, 응답 표현과 routing을 분리합니다.
- 종료와 재개는 명시적인 state와 transition으로 표현합니다.
- 최종 문장뿐 아니라 NLU, state와 routing을 함께 검증합니다.
단계별 기록¶
1. 실행 책임 분리¶
- 01. Greeting Executor 제거: 전용 실행기를 제거하고 공통 실행 경로로 통합한 과정
- 02. Fallback Policy: 무응답·이해 불가 처리를 Global Policy로 분리한 과정
- 03. Node Schema: Node field의 역할과 runtime 소비 범위를 정리한 과정
- 04. Prompts: NLU와 NLG prompt 책임을 분리한 과정
2. 대화 품질과 slot 정확도¶
- 05. General Conversation: 자유 대화 node의 stay와 종료 동작 정리
- 06. Slot Misassignment: 발화가 잘못된 slot에 저장되는 문제 해결
- 07. Prompt and Rules: 공통 prompt와 domain rule 위생 개선
- 08. Collection Nodes:
collect_slots기반 Task 실행 계약 정리
3. 종료와 fallback 경계¶
- 09. Closure and Schema Hygiene: Closure 흐름과 사용되지 않는 schema 정리
- 10. Scenario Prompt Cleanup: Scenario가 소유할 문구와 공통 prompt 분리
- 11. Responses and Fallback: 응답 source와 fallback 표현 우선순위 정리
- 12. Handoff Single Question: Node 이동 시 질문 중복 방지
4. 재개와 session 종료 권한¶
- 13. Continue Conversation Stays in Node: 계속 대화 intent가 현재 node를 유지하도록 수정
- 14. Session End Authority: 종료 요청과 최종 종료 판정의 책임 분리
- 15. Closure Resume and Termination: Closure에서 대화 재개와 종료 분기 정리
- 16. Repeated Silence: 반복 무응답의 counter와 종료 처리
- 17. Terminal Nodes: Terminal node와 outgoing transition의 관계 정리
5. 런타임 프롬프트와 죽은 파라미터¶
- 18. 런타임 내부 프롬프트 정리: 말투를 시나리오로 옮기고 Python NLG 지침을 줄인 과정
- 23.
off_topic제거: TopicGuard와 off-topic stay를 제거하고 슬롯 위생으로 대체한 과정 - 24. 죽은
free_conversation파라미터 제거: 런타임이 읽지 않는 자유 대화 플래그를 시나리오와 생성 목록에서 뺀 과정
현재 문서로 연결¶
과거 문제를 읽은 뒤 현재 동작은 아래 기준 문서에서 확인합니다.
| 주제 | 현재 기준 문서 |
|---|---|
| 전체 실행 구조 | Architecture |
| 한 턴의 함수 흐름 | DSTManager |
| Fallback·Safety·Task 판단 | Policy |
| Executor와 응답 생성 | Executor |
| Node 이동과 종료 우선순위 | Transition |
| Counter와 context field | State |
| Scenario schema | Scenario v2 작성 가이드 |
| 회귀 검증 | Testing |
기록을 읽는 방법¶
각 상세 문서의 코드 예시는 해당 시점의 snapshot입니다. 다음 항목은 특히 현재 코드와 다를 수 있습니다.
- 기본 fallback retry 횟수
- Policy와 Executor class 이름
- Scenario field와 condition namespace
- 종료 node와 transition 우선순위
- Prompt source와 응답 template
현재 동작을 판단할 때는:
- 현재 테스트
- 현재 코드
docs/graph_builder/와docs/scenario/- 이 Refactor 기록
순으로 확인합니다.