비즈니스 용어집 (Glossary)

GenD 의 비즈니스 용어집은 조직의 약어/지표/도메인 용어를 한 곳에 등록하고 검색할 수 있게 한다. NL2SQL 은 질문과 의미가 가까운 용어의 정의를 프롬프트에 함께 넣어 LLM 이 도메인 표현을 이해하도록 돕는다 (컬럼/테이블을 직접 지정해 주는 것은 아니다).

사전 준비

• GenD 에 로그인되어 있어야 합니다 (조회는 viewer 이상).
• analyst 이상 역할이면 신규 용어 등록·수정·삭제도 가능합니다.

1단계: 용어집 페이지 진입

사이드바 → 지식 & 시맨틱 → 용어 사전 메뉴를 클릭합니다 (/ai/glossary).

UI 가 호출하는 backend endpoint (ui/src/lib/api.ts):

동작	API
목록 조회	GET /api/v1/ai/glossary → {items: GlossaryTerm[], total: number}
단일 조회	GET /api/v1/ai/glossary/{term}
등록 (analyst)	POST /api/v1/ai/glossary
수정 (analyst)	PUT /api/v1/ai/glossary/{term}
삭제 (analyst)	DELETE /api/v1/ai/glossary/{term}

2단계: 용어 검색

검색창에 키워드 (e.g. LTV, MAU) 를 입력하면 list 응답을 클라이언트 측에서 substring 매칭으로 필터합니다. 매칭 대상은 용어명과 정의입니다 — 동의어만 일치하는 용어는 걸러지지 않으니 주의하세요.

3단계: 단일 용어 상세

목록 표에 용어명·정의·동의어가 모두 표시되므로 별도로 펼치는 동작은 없습니다. maps_to 매핑까지 확인하려면 GET /api/v1/ai/glossary/{term} 를 직접 호출하세요.

4단계: AI 채팅에서 활용

AI 채팅 (/ai) 에 도메인 용어 포함된 질문을 던지면 Agent 가 자동으로 search_glossary tool 을 호출해 의미를 보강한 뒤 SQL 을 생성:

사용자: "지난 분기 LTV 상위 10명 보여줘"
AI:     [search_glossary("LTV")] → definition: "Life Time Value (고객 생애 가치)"
        [get_tables] → customers, transactions 테이블 발견
        [execute_query] → SELECT customer_id, ... ORDER BY ltv DESC LIMIT 10

용어집이 비어 있어도 LLM 자체 지식으로 추론하지만, 조직 고유 약어 는 등록해야 정확도가 올라간다.

:::caution 알아둘 동작 두 가지

• 유사도 임계값이 없습니다. Text-to-SQL 은 코사인 유사도 상위 5건을 무조건 프롬프트에 넣습니다. 질문과 무관한 용어도 함께 들어가고, 등록된 용어가 5개 이하라면 매번 전부 주입됩니다.
• 데모 시드 용어의 벡터는 가짜입니다. make seed-demo 로 들어가는 금융 용어 30건은 해시 기반 난수 벡터(fake_embedding)를 씁니다. 의미가 없으므로 시드 데이터만 있는 환경에서 시맨틱 매칭 품질을 평가하면 안 됩니다. UI/API 로 직접 등록한 용어만 실제 임베딩을 갖습니다. :::

5단계: analyst — 용어 추가

analyst 이상 역할로 로그인하면 우측 상단의 용어 추가 버튼으로 신규 등록 가능. 또는 SDK 로 batch 등록:

from gend_api.sdk import glossary as g
await g.create_term(ctx, term="LTV", definition="Life Time Value", synonyms="생애가치,LV")

권한이 없으면 403 응답. 이미 있는 용어를 다시 등록하면 409.

등록 후 용어명은 변경할 수 없다 — 수정 화면에서 용어명 입력란은 잠겨 있고, PUT 으로 다른 이름을 보내면 400 이다. 이름을 바꾸려면 삭제 후 재등록한다.

외부 통합 (SDK / API client)

UI 외 자체 도구에서 read-only 으로 glossary 조회할 때는 /api/v1/glossary/* read-only endpoint 사용 (PR #791/#792). JWT 필수 — 이 라우터도 인증 보호 대상이라 Authorization: Bearer <token> 없이 호출하면 401 입니다:

API	용도
GET /api/v1/glossary/terms	전체 list (page-friendly)
GET /api/v1/glossary/search?q=...	server-side substring 검색
GET /api/v1/glossary/term/{term}	단일 term (404 on not found)

UI 와 backend store 는 동일 ArangoDB glossary collection 을 공유하므로 두 endpoint set 의 데이터는 일치한다.

회귀 테스트: apps/api/tests/test_glossary.py (PR #801 — 6 test pass).

다음 단계

• 데이터 계보 — 용어와 테이블/컬럼 연결 시각화
• AI Text-to-SQL — 자연어 질문 + 용어집 활용
• 거버넌스 개요