[AI] API 설계 - 100-hours-a-week/21-iceT-wiki GitHub Wiki

📚 Model API Design

0. 목적

백준 기반 학습 서비스에서 사용되는 3가지 AI 지원 기능(문제 해설 생성, 코드 리뷰, 모의 면접)을 제공하는 REST-first 인터페이스입니다. 모든 엔드포인트는 JSON 형식의 요청/응답을 따르며, 응답 시간은 Asia/Seoul (UTC+09:00) 기준의 ISO 8601 형식을 사용합니다.

1. 엔드포인트 목록 및 기능

# 그룹 Method Endpoint 설명
1 해설 POST /api/v1/solution 백준 문제 정보를 받아 언어별 해설 생성
2 피드백 POST /api/v1/feedback/start 사용자가 제출한 코드로 피드백 세션 시작
POST /api/v1/feedback/answer 피드백 세션 중 사용자의 질문에 응답
3 면접 POST /api/v1/interview/start 코드 기반 모의 면접 세션 생성
POST /api/v1/interview/answer 면접 답변 평가 후 다음 질문 제공
POST /api/v1/interview/end 면접 세션 종료 및 최종 평가 반환

2. API 요청/응답 예시

/api/v1/solution : 백준 문제 정보를 받아 언어별 해설 생성

  • Request
{
  "problem_number": 1000,
  "title": "A+B",
  "description": "두 정수 A와 B를 입력받은 다음, A+B를 출력하는 문제",
  "input_example": "1 2",
  "output_example": "3",
  "language": "python"
}
  • Response
{
  "language": "python",
  "problem_check": {
    "problem_description": "A와 B가 주어지고 두 수의 합을 구해야 합니다.",
    "algorithm": "단순한 수 입력 및 합 계산을 하는 구현 문제입니다."
  },
  "problem_solving": "+연산자를 사용해서 해결합니다.",
  "solution_code": "a, b = map(int, input().split())\nprint(a + b)"
}

/api/v1/feedback/start : 사용자가 제출한 코드로 피드백 세션 시작

  • Request
{
  "user_id": "abc123",
  "problem": {
    "problem_number": 1040,
    "title": "가격표",
    "description": "가격표 중 가장 비싼 물품과 가장 저렴한 물품 찾기",
    "input_example": "2000 3000 5000 1000",
    "output_example": "5000 1000",
  }
  "user_code": "N = int(input())\nname = []\nprice = []\nfor _ in range(N):\nS, P = input().split()..."
}
  • Response
{
  "session_id": "f4c2a1e0-1234-4567-890a-abcdef123456",
  "title": "정렬 알고리즘 개선 피드백",
  "message": "사용하신 sorted 함수는 기본적인 정렬에는 적절하지만...",
  "timestamp": "2025-04-16T18:25:00"
}

/api/v1/feedback/answer : 피드백 세션 중 사용자의 질문에 응답

  • Request
{
  "session_id": "f4c2a1e0-1234-4567-890a-abcdef123456",
  "content": "이 코드의 시간복잡도는 어떻게 되나요?"
}
  • Response
{
  "session_id": "f4c2a1e0-1234-4567-890a-abcdef123456",
  "message": "해당 코드에서 sorted 함수는 Timsort 알고리즘을 기반으로 하며, 평균 시간 복잡도는 O(n log n)입니다.",
  "timestamp": "2025-04-16T19:30:00"
}

/api/v1/interview/start : 코드 기반 모의 면접 세션 생성

  • Request
{
  "user_id": "abc123",
  "problem": {
    "problem_number": 1040,
    "title": "가격표",
    "description": "가격표 중 가장 비싼 물품과 가장 저렴한 물품 찾기",
    "input_example": "2000 3000 5000 1000",
    "output_example": "5000 1000",
  }
  "user_code": "N = int(input())\nname = []\nprice = []\nfor _ in range(N):\nS, P = input().split()..."
}
  • Response
{
  "question_id": 1
  "session_id": "f4c2a1e0-1234-4567-890a-abcdef123456",
  "title": "정렬 문제 모의 면접",
  "question_message": "이 코드의 시간복잡도를 설명해주세요.",
  "timestamp": "2025-04-16T18:25:00"
}

/api/v1/interview/answer : 면접 답변 평가 후 다음 질문 제공

  • Request
{
  "session_id": "f4c2a1e0-1234-4567-890a-abcdef123456",
  "answer_message": "O(1)입니다. 입력값이 고정이기 때문입니다.",
  "question_id": 1
}
  • Response
{
  "session_id": "f4c2a1e0-1234-4567-890a-abcdef123456",
  "next_question": {
    "question_id": 2,
    "question_message": "이 코드에서 개선 가능한 부분이 있다면 설명해주세요."
  },
  "timestamp": "2025-04-16T18:27:00"
}

/api/v1/interview/end : 면접 세션 종료 및 최종 평가 반환

  • Request
{
  "session_id": "f4c2a1e0-1234-4567-890a-abcdef123456"
}
  • Response
{
  "session_id": "f4c2a1e0-1234-4567-890a-abcdef123456",
  "overall_feedback": "이번 모의 면접에서는 시간복잡도 설명이 매우 정확했고, 코드 개선 제안이 구체적이었습니다. 다만 예외 처리 부분에서 약간의 보완이 필요해 보입니다.",
  "question_feedbacks": [
    {
      "question_id": 1,
      "your_answer": "O(1)입니다. 입력값이 고정이기 때문입니다.",
      "feedback_message": "정확합니다! 입력 크기에 따라 실행 시간이 변하지 않으므로 O(1)입니다."
    },
    {
      "question_id": 2,
      "your_answer": "리스트를 정렬하는 부분에서 in-place sort를 사용하면 메모리 효율이 높아집니다.",
      "feedback_message": "좋은 지적입니다. 다만 정렬 라이브러리 사용 대신 병합 정렬 구현을 직접 제안하는 것도 좋았습니다."
    }
  ],
  "final_score": 87,      
  "timestamp": "2025-04-16T18:40:00"
}

공통 에러 응답 예시

  • 400 Bad Request
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "입력 형식이 잘못되었습니다. problem_number는 필수입니다.",
    "hint": "필수 필드 누락 여부를 확인하세요."
  }
}
  • 500 Internal Server Error
{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "모델 추론 중 오류가 발생했습니다.",
    "hint": "서버 로그를 확인하거나 모델 상태를 점검하세요."
  }
}

3. 입력/출력 스키마

3.1 POST /api/v1/solution

Request Body

필드 타입
problem_number int
title string
description string
input_example string
output_example string
language string

Success Response (200)

필드 타입
language string
problem_check object
└ problem_description string
└ algorithm string
problem_solving string
solution_code string

3.2 POST /api/v1/feedback/start

Request Body

필드 타입
user_id string
problem object
└ problem_number int
└ title string
└ description string
└ input_example string
└ output_example string
user_code string

Success Response (200)

필드 타입
session_id string
title string
message string
timestamp string (ISO 8601)

3.3 POST /api/v1/feedback/answer

Request Body

필드 타입
session_id string
content string

Success Response (200)

필드 타입
session_id string
message string
timestamp string (ISO 8601)

3.4 POST /api/v1/interview/start

Request Body

필드 타입
user_id string
problem object
└ problem_number int
└ title string
└ description string
└ input_example string
└ output_example string
user_code string

Success Response (200)

필드 타입
question_id int
session_id string
title string
question_message string
timestamp string (ISO 8601)

3.5 POST /api/v1/interview/answer

Request Body

필드 타입
session_id string
answer_message string
question_id int

Success Response (200)

필드 타입
session_id string
next_question object
└ question_id int
└ question_message string
timestamp string (ISO 8601)

3.6 POST /api/v1/interview/end

Request Body

필드 타입
session_id string

Success Response (200)

필드 타입
session_id string
overall_feedback string
question_feedbacks array
└ question_id int
└ your_answer string
└ feedback_message string
final_score int
timestamp string

3.7 Error Response (400 / 500)

필드 타입
error object
└ code string
└ message string
└ hint string (optional)

4. 서비스 구조

        Client
          │
          ▼
 ┌──────────────────────────┐
 │ FastAPI Endpoint Layer   │
 └────────────┬─────────────┘
              ▼
         [ Controller ]
              ▼
         [ Service Logic ]
        ┌────────┬────────┬────────────────────────────┐
        │Solution│Feedback│Interview Orchestrator      │
        └────────┴────────┴──────────────┬─────────────┘
                                         ▼
                              [ core/model ↔ core/database ]

공통 데이터 흐름

  • 사용자가 문제 정보, 코드 등을 입력
  • FastAPI 라우터에서 요청을 수신한 후, Controller 계층으로 전달
  • Controller가 요청 수신 후 Service Logic으로 전달
  • Service Logic이 AI 모델을 호출하여 결과 생성
  • 결과를 Controller가 JSON 응답으로 클라이언트에 반환

공통 에러 응답

Status message data 예시
400 "invalid_request" null
500 "internal_server_error" null