> For the complete documentation index, see [llms.txt](https://genos-docs.gitbook.io/default/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://genos-docs.gitbook.io/default/v1.9.3/basic-tutorials/guides/data/custom-token.md). # 커스텀 토큰 ## 개요 커스텀 토큰은 AI 드라이브 단위로 **kagome\_kr 토크나이저가 하나의 토큰으로 유지해야 할 단어(토큰 텍스트)** 를 등록·관리하는 기능입니다. 토크나이저는 `신속채무조정` 같은 복합어를 `신속 / 채무 / 조정` 으로 분리합니다. 그러면 `신속배달` 처럼 `신속` 만 겹치는 무관한 문서까지 검색에 딸려 나와 정확도가 떨어집니다. 이 단어를 커스텀 토큰으로 등록하면 하나의 토큰으로 인식되어, 노이즈 없이 해당 문서만 정확히 검색됩니다. 진입 경로는 **관리자 콘솔 → 데이터 → AI 드라이브 → (드라이브 상세) → 상단 `파일 | 커스텀 토큰` 토글** 입니다.

AI 드라이브 상세 우측 상단의 파일 · 커스텀 토큰 토글 — 커스텀 토큰으로 전환한 상태

## 사용 전 확인 — 암호화 드라이브 제약 > **암호화 적재된 드라이브에서는 커스텀 토큰을 사용할 수 없습니다.** 커스텀 토큰은 저장된 청크 텍스트를 kagome\_kr 로 형태소 분석해 **역인덱스(BM25)** 를 만드는 방식으로 동작합니다. 암호화 적재된 드라이브는 청크 텍스트가 암호화된 상태로 저장되어 형태소 분석 자체가 불가능하므로, 토큰을 등록해도 검색에 반영되지 않습니다. 암호화가 필요한 데이터에는 커스텀 토큰 대신 **벡터 유사도 검색**을 사용하십시오. ## 주요 개념 | 개념 | 설명 | | ------ | -------------------------------------------------------------------------------------------------------------------- | | 커스텀 토큰 | 드라이브에 등록하는 **토큰 텍스트** 단일 값. 토크나이저가 분리하지 않아야 할 단어입니다. | | 용어사전 | 별개 기능입니다. `데이터 > 용어사전` 메뉴에서 뜻·동의어·번역어를 등록해 답변 품질을 높입니다. 커스텀 토큰은 색인·검색 단계, 용어사전은 확장·답변 단계에서 동작하며 **서로 자동 연동되지 않습니다.** | | 인덱싱 상태 | 토큰이 드라이브에 실제 반영됐는지 나타내는 상태 — 동기화됨 · 재인덱싱 대기 · 재인덱싱 중 · 재인덱싱 실패 | | 재인덱싱 | 아직 반영되지 않은(대기) 토큰을 kagome\_kr 사전에 실제로 적용하는 작업 | | 적용 속성 | 커스텀 토큰이 적용되는 kagome\_kr 토크나이저 속성. **조회 전용**입니다. | | 승인(신청) | 그룹 드라이브의 변경은 승인 결재를 거칩니다. 내 드라이브는 승인 없이 즉시 반영됩니다. | | 운영 이력 | 변경 신청의 결재 이력 | ## 커스텀 토큰 목록 보기 드라이브에 등록된 토큰이 테이블로 표시됩니다. 컬럼은 **토큰 텍스트 · 인덱싱 상태 · 수정일 · 수정자 · 관리** 이며, 토큰 텍스트·인덱싱 상태·수정일로 정렬할 수 있습니다. 상단 통합검색에서 검색 범위(토큰 텍스트·수정자)를 고른 뒤 검색어를 입력하면 필터링된 결과가 표시됩니다. 툴바 우측에는 사용량(등록 수 / 상한 2,000)이 표기됩니다.

커스텀 토큰 목록 테이블과 상단 통합검색·적용 속성·업로드·재인덱싱·사용량·커스텀 토큰 추가 버튼

### 인덱싱 상태 배지 | 배지 | 의미 | | ------- | --------------- | | 동기화됨 | 드라이브에 반영 완료 | | 재인덱싱 대기 | 변경됨 — 재인덱싱 필요 | | 재인덱싱 중 | 재인덱싱 진행 중 | | 재인덱싱 실패 | 재인덱싱 실패(재시도 필요) | ## 커스텀 토큰 추가 `[커스텀 토큰 추가]` 버튼을 누르면 추가 모달이 열립니다. **Enter 를 누를 때마다 토큰이 하나씩 추가**되며, 줄바꿈·쉼표로 구분된 텍스트를 붙여넣으면 한 번에 여러 건이 등록됩니다. 입력 규칙: * 1\~30자 · **한글·영문·숫자·공백만 입력 가능** (공백만 입력은 불가, 앞뒤 공백은 저장 시 제거) * 등록 시 중복 검사 — 오류 항목이 하나라도 있으면 추가할 수 없습니다 * 드라이브당 최대 2,000개까지 등록할 수 있습니다 * 추가 후 `[재인덱싱]` 을 실행해야 실제 검색에 적용됩니다 오류가 있는 칩은 빨간색으로 구분되며(공백만·사용 불가 문자·중복·30자 초과·상한 초과), 하단에 오류 문구가 표시됩니다. 오류 칩을 수정하거나 삭제하면 오류가 해제됩니다.

목록의 각 행 수정 아이콘을 누르면 **단건 수정 모달**로 토큰 텍스트를 편집할 수 있습니다. 체크박스로 여러 건을 선택하면 툴바에 `[삭제]` 가 나타납니다. ## 커스텀 토큰 업로드 `[업로드]` 버튼으로 CSV·XLSX 파일을 통해 여러 토큰을 일괄 등록합니다. `[양식 다운로드 (CSV)]` 로 양식을 받아 작성한 뒤 업로드합니다. **파일 구조는 1행이 헤더(`토큰 텍스트`), 2행부터 데이터입니다.** 헤더가 없으면 첫 데이터 행이 헤더로 인식되어 오류가 발생합니다. 검증은 개수 상한 → 헤더 → 행별 순서로 수행되며, 오류가 1건이라도 있으면 전체가 차단됩니다. 오류 발생 시 **형식·필수 오류 모달**에 행 번호와 사유(누락·공백만·30자 초과·사용 불가 문자·드라이브 내 중복·파일 내 중복)가 표로 표시됩니다.

## 적용 속성 조회 `[적용 속성]` 버튼으로 이 드라이브에서 커스텀 토큰이 적용되고 있는 kagome\_kr 토크나이저 속성을 확인합니다. **조회 전용이며 변경할 수 없습니다.** Weaviate 는 컬렉션 생성 시 속성의 토크나이저 설정이 고정되어 이후 변경할 수 없습니다. 따라서 커스텀 토큰은 **kagome\_kr 을 사용하는 모든 속성에 자동 적용**되며, 적용 대상을 사용자가 선택할 수 없습니다. * 기본 적용 속성: `text`, `summary`, `file_name` * 다른 속성에 적용하려면 드라이브 생성 시 수동 스키마에서 토크나이저를 설정해야 합니다 * 속성이 많은 경우 모달 상단 검색으로 속성명을 찾을 수 있습니다

## 재인덱싱 변경(대기) 토큰이 있으면 목록 상단에 **재인덱싱 필요 배너**가 표시됩니다. 추가뿐 아니라 **수정·삭제한 경우에도 재인덱싱이 필요**합니다. 배너에는 미반영 건수가 표시되며, 신규·수정과 삭제를 나누어 보여줍니다. > `{N}개 토큰 텍스트가 아직 이 드라이브에 반영되지 않았습니다. 재인덱싱이 필요합니다. (신규 및 수정 {N}건 / 삭제 {N}건)` `[재인덱싱]` 버튼을 누르면 확인 다이얼로그가 열립니다. > `변경된 {N}건을 대상으로 이 드라이브를 재인덱싱합니다.` `파일량에 따라 수 분이 소요될 수 있으며, 진행 중에도 검색은 계속 가능합니다.` `[실행]` 시 드라이브 전체를 대상으로 kagome\_kr 사전을 재적용합니다. 진행 중에도 검색은 계속 가능하며, 진행 상태는 화면 우측 하단 플로팅 위젯으로 확인할 수 있습니다. > **재인덱싱 진행 중에는 토큰 추가·업로드·수정·삭제를 신청할 수 없습니다.** 시도하면 `재인덱싱이 진행중입니다. 완료 후 변경을 신청해 주세요.` 안내가 표시됩니다. 완료 후 다시 시도하십시오. 문서 적재·재적재가 진행 중이면 재인덱싱을 실행할 수 없습니다(상호 배타).

## 운영 이력과 상세 목록 하단의 **커스텀 토큰 운영 이력** 에는 변경 신청의 결재 상태가 표시됩니다. 컬럼은 ID · 구분 · 유형(생성·수정·삭제·업로드) · 승인 상태 · 요청자 · 신청일시 · 승인자 · 승인/반려 일시 · 상세입니다. `[상세]` 를 누르면 신청 상세 모달이 열려 결재 정보와 토큰 정보를 확인할 수 있습니다. 업로드 건은 파일명과 함께 신청된 토큰 전량을 `No · 토큰 텍스트` 표로 표시하며, 모달 안에서 토큰을 검색할 수 있습니다. 신청 시점 값 기준의 스냅샷이므로, 이후 토큰이 변경·삭제되어도 이력 값은 바뀌지 않습니다. 승인 상태가 **대기 중**인 건은 `[신청 취소]` 로 취소할 수 있습니다.

커스텀 토큰 운영 이력 목록 — ID·구분·유형·승인 상태·요청자·신청일시·승인자·승인/반려 일시·상세

## 승인 처리 (승인 센터) **그룹 드라이브**의 변경 신청은 **홈 → 승인 → 승인 목록** 에서 결재합니다. 승인 유형 `데이터` · 상세 유형 `커스텀 토큰` 2단 필터로 조회할 수 있으며, `[검토]` 를 누르면 신청 이력 상세 모달에서 내용을 확인하고 `[승인]` 또는 `[반려]` 합니다. 결재 권한은 IAM 리소스 타입 **Data Approval** 로 부여합니다. **내 드라이브(개인 드라이브)** 는 승인권자가 존재하지 않으므로 승인 절차 없이 즉시 반영됩니다. 운영 이력에는 요청자·승인자가 모두 본인으로 기록됩니다.

## 오류·예외 처리 | 상황 | 화면 표시 | 조치 | | ------------ | --------------------------------- | ------------------------- | | 허용 문자 외 입력 | `한글·영문·숫자·공백만 사용할 수 있습니다` | 해당 칩 수정·삭제 | | 공백만 입력 | `공백만 입력할 수 없습니다` | 값 입력 | | 30자 초과 | `30자를 초과할 수 없습니다` | 길이 조정 | | 드라이브 내 중복 | `이미 등록된 커스텀 토큰입니다` | 중복 칩 삭제 | | 상한 초과 | `상한 초과 — 드라이브당 최대 2,000개입니다` | 초과분만큼 삭제 | | 업로드 파일 헤더 오류 | 형식·필수 오류 모달 + 실패 토스트 | 1행에 `토큰 텍스트` 헤더 추가 후 재업로드 | | 재인덱싱 중 변경 시도 | `재인덱싱이 진행중입니다. 완료 후 변경을 신청해 주세요.` | 재인덱싱 완료 후 재시도 | | 재인덱싱 실패 | 인덱싱 상태 `재인덱싱 실패` | `[재인덱싱]` 재실행 | | 적재·재적재 진행 중 | `[재인덱싱]` 비활성 | 적재 완료 후 실행 | ## 사용자 시나리오 ### 고유명사가 검색에 안 잡힐 때 1. 드라이브 상세 → `커스텀 토큰` 탭 진입 2. `[커스텀 토큰 추가]` → 분리되면 안 되는 단어 입력 → `[추가]` 3. (그룹 드라이브) 승인 완료 대기 / (내 드라이브) 즉시 반영 4. 상단 배너의 `[재인덱싱]` → `[실행]` 5. 인덱싱 상태가 `동기화됨` 으로 바뀌면 검색에 반영 완료 ### 여러 단어를 한 번에 등록할 때 1. `[업로드]` → `[양식 다운로드 (CSV)]` 2. 1행 헤더 유지, 2행부터 토큰 입력 후 저장 3. 파일 선택 → `[생성]` 4. 오류 모달이 뜨면 표시된 행·사유를 수정해 재업로드 5. 등록 완료 후 `[재인덱싱]` 실행 ### 잘못 등록한 토큰을 지울 때 1. 목록에서 체크박스 선택 → 툴바 `[삭제]` 2. 삭제 후에도 **재인덱싱이 필요**합니다 — 배너의 `[재인덱싱]` 실행 --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://genos-docs.gitbook.io/default/v1.9.3/basic-tutorials/guides/data/custom-token.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.