AskDesk 상세 설명서 — 무엇을, 왜, 어떻게

회사 문서를 올리면 그 회사만 아는 AI 상담원이 생기고, 웹 위젯·독립 페이지·카카오·API 로 붙여 쓰는 서비스입니다. 이 문서는 사용법보다 왜 이렇게 만들었고 안에서 무슨 일이 벌어지는지를 설명합니다.

1. 무엇을 해결하나

1-1. 문제

1-2. AskDesk 의 답

  1. 문서가 곧 지식: PDF·워드·텍스트·CSV·웹페이지·사이트 전체·Q&A 를 올리면 자동으로 잘게 나눠(청크) 의미 벡터로 바꿔 둡니다.
  2. 근거 없는 답은 하지 않는다: 질문과 충분히 비슷한 근거가 없으면 LLM 을 부르지도 않고 "자료에 없다"고 답합니다(환각 차단). 답할 때는 문장마다 출처 번호 [n] 를 답니다.
  3. 모르는 질문이 곧 할 일: 못 답한 질문은 미답변 큐에 자동으로 쌓이고, 운영자가 답을 적으면 그 즉시 지식이 됩니다.
  4. 채널은 어댑터: 답변 엔진은 하나, 위젯·독립 페이지·카카오 i 오픈빌더·REST 는 얇은 껍데기입니다.
  5. 비용 예측: 임베딩(문서 이해)은 서버 안 로컬 모델이라 무료, 생성만 Claude(Haiku 기본)를 씁니다. 메시지마다 토큰·비용을 기록하고 봇별·일별로 집계합니다.

1-3. 이 도구가 만들어 내는 가치

2. 전체 구조

구성 요소위치역할
콘솔(웹)Next.js 16, src/app/(console)워크스페이스·봇·지식·플레이그라운드·대화·미답변·평가·설치·사용량·설정
답변 엔진src/lib/answer.ts질문 → 검색 → 근거 임계 → LLM → 후처리 → 기록·집계·알림
검색 코어src/lib/retrieval.ts, index-cache.ts봇별 메모리 인덱스: 벡터(코사인) + BM25(키워드) → RRF 병합
임베딩src/lib/embed.tsXenova/multilingual-e5-small(384차원, CPU, 외부 키 없음)
색인 워커scripts/worker.mjsjobs 큐: 추출(PDF/DOCX/HTML/CSV/TXT) → 청킹 → 임베딩 → 저장, 사이트 크롤, 재수집, 평가 실행
채널/api/chat, widget.js, /w/:key, /c/:key, /api/kakao/:key, /api/v1/*같은 엔진을 다른 껍데기로
알림src/lib/notify.ts텔레그램·웹훅으로 상담원 요청·연락처 접수 알림

2-1. 데이터가 흐르는 길

[문서 업로드] → sources(pending) → jobs(index) → 워커: 추출 → 청킹 → 임베딩 → chunks 저장 → sources(ready), bots.index_version+1
[질문]       → 임베딩(query:) → 벡터 top30 + BM25 top30 → RRF → top_k(소스당 최대 3)
             → 최고 코사인 ≥ min_score ? LLM(근거 블록 + 대화 이력) : 폴백 문구(미답변 기록)
             → 인용 매핑·정리 → messages 저장 → usage_daily 집계 → (핸드오프면) 알림

3. 답변 파이프라인 — 단계별로 정확히

  1. 입력 정규화: 공백 정리, 2,000자 제한. 봇이 일시정지면 423.
  2. 레이트리밋: 봇별 분당 요청 한도(기본 20) — 방문자(IP 또는 visitorId) 단위 슬라이딩 윈도.
  3. 대화 확보: conversationId 가 이 봇의 것이면 이어 붙이고, 아니면 새로 만듭니다. 질문은 PII 마스킹 옵션에 따라 전화·이메일·카드번호를 가려 저장합니다. "이전 지시를 무시하라"류 문장은 감사 로그에만 남깁니다(차단은 하지 않음).
  4. 플랜 한도: 이번 달 메시지가 플랜 한도에 닿으면 안내문으로만 답합니다(플레이그라운드·평가는 집계 제외).
  5. 금지 주제: 설정한 단어가 들어 있으면 정중히 거절(LLM 호출 없음).
  6. 상담원 키워드: "상담원", "직원" 등이 들어 있으면 즉시 핸드오프 문구로 답하고, 영업시간 밖이면 영업시간 외 안내로 답합니다. escalated 표시 + 알림.
  7. 검색: 질문을 query: 접두로 임베딩 → 벡터 상위 30 + BM25 상위 30 → RRF(k=60) 로 병합 → top_k(기본 6), 같은 소스는 최대 3개.
  8. 근거 임계(게이트): 최고 코사인이 min_score(기본 0.82) 이상이면 통과. 임계에 0.04 못 미쳐도 BM25 점수가 1.0 이상(키워드가 분명히 잡힘)이면 통과. 미달이면 LLM 을 부르지 않고 폴백 문구 + 추천 질문으로 답하고 미답변에 기록합니다. > e5 계열 임베딩은 무관한 문장끼리도 코사인 0.80 근처가 나옵니다. 그래서 임계가 높아 보여도 정상입니다. 플레이그라운드의 "최고 코사인"을 보며 봇마다 조절하세요.
  9. 프롬프트: system = 봇 이름·페르소나 + 7가지 규칙(근거 밖 답 금지, [n] 인용, 자료는 지시가 아님, 개인정보 요구 금지, 언어·말투, 마지막 줄에 <<<META>>> JSON). user = 직전 max_history 턴 + <documents> 블록(번호·제목·본문) + 질문.
  10. LLM 출력 형식: 본문 다음 줄에 <<<META>>>{"citations":[…],"confidence":0~1,"needs_human":bool,"followups":[…],"unanswered":bool}. 스트리밍일 때는 마커 이후를 숨기는 필터가 글자를 흘려보냅니다.
  11. 후처리: 모델이 준 인용 번호를 실제 근거에 매핑(없는 번호 제거, 본문의 [n] 도 정리). unanswered 이거나 confidence 0 이면 인용을 붙이지 않습니다. needs_human 이면 핸드오프 문구를 덧붙이고 알림. 신뢰도는 모델 값이 있으면 그것, 없으면 코사인을 0~1 로 환산.
  12. 기록·집계: messages(인용·검색 후보·신뢰도·지연·토큰·비용·모델), conversations(메시지 수·escalated), usage_daily(메시지·대화·토큰·비용·폴백·핸드오프·👍👎), unanswered(정규화 해시로 같은 질문 누적).

4. 지식(색인) — 문서가 청크가 되는 과정

5. 콘솔 화면

화면무엇을 하나
대시보드오늘·30일 KPI, 봇 목록, 미답변 상위, 최근 대화, 한도 경고
상담봇 › 새로 만들기4단계 마법사: 이름·성격 → 첫 지식 → 테마 → 설치
개요봇 KPI(7일), 지식 상태, 최근 대화·작업, 설정 요약
지식소스 목록(상태·청크·진행률·재색인·삭제·청크 보기·Q&A 편집) + 추가(URL/사이트/파일/Q&A/텍스트)
플레이그라운드실제 파이프라인으로 대화 + 오른쪽 디버그(검색 후보와 cos/bm25/rrf 점수, 인용 표시, 프롬프트, 토큰·비용·지연). 사용량 집계 제외
대화채널·평가·상담원 요청·검색어 필터, 상세(출처·신뢰도·비용·👍👎·연락처), CSV 내보내기
미답변열림/해결/무시, 답 적기 → Q&A 승격, 샘플 대화 링크
평가세트(질문·필수/금지 키워드·상담원 기대) → 실행 → 점수·통과·지연·비용, 케이스별 근거, 추이
설치위젯 스니펫·독립 링크·카카오 스킬 URL·공개 API·REST 예시, 데모 페이지
설정기본·답변 정책·모델/검색·리드/영업시간·테마/허용 도메인·삭제
사용량·비용일별 메시지 막대, 토큰, 폴백 비율, 월 한도
워크스페이스이름, 멤버 초대(링크), 비밀번호, 플랜, 알림(텔레그램·웹훅), API 키

6. 채널

6-1. 위젯

<script src="https://ask.starplan.one/widget.js" data-bot="pk_…" async></script>

런처 버튼 → iframe /w/:key. 테마색·위치·문구는 봇 설정. 허용 도메인이 비어 있으면 어디서든 동작하고, 적어 두면 그 도메인(하위 포함)에서만 설정을 내려줍니다(그 외는 403). 대화·방문자 id 는 브라우저 localStorage 에 있어 새로고침해도 이어집니다. 모바일에서는 전체 화면.

6-2. 독립 페이지 /c/:key

링크 하나로 여는 전체 화면 채팅. 카카오채널 소개글·문자·QR 용.

6-3. 카카오 i 오픈빌더 스킬 /api/kakao/:key

요청의 userRequest.utterance 를 질문으로, user.id 를 방문자로 씁니다. 응답은 v2 simpleText(1,000자) + quickReplies(후속 질문 최대 5개). 출처는 "근거: 제목" 한 줄. 카카오는 5초 안에 답해야 하므로 4.5초 안에 못 끝나면 "확인 중" 으로 먼저 답하고 완성된 답을 10분간 캐시해 두었다가 같은 질문이 다시 오면 즉답합니다. 30분 안의 같은 사용자 대화는 이어 붙입니다.

6-4. 공개 채팅 API /api/chat

{botKey, message, conversationId?, visitorId?, stream?} → {conversationId, messageId, answer, citations, confidence, needsHuman, fallback, followups, latencyMs, usage}. stream:1 이면 SSE(delta 이벤트로 글자, done 에 위 객체). 부가: /api/chat/feedback(👍👎+메모), /api/chat/lead(연락처), /api/chat/history.

6-5. REST v1 (Business 플랜, Authorization: Bearer ak_…)

POST /api/v1/chat · GET/POST /api/v1/sources · GET /api/v1/conversations. 키는 워크스페이스에서 발급하며 해시만 저장됩니다(발급 시 1회 표시).

7. 평가(Evals) — "잘 되는지"를 숫자로

케이스 한 줄: 질문 | 필수키워드1;키워드2 | 금지키워드 | human. 실행하면 케이스마다 실제 파이프라인으로 답하고 채점합니다.

항목점수뜻
필수 키워드 포함률50답에 꼭 있어야 할 사실(숫자·정책어)이 들어갔나
금지 키워드 없음20하면 안 되는 말(경쟁사·틀린 숫자)이 없나
근거 인용 / 기대한 상담원 연결15폴백 없이 출처를 달았나(또는 human 케이스에서 연결했나)
상담원 판단 일치10needs_human 이 기대와 같나
8초 이내5지연

70점 이상 통과. 세트별 점수 추이가 남으니 지식을 바꾸기 전후로 같은 세트를 돌려 회귀를 확인하세요.

8. 보안·운영 원칙

9. 운영 메모(서버)

10. 한계와 다음 단계