Qt 데스크톱에서 만든 오목 AI를 웹으로 옮기려면 브라우저 상태, Next.js API와 내부 모델 서버 사이의 계약이 필요하다. 이 소스는 판 배열을 받아 VLM 착수를 요청하고 검증된 좌표만 클라이언트에 돌려준다.

오목 Next.js 웹과 VLM 착수 API 연결하기 핵심 도식
그림. 웹 요청을 검증한 뒤 내부 VLM 게이트웨이에 전달하고 오류 종류를 HTTP 상태로 구분한다.

요청 계약

POST 본문은 board 배열, 판 크기, AI 돌 색을 가진다. 돌 색은 1 또는 2, 크기는 허용 목록, 배열 길이는 `size × size`인지 먼저 검사한다. 잘못된 JSON과 schema 오류는 모델 서버에 보내지 않고 400으로 끝낸다.

내부 게이트웨이

API route는 `requestOmk3Move`를 호출한다. 모델 연결 거부나 timeout처럼 일시적인 장애는 503, 잘못된 upstream 응답은 502로 구분한다. 성공 응답은 `{type: "move", row, col}`이라는 작은 형식으로 제한한다.

추가로 필요한 검증

현재 판에서 반환 좌표가 범위 안이고 빈칸인지 API 경계에서도 다시 확인하는 것이 좋다. 클라이언트가 보낸 판을 신뢰해 승패를 결정하지 말고 서버가 game id와 move sequence를 관리해야 동시 요청과 조작을 막을 수 있다.

배포 안전

모델 포트는 공개하지 않고 웹 애플리케이션만 내부 연결한다. 요청 크기 제한, 사용자별 속도 제한, 모델 timeout과 취소를 둔다. 오류 메시지에는 내부 주소, 모델 경로와 stack trace를 넣지 않는다.

관련 소스

  • `omook-web/app/api/vlm/move/route.ts`: 요청 검증과 상태 코드
  • `omook-web/lib/omk3Client.ts`: 내부 모델 client
  • `omook-web/components/OmokBoard.tsx`: 브라우저 판