GraphNode AI

대화 데이터를 분석하여 지식 그래프(Knowledge Graph)를 생성하는 AI 파이프라인 서버.

---

폴더 구조

GraphNode_AI/
├── server/                          # FastAPI 서버 + SQS 워커
│   ├── main.py                      # HTTP 엔드포인트 (로컬 테스트용)
│   └── worker.py                    # SQS 워커 (배포 환경 비동기 처리)
│
├── add_node/                        # 기존 그래프에 대화 노드 추가 파이프라인
│   ├── analyze/                     # Q-A 파싱 (MongoDB messages[] 포맷 지원)
│   ├── steps/                       # 파이프라인 단계 모듈
│   │   ├── build_qa_pairs.py        # Step 1: Q-A 쌍 추출
│   │   ├── extract_qa_keywords.py   # Step 2: 키워드 + 임베딩 추출
│   │   ├── cluster_qa.py            # Step 3: Q-A 클러스터링 (HDBSCAN, 선택적)
│   │   ├── pool_qa_embeddings.py    # Step 4: 대화 임베딩 풀링
│   │   ├── assign_cluster_llm.py    # Step 5: LLM으로 클러스터 할당
│   │   └── create_edges.py          # Step 7: 엣지 생성
│   ├── utils/                       # 프롬프트 빌더, 로거 등
│   ├── config.py                    # 파이프라인 설정 (env 기반)
│   └── call.py                      # 진입점 (단일/배치 파이프라인 함수)
│
├── macro/                           # 전체 그래프 생성 파이프라인
│   ├── src/
│   │   ├── run_pipeline.py          # 파이프라인 실행 스크립트
│   │   └── insights/
│   │       └── storage/indexer.py   # EmbeddingIndexer (macro_node 컬렉션 인덱싱)
│   └── config.yaml
│
├── microscope/                      # RAG 기반 문서 인제스트 / 질의 파이프라인
│   ├── call.py                      # 파일 인제스트 진입점
│   ├── services/rag_service.py      # 질의·합성·관련질문 서비스
│   └── microscope_config.py         # 설정 로더
│
├── infra/                           # 데이터베이스 접근 계층
│   └── repositories/
│       ├── graph/
│       │   └── graphnode_repository.py  # GraphNodeDBHandler (싱글톤, 서버 시작 시 초기화)
│       ├── neo4j/                       # Neo4j 저장소
│       └── vectordb/
│           ├── macro_node_store.py      # MacroNodeStore (ChromaDB 'macro_node' 컬렉션)
│           └── chunks_store.py          # 문서 청크 벡터 저장소
│
├── dto/                             # 데이터 전송 객체 (Pydantic)
│   ├── server_dto.py                # HTTP/SQS 요청·응답 스키마 전체
│   └── microscope_dto.py            # microscope 전용 DTO
│
├── shared/                          # 공통 유틸리티
│   ├── env_loader.py                # .env 단일 로드 (load_root_env)
│   └── api_provider.py              # ApiProvider — LLM provider/model/key 캡슐화
│
├── tests/
│   └── add_node/
│       ├── test_http.py             # HTTP E2E 테스트 (/add-node/batch)
│       └── test_sqs.py              # SQS E2E 테스트 (S3 업로드 → SQS 전송 → 결과 폴링)
│
├── input_data/
│   └── add_node/mock_data.json      # add_node 배치 테스트용 목 데이터
├── output_data/                     # 파이프라인 결과 저장
├── docs/                            # 작업 문서
│   └── work-architecture-refactoring.md
├── .env                             # 환경변수 (gitignore)
├── .env.example                     # 환경변수 예시
├── requirements.txt
└── Dockerfile

---

아키텍처 개요

핵심 설계 원칙

계층	역할	파일
DTO	요청/응답 스키마 정의 (Pydantic)	dto/server_dto.py
Repository	DB 접근 추상화 (싱글톤)	infra/repositories/
ApiProvider	LLM API 캡슐화 (provider/model/key)	shared/api_provider.py
Pipeline	순수 비즈니스 로직 (call.py)	add_node/, macro/, microscope/
Server	HTTP 진입점 (로컬 테스트)	server/main.py
Worker	SQS 진입점 (배포 환경)	server/worker.py

DB 초기화 (싱글톤)

# server/main.py (서버 시작 시 한 번만 실행)
graphnode_db_handler = GraphNodeDBHandler(config=microscope_config)
# .macro_node_store  → ChromaDB 'macro_node' 컬렉션
# .graph_db          → Neo4j
# .vector_db         → ChromaDB 청크 저장소

모든 엔드포인트와 워커는 동일한 graphnode_db_handler 인스턴스를 공유합니다.

ApiProvider — 요청별 LLM 오버라이드

# 기본 provider (서버 시작 시 설정)
rag_api_provider = ApiProvider(provider="openai", model="gpt-4o-mini", ...)

# 요청에 provider/api_key 포함 시 override
provider = _build_api_provider(req)  # 요청 필드 우선, 없으면 기본값

지원 provider: openai | z.ai | groq

환경변수

# 모든 모듈은 이 한 줄로 .env 로드
from shared.env_loader import load_root_env
load_root_env()

.env 파일은 프로젝트 루트에 하나만 존재합니다. .env.example을 참고하시고 실제 값은 관리자에게 문의

---

환경 설정

Python 3.11+ 필요

pip install -r requirements.txt
cp .env.example .env
# .env 수정 — Neo4j, ChromaDB, LLM API 키, AWS 설정 입력

---

서버 실행

# 로컬 개발 서버
uvicorn server.main:app --host 127.0.0.1 --port 8000 --reload

# SQS 워커 (로컬 실행 — 배포 환경에서는 ECS가 자동 실행)
python server/worker.py

---

API 엔드포인트

메서드	경로	설명
GET	/health	헬스체크
POST	/microscope/ingest	파일 인제스트 (멀티파트)
POST	/microscope/query	지식 그래프 질의
POST	/microscope/synthesize	주제 기반 합성
POST	/microscope/related-questions	관련 질문 생성
POST	/macro/graph-generation	전체 그래프 생성 (멀티파트)
POST	/add-node/batch	대화 노드 배치 추가 (JSON 바디)

---