From 0593dae69b9f9e9b13ca66a04b31b18bcdd74cf2 Mon Sep 17 00:00:00 2001 From: happybell80 Date: Tue, 17 Mar 2026 11:12:16 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20companyx=20grounding=20=EC=BD=94?= =?UTF-8?q?=EB=93=9C=20=EA=B2=80=ED=86=A0=20=EA=B2=B0=EA=B3=BC=20=EB=AC=B8?= =?UTF-8?q?=EC=84=9C=20=ED=98=84=ED=96=89=ED=99=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 계획 문서 상태 planned→구현완료_미검증, 리서치 문서에 outdated 사실 섹션 추가, 코드 검토 worklog 신규 작성. 코드 수정 없음. Co-Authored-By: Claude Sonnet 4.6 --- ...합성_시나리오동시종결_계획.md | 9 +- ...성_시나리오동시종결_리서치.md | 45 +++++++ ...unding_코드검토_및_문서현행화.md | 110 ++++++++++++++++++ 3 files changed, 162 insertions(+), 2 deletions(-) create mode 100644 journey/worklog/260317_companyx_grounding_코드검토_및_문서현행화.md diff --git a/journey/plans/260315_companyx_rag_답변합성_시나리오동시종결_계획.md b/journey/plans/260315_companyx_rag_답변합성_시나리오동시종결_계획.md index 05a578d..8f5505a 100644 --- a/journey/plans/260315_companyx_rag_답변합성_시나리오동시종결_계획.md +++ b/journey/plans/260315_companyx_rag_답변합성_시나리오동시종결_계획.md @@ -4,10 +4,15 @@ tags: [plans, companyx, rag, answer-composition, scenario, troubleshooting] # Company X RAG 답변합성 시나리오·트러블 동시종결 계획 -**작성일**: 2026-03-15 -**상태**: planned +**작성일**: 2026-03-15 +**상태**: 구현완료_미검증 +**검토일**: 2026-03-17 **목표**: Company X 내부문서 근거응답 경로를 `대표 질문 특례 처리`에서 `공통 계약 기반 답변합성` 구조로 바꿔, 대응 troubleshooting 문서와 scenario 문서를 함께 닫습니다. +> **2026-03-17 코드 검토 결과**: 이 계획의 핵심 구현(Phase 1~4)은 이미 코드에 반영되어 있음. +> Phase 5(테스트 고정 및 Slack 실응답 검증)가 미완료 상태. +> 상세 내용: [260317_companyx_grounding_코드검토_및_문서현행화](../worklog/260317_companyx_grounding_코드검토_및_문서현행화.md) + ## 관련 문서 - [Company X RAG 답변 합성 회귀](../troubleshooting/260312_companyx_rag_answer_composition_regression.md) - [Company X 내부 문서 근거응답 사용자 시나리오](../scenarios/260312_companyx_내부문서_근거응답_사용자시나리오.md) diff --git a/journey/research/260315_companyx_rag_답변합성_시나리오동시종결_리서치.md b/journey/research/260315_companyx_rag_답변합성_시나리오동시종결_리서치.md index 00ed4b2..9722531 100644 --- a/journey/research/260315_companyx_rag_답변합성_시나리오동시종결_리서치.md +++ b/journey/research/260315_companyx_rag_답변합성_시나리오동시종결_리서치.md @@ -190,3 +190,48 @@ tags: [research, companyx, rag, answer-composition, scenario, troubleshooting] - [Company X RAG 답변합성 시나리오·트러블 동시종결 계획](../plans/260315_companyx_rag_답변합성_시나리오동시종결_계획.md) - [Company X 내부문서 RAG 근거응답 1차 구현 및 부분 검증](../worklog/260312_companyx_내부문서_rag_근거응답_구현및시나리오검증.md) - [Company X RAG 스킬 문서](../../skills/companyx-rag/SKILL.md) + +--- + +## 2026-03-17 코드 검토: 사실 섹션 현행화 + +> 이 리서치는 2026-03-15 코드 기준으로 작성됐습니다. +> 2026-03-17 실제 코드(`rb8001/app/services/companyx_grounding_service.py`)를 직접 검토한 결과, +> 아래 사실들이 이미 코드에서 변경되거나 구현된 것으로 확인됐습니다. + +### 이미 구현되어 outdated된 사실 + +| 리서치 사실 | 현재 코드 상태 | +|---|---| +| Fact 3: query expansion이 2종 하드코딩 | `_build_query_candidates()`가 `_extract_keywords()` + `_DOCUMENT_HINTS_BY_TYPE` 기반 동적 확장으로 변경됨 | +| Fact 4: relevance score만으로 결과 채택 | `_score_result_relevance()`, `_select_relevant_results()`로 질문 적합도 재평가 구현됨 | +| Fact 5: 직접 답이 2종 하드코딩 + generic 기본값 | `_classify_question_type()` + type-based `_build_direct_answer()`로 4개 유형 처리 구현됨 | +| Fact 6: 실패 처리가 results=0일 때만 작동 | `_select_relevant_results()` 필터링 후 relevant=0이면 `_build_failure_answer()` 호출됨. `QUESTION_QUANTITATIVE`는 `_can_answer_quantitative()`로 수치 존재 여부도 판정함 | +| Fact 9: 대표 질문만 특례 처리 | 이제 `_classify_question_type()` → `_build_query_candidates()` → `_score_result_relevance()` 공통 경로. 하드코딩 특례 제거됨 | + +### 여전히 사실인 항목 + +- **Fact 1**: Company X 경로는 의도 분류 전에 우선 진입 (`message_service.py:81`) +- **Fact 2**: 진입 조건은 여전히 marker 기반 (`_looks_like_companyx_grounding_question`) +- **Fact 7**: 응답 합성은 여전히 규칙 기반 문자열 조합 (LLM 합성 아님) + +### 현재 미해결 항목 (Unresolved 그대로) + +- relevance score만으로 질문 적합도 판정 가능한지, 별도 rerank 필요한지 미확정 +- 수치형 질문의 `단정 가능/불가`를 `_COUNT_MARKER_PATTERN` 패턴만으로 충분한지 미검증 +- 재정리형 질문은 이전 응답 재사용 없이 재검색함 (세션 연결 없음) + +### 현재 코드에서 추가 확인된 구조 + +- `_DOCUMENT_HINTS_BY_TYPE`: 유형별 문서 힌트 (`quantitative`는 투자/포트폴리오/실적 계열) +- `_supports_quantitative_focus()`: 수치형 질문에서 count marker 패턴(`\d+개사`, `총\d+` 등) 존재 여부 판정 +- `_select_evidence_results()`: 관련 결과 중 상위 2개만 근거로 선별 (중복 문서 제거) +- `_build_failure_answer()`: 유형별 다른 실패 메시지 반환 + +### 미완료 항목 (코드 기준) + +- Phase 5 테스트 고정 미완료: 재오픈 기준 질문 3개에 대한 자동화 테스트 없음 +- Slack 실응답 검증 미완료: 코드는 구현됐으나 실제 Slack에서 재오픈 질문 3개 통과 여부 미확인 +- 종결 worklog 미존재: 트러블슈팅 문서가 참조하는 `260315_companyx_정확표기_slack_근거응답_경로종결.md` 파일 없음 + +상세: [260317_companyx_grounding_코드검토_및_문서현행화](../worklog/260317_companyx_grounding_코드검토_및_문서현행화.md) diff --git a/journey/worklog/260317_companyx_grounding_코드검토_및_문서현행화.md b/journey/worklog/260317_companyx_grounding_코드검토_및_문서현행화.md new file mode 100644 index 0000000..5949d53 --- /dev/null +++ b/journey/worklog/260317_companyx_grounding_코드검토_및_문서현행화.md @@ -0,0 +1,110 @@ +--- +tags: [worklog, companyx, rag, code-review, docs] +--- + +# Company X Grounding 코드 검토 및 문서 현행화 + +**작성일**: 2026-03-17 +**작업자**: Claude Code (코드 수정 없음, 문서 업데이트만) + +## 관련 문서 +- [Company X RAG 답변합성 시나리오·트러블 동시종결 계획](../plans/260315_companyx_rag_답변합성_시나리오동시종결_계획.md) +- [Company X RAG 답변합성 시나리오·트러블 동시종결 리서치](../research/260315_companyx_rag_답변합성_시나리오동시종결_리서치.md) +- [Company X 내부 문서 근거응답 사용자 시나리오](../scenarios/260312_companyx_내부문서_근거응답_사용자시나리오.md) +- [Company X RAG 답변 합성 회귀](../troubleshooting/260312_companyx_rag_answer_composition_regression.md) + +## 작업 목적 +- 계획 문서 상태가 `planned`인 채로 방치된 상황에서, 실제 코드를 직접 검토해 현재 구현 상태를 확인 +- 리서치 문서의 사실 섹션이 outdated된 부분을 문서에 반영 + +## 검토 대상 파일 +- `rb8001/app/services/companyx_grounding_service.py` (전체) +- `rb8001/app/services/message_service.py` (grounding 진입 경로 확인) +- `DOCS/skills/companyx-rag/SKILL.md` + +## 코드 검토 결과 + +### 계획 대비 구현 완료 항목 + +계획 문서(260315)의 Phase 1~4 핵심이 이미 구현되어 있음. + +#### Phase 2 (질문 유형 계약) - 구현됨 +```python +# _classify_question_type() 존재 (line 137) +# 4개 유형: QUESTION_EXPLANATORY, QUESTION_FACT, QUESTION_QUANTITATIVE, QUESTION_RECAP +QUESTION_EXPLANATORY = "explanatory" +QUESTION_FACT = "fact_check" +QUESTION_QUANTITATIVE = "quantitative" +QUESTION_RECAP = "recap" +``` + +재오픈 기준 질문 매핑 (코드 기준): +- `컴퍼니엑스의 투자사는 몇개야?` → `몇개` 키워드 → `QUESTION_QUANTITATIVE` +- `내부 규정 상 휴가는 얼마나 쓸 수 있어?` → `휴가` 키워드 → `QUESTION_FACT` +- `오늘전통 프로그램을 옐로펀치랑 같이 운영한다는 근거 있어?` → 기본값 → `QUESTION_FACT` + +#### Phase 3 (근거 채택 판정) - 구현됨 +```python +# _score_result_relevance() 존재 (line 278) +# _select_relevant_results() 존재 (line 326): relevance_score <= 0이면 제외 +# _supports_quantitative_focus() 존재 (line 251): count marker 패턴 판정 +``` + +- `투자사` 질문에 투자/포트폴리오/실적 관련 없는 청크 → score=0으로 필터링됨 +- `휴가` 질문에 휴가/연차/반차 없는 청크 → score=0으로 필터링됨 +- 수치형 질문은 `_COUNT_MARKER_PATTERN`으로 실제 숫자 존재 여부까지 판정 + +#### Phase 4 (direct/failure 응답 계약) - 구현됨 +```python +# _build_direct_answer(): 유형별 다른 응답 (line 398) +# _build_failure_answer(): 유형별 다른 실패 메시지 (line 376) +# _build_grounded_response(): relevant_results가 없으면 failure 경로 (line 425) +``` + +`QUESTION_QUANTITATIVE` 실패 경로 예시: +- 관련 결과 있으나 count marker 없음 → `수치를 단정할 수 없습니다. ... 단정 불가` +- 관련 결과 자체 없음 → `뒷받침할 문서를 찾지 못했습니다` + +#### Phase 1 (구조 분리) - 구현됨 +- 함수 분리: `_classify_question_type`, `_build_query_candidates`, `_search_companyx_documents`, `_score_result_relevance`, `_select_relevant_results`, `_select_evidence_results`, `_build_direct_answer`, `_build_failure_answer` +- 질문별 특례 분기 (`if 오늘전통 in message`) 제거됨 + +### 미완료 항목 + +#### Phase 5 (테스트 고정) - 미완료 +- 재오픈 기준 질문 3개에 대한 자동화 테스트 없음 +- 코드 경로 구현은 됐지만 실제 Slack 실응답 검증 미완료 + +#### 문서 불일치 +- 트러블슈팅 문서 `260312_companyx_rag_answer_composition_regression.md`가 `닫힘` 표기 +- 종결 근거로 참조하는 `260315_companyx_정확표기_slack_근거응답_경로종결.md`가 존재하지 않음 +- 시나리오 문서는 여전히 `재오픈` 상태 + +#### SKILL.md vs 코드 정합성 +- SKILL.md 요구 형식: `direct answer → evidence documents → short evidence summary` +- 현재 코드 출력 형식: `direct answer\n\n근거 문서:\n- filename: chunk_summary (chunk N, score X.XX)` +- 대체로 일치하나, `short evidence summary` 부분이 chunk 앞부분 180자 잘라내기로 처리됨 (개선 가능) + +### 진입 조건 현황 (변경 없음) +```python +# _looks_like_companyx_grounding_question() (line 102) +# intent_markers: 근거, 내부 문서, 내부 자료, 자료 기준, 문서 기준, 근거 있어, 확인해줘, 같이 운영, 공동 운영, 협력, mou +# domain_markers: 오늘전통, 옐로펀치, yellowpunch, x-course, x course, 컴퍼니엑스, company x, companyx +``` +- 여전히 marker 기반. `컴퍼니엑스`만 들어가도 grounding 경로 진입 가능 + +## 업데이트한 문서 목록 + +1. `DOCS/journey/plans/260315_companyx_rag_답변합성_시나리오동시종결_계획.md` + - 상태: `planned` → `구현완료_미검증` + - 검토일 추가 + +2. `DOCS/journey/research/260315_companyx_rag_답변합성_시나리오동시종결_리서치.md` + - 코드 검토 섹션 추가 (outdated 사실 목록, 여전히 사실인 항목, 미완료 항목) + +3. 본 문서 신규 작성 + +## 남은 작업 (이 worklog 범위 밖) +- Phase 5: 재오픈 기준 질문 3개 자동화 테스트 작성 +- Slack 실응답 검증 후 시나리오/트러블슈팅 문서 종결 +- 종결 worklog 작성 (`260315_companyx_정확표기_slack_근거응답_경로종결.md` 또는 신규)