Model API 설계 - 100-hours-a-week/6-nemo-wiki GitHub Wiki

🤖 LLM 기반 모임 추천 및 정보 생성 API 설계

네모 서비스는 사용자의 성향과 선호에 따라 모임을 추천하고, AI를 활용하여 모임 정보를 자동 생성 및 저장하는 기능을 제공합니다. 본 문서는 해당 기능을 구성하는 API 명세를 설명합니다.

📌 API 목록

기능	메서드	URL
모임 정보 생성	`POST`	`/ai/v1/groups/information`
챗봇 객관식 질문 생성	`POST`	`/ai/v2/chatbot/questions`
챗봇 객관식 답변 분석	`POST`	`/ai/v2/chatbot/answers`
챗봇 자유입력 기반 추천	`POST`	`/ai/v2/chatbot/freeform`
벡터 DB - 모임 정보 저장	`POST`	`/ai/v2/vector/save/groups`
벡터 DB - 사용자 정보 저장	`POST`	`/ai/v2/vector/save/users`

📥 입력 & 📤 출력 명세

Version 1

1. 모임 정보 생성

Request

POST /ai/v1/groups/information
{
  "name": "SB 모임",
  "goal": "스스로 웹사이트를 제작할 수 있다.",
  "category": "IT/개발",
  "period": "1개월 이하",
  "isPlanCreated": true
}

Response

{
  "code": 200,
  "message": "모임 정보 생성 완료",
  "data": {
    "name": "SB 모임",
    "summary": "Spring boot를 개발할 수 있다.",
    "description": "안녕하세요 Spring boot를 학습하는 SB 모임입니다~~~....",
    "tags": ["Java", "비전공자 환영", "온라인스터디", "기초부터"],
    "plan": [
      {
        "step": 1,
        "title": "환경 설정",
        "content": "Spring boot 개발 환경을 설정합니다."
      }
    ]
  }
}

Version 2

2. 챗봇 객관식 질문 생성

Request

POST /ai/v2/chatbot/questions
{
  "user_id": "123"
}

Response

{
  "code": 200,
  "message": "챗봇 질문 생성 완료",
  "data": {
    "questions": [
      {
        "question": "모임에서 더 중요한 건?",
        "options": ["사람", "주제", "장소"]
      }
    ]
  }
}

3. 챗봇 객관식 답변 분석

Request

POST /ai/v2/chatbot/answers
{
  "user_id": "123",
  "answers": [
    {
      "question": "모임에서 더 중요한 건?",
      "selected_option": "사람"
    }
  ]
}

Response

{
  "code": 200,
  "message": "챗봇 질문 답변 완료",
  "data": null
}

4. 챗봇 자유입력 기반 추천

Request

POST /ai/v2/chatbot/freeform
{
  "user_id": "123",
  "query": "사람 많은 곳은 피하고, 조용한 대화 중심의 모임이 좋아요."
}

Response

{
  "code": 200,
  "message": "챗봇 질문 답변 완료",
  "data": {
    "context": "조용한 분위기에서 책을 함께 읽는 소모임이나 산책 중심의 모임이 잘 어울릴 것 같아요.",
    "groupId": ["123", "456"]
  }
}

5. 벡터 DB - 모임 정보 저장

Request

POST /ai/v2/vector/save/groups
{
  "code": 201,
  "message": "모임이 생성되었습니다.",
  "data": {
    "groupId": 123,
    "name": "SB 모임",
    "summary": "Spring boot를 개발할 수 있다.",
    "description": "...",
    "category": "개발",
    "location": "판교",
    "maxUserCount": "50",
    "imageUrl": "image.jpg",
    "tags": ["Java", "비전공자 환영", "온라인스터디", "기초부터"],
    "plan": "asdfasdfasdf"
  }
}

Response

{
  "code": 200,
  "message": "모임 정보 저장 완료",
  "data": null
}

6. 벡터 DB - 사용자 정보 저장

Request

POST /ai/v2/vector/save/users
{
  "code": 201,
  "message": "모임이 생성되었습니다.",
  "data": {
    "user_id": "1234",
    "group_id": ["8765", "3452"]
  }
}

Response

{
  "code": 200,
  "message": "사용자 정보 저장 완료",
  "data": null
}

❌ 오류 처리

상태 코드	설명	예시 메시지
400	잘못된 요청	`{"code":"INVALID_REQUEST","message":"요청에 잘못된 형식이 포함되었거나, 필수 입력값이 누락되었습니다."}`
409	리소스 충돌	`{"code":"FORBIDDEN","message":"이미 존재하는 리소스입니다."}`
422	유효성 검사 실패	`{"code":"FORBIDDEN","message":"요청 형식이 잘못되었습니다. 필수 입력값을 확인해주세요."}`
429	요청 과다	`{"code":"UNPROCESSABLE CONTENT","message":"요청이 너무 많습니다. 잠시 후 다시 시도해주세요."}`
500	AI 응답 처리 실패	`{"code":"MODEL_GENERATION_FAILED","message":"AI 모델 응답 처리 중 문제가 발생했습니다."}`
503	서비스 불가	`{"code":"SERVICE_UNAVAILABLE","message":"AI 생성 서비스가 현재 사용 불가능합니다. 잠시 후 다시 시도해주세요."}`

🧩 시스템 연계 구조

[사용자 입력]
    ↓
/chatbot/questions (질문 생성)
    ↓
/chatbot/answers (답변 분석)
    ↓
/chatbot/freeform (자유 입력 기반 추천)
    ↓
/groups/information (모임 정보 생성)
    ↓
/vector/save/groups & /vector/save/users (벡터 DB 저장)

🧪 API 테스트 예시

curl -X POST http://localhost:8000/ai/v2/chatbot/freeform \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "123",
    "query": "조용한 분위기의 책 모임을 찾고 있어요."
  }'

응답

{
  "code": 200,
  "message": "챗봇 질문 답변 완료",
  "data": {
    "context": "조용한 분위기에서 책을 함께 읽는 소모임이나 산책 중심의 모임이 잘 어울릴 것 같아요.",
    "groupId": ["123", "456"]
  }
}

본 API 명세는 네모 서비스의 AI 기능과 프론트/백엔드 간의 원활한 연동을 위한 기준 문서입니다.