SetFN
SetFNDocs2026년 10월 5일

AI 상담 채팅 샘플 배포하기

Webspace의 AI 채팅 기능을 켜고, 배포할 때 생성되는 chat.html로 상담 흐름을 확인합니다. 이 구성은 Webspace마다 새 모델이나 Agent를 만드는 대신 관리자가 이미 설정한 모델과 Agent 실행 파이프라인을 사용합니다.

시작하기 전에

  • 필요 권한: 스키마와 API를 배포할 수 있는 사용자
  • 서버 관리자가 AI 제공자를 연결하고 사용할 채팅 모델을 등록·활성화해야 합니다.
  • AI 채팅의 사용 권한을 부여할 회원, 레벨, 팀 또는 관리자 조건을 정합니다.
  • chat.html을 사용할 회원은 같은 SetFN 사이트에 로그인할 수 있어야 합니다.
  • 상담에 사용할 데이터의 공개 범위와 시스템 지침을 검토합니다.

관리자 AI 모델 준비하기

관리자 설정에서 AI 제공자를 연결하고 상담에 사용할 채팅 모델을 등록·활성화합니다. Webspace의 주 모델과 대체 모델을 비워 두면 서버가 사용 준비가 된 활성 채팅 모델을 우선해 자동으로 선택합니다. 이미지가 포함된 요청에는 관리자가 설정한 OCR/VL 모델 우선순위도 반영합니다.

특정 Webspace에서 모델을 고정해야 할 때만 고급 설정의 주 모델과 대체 모델을 지정합니다. Webspace 화면이나 chat.html에 제공자 키와 모델 비밀값을 넣지 않습니다. 상담 화면은 배포된 AI 기능 연결을 호출하고, 모델 선택과 Agent 실행은 기존 서버 파이프라인을 따릅니다.

AI 채팅 고급 설정 구성하기

스키마의 기능 연결에서 AI 채팅을 켠 뒤 고급 설정을 엽니다.

  1. AI 채팅 기능을 켭니다.
  2. 특정 모델을 지정할 필요가 없다면 주 모델과 대체 모델을 비워 둡니다.
  3. 도구가 필요하다면 도구 사용을 켭니다. 기본값은 꺼짐입니다.
  4. 상담 범위와 답변 원칙을 시스템 지침에 입력합니다.
  5. 사용 권한을 설정합니다.
  6. 상담 채팅 샘플 생성을 켭니다.

스키마 파일에는 마지막 항목이 다음 구조로 저장됩니다.

{
  "apiBuild": {
    "features": {
      "ai-chat": {
        "enabled": true,
        "sampleChat": true
      }
    }
  }
}

sampleChat은 샘플 화면 생성 여부만 결정합니다. 기존 관리자 모델과 Agent 설정을 복제하거나 덮어쓰지 않습니다.

chat.html 자동 생성하기

AI 채팅의 enabled와 sampleChat이 모두 true이고 배포에 프론트엔드 샘플을 포함하면 chat.html이 생성됩니다. 클라이언트 배포 경로를 지정하고 스키마를 배포합니다. chat.html은 index.html과 test.html이 만들어지는 현재 프론트엔드 샘플 생성 폴더에 함께 저장되며, AI 상담 전용 폴더를 별도로 만들지는 않습니다.

상담서비스/
├── index.html
├── test.html
├── chat.html
├── style.css
└── README.md

같은 SetFN 사이트에 회원으로 로그인한 뒤 chat.html을 열어 다음 항목을 확인합니다. 샘플은 현재 로그인 세션으로 회원 정보를 초기화하므로 익명 공개 채팅으로 동작한다고 가정하면 안 됩니다.

  1. AI 채팅의 사용 권한이 없는 회원에게 요청이 허용되지 않는지 확인합니다.
  2. 권한이 있는 계정으로 메시지를 보냅니다.
  3. 답변이 기존 관리자 모델 또는 Agent 파이프라인을 통해 도착하는지 확인합니다.
  4. 도구 사용을 켰다면 허용한 범위 안에서만 도구가 실행되는지 확인합니다.
  5. 연결이 끊겼을 때 오류 상태가 표시되고 중복 메시지가 생기지 않는지 확인합니다.

상담 화면 다듬기

자동 생성된 chat.html은 연결과 권한을 확인하는 시작점입니다. 안내 문구, 추천 질문과 화면 스타일은 서비스 목적에 맞게 수정할 수 있습니다. 연결 주소, 인증 처리와 서버가 관리하는 모델 선택 로직은 임의로 클라이언트 설정으로 바꾸지 않습니다.

AI가 확인되지 않은 내용을 단정하지 않도록 시스템 지침에 상담 범위와 모르는 질문을 처리하는 방식을 적습니다. 운영 전에는 실제 권한별 계정으로 질문, 도구 호출과 오류 응답을 확인합니다.

알아두기

  • chat.html은 샘플 클라이언트이며 별도의 AI 모델이나 Agent를 생성하지 않습니다.
  • 주 모델과 대체 모델을 비워 두면 서버가 관리자 설정과 사용 가능한 모델 상태에 따라 모델을 자동 선택합니다.
  • 샘플 생성과 Agent 프로토콜 연결만으로 실제 AI 제공자의 답변을 보장하지 않습니다. 운영 전에 서버에 설정된 제공자, 모델 또는 Agent로 실제 메시지를 보내 응답을 확인합니다.
  • 샘플은 기존 AI Agent 프로토콜을 사용하며 도구 실행 상태, 승인 대기와 추가 입력 대기 안내를 표시합니다. 하지만 승인이나 추가 입력을 완료하는 UI 자체는 제공하지 않습니다.
  • 도구 사용은 기본적으로 꺼져 있습니다. 도구를 켜기 전에 해당 Agent가 요구하는 승인이나 추가 입력을 처리할 별도 UI가 있는지 확인합니다.
  • 샘플은 회원 로그인과 세션 초기화가 필요하며 익명 공개 사용을 보장하지 않습니다.
  • 도구 사용 권한과 AI 채팅의 사용 권한은 구분해 검토합니다.
  • 상담 입력에 개인정보나 비밀값을 넣지 않도록 별도 안내를 제공합니다.
  • 샘플을 수정한 뒤 다시 배포할 때 파일 덮어쓰기 범위를 확인합니다.

관련 문서