> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloosphere.ai/llms.txt > Use this file to discover all available pages before exploring further. # 지식 그래프 > 용어집·데이터베이스·문서를 하나의 그래프로 연결하여 AI 에이전트의 이해력을 높이는 통합 지식 구조 ## 개요 지식 그래프(Knowledge Graph)는 **용어집·데이터베이스·지식기반**을 하나의 그래프로 연결한 통합 지식 구조입니다. AI 에이전트가 비즈니스 용어가 어떤 테이블 컬럼에 대응되는지, 어떤 문서 맥락과 관련 있는지를 자동으로 이해할 수 있게 해줍니다. ### 지식 그래프가 해결하는 문제 용어집·데이터베이스·지식기반을 각각 따로 쓰면 에이전트가 **의미를 연결하지 못합니다.** | 구성만 사용했을 때 | 한계 | | :------------ | :-------------------------------------- | | 용어집만 | "VIP 고객"이 뭔지는 알지만 어느 테이블에 있는지 모름 | | 데이터베이스만 | 테이블 구조는 알지만 "VIP"가 `tier='VIP'` 필터임을 모름 | | 지식기반만 | 문서 내용은 찾지만 실제 데이터로 연결 못 함 | | **지식 그래프 사용** | **용어 → 컬럼/필터 → 관련 문서까지 한 번에 연결** | ### 활용 예시 ``` 사용자: 강남지점 VIP 고객이 가장 많이 산 제품 TOP 3는? 에이전트 동작: 1. resolve_term("VIP 고객") → users.tier = 'VIP' 매핑 발견 2. resolve_term("강남지점") → stores.region = '강남' 매핑 발견 3. find_related_tables("users") → orders, products 테이블 연결 발견 4. SQL 자동 생성 후 실행 응답: 강남지점 VIP 고객 매출 TOP 3입니다: 1. 무선 이어폰 Pro — 1,523건 2. 스마트워치 X — 1,287건 3. 노이즈캔슬링 헤드폰 — 892건 ``` ### 세 가지 정보원 ```mermaid theme={null} flowchart LR G["용어집\nGlossary"] --> KG["지식 그래프\nKnowledge Graph"] D["데이터베이스\nDbSphere"] --> KG K["지식기반\nKnowledge Base"] --> KG KG --> A["에이전트"] ``` | 정보원 | 담는 내용 | 지식 그래프에서의 역할 | | :--------- | :---------------------------- | :------------------------------ | | **용어집** | 비즈니스 용어 정의 (VIP, MRR, 강남지점 등) | Term / Concept 노드 + 동의어·카테고리 엣지 | | **데이터베이스** | 테이블/컬럼 스키마 + FK 관계 | Table / Column 노드 + 구조 엣지 | | **지식기반** | 규정, 전략, 매뉴얼 등 문서 | Doc Entity 노드 + LLM 추출 관계 엣지 | *** ## 지식 그래프 생성 **워크스페이스 → 지식 그래프** 목록에서 **"+ 새 지식 그래프"** 클릭 지식 그래프 목록

| 필드 | 설명 | 예시 | | :----- | :--------------------- | :---------------- | | **이름** | 지식 그래프 식별 이름 (최대 200자) | "전사 지식 그래프" | | **설명** | 용도와 목표 설명 | "매출/고객/상품 통합 분석용" | 접근 제어 옵션을 통해 읽기/쓰기 권한을 그룹·조직·사용자 단위로 설정할 수 있습니다. 생성 완료 후 자동으로 지식 그래프 상세 페이지로 이동합니다. 이제 정보원을 연결할 차례입니다. *** ## 지식 그래프 상세 페이지

지식 그래프 상세 페이지는 **왼쪽 노드 목록**과 **오른쪽 설정/탐색 영역**으로 구성됩니다. ### 통계 카드 상단에 3개의 통계 카드가 표시됩니다. | 항목 | 의미 | | :---------- | :----------- | | **노드** | 그래프 내 총 노드 수 | | **엣지** | 그래프 내 총 엣지 수 | | **마지막 동기화** | 마지막 동기화 시점 | ### LLM 모델 설정 카드 영역 우측 하단의 **"LLM 모델"** 드롭다운 메뉴를 통해 지식 그래프 생성에 사용할 LLM 모델을 선택합니다. 카테고리 정의 생성, 지식기반 문서 매칭, AI 도구 설명 자동 생성 등에 사용됩니다. *** ## 지식 연결 (Knowledge Link) 지식 연결은 지식 그래프의 핵심 구조입니다. **용어집 1개 + 지식기반 N개**를 하나의 링크로 묶어, 용어와 문서 간 의미를 자동으로 연결합니다. ### 연결 구조 ```mermaid theme={null} flowchart TB subgraph Link["지식 연결"] GL["용어집\n(Source)"] KB1["지식기반 1"] KB2["지식기반 2"] end GL --> |"용어 노드 생성"| KG["지식 그래프\nKnowledge Graph"] GL -.-> |"추출 출처 참조"| DB["DB 스키마\n자동 포함"] DB --> |"테이블/컬럼 노드"| KG KB1 --> |"LLM 엔티티 추출"| KG KB2 --> |"LLM 엔티티 추출"| KG ``` 용어집에 카테고리의 **추출 출처**(extraction sources)가 설정되어 있으면, 해당 DB 스키마가 지식 연결에 자동으로 포함됩니다. 별도로 DB를 추가할 필요가 없습니다. ### 연결 추가 지식 그래프 상세 페이지의 **지식 연결** 섹션에서 **"+ 지식 연결 추가"** 버튼을 클릭 연결할 용어집을 선택합니다. 이미 연결된 용어집은 목록에서 제외됩니다. 체크박스로 **이 지식 연결에 실제로 동기화할 소스**를 선택합니다. 자동 감지된 후보 중 일부만 선택하거나 추가로 연결할 수 있습니다. | 소스 | 효과 | | ---------- | ------------------------------------ | | **데이터베이스** | 선택한 DB의 테이블·컬럼·외래키가 그래프 노드로 추출됩니다 | | **지식기반** | 선택한 지식기반의 문서 청크에서 LLM이 엔티티·관계를 추출합니다 | 체크하지 않은 소스는 자동 감지되어도 **이번 지식 연결에 포함되지 않습니다**. 이전 버전과 달리 자동 강제 연결되지 않으므로, 필요한 소스만 명시적으로 선택해 동기화 비용·시간을 제어할 수 있습니다. 지식기반을 선택했다면, 그 지식기반의 동적 필터(부서/연도/문서 유형 등)를 지식 그래프 노드로 승격할지 선택할 수 있습니다. 자세한 동작은 아래 [지식기반 필터를 지식 그래프 노드로 승격](#지식기반-필터를-지식-그래프-노드로-승격) 섹션을 참조하세요. 생성 후 **"엔티티 동기화"** 버튼으로 해당 링크를 동기화합니다. 선택한 데이터베이스·지식기반만 처리되며, 동기화 대상 목록도 자동으로 갱신됩니다. ### 연결이 만드는 노드와 엣지 | 원본 | 생성되는 노드 | 연결 엣지 | | :-------------- | :----------- | :---------------- | | 각 용어 (entry) | `Term` 노드 | — | | 동의어 | — | `synonym_of` 엣지 | | 카테고리 | `Concept` 노드 | `broader_than` 엣지 | | 카테고리 → DB 컬럼 매핑 | — | `maps_to` 엣지 | LLM 호출 없이 구조 변환만 수행하므로 빠르게 완료됩니다. | 원본 | 생성되는 노드 | 연결 엣지 | | :--- | :---------- | :---------------------- | | 테이블 | `Table` 노드 | — | | 컬럼 | `Column` 노드 | `belongs_to` (컬럼 → 테이블) | | 외래 키 | — | `foreign_key` 엣지 | DB 스키마 노드를 생성하려면 **DbSphere에서 스키마 추출을 먼저 실행**해야 합니다. 미실행 시 노드가 0개로 표시됩니다. | 원본 | 생성되는 노드 | 연결 엣지 | | :------------------ | :----------------- | :-------------------- | | 문서 청크 내 엔티티 | `Doc Entity` 노드 | LLM이 추출한 관계 엣지 | | 지식기반 필터 값 (선택한 슬롯만) | `Doc Attribute` 노드 | 필터 이름 엣지 (문서 → 속성 노드) | `Doc Entity`는 LLM이 각 문서 청크를 분석해 엔티티/관계를 추출한 결과입니다. `Doc Attribute`는 지식기반 필터 값을 그대로 그래프에 올리는 LLM 미사용 경로로, 후술하는 [지식기반 필터를 지식 그래프 노드로 승격](#지식기반-필터를-지식-그래프-노드로-승격) 섹션을 참조하세요. `Doc Entity` 추출은 **LLM 호출 비용이 발생**합니다. 필요한 지식기반만 선택적으로 연결하세요. `Doc Attribute`는 LLM을 호출하지 않으므로 비용이 들지 않습니다. ### 지식기반 필터를 지식 그래프 노드로 승격 지식기반에 정의된 필터 값(국가, 카테고리, 부서 등)을 그대로 그래프 노드로 올려 검색·탐색·에이전트 라우팅에 활용할 수 있습니다. **LLM을 호출하지 않으므로** 비용 없이 구조화된 메타데이터를 그래프에 통합합니다. 예시: 지식기반에 "부서" 필터가 있고 이를 지식 그래프 노드로 승격하면, 에이전트가 "재무팀 문서 중에서 찾아줘" 같은 자연어 질의를 자동으로 부서 필터로 변환합니다. 화면 우측의 지식 연결에서 연결된 지식기반 카드의 **"노드 설정"** 버튼을 클릭하여 모달을 엽니다. 연결된 지식기반의 필터 값이 표시됩니다. 노드로 승격할 필터를 체크박스로 선택합니다. | 필터 종류 | 노드 승격 가능 | 비고 | | :----------------------- | :------: | :------------------------------------------- | | 텍스트·범주형 (부서, 국가, 문서유형 등) | ✓ | 값 종류가 적당해 노드로 적합 | | 숫자·날짜형 | ✓ | 값 종류가 매우 많아 노드 수가 급증할 수 있어 신중히 선택 | | 용어집 연동형 | — | 용어집 용어로 자동 연결되어 별도 승격 불필요 (기존 `Term` 노드 재사용) | 저장하면 선택한 슬롯이 지식 그래프 링크에 저장됩니다. 다음 동기화 실행 시 선택된 슬롯의 값들이 `Doc Attribute` 노드로 만들어지고, 각 문서가 보유한 값과 엣지로 연결됩니다. #### 동작 원리 | 단계 | 처리 | | --------- | ------------------------------------------------------------------------------------------ | | 1. 슬롯 등록 | 선택한 필터를 지식 그래프 링크에 기록합니다. **원본 지식기반 필터 설정은 변경하지 않으므로**, 지식 그래프를 안 쓰는 환경에서도 지식기반은 그대로 동작합니다 | | 2. 값 수집 | 선택한 필터가 문서에서 실제 갖는 값들을 중복 없이 모읍니다 | | 3. 용어집 매치 | 모은 값이 연결된 용어집 용어와 일치하면 **기존 Term 노드를 재사용**해 그래프 중복·파편화를 방지합니다 | | 4. 노드 생성 | 용어집에 없는 값만 새 `Doc Attribute` 노드로 생성합니다 | | 5. 엣지 연결 | 각 문서를 자신이 가진 값 노드와 연결합니다 (예: "재무팀" 값을 가진 문서 → 재무팀 노드) | 연결 엣지 이름에는 필터 이름이 그대로 쓰입니다(예: 부서, 국가). 라우팅 단계에서 더 자연스러운 이름이 제안되면 그 이름이 우선 적용됩니다. `Doc Attribute`는 지식기반 필터를 LLM 호출 없이 그래프로 가져오는 가벼운 경로입니다. 청크 단위 엔티티 추출(`Doc Entity`)이 비용 부담스러우면 우선 `Doc Attribute`만으로 시작하고, 필요한 지식기반에만 LLM 추출을 켜는 단계적 도입을 권장합니다. ### 연결 상세 보기 각 지식 연결 카드를 펼치면 DB 테이블별 컬럼 매핑 현황을 확인할 수 있습니다. * **테이블 그룹**: 연결된 DB의 테이블별로 그룹핑 * **컬럼 매핑**: 컬럼명, 데이터 타입, PK/FK 표시, 매핑된 카테고리, 용어 개수 * **매칭된 문서 수**: 지식기반과 매칭된 문서 개수 표시 *** ## 동기화 리소스를 연결한 후 **동기화**를 실행해야 노드와 엣지가 만들어집니다. ### 동기화 방식 | 방식 | 버튼 | 범위 | | :------------ | :------------------ | :---------------------- | | **전체 동기화** | 상단 **"전체 동기화"** | 모든 소스 일괄 재구축 | | **링크 단위 동기화** | 각 링크의 **"엔티티 동기화"** | 해당 링크의 용어집 + DB + 지식기반만 | ### 전체 동기화 흐름 ```mermaid theme={null} flowchart TB A["전체 동기화 클릭"] --> B["삭제된 소스 정리"] B --> C["용어집 동기화\n(빠름, LLM 불필요)"] C --> D["DB 스키마 동기화\n(빠름)"] D --> E{"지식기반 자동 추출\n활성화?"} E -->|"Yes"| F["지식기반 엔티티 추출\n(LLM 호출, 시간 소요)"] E -->|"No"| G["검색 인덱스 갱신"] F --> G G --> H["통계 갱신 완료"] ``` ### 진행 상황 확인 * 동기화가 시작되면 버튼이 **"동기화중"** 으로 변경됩니다 * 완료/실패 시 실시간 알림(toast)이 표시됩니다 * 이미 실행 중인 동기화가 있으면 중복 실행이 차단됩니다 재동기화할 때는 **새로 추가되거나 바뀐 문서만** 다시 처리합니다. 이미 처리한 문서는 건너뛰어, 두 번째 동기화부터는 훨씬 빨라집니다. ### 동기화 소요 시간 | 소스 | 소요 시간 | 비용 | | :---------- | :-------------------- | :----------- | | 용어집 | 수 초 | 없음 | | DB 스키마 | 수 초 \~ 수 분 | 없음 | | 지식기반 엔티티 추출 | 수 분 \~ 수 시간 (문서량에 비례) | LLM 호출 비용 발생 | *** ## 그래프 탐색 ### 그래프 시각화 지식 그래프 상세 페이지에서 **"그래프 표시"** 토글을 켜면 인터랙티브 그래프 뷰가 표시됩니다. 지식 그래프 시각화