이 글에서는 IFC 포맷의 BIM 데이터를 FalkorDB 그래프 데이터베이스로 변환하고, 로컬 LLM(Ollama)을 연동하여 온톨로지 모델 자연어 질의가 가능한 AI 에이전트를 구축하는 전체 과정을 기술한다. 또한, 도커(Docker) 기반의 데이터베이스 서버 구성부터 Python 의존성 설치, 데이터 적재 및 애플리케이션 실행 방법을 단계별로 정리한다. FalkorDB는 neo4j에 비해 라이센스 정책이 유연하고, 설치부터 사용이 가벼운 장점이 있다. 참고로 neo4j 기반 그래프 RAG 개발은 그래프 데이터베이스 Neo4J 기반 데이터 질의 서비스 개발하기 글을 참고한다.
본 글의 모든 실행코드는 다음 github를 참고한다.
코드 clone을 위해 다음 명령을 터미널에서 실행한다.
git clone https://github.com/mac999/LLM-RAG-Agent-Tutorial.git
개발 환경 및 전제 조건
본 시스템은 온프레미스 환경에서의 실행을 가정하며, 다음 도구, 컴포넌트들을 필요로 한다.
- Docker: 그래프 데이터베이스(FalkorDB) 실행
- Python 3.12+: 데이터 변환 및 에이전트 로직 수행
- Ollama: 로컬 LLM 추론 서버
- 하드웨어: LLM 구동을 위한 적정 수준의 GPU(NVIDIA VRAM 6GB 이상 권장)
사전 지식
온톨로지 지식 그래프 구조와 Cypher Query에 대한 사전 지식이 있다면, 아래 실습을 이해하기 용이하다. 상세한 내용은 다음을 참고한다.
FalkorDB는 Redis API 호환 고성능 그래프 데이터베이스다.
다음과 같이 터미널에서 Docker를 실행하면, FalkorDB 서버가 구동될 것이다.
docker run -p 6379:6379 -p 3000:3000 -it --rm -v ./data:/var/lib/falkordb/data -e ENCRYPTION_KEY=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef falkordb/falkordb
-p 6379:6379: FalkorDB(Redis 프로토콜) 접속 포트 바인딩. Python 클라이언트가 이 포트로 통신한다.-p 3000:3000: (옵션) FalkorDB 시각화 도구 등을 위한 포트 바인딩.-it --rm: 대화형 모드로 실행하며, 컨테이너 종료 시 자동 삭제.-v ./data:/var/lib/falkordb/data: 호스트의 ./data 디렉토리를 컨테이너 내 데이터 저장소로 마운트하여 데이터 영속성(Persistence)을 보장한다.ENCRYPTION_KEY: 이 키는 브라우저가 여러분의 데이터베이스 접속 정보(호스트, 포트, 아이디, 비밀번호 등)를 서버 측에 저장할 때 암호화하기 위해 사용. 로그인을 하면 해당 정보가.data/api_tokens.json같은 파일에 저장되는데, 이때 평문이 아닌 이 키로 암호화해서 저장. 반드시 64자. 16진수(Hexadecimal)만 허용 (최근 버전업 기능)
FalkorDB Browser (http://localhost:3000) 에 접속해 로그인한다. 참고로 로그인 user name은 default 혹은 빈칸 입력, pwd는 없다(나중에 설정 가능). 데쉬보드가 보이면, 좌측 database 추가 [+] 메뉴 클릭 후, bim 이름으로 데이터베이스를 다음 그림처럼 하나 만든다.
데이터베이스 생성
생성 후 모습
이제 IFC 파싱, 그래프 DB 연결, LLM 체인 구성을 위한 라이브러리를 pip로 터미널에서 설치한다.
pip install Plaintext falkordb langchain langchain-ollama langchain-core ifcopenshell python-dotenv streamlit
자연어를 Cypher 쿼리로 변환(Text-to-Cypher)하는 작업에는 코드 생성 능력이 뛰어난 모델이 필요하다. 본 프로젝트에서는 qwen2.5-coder:7b 모델을 사용한다.
Ollama 설치 후 아래 명령어 실행한다
자연어를 Cypher 쿼리로 변환(Text-to-Cypher)하는 작업에는 코드 생성 능력이 뛰어난 모델이 필요하다. 본 프로젝트에서는 qwen2.5-coder:7b 모델을 사용한다.
Ollama 설치 후 아래 명령어 실행한다
ollama pull qwen2.5-coder:7b
데이터베이스 연결 정보 및 그래프 네임스페이스 설정을 위해 프로젝트 루트 폴더에 .env 파일을 생성한다.
FALKORDB_HOST=localhostFALKORDB_PORT=6379FALKORDB_GRAPH=bimFALKORDB_USERNAME=defaultFALKORDB_PASSWORD=
데이터 적재 (ETL Process)
BIM 데이터(.ifc)를 그래프 구조(노드 및 엣지)로 변환하여 FalkorDB에 적재하는 과정이다.
- ifcopenshell을 이용해 IFC 엔티티 파싱.
- src.falkordb_graph_converter 모듈이 엔티티를 노드로, 관계(포함, 집합 등)로 구성된 트리플 레이블(객체-관계-행동) 속성그래프(Labeled Property Graph, LPG) 형식으로 변환.
- 속성(Property Set) 정보를 JSON 형태로 직렬화하여 노드에 저장.
이 알고리즘이 구현된 다음 소스 파일을 실행한다. 이 파일은 하위 input 폴더 내의 IFC 파일 자동 감지해 앞에서 설정한 .env 의 bim database로 속성정보를 그래프로 변환해 저장한다.
다음을 실행해 본다.
python import_ifc_to_falkordb.py
그 결과 FalkorDB 에서 질의문 실행해 확인해 보자.
다음과 같이 파싱된 IFC 데이터셋이 그래프DB로 구축된 것을 확인할 수 있다.
웹 기반 에이전트 실행
데이터 적재가 완료되면 Streamlit 기반의 웹 인터페이스를 구동하여 질의응답 시스템을 활성화한다.
CLI(Command Line Interface) 기반 에이전트 실행
CLI 기반 웹 에이전트를 다음 명령어로 실행한다.
python BIM_graph_agent_falkordb.py
이 모듈은 다음과 같은 방식으로 실행된다.
- 질의 입력: 사용자 자연어 질문 수신.
- Cypher 변환: LLM(qwen2.5-coder)이 스키마 정보를 바탕으로 질문을 Cypher 쿼리로 변환.
- 쿼리 실행: FalkorDB 엔진이 그래프 탐색 수행 후 JSON 결과 반환.
다음과 같이 질문을 해본다.
What IFC files are loaded?
List all properties of space A204
List all elements contained in A204 space
How many IfcWallStandardCase?
결과는 다음과 같다. 환각이 심한 약어, 숫자와 관련된 질의 결과도 정확히 정보를 얻어오는 것을 확인할 수 있다.
실행 결과
각 질의는 LLM에 의해 Cypher Query언어로 변환되어, FalkorDB에 전달되어 결과가 리턴된다. 이를 파싱해 보여주는 파이프라인이 수행된다. 실제 질의언어는 FalkorDB 도커 로그에서 확인할 수 있다.
FalkorDB 도커 로그
웹 기반 에이전트 실행
데이터 적재가 완료되면 Streamlit 기반의 웹 인터페이스를 구동하여 질의응답 시스템을 활성화한다.
- 질의 입력: 사용자 자연어 질문 수신.
- Cypher 변환: LLM(qwen2.5-coder)이 스키마 정보를 바탕으로 질문을 Cypher 쿼리로 변환.
- 쿼리 실행: FalkorDB 엔진이 그래프 탐색 수행 후 JSON 결과 반환.
- 답변 생성: LLM이 JSON 결과를 해석하여 자연어 답변 생성.
이제 터미널에서 다음과 같이 명령 실행해본다.
streamlit run BIM_graph_agent_web_falkordb.py
BIM 기반 AI 에이전트 실행 결과
결론
위 과정을 통해 구축된 시스템은 복잡한 BIM 데이터의 위상학적 관계를 그래프로 표현하고, 별도의 쿼리 언어 학습 없이 자연어만으로 온톨로지 건물 모델 정보를 조회할 수 있는 환경을 제공한다. FalkorDB의 빠른 인덱싱, 로컬 LLM의 보안성, vLLM과 같은 캐쉬 도구를 잘 활용하면 실무에 적용 가능한 수준의 응답 속도와 데이터 프라이버시를 확보할 수 있다.
단, 온톨로지 모델 구조인 그래프 형식 지식을 적절히 추출할 수 있는 방식은 여러가지가 될 수 있다. 에이전트로 연결하기 위해서는 적절한 템플릿, 데이터 파싱, RAG 및 데이터처리 방식 및 적절한 펑션콜(function call) 모델이 필요하고, 기능과 속도 간 트레이드오프도 고려해야 한다.
