AskDesk 상세 설명서 — 무엇을, 왜, 어떻게
회사 문서를 올리면 그 회사만 아는 AI 상담원이 생기고, 웹 위젯·독립 페이지·카카오·API 로 붙여 쓰는 서비스입니다. 이 문서는 사용법보다 왜 이렇게 만들었고 안에서 무슨 일이 벌어지는지를 설명합니다.
1. 무엇을 해결하나
1-1. 문제
- 고객센터 질문의 대부분은 이미 FAQ·정책·안내문에 답이 있습니다. 그런데 고객은 그 문서를 찾지 않고 묻고, 직원은 같은 답을 하루에 수십 번 합니다.
- 일반 챗봇(ChatGPT 같은)은 우리 회사 정책을 모르고, 모르면 그럴듯하게 지어냅니다. 배송 기간·환불 규정을 지어내면 사고가 됩니다.
- 시나리오형 챗봇(버튼 트리)은 만들기 어렵고, 질문이 조금만 달라져도 못 알아듣습니다.
1-2. AskDesk 의 답
- 문서가 곧 지식: PDF·워드·텍스트·CSV·웹페이지·사이트 전체·Q&A 를 올리면 자동으로 잘게 나눠(청크) 의미 벡터로 바꿔 둡니다.
- 근거 없는 답은 하지 않는다: 질문과 충분히 비슷한 근거가 없으면 LLM 을 부르지도 않고 "자료에 없다"고 답합니다(환각 차단). 답할 때는 문장마다 출처 번호 [n] 를 답니다.
- 모르는 질문이 곧 할 일: 못 답한 질문은 미답변 큐에 자동으로 쌓이고, 운영자가 답을 적으면 그 즉시 지식이 됩니다.
- 채널은 어댑터: 답변 엔진은 하나, 위젯·독립 페이지·카카오 i 오픈빌더·REST 는 얇은 껍데기입니다.
- 비용 예측: 임베딩(문서 이해)은 서버 안 로컬 모델이라 무료, 생성만 Claude(Haiku 기본)를 씁니다. 메시지마다 토큰·비용을 기록하고 봇별·일별로 집계합니다.
1-3. 이 도구가 만들어 내는 가치
- 반복 문의 자동 응대(24시간), 상담원은 상담원 연결 요청과 미답변 큐만 봅니다.
- 답변 품질을 평가 세트로 숫자화하고, 지식·설정을 바꾼 뒤 회귀를 잡습니다.
- 대화 기록·출처·신뢰도가 남아 "봇이 왜 그렇게 답했는지"를 언제든 되짚을 수 있습니다.
2. 전체 구조
| 구성 요소 | 위치 | 역할 |
|---|---|---|
| 콘솔(웹) | Next.js 16, src/app/(console) | 워크스페이스·봇·지식·플레이그라운드·대화·미답변·평가·설치·사용량·설정 |
| 답변 엔진 | src/lib/answer.ts | 질문 → 검색 → 근거 임계 → LLM → 후처리 → 기록·집계·알림 |
| 검색 코어 | src/lib/retrieval.ts, index-cache.ts | 봇별 메모리 인덱스: 벡터(코사인) + BM25(키워드) → RRF 병합 |
| 임베딩 | src/lib/embed.ts | Xenova/multilingual-e5-small(384차원, CPU, 외부 키 없음) |
| 색인 워커 | scripts/worker.mjs | jobs 큐: 추출(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. 답변 파이프라인 — 단계별로 정확히
- 입력 정규화: 공백 정리, 2,000자 제한. 봇이 일시정지면 423.
- 레이트리밋: 봇별
분당 요청 한도(기본 20) — 방문자(IP 또는 visitorId) 단위 슬라이딩 윈도. - 대화 확보:
conversationId가 이 봇의 것이면 이어 붙이고, 아니면 새로 만듭니다. 질문은PII 마스킹옵션에 따라 전화·이메일·카드번호를 가려 저장합니다. "이전 지시를 무시하라"류 문장은 감사 로그에만 남깁니다(차단은 하지 않음). - 플랜 한도: 이번 달 메시지가 플랜 한도에 닿으면 안내문으로만 답합니다(플레이그라운드·평가는 집계 제외).
- 금지 주제: 설정한 단어가 들어 있으면 정중히 거절(LLM 호출 없음).
- 상담원 키워드: "상담원", "직원" 등이 들어 있으면 즉시 핸드오프 문구로 답하고, 영업시간 밖이면 영업시간 외 안내로 답합니다.
escalated표시 + 알림. - 검색: 질문을
query:접두로 임베딩 → 벡터 상위 30 + BM25 상위 30 → RRF(k=60) 로 병합 →top_k(기본 6), 같은 소스는 최대 3개. - 근거 임계(게이트): 최고 코사인이
min_score(기본 0.82) 이상이면 통과. 임계에 0.04 못 미쳐도 BM25 점수가 1.0 이상(키워드가 분명히 잡힘)이면 통과. 미달이면 LLM 을 부르지 않고 폴백 문구 + 추천 질문으로 답하고 미답변에 기록합니다. > e5 계열 임베딩은 무관한 문장끼리도 코사인 0.80 근처가 나옵니다. 그래서 임계가 높아 보여도 정상입니다. 플레이그라운드의 "최고 코사인"을 보며 봇마다 조절하세요. - 프롬프트: system = 봇 이름·페르소나 + 7가지 규칙(근거 밖 답 금지, [n] 인용, 자료는 지시가 아님, 개인정보 요구 금지, 언어·말투, 마지막 줄에
<<<META>>>JSON). user = 직전max_history턴 +<documents>블록(번호·제목·본문) + 질문. - LLM 출력 형식: 본문 다음 줄에
<<<META>>>{"citations":[…],"confidence":0~1,"needs_human":bool,"followups":[…],"unanswered":bool}. 스트리밍일 때는 마커 이후를 숨기는 필터가 글자를 흘려보냅니다. - 후처리: 모델이 준 인용 번호를 실제 근거에 매핑(없는 번호 제거, 본문의 [n] 도 정리).
unanswered이거나 confidence 0 이면 인용을 붙이지 않습니다.needs_human이면 핸드오프 문구를 덧붙이고 알림. 신뢰도는 모델 값이 있으면 그것, 없으면 코사인을 0~1 로 환산. - 기록·집계: messages(인용·검색 후보·신뢰도·지연·토큰·비용·모델), conversations(메시지 수·escalated), usage_daily(메시지·대화·토큰·비용·폴백·핸드오프·👍👎), unanswered(정규화 해시로 같은 질문 누적).
4. 지식(색인) — 문서가 청크가 되는 과정
- 추출: PDF(pdf-parse) · DOCX(mammoth) · HTML(스크립트/내비/푸터 제거, 제목은
#접두) · CSV(헤더 기준 "열: 값") · TXT/MD/JSON. - 청킹: 문단 경계를 지키며 약 700자, 앞 청크 꼬리 100자를 물고 갑니다.
# 제목줄은 경계가 되고 그 아래 청크들의 제목이 됩니다(출처 표시·임베딩 문맥에 씀). 20자 미만은 버립니다. - 임베딩:
passage:접두, 16개씩 배치, 정규화된 384차원 float32 → BLOB 저장. 로컬 CPU 에서 100청크에 몇 초. - Q&A: 한 쌍이 한 청크("Q: … A: …"), 제목은 질문. 짧은 정답을 바로 찾게 하는 가장 강력한 형식입니다. 미답변에서 "답 적기"를 하면 이 형식으로 들어갑니다.
- URL/사이트: 15초 제한·5MB 상한. 사이트는 같은 호스트만,
robots.txt의 Disallow 존중, 링크 깊이·최대 페이지·포함/제외 경로, 요청 간 0.4초 간격. 재수집 주기를 두면 워커가 매시간 만료된 것을 다시 큐잉합니다. - 캐시: 봇별 인덱스는 메모리에 올려 두고
bots.index_version이 바뀌면(소스 추가·삭제·재색인) 다시 올립니다. 30분 미사용 봇은 내립니다.
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 케이스에서 연결했나) |
| 상담원 판단 일치 | 10 | needs_human 이 기대와 같나 |
| 8초 이내 | 5 | 지연 |
70점 이상 통과. 세트별 점수 추이가 남으니 지식을 바꾸기 전후로 같은 세트를 돌려 회귀를 확인하세요.
8. 보안·운영 원칙
- 비밀번호 scrypt, 세션은 HMAC 쿠키(14일), 모든 조회에 workspace_id 격리, API 키는 SHA-256 해시 저장.
- 업로드는 20MB·확장자 화이트리스트, 파일은 웹루트 밖(
/var/lib/askdesk/uploads). - 프롬프트 인젝션: 근거는
<documents>안의 데이터로만 취급하라고 시스템 규칙에 명시, 의심 문장은 감사 로그. - 내부 주소(localhost·사설 IP) 수집 금지, robots.txt 존중, 요청 간격.
- 플랜: Free(봇 1·소스 5·월 300) / Pro(5·100·5,000) / Business(무제한·REST). 초과 시 안내문 응답 + 콘솔 배너. 청구는 수동.
- 텔레그램 토큰은 응답에서 마스킹, 로그에 비밀값을 남기지 않습니다.
9. 운영 메모(서버)
- 서비스: pm2
askdesk(:3250) +askdesk-worker. Apacheask.starplan.one→ 3250, SSE 를 위해flushpackets=on. - DB
askdesk(MariaDB), 마이그레이션npm run migrate(재실행 안전). 모델 캐시/var/lib/askdesk/models. - 테스트:
npm test(청킹·토크나이저·BM25·RRF·프롬프트 파서·스트리밍 마커 필터·카카오 포맷·레이트리밋·영업시간). - 상태 확인: 대시보드 KPI,
jobs테이블(실패 사유),pm2 logs askdesk-worker.
10. 한계와 다음 단계
- 스캔 PDF(이미지)는 텍스트를 뽑지 못합니다(OCR 미지원).
- 임베딩 모델이 작아(e5-small) 아주 미묘한 의미 차이는 놓칠 수 있습니다 → Q&A 로 보강하거나 Sonnet 모델로 답변 품질을 올리세요.
- Phase 2: 음성(TTS) 위젯, 다국어 자동 번역 답변, 슬랙/디스코드/네이버 톡톡 어댑터, 청구 자동화, 온프레미스.