커리큘럼

아카데미모듈 2 · 지식그래프 구축과 관리

파일 추가와 지식 추출

6개 레슨 중 2번째12분

이 레슨에서 배우는 것

모든 원본을 마크다운으로 바꾸지 않고 내보낸 파일을 작업공간 폴더에 추가할 수 있습니다
파일 정보를 열어 분석 상태와 기록을 확인할 수 있습니다
지식 추출·갱신을 직접 실행하고 실패하거나 중단된 분석을 확인할 수 있습니다
.consilienceignore로 파일을 영구 제외하고 "제외 해제"로 되돌릴 수 있습니다
대량 구축 중에 채팅 메시지를 바로 보낼지, 잠시 맡겨 둘지 판단할 수 있습니다

지원하는 문서·스프레드시트·PDF·이미지·녹음 파일을 작업공간 폴더에 보관하세요. 다른 앱의 자료는 필요하면 먼저 파일로 내보냅니다.

파일을 넣으면 원본이 등록되고 상태가 표시됩니다. 이 동작만으로 AI 분석이 시작되지는 않습니다. "파일 정보"에서 지식을 추출할 시점을 선택하세요.

분석에서 얻은 지식은 별도로 저장됩니다. 원본은 기존 경로와 형식 그대로 남으며, 마크다운 사본을 만들거나 attachments/로 옮길 필요가 없습니다.

대화로 구축하고 유지하기

데스크톱에서 대화로 구축 시작하기

“이 파일로 온톨로지를 만들어줘”라고 요청하세요. 에이전트는 파일을 가져온 뒤 필요한 어휘 튜닝과 추출을 순서대로 실행하고 완료 결과를 기다립니다. 백그라운드 진행은 활동 센터에서 확인합니다.

현재 그래프 상태에 따라 빠진 종류 채우기, 동의어 정리, 주제 지도 재생성 등 필요한 관리 도구를 선택합니다. 구축한 지식을 다듬고 유지하는 일도 대화로 요청할 수 있습니다.

일반 권한 모드에서는 의미를 바꾸는 제안을 검토·승인한 뒤 적용합니다. 바뀐 문서나 실패한 항목만 지정해 갱신할 수 있습니다. 로컬·호스팅 환경마다 사용할 수 있는 도구는 다릅니다.

현재 파일 작업은 파일 트리와 "파일 정보"에서 시작합니다. 원본을 열고 현재 버전을 확인한 뒤 파일 프로필에서 분석을 실행하세요.

파일 정보 열기

각 파일의 "파일 정보"는 탭으로 열립니다. 다음 경로를 사용할 수 있습니다:

사이드바 파일 우클릭 → "파일 정보"
파일을 연 상태에서 Cmd+Shift+I(macOS) 또는 Ctrl+Shift+I(Windows). 사용자 지정 단축키는 다를 수 있습니다
파일 탭 우클릭 → "파일 정보"
현재 파일의 우측 상단 더 보기 메뉴 → "파일 정보"

등록과 분석은 별개입니다

지식을 추출하지 않은 파일도 폴더에 존재하고 열 수 있습니다. "파일 정보"에서 분석 상태와 기록을 확인하고, 파일 형식·권한·설정한 모델 경로가 허용하면 "지식 추출"을 실행합니다.

무엇을 넣을 수 있나

내보낸 파일을 사이드바 파일 트리에 드래그하거나 파일 관리자로 작업공간 폴더에 넣으면 앱이 발견합니다. 웹 페이지나 Notion 페이지는 지원하는 파일로 먼저 내보내세요. 로컬 내보내기 파일을 추가해도 SaaS 계정이 연결되거나 동기화되지는 않습니다.

소스	형식	처리 방식
문서	`docx`, `pptx`, `hwp`/`hwpx`, `epub`, `odt`, `rtf`	기존 형식의 원본을 유지하며, 읽기·분석 가능 여부는 파일 정보에서 확인
스프레드시트	`xlsx`/`xls`/`xlsm`/`ods`, `csv`/`tsv`	셀과 시트는 원본 스프레드시트 또는 구분자 텍스트 파일에 유지
PDF	`pdf`	PDF를 출처로 유지하며 텍스트·시각 분석 결과에 페이지나 영역 근거를 연결
이미지	`png`, `jpg`, `gif`, `webp`, `bmp`, `tiff`…	원본 이미지에 근거를 연결하며 관찰 내용과 텍스트를 분석
오디오	`mp3`, `wav`, `m4a`, `flac`, `ogg`…	직접 분석을 요청하면 설정한 분석 경로로 전사
웹페이지	PDF / HTML	지원하는 파일로 내보낸 뒤 폴더에 추가
Notion	Markdown / HTML / PDF	페이지를 내보낸 뒤 내보내기 파일을 폴더에 추가
일반 텍스트	`md`, `txt`, `json`, `yaml`, `xml`…	텍스트 파일 자체를 출처로 유지
기타 형식	미지원 형식	원본을 보관하고 지식 추출 미지원 여부는 파일 정보에 표시

코드 폴더는 작업공간의 구조를 유지하고 코드 색인을 사용합니다. 개별 문서는 별도의 지식 분석 상태를 가질 수 있으며, 저장소를 발견했다고 모든 문서의 분석이 끝난 것은 아닙니다.

파일이 있다고 분석된 것은 아닙니다

지원하지 않거나 읽을 수 없는 파일도 지식 추출 없이 폴더에 남을 수 있습니다. 파일 정보에서 지원 여부, 읽은 범위와 오류를 확인하세요.

그래프를 사용하기 전에 현재 버전과 분석 기록을 확인하세요. 원본을 보관하기 위한 자리표시 마크다운 노트는 필요하지 않습니다.

원본 파일 분석하기

첫 파일 분석

파일 추가
지원하는 파일 하나를 작업공간 폴더에 넣고 파일 트리에서 선택합니다.
파일 정보 열기
파일을 우클릭해 "파일 정보"를 엽니다. 경로·형식·버전·분석 상태를 확인합니다.
"지식 추출" 선택
분석을 직접 시작합니다. 읽기 전용 작업공간이나 미지원 형식에서는 분석할 수 없습니다. 앱이 안내하면 허용된 모델 연결을 설정하세요.
분석 확인
프로필에서 내용 읽기·지식 추출·검색 인덱싱 단계를 확인합니다. 기록에는 분석 실행과 오류가 남습니다.
결과 검토
엔티티·지식그래프·RDF 관계와 시각적 근거를 확인합니다. "파일 열기"로 원본에 돌아갈 수 있습니다.

파일 프로필은 다음 단계를 구분합니다:

"파일 발견": 작업공간에 원본 파일이 등록됨
"내용 읽기": 내용을 읽은 상태이며, 지식 추출 완료를 의미하지 않음
"지식 추출": 분석에서 그래프 정보를 얻음
"검색 인덱싱": 처리한 내용을 검색 색인에 반영

현재 파일 버전과 상태를 함께 확인하세요:

미분석: 파일은 등록되었지만 완료된 분석 기록이 없음
진행 중: 명시적으로 시작한 분석이 실행 중
분석 후 변경됨: "지식 갱신"으로 현재 원본 내용을 반영
실패 또는 일부 완료: 읽기 상세와 기록을 확인한 뒤 재시도
미지원 또는 제외됨: 지원·제외 조건이 바뀌어야 분석 가능

작업 중 다른 화면을 사용하다가 파일 프로필의 상태와 기록으로 돌아올 수 있습니다. "분석 중지"는 실행 중인 파일 분석에 취소를 요청합니다. 최종 상태를 확인하세요. 원본 파일은 폴더에 남습니다.

중단, 유예, 재시도

유예(Deferred): AI 사용 한도에 닿아 잠깐 멈춘 상태입니다. 실패가 아닙니다. 앱이 붙잡고 있다가 한도가 초기화되는 순간 알아서 다시 이어갑니다.
소진(Exhausted): 노트가 몇 번이나 걸림돌을 만나면, 앱이 자동 재시도를 멈추고 원할 때 누르는 원클릭 "재시도"를 건네줍니다.
낡음(Stale): 추출한 뒤에 파일이 디스크에서 바뀐 상태입니다. 앱이 이를 알아채고 그래프를 최신으로 맞추자고 제안합니다.
.consilienceignore: 워크스페이스마다 두는, .gitignore처럼 동작하는 파일입니다. 여기에 걸리는 파일은 추출에서도 코드 색인에서도 영영 빠집니다.
추출 게이트: 대량 구축 중에 채팅하면 뜨는 보류/전송 선택입니다. 답변이 언제나 완성된 그래프를 근거로 나오게 해 줍니다.

분석이 중단되거나 실패하면 파일 정보에서 현재 버전·기록·오류를 확인하고 다시 요청하세요. 재시도해도 원본의 마크다운 사본을 만들지 않습니다.

중단되거나 실패한 원본 파일 분석은 "파일 정보"에서 기록을 검토한 뒤 직접 다시 실행합니다
"추출 재시도가 필요해요": 여러 번 실패해 멈춘 노트들 → "모두 재시도"
"앱 밖에서 수정된 노트가 있어요": 추출 뒤 디스크에서 바뀐 노트 → "재추출"
지식그래프 튜닝 → "추출" 탭: 커버리지 헤드라인("N개 중 M개 AI 검색에 추가됨")과 "AI 검색에 추가하지 못한 노트" 섹션이 있어, 노트별 오류와 재시도 버튼을 보여 줍니다

영구 제외하기

내보내기 산출물, 비밀 정보, 자동 생성된 잡동사니처럼 절대 스캔되면 안 되는 파일도 있습니다. .consilienceignore는 워크스페이스마다 두는, .gitignore처럼 동작하는 파일입니다. 여기에 걸리는 파일은 추출에서도 코드 색인에서도 빠지고, 앞으로의 어떤 스캔에서도 마찬가지입니다. 제외하면 거기서 이미 파생된 데이터도 함께 지워집니다.

파일 트리에서 우클릭 → "추출에서 제외"
지식그래프 튜닝 → "제외된 파일" 탭: "목록"(검색 + "제외 해제"), "찾아보기"(체크박스 파일 트리), "직접 편집"(패턴 직접 입력)의 세 가지 보기가 있습니다

.consilienceignore

# 한 줄에 .gitignore 형식 패턴 하나
*.snap
build/
/drafts/private-journal.md
!keep.md

제외해도 원본은 삭제되지 않습니다

파일 트리의 제외 동작이나 .consilienceignore로 이후 스캔에서 자료를 제외할 수 있습니다. 분석 대상에서 빼는 것과 디스크에서 파일을 삭제하는 것은 다릅니다.

지원하는 파일을 다시 처리하려면 제외 패널에서 복원하거나 제외 규칙을 수정하세요.

찾아보기 트리에서 "이미 제외됨" 태그가 붙은 행은 .gitignore나 의존성 디렉터리, 제외된 상위 폴더에 걸린 것입니다. 규칙이 다른 곳에 있어서 여기서는 되돌릴 수 없습니다.

구축 중에 채팅하기

대량 구축이 도는 동안엔 채팅 답변이 아직 절반뿐인 그래프를 뒤지게 됩니다. 그래서 구축 중에 첫 메시지를 보내면 "지식 그래프 구축 중" 대화상자가 뜹니다. 실시간 진행("지금까지 N개 중 M개 추출됨")과 함께 세 가지 선택지를 줍니다: "추출 완료 후 자동 전송", "지금 전송", 취소. 고른 값은 그 구축이 끝날 때까지 기억되고, 대화상자는 구축당 많아야 한 번만 나타납니다.

보류된 메시지는 입력창 위 스트립에서 기다리다가 구축이 안정되면 알아서 전송됩니다. 그 전까지는 "기다리지 않고 보내기"를 누르거나, 수정해서 다시 대기열에 넣거나, 삭제할 수 있습니다. 노트 하나를 저장할 때는 게이트가 절대 뜨지 않습니다. 최근 편집이 아직 그래프에 반영되지 않았을 수 있다는 잔잔한 힌트만 보일 뿐입니다.

마무리

첫 원본 파일 분석하기

PDF나 이미지 하나를 작업공간 폴더에 추가합니다
파일 우클릭 → "파일 정보"에서 원본 경로와 최초 분석 상태를 확인합니다
허용된 모델 경로로 "지식 추출"을 실행하고 기록에서 결과를 확인합니다
추출한 지식을 검토하고, 제공된 경우 "근거 보기"로 원본의 해당 페이지나 영역에 돌아갑니다

원본은 기존 형식과 경로 그대로 남습니다. 파일 정보에서 분석 기록과 파생된 지식을 확인하며, 마크다운 사본을 반드시 만들지는 않습니다.

원본과 파생 데이터

파일 발견과 규칙 기반 읽기는 모델 분석과 구분됩니다. AI 분석은 설정한 모델 경로를 따르며 항상 로컬에서 처리되는 것은 아닙니다.

분석을 중지해도 원본은 삭제되지 않습니다. 다시 실행하거나 파생 지식이 최신이라고 판단하기 전에 최종 상태와 기록을 확인하세요.

원본을 추가하고 분석할 대상을 선택한 뒤 파일 정보에서 상태·기록·근거를 확인하세요. 다음은 추출이 만드는 엔티티와 관계, 그 온톨로지를 살펴볼 차례입니다.

← 이전 레슨