architecture 전체 구조

파일 맵 — 어디를 바꾸나

deployed_code Docker 배포 권장

사전 요구사항

1. 환경변수 설정

프로젝트 루트에 .env 파일을 생성합니다. LLM 연결 정보만 필수입니다.

# .env — 최소 설정 (LLM만 필수)
LLM_BASE_URL="http://llm-server:8000/v1"        # 사내 vLLM / Ollama / Gemini
LLM_API_KEY="your-api-key"                      # API 키 (폐쇄망이면 빈 값 가능)
LLM_MODEL="Qwen/Qwen2.5-72B"                    # 사용할 모델 ID

2. 실행

# 컨테이너 시작 (백그라운드)
docker compose up -d

# 로그 확인
docker compose logs -f

# 중지
docker compose down

3. 접속 정보

기본 로그인: admin / fab-admin

데모 데이터 주입 (선택)

처음 실행하면 테이블이 비어 있습니다. 시연용 데이터를 넣으면 대시보드 KPI, 이상 목록 등을 바로 체험할 수 있습니다.

# Tool Studio 도구 import (최초 1회)
docker exec flopi-api .venv/bin/python import_seed.py --sqlite /app/data/simulator.db

# MES 시뮬레이션 데이터 + 이상탐지 이력 주입
docker exec flopi-api .venv/bin/python data_injector.py --reset

# 점진적 악화 시나리오 — 라이브 시연용 (Ctrl+C로 중지)
docker exec flopi-api .venv/bin/python data_injector.py --loop --speed 2

아키텍처

폐쇄망 배포 (오프라인)

인터넷이 차단된 FAB 폐쇄망에서는 이미지를 파일로 반입합니다.

Step 1 — 인터넷 환경에서 이미지 다운로드

GitHub Releases에서 flopi-image.tar.gz를 다운로드하거나, 직접 pull하여 저장합니다.

# 방법 A: GitHub Release에서 다운로드
# → https://github.com/donchoru/FLOPI/releases 에서 flopi-image.tar.gz 다운로드

# 방법 B: 직접 pull 후 저장
docker pull ghcr.io/donchoru/flopi:1.7.0
docker save ghcr.io/donchoru/flopi:1.7.0 | gzip > flopi-image.tar.gz

Step 2 — 폐쇄망으로 반입 후 로드

# 이미지 로드
docker load < flopi-image.tar.gz

# .env 파일 작성 (사내 LLM 연결 정보)
# → 위 "환경변수 설정" 참고

# 실행
docker compose up -d

science SQLite 시뮬레이터 모드

개발/데모용. 외부 DB 서버 없이 로컬 파일 하나로 동작합니다.

사전 요구사항 (로컬 실행)

주요 의존성 (pyproject.toml)

# 의존성 설치
uv sync

# 최초 실행 — DB 초기화 + 시뮬레이션 데이터 생성
.venv/bin/python init_db.py

# API 서버 시작 (SQLite 모드)
.venv/bin/python main.py --sqlite simulator.db --interval 60

# UI 대시보드 (별도 터미널, 기본 포트 18080)
.venv/bin/python -m ui.main

CLI 인자

작동 원리

join_inner 하이브리드 모드 — SQLite + MES Oracle

가장 간편한 사내 배포 방식. FLOPI 시스템 데이터는 SQLite에 저장하고, MES 실데이터만 Tool Studio의 Oracle 연결로 조회합니다.

장점

셋업 (4단계)

# 1. 의존성 설치
uv sync

# 2. SQLite DB 초기화 (코어 32개 테이블 + admin 계정 + 기본 도구)
.venv/bin/python init_db.py simulator.db

# 3. API 서버 시작
.venv/bin/python main.py --sqlite simulator.db --interval 300

# 4. 대시보드 시작 (별도 터미널)
.venv/bin/python -m ui.main --port 18080

MES Oracle 연결 방법

1. 대시보드 로그인 → admin / fab-admin
2. Tool Studio → DB 연결 관리 → "연결 추가"
3. 연결 정보 입력 (이름, 타입: oracle, Host/Port/SID)
4. "연결 테스트" → 성공 확인
5. 도구 생성 시 연결을 MES로 선택, SQL에 실제 MES 테이블/뷰 사용

SQLite 프로덕션 적합성

dns Oracle 운영 모드

Oracle로 전체 시스템을 운영하려는 경우입니다. 하이브리드 모드로 충분하면 이 섹션은 건너뛰세요.

# 환경변수 설정
export ORACLE_USER="fab"
export ORACLE_PASSWORD="your_password"
export ORACLE_DSN="dbhost:1521/FABPDB"

# API 서버 시작 (Oracle 모드 — --no-sqlite 플래그)
.venv/bin/python main.py --no-sqlite

# UI 대시보드 (포트 18080)
.venv/bin/python -m ui.main

storage DB 전환: SQLite → Oracle

전환 절차

1. Oracle 테이블 생성 — DB Manual DDL 순서대로 실행
2. 기본 데이터 INSERT — admin 계정, fab_tools, system_settings
3. 환경변수 설정 — ORACLE_USER, ORACLE_PASSWORD, ORACLE_DSN
4. --no-sqlite 플래그 사용하여 서버 시작
5. 규칙 seed 확인 — DB 비어있으면 rules.yaml에서 자동 seed

관련 파일

주의사항

hub 벡터 DB 전환: ChromaDB → Milvus

현재 구조

전환 절차

1. Milvus 서버 구축 — K8s 또는 standalone
2. MilvusVectorStore 구현 — BaseVectorStore 상속
3. 등록 — 서버 시작 코드에서 set_vectorstore() 호출
4. 임베딩 재생성 — 기존 문서 re-embed 필요

구현 예시

# core/rag/milvus_store.py (신규 파일)
from core.rag.vectorstore import BaseVectorStore

class MilvusVectorStore(BaseVectorStore):
    def __init__(self, host="localhost", port=19530, collection="kb_chunks"):
        from pymilvus import connections, Collection
        connections.connect(host=host, port=port)
        self.collection = Collection(collection)

    async def upsert(self, ids, embeddings, documents, metadatas):
        # pymilvus insert 구현
        ...

    async def search(self, query_embedding, top_k=5, where=None):
        # pymilvus search 구현 → [{id, document, metadata, score}] 반환
        ...

    async def delete(self, ids):
        ...

    async def count(self):
        ...

# main.py lifespan에 추가
from core.rag.vectorstore import set_vectorstore
from core.rag.milvus_store import MilvusVectorStore

set_vectorstore(MilvusVectorStore(host="milvus-host", port=19530))

관련 파일

psychology LLM 전환: Gemini → 사내 모델

FLOPI의 LLM 클라이언트는 OpenAI-compatible API를 사용합니다. vLLM, Ollama, TGI 등 OpenAI 호환 엔드포인트를 제공하는 서버라면 환경변수 3개만 바꾸면 즉시 전환됩니다.

환경변수

# .env 또는 export
export LLM_BASE_URL="http://llm-server:8000/v1"
export LLM_API_KEY="your-token"
export LLM_MODEL="Qwen/Qwen2.5-72B"

관련 파일

data_array 임베딩 전환: Gemini → 사내 모델

임베딩 모델은 LLM과 별도로 관리됩니다. 2가지 백엔드가 내장되어 있습니다:

환경변수

# 사내 임베딩 서버 전환
export RAG_EMBED_BACKEND="openai"
export RAG_EMBED_BASE_URL="http://embed-server:8080/v1"
export RAG_EMBED_API_KEY="your-token"
export RAG_EMBED_MODEL="bge-m3"

관련 파일

smart_toy AI Chat — FAB 전문 어시스턴트

Tool Studio 도구를 자동으로 활용하여 실제 FAB 데이터 기반 답변을 제공하는 SSE 스트리밍 채팅입니다.

주요 기능

API 엔드포인트

# 채팅 (SSE 스트리밍)
POST /api/ai-chat

# 세션 관리
GET  /api/ai-chat/sessions
POST /api/ai-chat/sessions
GET  /api/ai-chat/sessions/{id}
DELETE /api/ai-chat/sessions/{id}

# 도구
GET  /api/ai-chat/tools
GET  /api/ai-chat/suggested-questions

code Code Interpreter — Python 코드 실행

AI Chat에서 LLM이 생성한 Python 코드를 subprocess로 안전하게 실행합니다. 수치 분석, 통계, 차트 생성 등 데이터 기반 질문에 자동 활용됩니다.

지원 라이브러리

동작 방식

history 도구 감사 로그 & 버전 관리

Tool Studio 도구의 모든 변경사항을 추적합니다. 누가 언제 무엇을 변경했는지 기록하고, SQL/파라미터 변경 시 버전 스냅샷을 자동 저장합니다.

감사 로그

버전 스냅샷

API

GET /api/tool-studio/tools/{id}/history       # 감사 로그
GET /api/tool-studio/tools/{id}/versions      # 버전 목록
GET /api/tool-studio/tools/{id}/versions/{v}  # 특정 버전 스냅샷

cable MCP 서버 — Claude 연동

Tool Studio의 모든 활성 도구를 MCP 프로토콜(stdio)로 외부에 노출합니다. Claude Desktop, Claude Code 등에서 FAB 도구를 직접 호출할 수 있습니다.

설정 (.mcp.json)

// Claude Desktop 또는 Claude Code 설정
{
  "mcpServers": {
    "flopi": {
      "command": "uv",
      "args": ["run", "python", "mcp_server.py", "--sqlite", "simulator.db"]
    }
  }
}

특징

• 동적 도구 로딩 — DB에서 활성 도구를 실시간으로 읽어 MCP Tool로 변환
• Rate Limiting — 도구별 분당 호출 제한 적용
• 캐싱 — TTL 기반 결과 캐싱
• 결과 자르기 — 최대 200행으로 응답 크기 제한
• 쿼리 로깅 — 모든 호출 ds_query_log에 기록

tune 환경변수 총정리

checklist 운영 배포 체크리스트