수업에서 사용하는 도구¶
이 과정의 도구는 AI 서비스를 새로 구축하기보다 이미 준비된 데이터, 모델, 실행 환경의 상태를 확인하기 위해 사용합니다. 수강생은 도구 이름을 외우는 대신 어떤 질문에 어떤 도구를 사용하는지 구분하면 됩니다.
도구를 처음 확인하는 활동은 별도의 결과물을 작성하거나 제출하는 실습이 아닙니다. 화면이 열리고 필요한 상태를 확인할 수 있으면 다음 학습으로 넘어갑니다. 품질 판단과 기록이 필요한 활동은 각 교시의 Lab에서 따로 안내합니다.
도구를 구분하는 방법¶
표준 도구, 관리형 서비스, 과정 제공 환경¶
같은 화면에서 사용하더라도 일반적인 기술과 이 과정을 위해 준비한 환경은 구분해야 합니다. 예를 들어 Docker와 Kubernetes는 여러 환경에서 사용할 수 있는 표준 도구이고, 수업용 baseline API는 이번 과정을 위해 미리 준비한 실행 환경입니다.
관리형 서비스는 설치해서 운영하는 프로그램이 아니라 계정과 주소를 통해 접속하는 외부 서비스입니다. GitHub와 Grafana Cloud가 여기에 해당합니다. 수강생은 과정에서 필요한 기능만 사용하며 서비스 전체를 구축하지 않습니다.
과정 제공 환경과 사전 구축 플랫폼은 강의 진행을 위해 준비된 구성입니다. 수강생은 정상 동작 여부와 주요 화면을 확인하지만, 설치와 운영까지 모두 담당하지 않습니다.
| 구분 | 주요 항목 | 과정에서의 범위 |
|---|---|---|
| 표준 도구 | Git, Python, DVC, Docker, MLflow, Kubernetes, Helm, k9s | 코드를 실행하고 데이터, 모델, 배포 상태를 확인합니다 |
| 관리형 서비스 | GitHub, GitHub Container Registry, Grafana Cloud | 저장소, 이미지, 관측 화면에 접속합니다 |
| 과정 제공 환경 | baseline API, traffic generator, 준비된 데이터와 결과 | 같은 출발점과 확인 대상을 제공합니다 |
| 사전 구축 플랫폼 | k3s, KServe, Argo CD, ingress | 배포와 운영 구조를 관찰하고 지정된 연결 작업을 수행합니다 |
이 구분은 책임 범위를 이해하기 위한 안내입니다. 표준 도구를 사용한다고 해서 수강생이 모든 설치와 운영을 맡는 것은 아니며, 사전 구축된 환경을 확인했다고 해서 전체 플랫폼을 구축한 것도 아닙니다.
공통 실행 환경¶
코드를 받고 실행하는 도구¶
공통 실행 환경은 실습 코드를 같은 조건에서 열고 실행하기 위한 도구로 구성합니다. Git으로 저장소를 받고, Visual Studio Code에서 파일과 터미널을 열며, Python 3.11과 uv로 필요한 Python 패키지를 맞춥니다.
Jupyter는 코드를 작은 단계로 실행하며 입력과 출력을 확인할 때 사용합니다. notebook은 일반 Python 파일처럼 실행하지 않고, Visual Studio Code 또는 Jupyter 화면에서 셀 순서대로 실행합니다.
curl은 API가 응답하는지 터미널에서 빠르게 확인하는 보조 명령입니다. 별도의 JSON 처리 명령을 학습 대상으로 추가하지 않으며, 복잡한 확인은 제공된 notebook이나 실습 화면에서 진행합니다.
| 도구 | 하는 일 | 수강생이 확인하는 것 |
|---|---|---|
| Git과 GitHub | 실습 코드와 변경 이력을 가져옵니다 | 지정된 저장소와 리비전 |
| Visual Studio Code | 파일, 터미널, notebook을 한곳에서 엽니다 | 실습 파일과 실행 위치 |
Python 3.11과 uv |
Python 버전과 패키지 환경을 맞춥니다 | 실습 코드가 같은 환경에서 실행되는지 |
| Jupyter | 코드와 결과를 셀 단위로 확인합니다 | 중간 계산과 최종 출력 |
curl |
HTTP 경로를 호출합니다 | 상태 코드와 응답 여부 |
공통 도구는 분석 결과를 대신 판단하지 않습니다. 명령이 성공했다는 사실은 실행 준비가 됐다는 뜻이며, 데이터 품질이나 모델 품질이 통과했다는 뜻은 아닙니다.
데이터와 모델 품질에 사용하는 도구¶
실행 중인 API와 데이터 품질 확인¶
1일차 오전에는 이미 baseline 모델이 배포된 API를 호출해 실행 중인 AI 서비스의 응답 구조를 먼저 확인합니다. 이 확인은 서비스의 출발점을 이해하기 위한 활동이며, 응답값을 별도 보고서에 옮기지 않습니다.
이후 pandas로 데이터의 구조와 값을 살펴보고, DVC로 데이터 버전과 변경 상태를 확인합니다. Great Expectations와 pytest는 사람이 확인한 데이터 규칙을 반복 가능한 검사로 확인할 때 사용합니다.
scikit-learn은 분류 결과와 지표가 만들어지는 과정을 이해하는 데 사용합니다. 이 과정의 목적은 모델 성능을 높이는 것이 아니라 같은 평가 조건에서 결과를 읽고 비교하는 것입니다.
| 도구 | 과정에서 하는 일 | 확인하고 넘어갈 내용 |
|---|---|---|
| baseline API | 이미 실행 중인 서비스의 응답을 확인합니다 | API가 준비됐고 기준 모델로 응답하는지 |
| pandas | 데이터 행, 열, 결측과 값의 범위를 살펴봅니다 | 실제 구조가 설명과 같은지 |
| DVC | 데이터와 파이프라인의 버전을 관리합니다 | 어떤 데이터 리비전을 사용하고 있는지 |
| Great Expectations | 데이터 규칙을 검사합니다 | 어떤 규칙이 통과하거나 실패했는지 |
| pytest | 자동 검사 코드를 실행합니다 | 기대한 검사가 실행되는지 |
| scikit-learn | 모델 평가와 분류 지표 계산을 수행합니다 | 점수, 임계값, 예측과 지표의 관계 |
각 도구의 성공 메시지는 서로 대신할 수 없습니다. DVC 상태가 맞아도 데이터 규칙이 자동으로 통과하지 않으며, 데이터 검사가 통과해도 후보 모델이 승인되는 것은 아닙니다.
서빙과 운영에 사용하는 도구¶
컨테이너와 MLflow¶
Docker는 애플리케이션과 실행 환경을 이미지로 묶고 컨테이너로 실행하는 방식을 확인할 때 사용합니다. OCI는 이미지의 manifest와 layer를 여러 도구와 registry에서 공통으로 다루기 위한 규약으로 소개합니다.
Docker Compose는 API와 MLflow처럼 함께 사용하는 서비스를 정의하고 실행합니다. 컨테이너 실습에서는 제공된 Compose 설정으로 MLflow 컨테이너를 올리고 웹 화면이 열리는지 확인합니다.
MLflow에서는 Experiment와 Run, metric, parameter, 실행 ID와 모델 산출물이 어떻게 연결되는지 살펴봅니다. MLflow 화면이 열렸다는 사실은 추적 서버가 준비됐다는 뜻이며, 특정 모델이 승인되거나 배포됐다는 뜻은 아닙니다.
| 도구 | 과정에서 하는 일 | 확인하고 넘어갈 내용 |
|---|---|---|
| Docker | 이미지에서 격리된 실행 인스턴스를 만듭니다 | 이미지와 실행 중인 컨테이너의 차이 |
| OCI | 이미지 manifest와 layer의 공통 형식을 정의합니다 | 이미지 이름과 내용 지문의 차이 |
| Docker Compose | 여러 컨테이너와 연결 설정을 함께 실행합니다 | API와 MLflow 서비스 상태 |
| MLflow | 모델 실험과 실행 정보를 한 화면에서 비교합니다 | Experiment, Run, metric, parameter, 실행 ID와 모델 산출물 |
컨테이너 실행 확인과 모델 상태 확인은 다른 질문입니다. MLflow 컨테이너와 API 컨테이너가 정상이어도 두 화면이 같은 모델 실행을 가리키는지는 별도로 확인해야 합니다.
Kubernetes 배포 환경¶
Kubernetes 도구는 같은 클러스터의 선언과 실행 상태를 서로 다른 방식으로 확인합니다. k3s는 수강생 VM에서 사용하는 가벼운 Kubernetes 배포판이며, KServe는 모델을 예측 서비스 형태로 제공하는 Kubernetes 구성요소입니다.
Helm은 여러 Kubernetes 리소스를 Chart로 묶고 values.yaml로 환경별 값을 적용하는 방식을 소개할 때 사용합니다. 수강생은 Chart를 처음부터 개발하기보다 제공된 Chart의 구성과 렌더링 결과를 확인합니다.
kubectl과 k9s는 모두 kubeconfig의 context와 자격증명을 이용해 Kubernetes API Server와 통신합니다. kubectl은 명령으로 객체와 상태를 조회하고, k9s는 Pod, Deployment, Service와 이벤트를 대화형 화면에서 확인합니다.
| 도구 | 과정에서 하는 일 | 확인하고 넘어갈 내용 |
|---|---|---|
| Kubernetes와 k3s | 컨테이너 실행과 네트워크 상태를 관리합니다 | 선언한 객체와 실제 상태의 차이 |
| Helm | 관련 Kubernetes 리소스와 설정값을 묶습니다 | Chart, template, values.yaml의 관계 |
kubectl |
API Server를 통해 객체와 상태를 명령으로 조회합니다 | context, 리소스, 준비 상태 |
| k9s | Kubernetes 객체와 이벤트를 화면에서 탐색합니다 | Pod 상태, 로그 위치, 이벤트 |
| KServe | 모델 파일을 예측 서비스와 연결합니다 | 예측 실행 단위와 API 연결 구조 |
Helm release가 만들어졌거나 Kubernetes 객체가 보인다는 사실만으로 서비스 준비를 확정하지 않습니다. 실제 Pod 상태와 Service 연결, 예측 요청은 서로 다른 확인 단계입니다.
GitOps와 배포 상태¶
Argo CD는 Git에 기록된 목표 상태와 Kubernetes의 현재 상태를 비교하고 반영하는 GitOps 도구입니다. 이 과정에서는 공유 Argo CD에 연결된 자기 k3s 클러스터와 지정된 Git 저장소를 구분하고 제공된 배포 화면을 확인합니다.
GitHub fine-grained personal access token은 Argo CD가 지정된 비공개 저장소를 읽는 연결에 사용합니다. 연결 주체와 절차는 해당 GitOps Lab의 안내를 따르며, 토큰 값은 명령 예시, 문서, 화면 캡처에 남기지 않습니다.
Argo CD의 Synced와 Healthy는 다른 질문에 답합니다. Synced는 Git의 목표가 반영됐는지, Healthy는 반영된 리소스가 준비 상태인지 보여 주며, 실제 API 요청 성공은 다시 별도로 확인합니다.
| 도구와 서비스 | 과정에서 하는 일 | 확인하고 넘어갈 내용 |
|---|---|---|
| Argo CD | Git 목표와 클러스터 상태를 비교합니다 | 연결된 클러스터와 저장소, 동기화와 준비 상태 |
| GitHub fine-grained PAT | Argo CD의 지정 저장소 연결에 읽기 권한을 제공합니다 | 해당 Lab에서 안내한 범위의 저장소 연결 상태 |
| GitHub Container Registry | 컨테이너 이미지를 저장하고 제공합니다 | 배포 선언이 가리키는 이미지 |
저장소 연결과 클러스터 등록은 배포 완료가 아닙니다. 연결 확인을 마치면 목표 상태, 준비 상태, 실제 요청을 구분하는 다음 설명으로 넘어갑니다.
운영 상태를 확인하는 도구¶
관측 도구는 애플리케이션이 만든 지표, 로그, 처리 경로를 수집하고 조회하기 위해 사용합니다. OpenTelemetry는 관측 신호의 공통 형식을 제공하고, Alloy는 이 신호를 수집해 저장소로 전달합니다.
Prometheus 호환 저장소는 지표, Loki는 로그, Tempo는 처리 경로를 저장합니다. Grafana Cloud는 저장된 신호를 대시보드와 Explore 화면에서 함께 확인하는 관리형 서비스입니다.
수강생은 관측 시스템을 처음부터 구축하지 않습니다. 준비된 연결과 화면에서 시간 범위, 모델, 상태 코드와 요청 식별값이 같은 사건을 가리키는지 확인합니다.
| 도구와 서비스 | 과정에서 하는 일 | 확인하고 넘어갈 내용 |
|---|---|---|
| OpenTelemetry | 지표, 로그, 처리 경로의 공통 형식을 제공합니다 | 애플리케이션이 만드는 신호의 종류 |
| Alloy | 관측 신호를 수집하고 전달합니다 | 수집 대상과 전송 경로 |
| Prometheus 호환 저장소 | 시간에 따른 지표를 저장합니다 | 요청 수, 지연, 상태 코드 변화 |
| Loki | 구조화 로그를 저장합니다 | 한 요청의 상태와 모델 정보 |
| Tempo | 요청 처리 구간을 저장합니다 | 어느 구간에서 시간이 걸렸는지 |
| Grafana Cloud | 여러 관측 신호를 화면에서 조회합니다 | 조사할 시간 범위와 연결할 신호 |
Grafana에서 함께 움직이는 신호를 봤다고 해서 원인이 확정되는 것은 아닙니다. 대시보드는 조사할 범위를 좁히고 다음에 확인할 로그와 처리 경로를 찾는 화면입니다.
과정에서 별도로 제공하는 구성요소¶
강의를 위해 준비한 환경과 자동화¶
과정 제공 구성요소는 제한된 수업 시간에 모든 수강생이 같은 출발점에서 확인하도록 준비한 자산입니다. 일반적으로 설치해 사용하는 제품과 과정 전용 자동화를 같은 종류의 도구처럼 설명하지 않습니다.
baseline API와 traffic generator는 이미 실행 중인 서비스와 반복 가능한 요청을 제공합니다. 준비된 데이터와 결과는 실행 환경이 막혔을 때 확인 범위를 이해하기 위한 대체 경로이며, 직접 실행한 결과와 같다고 말하지 않습니다.
preflight와 Grafana Dashboard Importer는 수업 환경을 준비하고 확인하기 위한 자동화입니다. 수강생이 도구 자체를 학습하거나 새로 구현하는 대상은 아닙니다.
| 과정 제공 구성요소 | 제공하는 것 | 수강생의 범위 |
|---|---|---|
| baseline API | 첫 수업부터 확인할 수 있는 기준 서비스 | 준비 상태와 응답 구조를 확인합니다 |
| traffic generator | 같은 형식의 정상 요청과 오류 요청 | 실행 결과와 상태 변화를 확인합니다 |
| 준비된 데이터와 결과 | 공통 비교 대상과 실행 대체 경로 | 제공 범위와 한계를 확인합니다 |
| preflight | 실습 전 환경 상태 검사 | 준비 또는 차단 상태를 확인합니다 |
| Grafana Dashboard Importer | 과정용 대시보드 준비 | 제공된 대시보드가 열리는지 확인합니다 |
| 사전 구축 플랫폼 | k3s, KServe, Argo CD와 연결 환경 | 지정된 조회와 연결 확인만 수행합니다 |
과정 제공 자동화가 성공해도 개별 품질 판단이 자동으로 끝나는 것은 아닙니다. 이 페이지에서는 어떤 구성요소가 준비됐는지만 이해하고, 구체적인 실행과 해석은 각 교시의 Core와 Lab에서 진행합니다.