문서 - 월아 AI 고객 서비스

환경 요구사항

Node.js

18.0 이상

MySQL

5.7 이상

Alibaba Cloud 계정

百炼 + 기계 번역

설치 단계

1

1단계: 의존성 설치

安装全部依赖.bat를 더블클릭하여 실행하고 모든 의존성 설치가 완료될 때까지 기다립니다.

安装全部依赖.bat

2

2단계: 프로젝트 시작

启动项目.bat를 더블클릭하여 실행하면 개발 서버가 시작됩니다.

启动项目.bat
# http://127.0.0.1:3000

3

3단계: 설치 마법사 완료

브라우저에서 http://127.0.0.1:3000을 열면 데이터베이스 설정과 관리자 계정 생성이 안내됩니다.

설치 마법사가 SQL 테이블 생성, 관리자 생성, 설정 파일 작성을 자동으로 처리합니다. 수동 데이터베이스 작업이 필요 없습니다.

데이터베이스 구조

시스템은 7개의 테이블을 사용하며, 설치 마법사가 자동으로 생성합니다:

Table	Description
`users`	관리자 및 상담원 계정. admin / agent 두 가지 역할 지원
`clients`	사이트 설정 — 통합된 웹사이트당 하나의 레코드, Alibaba Cloud Agent ID 등 저장
`chat_sessions`	방문자 세션 — IP, 기기, 참조 페이지, 현재 서비스 모드 기록
`chat_messages`	채팅 메시지 — 모든 메시지 내용 및 발신자 유형 (방문자/상담원/AI)
`knowledge_base`	지식 베이스 Q&A 쌍 — 카테고리, 키워드, 우선순위 지원
`knowledge_files`	Alibaba Cloud 지식 베이스에 업로드된 파일 및 동기화 상태
`system_config`	API 키 및 번역 키를 포함한 전역 시스템 설정

Alibaba Cloud 설정

시스템은 Alibaba Cloud의 두 가지 서비스가 필요합니다: 百炼 (AI 응답)과 기계 번역 (메시지 번역). 관리 패널에 로그인하고 시스템 설정에서 다음을 입력하세요:

ali_api_key 百炼 API 키

Alibaba Cloud 百炼 콘솔에서 생성. Q&A 에이전트 호출에 사용.

ali_workspace_id 워크스페이스 ID

百炼 콘솔 우측 상단에서 확인 가능. ws-xxxxxxxx 형식.

ali_translate_key_id 번역 AccessKey ID

Alibaba Cloud RAM 콘솔에서 생성. 기계 번역 서비스 활성화 후 획득.

ali_translate_key 번역 AccessKey Secret

AccessKey ID와 쌍을 이룹니다. 생성 시 저장하세요. 이후 다시 확인할 수 없습니다.

Agent ID에 대하여：통합하는 각 사이트마다 Alibaba Cloud 百炼에서 별도의 지식 베이스와 에이전트를 만들어야 합니다. 생성 후 관리 패널의 사이트 관리에서 Agent ID와 지식 베이스 ID를 입력하세요.

웹사이트 통합

설치 후 채팅 창을 웹사이트에 임베드하면 방문자가 페이지를 떠나지 않고 대화를 시작할 수 있습니다.

1단계: 사이트 생성

관리 패널에 로그인하고 사이트 관리에서 새 사이트를 만들고 웹사이트 도메인을 입력합니다. 시스템이 고유한 클라이언트 코드를 생성합니다.

2단계: 코드 임베드

웹사이트 HTML의 태그 앞에 아래 코드를 붙여넣으세요. YOUR_LOCALE을 언어 코드(예: ko)로, YOUR_CLIENT_CODE를 사이트 클라이언트 코드로 교체하세요:

<script>
  (function() {
    var btn = document.createElement('a');
    btn.href = 'https://your-domain.com/YOUR_LOCALE/chat?client=YOUR_CLIENT_CODE';
    btn.target = '_blank';
    btn.rel = 'noopener noreferrer';
    btn.title = '联系客服';
    btn.style.cssText = 'position:fixed;bottom:24px;right:24px;width:56px;height:56px;border-radius:50%;background:#2563eb;display:flex;align-items:center;justify-content:center;box-shadow:0 4px 16px rgba(37,99,235,.45);z-index:9999;transition:transform .15s';
    btn.innerHTML = '<svg width="28" height="28" viewBox="0 0 24 24" fill="none" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>';
    btn.onmouseover = function(){ btn.style.transform = 'scale(1.1)'; };
    btn.onmouseout  = function(){ btn.style.transform = 'scale(1)'; };
    document.body.appendChild(btn);
  })();
</script>

3단계: 지식 베이스 설정

Alibaba Cloud 百炼에서 지식 베이스를 만들고 비즈니스 문서를 업로드한 후 Q&A 에이전트를 생성합니다. 그런 다음 관리 패널 사이트 관리에서 Agent ID를 입력하면 AI가 방문자 질문에 자동으로 응답합니다.