docs(workflow): RAG 03_rag 흐름 문서화 및 JSON settings 필드 추가

- workflow/03_rag/README.md: RAG 워크플로우 인덱스 SSOT - 4개 흐름 문서 추가 (companyx_grounding, rag_search, rag_upload, skill_embedding) - workflow README에 03_rag 인덱스 섹션 연결 - JSON 4개에 settings 필드 추가 Made-with: Cursor
2026-03-19 18:31:27 +09:00 · 2026-03-19 18:31:27 +09:00 · 64ef0deaee
commit 64ef0deaee
parent 337e2f16e7
10 changed files with 245 additions and 1 deletions
--- a/workflow/03_rag/README.md
+++ b/workflow/03_rag/README.md
@ -0,0 +1,35 @@
+tags: [workflow, rag, companyx, grounding, ssot]
+
+# RAG Workflow Index
+
+## 목적
+- 로빙이 Company X 내부 문서를 읽고 답변하는 RAG 흐름의 SSOT 진입점을 제공한다.
+- 업로드, 검색, Grounding, 임베딩 브리지를 서로 분리해 읽게 한다.
+- 구현 JSON과 운영 문서를 한 곳에서 연결한다.
+
+## 상위 원칙
+- [project-artifacts-ssot.md](../../../../0_VALUE/02_Governance/project-artifacts-ssot.md)
+- [writing-principles.md](../../../../0_VALUE/02_Governance/writing-principles.md)
+- [companyx_rag_답변합성_시나리오동시종결_리서치.md](../../journey/research/260315_companyx_rag_답변합성_시나리오동시종결_리서치.md)
+
+## 범위
+- 포함: `03_rag/*.json`에 대응하는 실행 흐름 문서
+- 포함: Company X 내부문서 업로드, 검색, Grounding, 임베딩 연결
+- 제외: `rb8001`의 답변 합성 로직 상세, 메모리 컬렉션 정비, NAS 동기화 스케줄 자체
+
+## 흐름 지도
+1. [RAG 업로드·인덱싱 파이프라인](./rag_upload_indexing_pipeline.md)
+2. [임베딩 브리지](./skill_embedding_bridge.md)
+3. [RAG 검색·Grounding 요청](./rag_search_grounding_request.md)
+4. [Company X Grounding 파이프라인](./companyx_grounding_pipeline.md)
+
+## 공통 운영 원칙
+- 문서는 JSON보다 먼저 읽는 실행 기준이다.
+- 입력/출력 계약, 실패 분기, 복구 기준을 문서에 먼저 고정한다.
+- 내부 IP, `team_id`, 경로 같은 실행값은 워크플로우 문서에서 현재 기준을 명시하고, 변경 시 같은 작업 단위에서 갱신한다.
+- 검색 결과가 0건이거나 오류가 나면 그대로 실패를 드러내고, 메타 대화나 임시 우회로 숨기지 않는다.
+
+## 연결 문서
+- [Company X 내부문서 RAG 근거응답 구현계획](../../journey/plans/260312_companyx_내부문서_rag_근거응답_구현계획.md)
+- [Company X 내부문서 RAG 근거응답 1차 구현 및 부분 검증](../../journey/worklog/260312_companyx_내부문서_rag_근거응답_구현및시나리오검증.md)
+- [Company X RAG 답변 합성 회귀](../../journey/troubleshooting/260312_companyx_rag_answer_composition_regression.md)
--- a/workflow/03_rag/companyx_grounding_pipeline.json
+++ b/workflow/03_rag/companyx_grounding_pipeline.json
@ -93,6 +93,7 @@
    "Prepare LLM Prompt": { "main": [[{ "node": "Call rb8001 with Context", "type": "main", "index": 0 }]] },
    "Call rb8001 with Context": { "main": [[{ "node": "Return Grounded Answer", "type": "main", "index": 0 }]] }
  },
+  "settings": {},
  "pinData": {},
  "meta": { "templateCredsSetupCompleted": true, "instanceId": "robeing-rag" }
 }
--- a/workflow/03_rag/companyx_grounding_pipeline.md
+++ b/workflow/03_rag/companyx_grounding_pipeline.md
@ -0,0 +1,52 @@
+tags: [workflow, rag, companyx, grounding, answer]
+
+# Company X Grounding 파이프라인
+
+## 목적
+- Company X 소속 사용자의 내부 문서 질문에 대해 로빙이 근거를 붙여 답하게 한다.
+- 직접 답과 근거 문서를 함께 반환하는 기준을 고정한다.
+
+## 상위 원칙
+- [RAG Workflow Index](./README.md)
+- [global-principles.md](../../../../0_VALUE/00_Principles/global-principles.md)
+- [writing-principles.md](../../../../0_VALUE/02_Governance/writing-principles.md)
+
+## 입력
+- 사용자 질문
+- 사용자 ID
+- 검색된 근거 문서 목록
+- 근거 문서 메타데이터
+
+## 출력
+- 직접 답
+- 근거 문서명
+- 근거 문단 요약
+- 필요 시 위치 정보
+- 근거 부족 시 명시적 실패 응답
+
+## 처리 순서
+1. 질문이 Company X 근거응답 대상인지 판단한다.
+2. 검색된 문서 중 질문과 관련도가 높은 근거만 선별한다.
+3. 직접 답을 먼저 만든다.
+4. 근거 문서명과 요약을 붙인다.
+5. 근거가 부족하면 추정 답변 대신 실패 응답으로 끝낸다.
+
+## 실패 분기
+- 질문과 맞지 않는 청크를 근거처럼 반환하지 않는다.
+- 수치형 질문에서 값이 없으면 추정하지 않는다.
+- 내부 규정이나 최신 집계가 없으면 `문서 없음`, `미확인`, `불일치` 중 하나로 명시한다.
+- 메타 대화로 회피하지 않는다.
+
+## 현재 기준
+- 이 흐름은 `rb8001` 답변 합성 규칙과 연결된다.
+- 검색 결과를 그대로 붙이는 방식은 허용하지 않는다.
+- 질문 유형별 분기와 근거 적합도 평가가 필요하다.
+
+## 검증 기준
+- `오늘전통/옐로펀치` 같은 기준 질문에서 직접 답 + 근거 문서가 함께 나와야 한다.
+- `투자사 수`, `휴가 규정` 같은 근거 부족 질문은 추정 없이 실패해야 한다.
+- Slack 실응답과 테스트 응답이 같은 기준을 따라야 한다.
+
+## 관련 문서
+- [RAG 검색·Grounding 요청](./rag_search_grounding_request.md)
+- [Company X 내부 문서 근거응답 사용자 시나리오](../../journey/scenarios/260312_companyx_내부문서_근거응답_사용자시나리오.md)
--- a/workflow/03_rag/rag_search_grounding_request.json
+++ b/workflow/03_rag/rag_search_grounding_request.json
@ -65,6 +65,7 @@
    "Webhook In": { "main": [[{ "node": "Call skill-rag-file Search", "type": "main", "index": 0 }]] },
    "Call skill-rag-file Search": { "main": [[{ "node": "Return Response", "type": "main", "index": 0 }]] }
  },
+  "settings": {},
  "pinData": {},
  "meta": { "templateCredsSetupCompleted": true, "instanceId": "robeing-rag" }
 }
--- a/workflow/03_rag/rag_search_grounding_request.md
+++ b/workflow/03_rag/rag_search_grounding_request.md
@ -0,0 +1,49 @@
+tags: [workflow, rag, companyx, search, grounding]
+
+# RAG 검색·Grounding 요청
+
+## 목적
+- 질문을 `skill-rag-file` 검색으로 보내고, 결과를 로빙의 근거 답변 경로에 전달한다.
+- Company X 내부 문서 질문은 일반 대화가 아니라 근거 검색 경로로 먼저 처리한다.
+
+## 상위 원칙
+- [RAG Workflow Index](./README.md)
+- [writing-principles.md](../../../../0_VALUE/02_Governance/writing-principles.md)
+- [companyx_rag_답변합성_시나리오동시종결_리서치.md](../../journey/research/260315_companyx_rag_답변합성_시나리오동시종결_리서치.md)
+
+## 입력
+- 사용자 질문
+- 사용자 식별자
+- 검색 제한값
+- Company X 대상 여부
+
+## 출력
+- 검색 결과 목록
+- 검색 결과 수
+- 근거 문서 후보
+- 0건 또는 오류 시 실패 상태
+
+## 처리 순서
+1. 질문과 사용자 정보를 받는다.
+2. Company X 대상이면 Company X 컬렉션 우선으로 검색한다.
+3. 검색 결과를 답변 프롬프트에 넣을 수 있는 형태로 정리한다.
+4. 근거 문서 후보를 로빙 답변 경로에 전달한다.
+
+## 실패 분기
+- 검색 결과가 0건이면 `문서 없음` 또는 `미확인`으로 넘길 수 있어야 한다.
+- 검색 API 오류를 성공 응답처럼 포장하지 않는다.
+- 질문 적합도가 낮은 청크는 그대로 노출하지 않는다.
+
+## 현재 기준
+- 이 흐름은 `skill-rag-file` 검색을 호출하는 얇은 브리지다.
+- 실제 답변 합성은 `rb8001`이 맡는다.
+- 검색과 답변 합성의 책임을 섞지 않는다.
+
+## 검증 기준
+- 대표 질문이 검색 API로 정상 전달되는지 확인한다.
+- 검색 결과 0건과 정상 적중이 구분되는지 확인한다.
+- 근거 후보가 없는 경우에도 실패 경로가 유지되는지 확인한다.
+
+## 관련 문서
+- [RAG 업로드·인덱싱 파이프라인](./rag_upload_indexing_pipeline.md)
+- [Company X Grounding 파이프라인](./companyx_grounding_pipeline.md)
--- a/workflow/03_rag/rag_upload_indexing_pipeline.json
+++ b/workflow/03_rag/rag_upload_indexing_pipeline.json
@ -77,6 +77,7 @@
    "Normalize Upload Payload": { "main": [[{ "node": "Call skill-rag-file Upload", "type": "main", "index": 0 }]] },
    "Call skill-rag-file Upload": { "main": [[{ "node": "Return Response", "type": "main", "index": 0 }]] }
  },
+  "settings": {},
  "pinData": {},
  "meta": { "templateCredsSetupCompleted": true, "instanceId": "robeing-rag" }
 }
--- a/workflow/03_rag/rag_upload_indexing_pipeline.md
+++ b/workflow/03_rag/rag_upload_indexing_pipeline.md
@ -0,0 +1,51 @@
+tags: [workflow, rag, companyx, upload, indexing]
+
+# RAG 업로드·인덱싱 파이프라인
+
+## 목적
+- 외부 또는 내부 문서를 `skill-rag-file`에 업로드해 검색 가능한 상태로 만든다.
+- Company X 문서를 검색 경로에 넣기 위한 전처리·저장 절차를 고정한다.
+
+## 상위 원칙
+- [RAG Workflow Index](./README.md)
+- [project-artifacts-ssot.md](../../../../0_VALUE/02_Governance/project-artifacts-ssot.md)
+- [test-principles.md](../../../../0_VALUE/02_Governance/test-principles.md)
+
+## 입력
+- `team_id`
+- `file_url` 또는 업로드 파일 본문
+- `file_name`
+- `metadata`
+
+## 출력
+- 업로드 결과
+- 인덱싱 결과
+- 저장된 문서의 메타데이터
+- 실패 시 실패 원인과 재시도 가능 여부
+
+## 처리 순서
+1. 요청 페이로드를 정규화한다.
+2. 원본 문서를 `skill-rag-file` 업로드 엔드포인트로 전달한다.
+3. 텍스트 추출, 청킹, 임베딩, 저장을 수행한다.
+4. 저장 결과를 그대로 반환한다.
+
+## 실패 분기
+- 파일 누락이면 업로드 전에 실패한다.
+- 텍스트 추출이 실패하면 인덱싱하지 않는다.
+- 임베딩 또는 저장이 실패하면 성공처럼 반환하지 않는다.
+- 같은 파일 재업로드 시 멱등성 규칙을 유지해야 한다.
+
+## 현재 기준
+- RAG 인덱싱은 `skill-rag-file`이 담당한다.
+- Company X 문서는 일반 업로드와 섞이지 않도록 팀/컬렉션 경계를 분리한다.
+- 검색 가능한 상태가 되기 전까지는 Grounding 파이프라인에 연결하지 않는다.
+
+## 검증 기준
+- 업로드 직후 검색 API로 최소 1건 이상 적중하는지 확인한다.
+- 저장된 문서명이 원본 파일명과 정합한지 확인한다.
+- 대용량 문서도 실패 없이 처리되는지 확인한다.
+
+## 관련 문서
+- [RAG 검색·Grounding 요청](./rag_search_grounding_request.md)
+- [임베딩 브리지](./skill_embedding_bridge.md)
+- [Company X Grounding 파이프라인](./companyx_grounding_pipeline.md)
--- a/workflow/03_rag/skill_embedding_bridge.json
+++ b/workflow/03_rag/skill_embedding_bridge.json
@ -74,6 +74,7 @@
    "Call Gemini Embedding API": { "main": [[{ "node": "Normalize Response", "type": "main", "index": 0 }]] },
    "Normalize Response": { "main": [[{ "node": "Return Response", "type": "main", "index": 0 }]] }
  },
+  "settings": {},
  "pinData": {},
  "meta": { "templateCredsSetupCompleted": true, "instanceId": "robeing-rag" }
 }
--- a/workflow/03_rag/skill_embedding_bridge.md
+++ b/workflow/03_rag/skill_embedding_bridge.md
@ -0,0 +1,48 @@
+tags: [workflow, rag, embedding, bridge, companyx]
+
+# 임베딩 브리지
+
+## 목적
+- 워크플로우에서 임베딩 서비스를 호출하는 공통 접점을 정의한다.
+- RAG 인덱싱과 검색에서 같은 임베딩 계약을 사용하게 한다.
+
+## 상위 원칙
+- [RAG Workflow Index](./README.md)
+- [infrastructure-ssot-principle.md](../../../../0_VALUE/02_Governance/infrastructure-ssot-principle.md)
+- [embedding-policy.md](../../../../0_VALUE/02_Governance/embedding-policy.md)
+
+## 입력
+- API 키 또는 인증 정보
+- 입력 텍스트 또는 멀티모달 payload
+- 출력 차원
+- 작업 유형
+
+## 출력
+- 임베딩 벡터
+- 사용한 모델명
+- 실패 시 오류 원인
+
+## 처리 순서
+1. 워크플로우 입력을 임베딩 API 형식으로 변환한다.
+2. 외부 임베딩 API를 호출한다.
+3. 응답 벡터를 정규화한다.
+4. 호출 결과를 다음 단계로 넘긴다.
+
+## 실패 분기
+- 인증 정보가 없으면 호출하지 않는다.
+- 모델명 또는 차원 값이 맞지 않으면 저장 전에 실패한다.
+- 응답 파싱 실패를 성공처럼 반환하지 않는다.
+
+## 현재 기준
+- 임베딩 브리지는 워크플로우에서 공용 접점이다.
+- 차원과 모델은 별도 SSOT와 정합해야 한다.
+- 문서 인덱싱과 검색이 같은 임베딩 기준을 써야 한다.
+
+## 검증 기준
+- 임베딩 호출이 정상 응답을 반환하는지 확인한다.
+- 차원 불일치가 있으면 즉시 실패하는지 확인한다.
+- RAG 인덱싱과 검색이 같은 모델 계약을 쓰는지 확인한다.
+
+## 관련 문서
+- [RAG 업로드·인덱싱 파이프라인](./rag_upload_indexing_pipeline.md)
+- [RAG 검색·Grounding 요청](./rag_search_grounding_request.md)
--- a/workflow/README.md
+++ b/workflow/README.md
@ -6,7 +6,7 @@

 - `01_conversation/`: Slack 진입점, 대화 정규화, 콜드메일 IR 알림 및 액션 추출
 - `02_skills/`: `skill-*` 서비스 브리지 (Email, News, Calendar, Slack)
- `03_rag/`: 파일 업로드, 인덱싱, 임베딩, CompanyX 전용 Grounding 파이프라인
+- `03_rag/`: 파일 업로드, 인덱싱, 임베딩, Company X 전용 Grounding 파이프라인
 - `04_scheduler/`: 정기 브리핑, 상태 알림, 재시도 로직
 - `05_admin/`: 서비스 헬스 체크, 일기(Reflection) 자동 생성 및 동기화

@ -35,6 +35,11 @@
 - 구글 캘린더 연동을 위한 브리지 워크플로우입니다.
 - 일정 조회, 등록, 삭제 요청을 `skill-calendar` 서비스로 전달합니다.

+### 5. RAG 워크플로우 인덱스 (`03_rag/README.md`)
+- Company X 내부 문서를 로빙이 읽고 답변하도록 만드는 RAG 흐름의 진입점입니다.
+- 업로드, 검색, Grounding, 임베딩 브리지의 역할을 분리해서 봅니다.
+- 세부 절차는 각 흐름 문서에서 확인합니다.
+
 ## 사용 시 주의사항

 - **Credential 설정**: 각 노드의 Slack, HTTP Request 노드에서 실제 환경의 Credentials(Token, API Key)를 설정해야 합니다.