> 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/glossary.md). # 용어사전 ## 개요 용어사전은 사내에서 쓰는 용어를 등록해 **챗봇이 질문을 정확히 이해하도록** 만드는 기능입니다. 용어마다 뜻·동의어·번역어 같은 항목을 함께 넣어 두면, 사용자가 줄임말이나 사내 표현으로 물어봐도 챗봇이 무엇을 묻는지 알아냅니다. v1.9.3에서 용어사전은 **`데이터 > 용어사전` 독립 메뉴로 새로 만들어졌습니다.** 사전 단위로 **어떤 항목을 입력받을지(속성 구조)** 와 **임베딩 모델**을 직접 정의하며, 사전 1개마다 벡터 인덱스 1개가 만들어집니다. 진입 경로는 **관리자 콘솔 → 데이터 → 용어사전** 입니다. 메뉴는 IAM 정책에서 **용어사전 유형 권한(읽기 이상)** 을 받은 계정에만 보입니다.

## 주요 개념 | 개념 | 설명 | | -------- | ------------------------------------------------------------------------------------ | | 용어사전(사전) | 용어를 담는 단위. 사전 1개 = 벡터 인덱스 1개이며, 속성 구조·임베딩 모델·관리 그룹을 사전 단위로 정합니다. | | 속성 | 용어에 입력받을 항목. 여기서 정한 속성이 그대로 용어 테이블의 컬럼과 입력 폼의 항목이 됩니다. | | 대표어 | 모든 사전에 고정으로 있는 속성(키 `text`). 이 용어를 대표하는 이름이며 검색·답변의 기준입니다. | | 데이터 타입 | `text` · `text[]` · `int` · `int[]` · `number` · `number[]` · `boolean` · `date` 8종. | | 토크나이저 | 검색할 때 값을 쪼개는 단위. 문자 계열 속성에만 적용되며 한국어 기본값은 `kagome_kr`입니다. | | 검색 벡터 | 속성 값으로 벡터를 만들 때 붙이는 이름. 비워 두면 그 속성으로는 벡터를 만들지 않습니다. | | 인덱싱 | 용어를 벡터로 만들어 검색에 쓸 수 있게 하는 처리. **단건 추가·수정·삭제는 저장 시 자동**입니다. | | 전체 재인덱싱 | 사전의 모든 용어 벡터를 다시 계산하는 작업. 임베딩 모델을 바꿀 때 필요합니다. | | 영향 범위 | 대표어를 바꿀 때, 그 이름을 속성 값으로 쓰고 있는 다른 용어들. 함께 고칠 수 있습니다. | | 인증 키 | 워크플로우·코드에서 이 사전을 조회·수정할 때 쓰는 키. 읽기 전용 / 쓰기 가능 2종. | ## 용어사전 목록 컬럼은 **ID · 사전 이름 · 설명 · 용어 수 · 속성 수 · 임베딩 모델 · 관리 그룹 · 생성자/생성일시** 입니다. 사전 이름을 누르면 상세로 들어갑니다. * 검색은 **사전 이름 · ID · 관리 그룹 · 생성자** 중에서 대상을 골라 검색어를 입력합니다. * 정렬은 **사전 이름 · 생성일시** 2개 컬럼만 지원합니다. ## 용어사전 만들기 우측 상단 **\[용어사전 생성]** 을 누르면 **기본 정보 · 임베딩 모델 · 속성 정의 · 생성 결과** 4개 구획의 모달이 열립니다. | 항목 | 규칙 | | ----------- | -------------------------------------- | | 이름 (필수) | 최대 64자 | | 관리 그룹 (필수) | 셀렉트에서 선택(검색 가능). **생성 후에는 바꿀 수 없습니다.** | | 설명 | 최대 1,024자 | | 임베딩 모델 (필수) | 배포된 임베딩 서빙 중에서 선택. 사전 전체의 벡터 생성에 쓰입니다. | ### 속성 정의 용어에 어떤 항목을 입력받을지 정하는 단계입니다. 첫 줄은 **대표어**로 고정되어 이름·키(`text`)·타입을 바꿀 수 없고, **\[속성 추가]** 로 줄을 늘려 원하는 항목을 정의합니다.

* **속성 이름** 최대 64자 · **속성 키** 최대 128자(영문 소문자로 시작 + 영문·숫자·밑줄만, 예약어 불가) — 둘 다 사전 안에서 중복 불가이며, 키와 데이터 타입은 **저장 후 변경 불가**입니다. * 값을 여러 개 받으려면 `[]` 가 붙은 타입을 고릅니다. * ⚙ 버튼으로 **설명**(최대 1,024자 · 용어 입력 폼의 안내 문구로도 쓰입니다) · **토크나이저**(`kagome_kr` · `word` · `lowercase` · `whitespace` · `trigram` · `field` 6종) · **검색 벡터** · **검색·필터 설정**을 지정합니다. | 검색 · 필터 설정 | 설명 | 적용 범위 | | ---------- | ------------------------------- | ----------- | | 텍스트 검색 | 문장이나 단어로 데이터를 찾을 수 있습니다. | 문자 속성 전용 | | 일치 필터 | 같은 값이나 일부를 포함하는 값으로 조회할 수 있습니다. | 모든 타입 | | 범위 필터 | 값이 크거나 작은 조건으로 조회할 수 있습니다. | 숫자·날짜 속성 전용 | * **대표어의 일치 필터는 항상 켜져 있고 끌 수 없습니다** — 용어를 찾는 기준이기 때문입니다. * 범위 필터는 `int` · `number` · `date` **스칼라 타입에만** 켤 수 있습니다. 배열 타입은 벡터DB가 지원하지 않아 비활성입니다. * **생성 결과**에는 만들어질 검색 벡터가 미리 표시됩니다. 하나도 지정하지 않으면 그 사전은 챗봇 검색에 쓰이지 않습니다. > **속성은 만든 뒤 고칠 수 없습니다.** 등록한 속성은 이름·설명까지 포함해 수정·삭제가 모두 불가하며 **추가만** 됩니다. 사전을 만들기 전에 필요한 항목을 미리 정리해 두세요. ## 용어사전 상세 상단 헤더에 **ID · 관리 그룹 · 생성자 · 생성일시** 가 표시되고, 관리 그룹과 생성자는 클릭해 해당 상세로 이동할 수 있습니다. ✎ 버튼으로 **이름 · 상세 설명**을 수정하고, ⋮ 더보기에서 사전을 **삭제**합니다. 탭은 **운영 정보 · 용어 · 속성 정의 · 인증 키 · 변경 이력** 5개이며, 현재 탭이 URL에 남으므로 새로고침·링크 공유 시에도 같은 탭이 열립니다. ### 운영 정보 탭 **임베딩 모델**(수정 가능)과 이 사전에 만들어진 **검색 벡터** 목록(조회 전용)을 보여줍니다. 기본은 조회 모드이므로, 값을 바꾸려면 **\[수정]** 을 누르고 확인 창("수정 하시겠습니까?")에서 \[예]를 선택해야 입력이 열립니다. 임베딩 모델을 바꾸고 \[저장]을 누르면 안내와 함께 셋 중 하나를 고르게 됩니다.

| 선택 | 결과 | | ------- | ----------------------------------------------------- | | 취소 | 아무것도 저장하지 않습니다. | | 무시하고 저장 | 모델만 바꾸고 재인덱싱은 하지 않습니다. 변경 이력의 「인덱싱」 열에 **무시** 로 남습니다. | | 지금 재인덱싱 | 저장과 함께 **전체 재인덱싱**을 시작합니다. 한 번 더 실행 확인을 받습니다. | > 같은 모델을 다른 서빙으로 바꾼 것이라면 벡터를 다시 만들 필요가 없으니 **무시하고 저장**을 고릅니다. ### 용어 탭

표 컬럼은 **대표어 + 사전에 정의한 속성들 + 생성일시 + 수정일시** 라, 사전마다 컬럼 구성이 다릅니다. 값이 여러 개인 속성은 칩으로 표시되고 길면 말줄임되며, 마우스를 올려 전체 값을 확인합니다. * 검색은 **대표어 기준**이고, 정렬은 **대표어 · 생성일시 · 수정일시** 3개 컬럼입니다. * 행을 클릭하면 수정 패널이 열립니다. * 우측 상단은 **\[업로드] · \[다운로드] · \[용어 추가]** 이며, 읽기 전용 권한이면 \[다운로드]만 보입니다. * **\[다운로드]** 는 용어 전체를 `<사전 이름>_용어_.csv` 로 저장합니다. #### 용어 추가·수정 **\[용어 추가]** 를 누르면 **이 사전에 정의한 속성에 따라 입력란이 만들어진** 패널이 열립니다.

| 타입 | 입력 방법 | | --------------------- | ------------------------------------------------ | | `text` · `text[]` | 최대 1,024자. 배열은 하나 입력하고 **Enter**(또는 + 버튼)로 계속 추가 | | `int` · `int[]` | 정수만. `±9,007,199,254,740,991` 까지 | | `number` · `number[]` | 숫자만(소수 가능) | | `date` | `YYYY-MM-DD` 형식만. 시각은 넣을 수 없습니다 | | `boolean` | 스위치로 참/거짓 | * **대표어는 필수**이며, 이미 등록된 대표어와 같으면 "이미 등록된 용어입니다." 로 막힙니다. * 속성 설명은 라벨 옆에 안내로 표시되고, 라벨 오른쪽에 그 속성의 **키 · 데이터 타입**(예: `category · text`)이 회색으로 표기됩니다. * 저장하면 **자동으로 인덱싱됩니다.** 별도 재인덱싱이나 승인 결재가 필요 없습니다. #### 대표어를 바꿀 때 — 영향 범위 확인 대표어는 다른 용어의 속성 값(동의어·관련어 등)으로 들어가 있을 수 있어, **대표어를 수정하면 저장 전에 영향 범위를 확인해야 합니다.**

1. 대표어를 고치면 안내 박스와 **\[영향 범위 확인]** 버튼이 나타납니다. 2. 버튼을 누르면 이 값을 속성 값으로 쓰는 항목을 조회합니다. 3. 결과는 **집계 카드**(영향 항목 · 용어 · 속성 건수)와 **대표어 · 속성 · 값 변경** 표로 나오며, 함께 바꿀 항목을 체크합니다(기본 전체 선택). 4. 선택한 항목은 저장 시 함께 수정되고, 해당 용어도 자동으로 다시 인덱싱됩니다. 확인하지 않고 저장하면 막히고, 확인 후 대표어를 또 고치면 결과가 폐기되어 버튼이 다시 나타납니다. **속성 값만 바꿀 때는 이 단계가 없습니다.** #### 용어 삭제 체크박스로 용어를 고르면 하단에 **\[선택 삭제]** 바가 나타납니다. 토스트의 건수는 **실제로 지워진 건수**이며, 다른 사람이 이미 지운 용어는 제외됩니다. 전부 이미 지워졌으면 오류가 아니라 "이미 삭제된 용어입니다." 안내가 뜹니다. ### 용어 대량 등록 (업로드) 용어 탭 **\[업로드]** 를 누르면 양식을 받고 파일을 올리는 모달이 열립니다.

**① 양식 내려받기** — **\[CSV 내려받기]** 로 양식을 받습니다. **컬럼은 현재 속성 정의의 「속성 키」로 만들어지므로**, 속성을 바꿨다면 양식을 다시 받아 작성해야 합니다. | 작성 규칙 | 내용 | | ------------- | ------------------------------------------------------------ | | 파일 형식·한도 | `.csv` · `.xlsx` / 최대 5,000행 · 10MB | | 여러 값(`[]` 타입) | 세미콜론(`;`)으로 구분 | | 날짜 | `YYYY-MM-DD` | | 참/거짓 | `참`·`true`·`1`·`y`·`yes`·`t` / `거짓`·`false`·`0`·`n`·`no`·`f` | **② 판정 확인** — 파일을 올리면 **행마다 등록 가능 여부를 먼저 판정**해 「처리 상태」 표(행 · 대표어 · 상태 · 메시지 · 속성 값 컬럼들)로 보여줍니다. 상태는 **가능 / 불가** 2종이고, 불가 행은 사유가 메시지로 표시됩니다(대표어 누락·중복, 파일 안 중복, 타입·형식 불일치, 글자 수·숫자 크기 초과, 구분자 오류). 헤더가 현재 속성 정의와 맞지 않으면 판정 없이 안내 토스트만 뜹니다. **③ 반영** — **\[용어 추가]** 를 누르면 **가능 행만** 등록됩니다. 모달이 닫히고 용어 탭 상단에 진행 배너가 뜨며, 완료되면 성공·실패 건수가 토스트로 표시됩니다. ### 인덱싱 중 잠금 인덱싱이 도는 동안에는 일부 조작이 잠기고, 버튼에 마우스를 올리면 사유가 표시됩니다. | 진행 중인 작업 | 잠기는 조작 | | --------- | ------------------------------------------------ | | 대량 업로드 반영 | 용어 추가 · 업로드 · 선택 삭제 · 운영 정보 수정 · 사전 삭제 · 전체 재인덱싱 | | 전체 재인덱싱 | 운영 정보 수정 · 사전 삭제 (**용어 추가·업로드는 그대로 가능**) | 다운로드는 인덱싱 중에도 가능합니다. 진행률 배너는 작업을 실행한 사람에게만 보이고, 같은 사전을 보는 다른 관리자에게는 "인덱싱 진행 중" 상태 배너가 표시됩니다. ### 전체 재인덱싱 임베딩 모델을 바꿀 때 필요하며, 진입 경로는 **운영 정보 탭에서 \[지금 재인덱싱] 선택** 과 **직전 재인덱싱이 실패했을 때 용어 탭 상단 배너의 \[전체 재인덱싱]** 두 곳입니다. 진행 중에도 챗봇은 계속 답변하지만 아직 반영되지 않은 용어는 이전 내용으로 답변합니다. 실패하면 재시도 배너가 남고, 재시도는 처음부터 다시 실행됩니다. ### 속성 정의 탭 정의된 속성을 **속성 이름 · 속성 키 · 데이터 타입 · 토크나이저 · 검색 벡터 · 검색 설정 · 설명** 한 표로 보여줍니다. 검색 설정은 켜진 항목을 **텍스트 · 일치 · 범위** 칩으로 표시하고, 지정하지 않은 값은 `—` 입니다. 대표어 행은 배경색으로 구분되며, 행을 클릭해 열리는 속성 상세는 **조회 전용**입니다. **\[속성 추가]** 로 항목을 하나 더 만들 수 있습니다. 추가하면 모든 용어에 입력란이 하나 늘어나지만 기존 용어는 값이 비어 있어 **재인덱싱이 필요하지 않습니다.** 값을 채우면 그 용어만 자동으로 다시 인덱싱됩니다. ### 인증 키 탭 워크플로우·코드에서 이 사전을 조회하거나 수정할 때 쓰는 키를 발급합니다.

* **읽기 전용 키** — 용어를 조회만 할 수 있는 키 * **쓰기 가능 키** — 용어 추가·수정·삭제까지 할 수 있는 키. 노출에 주의하세요. 키는 자동 발급되지 않습니다. 발급 전에는 "아직 생성된 키가 없습니다" 가 표시되며 오른쪽 **생성 아이콘 버튼**으로 발급하고, 발급된 키는 **복사 아이콘 버튼**으로 가져갑니다. 같은 자리 버튼이 **갱신**이며, 확인 문구 `확인했습니다` 를 직접 입력해야 실행됩니다. **갱신하면 이전 키는 더 이상 쓸 수 없으므로** 그 키를 쓰는 워크플로우·코드가 없는지 먼저 확인하세요. 읽기 전용 권한 계정에는 쓰기 가능 키 카드와 생성·갱신 버튼이 보이지 않습니다. 사용처는 카드 아래에 안내됩니다 — **용어사전 · 코드스페이스 · 코드 서빙 · 평가지표 · MCP 도구 · MCP 서버 · 워크플로우 · 전처리기** 8곳. 인증 키는 코드에서 사전을 직접 다룰 때 쓰는 경로입니다. 챗봇이 사전을 쓰게 하려면 아래 **챗봇에서 사용하기**를 따릅니다. ### 변경 이력 탭

컬럼은 **변경 일시 · 작업자 · 변경 유형 · 대상 · 변경 내용 · 인덱싱/반영 일시** 입니다. **대상 · 작업자** 로 검색하고 **변경 유형** 필터로 원하는 유형만 볼 수 있습니다. 변경 유형은 **용어 추가 · 용어 수정 · 용어 삭제 · 속성 정의 변경 · 설정 변경 · 재인덱싱** 6종입니다. 변경 내용은 `신규 등록 (속성 3개)` · `벌크 업로드 100건 등록` · `선택 삭제 5건` · `대표어 연차→연차휴가` + `영향 항목 2건 함께 수정` · `속성 추가 antonym` · `전체 벡터 재계산 완료` 처럼 표기됩니다. 「인덱싱 / 반영 일시」 열은 인덱싱과 무관한 변경이면 `-`, 인덱싱된 건은 **건수 + 반영 시각**, 임베딩 변경에서 무시하고 저장했으면 **무시** 입니다. 실패한 재인덱싱도 그때까지 반영된 건수를 표시하므로(전부 실패면 `0건`) 어디까지 처리됐는지 확인할 수 있습니다. 대량 업로드 행은 「변경 내용」이 **시도 건수**, 「인덱싱」이 **성공 건수** 라 두 숫자가 다르면 일부만 반영된 것입니다. ## 챗봇에서 사용하기 사전을 만들고 용어를 넣는 것만으로는 답변에 쓰이지 않습니다. **워크플로우에서 그 사전을 조회 대상으로 붙여야** 챗봇이 사용합니다. ### 워크플로우 노드에 사전 붙이기 1. 워크플로우 편집 화면에서 **Genos VectorDB** 노드의 **Weaviate Host** 를 클릭합니다. 2. 선택창 좌측에 **벡터DB · 그룹 드라이브 · 내 드라이브 · 공유받은 문서함 · 용어사전** 탭이 나옵니다(Skills 탭은 정책이 켜진 환경에서만 추가로 보입니다). **용어사전** 탭에서 권한이 있는 사전을 고릅니다. 3. **Weaviate Index** 는 고른 사전의 인덱스(`GenosGlossary_<사전 ID>`)로 자동 채워집니다. 4. 노드의 **Weaviate Retriever** 또는 **Weaviate Vector Store** 출력을 RAG 체인에 연결합니다. 사전을 고르면 노드가 문서용 설정을 사전 기준으로 자동 보정합니다. | 항목 | 사전을 고를 때의 동작 | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Weaviate Metadata Keys | 문서용 기본값(`i_page` · `file_name` · `file_path`)은 사전에 없는 속성이라 그대로 요청하면 검색이 실패합니다. 그래서 노드가 사전 스키마에 있는 키만 남기고, 남는 키가 없으면 **대표어를 뺀 사전 속성 전체**를 가져옵니다. 정의·동의어 같은 값이 답변 근거에 함께 실리는 이유입니다. | | Weaviate Filter | 문서 기준으로 남아 있던 필터(사전에 없는 속성)는 무시됩니다. | | Weaviate Text Key | 비워 두면 기본값 `text` 가 쓰이며, 이 값이 대표어 키입니다. | * 사전 생성이 정상 완료되지 않아 인덱스 정보가 없는 사전은 선택창에서 **비활성**으로 표시됩니다. * **검색 벡터가 하나도 없는 사전은 챗봇 검색에 쓸 수 없습니다**(속성 정의 탭에서 확인). 검색 벡터를 여러 개 만든 사전은 노드에서 대상 벡터를 고를 수 없으므로, 아래 **코드에서 직접 조회하기** 경로를 사용합니다. * 사전을 만들 때 지정한 임베딩 모델과 **같은 모델**을 노드의 Embeddings 에 연결해야 합니다. 다른 모델로 질문을 벡터화하면 저장된 벡터와 비교가 되지 않습니다. ### 답변에 반영되는 방식 용어사전에서 검색된 내용은 답변을 만드는 근거로 쓰이지만, **채팅 답변의 출처 목록에는 표시되지 않습니다.** 출처에는 문서 벡터DB 결과만 노출됩니다. ### 코드에서 직접 조회하기 인증 키를 발급하면 코드스페이스 · 코드 서빙 · MCP 도구 · MCP 서버 · 워크플로우 Python 단계 · 평가지표 · 전처리기에서 사전을 직접 조회하거나(읽기 전용 키) 용어를 추가·수정·삭제할 수 있습니다(쓰기 가능 키). ## 용어사전 삭제 상세 헤더 ⋮ → **\[삭제]**. 되돌릴 수 없으므로 확인 창에 **`삭제`** 를 직접 입력해야 버튼이 활성됩니다. > 등록된 **용어와 속성 정의가 모두 삭제**되고, 연결된 **벡터 인덱스도 함께 삭제**됩니다. 남겨 둬야 할 내용이 있으면 용어 다운로드를 먼저 하세요. 인덱싱이 진행 중이면 삭제가 잠깁니다. ## 사용자 시나리오 ### 사내 용어사전을 처음 만든다 `데이터 > 용어사전` → **\[용어사전 생성]** → 이름·관리 그룹·임베딩 모델 선택 → 속성 정의에서 필요한 항목 추가(예: `정의`(text) · `동의어`(text\[]) · `영문명`(text) · `개정일`(date)) → 검색에 쓸 속성에 **텍스트 검색**을 켜고 벡터 검색이 필요하면 **검색 벡터** 이름 지정 → \[생성] → 용어 탭에서 **\[용어 추가]** → 워크플로우 **Genos VectorDB** 노드의 Weaviate Host에서 이 사전을 골라 챗봇에 연결. > 속성은 나중에 수정·삭제할 수 없으니 항목 구성을 먼저 확정하세요. ### 엑셀로 용어 수백 건을 한 번에 올린다 용어 탭 → **\[업로드]** → **\[CSV 내려받기]** 로 양식 확보 → 컬럼(=속성 키)에 맞춰 작성(여러 값은 `;`, 날짜는 `YYYY-MM-DD`) → 파일 드롭 후 **가능/불가** 판정 확인 → 문제없으면 **\[용어 추가]** → 배너로 진행 확인, 완료 토스트에서 성공·실패 건수 확인. ### 용어 이름을 바꿔야 한다 용어 탭에서 해당 행 클릭 → 대표어 수정 → **\[영향 범위 확인]** 으로 이 이름을 값으로 쓰는 용어 확인 → 함께 고칠 항목 체크 → \[저장] → 변경 이력에서 `대표어 A→B` + `영향 항목 N건 함께 수정` 확인. --- # 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/glossary.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.