실습 환경 준비¶

오늘 할 일은 강사가 안내한 수업용 공개 HTTPS 베이스를 확인하고, 그 주소 뒤에 경로를 붙여 기준 모델을 확인하는 것입니다. 프로그램 설치와 저장소 준비는 그 주소를 쓰기 위한 준비입니다. 공개 API는 브라우저나 터미널에서 확인하고, 로컬 실습 명령은 저장소 루트에서 실행합니다.

설치하기 전에 수업에서 사용하는 도구에서 각 도구가 어느 교시에 어떻게 쓰이는지 먼저 확인합니다. 이 페이지에서는 실제 설치와 접속 준비만 진행합니다.

오늘 끝내는 일

내 컴퓨터에 프로그램을 설치합니다.
강사가 안내한 수업용 공개 HTTPS 베이스를 확인합니다.
tta-aiqa 저장소를 준비하고 uv sync를 실행합니다.
저장소 루트에서 필요한 확인 명령을 실행합니다.
공개 베이스의 /docs에서 준비 상태와 예측 요청을 확인합니다.

프로그램 설치¶

Windows를 쓰는 사람이 많습니다. Windows는 Git Bash와 VS Code가 필요합니다. Git Bash는 명령을 입력하는 창입니다. macOS와 Linux는 VS Code만 설치하면 됩니다.

Windows¶

Git for Windows를 받아 설치합니다. 설치 창이 여러 장 나와도 다음(Next)을 눌러 기본값으로 마칩니다.

설치가 끝나면 Windows 시작 단추를 누르고 Git Bash를 검색해 엽니다. 이후 실습 저장소 준비 절에서 명령을 실행합니다.

Visual Studio Code를 받아 설치합니다. VS Code를 연 뒤 왼쪽 세로 막대에서 네모가 네 개인 아이콘을 누릅니다. 이 아이콘이 확장(Extension)입니다. 또는 키보드에서 Ctrl+Shift+X를 눌러도 됩니다.

macOS와 Linux¶

Visual Studio Code를 설치합니다. 명령을 입력하는 창(터미널, terminal)을 열어 저장소 명령을 실행합니다.

수업용 실행 환경¶

강사가 제공한 개발 환경 안내를 따릅니다. 공개 교안에는 환경별 상세 정보를 기록하지 않습니다.

공개 HTTPS 베이스를 확인하지 못하면 주소를 추측하지 않습니다. 준비된 결과를 확인하고, 직접 실행하지 못한 범위와 이유를 기록합니다.

VS Code로 가상 컴퓨터 접속하기¶

실습 명령은 강사가 준비한 Linux 가상 컴퓨터에서 실행합니다. VS Code의 확장 화면에서 Microsoft가 제공하는 Remote - SSH를 설치한 뒤, SSH 설정 파일에 수업용 접속 정보를 추가합니다.

키보드에서 F1을 누르거나 Windows는 Ctrl+Shift+P, macOS는 Cmd+Shift+P를 눌러 명령 팔레트를 엽니다. Remote-SSH: Open SSH Configuration File...을 선택하고 내 사용자 폴더 아래의 .ssh/config를 엽니다. 파일이 없으면 VS Code가 새로 만듭니다.

접속 이름과 사용자 이름은 그대로 두고, HostName과 ProxyJump만 강사가 안내한 값으로 바꿉니다. 실제 IPv4, 중간 서버 주소와 비밀번호는 공개 교안이나 제출 파일에 적지 않습니다.

Host tta-lab
  HostName 화면에서-확인한-가상-컴퓨터-IPv4
  User tta
  ProxyJump 강사가-안내한-계정@중간서버
  PreferredAuthentications password
  PubkeyAuthentication no

각 줄은 접속할 대상과 중간 경로를 구분합니다. 값을 바꿀 때는 줄 이름과 들여쓰기를 유지합니다.

설정	의미	수강생이 할 일
`Host tta-lab`	VS Code에 표시할 접속 이름	바꾸지 않습니다
`HostName`	실습할 가상 컴퓨터의 SSH 주소	화면에서 확인한 자기 VM의 IPv4로 바꿉니다
`User tta`	가상 컴퓨터의 사용자 이름	바꾸지 않습니다
`ProxyJump`	가상 컴퓨터로 연결할 때 거치는 중간 서버	강사가 안내한 `계정@호스트`로 바꿉니다
인증 설정 두 줄	공개키 인증을 끄고 수업용 비밀번호 인증만 사용	바꾸거나 지우지 않습니다

비밀번호는 .ssh/config에 적지 않습니다. 설정을 저장한 뒤 명령 팔레트에서 Remote-SSH: Connect to Host...를 선택하고 tta-lab에 연결합니다. 처음 보는 호스트인지 묻는 경우에는 화면에 표시된 SHA-256 host key fingerprint를 강사가 별도 채널로 안내한 값과 비교하고, 값이 없거나 다르면 연결을 중단합니다.

새 VS Code 창이 열리면 원격 가상 컴퓨터에 접속한 상태입니다. 다음 절의 저장소 준비와 이후 실습 명령은 이 창에서 연 터미널에 입력합니다. 연결되지 않으면 HostName, User, ProxyJump를 한 번 확인하고 실제 주소나 비밀번호를 화면에 공유하지 않은 채 강사에게 알립니다.

실습 저장소 준비¶

실습 코드는 tta-aiqa 저장소에 있습니다. 원격 가상 컴퓨터의 터미널에서 복제한 뒤, 의존성을 맞춥니다.

VS Code 안에서 명령을 입력하는 창을 엽니다. 메뉴의 터미널에서 새 터미널(New Terminal)을 고르거나, 키보드에서 Ctrl+` 를 누릅니다.

git clone https://github.com/seungbaeji/tta-aiqa.git
cd tta-aiqa
git switch --detach 508293c12a5a70e24c583055de8e100dddccc6d7
uv sync --all-packages --group notebook --group dev

복제가 끝나면 tta-aiqa 폴더가 생깁니다. 왼쪽 위 파일 메뉴에서 폴더 열기(Open Folder)를 누르고 그 폴더를 고릅니다. 이후 파일과 노트북(notebook), 명령을 입력하는 창은 모두 그 폴더 안입니다.

이번 과정의 실행 지침

공개 교재에 적힌 명령만 수강생 실행 지침으로 사용합니다. 고정한 실습 저장소 리비전의 자체 README에는 Candidate B 모델 게시와 GitOps 동기화 절차가 포함되어 있지만, 이번 과정에서 수강생이 실행하는 경로가 아닙니다. Application 생성, 모델 게시, 배포 동기화와 되돌리기는 강사와 플랫폼 담당자가 수행합니다. 수강생은 정적 설정 검사와 제공된 대상 상태를 읽고, 확인하지 못한 단계는 target_pending으로 남깁니다.

uv sync는 몇 분이 걸릴 수 있습니다. 오류 없이 끝나면 실습을 시작할 수 있습니다. 내 노트북에서 같은 명령을 실행한 결과는 수업 근거로 쓰지 않습니다.

수업에서 여는 Risk API 주소¶

수업에서 확인하는 Risk API는 강사가 안내한 공개 HTTPS 베이스입니다. 로컬 Compose는 http://127.0.0.1:8000에서 실행하며, 공개 API와 로컬 루프백은 서로 다른 확인 범위입니다. 공개 베이스나 로컬 주소에 없는 환경의 주소를 추측하지 않습니다.

공개 베이스 뒤에 확인하려는 기능의 경로를 붙입니다. 공개 베이스와 로컬 Compose 결과를 같은 환경의 근거로 합치지 않습니다.

경로	하는 일
`/health/ready`	기준 모델이 요청을 받을 준비가 됐는지 확인합니다
`/v1/model`	지금 돌아가는 모델 이름과 특성 개수를 확인합니다
`/docs`	Swagger UI. 경로를 보고 Try it out으로 GET과 예측 요청을 보냅니다
`/redoc`	ReDoc. 같은 경로와 요청·응답 필드를 읽습니다. 여기서는 요청을 보내지 않습니다
`/openapi.json`	OpenAPI 스펙을 JSON으로 받습니다
`/v1/predict`	특성 값을 넣어 예측합니다. 주소창에 치면 안 되고, `/docs`의 Try it out을 씁니다

브라우저에서 /docs를 열면 FastAPI가 만든 Swagger 화면이 나옵니다. /redoc은 같은 계약을 읽기 쉽게 보여 줍니다. 값을 넣어 호출하는 화면은 Swagger입니다. KServe의 /v2/models/.../infer는 이 목록에 없습니다.

준비 상태와 모델 이름은 Swagger에서 GET /health/ready, GET /v1/model을 열고 Try it out과 Execute를 누르면 됩니다. 본문이 필요 없습니다.

터미널에서는 AIQA_RISK_API_URL을 강사가 안내한 공개 HTTPS 베이스로 설정한 뒤 다음 명령을 실행합니다.

curl -sS "${AIQA_RISK_API_URL:?Risk API base URL is required}/health/ready"
curl -sS "${AIQA_RISK_API_URL:?Risk API base URL is required}/v1/model"

/health/ready는 HTTP 200과 status=ready, model_version=baseline-f2576f12512a를 돌려줘야 합니다. /v1/model은 HTTP 200과 backend=kserve, profile=baseline, feature_count=133, education_only=true를 돌려줘야 합니다. 이 응답은 기준 모델이 요청을 받을 준비가 됐다는 뜻이며, 예측 비율 변화의 원인을 설명하지 않고 Candidate B 배포 완료도 뜻하지 않습니다.

POST /v1/predict는 133개 특성의 이름과 자료형을 모두 만족하는 요청이 필요합니다. 일부 측정값만 손으로 넣은 요청은 누락 입력으로 HTTP 422가 되며, 서버가 나머지를 자동으로 채우지 않습니다. 정상 200과 의도한 422는 서빙 실습의 트래픽 생성기와 노트북이 만드는 완전한 요청으로 확인합니다. /redoc에서는 요청·응답 필드를 읽을 수 있지만 Execute는 없습니다.

정상 요청의 HTTP 200에는 model_profile, threshold, education_only, score, prediction이 있습니다. score와 prediction은 입력마다 달라지므로 숫자를 보고서에 고정하지 않습니다. 한 요청의 HTTP 200은 API 규약을 통과했다는 뜻이며, 운영 예측 비율이 늘어난 이유나 Candidate B 배포 완료로 기록하지 않습니다. 경로의 의미와 응답 필드는 컨테이너와 예측 API에서 이어서 읽습니다.