수동 문서
수동 문서는 파일 업로드나 웹 크롤링 없이 텍스트 청크를 직접 작성하여 Knowledge에 추가하는 방법입니다. 별도의 파싱이나 청킹 과정 없이 사용자가 원하는 내용을 정확히 제어할 수 있습니다.
새 수동 문서 생성
/knowledge/:knowledgeId/documents/manual/new 경로에서 새 수동 문서를 생성합니다. Knowledge 상세 페이지의 문서 (Documents) 탭에서 + 문서 추가 버튼을 클릭하여 진입합니다.
입력 항목
| 항목 | 필수 | 설명 |
|---|---|---|
| 이름 | 필수 | 문서의 제목 |
| 설명 | 선택 | 문서에 대한 설명 |
| 초기 청크 | 선택 | 첫 번째 청크로 등록될 초기 텍스트 |
초기 콘텐츠를 입력하면 문서 생성과 동시에 첫 번째 청크가 자동으로 생성됩니다. 비워두고 생성한 뒤 상세 페이지에서 청크를 추가할 수도 있습니다.
문서 만들기 버튼을 클릭하면 문서가 생성되고 상세 페이지로 자동 이동합니다.
수동 문서 생성 시 초기 콘텐츠는 선택 사항입니다. 문서를 먼저 생성한 뒤 상세 페이지에서 청크를 하나씩 추가하는 것도 좋은 방법입니다.
수동 문서 상세
/knowledge/:knowledgeId/documents/manual/:docId 경로에서 수동 문서의 상세 정보와 청크를 관리합니다.
문서 정보
상단 영역에 문서의 기본 정보가 표시됩니다:
| 항목 | 설명 |
|---|---|
| 유형 (Type) | 수동 태그 |
| 청크 (Chunks) | 총 청크 수 |
| 생성일 (Created) | 생성 일시 |
| 설명 (Description) | 문서 설명 (인라인 편집 가능) |
설명은 편집 버튼을 클릭하여 페이지 이동 없이 바로 수정할 수 있습니다.
청크 목록
문서에 포함된 청크가 테이블 형태로 표시됩니다.
| 컬럼 | 설명 |
|---|---|
| 체크박스 | 다중 선택 (일괄 삭제용) |
| # | 청크 순번 |
| 내용 (Content) | 청크 내용 미리보기 (2줄) |
| 토큰 (Tokens) | 토큰 수 (추정값) |
| 작업 (Actions) | 수정, 삭제 버튼 |
페이지네이션은 20개 단위로 서버사이드에서 처리됩니다. 청크가 20개를 초과하면 하단에 페이지 네비게이션이 표시됩니다.
청크 상세 보기
테이블에서 청크 행을 클릭하면 오른쪽에 청크 내용 뷰어 사이드 패널이 열립니다:
- 네비게이션: 이전 청크 / 다음 청크로 이동 (키보드 화살표 키 지원)
- 콘텐츠: 청크 전체 텍스트 확인 및 복사
- 메타데이터: Key-Value 형식의 메타데이터 조회
- 정보: 청크 ID, 스토리지(Vector/Text), 생성/수정 일시
청크 관리
청크 추가
청크 추가 버튼을 클릭하면 청크 편집 모달이 열립니다.
모달 입력 항목:
| 항목 | 설명 | 제한 |
|---|---|---|
| 내용 (Content) | 청크 텍스트 내용 | 최대 10,000자 |
| 메타데이터 (Metadata) | Key-Value 쌍의 메타데이터 | 동적 추가/삭제 가능 |
모달 하단에는 현재 텍스트의 추정 토큰 수가 실시간으로 표시됩니다.
메타데이터 편집
메타데이터는 Key-Value 쌍으로 구성됩니다:
- 메타데이터 추가 버튼으로 새 항목을 추가합니다
- 각 항목은 키(Key) 입력 필드와 값(Value) 입력 필드로 구성됩니다
- 항목 오른쪽의 삭제 버튼으로 개별 항목을 제거할 수 있습니다
- Value는 자동 타입 추론을 지원합니다:
true/false→ Boolean, 숫자 → Number, JSON 문자열 → Object/Array
기존 청크를 수정할 때 메타데이터는 병합(merge) 방식으로 업데이트됩니다. 기존 키에 새 값을 지정하면 덮어쓰고, 새 키는 추가됩니다.
청크 수정
청크 테이블의 편집 버튼 또는 청크 내용 뷰어의 편집 버튼을 클릭하면 편집 모달이 열립니다. 기존 콘텐츠와 메타데이터가 미리 로드되며, 수정 후 저장하면 해당 저장소(Vector/Text)에 자동 반영됩니다.
콘텐츠가 변경되면 임베딩 벡터가 자동으로 재생성됩니다.
청크 삭제
두 가지 삭제 방식을 제공합니다:
- 개별 삭제: 청크 행의 삭제 버튼 클릭 → 확인 팝업에서 확정 후 삭제
- 일괄 삭제: 체크박스로 여러 청크를 선택한 뒤 삭제 (N개) 버튼 클릭
삭제된 청크는 Vector DB와 Text DB에서 모두 제거됩니다. 이 작업은 되돌릴 수 없습니다.
문서 삭제
상세 페이지 헤더의 삭제 버튼으로 수동 문서 전체를 삭제할 수 있습니다. 문서 삭제 시 포함된 모든 청크도 함께 제거됩니다.
사용 사례
수동 문서는 다음과 같은 상황에서 유용합니다:
- FAQ 데이터 등록: 질문-답변 쌍을 개별 청크로 등록하여 정확한 검색 결과 확보
- 내부 규정/정책 텍스트 입력: 별도 파일 없이 정책 내용을 직접 입력
- 기존 시스템에서 추출한 텍스트 데이터: 다른 시스템에서 복사한 텍스트를 청크 단위로 등록
- AI 채팅 응답 저장: AI Chat에서 유용한 응답을 수동 문서의 청크로 저장하여 지식으로 재활용
- 정형 데이터 보완: 파일 업로드로 처리하기 어려운 짧은 텍스트나 메모를 추가
수동 문서는 소규모 텍스트 데이터에 적합합니다. 대량의 문서 데이터는 파일 업로드를 사용하세요.