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

개요

네모 서비스는 다양한 AI 기능을 API로 모듈화하여 제공합니다. 이 문서는 AI 모델과 연동된 각 API의 기능, 입력/출력 명세, 예시, 공통 오류 처리 방식까지 포함합니다.

API 명세서 링크

1. API 엔드포인트 목록

엔드포인트 Method 설명
/groups/information POST 모임 정보 생성 (모임명/목적/카테고리/기간/커리큘럼 생성 여부 입력)
/persona/mcq POST 성향 질문 생성
/persona/keywords POST 성향 질문 응답 분석 및 키워드 추출
/groups/recommendations/search POST 입력한 쿼리 기반 모임 추천 검색
/groups/recommendations/personal POST 사용자 참여 이력 기반 개인화된 모임 추천

2. API 상세 설명

/groups/information – 모임 소개 자동 생성

  • 사용자가 입력한 모임 정보 기반으로, AI가 소개글, 상세 설명, 태그, 커리큘럼을 생성합니다.

입력 예시

{
  "group_name": "LangChain 스터디",
  "purpose": "LangChain 개념 정리와 실습",
  "category": "개발/스터디",
  "duration": "1개월",
  "curriculum_required": true
}

입력 필드 명세

필드명 타입 필수 설명
group_name string 예 모임 이름
purpose string 예 모임 목적
category string 예 카테고리 (예: 개발/스터디)
duration string 예 예상 진행 기간
curriculum_required boolean 예 커리큘럼 포함 여부

출력 예시

{
  "short_description": "LangChain 실습 중심 스터디, 함께 성장해요!",
  "detailed_description": "생성형 AI와 LangChain에 관심 있는 분들을 위한 실습 중심 스터디입니다...",
  "tags": ["LangChain", "AI", "스터디", "LLM", "실습"],
  "curriculum": [
    { "step": 1, "title": "LangChain 시작하기", "content": "설치 및 기본 구조 이해" },
    { "step": 2, "title": "LLM 모듈 실습", "content": "PromptTemplate 및 LLMWrapper 실습" }
  ]
}

공통 오류 처리 → 아래 참고

/persona/mcq – 성향 질문 생성

  • 성향 분석을 위한 다지선다형 질문과 선택지를 생성합니다.

입력 예시

(입력 없음)

입력 필드 명세

(요청 없음)

출력 예시

{
  "questions": [
    { "question": "모임에서 더 중요한 건?", "options": ["사람", "주제", "장소"] },
    { "question": "처음 보는 사람 앞에서는?", "options": ["말이 많아지는 편", "조용해지는 편"] }
  ]
}

공통 오류 처리 → 아래 참고

/persona/keywords – 성향 응답 분석 및 키워드 추출

  • 사용자의 질문 응답을 기반으로 키워드를 추출합니다.

입력 예시

{
  "answers": [
    { "question": "모임에서 더 중요한 건?", "selected_option": "사람" },
    { "question": "처음 보는 사람 앞에서는?", "selected_option": "조용해지는 편" }
  ]
}

입력 필드 명세

필드명 타입 필수 설명
answers array 예 응답 배열
answers[].question string 예 질문 내용
answers[].selected_option string 예 선택한 답변

출력 예시

{
  "keywords": ["사교적", "조용한 분위기 선호"]
}

공통 오류 처리 → 아래 참고

/groups/recommendations/search – 유사 모임 검색

  • 입력된 쿼리와 유사한 모임을 검색해 추천합니다.

입력 예시

{
  "query": "온라인으로 진행되는 소규모 개발 스터디"
}

입력 필드 명세

필드명 타입 필수 설명
query string 예 검색 쿼리 문장

출력 예시

{
  "results": [
    { "group_id": "123", "group_name": "백엔드 스터디" },
    { "group_id": "456", "group_name": "비대면 개발 모임" }
  ]
}

공통 오류 처리 → 아래 참고

/groups/recommendations/personal – 개인화 추천

  • 사용자 이력 기반으로 개인 맞춤 모임을 추천합니다.

입력 예시

{
  "user_id": "user_abc",
  "interaction_history": [
    { "group_id": "001", "action": "viewed" },
    { "group_id": "123", "action": "joined" }
  ]
}

입력 필드 명세

필드명 타입 필수 설명
user_id string 예 사용자 ID
interaction_history array 예 사용자 모임 상호작용 내역
interaction_history[].group_id string 예 모임 ID
interaction_history[].action string 예 행동 종류 (예: viewed, joined)

출력 예시

{
  "results": [
    { "group_id": "789", "group_name": "API 개발 집중반" }
  ]
}

공통 오류 처리 → 아래 참고

3. 공통 오류 처리 명세

상태 코드 설명 예시 메시지
400 Bad Request 필수 입력값 누락 또는 JSON 포맷 오류 { "message": "요청에 잘못된 형식이 포함되어 있거나, 필수 입력값이 누락되었습니다.", "code": "INVALID_REQUEST" }
403 Forbidden 인증은 되었지만 권한 없음 { "message": "이 기능에 접근할 권한이 없습니다.", "code": "FORBIDDEN" }
429 Too Many Requests 요청 과다로 인한 제한 { "message": "요청이 너무 많습니다. 잠시 후 다시 시도해주세요.", "code": "RATE_LIMIT_EXCEEDED" }
500 Internal Server Error AI 모델 예외 처리 실패 { "message": "AI 모델 응답 처리 중 문제가 발생했습니다.", "code": "MODEL_GENERATION_FAILED" }
503 Service Unavailable 서비스 비가동 상태 { "message": "AI 생성 서비스가 현재 사용 불가능합니다. 잠시 후 다시 시도해주세요.", "code": "SERVICE_UNAVAILABLE" }