핵심 설계: CMS 는 LangChain·벡터 로직을 Java 에 재구현하지 않는다. 중앙 Python
+ * guardia-rag 의 검색·기법·구조화·검증·에이전틱을 REST 로 호출하기만 한다. 미가용/타임아웃/RAM
+ * 부족 시 절대 예외를 전파하지 않고 {@code degraded:true} 가 표시된 빈/폴백 결과를 돌려준다(서비스
+ * 계층이 CMS 로컬 {@code AiService} 폴백 수행).
+ *
+ *
보안 불변: 온프레미스 전용(외부 API 0). 응답에서 자격증명/회원 PII/스택트레이스 미노출.
+ * 오류는 요약만 로깅.
+ *
+ *
호출 계약(중앙, base http://127.0.0.1:8020):
+ *
+ *
POST /rag/answer — 검색+근거생성+인용+guardrail (콘텐츠 초안·SEO·번역·검색 용)
+ *
POST /rag/structured — format:json 결정론 JSON (UGC 모더레이션·감성 용)
+ *
POST /rag/agent — 에이전틱 tool-use 다단계 (콘텐츠 일괄 작업, 옵트인)
+ *
POST /rag/feedback — 👍/👎 피드백 (solution=cms 격리)
+ *
GET /rag/trust/settings — 가용성 핑
+ *
+ */
+@Slf4j
+@Component
+public class RagClient {
+
+ private final WebClient.Builder builder;
+ private final RagProperties props;
+
+ public RagClient(WebClient.Builder builder, RagProperties props) {
+ this.builder = builder;
+ this.props = props;
+ }
+
+ /** 중앙 RAG 사용 가능 여부(설정 enabled + 가벼운 핑). */
+ public boolean available() {
+ if (!props.isEnabled()) return false;
+ try {
+ builder.baseUrl(props.getBaseUrl()).build()
+ .get().uri("/rag/trust/settings?solution=" + props.getSolution())
+ .retrieve().bodyToMono(String.class)
+ .timeout(Duration.ofSeconds(3)).block();
+ return true;
+ } catch (Exception e) {
+ return false;
+ }
+ }
+
+ /**
+ * POST /rag/answer — 검색+생성+검증+guardrail.
+ *
+ * @return {@code {answer, grounded, faithfulness, citations[], guardrail{...}, sources[], answer_id, degraded}}.
+ * 미가용 시 {@code degraded:true}.
+ */
+ public Map answer(String query, String retrievalMode, boolean rerank,
+ int topK, String model, boolean verify) {
+ if (!props.isEnabled()) return degraded("rag_disabled");
+ try {
+ Map options = new LinkedHashMap<>();
+ options.put("rerank", rerank);
+ options.put("stream", false);
+ options.put("verify", verify);
+ if (model != null) options.put("model", model);
+
+ Map body = new LinkedHashMap<>();
+ body.put("solution", props.getSolution());
+ body.put("query", query);
+ body.put("retrieval_mode", retrievalMode == null ? "vector" : retrievalMode);
+ body.put("top_k", topK <= 0 ? 5 : topK);
+ body.put("options", options);
+ Map res = post("/rag/answer", body);
+ return res != null ? res : degraded("rag_no_response");
+ } catch (Exception e) {
+ log.warn("RAG /answer 일시 불가 — CMS 폴백: {}", summarize(e));
+ return degraded("rag_unavailable");
+ }
+ }
+
+ /**
+ * POST /rag/structured — 스키마 강제 결정론 JSON (UGC 모더레이션).
+ *
+ * @return {@code {data:{...}, valid, fallback_used, degraded}} 형태. 미가용 시 {@code degraded:true}.
+ */
+ public Map structured(String prompt, Map schema,
+ String model, double temperature) {
+ if (!props.isEnabled()) return degraded("rag_disabled");
+ try {
+ Map body = new LinkedHashMap<>();
+ body.put("solution", props.getSolution());
+ body.put("prompt", prompt);
+ if (schema != null) body.put("schema", schema);
+ if (model != null) body.put("model", model);
+ body.put("temperature", temperature);
+ body.put("max_retries", 1);
+ Map res = post("/rag/structured", body);
+ return res != null ? res : degraded("rag_no_response");
+ } catch (Exception e) {
+ log.warn("RAG /structured 일시 불가 — CMS 폴백: {}", summarize(e));
+ return degraded("rag_unavailable");
+ }
+ }
+
+ /**
+ * POST /rag/agent — 에이전틱 tool-use 다단계 (CMS 콘텐츠 도구 활용, 옵트인).
+ *
+ * @param tools 등록할 CMS 도구 이름 목록(중앙 도구 레지스트리 매칭). null 가능.
+ * @return {@code {answer, steps[], tools_used[], degraded}}. 미가용 시 {@code degraded:true}.
+ */
+ public Map agent(String task, List tools, int maxSteps,
+ String model, String retrievalMode) {
+ if (!props.isEnabled()) return degraded("rag_disabled");
+ try {
+ Map body = new LinkedHashMap<>();
+ body.put("solution", props.getSolution());
+ body.put("task", task);
+ if (tools != null) body.put("tools", tools);
+ body.put("max_steps", maxSteps <= 0 ? 4 : Math.min(maxSteps, 8)); // 상한 강제(폭주 차단)
+ if (model != null) body.put("model", model);
+ if (retrievalMode != null) body.put("retrieval_mode", retrievalMode);
+ Map res = post("/rag/agent", body);
+ return res != null ? res : degraded("rag_no_response");
+ } catch (Exception e) {
+ log.warn("RAG /agent 일시 불가 — CMS 폴백: {}", summarize(e));
+ return degraded("rag_unavailable");
+ }
+ }
+
+ /**
+ * POST /rag/feedback — 👍/👎 피드백(solution=cms 격리).
+ *
+ * @return {@code {feedback_id, stored}} 또는 미가용 시 {@code {stored:false, degraded:true}}.
+ */
+ public Map feedback(String answerId, String query, String answer,
+ String verdict, String correction, String userRef) {
+ if (!props.isEnabled()) return Map.of("stored", false, "degraded", true);
+ try {
+ Map body = new LinkedHashMap<>();
+ body.put("solution", props.getSolution());
+ if (answerId != null) body.put("answer_id", answerId);
+ if (query != null) body.put("query", query);
+ if (answer != null) body.put("answer", answer);
+ body.put("verdict", verdict);
+ if (correction != null) body.put("correction", correction);
+ if (userRef != null) body.put("user_ref", userRef);
+ Map res = post("/rag/feedback", body);
+ return res != null ? res : Map.of("stored", false, "degraded", true);
+ } catch (Exception e) {
+ log.warn("RAG /feedback 일시 불가: {}", summarize(e));
+ return Map.of("stored", false, "degraded", true);
+ }
+ }
+
+ // ── helpers ───────────────────────────────────────────────────────────
+ @SuppressWarnings("unchecked")
+ private Map post(String path, Map body) {
+ return builder.baseUrl(props.getBaseUrl()).build()
+ .post().uri(path)
+ .header("X-Solution-Key", props.getSolution())
+ .bodyValue(body)
+ .retrieve()
+ .bodyToMono(Map.class)
+ .timeout(Duration.ofMillis(props.getTimeoutMs()))
+ .map(m -> (Map) m)
+ .block();
+ }
+
+ private Map degraded(String reason) {
+ Map out = new LinkedHashMap<>();
+ out.put("degraded", true);
+ out.put("degraded_reason", reason);
+ return out;
+ }
+
+ /** 스택트레이스 미노출: 메시지 1줄만 요약. */
+ private String summarize(Exception e) {
+ String m = e.getMessage();
+ if (m == null) return e.getClass().getSimpleName();
+ return m.length() > 160 ? m.substring(0, 160) : m;
+ }
+}
diff --git a/backend/src/main/java/com/zioinfo/cms/rag/RagCmsService.java b/backend/src/main/java/com/zioinfo/cms/rag/RagCmsService.java
new file mode 100644
index 0000000..f4e6c84
--- /dev/null
+++ b/backend/src/main/java/com/zioinfo/cms/rag/RagCmsService.java
@@ -0,0 +1,257 @@
+package com.zioinfo.cms.rag;
+
+import com.zioinfo.cms.ai.AiService;
+import com.zioinfo.cms.rag.RagToggleService.RagToggles;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * CMS 대표 AI 기능 RAG 배선 레이어(순증·비파괴, 별개 레이어).
+ *
+ *
기존 {@link AiService}(Ollama + Java 폴백)는 불변. 본 서비스는 중앙 guardia-rag 를
+ * 경유하는 별개 레이어로, 두 대표 기능을 전환한다:
+ *
+ *
contentDraft → {@code /rag/answer}(hybrid 근거+인용) 또는 tool_use 토글 시
+ * {@code /rag/agent}(다단계 콘텐츠 작업). 근거 부족 시 보류 표기.
+ * 토글 off/미가용 시 기존 {@link AiService#draft} 로 무손실 폴백(degraded:true).
+ *
moderate → {@code /rag/structured}(format:json 결정론) 판정. 애매(저신뢰) 시
+ * 자동 통과 금지 → REVIEW(hold). 토글 off/미가용 시 기존 {@link AiService#moderate}
+ * (룰 기반) 폴백(degraded:true).