📄 [문서]RAG 시스템에서 FunctionGemma 적용 설계 보고서

[Cassiiopeia]

FunctionGemma 기반 RAG 라우팅 시스템 설계 보고서

1. 개요

본 문서는 ROMI 서비스의 RAG(Retrieval-Augmented Generation) 시스템에
FunctionGemma(270M) 모델을 적용하여 사용자 입력을 검색 필요 여부 및 처리 경로로 분기(라우팅) 하기 위한 설계 내용을 정리한다.

핵심 목표:

• 불필요한 벡터 검색(RAG) 호출 최소화
• 시스템 요청 / 잡담 / 모호한 질문 분리
• 초경량 모델 기반 비용·지연 최소화
• RAG 이전 단계 의도 판단 정확도 향상

---

2. 문제 정의

2.1 기존 RAG 구조의 한계

• 모든 입력에 대해 무조건 벡터 DB 검색 수행
• 잡담·감정 표현·상태 확인 요청에도 검색 비용 발생
• 시스템 액션과 지식 검색을 구분하지 못함
• 검색 불필요 질문에 대한 환각(hallucination) 발생 가능

---

3. 해결 전략

3.1 핵심 아이디어

FunctionGemma를 **답변 생성 모델이 아닌 “의사결정(라우팅) 전용 모델”**로 사용한다.

FunctionGemma 특징:

• 270M 초경량 모델
• Function Calling 특화
• 단일 판단(single-turn decision)에 강점
• 빠른 응답 속도, 낮은 리소스 요구

---

4. 전체 아키텍처

4.1 처리 흐름

[User Input]
      ↓
[FunctionGemma Router]
      ↓
┌───────────────┬───────────────────┬────────────────┬─────────────────┐
│ route_rag     │ route_system       │ route_smalltalk│ route_clarify   │
│ (벡터검색)     │ (상태/로그/액션)   │ (일상대화)      │ (추가질문)      │
└───────────────┴───────────────────┴────────────────┴─────────────────┘
      ↓
[각 분기별 실제 처리 로직]
      ↓
[최종 응답 생성]

---

5. FunctionGemma 역할 정의

5.1 하지 않는 일

• 실제 검색 수행
• DB 조회
• 시스템 명령 실행
• 최종 자연어 답변 생성

5.2 수행 역할

• 사용자 의도 분류
• 처리 경로 결정
• JSON 기반 최소 정보 반환

---

6. 라우팅 설계

6.1 라우팅 함수 정의

route_rag

• 내부 문서/설정/코드 검색 필요 시
• 키워드: 어디, 위치, 설정, config, 파일, 코드

route_system

• 상태/로그/포트/프로세스 등 런타임 질의

route_smalltalk

• 인사, 감정 표현, 잡담

route_clarify

• 질문이 모호하여 추가 정보 필요 시

---

7. 동작 예시

사용자 입력

romi에서 SSE 스트리밍 설정 어디에 했지?

라우팅 결과

{
  "function": {
    "name": "route_rag",
    "arguments": {
      "query": "ROMI SSE streaming configuration location"
    }
  }
}

---

8. 기술적 고려사항

8.1 CLI 사용 불가

• ollama run functiongemma는 Function Calling 미지원
• /api/chat + tools JSON 방식 필수

8.2 Windows PowerShell 인코딩 이슈

• UTF-8 강제 필요
• 라우팅 단계에서는 query를 참고용으로만 사용 권장

---

9. 장점 요약

• 성능: 빠른 응답, 검색 비용 절감
• 안정성: 환각 감소
• 확장성: Agent 구조로 확장 가능

---

10. 결론

FunctionGemma는 RAG 시스템의 첫 관문(Gatekeeper)이다.

“FunctionGemma는 답변을 만드는 모델이 아니라,
RAG를 사용할지 말지를 결정하는 모델이다.”

🙋‍♂️ 담당자

• 백엔드: @Cassiiopeia
• 프론트엔드: 이름
• 디자인: 이름

[github-actions]

Chuseok22 Issue Helper

브랜치명

20251223_#8_RAG_시스템에서_FunctionGemma_적용_설계_보고서

커밋 메시지

RAG_시스템에서_FunctionGemma_적용_설계_보고서 : feat : {변경 사항에 대한 설명} https://github.com/Team-Romi/romi-chatbot/issues/8

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• 📄 [문서][UI/UX] ROMI 챗봇 사용자 흐름 설계 #7

👤 Suggested Assignees

• Cassiiopeia

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord or schedule a call!

[Cassiiopeia]

다음 URL 참고 필요

• https://ollama.com/library/functiongemma

[Cassiiopeia]

FunctionGemma + RAG 라우터 사용 예시 (PowerShell 실습 + Python 서버 적용)

이 문서는 **FunctionGemma를 RAG “게이트키퍼(라우터)”**로 쓰는 실제 사용 예시를 정리합니다.

• ✅ PowerShell에서 Ollama /api/chat + tools로 라우팅이 실제로 동작하는 것까지 확인함
• ✅ 다음 단계는 Python 서버에서 동일한 흐름을 코드로 고정하는 것

---

0) 전제 조건

• Ollama 실행 중 (기본: http://localhost:11434)
• 모델 설치:

  ollama pull functiongemma

ollama run functiongemma (CLI 대화)는 툴콜링 실습용으로 적합하지 않습니다.
반드시 /api/chat에 tools를 포함해서 호출해야 tool_calls가 나옵니다.

---

1) PowerShell 실습: “라우팅 전용 tools 4개”로 분기 확인

아래 스크립트는 딱 1개 tool call만 선택하도록 강제합니다.

1.1 라우팅 요청 실행

$body = @{
  model  = "functiongemma"
  stream = $false
  messages = @(
    @{ role="system"; content=@"
You are a strict router. You MUST choose exactly ONE tool call and NEVER answer with normal text.

Routing rules:
- If the user asks WHERE a setting/config/code is (keywords: ""어디"", ""위치"", ""설정"", ""config"", ""파일"", ""코드"", ""어디에 했지"") -> route_rag.
- If the user asks about runtime health/status/logs/ports/processes (keywords: ""죽었나"", ""상태"", ""로그"", ""포트"", ""프로세스"", ""느려"") -> route_system.
- If it's chit-chat/emotions/greetings -> route_smalltalk.
- If ambiguous -> route_clarify.
"@ }
    @{ role="user"; content="romi에서 SSE 스트리밍 설정 어디에 했지?" }
  )
  tools = @(
    @{
      type="function"
      function=@{
        name="route_smalltalk"
        description="Casual conversation only."
        parameters=@{
          type="object"
          properties=@{ text=@{type="string"} }
          required=@("text")
          additionalProperties=$false
        }
      }
    },
    @{
      type="function"
      function=@{
        name="route_rag"
        description="Use when user asks where/what/how about ROMI internal config, docs, or code. Especially '설정 위치/어디/파일'."
        parameters=@{
          type="object"
          properties=@{ query=@{type="string"} }
          required=@("query")
          additionalProperties=$false
        }
      }
    },
    @{
      type="function"
      function=@{
        name="route_system"
        description="Use ONLY for runtime checks/actions: status, logs, port, process."
        parameters=@{
          type="object"
          properties=@{
            action=@{type="string"; enum=@("get_status","get_logs","check_port","list_processes")}
            args=@{type="object"}
          }
          required=@("action")
          additionalProperties=$false
        }
      }
    },
    @{
      type="function"
      function=@{
        name="route_clarify"
        description="Ask ONE clarification question."
        parameters=@{
          type="object"
          properties=@{ question=@{type="string"} }
          required=@("question")
          additionalProperties=$false
        }
      }
    }
  )
} | ConvertTo-Json -Depth 30

$r = Invoke-RestMethod -Uri "http://localhost:11434/api/chat" -Method Post -ContentType "application/json" -Body $body
$r.message.tool_calls | ConvertTo-Json -Depth 20

1.2 기대 결과 (예)

• 설정/위치 질문 → route_rag
• 상태/로그 질문 → route_system
• 잡담 → route_smalltalk
• 애매하면 → route_clarify

예:

{
  "function": {
    "name": "route_rag",
    "arguments": { "query": "ROMI SSE streaming configuration location" }
  }
}

💡 Windows 콘솔 인코딩에 따라 query의 한글이 ?로 깨질 수 있습니다.
실무에서는 query를 참고용으로만 쓰고, 실제 검색 질의는 원문(user text)을 그대로 임베딩하는 게 제일 안정적입니다.

---

2) Python 서버 적용: “라우팅 → (필요시) RAG → 응답” 최소 구현

아래 예시는 FastAPI 기준입니다. (Flask로 바꿔도 핵심은 동일)

2.1 설치

pip install fastapi uvicorn requests

2.2 서버 코드 (app.py)

from __future__ import annotations

from typing import Any, Dict, List, Optional, Literal, Tuple
import requests
from fastapi import FastAPI
from pydantic import BaseModel

OLLAMA_HOST = "http://localhost:11434"
MODEL = "functiongemma"

app = FastAPI(title="ROMI Router (FunctionGemma)")

# ----------------------------
# 요청/응답 스키마
# ----------------------------
class ChatIn(BaseModel):
    text: str


class RouteOut(BaseModel):
    route: Literal["rag", "system", "smalltalk", "clarify"]
    tool_name: str
    arguments: Dict[str, Any]


# ----------------------------
# 1) FunctionGemma Router 호출
# ----------------------------
def route_with_functiongemma(user_text: str) -> RouteOut:
    tools = [
        {
            "type": "function",
            "function": {
                "name": "route_smalltalk",
                "description": "Casual conversation only.",
                "parameters": {
                    "type": "object",
                    "properties": {"text": {"type": "string"}},
                    "required": ["text"],
                    "additionalProperties": False,
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "route_rag",
                "description": "Use when user asks where/what/how about ROMI internal config, docs, or code.",
                "parameters": {
                    "type": "object",
                    "properties": {"query": {"type": "string"}},
                    "required": ["query"],
                    "additionalProperties": False,
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "route_system",
                "description": "Use ONLY for runtime checks/actions: status, logs, port, process.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "action": {
                            "type": "string",
                            "enum": ["get_status", "get_logs", "check_port", "list_processes"],
                        },
                        "args": {"type": "object"},
                    },
                    "required": ["action"],
                    "additionalProperties": False,
                },
            },
        },
        {
            "type": "function",
            "function": {
                "name": "route_clarify",
                "description": "Ask ONE clarification question.",
                "parameters": {
                    "type": "object",
                    "properties": {"question": {"type": "string"}},
                    "required": ["question"],
                    "additionalProperties": False,
                },
            },
        },
    ]

    system_msg = (
        "You are a strict router. Choose exactly ONE tool call and NEVER answer with normal text.\n"
        "Rules:\n"
        "- WHERE/위치/설정/config/파일/코드/어디에 했지 -> route_rag\n"
        "- 상태/로그/포트/프로세스/느려/죽었나 -> route_system\n"
        "- 잡담/감정/인사 -> route_smalltalk\n"
        "- 애매하면 -> route_clarify\n"
    )

    payload = {
        "model": MODEL,
        "stream": False,
        "messages": [
            {"role": "system", "content": system_msg},
            {"role": "user", "content": user_text},
        ],
        "tools": tools,
    }

    res = requests.post(f"{OLLAMA_HOST}/api/chat", json=payload, timeout=60)
    res.raise_for_status()
    data = res.json()

    tool_calls = (data.get("message") or {}).get("tool_calls") or []
    if not tool_calls:
        # 라우터가 실패한 경우: 안전하게 clarify로 처리
        return RouteOut(route="clarify", tool_name="route_clarify", arguments={"question": "질문을 조금 더 구체적으로 말해줘."})

    call = tool_calls[0]
    fn = call.get("function", {})
    name = fn.get("name", "")
    args = fn.get("arguments", {}) or {}

    if name == "route_rag":
        route = "rag"
    elif name == "route_system":
        route = "system"
    elif name == "route_smalltalk":
        route = "smalltalk"
    else:
        route = "clarify"

    return RouteOut(route=route, tool_name=name, arguments=args)


# ----------------------------
# 2) RAG / System 처리 (샘플)
# ----------------------------
def rag_search(user_text: str) -> str:
    # TODO: 여기에 Qdrant/Elastic/로컬문서 검색을 연결
    # NOTE: 여기서는 예시로 더미 결과 반환
    return (
        "[RAG 결과 예시]\n"
        "- docs/romi/streaming.md 에 SSE 설정 섹션이 있음\n"
        "- reverse proxy는 WebSocket 필요 시 'WebSocket 활성화' 체크\n"
    )


def system_action(action: str, args: Optional[Dict[str, Any]]) -> str:
    args = args or {}
    # TODO: 실제 상태조회/로그조회/포트확인 로직을 연결
    return f"[SYSTEM 결과 예시]\n- action={action}\n- args={args}"


# ----------------------------
# 3) 최종 응답 생성 전략
# ----------------------------
def make_final_answer(route: RouteOut, user_text: str) -> str:
    if route.route == "smalltalk":
        # 간단 응답(또는 별도 대화모델로 위임)
        return "오케이 🙂 무슨 일 있었어? 요즘 컨디션 어때?"

    if route.route == "clarify":
        return route.arguments.get("question", "조금만 더 구체적으로 말해줘.")

    if route.route == "system":
        result = system_action(route.arguments.get("action", "get_status"), route.arguments.get("args"))
        return f"시스템 요청으로 판단했어.\n\n{result}"

    # route == "rag"
    # NOTE: query는 참고용, 실 검색은 user_text로 하는 게 안정적
    retrieved = rag_search(user_text)
    return f"설정/문서 검색이 필요해 보여서 RAG로 처리할게.\n\n{retrieved}"


# ----------------------------
# API 엔드포인트
# ----------------------------
@app.post("/chat", response_model=dict)
def chat(payload: ChatIn):
    route = route_with_functiongemma(payload.text)
    answer = make_final_answer(route, payload.text)
    return {"route": route.model_dump(), "answer": answer}

2.3 실행

uvicorn app:app --reload --port 8083

2.4 테스트 (PowerShell)

Invoke-RestMethod -Uri "http://localhost:8083/chat" -Method Post -ContentType "application/json" -Body '{"text":"romi에서 SSE 스트리밍 설정 어디에 했지?"}'

---

3) 실전 운영 팁 (중요)

3.1 라우팅 단계에서 query를 “참고용”으로만 쓰기

• Windows/콘솔/인코딩 이슈로 문자열이 깨질 수 있음
• 실제 벡터 검색은 user_text 원문 그대로 임베딩하는 방식이 가장 안정적

3.2 tool 스키마를 빡세게 잠그기

• additionalProperties: false
• enum으로 action 제한
  → 모델이 result, index 같은 엉뚱한 키를 arguments에 넣는 걸 줄임

3.3 도구 수는 적을수록 정확함 (270M 기준)

• 3~6개 추천
• “큰 분기(라우팅)”에 최적화해 쓰기

---

4) 다음 확장 (선택)

• route_rag를 더 쪼개기: route_rag_docs / route_rag_code / route_rag_logs
• route_system에 승인(confirmation) 단계 추가 (위험 액션 방지)
• Router → Planner → Executor 형태의 Agent 구조로 확장

---

5) 체크리스트

• Invoke-RestMethod로 tool_calls 정상 출력되는가?
• 라우팅이 route_rag/system/smalltalk/clarify 중 하나로 안정적으로 떨어지는가?
• 서버에서 route에 따라 RAG/시스템/잡담 처리를 분기하는가?
• 실제 검색은 원문 기반으로 수행하는가?

---

끝.