Feat: RAG기반 금융용어 설명 기능 추가

Author: psb3707

.claude/worktrees/awesome-payne

@@ -0,0 +1 @@
+Subproject commit d414178b6fce81607eb966fd8434c1392624fc34

docker-compose.yml

@@ -24,11 +24,17 @@ services:
       dockerfile: Dockerfile
     env_file:
       - .env
+    environment:
+      # 컨테이너 내부에서는 서비스명으로 접근
+      - MONGO_URI=mongodb://mongodb:27017
+      - REDIS_HOST=redis
+      - CHROMA_HOST=chromadb
     ports:
       - "8000:8000"
     depends_on:
       - mongodb
       - redis
+      - chromadb
     restart: unless-stopped
 
   # 백그라운드 워커1 (기사 요약)
@@ -39,6 +45,9 @@ services:
     command: python -m app.services.queue.worker
     env_file:
       - .env
+    environment:
+      - MONGO_URI=mongodb://mongodb:27017
+      - REDIS_HOST=redis
     depends_on:
       - mongodb
       - redis
@@ -52,6 +61,9 @@ services:
     command: python -m app.services.recommend_queue.worker
     env_file:
       - .env
+    environment:
+      - MONGO_URI=mongodb://mongodb:27017
+      - REDIS_HOST=redis
     depends_on:
       - mongodb
       - redis
@@ -65,10 +77,23 @@ services:
     command: python -m app.services.keyword_queue.worker
     env_file:
       - .env
+    environment:
+      - MONGO_URI=mongodb://mongodb:27017
+      - REDIS_HOST=redis
     depends_on:
       - mongodb
       - redis
     restart: unless-stopped
 
+  # 벡터 DB (RAG)
+  chromadb:
+    image: chromadb/chroma:latest
+    ports:
+      - "8001:8000"
+    volumes:
+      - chroma_data:/chroma/chroma
+    restart: unless-stopped
+
 volumes:
   mongodb_data:
+  chroma_data:

econoeasy/app/core/config.py

@@ -64,6 +64,14 @@ class Settings(BaseSettings):
     REDIS_KEYWORD_CONSUMER_GROUP: str = "article-keyword-request-processors"
     REDIS_KEYWORD_CONSUMER_NAME: str = "article-keyword-request-worker-1"
 
+    # RAG 설정
+    EMBEDDING_MODEL: str = "models/text-embedding-004"
+    CHROMA_HOST: str = "localhost"
+    CHROMA_PORT: int = 8001
+    CHROMA_COLLECTION_NAME: str = "econoeasy_articles"
+    RAG_TOP_K: int = 5
+    RAG_MIN_SCORE: float = 0.4
+
     model_config = SettingsConfigDict(
         env_file=str(ENV_FILE),
         env_file_encoding="utf-8",

econoeasy/app/main.py

@@ -3,6 +3,7 @@
 from .core.config import settings
 from .routers import summarize, recommend
 from .routers import quiz, keyword
+from .routers import rag
 from .services.queue.mongodb_client import mongodb_client
 
 
@@ -24,6 +25,7 @@
 app.include_router(recommend.router)
 app.include_router(quiz.router)
 app.include_router(keyword.router)
+app.include_router(rag.router)
 
 # MongoDB 라이프사이클 이벤트
 @app.on_event("startup")

econoeasy/app/models/schemas.py

@@ -231,7 +231,18 @@ class KeywordStockResponse(BaseModel):
 
 class TermDefineRequest(BaseModel):
     term: str
+    article_content: Optional[str] = None
+
 
 class TermDefineResponse(BaseModel):
     term: str
     definition: str
+
+
+class EnrichedTermDefineResponse(BaseModel):
+    """RAG 기반 용어 설명 응답 (정의 + 기사 맥락 + 최근 동향)."""
+    term: str
+    definition: str
+    article_context: Optional[str] = None
+    recent_trend: Optional[str] = None
+    sources: List[Dict[str, Any]] = []

econoeasy/app/routers/keyword.py

@@ -1,16 +1,22 @@
 from fastapi import APIRouter, HTTPException
-from ..models.schemas import ArticleInput, KeywordTermsResponse, KeywordStockResponse, TermDefineRequest, TermDefineResponse
+from ..models.schemas import (
+    ArticleInput, KeywordTermsResponse, KeywordStockResponse,
+    TermDefineRequest, EnrichedTermDefineResponse,
+)
 from ..services.keyword.service import keyword_service
+from ..services.keyword.term_definition_service import term_definition_service
 
 router = APIRouter(prefix="/keyword", tags=["keyword"])
 
+
 @router.post("/terms", response_model=KeywordTermsResponse)
 async def get_related_terms(article: ArticleInput):
     try:
         return await keyword_service.extract_related_terms(article)
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
+
 @router.post("/stock_id", response_model=KeywordStockResponse)
 async def get_related_stocks(article: ArticleInput):
     try:
@@ -19,10 +25,16 @@ async def get_related_stocks(article: ArticleInput):
         raise HTTPException(status_code=500, detail=str(e))
 
 
-@router.post("/define", response_model=TermDefineResponse)
+@router.post("/define", response_model=EnrichedTermDefineResponse)
 async def define_term(payload: TermDefineRequest):
+    """용어 정의 + 기사 맥락 + 최근 뉴스 동향을 한 번에 반환한다."""
     try:
-        return await keyword_service.define_term(payload.term)
+        return await term_definition_service.define_term(
+            term=payload.term,
+            article_content=payload.article_content,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 

econoeasy/app/routers/rag.py

@@ -0,0 +1,55 @@
+"""
+[구현 의도]
+HTTP 요청/응답 변환만 담당한다.
+비즈니스 로직은 전부 RAGService에 위임.
+ValueError → 400, RAGServiceError → 500으로 매핑.
+"""
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+from ..services.rag.rag_service import rag_service, RAGServiceError
+
+router = APIRouter(prefix="/rag", tags=["rag"])
+
+
+class AskRequest(BaseModel):
+    question: str
+
+
+class IndexRequest(BaseModel):
+    article_id: str
+    title: str
+    content: str
+    published_at: str
+    url: str
+
+
+@router.post("/ask")
+async def ask(request: AskRequest):
+    """경제 뉴스 기사를 근거로 질문에 답변한다."""
+    try:
+        return await rag_service.ask(request.question)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except RAGServiceError as e:
+        raise HTTPException(status_code=500, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"처리 중 오류: {str(e)}")
+
+
+@router.post("/index")
+async def index_article(request: IndexRequest):
+    """단일 기사를 RAG 검색 인덱스에 추가한다."""
+    try:
+        await rag_service.index_article(
+            article_id=request.article_id,
+            title=request.title,
+            content=request.content,
+            published_at=request.published_at,
+            url=request.url,
+        )
+        return {"status": "ok", "article_id": request.article_id}
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=f"인덱싱 오류: {str(e)}")

econoeasy/app/services/keyword/term_definition_prompts.py

@@ -0,0 +1,79 @@
+"""
+[구현 의도]
+세 가지 설명을 단일 LLM 호출로 생성한다.
+  1. definition      : 용어의 일반적 정의
+  2. article_context : 사용자가 읽는 기사에서 이 용어가 쓰인 맥락 (기사 있을 때만)
+  3. recent_trend    : 최근 뉴스 기사들에서 이 용어의 동향 (ChromaDB 결과 있을 때만)
+
+항목이 없을 때 null을 반환하도록 프롬프트에 명시한다.
+"""
+
+
+class TermDefinitionPrompts:
+
+    _BASE = """당신은 경제/금융 전문 설명가입니다.
+아래 지시에 따라 용어를 설명하고, 반드시 JSON 형식으로만 응답하세요.
+
+용어: "{term}"
+
+{article_section}{trend_section}
+다음 JSON 형식으로 응답하세요:
+{{
+  "definition": "이 용어의 일반적인 정의 (2-3문장, 비전문가도 이해할 수 있게)",
+  "article_context": {article_context_instruction},
+  "recent_trend": {recent_trend_instruction}
+}}"""
+
+    _ARTICLE_SECTION = """[사용자가 읽고 있는 기사]
+{article_content}
+
+"""
+
+    _TREND_SECTION = """[최근 관련 뉴스 기사들]
+{trend_context}
+
+"""
+
+    @classmethod
+    def build(
+        cls,
+        term: str,
+        article_content: str | None,
+        trend_docs: list[dict],
+    ) -> str:
+        article_section = ""
+        article_context_instruction = "null"
+
+        if article_content and article_content.strip():
+            article_section = cls._ARTICLE_SECTION.format(
+                article_content=article_content[:3000]
+            )
+            article_context_instruction = (
+                '"위 기사에서 이 용어가 어떤 역할/맥락으로 사용되었는지 2문장으로 설명"'
+            )
+
+        trend_section = ""
+        recent_trend_instruction = "null"
+
+        if trend_docs:
+            trend_lines = []
+            for i, doc in enumerate(trend_docs, 1):
+                meta = doc.get("metadata", {})
+                title = meta.get("title", "")
+                published = meta.get("publishedAt", "")
+                text = doc.get("text", "")[:500]
+                trend_lines.append(f"[기사{i}] {title} ({published})\n{text}")
+            trend_section = cls._TREND_SECTION.format(
+                trend_context="\n\n".join(trend_lines)
+            )
+            recent_trend_instruction = (
+                '"위 최근 기사들을 바탕으로, 현재 이 용어와 관련된 뉴스 동향을 2-3문장으로 설명"'
+            )
+
+        return cls._BASE.format(
+            term=term,
+            article_section=article_section,
+            trend_section=trend_section,
+            article_context_instruction=article_context_instruction,
+            recent_trend_instruction=recent_trend_instruction,
+        )