AI 챗봇 API

개요

순라이프 AI는 학교 공지·학사일정 등을 근거로 답변하는 챗봇입니다. 자체 호스팅된 vLLM 서버(OpenAI 호환 /chat/completions API, stream=True)를 사용하며, 공지 검색·시맨틱 검색·학사일정 조회 등의 **도구 호출(tool calling)**을 통해 최신 정보를 찾아 답변합니다.

엔드포인트 목록

모든 엔드포인트는 sch_session 쿠키 인증이 필요합니다.

대화 기록 저장 방식 — 로컬 저장 vs 클라우드 동기화

클라우드 동기화를 켜면 로컬 대화가 POST /api/chat/history/로 서버에 이전되고, 끄면 서버 대화가 다시 로컬로 내려온 뒤 DELETE /api/chat/history/로 서버 기록이 삭제됩니다.

POST /api/chat/

메시지 1건을 전송하고 답변을 NDJSON(줄바꿈으로 구분된 JSON) 스트림으로 받습니다.

요청 본문

클라우드 동기화 모드 (save_history: true)

{
  "message": "이번 학기 기숙사 규정 뭐가 바뀌었어?",
  "high_quality": false,
  "save_history": true,
  "conversation_id": null
}

로컬 저장 모드 (save_history: false, 기본값)

{
  "message": "이번 학기 기숙사 규정 뭐가 바뀌었어?",
  "high_quality": false,
  "save_history": false,
  "local_key": "loc-8f3a2b1c",
  "local_turns": [
    { "question": "안녕", "answer": "안녕하세요! 순라이프 AI입니다." }
  ]
}

응답 — NDJSON 스트림

Content-Type: application/x-ndjson. 줄 단위로 아래 이벤트 타입이 순서대로 도착합니다.

스트림 예시

{"type":"trace","message":"질문을 살펴보는 중이에요."}
{"type":"meta","conversation_id":42}
{"type":"trace","message":"공지사항을 찾는 중이에요."}
{"type":"delta","text":"이번 학"}
{"type":"delta","text":"기부터 "}
{"type":"ping"}
{"type":"delta","text":"바뀐 규정은..."}
{"type":"done"}

에러 응답

스트림 도중 발생하는 오류(대화를 찾지 못함, LLM 호출 실패 등)는 200 응답 안에서 {"type":"error", ...} 이벤트로 전달됩니다.

고성능 모드 (high_quality)

첨부문서(공지 첨부 PDF/HWP/DOCX 등)를 근거로 답변할 때, 일부 페이지만 보고 답하다 보면 중간에 있는 내용을 놓칠 수 있습니다. 고성능 모드는 첨부 전체 페이지를 배치로 전사(轉寫)해 근거 누락을 줄입니다. 그만큼 응답 시간이 길어집니다.

POST /api/chat/stop/

진행 중인 답변 생성을 즉시 중단합니다. 이미 생성된 부분까지는 스트림으로 전달되었을 수 있으나, 해당 턴은 대화 기록에 저장되지 않습니다.

요청

Body 없음.

응답

204 No Content

에러 응답

POST /api/chat/clear/

서버 메모리에 유지 중인 대화 컨텍스트를 초기화합니다(새 대화 시작). 진행 중인 답변 생성이 있다면 함께 중단됩니다.

요청

Body 없음.

응답

204 No Content

에러 응답

GET /api/chat/history/

내 대화 기록 목록을 최신순으로 반환합니다. (클라우드 동기화로 서버에 저장된 대화만 해당 — 로컬 저장 모드의 대화는 브라우저에만 있어 이 API로 조회되지 않습니다.)

쿼리 파라미터

응답 — 200 OK

{
  "conversations": [
    {
      "id": 42,
      "title": "이번 학기 기숙사 규정 뭐가 바뀌었어?",
      "updated_at": "2026-07-20T15:30:00+09:00"
    }
  ]
}

full=1이면 각 항목에 turns 배열([{question, answer, trace}])이 추가됩니다.

에러 응답

POST /api/chat/history/

브라우저(로컬 저장)에 있던 대화 기록을 서버로 이전합니다. 클라우드 동기화를 켤 때 호출됩니다.

요청 본문

{
  "conversations": [
    {
      "local_id": "loc-8f3a2b1c",
      "title": "기숙사 규정 문의",
      "turns": [
        { "question": "이번 학기 기숙사 규정 뭐가 바뀌었어?", "answer": "..." }
      ]
    }
  ]
}

응답 — 200 OK

{
  "mapping": {
    "loc-8f3a2b1c": 42
  }
}

mapping은 로컬 대화 id → 서버에 생성/재사용된 대화 id의 매핑입니다.

에러 응답

DELETE /api/chat/history/

내 대화 기록을 서버에서 전부 삭제합니다. 클라우드 동기화를 끌 때 호출됩니다.

응답

204 No Content

에러 응답

GET /api/chat/history/{id}/

특정 대화의 전체 내용을 조회합니다.

응답 — 200 OK

{
  "id": 42,
  "title": "이번 학기 기숙사 규정 뭐가 바뀌었어?",
  "turns": [
    { "question": "...", "answer": "...", "trace": ["..."] }
  ],
  "updated_at": "2026-07-20T15:30:00+09:00"
}

에러 응답

DELETE /api/chat/history/{id}/

특정 대화를 삭제합니다.

응답

204 No Content

에러 응답

POST /api/chat/feedback/

답변에 대한 좋아요/싫어요 평가를 제출합니다. 추후 응답 품질 개선(RLHF 학습 데이터)에 활용됩니다.

요청 본문

{
  "rating": "up",
  "question": "이번 학기 기숙사 규정 뭐가 바뀌었어?",
  "answer": "...",
  "comment": "표로 정리해줘서 좋았어요",
  "context": [],
  "high_quality": true
}

응답

201 Created

에러 응답

GET /api/chat/health/

챗봇 관련 인프라(DB, LLM, 시맨틱 검색 서버) 상태를 확인합니다. 로그인 여부와 무관하게 호출 가능합니다.

응답 — 200 OK

{
  "ok": true,
  "db": "connected",
  "model": "soonlife-qwen",
  "embed_search": "connected (12480건 인덱싱됨)"
}

기숙사 규정 변경 질문 — 고정 답변

이 경로로 응답되는 경우 도구 호출, 답변 검증 단계가 모두 생략되며, trace 이벤트도 발생하지 않고 곧바로 delta/done이 이어집니다.

챗봇 설정 (참고 — 서버 환경변수)

배포 환경에 따라 아래 값들이 챗봇 동작에 영향을 줍니다. (API 사용자 입장에서 직접 제어하는 값은 아니며, 서버 운영 참고용입니다.)