초기에는 Custom Prompt만 잘 작성하면 원하는 장면을 추출할 수 있을 것이라 생각했으나,
실제로 진행해 보니 VLM 서술 방식, 고정 프롬프트, 후속 파이프라인의 동작 방식까지
예상보다 깊이 있게 고려해야 할 영역이 많았습니다.

이 글에서는 대규모 영상 AI 프로젝트에서 VLM Custom Prompt 최적화 과정을 정리합니다.
프롬프트 전략 비교, 테스트 자동화, 정량 평가, 인터페이스 설계 변경까지의 과정을 다룹니다.

본 포스팅의 프롬프트, 데이터, 수치는
실제 프로젝트 내용을 기반으로 일부 각색되었습니다.

1. 영상 추출에서의 VLM 활용

VLM의 아키텍처와 기본 개념은 폐쇄망 AI Solution 서비스 구성 및 배포에서 다뤘습니다.
이 글에서는 VLM을 영상 장면 추출에 적용할 때의 특성에 집중합니다.

이번 프로젝트에서 VLM은 프레임 묶음(10~20장)을 입력받아
해당 구간에서 무엇이 일어나고 있는지를 자연어로 서술합니다.

영상 서술에서는 프롬프트가 관찰 초점을 결정하므로, 프롬프트 설계가 추출 품질을 좌우합니다.

2. 프롬프트 엔지니어링 (Prompt Engineering)

프롬프트 엔지니어링은 AI 모델에 입력하는 지시문(프롬프트)을 설계·최적화하여
원하는 출력을 유도하는 기법입니다.

1. LLM 프롬프트 엔지니어링과의 차이

텍스트 전용 LLM에서의 프롬프트 엔지니어링은 주로 다음에 집중합니다:

• 역할 지정 (“너는 번역가다”)
• 출력 형식 지정 (“JSON으로 응답해”)
• Few-shot 예시 제공
• Chain-of-Thought 유도

VLM에서의 프롬프트 엔지니어링은
여기에 시각 정보의 해석 방향이 추가됩니다:

2. 할루시네이션 (Hallucination)

할루시네이션은 AI 모델이 입력에 존재하지 않는 내용을 사실인 것처럼 생성하는 현상입니다.
LLM에서는 학습 데이터에 없는 사실을 지어내는 형태로 나타나고,
VLM에서는 이미지에 없는 객체나 행동을 서술하는 형태로 나타납니다.

VLM 프롬프트는 문장을 생성하라는 지시가 아니라 영상에서 무엇을 볼지 지정하는 지시이므로,
프롬프트의 표현 하나가 다수 구간의 서술 결과에 영향을 줄 수 있습니다.

3. System Prompt vs User Prompt

LLM/VLM에 입력되는 프롬프트는 일반적으로 두 영역으로 나뉩니다.

System Prompt는 모델이 어떻게 동작할지 결정하고, User Prompt는 무엇을 할지 지시합니다.

ChatGPT 같은 서비스에서는 System Prompt가 사용자에게 보이지 않지만,
API를 직접 호출할 때는 messages의 role: "system"과 role: "user"로 구분하여 입력합니다.

messages = [
    {"role": "system", "content": "너는 영상 분석 전문가다..."},
    {"role": "user", "content": "이 영상에서 건물이 보이는 장면을 찾아줘"},
]

4. Custom Prompt의 위치

이번 프로젝트에서 Custom Prompt는 전체 프롬프트의 일부로,
시스템이 고정한 기본 프롬프트 위에 사용자가 추가하는 형태입니다.
앞서 설명한 User Prompt와는 다르며, 사용자가 UI에서 입력하는 가변 영역을 가리킵니다.

┌──────────────────────────────┐
│  시스템 고정 프롬프트 (수정 불가)   │
│  ┌────────────────────────┐  │
│  │ 기본 프롬프트            │  │
│  │ 작업 순서 프롬프트         │  │
│  │ 출력 형식 프롬프트    │  │
│  └────────────────────────┘  │
│                              │
│  ┌────────────────────────┐  │
│  │ Custom Prompt (수정 가능) │  │  ← 유일한 가변 영역
│  └────────────────────────┘  │
└──────────────────────────────┘

각 Custom Prompt는 다음 두 필드로 구성됩니다.

두 필드는 VLM 프롬프트에 하나의 줄로 결합됩니다.

인물이 등장하는 장면(의상 위주로 서술)

Custom Prompt는 사용자가 UI에서 직접 입력하는 영역이며,
이 프로젝트에서의 역할은 사용자가 원하는 장면을 효과적으로 추출할 수 있도록
작성 가이드를 설계하고 추출에 최적화된 인터페이스 구조를 제안하는 것이었습니다.
프롬프트 엔지니어링 대상이 Custom Prompt에 한정된다는 점이 핵심 제약이었습니다.

5. 영어 프롬프트 vs 한국어 프롬프트

프롬프트 엔지니어링이 확산되던 초기에는 논문·예제·벤치마크 대부분이 영어 기준이었기 때문에
영어 프롬프트가 사실상 기본값처럼 사용되었습니다.

• 레퍼런스가 영어 중심이라 시행착오가 상대적으로 적었고
• 당시에는 한국어 프롬프트에서 표현/출력 일관성이 떨어지는 경우도 종종 관찰되었습니다.

이번 프로젝트에서는 모든 Custom Prompt를 한국어로 작성했습니다.
모델 자체가 다국어 사전학습(multilingual pretraining)을 거친 최신 버전이었고,
임베딩 모델 또한 다국어 지원 모델을 사용했으며, 사용자가 한국어 기반 UI를 사용했기 때문에
쿼리-서술-후처리 전 과정을 동일 언어로 통일하는 것이 일관성 측면에서 유리했습니다.

영어 프롬프트는 별도로 비교 실험하지 않았으나,
동일 데이터셋에서 한국어 프롬프트의 출력 안정성과 후처리 일관성이 충분하다고 판단했습니다.

6. VLM은 언어를 타는가?

많은 VLM은 시각 정보가 언어 모델 출력으로 자연스럽게 이어지도록
시각-언어 정렬(alignment)을 거치며 학습됩니다.
이때 언어 모델이 어떤 언어 데이터로 얼마나 학습되었는지가 출력 안정성에 영향을 줍니다.

• 영어 중심 데이터로 학습된 모델 → 영어 프롬프트에 더 안정적인 편
• 다국어 학습 모델 → 한국어 포함 여러 언어에서 상대적으로 안정적

모델이 언어를 가린다기보다는,
학습 데이터의 분포와 토큰 통계에 영향을 받는다고 보는 것이 더 정확합니다.

실무에서 실제로 달라지는 부분은 다음과 같습니다.

VLM, 임베딩 모델 모두 다국어 지원 모델을 사용했고,
검색 쿼리도 한국어였으므로 전 과정을 한국어로 통일했습니다.

3. RAG (Retrieval-Augmented Generation)

RAG는 LLM의 응답에 외부 검색 결과를 결합하는 구조입니다.
LLM은 학습 데이터에 포함되지 않은 정보 (사내 문서, 실시간 데이터, 도메인 지식 등)에 대해
정확한 응답을 생성하기 어려우나, RAG는 이 한계를 보완합니다.

1. 동작 원리

1. 사용자 질문 입력
2. 질문을 벡터로 변환 (임베딩)
3. 벡터 DB 또는 검색 엔진에서 관련 문서/데이터 검색
4. 검색 결과를 LLM의 컨텍스트에 삽입
5. LLM이 검색 결과를 참고하여 응답 생성

┌──────────┐     ┌──────────────┐     ┌──────────┐
│ 사용자    │────▶│  검색 엔진    │────▶│   LLM    │
│ 질문      │     │ (벡터 DB 등) │     │          │
└──────────┘     └──────────────┘     └──────────┘
                   │ 관련 문서 반환        │ 검색 결과 + 질문
                   └──────────────────────▶│ → 응답 생성

2. LLM 단독 vs RAG 적용

3. 영상 추출에서의 RAG

영상 추출 파이프라인에서는 RAG를 답변 생성이 아닌 검색 결과의 re-scoring 용도로 사용합니다.

일반적인 RAG:    질문 → 문서 검색 → LLM이 답변 생성
영상 추출의 RAG:  쿼리 → 임베딩 검색 → LLM이 각 결과에 관련도 점수(1~10) 산출

임베딩 유사도 검색(1차)만으로는 부정문, 동의어, 맥락 차이를 정확히 구분하지 못하므로,
LLM이 텍스트를 직접 읽고 2차 필터링하는 구조입니다.

4. 영상 추출 파이프라인

영상에서 원하는 장면을 찾는 것은 구조적으로 검색 문제에 가깝습니다.
다만, 영상은 텍스트처럼 직접 검색할 수 없으므로 다음과 같은 변환이 필요합니다:

영상 → VLM으로 텍스트 변환(인덱싱) → 텍스트 임베딩 저장 → 사용자 쿼리로 검색

이 구조에서 VLM의 서술은 검색 인덱스의 역할을 합니다.
검색 엔진에서 문서 품질이 검색 결과를 좌우하듯,
VLM 서술 품질이 장면 추출 품질에 크게 영향을 줍니다.

이번 프로젝트에서 사용한 평가 지표(Precision, Recall, F1)도
정보 검색(Information Retrieval) 분야에서 사용하는 것과 동일합니다.
검색 결과 중 정답 비율(Precision)과 전체 정답 중 찾은 비율(Recall)로 검색 품질을 측정합니다.

전체 시스템은 분석엔진과 추출 서버 두 단계로 구성됩니다.

1. 분석엔진 (VLM 추론)

영상 입력 → 프레임 샘플링 (N프레임마다 1장) → 배치 구성 (10~20프레임) → VLM 추론 → 구간별 서술 생성

VLM 인터페이스 내부에서 프롬프트는 고정 영역과 가변 영역으로 나뉩니다.

각 프롬프트의 내용은 다음과 같습니다.

기본 프롬프트:

당신은 영상 분석 전문가입니다.
주어진 영상 프레임에 나타난 객체와 인물의 행동에 초점을 맞춰
현재 상황을 서술하세요.
화면에 보이는 시각적 정보만 사용하며,
추측이나 영상에 없는 정보를 만들어내서는 안 됩니다.

작업 순서 프롬프트:

작업 순서:
1) 중점 상황이 실제로 보이는지 확인
2) 보이지 않으면 → 핵심 장면만 사실적으로 요약
3) 보이면 → 해당 장면을 우선으로 1~2문장으로 요약

Custom Prompt 안내 문구:

다음 상황들을 중점적으로 서술하여야 합니다.
해당 상황이 나타나지 않으면 절대 서술하지 않아야 하며,
항목 옆에 ()로 지시문이 있으면 따라 서술하여야 합니다.

출력 형식 프롬프트:

- 한국어로 1~2문장 작성
- 나오지 않는 상황은 절대 서술하지 않음
- 중점 상황이 없으면 화면에 나타난 장면을 직관적으로 서술
- 포함되어 있지 않다는 이야기를 절대 하지 않음

최종 프롬프트 조합 방식:

{기본 프롬프트}
+
{작업 순서 프롬프트}
+
{안내 문구}
+
1. {custom_prompt_1}
2. {custom_prompt_2}
+
{출력 형식 프롬프트}

2. 추출 서버 (클립 생성)

분석엔진의 VLM 서술 결과는 Kafka를 통해 추출 서버로 전달되고,
Elasticsearch에 임베딩 벡터와 함께 저장됩니다.

사용자 쿼리 → 쿼리 임베딩 → ES KNN 검색 → RAG 재점수 → 구간 병합 → 클립 추출

RAG 재점수 시 적용되는 규칙은 다음과 같습니다:

• 동의어 허용
• 부정문 제외
• 과도한 추론 금지
• 일정 점수 이상만 최종 선택

5. 고정 프롬프트의 상충 문제

1. 고정 프롬프트가 항상 서술하도록 설계된 이유

분석엔진의 VLM은 모든 구간을 자연어로 서술해 검색 인덱스를 생성하는 역할로 설계되었습니다.
서술이 없는 구간은 검색 대상이 될 수 없으므로,
“항상 무언가를 서술하라”는 지시는 검색 커버리지 관점에서 합리적입니다.

Custom Prompt가 추가되어도 VLM은 여전히 모든 구간을 서술합니다.
다만 특정 장면이 있으면 그것을 우선 서술하도록 방향을 유도하는 것이 원래 의도였습니다.

문제는 이 구조를 특정 장면 추출 용도로 사용할 때 발생합니다.
분석엔진의 프롬프트는 추출 파이프라인을 고려하여 설계된 것이 아니므로,
범용 서술용 프롬프트와 Custom Prompt 사이에 상충이 생깁니다.

Custom Prompt 기능이 추가될 때 안내 문구만 삽입되었고,
기존 작업 순서 프롬프트는 수정되지 않았습니다.
그 결과 실제 동작에서는 긍정 지시(서술)가 우선되면서,
‘서술하지 말라’는 부정 지시가 기대만큼 반영되지 않았습니다.

2. 상충 지시에 대한 VLM의 동작

LLM/VLM은 프롬프트 내에서 모순되는 지시를 받으면 한쪽을 우선하여 동작합니다.

이 세 가지 패턴이 결합되어 부정 지시가 기대만큼 우선되지 않았고,
대상 장면이 없어도 서술이 생성되는 경우가 잦았습니다.

이 동작의 결과로 발생하는 문제:

이 부정문 서술은 후속 파이프라인에서 두 가지 경로로 오탐을 유발합니다:

1. 키워드 매칭: “조끼”, “달리” 등 목표 키워드가 부정문에 포함되어 양성 판정
2. 임베딩 유사도: 부정문이라도 목표 키워드를 포함하므로
   임베딩 벡터 간 유사도가 임계값 이상으로 산출될 수 있음

6. 서술형 vs 감지형 인터페이스

VLM이 영상을 분석할 때 결과를 출력하는 방식은 크게 두 가지로 나눌 수 있습니다.

서술형은 항상 무언가를 출력하므로,
후속 파이프라인에서 부정문 서술도 유사도 점수를 받을 수 있습니다.

7. 프롬프트 전략 3종 비교

Custom Prompt 최적화를 위해 3가지 전략을 설계하고 동일 조건에서 비교했습니다.

1. v1: 서술형 + 키워드 OR

기존 인터페이스를 그대로 사용합니다.
VLM 출력에서 목표 키워드가 하나라도 포함되면 감지로 판정합니다.

2. v2: 감지형 N/A

프롬프트 구조를 재설계하여 감지 대상의 모든 조건이 동시에 충족되는 경우에만 장면을 서술하고,
하나라도 충족되지 않으면 "N/A"만 출력하도록 합니다.
후처리는 N/A 여부만 확인하면 됩니다.

3. v3: 서술형 + () 지시문 + AND 키워드

v1의 프롬프트 구조를 유지하면서,
() 지시문으로 VLM 출력에 복장/색상/동작 정보를 강제 포함시킵니다.
후처리에서 AND 키워드 그룹 매칭과 제외 키워드를 적용합니다.

AND 키워드 매칭 예시:

모든 그룹에서 최소 1개씩 매칭되어야 감지 판정합니다.

8. 테스트 자동화 환경

1. 테스트 파이프라인

각 전략의 정량 비교를 위해 다음 파이프라인을 자동화했습니다.

1. 프레임 추출 (ffmpeg, N프레임 간격)
2. VLM 추론 (vLLM API, 배치 병렬 처리)
3. 후처리 (키워드 매칭 / N/A 판정)
4. 구간 병합 (인접 감지 구간 합치기)
5. 정답 비교 (IoU 기반 Precision/Recall/F1)
6. 리포트 생성 (JSON + CSV + 클립 추출)

2. 테스트 조합

복수의 추출 유형 × 3가지 프롬프트 전략 × 복수 영상의 조합을 테스트했습니다.
추출 유형은 행동추출(특정 복장/동작 인물 탐지)과 배경 추출(건물, 자연 등)로 구분했습니다.

3. 평가 지표

정답 비교에는 IoU(Intersection over Union) 기반의 매칭을 사용했습니다.

IoU = (예측 구간 ∩ 정답 구간) / (예측 구간 ∪ 정답 구간)

예를 들어 IoU 임계값을 0.3으로 설정한 경우,
이 이상인 구간을 매칭으로 판정하고 Precision, Recall, F1을 산출합니다.

정답 클립의 타임스탬프가 없는 경우, 퍼셉추얼 해싱(aHash/dHash)으로 자동 매칭을 시도했으나,
정확도가 충분하지 않아 원본 영상을 직접 재생하며 수작업으로 타임스탬프를 매칭했습니다.

9. 실험 결과

3가지 전략을 동일 조건에서 비교했습니다.

1. 행동추출

특정 복장/동작을 가진 인물을 탐지하는 유형입니다.

v1에서 프롬프트를 상세하게 작성할수록 VLM이 부정문에도 목표 키워드를 더 많이 포함시켜
오히려 역효과가 발생했습니다.

2. 배경 추출

건물, 자연 등 소재 장면을 탐지하는 유형으로 v1, v2 모두 유의미한 결과를 내지 못했습니다.
정답 기준이 영상미, 구도, 장면전환 등 주관적 요소에 의존하기 때문입니다.

3. 인코딩 영향

해상도가 동일하더라도 비트레이트가 낮아지면 압축 아티팩트가 증가하고
복장 색상, 로고 등 세부 시각 요소가 손실되어 동일한 프롬프트에서도 서술 결과가 달라졌습니다.

4. 부정문의 자연 필터링

테스트에서는 VLM 출력을 직접 키워드 매칭하여 부정문이 대량의 오탐을 유발했습니다.
그러나 추출 서버에 배포된 임베딩 모델로 동일한 결과를 재검증하면,
부정문 서술 중 상당수는 유사도 임계값 미만으로 자동 탈락합니다.
즉, 임베딩 유사도 임계값 단계에서 일부 오탐이 추가로 제외됩니다.

다만 모든 부정문이 걸러지는 것은 아니며,
이 임계값은 코드에 하드코딩되어 있어 프롬프트 작성자가 조절할 수 없습니다.

10. 실험 중 발견한 이슈

실험 과정에서 프롬프트 최적화만으로는 해결할 수 없는 시스템 이슈들을 발견했습니다.

11. 리서치 단계에서 검토한 접근법

프로젝트 초기에 다음 접근법들을 리서치하고 일부를 실제 구현하여 테스트했습니다.

이 중 Dense Caption, 구조화 조건, 앙상블 등은 구현까지 완료했으나,
인터페이스가 자연어 Custom Prompt만 받는 구조라 적용할 수 없었습니다.

1. 프롬프트 작성자의 제어 가능 범위

Custom Prompt 작성자가 실제로 제어할 수 있는 영역과
없는 영역을 정리하면 다음과 같습니다.

12. 프롬프트 엔지니어링 인사이트

실험 과정에서 확인한 프롬프트 작성 시 고려사항입니다.

마무리

이 글에서는 VLM 영상 추출 시스템의 프롬프트 최적화와 구조적 한계를 정리했습니다.

1. 서술형(v1), 감지형(v2), AND 후처리(v3) 전략을 동일 조건에서 비교
2. 자동화 파이프라인을 구축해 IoU, Precision, Recall, F1 기반 정량 평가 수행
3. 감지형 인터페이스가 행동추출에서 가장 안정적인 결과를 보임
4. 프롬프트 수정만으로는 고정 프롬프트의 모순과 파이프라인 제약을 해소할 수 없음을 확인
5. 임베딩·재점수·구간 병합 단계가 실제 성능에 큰 영향을 미침을 검증

핵심 제약은 고정 프롬프트를 변경할 수 없다는 점이었습니다.
범용 서술 목적의 프롬프트 위에 특정 장면 추출 요구가 추가되면서 상충 지시가 공존하게 되었고,
이는 Custom Prompt만으로 조정하기 어려운 영역이었습니다.

임베딩 임계값, RAG 재점수 기준, 구간 병합 로직 등
후속 파이프라인의 파라미터 역시 프롬프트의 통제 범위를 벗어나 있습니다.

프롬프트는 시스템의 한 구성 요소입니다.
후처리·검색·인터페이스와 역할을 구분하지 않으면 성능 개선은 한계에 부딪힐 수밖에 없습니다.

프롬프트의 책임과 시스템의 책임을 구분하는 인식이 먼저 필요합니다.

일반적인 프로젝트에서는 Docker 이미지의 CVE를 검수하지 않는 경우가 많지만,
보안 요건이 높은 환경에서는 HIGH/CRITICAL 취약점이 0건이어야 배포가 승인됩니다.

온라인 환경에서는 apt upgrade나 pip install --upgrade 한 줄이면 끝나는 작업이지만,
폐쇄망에서는 패키지 저장소에 접근할 수 없어 패치 파일을 직접 준비해야 하고,
스캐너의 취약점 DB조차 수동으로 반입해야 합니다.
실제로 대응을 진행해 보니, 패키지 업데이트 외에도
커널 CVE의 검수 범위 문제나 패치 미제공 상황 등 예외 케이스가 많았습니다.

이 글은 폐쇄망 환경에서 Docker 이미지의 CVE를 스캔하고,
패키지를 패치하고, 예외 상황에 대응하는 전체 과정을 정리한 것입니다.

특정 이미지나 프로젝트에 한정되지 않으며
Debian/Ubuntu 기반 Docker 이미지라면 동일한 방식으로 적용할 수 있습니다.

1. CVE(Common Vulnerabilities and Exposures)

CVE란?

CVE는 MITRE Corporation이 운영하며, CVE-연도-일련번호 형식으로 표기됩니다.

CVE-2026-0861
 │    │    │
 │    │    └── 일련번호 (해당 연도 내 순번)
 │    └─────── 취약점이 등록된 연도
 └──────────── CVE 접두어

CVE가 등록되면 NVD(National Vulnerability Database)에서 해당 취약점의 심각도를 평가합니다.
심각도는 CVSS(Common Vulnerability Scoring System)라는 점수 체계로 산정되며,
0.0~10.0 범위의 점수가 다음과 같은 등급으로 분류됩니다.

보안 검수에서는 일반적으로 HIGH(7.0 이상)와 CRITICAL(9.0 이상)이 대상
MEDIUM 이하는 조직 보안 정책에 따라 허용되는 경우가 많음

Docker 이미지에는 OS 패키지와 Python 패키지가 포함되어 있으며,
이 중 알려진 CVE가 존재하는 패키지가 있으면 보안 검수에서 반려됩니다.

취약점 스캐너

컨테이너 이미지의 CVE를 식별하려면 취약점 스캐너가 필요합니다.
스캐너는 이미지 내 설치된 패키지 목록을 추출하고,
취약점 DB와 대조하여 알려진 CVE가 포함되어 있는지 확인합니다.

Trivy

Trivy는 Aqua Security에서 개발한 오픈소스 취약점 스캐너입니다.
컨테이너 이미지, 파일시스템, Git 저장소, Kubernetes 클러스터 등을 스캔할 수 있으며,
취약점 외에도 Misconfiguration과 Secret 노출까지 탐지합니다.

Trivy DB 업데이트 방식

Trivy는 취약점 정보를 자체 DB에 저장하며,
이 DB는 6시간 간격으로 빌드됩니다.
Trivy CLI는 로컬 DB가 일정 시간(기본 12시간) 이상 경과하면
스캔 전에 자동으로 최신 DB를 다운로드합니다.

Trivy 스캔 실행
    ↓
DB 최신 여부 확인
    ↓ (오래된 경우)
OCI 레지스트리에서 DB 다운로드
    ↓
스캔 수행

DB는 다음 OCI 레지스트리에서 배포됩니다.

그러나 폐쇄망에서는 OCI 레지스트리에 접근할 수 없으므로
외부망에서 DB를 미리 다운로드하여 물리 매체로 반입해야 합니다.

# 외부망: DB 다운로드
./trivy image --download-db-only

# 외부망: DB 압축
cd ~/.cache/trivy
tar -czf trivy-db.tar.gz db

# 폐쇄망: DB 복원
mkdir -p /root/.cache/trivy
tar -xzf trivy-db.tar.gz -C /root/.cache/trivy

# 폐쇄망: 스캔 시 DB 업데이트 차단
trivy fs --skip-db-update --scanners vuln /

폐쇄망에서의 Trivy DB는 수동 반입·수동 갱신
DB가 오래되면 새로 발견된 CVE를 탐지하지 못하므로
검수 시점에 맞춰 최신 DB를 다운로드하여 반입하는 것을 권장

다른 스캐너와 비교

Trivy 외에도 컨테이너 이미지 취약점을 스캔할 수 있는 도구들이 있습니다.

Trivy를 선택한 이유는 오프라인 지원이 간편하고 단일 바이너리로 동작하기 때문
Grype도 유사한 방식으로 오프라인 스캔이 가능하지만
Clair는 서버 데몬을 별도로 구성해야 해서 폐쇄망에서는 설정 부담이 큼
Docker Scout는 오프라인을 지원하지 않으므로 폐쇄망에서 사용 불가

2. 전체 전략

CVE 대응은 작업용 이미지와 배포용 이미지를 분리하여 진행합니다.

원본 이미지
    ↓
작업용 이미지 (bash ENTRYPOINT)
    → OS 패키지 제거
    → Python 패키지 업데이트
    → Trivy 스캔 (HIGH/CRITICAL = 0 확인)
    ↓
배포용 이미지 (원래 ENTRYPOINT 복구)
    → 서비스 실행용 최종 이미지

작업용 이미지에서 CVE를 제거한 뒤 docker commit으로 고정하고
배포용 이미지에서 ENTRYPOINT만 복구하는 2단계 구조
이렇게 분리하면 스캔 도구와 서비스 실행이 충돌하지 않음

3. 외부망 준비 (1회)

폐쇄망 반입 전에 외부망에서 다음 파일들을 준비합니다.

1. Trivy 바이너리

wget https://github.com/aquasecurity/trivy/releases/download/v0.69.1/trivy_0.69.1_Linux-64bit.tar.gz
tar -xzf trivy_0.69.1_Linux-64bit.tar.gz
chmod +x trivy

Trivy 릴리즈 페이지에서 최신 버전을 확인하여 다운로드

2. Trivy 취약점 DB

1장에서 설명한 대로, 폐쇄망에서는 Trivy DB를 수동으로 반입해야 합니다.
1장의 DB 다운로드 및 압축 명령어를 참고하여 trivy-db.tar.gz 파일을 준비합니다.

DB는 6시간마다 갱신되므로 보안 검수 직전에 최신 DB를 다운로드하는 것을 권장

3. Python whl 패키지

Trivy 스캔 결과에서 CVE가 보고된 Python 패키지의 패치된 버전을 .whl 파일로 다운로드합니다.

pip download <패키지명>==<패치_버전> ...

예를 들어 urllib3에 HIGH 취약점이 보고되었고, 패치된 버전이 2.6.0이라면:

pip download urllib3==2.6.0

패키지 버전은 CVE가 수정된 최소 버전 이상을 지정
의존성 충돌을 방지하기 위해 설치 시 --no-deps 옵션을 사용할 예정이므로
대상 패키지만 정확히 다운로드

4. 반입 대상 정리

trivy                  # Trivy 바이너리
trivy-db.tar.gz        # 취약점 DB
*.whl                  # 패치된 Python 패키지

4. 작업용 이미지 생성

1. 원본 이미지 태그

원본 이미지를 작업용 태그로 복제합니다.
원본을 보존하면서 작업용 이미지를 분리하기 위함입니다.

docker tag <IMAGE>:<TAG> <IMAGE>:<TAG>-work

2. 작업용 컨테이너 실행

ENTRYPOINT를 /bin/bash로 오버라이드하여 인터랙티브 셸로 진입합니다.

docker rm -f cve-work 2>/dev/null || true

docker run -it \
  --entrypoint /bin/bash \
  --name cve-work \
  <IMAGE>:<TAG>-work

--entrypoint /bin/bash로 실행해야 컨테이너 안에서 패키지 제거, 설치, 스캔 작업 가능
원래 ENTRYPOINT로 실행하면 셸 접근이 제한됨

5. 컨테이너 내부 CVE 제거

1. 파일 복사 (호스트 → 컨테이너)

호스트에서 준비한 파일들을 작업용 컨테이너 내부로 복사합니다.

# 별도 터미널에서 실행 (호스트)
docker cp trivy cve-work:/usr/local/bin/trivy
docker cp trivy-db.tar.gz cve-work:/opt/trivy-db.tar.gz
docker cp /path/to/whl cve-work:/opt/whl

2. Trivy DB 복원

# 컨테이너 내부에서 실행
mkdir -p /root/.cache/trivy
cd /root/.cache/trivy
tar -xzf /opt/trivy-db.tar.gz

3. OS 레벨 CVE 제거

Trivy 스캔 결과에서 HIGH/CRITICAL로 보고된 OS 패키지를 제거합니다.
Debian/Ubuntu 기반 이미지에서 자주 보고되는 패키지는 다음과 같습니다.

apt-get update

# 예시: 자주 보고되는 취약 패키지 제거
apt-get purge -y gnupg* dirmngr
apt-get purge -y gpg gpgv gpgconf

# 불필요한 의존성 정리
apt-get autoremove -y
apt-get clean

OS 패키지가 제거 가능한 이유

Docker 이미지에는 빌드 시점에 필요했지만
실제 서비스 실행(런타임)에는 사용되지 않는 패키지가 포함되어 있는 경우가 많습니다.
이러한 패키지는 제거해도 서비스에 영향이 없으며,
CVE 제거와 이미지 경량화를 동시에 달성할 수 있습니다.

gnupg, dirmngr, gpg, gpgv, gpgconf는 GPG(GNU Privacy Guard) 스택을 구성하는 패키지들로,
각각의 역할은 다음과 같습니다.

이들은 주로 apt-get update / apt-get install 시
패키지 저장소의 서명을 검증하는 데 사용됩니다.
이미지 빌드 과정에서 패키지를 설치할 때 필요하지만,
빌드가 완료된 후에는 더 이상 패키지를 설치할 일이 없으므로 제거할 수 있습니다.

특히 폐쇄망 환경에서는 외부 패키지 저장소에 접근할 수 없으므로
GPG 서명 검증 기능 자체가 사용될 가능성이 없습니다.

제거 전 확인 방법

패키지를 제거하기 전에 해당 패키지에 의존하는 다른 패키지가 있는지 확인합니다.

# 역의존성 확인: 이 패키지를 필요로 하는 다른 패키지 목록
apt-cache rdepends --installed <패키지명>

역의존성 목록에 서비스 실행에 필요한 패키지가 포함되어 있다면 제거하면 안 됩니다.

위는 자주 보고되는 예시이며, 실제 제거 대상은 Trivy 스캔 결과에 따라 다름
핵심 판단 기준은 “이 패키지가 빌드 시점에만 필요한가, 런타임에도 필요한가”
빌드 전용 패키지는 제거해도 서비스에 영향이 없음

4. Python 패키지 업데이트

사전에 준비한 .whl 파일로 취약 Python 패키지를 업데이트합니다.

pip install --no-index --find-links=/opt/whl --no-deps <패키지명>==<패치_버전>

--no-deps를 사용하는 이유는 의존성 자동 해결 시
기존에 설치된 다른 패키지와 버전 충돌이 발생할 수 있기 때문
대상 패키지만 정확히 교체하는 것이 안전

5. 버전 증빙

업데이트된 패키지 버전을 기록합니다.
보안 검수 시 증빙 자료로 제출할 수 있습니다.

pip list | egrep '<패키지1>|<패키지2>|...' \
  | tee /tmp/python_versions.txt

6. Trivy 오프라인 스캔

1. 스캔 실행

export TRIVY_SKIP_DB_UPDATE=true

trivy fs \
  --skip-db-update \
  --scanners vuln \
  --severity HIGH,CRITICAL \
  --format table \
  / | tee /tmp/trivy_scan_result.txt

2. 합격 기준

Total: 0 (HIGH: 0, CRITICAL: 0)

HIGH 또는 CRITICAL 등급의 취약점이 0건이면 합격입니다.

MEDIUM 이하는 일반적으로 검수에서 허용되지만
조직 보안 정책에 따라 기준이 다를 수 있음

3. 불합격 시 대응

스캔 결과에 취약점이 남아 있으면 다음을 확인합니다.

모든 CVE가 패키지 제거나 업데이트로 해결되는 것은 아닙니다.
패치가 존재하지 않거나, 제거하면 서비스가 깨지거나,
컨테이너 레벨에서 대응할 수 없는 경우가 있습니다.
이 경우 리스크 수용 또는 예외 처리를 보안팀에 요청해야 합니다.

4. 예외 처리가 필요한 경우

실제 CVE 대응 과정에서는 패키지 제거나 업데이트만으로 해결되지 않는 경우가 빈번합니다.
아래는 실무에서 자주 발생하는 예외 패턴과 대응 논리입니다.

1. 패치 버전이 배포되지 않은 경우

배포판(Debian, Ubuntu 등)에서 해당 CVE를 Minor issue(<no-dsa>)로 분류하고,
보안 업데이트를 별도로 제공하지 않는 경우입니다.

[상황]
- Trivy에서 HIGH로 보고되었으나
  배포판 보안팀은 해당 CVE를 Minor issue로 분류
- 저장소에 적용 가능한 패치 버전이 존재하지 않음

[대응 논리]
- 취약점의 악용 조건이 매우 제한적 (예: 공격자가 특정 파라미터를 동시에 제어해야 함)
- 일반적인 런타임 환경에서 실질 악용 가능성이 낮음
- 패치 제공 시 즉시 반영을 전제로 리스크 수용 요청

Trivy의 심각도 판정과 배포판의 판정이 다를 수 있음
NVD에서는 HIGH로 분류하더라도 Debian/Ubuntu 보안팀이 자체 평가 후
<no-dsa> (Debian Security Advisory 미발행)로 처리하는 경우가 있음

2. 호스트 커널 CVE가 컨테이너에서 탐지되는 경우

Linux 커널 관련 CVE가 컨테이너 이미지 스캔에서 탐지되는 경우입니다.
컨테이너는 자체 커널을 포함하지 않고 호스트 시스템의 커널을 공유하므로,
컨테이너 이미지 레벨에서는 근본적인 해결이 불가능합니다.

[상황]
- 커널 소스 코드에 대한 CVE가 컨테이너 이미지 스캔에서 탐지
- 컨테이너 내부에서 패키지를 제거하거나 업데이트해도 효과 없음

[대응 논리]
- 컨테이너는 자체 커널을 포함/사용하지 않음 (호스트 커널 공유)
- 취약점의 영향 여부는 호스트 OS 커널 버전과 보안 패치 상태에 따라 결정
- 컨테이너 이미지가 아닌 호스트 OS 커널 패치 적용 여부를 기준으로 리스크 관리

대표적인 예가 linux-libc-dev 패키지입니다.
이 패키지는 Linux 커널 헤더 파일을 제공하는 개발용 패키지로,
이미지 빌드 시 C extension을 컴파일할 때 설치되는 경우가 많습니다.

Trivy는 이 패키지의 버전을 기준으로 커널 CVE를 매핑하여 보고합니다.
문제는 이 패키지 하나에 매핑되는 커널 CVE가 매우 많다는 것입니다.
일반적인 Docker 이미지를 스캔하면
전체 탐지 건수의 절반 이상이 linux-libc-dev 기인인 경우가 흔합니다.

다만 linux-libc-dev는 커널 헤더 파일일 뿐, 실제 커널 코드가 컨테이너에 포함된 것이 아닙니다.
컨테이너는 호스트의 커널을 공유하므로 이 패키지에서 보고되는 CVE는
컨테이너 이미지 레벨에서는 대응할 수도, 대응할 필요도 없습니다.

따라서 이 유형의 CVE는 컨테이너 이미지 검수 범위에서 제외하고,
호스트 OS의 커널 패치 상태를 기준으로 별도 관리하는 것이 일반적입니다.

linux-libc-dev를 검수 범위에서 제외하면 전체 CVE 건수가 대폭 줄어듦
보안팀과 사전에 “커널 CVE는 호스트 OS 영역”이라는 합의를 하면
이후 검수에서 반복적으로 같은 논의를 할 필요가 없음

3. 라이브러리가 존재하지만 런타임에 로드되지 않는 경우

취약 라이브러리가 이미지에 포함되어 있지만,
실제 서비스 실행 시 해당 라이브러리가 메모리에 로드되지 않는 경우입니다.

[상황]
- 취약 라이브러리(.so)가 이미지에 존재
- 그러나 서비스 프로세스의 메모리 맵(/proc/<pid>/maps)에서 미검출
- 다른 핵심 패키지가 해당 라이브러리에 의존하여 제거 불가

[확인 방법]
# 컨테이너 내부에서 실행
cat /proc/<서비스_PID>/maps | grep <라이브러리명>
# → 출력 없으면 런타임에 로드되지 않음

# 역의존성 확인
apt-cache rdepends --installed <라이브러리_패키지명>
# → 핵심 패키지가 의존하고 있으면 제거 불가

[대응 논리]
- 라이브러리는 이미지에 포함되어 있으나 런타임에 사용(로드)되지 않음
- 의존성 관계로 인해 패키지 삭제 시 서비스 기능에 영향
- 실제 악용 가능성이 낮으므로 패치 버전 적용 가능 시까지 리스크 수용 요청

공유 라이브러리(.so)는 다른 패키지가 의존하더라도 실제 실행 시 로드되지 않을 수 있음
/proc/<pid>/maps로 런타임 로드 여부를 확인하면 실질적인 영향 범위를 입증할 수 있음

4. 패치 완료되었으나 스캐너가 구버전으로 인식하는 경우

실제로는 패치된 버전의 파일을 사용하고 있지만,
호환성을 위해 구버전 이름의 심볼릭 링크를 유지해 스캐너가 취약 버전으로 탐지하는 경우입니다.

[상황]
- 취약 버전의 라이브러리/JAR 파일은 이미 삭제
- 패치된 버전의 파일만 존재
- 그러나 애플리케이션 호환성을 위해 구버전 이름의 심볼릭 링크를 유지
- Trivy가 심볼릭 링크의 파일명(구버전)을 기준으로 취약 판정

[확인 방법]
# 실제 파일 확인
ls -la /path/to/<라이브러리>*
# → 심볼릭 링크가 패치된 버전의 실제 파일을 가리키는지 확인

[대응 논리]
- 실제 파일시스템에는 패치된 버전만 존재
- 취약 버전의 파일은 포함되어 있지 않음
- 심볼릭 링크는 이름만 구버전이며, 참조하는 실제 파일은 패치 완료

5. 구버전 베이스 이미지로 인한 대량 CVE

베이스 이미지 자체가 오래된 OS 버전(예: Debian 11)으로 빌드되어
다수의 CVE가 동시에 보고되며, 개별 패치로는 대응이 불가능한 경우입니다.

[상황]
- 구버전 OS 기반 이미지에서 수십~수백 건의 CVE 탐지
- 대부분의 패키지에 Fixed version이 배포되지 않음
- 개별 패키지 업데이트로는 해결 불가

[대응]
- 최신 OS(Debian 12/13 등)로 빌드된 새 이미지를 반입
- 주요 라이브러리 버전 업데이트에 따른 애플리케이션 호환성 검증 필요
- 이미지 재빌드 후 다시 스캔하여 잔여 CVE 확인

구버전 이미지는 개별 CVE 패치보다 이미지 재빌드가 효율적
다만 라이브러리 메이저 버전이 변경되면 애플리케이션 코드 수정이 필요할 수 있으므로
개발팀과의 사전 호환성 검증이 필수

예외 요청 시 포함할 항목

예외 처리를 요청할 때는 다음 항목을 정리하여 보안팀에 전달합니다.

“패치가 없다”로 끝내는 것이 아니라
“왜 현 시점에서 리스크가 낮은지”를 기술적으로 입증하는 것이 핵심
런타임 로드 여부, 악용 조건의 제한성, 배포판의 자체 판단 등을 근거로 제시

7. 이미지 확정 및 배포용 빌드

1. 작업용 이미지 커밋

스캔을 통과한 작업용 컨테이너를 이미지로 고정합니다.

# 컨테이너에서 exit
exit

# 이미지 커밋
docker commit cve-work <IMAGE>:<TAG>-hardened

docker commit은 현재 컨테이너 상태를 그대로 이미지로 저장
이 시점의 이미지에는 CVE가 제거된 상태가 반영되어 있음

2. 배포용 이미지 빌드

작업용 이미지는 ENTRYPOINT가 /bin/bash로 되어 있으므로
서비스 실행을 위해 원래 ENTRYPOINT를 복구해야 합니다.

FROM <IMAGE>:<TAG>-hardened
ENTRYPOINT ["<원본_ENTRYPOINT>"]

docker build -t <IMAGE>:<TAG>-hardened-release .

원본 이미지의 ENTRYPOINT는 다음 명령으로 확인할 수 있습니다.

docker inspect --format='' <IMAGE>:<TAG>

8. 서비스 실행

runtime 이미지로 서비스를 실행합니다.

docker rm -f <CONTAINER_NAME> 2>/dev/null || true

docker run -d \
  --name <CONTAINER_NAME> \
  --gpus '"device=0"' \
  -p <HOST_PORT>:<CONTAINER_PORT> \
  -v /path/to/data:/data \
  <IMAGE>:<TAG>-hardened-release

GPU 옵션, 포트, 볼륨 마운트 등은 서비스에 맞게 조정

9. 최종 검증

1. 서비스 정상 동작 확인

# 컨테이너 로그
docker logs -f <CONTAINER_NAME>

# GPU 할당 확인 (GPU 사용 시)
docker exec -it <CONTAINER_NAME> nvidia-smi

# API 응답 확인 (API 서버인 경우)
curl http://localhost:<HOST_PORT>/health

CVE 패치 과정에서 Python 패키지 버전이 변경되면
deprecated된 함수나 변경된 API로 인해 기존 코드가 동작하지 않을 수 있습니다.
컨테이너 기동 확인 외에 주요 기능에 대한 호환성 검증도 필요합니다.

--no-deps로 대상 패키지만 교체하므로 마이너 패치에서는 문제가 드물지만
메이저/마이너 버전이 변경된 경우 함수 시그니처나 모듈 구조가 달라질 수 있으므로
패치 전후 changelog를 확인하는 것을 권장

2. CVE 스캔 결과 추출

보안 검수 제출용 증빙 파일을 추출합니다.

# 작업용 컨테이너에서 저장한 파일 추출
docker cp cve-work:/tmp/trivy_scan_result.txt ./
docker cp cve-work:/tmp/python_versions.txt ./

제출 증빙 목록:

마무리

이 글에서 다룬 CVE 대응 절차를 정리하면 다음과 같습니다.

1. 외부망: Trivy 바이너리 + DB + Python whl 준비
    ↓
2. 폐쇄망: 작업용 컨테이너 생성 (bash ENTRYPOINT)
    ↓
3. 컨테이너 내부: OS 패키지 제거 + Python 패키지 업데이트
    ↓
4. Trivy 오프라인 스캔 (HIGH/CRITICAL = 0 확인)
    ↓
5. 이미지 커밋 → 배포용 이미지 빌드 (ENTRYPOINT 복구)
    ↓
6. 서비스 실행 및 최종 검증

폐쇄망에서는 CVE 하나를 수정하는 것도
“whl 다운로드 → 물리 매체 반입 → 설치 → 재스캔”의 사이클을 거쳐야 합니다.
외부망에서는 한 줄이면 끝나는 작업이 폐쇄망에서는 하루가 걸릴 수 있습니다.

사전에 어떤 CVE가 보고되는지 파악하고,
필요한 패치 파일을 한 번에 준비하여 반입하는 것이 재작업을 줄이는 핵심입니다.

특정 조직의 내부 시스템이나 정책, 네트워크 설정은 포함하지 않으며
모든 내용은 공개된 기술과 일반적인 Linux 환경을 기반으로 구성되었습니다.

15. 파인튜닝

본 프로젝트에서는 VLM(Vision-Language Model) 기반으로 OCR 파인튜닝을 수행했습니다.
기존 PaddleOCR 기반 파인튜닝은 PaddleOCR 기반 도메인 특화 OCR fine-tuning에서 다뤘으며,
이번에는 VLM 기반 OCR 방식을 적용했습니다.

VLM(Vision-Language Model)이란?

VLM은 이미지와 텍스트를 함께 처리할 수 있는 멀티모달 모델입니다.
GPT 계열, Gemini 계열, Qwen-VL과 같은 모델들이 대표적인 VLM에 해당합니다.
다만 GPT 및 Gemini와 같은 상용 멀티모달 모델은
내부 Vision–Language 결합 구조가 공개되어 있지 않습니다.
아래 구조는 주로 오픈소스 VLM에서 일반적으로 사용되는 아키텍처입니다.

┌─────────────────┐     ┌──────────────┐     ┌─────────────────┐
│ Vision Encoder  │────▶│  Projector   │────▶│ Language Model  │
│ (이미지 인코더)  │     │ (모달리티 정렬) │     │  (텍스트 생성)   │
└─────────────────┘     └──────────────┘     └─────────────────┘

VLM에 “이 이미지의 텍스트를 읽어줘”라고 프롬프트를 주면
이미지 속 텍스트를 인식하여 자연어로 출력합니다.
이처럼 텍스트 인식을 LLM 생성 과정으로 수행하는 방식을 VLM OCR이라 합니다.

OCR 전용 모델 vs VLM OCR

OCR 전용 모델은 좌표 기반 정밀 탐지와 빠른 추론에 강점이 있고
VLM OCR은 문맥 이해 기반의 유연한 텍스트 인식에 강점이 있음
두 방식은 대체 관계가 아니라 용도에 따라 선택하는 보완 관계

1. 데이터셋 구축: 모델 보조 라벨링

학습 데이터는 영상에서 자막이 표시되는 구간을 캡처하여 구축했습니다.
사전학습된 베이스 VLM의 추론 결과를 초안 라벨로 활용하고,
사람이 오류를 수정한 뒤 해당 데이터로 파인튜닝을 진행했습니다.

영상에서 자막 구간 캡처 (이미지 추출)
        ↓
베이스 VLM으로 인퍼런스 (초안 라벨 생성)
        ↓
사람이 오류 수정 (Human-in-the-Loop 검수)
        ↓
수정된 데이터로 파인튜닝 학습

해당 방식은 Model-Assisted Labeling에 해당하며
모델 예측을 사람이 검수·보정하여 최종 정답을 확정하는 Human-in-the-Loop 기반 전략임
모델 예측을 그대로 학습에 사용하는 Pseudo Labeling과는 구분됨
데이터셋 규모가 작을수록 라벨 품질이 성능에 미치는 영향이 큼

2. LoRA 파인튜닝

LoRA(Low-Rank Adaptation)는 대규모 모델의 원본 가중치를 고정한 채
저랭크 어댑터 행렬만 추가 학습하는 기법입니다.
전체 파라미터 대비 소수(보통 1% 내외)만 학습하므로 메모리 효율이 높지만,
데이터가 매우 적은 경우에는 여전히 과적합이 발생할 수 있습니다.

VLM 파인튜닝 시에는 Vision Encoder와 Projector를 동결(Freeze)하고
Language Model에만 LoRA를 적용하는 것이 일반적입니다.
다만 도메인 특성이 강한 경우 일부 레이어를 추가 학습하기도 합니다.

LoRA는 어댑터 가중치만 저장하므로 용량이 수십 MB 수준으로 매우 작음
데이터가 매우 적은 경우 상위 레이어에만 LoRA를 적용하는 방식도 고려할 수 있음

3. 평가

OCR 성능 평가에는 CER(Character Error Rate, 문자 오류율)을 사용합니다.
CER은 모델이 출력한 텍스트와 정답 텍스트 사이의 편집 거리를 문자 단위로 측정하며,
단어 단위 지표(WER)보다 OCR 태스크에 적합합니다.
평가 시에는 공백 및 특수문자 처리 기준을 사전에 정의하여 일관된 방식으로 CER을 계산했습니다.

파인튜닝 후 베이스 모델 대비 CER이 개선되었으며,
소규모 데이터셋임에도 Model-Assisted Labeling 방식의 효과를 확인할 수 있었습니다.

4. 가중치 관리

학습 완료 시 어댑터 파일(adapter_config.json, adapter_model.safetensors) 2개만 저장됩니다.
전체 모델을 다시 가져올 필요 없이 어댑터 파일만 교체하면 됩니다.

여러 버전의 어댑터를 관리하면 태스크별 모델 전환이 가능
다만 런타임 전환 가능 여부는 사용하는 서빙 프레임워크에 따라 달라짐

16. 모델 서빙

모델 서빙은 학습이 완료된 AI 모델을 실시간으로 호출할 수 있는 상태로 배포하는 과정입니다.
학습된 가중치 파일(.pt, .safetensors, .trt 등)을 메모리에 로드하고,
외부 요청에 대해 추론 결과를 반환하는 API 형태로 운영합니다.

모델 서빙은 크게 두 가지 요소로 구성됩니다.

1. Hugging Face Transformers

Transformers는 Hugging Face에서 개발한 오픈소스 라이브러리로,
다양한 pretrained 모델(LLM, VLM, Vision 등)을
로드하고 추론·학습할 수 있는 통합 프레임워크입니다.

from transformers import AutoModelForCausalLM, AutoProcessor

model = AutoModelForCausalLM.from_pretrained("model_path", trust_remote_code=True)
processor = AutoProcessor.from_pretrained("model_path", trust_remote_code=True)

vLLM, SGLang 등은 Hugging Face 모델 포맷과 토크나이저를 호환하여 로드합니다.
다만 Transformers의 기본 추론 API는 대규모 서빙 최적화를 제공하지 않으므로,
고부하 프로덕션 환경에서는 전용 추론 엔진을 사용하는 것이 일반적입니다.

2. 추론 엔진 비교

(1) TensorRT

NVIDIA의 GPU 최적화 추론 엔진입니다.
모델을 .trt 엔진 파일로 변환하여 Layer Fusion, Kernel Auto-Tune, Quantization 등
하드웨어 수준의 최적화를 적용합니다.

# ONNX → TensorRT 변환 예시
trtexec --onnx=model.onnx --saveEngine=model.trt --fp16

TensorRT 엔진은 생성 시점의 GPU 아키텍처에 종속되므로
폐쇄망 반입 시 현장 GPU와 동일한 환경에서 변환해야 함

(2) vLLM

LLM/VLM 전용 고속 추론 엔진입니다.
PagedAttention, Continuous Batching 등 LLM에 특화된 최적화를 제공하며
OpenAI 호환 API를 기본으로 지원합니다.

(3) SGLang

SGLang은 LLM/VLM 추론 및 프롬프트 프로그래밍을 위한 프레임워크입니다.
RadixAttention 기반의 KV Cache 재사용 구조를 사용하여
동일 prefix를 공유하는 반복 프롬프트 처리에 강점이 있습니다.

vLLM / SGLang Docker 배포

vLLM과 SGLang은 공식 Docker 이미지를 사용하여 컨테이너로 실행합니다.

vLLM

docker run -itd \
    --name vllm_server \
    --gpus '"device=0"' \
    --ipc=host \
    -p <PORT>:<PORT> \
    -v /path/to/models:/models \
    vllm/vllm-openai:v0.11.0 \
    --model /models/VLM-7B \
    --host 0.0.0.0 \
    --port <PORT> \
    --tensor-parallel-size 1 \
    --gpu-memory-utilization 0.7 \
    --max-model-len 8192

SGLang

docker run -itd \
    --name sglang_server \
    --gpus '"device=0"' \
    --shm-size 32g \
    -p <PORT>:<PORT> \
    -v /path/to/models:/models \
    --ipc=host \
    lmsysorg/sglang:v0.5.4 \
    python3 -m sglang.launch_server \
    --model-path /models/model_name \
    --host 0.0.0.0 --port <PORT> \
    --mem-fraction-static 0.8 \
    --context-length 70000

정상 실행 확인

# 컨테이너 로그 확인
docker logs -f vllm_server
# → "Application startup complete" 메시지 확인

# API 응답 확인
curl http://localhost:<PORT>/v1/models
# → 200 OK

폐쇄망에서는 Docker 이미지를 tar로 반입해야 하므로
docker save / docker load로 이미지를 준비함 (폐쇄망 AI Solution 개발환경 구축 (2) 참고)

참고: Blackwell GPU 환경에서의 차이

Blackwell(B200, B300 등) 환경에서는 CUDA 13.0 이상이 필요하며,
작성 시점 기준으로 안정 릴리즈 대신 nightly/dev 이미지를 사용해야 할 수 있습니다.

vLLM은 Blackwell에서 Triton 커널 컴파일 시
ptxas fatal: Value 'sm_103a' is not defined 오류가 발생합니다.
CUDA 13.0 툴킷의 ptxas 바이너리를 추출하여
-v ptxas:/opt/ptxas:ro -e TRITON_PTXAS_PATH=/opt/ptxas로 주입하면 해결됩니다.

SGLang은 이미지 태그만 변경하면 Blackwell에서 동작
vLLM은 이미지 교체 + ptxas 주입이 모두 필요

(4) Transformers + FastAPI (직접 구현)

Hugging Face Transformers로 모델을 직접 로드하고
FastAPI로 API 서버를 구성하는 방식입니다.
대부분의 Hugging Face 호환 모델에서 사용할 수 있습니다.

# FastAPI 서버 실행
uvicorn app.main:app --host 0.0.0.0 --port <PORT>

3. 서빙 방식 비교

일부 커스텀 아키텍처 기반 VLM은 vLLM, SGLang 등 범용 추론 엔진을 지원하지 않음
이 경우 Transformers + FastAPI 조합이 유일한 서빙 방법이 됨

4. 커스텀 아키텍처 VLM의 서빙 제약

일부 VLM은 vLLM/SGLang의 공식 지원 목록에 포함되지 않은 커스텀 아키텍처를 사용합니다.
이번 프로젝트에서 사용한 VLM도 이에 해당했습니다.

vLLM/SGLang이 해당 아키텍처를 공식 지원하기 전까지는
Transformers의 trust_remote_code=True로 직접 로드하는 것이 유일한 방법이었습니다.

5. FastAPI 기반 VLM 서빙 구성

위의 제약으로 인해 Transformers + PEFT + FastAPI 조합으로 직접 서빙 서버를 구축했습니다.
API 형식은 OpenAI 호환으로 구성하여
추후 vLLM/SGLang 전환 시 클라이언트 수정이 불필요하도록 설계했습니다.

[FastAPI 서버]
├── /health                   # 헬스 체크
├── /v1/chat/completions      # OpenAI 호환 API (단건 / 스트리밍)
├── /v1/batch/ocr             # 배치 OCR API (최대 8건)
└── /ocr                      # 단순 OCR API

서빙 시에는 베이스 모델과 LoRA 어댑터를 분리하여 로드하며,
use_lora 파라미터로 런타임에 베이스/파인튜닝 모델을 전환할 수 있습니다.

어댑터 폴더에는 adapter_config.json과 adapter_model.safetensors 2개만 있어야 함
베이스 모델의 설정 파일이 함께 있으면 로드 시 충돌 발생

Docker 컨테이너 실행

docker run -d --gpus '"device=0"' \
    --shm-size 32g \
    -p <PORT>:<PORT> \
    -v /path/to/model:/workspace/model/VLM \
    -v /path/to/adapter:/workspace/adapter/best_model_clean \
    -v /path/to/server:/workspace/server \
    --name vlm_ocr_server \
    base_image:latest \
    uvicorn app.main:app --host 0.0.0.0 --port <PORT>

정상 실행 확인

curl http://localhost:<PORT>/health
# → {"status": "ok", "model_type": "both (base + finetuned)"}

모델과 어댑터를 별도 볼륨으로 마운트하면 어댑터만 교체하여 모델 버전 전환 가능
폐쇄망에서는 서버 실행 후 반드시 헬스 체크와 샘플 추론으로 정상 동작을 확인해야 함

17. 분석엔진 연동

분석엔진은 AI 모델의 실행과 외부 시스템 연동을 담당하는 백엔드 서비스입니다.
컨테이너 매니저와 분석 스케줄러로 구성되며,
컨테이너 매니저가 각 AI 모델별 분석 컨테이너를 생성·관리합니다.

         ┌── 분석엔진 (컨테이너 매니저 + 스케줄러 + 분석 컨테이너들)
         │
웹 서비스 ┤
         │
         └── 검색백엔드 ←── Kafka ←── 분석엔진

1. 시작 및 종료

컨테이너 매니저를 먼저 시작한 후 스케줄러를 시작해야 합니다.

# 컨테이너 매니저 시작
cd ~/engine/container_manager
./run.sh

# 스케줄러 시작
cd ~/engine/scheduler
./run.sh

# 상태 확인
docker ps --filter "name=container_manager" --filter "name=scheduler"

# 로그 확인
docker logs -f container_manager
docker logs -f scheduler

2. IP 및 연동 설정

스케줄러의 run.sh에서 각 컴포넌트의 IP와 포트를 환경 변수로 설정합니다.

컨테이너 매니저의 params.cfg에서는
분석 컨테이너들이 사용하는 환경 변수와 볼륨 마운트 경로를 설정합니다.

params.cfg 변경 후에는 기존 분석 컨테이너들도 리셋해야 새 설정이 적용됨
./reset_containers.sh <scheduler_host:port> 명령으로 일괄 리셋 가능

3. 분석 컨테이너 관리

컨테이너 매니저는 분석 요청에 따라 GPU가 연동된 분석 컨테이너를 자동으로 생성합니다.
각 컨테이너는 독립된 모델을 탑재하고 있으며,
분석이 완료되면 결과를 Kafka를 통해 검색백엔드로 전달합니다.

# 분석 컨테이너 일괄 리셋
./reset_containers.sh localhost:<SCHEDULER_PORT>

# 실행 중인 분석 컨테이너 확인
docker ps | grep analysis

분석 컨테이너 내부에서 GPU를 사용하므로 NVIDIA 드라이버 및 Container Toolkit이
정상 설치되어 있어야 함 (폐쇄망 AI Solution 개발환경 구축 (2) 참고)

18. 검색백엔드 배포

검색백엔드는 분석엔진의 결과를 수집·인덱싱하고, 조건 기반 검색 API를 제공하는 서비스입니다.
코드 개발은 별도 담당자가 수행하며,
폐쇄망 환경에서는 솔루션 담당자가 배포, 로그 확인, 장애 대응을 직접 수행합니다.

1. 구성 요소

2. 시작 및 종료

# Kafka
cd ~/infrastructure/kafka
docker compose up -d

# Elasticsearch
cd ~/infrastructure/elasticsearch
docker compose up -d

# 검색 API 서버
cd ~/search/api/docker
docker compose -f docker-compose.release.yml up -d

# 검색 오케스트레이터
cd ~/search/orchestrator/docker
docker compose -f docker-compose.release.yml up -d

3. IP 설정

각 컴포넌트의 .env 파일에서 IP와 포트를 설정합니다.

# 검색 API 서버 (.env)
SERVER_EXTERNAL_HOST=<검색_API_SERVER_IP>
ELASTICSEARCH_HOST=https://<ES_SERVER_IP>:<ES_PORT>
KAFKA_HOST=<KAFKA_SERVER_IP>

설정 변경 후 반드시 해당 컴포넌트를 재시작해야 적용됨

4. 로그 확인 및 에러 추적

# 컨테이너 로그
docker logs -f search_api
docker logs -f search_orchestrator

# 파일 로그
tail -f ~/search/api/logs/orchestration.log
tail -f ~/search/orchestrator/logs/orchestrator.log

5. 폐쇄망에서 직접 해결한 이슈

(1) Elasticsearch 디렉터리 권한 문제

Elasticsearch 컨테이너는 root가 아닌 전용 사용자(기본 UID 1000)로 실행됩니다.
호스트에 bind mount한 데이터/로그 디렉터리의 UID/GID가 일치하지 않으면
로그 파일 생성 및 rename 단계에서 JVM 초기화가 실패할 수 있습니다.

gc.log permission error
cannot change name gc.log to gc1.log

해당 오류는 GC 로그 파일에 대한 쓰기/rename 권한이 없어 발생한 문제였습니다.

일반적인 환경에서는 chown/chgrp를 통해 UID/GID를 일치시키는 것이 권장됩니다.
그러나 본 사례에서는 다음과 같은 제약이 존재했습니다.

• sudo 권한 미제공
• 호스트 파일 소유권 변경 불가
• 컨테이너 생성 권한만 허용

이 제약 하에서 컨테이너 내부 root 권한을 활용하여
bind mount된 디렉터리의 접근 권한을 간접적으로 조정하는 방식으로 대응했습니다.

docker run --rm -v /path/to/es_data:/data <image> chmod -R 777 /data
docker run --rm -v /path/to/es_logs:/data <image> chmod -R 777 /data

chmod 777은 보안상 권장되지 않지만,
권한이 제한된 환경에서 서비스 가동을 위한 현실적인 대응 전략임
동일 증상은 SELinux 컨텍스트 미적용에서도 발생할 수 있으며
이 경우 restorecon으로 해결 가능 (폐쇄망 AI Solution 개발환경 구축 (2) 참고)

(2) Elasticsearch 클러스터 재시작 시 노드 종료

Elasticsearch 클러스터를 최초로 부트스트랩한 뒤에는 docker-compose.yml의 cluster.initial_master_nodes 설정을 제거하는 것이 원칙입니다.
클러스터가 이미 형성된 상태에서 이 설정을 남겨두면,
재시작 시 불필요한 부트스트랩 시도를 유발하거나
cluster UUID 불일치로 실행 실패가 발생할 수 있습니다.

(3) Elasticsearch 인덱싱 확인

Elasticsearch와 Kibana를 실행한 뒤, Kibana UI를 통해 인덱싱 상태를 확인합니다.

Kibana 인덱스 관리 화면(/app/elasticsearch/content/search_indices)에서
인덱스 목록과 도큐먼트 수가 정상적으로 표시되고,
분석 이후 도큐먼트 수가 증가하는지 확인합니다.

도큐먼트 수가 증가하지 않으면 다음 순서로 점검합니다.

• Kafka 연결 상태 확인
• 검색백엔드 컨슈머/인덱서 로그 확인
• Elasticsearch 로그에서 인덱싱 에러(4xx/5xx) 확인

(4) Kafka 브로커 연결 실패

Kafka가 실행되었으나 분석엔진이나 검색 서버에서 연결하지 못하는 경우,
Kafka의 KAFKA_ADVERTISED_HOST_NAME이 실제 서버 IP와 일치하는지 확인합니다.

# Kafka env 파일 확인
KAFKA_ADVERTISED_HOST_NAME=<실제_서버_IP>

19. 웹 서비스 배포

웹 서비스는 사용자 대시보드, 분석 요청 및 결과 조회를 담당하는 서비스입니다.
코드 개발은 별도 담당자가 수행하며,
폐쇄망 환경에서는 솔루션 담당자가 배포, 로그 확인, 장애 대응을 직접 수행합니다.

1. 이미지 반입 및 실행

웹 서비스는 프론트엔드, 백엔드, DB(MySQL)로 구성되며,
각각 별도의 Docker 이미지를 tar로 반입하여 배포합니다.

# 이미지 로드
docker load -i web_frontend.tar.gz
docker load -i web_backend.tar.gz
docker load -i mysql.tar.gz

# 컨테이너 실행 (예: 프론트엔드)
docker run -d \
    --name web_frontend \
    --network="host" \
    -e PORT=<PORT> \
    -e HOSTNAME=0.0.0.0 \
    --restart unless-stopped \
    web_frontend:v1.0

백엔드와 DB도 동일한 방식으로 이미지 로드 후 컨테이너를 실행
버전 업데이트 시에는 기존 컨테이너를 중지·삭제한 뒤 새 이미지를 로드하여 재실행

2. DB 설정 (MySQL)

웹 백엔드의 설정은 MySQL DB를 통해 관리됩니다.

# DB 컨테이너 접속
docker exec -it db_container /bin/bash
mysql -u root -p
use app_db;

AI 모델 등록

INSERT INTO <모델_설정_테이블>
(name, description, ip, port, model_data)
VALUES
('VLM-7B', '멀티모달 모델', '<VLM_SERVER_IP>', '<VLM_PORT>', '/models/VLM-7B');

IP 설정 변경

UPDATE <시스템_설정_테이블> SET value = 'http://<HOST>:<PORT>' WHERE type = 'search.base-url';
UPDATE <시스템_설정_테이블> SET value = 'http://<HOST>:<PORT>' WHERE type = 'engine.base-url';

3. 운영 중 발생한 이슈

분석 에러 시 웹 무한 대기

분석 도중 에러가 발생하면 웹에서 분석 상태가 “진행 중”으로 멈추는 경우가 있습니다.
이때 DB에서 직접 status 값을 변경하여 강제로 실패 또는 완료 처리합니다.

-- 분석 상태 강제 변경 (실패 처리)
UPDATE <분석_작업_테이블> SET status = 'FAILED' WHERE task_id = <id>;

-- 또는 완료 처리
UPDATE <분석_작업_테이블> SET status = 'COMPLETED' WHERE task_id = <id>;

각 컴포넌트 간 연동은 일직선이 아니라 분석-웹, 분석-검색, 검색-웹 등 다대다 구조
에러 원인이 어느 연결에서 발생했는지 파악하는 것이 핵심

에러 추적 흐름

                ┌── 웹 (분석 상태 조회)
분석엔진 ──────┤
                └── Kafka → 검색백엔드 (결과 인덱싱)
                                 │
                            웹 (검색 결과 조회)

웹에서 무한 대기 발견
    ↓
1. 분석엔진 로그 확인 → 분석 자체가 실패했는지?
2. Kafka 연결 상태 확인 → 결과 전달이 끊겼는지?
3. 웹 백엔드 로그 확인 → 콜백을 수신하지 못했는지?
    ↓
원인에 따라 조치 (재시작 / DB 강제 변경 / 설정 수정)

폐쇄망에서는 솔루션 담당자가 모든 컴포넌트의 로그를 직접 확인해야 함
코드 수정이 필요한 경우 개발자에게 로그를 전달하고 수정된 이미지를 재반입

20. 통합 운영 및 테스트

1. 서비스 실행 순서

전체 서비스는 의존성에 따라 순서대로 실행해야 합니다.

1. 인프라 (Kafka, Elasticsearch)
    ↓
2. LLM 서빙 (SGLang / vLLM)
    ↓
3. 분석엔진 (컨테이너 매니저 → 스케줄러)
    ↓
4. 검색백엔드 (검색 API → 검색 오케스트레이터)
    ↓
5. 웹 서비스 (프론트엔드, 백엔드)

역순으로 종료하는 것을 권장
Kafka/Elasticsearch가 내려간 상태에서 분석이 실행되면 데이터 유실 가능

2. E2E 통합 테스트

모든 서비스가 실행된 후 다음 흐름을 순차적으로 검증합니다.

3. 운영 모니터링

4. 장애 대응

서비스 재시작

# 특정 컨테이너 재시작
docker restart <container_name>

# 분석 컨테이너 일괄 리셋
./reset_containers.sh <scheduler_host:port>

# docker compose 서비스 재시작
cd ~/search/api/docker
docker compose -f docker-compose.release.yml down
docker compose -f docker-compose.release.yml up -d

폐쇄망 특화 트러블슈팅

폐쇄망에서는 에러 발생 시 외부 지원이 제한되므로
로그 확인 → 원인 추적 → 조치의 흐름을 솔루션 담당자가 직접 수행해야 함

마무리

이번 글에서는 폐쇄망 환경에서 AI 서비스를 실제 운영 가능한 형태로 구성하고 배포했습니다.
모델 고도화부터 통합 운영까지 다음 단계를 직접 수행했습니다.

1. VLM 기반 OCR 파인튜닝 전략 수립 및 LoRA 적용

2. 추론 엔진 비교와 서빙 아키텍처 설계

3. 커스텀 아키텍처 VLM 제약 분석 및 대응

4. 분석엔진·검색 백엔드·웹 서비스 통합 구조 정리

5. 컨테이너 기반 배포 및 운영 안정화

6. 통합 테스트 및 장애 대응 체계 수립

일반적인 환경에서는 인프라, AI, 백엔드, 운영이 분리되지만,
폐쇄망 환경에서는 모델 학습부터 배포, 서비스 연동, 장애 대응까지
현장에서 통합적으로 판단하고 정리해야 합니다.

이번 프로젝트에서는
OS 설치와 네트워크 구성부터
GPU 드라이버·컨테이너 런타임·원격 개발 환경 구축,
모델 파인튜닝, 추론 엔진 선택 및 서빙 구조 설계,
분석엔진·검색 백엔드·웹 서비스 배포,
서비스 실행 순서 체계화와 현장 이슈 대응까지 맡으며
전체 시스템이 안정적으로 동작하도록 구조를 정리하고 조율하는 역할을 수행했습니다.

특히 범용 추론 엔진이 지원하지 않는 커스텀 아키텍처 VLM을
현장 환경에서 동작하도록 전환하고 검증한 과정은
기술 제약 속에서 현실적인 대안을 도출해야 했던 작업이었습니다.

모델 개발을 넘어 인프라·서빙·서비스 연동·운영 안정화까지 직접 다루며
AI 시스템을 구성 요소 단위가 아닌, 실제 운영되는 전체 시스템 기준으로 판단하게 되었습니다.

특정 조직의 내부 시스템이나 정책, 네트워크 설정은 포함하지 않으며
모든 내용은 공개된 기술과 일반적인 Linux 환경을 기반으로 구성되었습니다.

10. NVIDIA 드라이버 설치

NVIDIA 드라이버는 GPU 하드웨어를 제어하는 커널 모듈입니다.
NVIDIA 드라이버가 없으면 nvidia-smi 명령이 작동하지 않고, CUDA를 사용할 수 없습니다.
NVIDIA Container Toolkit을 사용하는 경우 호스트에는 NVIDIA 드라이버만 설치합니다.

1. GPU 장치 인식 확인

시스템에서 NVIDIA GPU가 정상적으로 인식되는지 확인합니다.
결과 미출력 시 BIOS에서 PCI 장치를 활성화하거나 슬롯 연결을 점검합니다.

lspci | grep -i nvidia

2. 기존 드라이버 제거

기존 NVIDIA 관련 드라이버나 nouveau 모듈이 있다면 제거합니다.
nouveau는 기본 커널 모듈로, 공식 NVIDIA 드라이버(nvidia.ko)와 충돌을 일으킬 수 있습니다.

sudo dnf remove -y '*nvidia*'
sudo dnf remove -y xorg-x11-drv-nouveau

3. nouveau 블랙리스트 설정

부팅 시 nouveau 모듈이 자동 로드되지 않도록 차단합니다.
modeset=0 설정은 X11 초기화 시 프레임버퍼 점유를 방지합니다.

sudo bash -c 'cat <<EOF > /etc/modprobe.d/blacklist-nouveau.conf
blacklist nouveau
options nouveau modeset=0
EOF'

생성되는 파일 경로:

/etc/modprobe.d/blacklist-nouveau.conf

4. 커널 빌드 도구 설치

NVIDIA 드라이버는 커널 모듈을 직접 빌드하기 때문에 버전에 맞는 개발 도구가 필요합니다.
uname -r 명령으로 커널 버전을 확인하고, kernel-devel 패키지의 버전이 일치해야 합니다.

gcc는 GNU Compiler Collection의 약자로, C/C++ 코드를 컴파일하여 실행 가능한 바이너리로 만드는 컴파일러입니다. NVIDIA 드라이버는 내부적으로 C 코드로 작성된 커널 모듈을 빌드하므로, gcc가 설치되어 있어야 설치 과정이 정상적으로 완료됩니다.

sudo dnf install -y gcc kernel-devel kernel-headers
uname -r
rpm -q kernel-devel

5. initramfs 재생성

initramfs는 부팅 시 커널이 로드하는 임시 루트 파일시스템입니다.
이전에 포함된 nouveau.ko를 제거하기 위해 새로 생성합니다.

sudo dracut --force

6. X11 종료 및 CLI 모드 전환

GUI(X11, GDM)가 실행 중이면 드라이버 설치가 실패할 수 있습니다.
CLI 모드로 전환하여 그래픽 세션을 종료합니다.

sudo systemctl set-default multi-user.target
sudo systemctl isolate multi-user.target

7. 시스템 재부팅

재부팅 후 다음 명령으로 nouveau가 비활성화되었는지 확인합니다.

sudo reboot

출력 결과가 없으면 성공적으로 비활성화된 것입니다.

lsmod | grep nouveau

8. NVIDIA 드라이버 설치

(1) RHEL 9 환경용 .rpm 드라이버 설치

NVIDIA 공식 사이트에서 nvidia-driver-local-repo-rhel9-580.*.rpm 패키지를 사용해
로컬 리포지토리를 구성한 뒤 설치할 수 있습니다.

이 파일은 폐쇄망 환경에서도 동작하는 오프라인 설치용 패키지입니다.
설치 후 자동으로 /var/nvidia-driver-local-repo-rhel9-580.* 경로에 드라이버 파일이 풀리고,
/etc/yum.repos.d/에 로컬 리포지토리가 등록됩니다.

설치 절차는 다음과 같습니다.

# 1. local repo 패키지 설치
sudo rpm -ivh nvidia-driver-local-repo-rhel9-580.95.05-1.0-1.x86_64.rpm

# 2. 리포지토리 등록 갱신
sudo dnf clean all
sudo dnf repolist

# 3. 드라이버 설치
sudo dnf install -y nvidia-driver

(2) .run 파일 방식 설치

.run 파일 방식으로도 설치할 수 있습니다.
이 방식은 커널 모듈을 직접 빌드하므로 인터넷 연결이 필요하지 않습니다.

설치 절차는 다음과 같습니다.

# 1. 실행 권한 부여
chmod +x NVIDIA-Linux-x86_64-580.95.05.run

# 2. 드라이버 설치
sudo bash NVIDIA-Linux-x86_64-580.95.05.run --no-cc-version-check

--no-cc-version-check 옵션은 GCC 버전 불일치 시에도 설치가 중단되지 않도록 하는 옵션입니다.
이 방식은 로컬 리포지토리 구성 없이 바로 설치할 수 있어 간편합니다.

(3) 설치 확인

드라이버 설치가 완료되면 시스템을 재부팅한 뒤, GPU 인식 여부를 확인합니다.

sudo reboot

재부팅 후 다음 명령을 실행합니다.

nvidia-smi

정상적으로 설치되었다면 다음과 같은 출력이 표시됩니다.

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 580.95.05              Driver Version: 580.95.05      CUDA Version: 13.0     |
+-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA B300 SXM6 AC            On  |   00000000:1A:00.0 Off |                    0 |
| N/A   27C    P0            139W / 1100W |       0MiB / 275040MiB |      0%      Default |
|                                         |                        |             Disabled |
+-----------------------------------------+------------------------+----------------------+
|   1  NVIDIA B300 SXM6 AC            On  |   00000000:3C:00.0 Off |                    0 |
| N/A   27C    P0            139W / 1100W |       0MiB / 275040MiB |      0%      Default |
|                                         |                        |             Disabled |
+-----------------------------------------+------------------------+----------------------+
|   2  NVIDIA B300 SXM6 AC            On  |   00000000:62:00.0 Off |                    0 |
| N/A   27C    P0            139W / 1100W |       0MiB / 275040MiB |      0%      Default |
|                                         |                        |             Disabled |
+-----------------------------------------+------------------------+----------------------+
|   3  NVIDIA B300 SXM6 AC            On  |   00000000:73:00.0 Off |                    0 |
| N/A   27C    P0            139W / 1100W |       0MiB / 275040MiB |      0%      Default |
|                                         |                        |             Disabled |
+-----------------------------------------+------------------------+----------------------+
|   4  NVIDIA B300 SXM6 AC            On  |   00000000:9A:00.0 Off |                    0 |
| N/A   27C    P0            139W / 1100W |       0MiB / 275040MiB |      0%      Default |
|                                         |                        |             Disabled |
+-----------------------------------------+------------------------+----------------------+
|   5  NVIDIA B300 SXM6 AC            On  |   00000000:BC:00.0 Off |                    0 |
| N/A   27C    P0            139W / 1100W |       0MiB / 275040MiB |      0%      Default |
|                                         |                        |             Disabled |
+-----------------------------------------+------------------------+----------------------+
|   6  NVIDIA B300 SXM6 AC            On  |   00000000:DF:00.0 Off |                    0 |
| N/A   27C    P0            139W / 1100W |       0MiB / 275040MiB |      0%      Default |
|                                         |                        |             Disabled |
+-----------------------------------------+------------------------+----------------------+
|   7  NVIDIA B300 SXM6 AC            On  |   00000000:F0:00.0 Off |                    0 |
| N/A   27C    P0            139W / 1100W |       0MiB / 275040MiB |      0%      Default |
|                                         |                        |             Disabled |
+-----------------------------------------+------------------------+----------------------+

Driver Version과 CUDA Version이 정상적으로 표시되면 드라이버 설치가 완료된 것입니다.

9. 그래픽 모드 복원 및 확인

CLI 모드에서 설치를 완료한 경우,
GUI 환경이 필요하다면 다음 명령으로 그래픽 모드를 복원합니다.

sudo systemctl set-default graphical.target
sudo reboot

.run 방식과 .rpm 방식 비교

전체 절차 요약

# 1. 기존 드라이버 및 nouveau 제거
sudo dnf remove -y '*nvidia*'
sudo dnf remove -y xorg-x11-drv-nouveau

# 2. 블랙리스트 등록
sudo bash -c 'cat <<EOF > /etc/modprobe.d/blacklist-nouveau.conf
blacklist nouveau
options nouveau modeset=0
EOF'

# 3. 커널 빌드 도구 설치
sudo dnf install -y gcc kernel-devel kernel-headers

# 4. initramfs 재생성
sudo dracut --force

# 5. CLI 모드 전환 후 재부팅
sudo systemctl set-default multi-user.target
sudo reboot

# 6-1. NVIDIA 드라이버 설치 (rpm 방식)
sudo rpm -ivh nvidia-driver-local-repo-rhel9-580.95.05-1.0-1.x86_64.rpm
sudo dnf clean all
sudo dnf install -y nvidia-driver

# 6-2. NVIDIA 드라이버 설치 (run 방식)
chmod +x NVIDIA-Linux-x86_64-580.95.05.run
sudo bash NVIDIA-Linux-x86_64-580.95.05.run --no-cc-version-check

# 7. 그래픽 모드 복귀 및 확인
sudo systemctl set-default graphical.target
sudo reboot

nouveau 비활성화 → initramfs 재생성 → CLI 전환 → 드라이버 설치 순서를 지켜야 함
6단계에서 .rpm 방식(6-1) 또는 .run 방식(6-2) 중 선택

11. NVIDIA Container Toolkit 설치

NVIDIA Container Toolkit은 컨테이너의 GPU 인식을 지원하는 핵심 구성 요소입니다.
미설치시 컨테이너 내부에서 nvidia-smi 명령이 동작하지 않으며,
AI 모델 학습이나 추론 시 GPU 가속을 사용할 수 없습니다.

1. 구성 요소

NVIDIA Container Toolkit은 다음 패키지들로 구성됩니다.

2. 설치 전제 조건

NVIDIA 커널 드라이버(nvidia.ko)가 이미 설치되어 있어야 합니다.
설치하려는 NVIDIA Container Toolkit 버전은 드라이버 버전과 호환되어야 합니다.

드라이버 설치 여부 확인:

nvidia-smi

버전 호환성 예시:

• driver 580.95.05 → toolkit 1.18.0 사용 가능
• driver 550.78 → toolkit 1.17.9 사용 가능

3. 설치 절차

GitHub Release에서 직접 받은 .rpm 파일은 별도의 리포지토리 등록 없이
dnf install -y *.rpm 명령어로 설치할 수 있습니다.
의존성 순서가 있기 때문에 위 순서를 지키는 것이 안정적입니다.

NVIDIA Container Toolkit 설치 후에는 재부팅이 필요하지 않으며,
Docker 또는 Podman 런타임에서 GPU를 인식하도록 설정만 추가하면 됩니다.

# 1. GitHub Release에서 패키지 다운로드
# https://github.com/NVIDIA/nvidia-container-toolkit/releases
# (예: 1.18.0 버전 기준)
libnvidia-container1-1.18.0-1.x86_64.rpm
libnvidia-container-tools-1.18.0-1.x86_64.rpm
nvidia-container-toolkit-base-1.18.0-1.x86_64.rpm
nvidia-container-toolkit-1.18.0-1.x86_64.rpm

# 2. 설치 실행
export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.18.0-1
sudo dnf install -y \
  libnvidia-container1-${NVIDIA_CONTAINER_TOOLKIT_VERSION}.x86_64.rpm \
  libnvidia-container-tools-${NVIDIA_CONTAINER_TOOLKIT_VERSION}.x86_64.rpm \
  nvidia-container-toolkit-base-${NVIDIA_CONTAINER_TOOLKIT_VERSION}.x86_64.rpm \
  nvidia-container-toolkit-${NVIDIA_CONTAINER_TOOLKIT_VERSION}.x86_64.rpm

4. 설치 확인

설치된 패키지 목록을 확인할 수 있습니다.

rpm -qa | grep nvidia-container

출력 예시:

libnvidia-container1-1.18.0-1.x86_64
libnvidia-container-tools-1.18.0-1.x86_64
nvidia-container-toolkit-base-1.18.0-1.x86_64
nvidia-container-toolkit-1.18.0-1.x86_64

NVIDIA Container Toolkit CLI 버전을 확인합니다.

nvidia-ctk --version

출력 예시:

NVIDIA Container Toolkit CLI version 1.18.0

정상적으로 설치되었다면 /etc/nvidia-container-runtime/config.toml 파일이 존재하며,
NVIDIA Container Toolkit 설정이 적용된 상태입니다.

ls /etc/nvidia-container-runtime/
cat /etc/nvidia-container-runtime/config.toml | head -n 10

호스트 CUDA 설치에서 컨테이너 격리로: CUDA 설치가 필요 없어진 이유

과거에는 환경 설정이 딥러닝 학습의 최대 진입장벽 중 하나였습니다.

Windows 환경에서는 CUDA Toolkit 설치 단계부터 Visual Studio 버전 제약으로 막히는 경우가 많았고, OpenCV 같은 복잡한 라이브러리는 빌드 실패와 재시도를 며칠에 걸쳐 반복해야 했습니다.
Ubuntu는 CUDA/cuDNN 설치가 비교적 수월했으나 OpenCV 빌드 시 WITH_QT, WITH_FFMPEG 같은 옵션 조합에서 충돌이 반복되었습니다.

그러나 Docker 기반 워크플로우로 전환된 이후부터는 상황이 크게 달라졌습니다.
호스트에는 드라이버만 설치하면 되고, CUDA/cuDNN은 모두 컨테이너에 포함되기 때문에
환경 구성으로 인한 문제는 사실상 사라졌습니다.

1. 호스트 직접 설치 방식 (conda)

• 호스트에 NVIDIA 드라이버 + CUDA Toolkit + cuDNN 설치 필요
• Windows의 경우 Visual Studio, CMake, Ninja 등 추가 개발 도구 필수
• OpenCV 소스 빌드 시 Qt/GTK GUI 옵션과 FFmpeg 의존성 충돌이 빈번
• CUDA/cuDNN/PyTorch 버전 조합을 맞추는 데 많은 시간 소모
• 프로젝트마다 다른 CUDA 버전을 쓰면 호스트 환경 충돌 발생
• 현재도 Jupyter 기반 로컬 개발, 빠른 프로토타이핑에는 유용함

2. 컨테이너 방식 (Docker + NVIDIA Container Toolkit)

• 호스트에는 NVIDIA 드라이버만 설치하면 충분
• CUDA Toolkit, cuDNN, AI 프레임워크는 컨테이너 이미지에 포함
• 호스트는 GPU 하드웨어 제어만 담당
• 프로젝트마다 CUDA 버전이 달라도 컨테이너로 격리되어 충돌 없음
• 환경 재현성이 높고, 학습·배포·운영까지 동일한 구성 유지 가능
• 프로덕션·학습 환경에서는 사실상 표준

단, 호스트에서 직접 CUDA C++ 컴파일을 수행해야 하는 경우 CUDA Toolkit 설치 필요
→ PyTorch C++ Extension, TensorRT 플러그인, FlashAttention·xFormers 등 고성능 CUDA 커널, NVDEC/NPP 기반 미디어 처리 등

12. Docker 설치 및 GPU 연동

Docker를 설치해 컨테이너 기반 개발 환경을 구성합니다.
NVIDIA Container Toolkit과 연동하여 GPU를 사용할 수 있도록 설정합니다.

1. Docker 설치

사전에 다운로드한 .rpm 파일을 사용해 Docker를 설치합니다.

# Docker 설치
sudo dnf install -y ./containerd.io-*.rpm \
  ./docker-ce-*.rpm \
  ./docker-ce-cli-*.rpm \
  ./docker-buildx-plugin-*.rpm \
  ./docker-compose-plugin-*.rpm

# 서비스 등록 및 실행
sudo systemctl enable --now docker
sudo systemctl status docker

2. NVIDIA Container Toolkit 연동

NVIDIA Container Toolkit을 Docker 런타임에 연결하면
컨테이너 내부에서도 GPU가 인식되어 CUDA 연산을 사용할 수 있습니다.

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

3. 사용자 권한 설정

현재 사용자를 docker 그룹에 추가해야 루트 권한 없이 명령을 실행할 수 있습니다.
변경 사항은 새 터미널 세션에서 적용됩니다.

sudo usermod -aG docker $USER

4. 컨테이너 생성 및 이미지 관리

폐쇄망 환경에서는 Docker Hub에 직접 접근할 수 없으므로,
외부 인터넷 환경에서 이미지를 준비해 tar 파일 형태로 반입해야 합니다.

이미지를 만드는 방법은 두 가지입니다.

1. Dockerfile 방식
2. docker commit 방식

두 방식 모두 최종적으로 docker save로 tar 파일을 생성해 반입합니다.

Dockerfile

가장 일반적이며 재현성과 협업·버전 관리에 유리합니다.
동일 Dockerfile로 언제든지 같은 환경을 다시 만들 수 있고 Git으로 관리가 가능합니다.

# Dockerfile
FROM pytorch/pytorch:2.4.0-cuda12.4

# 시스템 패키지 설치
RUN apt-get update && \
    apt-get install -y vim git wget && \
    rm -rf /var/lib/apt/lists/*

# Python 패키지 설치
RUN pip install --no-cache-dir numpy pandas scikit-learn opencv-python

# 작업 디렉터리 설정
WORKDIR /workspace

# 이미지 빌드
docker build -t idxkim_image:v0.1 .

# 이미지를 tar로 저장
docker save -o idxkim_image_v0.1.tar idxkim_image:v0.1

분석 엔진 개발, 프로덕션 배포, 팀 간 협업 환경에 적합하며
CI/CD 파이프라인 구축에 활용됩니다.

docker commit

컨테이너 내부에서 직접 패키지를 설치하고, 그 실행 상태 그대로 스냅샷을 저장하는 방식입니다. 재현성은 Dockerfile보다 떨어지지만, 파인튜닝·실험·일회성 분석에 빠르게 활용할 수 있습니다.

# 1. 베이스 이미지 다운로드
docker pull pytorch/pytorch:2.4.0-cuda12.4

# 2. 컨테이너 실행 및 필요한 패키지 설치
docker run -it --name temp_container pytorch/pytorch:2.4.0-cuda12.4 /bin/bash
# (컨테이너 내부에서)
# apt-get update && apt-get install -y vim git wget
# pip install numpy pandas scikit-learn opencv-python
# exit

# 3. 커스텀 이미지로 저장
docker commit temp_container idxkim_image:v0.1
docker rm temp_container

# 4. 이미지를 tar로 저장
docker save -o idxkim_image_v0.1.tar idxkim_image:v0.1

모델 파인튜닝, 데이터 전처리 파이프라인 테스트, 라이브러리 조합 탐색 등
일회성 분석 및 실험 환경에 활용됩니다.

두 방식 비교

폐쇄망 반입 방법

두 방식 중 무엇을 사용하든 tar 파일 형태로 반입합니다. tar 파일 방식을 사용하는 이유는 다음과 같습니다.

• 외부에서 검증된 환경을 그대로 가져올 수 있음
• 폐쇄망 내부에서 재빌드할 필요 없음
• 의존성 충돌 없이 동일한 환경 보장
• 물리적 이동만으로 환경 복제 가능

# 외부 환경에서 이미지 검증 완료 후 저장
docker save -o idxkim_image_v0.1.tar idxkim_image:v0.1

# 폐쇄망 내부에서 즉시 사용
docker load -i idxkim_image_v0.1.tar
docker run --gpus all idxkim_image:v0.1  # 바로 실행 가능

commit 이미지에서 Dockerfile 복원하기

docker commit으로 만든 이미지를 Dockerfile로 되돌릴 수 있는지는
원본 Dockerfile의 존재 여부에 따라 결정됩니다.

원본 Dockerfile이 없는 경우

설치 패키지 정보를 기반으로 유사한 Dockerfile을 작성할 수 있지만 완전한 복원은 불가능합니다.

# 이미지에서 컨테이너 실행
docker run -it idxkim_image:v0.1 /bin/bash

# 시스템 패키지 목록 추출
apt list --installed > apt_packages.txt
dpkg -l > dpkg_list.txt

# Python 패키지 정확한 버전 추출
pip freeze > requirements.txt

# 설치된 CUDA 버전 확인
ls /usr/local/cuda*/bin/
which nvidia-smi

추출한 정보로 Dockerfile을 재작성합니다.

FROM pytorch/pytorch:2.4.0-cuda12.4

# apt_packages.txt 참고하여 필요한 패키지만 선택
RUN apt-get update && \
    apt-get install -y \
    vim \
    git \
    wget \
    && rm -rf /var/lib/apt/lists/*

# requirements.txt 그대로 사용
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

WORKDIR /workspace

그러나 다음과 같은 정보는 복원할 수 없습니다.

• 설치 순서 및 의존성 설치 흐름
• 빌드 스크립트의 컴파일 옵션 (FFmpeg/OpenCV 빌드 플래그 등)
• 환경 변수 및 커스텀 스크립트
• 중간 레이어가 어떤 명령으로 만들어졌는지에 대한 정보

원본 Dockerfile이 있는 경우

원본 Dockerfile과 빌드 스크립트를 보유하고 있다면,
docker commit으로 만든 이미지든 tar 파일이든 상관없이
언제든지 동일한 환경을 재생성할 수 있습니다.

Dockerfile은 환경 구성의 설계도이므로,
이를 보관하면 필요할 때마다 동일한 환경을 재현할 수 있습니다.

5. GPU 테스트

커스텀 이미지에 nvidia-smi와 PyTorch가 모두 포함되어 있으므로,
하나의 이미지로 GPU 드라이버 및 CUDA 연동을 모두 확인할 수 있습니다.

# nvidia-smi로 GPU 드라이버 확인
docker run --rm --gpus all idxkim_image:v0.1 nvidia-smi

# PyTorch로 CUDA 가용성 확인
docker run --rm --gpus all idxkim_image:v0.1 \
  python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'GPU count: {torch.cuda.device_count()}')"

GPU 정보가 정상적으로 출력되면 Docker와 NVIDIA 런타임 연동이 완료된 것입니다.

12-1. Docker 데이터 저장 경로 변경

Docker 설치 후 저장 경로(/var/lib/docker)를 변경해야 하는 경우에만 수행합니다.
새 설치 시에는 /etc/docker/daemon.json 파일로 경로를 미리 지정하세요.

주의사항

• 레이어 손상 위험: 복사 중 중단되면 컨테이너 실행이 실패할 수 있습니다.
• 다운타임 발생: 모든 컨테이너를 중지한 상태에서 작업해야 합니다.
• 백업 권장: 중요한 컨테이너나 이미지는 사전에 백업해 두는 것이 안전합니다.
• SELinux 컨텍스트: 경로 변경 후 새 디렉터리에 SELinux 컨텍스트를 등록해야 합니다.
  등록하지 않으면 이후 볼륨 마운트 시 권한 문제가 발생할 수 있습니다.

# 새 경로에 SELinux 컨텍스트 등록
sudo semanage fcontext -a -t container_var_lib_t "/home/docker(/.*)?"
sudo restorecon -Rv /home/docker

1. 데이터 디렉터리 이동

Docker 서비스를 중지하고 기존 데이터를 새 경로로 복사합니다.

sudo systemctl stop docker
sudo mkdir -p /home/docker
sudo rsync -aP /var/lib/docker/ /home/docker/
sudo vi /etc/docker/daemon.json

/etc/docker/daemon.json 수정 내용:

{
    "data-root": "/home/docker",
    "runtimes": {
        "nvidia": {
            "args": [],
            "path": "nvidia-container-runtime"
        }
    }
}

2. 서비스 재시작 및 확인

Docker 데몬을 다시 로드하고 경로 변경을 확인합니다.

sudo systemctl daemon-reload
sudo systemctl start docker
docker info | grep "Docker Root Dir"

출력 예시:

Docker Root Dir: /home/docker

정상적으로 변경되면 기존 디렉터리를 제거합니다.

sudo rm -rf /var/lib/docker

12-2. 설치 전 데이터 경로 지정 (사전 설정 방식)

Docker 설치 전에 데이터 경로를 지정하는 방법입니다. 이후 일반적인 Docker 설치 절차를 진행하면 초기부터 /home/docker 경로를 사용하게 됩니다.

sudo mkdir -p /home/docker
sudo mkdir -p /etc/docker
sudo bash -c 'cat <<EOF > /etc/docker/daemon.json
{
  "data-root": "/home/docker"
}
EOF'

12-3. 명령어 자동 완성 설치 (선택)

docker 및 podman 명령의 자동 완성이 활성화되어 명령 입력 효율이 향상됩니다.

sudo dnf install -y bash-completion

13. Podman 설치 및 GPU 연동

Podman은 데몬(daemon) 없이 동작하는 컨테이너 엔진입니다.
데몬은 백그라운드에서 상시 실행되는 서비스 프로세스로,
Docker는 dockerd라는 데몬을 통해 컨테이너를 관리하지만
Podman은 명령 실행 시 즉시 컨테이너를 생성·종료합니다.
따라서 Rootless 실행이 가능하고 보안성이 높습니다.

RHEL 9에서는 Podman이 기본 컨테이너 엔진으로 권장됩니다.

Docker vs Podman 주요 차이점

중요: GPU 사용 시 옵션이 다름
Docker: docker run --gpus all <image>
Podman: podman run --device nvidia.com/gpu=all <image>

1. Podman 설치

Podman은 별도의 데몬이 필요하지 않으며, 설치 직후 바로 사용 가능합니다.

# Podman 설치
sudo dnf install -y podman

2. NVIDIA Container Toolkit 연동

cdi generate는 Podman용 GPU 장치 매핑 설정 파일(/etc/cdi/nvidia.yaml)을 생성합니다. Docker의 runtime configure 명령과 동일한 역할을 수행합니다.

sudo nvidia-ctk cdi generate --output=/etc/cdi/nvidia.yaml

3. 컨테이너 이미지 로드 및 실행

커스텀 이미지를 로드하고 GPU 연동을 테스트합니다.

# 커스텀 이미지 로드
sudo podman load -i idxkim_image_v0.1.tar

# nvidia-smi로 GPU 드라이버 확인
sudo podman run --rm -it \
  --device nvidia.com/gpu=all \
  idxkim_image:v0.1 \
  nvidia-smi

# PyTorch로 CUDA 가용성 확인
sudo podman run --rm -it \
  --device nvidia.com/gpu=all \
  idxkim_image:v0.1 \
  python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'GPU count: {torch.cuda.device_count()}')"

정상적으로 GPU 정보가 출력되면 Podman과 NVIDIA Container Toolkit이 연동된 것입니다.

4. 작업용 컨테이너 실행 예시

실제 개발 작업을 위한 컨테이너를 실행합니다.

sudo podman run -it --rm \
  --device nvidia.com/gpu=all \
  --shm-size=100g \
  -v /workspace:/workspace \
  idxkim_image:v0.1

13-1. Podman 데이터 저장 경로 변경

Podman 설치 후 저장 경로(/var/lib/containers)를 변경해야 하는 경우에만 수행합니다.
새 설치 시에는 /etc/containers/storage.conf 파일로 경로를 미리 지정하세요.

주의사항

• 레이어 손상 위험: 복사 중 중단되면 컨테이너 실행이 실패할 수 있습니다.
• 다운타임 발생: 모든 컨테이너를 중지한 상태에서 작업해야 합니다.
• 백업 권장: 중요한 컨테이너나 이미지는 사전에 백업해 두는 것이 안전합니다.
• Rootless 모드: Rootless 환경은 ~/.local/share/containers 경로도 함께 확인해야 합니다.

1. 데이터 디렉터리 이동

Podman 컨테이너를 중지하고 기존 데이터를 새 경로로 복사합니다.

sudo podman stop --all
sudo du -sh /var/lib/containers
sudo mkdir -p /home/podman
sudo rsync -aP /var/lib/containers/ /home/podman/
sudo vi /etc/containers/storage.conf

/etc/containers/storage.conf 수정 내용:

[storage]
driver = "overlay"
runRoot = "/run/containers/storage"
graphRoot = "/home/podman"

[storage.options]
additionalimagestores = []

2. 적용 및 확인

설정을 다시 로드하고 경로 변경을 확인합니다.

sudo systemctl daemon-reexec
sudo systemctl start podman
podman info | grep graphRoot

출력 예시:

graphRoot: /home/podman

정상적으로 변경되면 기존 디렉터리를 제거합니다.

sudo rm -rf /var/lib/containers

13-2. 설치 전 데이터 경로 지정 (사전 설정 방식)

Podman 설치 전에 데이터 저장 경로를 변경하는 방법입니다.
이후 일반적인 Podman 설치 절차를 진행하면 초기부터 /home/podman 경로를 사용합니다.

sudo mkdir -p /home/podman
sudo mkdir -p /etc/containers
sudo bash -c 'cat <<EOF > /etc/containers/storage.conf
[storage]
driver = "overlay"
runRoot = "/run/containers/storage"
graphRoot = "/home/podman"

[storage.options]
additionalimagestores = []
EOF'

13-3. 명령어 자동 완성 설치 (선택)

podman 및 docker 명령 자동 완성이 활성화되어 명령 입력 효율이 향상됩니다.

sudo dnf install -y bash-completion

14. VSCode Remote-SSH 설치

폐쇄망 환경에서 VSCode를 이용해 원격 개발 환경(SSH)을 구성합니다.
호스트는 RHEL 9, 클라이언트는 Windows 10 기준이며,
2025.11 기준 최신 VSCode 버전 1.105.1 (커밋 해시 7d842fb85a0275a4a8e4d7e040d2625abbf7f084)을 사용합니다.

1. 커밋 해시 확인

버전: 1.105.1
커밋: 7d842fb85a0275a4a8e4d7e040d2625abbf7f084

VSCode를 실행한 후 도움말 > 정보(About) 에서 버전과 커밋 해시를 확인할 수 있습니다.
클라이언트(Windows)와 호스트(RHEL)의 커밋 해시는 반드시 동일해야 합니다.

2. 설치 파일 준비

3. 확장 프로그램 다운로드 (.vsix 파일)

VSCode에서 확장의 .vsix 파일을 다운로드합니다.

1. VSCode를 실행합니다.
2. 확장 탭에서 필요한 확장을 검색합니다.
3. 마우스 오른쪽 버튼을 클릭한 후 “.vsix 파일 다운로드”를 선택합니다.

다운로드한 .vsix 파일은 오프라인 환경에서 확장 설치 시 사용합니다.

4. VSCode Server 다운로드

VSCode Server는 클라이언트와 동일한 커밋 해시를 기준으로 다운로드해야 합니다.

다운로드 경로:

https://update.code.visualstudio.com/commit/<commit-hash>/server-linux-x64/stable

예시:

https://update.code.visualstudio.com/commit/7d842fb85a0275a4a8e4d7e040d2625abbf7f084/server-linux-x64/stable

다운로드한 파일명은 vscode-server-linux-x64.tar.gz 입니다.

5. 호스트 설치 절차 (RHEL 9)

(1) VSCode 설치 (root 권한)

사전에 다운로드한 .rpm 파일을 사용해 VSCode를 설치합니다.

sudo dnf install -y code-1.105.1-1760482588.el8.x86_64.rpm

(2) 사용자별 확장 설치

사용자 계정에 필요한 확장을 설치합니다.

# .vsix 파일이 위치한 경로로 이동
cd /path/to/vsix/files

# 확장 설치
code --install-extension *.vsix

# 설치 확인
code --list-extensions --show-versions

(3) VSCode Server 구성

폐쇄망에서는 VSCode가 서버 파일을 자동으로 다운로드할 수 없으므로
vscode-server-linux-x64.tar.gz 파일을 사전에 준비하고 직접 설치해야 합니다.

COMMIT_HASH="7d842fb85a0275a4a8e4d7e040d2625abbf7f084"
mkdir -p ~/.vscode-server/cli/servers/Stable-${COMMIT_HASH}/server
cd ~/.vscode-server/cli/servers/Stable-${COMMIT_HASH}/server
tar -xzf ~/vscode-server-linux-x64.tar.gz --strip-components=1
chown -R $USER:$USER ~/.vscode-server
chmod -R 755 ~/.vscode-server

설치 후 디렉터리 구조 예시:

~/.vscode-server/
 └── cli/
     └── servers/
         └── Stable-7d842fb85a0275a4a8e4d7e040d2625abbf7f084/
             └── server/
                 ├── bin/
                 ├── node
                 ├── extensions/
                 ├── out/
                 ├── package.json
                 └── product.json

온라인 환경에서 이미 구성된 ~/.vscode-server 디렉터리를 tar로 복사하여 사용 가능
예: tar -czf vscode-server-copy.tar.gz ~/.vscode-server
→ 오프라인 서버로 옮겨 tar -xzf vscode-server-copy.tar.gz -C ~ 실행

6. 클라이언트 설치 절차 (Windows 10)

(1) VSCode 설치

VSCodeUserSetup-x64-1.105.1.exe 파일을 실행하여 기본 옵션으로 설치합니다.

(2) 확장 설치

다운로드한 .vsix 파일을 사용해 확장을 설치합니다.

VSCode 실행 → 확장 탭 → 우측 상단 점 3개 메뉴 → “.vsix 파일에서 설치” 선택 후 파일 지정

(3) 설정 파일 수정

폐쇄망 환경에서 VSCode가 자동 업데이트 및 서버 다운로드를 시도하지 않도록 설정합니다.

Ctrl + Shift + P → Preferences: Open User Settings (JSON)

다음 내용을 추가합니다.

{
  "update.mode": "none",
  "extensions.autoUpdate": false,
  "extensions.autoCheckUpdates": false,
  "remote.SSH.useLocalServer": false,
  "remote.SSH.localServerDownload": "off",
  "remote.SSH.allowLocalServerDownload": false,
  "remote.SSH.showLoginTerminal": true,
  "http.proxySupport": "off"
}

"allowLocalServerDownload": false 옵션으로 서버 자동 다운로드 차단

(4) SSH 구성 추가

SSH 연결 정보를 설정 파일에 추가합니다.

Ctrl + Shift + P → Remote-SSH: Open SSH Configuration File

C:\Users\<사용자명>\.ssh\config 파일을 편집합니다.

Host gpu-server
    HostName 192.168.0.50
    User idxkim
    Port 22

(5) Dev Container 연결 (폐쇄망 환경 수동 설정)

폐쇄망에서는 VSCode가 Dev Container 서버 파일을 자동으로 다운로드할 수 없습니다.
따라서 한 번 연결 시도 후 생성되는 캐시 경로에 서버 파일을 직접 복사해야 합니다.

1. Dev Container 연결을 한 번 시도합니다.
2. 연결이 실패하면 다음 경로가 자동으로 생성됩니다.

C:\Users\<username>\AppData\Local\Temp\vsch\serverCache\<commit_id>\

1. 위 폴더에 vscode-server-linux-x64.tar.gz 파일을 복사합니다.
2. VSCode에서 재연결 시도 시 해당 파일을 사용해 컨테이너 내부로 서버가 복사됩니다.

캐시 폴더는 임시 디렉터리이므로 삭제되면 동일한 절차를 다시 수행해야 함

작동 원리 참고

• VSCode는 Dev Container를 연결할 때 vscode-server-linux-x64.tar.gz 파일을 다운로드하려 시도하며, 그 직전에 serverCache 폴더를 생성합니다.
• 폐쇄망에서는 다운로드가 실패하지만, 폴더는 오류 직전 단계에서 자동으로 만들어집니다.
• 이 폴더에 서버 파일을 넣으면 VSCode가 다음 연결 시 해당 파일을 재사용해
  컨테이너 내부에 서버를 설치합니다.
• 단, 한 번도 실행을 시도하지 않았다면 serverCache 폴더는 존재하지 않으며
  수동으로 폴더를 만들어도 VSCode가 인식하지 못할 수 있습니다.

14-1. VSCode 비밀번호 자동 입력 (SSH Key 설정)

1. SSH 키 생성 (Windows)

RSA 키 쌍을 생성합니다.
경로와 패스프레이즈는 기본값을 사용합니다(엔터 3회).

ssh-keygen -t rsa -b 4096

2. 공개키 확인

생성된 공개키를 확인합니다.

Get-Content ~/.ssh/id_rsa.pub

3. 서버 계정 전환 (RHEL)

SSH 키를 등록할 계정으로 전환합니다.

su - <계정명>

4. SSH 디렉터리 생성

SSH 키를 저장할 디렉터리를 생성하고 권한을 설정합니다.

mkdir -p ~/.ssh
chmod 700 ~/.ssh

5. 공개키 등록

Windows에서 확인한 공개키(ssh-rsa ...)를 authorized_keys 파일에 추가합니다.
파일 편집 후 Ctrl+O → Enter로 저장하고 Ctrl+X로 종료합니다.

nano ~/.ssh/authorized_keys

6. 파일 권한 설정

SSH 인증을 위한 파일 권한을 설정합니다.

chmod 600 ~/.ssh/authorized_keys
chown -R $USER:$USER ~/.ssh

7. SELinux 컨텍스트 복원

SELinux가 활성화된 경우 SSH 디렉터리의 보안 컨텍스트를 복원합니다.

restorecon -R -v ~/.ssh

8. SSH 설정 파일 열기 (Windows)

VSCode 명령 팔레트에서 SSH 설정 파일을 엽니다.

Ctrl + Shift + P → Remote-SSH: Open SSH Configuration File

9. SSH 호스트 추가

C:\Users\<사용자명>\.ssh\config 파일에 서버 정보를 추가합니다.

Host gpu-server
    HostName 192.168.1.50
    User idxkim
    IdentityFile ~/.ssh/id_rsa

10. 연결 테스트

VSCode에서 서버로 연결을 시도합니다.
비밀번호 입력 없이 자동으로 로그인되면 SSH 키 인증이 정상적으로 설정된 것입니다.

Ctrl + Shift + P → Remote-SSH: Connect to Host → gpu-server

마무리

폐쇄망 환경에서 AI Solution 개발환경 구축의 핵심 인프라 구성이 완료되었습니다.
이번 글에서는 GPU 기반 컨테이너 환경과 원격 개발 환경을 중심으로 다음 과정을 진행했습니다.

1. GPU 드라이버 및 런타임 구성
   • NVIDIA 드라이버 설치 및 nouveau 모듈 비활성화
   • NVIDIA Container Toolkit 설치로 GPU 컨테이너 연동 구성
2. 컨테이너 엔진 설치 및 GPU 연동
   • Docker 및 Podman 설치
   • Docker(runtime configure)와 Podman(CDI generate) 설정을 통한 GPU 접근 구성
   • 데이터 저장 경로 변경 및 최적화
3. 원격 개발 환경 구성
   • VSCode Remote-SSH 오프라인 설치
   • Dev Container 수동 연결 및 SSH Key 기반 자동 인증 설정

이로써 폐쇄망 환경에서도 GPU를 활용한 컨테이너 기반 AI 개발 환경이 구축되었습니다.

다음 편에서는 AI Solution 서비스 구성 및 배포로 이어집니다.

폐쇄망에서는 다음과 같은 제약이 있습니다:

• 인터넷을 통한 패키지 다운로드 불가 (apt install, pip install 등)
• 클라우드 서비스 접근 불가 (GitHub, Docker Hub, PyPI 등)
• 모든 소프트웨어와 데이터는 USB, 외장 SSD 등 물리적 매체로 전달

따라서, 폐쇄망에서 AI Solution 개발환경을 구축하려면
사전에 모든 필요한 소프트웨어, 패키지, 모델 파일을 준비하고,
오프라인 상태에서도 완전히 작동하는 독립적인 환경을 만들어야 합니다.

이 글은 실제 폐쇄망 환경 구축 경험을 바탕으로 작성되었습니다.
RHEL 9을 기준으로 하지만, 다른 Linux 배포판에서도 동일한 방식으로 적용할 수 있습니다.

특정 조직의 내부 시스템이나 정책, 네트워크 설정은 포함하지 않으며
모든 내용은 공개된 기술과 일반적인 Linux 환경을 기반으로 구성되었습니다.

1. 준비물

하드웨어

소프트웨어 (사전 다운로드 필요)

폐쇄망 반입 전 모든 파일의 무결성 검증(해시 체크) 및 보안 스캔을 권장함

2. 설치 미디어 준비

ISO 다운로드

• 경로: Red Hat Developers 사이트 (공식 포털이 아닌 developers 사이트에서 무료 회원가입 후 다운로드 가능)
• 파일 형태: rhel-9.x-x86_64-dvd.iso
• 용량: 약 12GB

• 버전 확인 및 무결성 검증:

  sha256sum rhel-9.x-x86_64-dvd.iso
  

  → 제공된 해시값과 동일한지 확인

Developers용 ISO는 구독 없이도 다운로드 가능하며, 테스트·폐쇄망 개발용으로 적합

3. 설치 USB 제작

도구: Rufus

• Rufus 공식 사이트에서 다운로드
• ISO 파일(rhel-9.x-x86_64-dvd.iso) 선택 후 USB 굽기

• 설정 권장값:

  • 파티션 방식: GPT
  • 대상 시스템: UEFI
  • 파일 시스템: NTFS (4GB 초과 파일 복사 가능)
  • 빠른 포맷 체크
• USB 용량: 최소 16GB 이상 권장

복사 후 USB에 EFI, BaseOS, AppStream 폴더가 보이면 성공

4. ISO 구조 확인

ISO 내부 주요 폴더

• /BaseOS – 운영체제 핵심 패키지 (커널, 라이브러리 등)
• /AppStream – 개발 도구 및 응용 프로그램 모듈

설치용 ISO를 마운트하면 이 두 폴더를 확인할 수 있습니다.

ISO 파일을 임시 디렉터리에 마운트하여 내부 구조를 확인합니다:

mkdir -p /mnt/iso
mount -o loop rhel-9.x-x86_64-dvd.iso /mnt/iso

이후 /mnt/iso/BaseOS와 /mnt/iso/AppStream을 로컬 리포지토리로 등록하여
폐쇄망에서도 dnf install이 가능하도록 구성합니다.

5. BIOS 부팅 및 설치 진입

부팅 절차

1. Rufus로 만든 설치 USB를 서버에 꽂기
2. BIOS/UEFI 진입 (DEL, F2, F12, ESC 등 제조사별 키)
3. Boot 메뉴에서 USB 선택
   • 중요: USB가 두 개로 보이면 UEFI: USB 이름 을 선택
   • 예시: UEFI: SanDisk (O) vs SanDisk (X)
   • UEFI 모드를 최우선 순위로 설정
4. 메뉴에서 Install Red Hat Enterprise Linux 9.x 선택

UEFI 모드 필수 (Legacy BIOS로 설치 시 부팅 문제 발생 가능)

6. 설치 UI 단계

설정 요약

파티션은 /, /var, /home을 분리하여 설정하는 것을 권장
로그 누적 및 사용자 데이터로 인한 루트 파티션 포화 방지를 위해 구조 분리 필요

7. 로컬 리포지토리 등록

Linux 패키지 관리자(dnf, apt 등)는 일반적으로 인터넷의 원격 저장소(repository)에서 패키지를 다운로드합니다. 폐쇄망 환경에서는 인터넷 접근이 불가능하므로, RHEL 설치 ISO의 BaseOS와 AppStream 폴더를 워크스테이션 내부 디스크로 복사하여 로컬 리포지토리를 구성합니다.

오프라인 dnf repo 구성 절차

(1) ISO 마운트 및 디렉터리 복사

설치 USB 또는 ISO를 임시로 마운트합니다:

mkdir -p /mnt/iso
mount -o loop /path/to/rhel-9.x-x86_64-dvd.iso /mnt/iso

ISO 내부 디렉터리를 로컬 디스크로 복사합니다:

mkdir -p /opt/repos
cp -r /mnt/iso/BaseOS /opt/repos/
cp -r /mnt/iso/AppStream /opt/repos/

마운트 해제 후 USB를 제거합니다:

umount /mnt/iso

(2) 로컬 repo 설정 파일 생성

복사한 로컬 디렉터리를 리포지토리로 등록하기 위해 설정 파일을 생성합니다:

sudo vi /etc/yum.repos.d/local.repo

입력 내용:

[BaseOS]
name=RHEL-9-BaseOS
baseurl=file:///opt/repos/BaseOS
enabled=1
gpgcheck=0

[AppStream]
name=RHEL-9-AppStream
baseurl=file:///opt/repos/AppStream
enabled=1
gpgcheck=0

(3) repo 인덱스 갱신 및 확인

로컬 리포지토리 설정이 완료되면 패키지 캐시를 갱신하고 등록된 리포지토리 목록을 확인합니다.

sudo dnf clean all
sudo dnf repolist

출력 예시:

repo id                        repo name
BaseOS                         RHEL-9-BaseOS
AppStream                      RHEL-9-AppStream

(4) 패키지 설치 테스트

로컬 리포지토리가 정상적으로 동작하는지 확인하기 위해 간단한 패키지를 설치해봅니다.

sudo dnf install -y vim

정상 설치되면 로컬 리포지토리 구성이 완료된 것입니다.

USB를 제거해도 완전한 오프라인 환경 유지됨
추후 새 버전 ISO로 업데이트할 때는 /opt/repos 디렉터리 덮어쓰기

8. 폐쇄망 네트워크 설정

유선 네트워크 구성

워크스테이션과 클라이언트(노트북/PC)는 L2 스위치(Layer 2 Switch) 를 통해 유선(LAN)으로 연결합니다. L2 스위치는 MAC 주소를 기반으로 프레임을 전달하지만, 사용자가 별도로 MAC 주소를 설정할 필요는 없습니다. 각 장비의 네트워크 인터페이스에 기본 내장된 MAC 정보를 스위치가 자동으로 학습해 처리합니다. 공유기(Router)는 외부망 연결용 장비이므로 폐쇄망 환경에서는 사용하지 않습니다.

구성 예시:

[Workstation]──LAN──┐
                    │  (Switch/Hub)
[Client Laptop]──LAN─┘

RHEL 워크스테이션 IP 설정

RHEL 9의 Settings → Network → Wired → IPv4 → Manual 에서 아래 값 입력:

폐쇄망에서는 외부 네트워크(인터넷)와의 연결이 없으므로
기본 게이트웨이와 DNS는 설정하지 않음

클라이언트 IP 설정(윈도우 기준)

(1) 네트워크 설정 진입

1. 제어판 → 네트워크 및 공유 센터 (Network and Sharing Center) 클릭
2. 왼쪽 메뉴의 어댑터 설정 변경(Change adapter settings) 클릭
3. 이더넷(Ethernet) 아이콘 찾기 (Wi-Fi가 아닌 유선 연결 항목)

(2) 속성 변경

1. Ethernet 아이콘 우클릭 → 속성(Properties)
2. 목록에서 Internet Protocol Version 4 (TCP/IPv4) 선택
3. 속성(Properties) 버튼 클릭

(3) IP 수동 입력

확인(OK) → 닫기(Close) 선택

(4) 연결 확인

명령 프롬프트(cmd)를 열고 다음을 입력합니다:

ping 192.168.0.50

워크스테이션에서 응답이 오면 네트워크 연결이 완료된 것입니다.

(5) 설정 확인

네트워크 설정이 올바르게 적용되었는지 확인합니다:

ipconfig

IPv4 Address 항목이 192.168.0.51로 표시되면 정상 설정된 것입니다.

9. Ubuntu vs RHEL(Red Hat Enterprise Linux)

폐쇄망 환경에서 AI Solution 개발환경 구축 시 운영체제 선택은 전체 복잡도에 직접적인 영향을 줍니다. Ubuntu와 RHEL은 모두 Linux 계열이지만 철학, 관리 방식, 보안 정책, 지원 체계가 다릅니다.

차이점

(1) 설치 및 초기 세팅

Ubuntu는 인터넷 저장소 의존 구조로 인해 오프라인 설정이 복잡
(패키지 의존성, GPG 키, 미러 구성 등을 수동으로 준비해야 함)
RHEL은 ISO 내부에 저장소가 포함되어 있어 복사와 등록만으로 오프라인 운용 가능

(2) 패키지 관리 구조

Ubuntu는 단일 저장소 구조로 관리가 직관적
RHEL은 리포지토리 단위 관리로 확장성과 안정성이 높음

(3) 보안 정책 (SELinux vs AppArmor)

AppArmor는 유연하고 개발에 친화적
SELinux는 정밀한 제어와 보안 감사 기능이 강력함
폐쇄망에서는 SELinux를 Permissive 모드로 완화 운영하는 경우가 많음

(4) AI 프레임워크 호환성

Ubuntu는 AI 개발 환경 구성이 용이
RHEL은 장기적인 운영 안정성이 높음

(5) 오프라인 패키지 리포지토리 구성

Ubuntu는 최신 패키지와 다양한 버전을 제공
RHEL은 단순한 구조로 오프라인 환경 구성에 용이

(6) 컨테이너 관리 (Docker vs Podman)

Ubuntu는 개발 및 배포 환경 구성이 편리
RHEL은 컨테이너 보안성과 격리성이 우수

요약 비교 및 선택 가이드

Ubuntu는 개발 및 테스트 환경에 적합
RHEL은 보안과 안정성을 요구하는 운영 환경에 적합

APT ↔ DNF 명령어 대응표

Ubuntu와 RHEL 계열의 가장 큰 차이 중 하나는 패키지 관리 도구입니다.
Ubuntu는 apt, RHEL은 dnf를 사용하지만, 명령 체계와 기능은 매우 유사합니다. 아래 표는 동일 작업을 수행할 때의 명령어 대응 관계입니다.

RHEL 8 이후 yum은 dnf로 완전히 대체
Ubuntu는 .deb, RHEL은 .rpm 포맷을 사용하므로 교차 설치 불가
폐쇄망 환경에서는 dnf가 ISO 또는 디렉터리 기반 리포지토리(baseurl=file:///opt/repos/...) 구성에 유리

마무리

폐쇄망 환경에서 AI Solution 개발환경을 구축하는 과정은
OS 설치를 넘어 완전한 독립 생태계 구성을 목표로 합니다.

이번 글에서는 폐쇄망 환경 구축의 기초 단계를 다음과 같이 진행했습니다.

1. 준비 및 OS 설치
   • 하드웨어·소프트웨어 목록 정리 및 RHEL ISO 기반 부팅 USB 제작
   • UEFI 모드 부팅 및 Workstation 설치 완료
2. 오프라인 패키지 저장소 구성
   • ISO 내부 BaseOS/AppStream을 로컬 디스크로 복사
   • /etc/yum.repos.d/local.repo 설정으로 인터넷 없이 dnf install 가능한 환경 구축
3. 폐쇄망 네트워크 설정
   • Switch/Hub 기반 유선 연결 및 고정 IP 할당
   • 워크스테이션–클라이언트 간 통신 확인
4. 운영체제 비교 (Ubuntu vs RHEL)
   • 패키지 관리, 보안 정책, AI 프레임워크 호환성 분석
   • 폐쇄망 환경에 적합한 OS 선택 기준 제시

이로써 인터넷 연결 없이도 패키지 설치와 네트워크 통신이 가능한
폐쇄망 기본 인프라 환경이 완성되었습니다.

다음 편에서는 컨테이너와 GPU 기반 AI 개발 환경 구축 과정으로 이어집니다.

초기에는 OCR이 이미지를 글자로 변환하는 기술이라고 생각했으나,
실제 fine-tuning을 진행해 보니 Detection과 Recognition 구조 차이, 데이터 라벨 구조,
그리고 환경설정의 까다로움까지 예상보다 깊이 있게 다뤄야 할 영역이 많았습니다.

공개된 OCR 데이터셋은 대부분 일상적인 상황과 표준어 중심으로 구성되어 있어,
특정 환경에서 자주 등장하는 표현이나 어휘를 충분히 반영하지 못하는 경우가 많습니다.
이에 맞춰 한국어 확장 커스텀 사전부터 이미지 생성, 라벨링까지 직접 데이터셋을 제작하고
PaddleOCR 기반으로 fine-tuning을 진행했습니다.

Text Detection vs Text Recognition

대부분의 OCR 엔진은 Detection → Recognition 순서로 동작합니다.

PaddleOCR vs EasyOCR

OCR 프레임워크 중 유명한 것은 크게 두 가지가 있습니다.
EasyOCR은 설치와 사용이 쉽습니다. pip install easyocr 한 줄로 바로 시작할 수 있습니다.
다만, 구조가 단일 파이프라인 형태라 Detection·Recognition을 개별적으로 튜닝하거나,
End-to-End 구조를 쓰기에는 제약이 많습니다.

PaddleOCR은 Baidu에서 만든 PaddlePaddle 프레임워크 기반으로,
Detection·Recognition·End-to-End 모델을 모두 제공합니다.
모델 구조와 학습 설정을 세밀하게 조정할 수 있고, TensorRT/ONNX 변환도 지원합니다.
단점은 설치가 복잡하고, 문서가 중국어 중심이라 처음 진입 장벽이 높습니다.

이번 프로젝트의 목적이 특정 도메인에서의 고정밀 fine-tuning이었기 때문에,
구조적 유연성과 End-to-End 지원이 강점인 PaddleOCR을 선택했습니다.

Paddle 계열 패키지

Paddle 계열은 이름이 비슷해서 처음 접하면 헷갈리기 쉽습니다.

PaddleOCR fine-tuning 환경 구성 (Conda 기반)

PaddleOCR은 설치 순서를 잘못 잡으면 의존성 충돌이나 버전 불일치가 발생할 수 있습니다.
아래 순서를 반드시 지키는 것이 안전합니다.

1. Conda 가상환경 생성

conda update -n base -c defaults conda
conda create -n paddle python=3.10
conda activate paddle
python -m pip install --upgrade pip setuptools wheel

2. PaddleOCR 설치 (순서 중요)

# GPU 환경 기준 (CUDA 11.8 예시)
pip install paddlepaddle-gpu==2.6.2 -f https://www.paddlepaddle.org.cn/whl/mkl/avx/stable.html

# CPU만 사용할 경우
# pip install paddlepaddle

# 추론만 쓸 경우
pip install paddleocr

# 학습 시에는 반드시 GitHub clone + 개발 모드 설치
git clone https://github.com/PaddlePaddle/PaddleOCR.git
cd PaddleOCR
pip install -r requirements.txt
pip install -e .

# (선택) ONNX 변환
pip install paddle2onnx

3. 학습 실행 예시

# REC 예시
python tools/train.py -c /workspace/idxkim/cfg/rec_svtrnet.yml

# E2E 예시
python tools/train.py -c /workspace/idxkim/cfg/e2e_r50_vd_pg.yml

• -c 옵션에는 PaddleOCR의 config 파일 경로를 넣어야 합니다.
• 커스텀 데이터셋을 쓰려면 원본 config를 복사 후 데이터 경로만 수정하여 사용합니다.

설치 시 자주 발생하는 오류

설치 시 핵심 체크리스트

• 설치 순서: PaddlePaddle → PaddleOCR → 기타 유틸 순으로 설치
• 학습 목적: GitHub clone + pip install -e . 필수
• 추론 목적: pip paddleocr만 설치
• 문제가 꼬이면 가상환경을 새로 만드는 게 가장 빠름
• GPU 사용 시 반드시 CUDA 버전 호환 여부 확인 (공식 문서 참고)

Docker 컨테이너 기반 학습 환경 구성

실무에서 모델 학습 시 이미 빌드된 분석엔진용 Docker 이미지(A 이미지)를 사용합니다.
배포 환경과 동일하게 구성되어 있어, 추가 빌드 없이 바로 컨테이너를 생성할 수 있습니다.

이 방식은 학습 환경과 배포 환경이 완전히 일치하므로,
모델을 분석엔진에 올릴 때 환경 호환성 문제를 최소화할 수 있습니다.
필요에 따라 학습 전용 이미지(B 이미지)를 따로 사용해 실험한 뒤,
완성된 모델만 분석엔진 환경에 반영하기도 합니다.

1. 배포 환경 기반에서 학습

• A 이미지: 실제 제품 배포 시 사용하는 분석엔진 컨테이너의 베이스 이미지
• 이 컨테이너에서 바로 학습·검증까지 진행
• 장점:
  • 학습 환경과 배포 환경이 동일
  • Ultralytics, SAM, PaddleOCR 등 다른 Vision AI 프레임워크와 공존 가능
  • 모델 검증, 최적화, 배포까지 한 컨테이너에서 처리 가능

2. 학습 전용 이미지에서 학습

• A 이미지와는 별도의 학습 전용 컨테이너
• 학습 완료 후 모델 가중치와 설정 파일만 A 이미지 환경에 반영
• 장점:
  • 환경 충돌 최소화
  • 실험적인 버전 테스트에 유리

컨테이너별 비교

학습 완료 모델을 A 이미지에 반영할 때는
가중치 파일 + character_dict + config.yml 세트를 그대로 옮기는 것이 안전합니다.

OCR 데이터셋 생성 과정

이번 프로젝트에서는 사전 제작한 한국어 확장 커스텀 사전을 활용하여 도메인 맞춤형 한글 OCR 데이터셋을 직접 생성했습니다. 실제 서비스 환경에서 발생할 수 있는 색상 대비, 폰트 다양성, 배치, 초성 분포, 회전 요소를 반영하여, 모델이 다양한 상황에서도 안정적으로 동작할 수 있도록 설계했습니다.

1. HSV 기반 배경/전경 색상 선택

OCR 모델은 배경과 글자색의 대비가 낮으면 인식률이 떨어집니다.
RGB 색상값을 무작위로 지정하는 방식 대신 HSV 색공간에서 색상을 생성하고,
상대 휘도(luminance) 기반으로 최소 대비 기준을 충족하는 전경색을 선택했습니다.

• 목적: 글자와 배경이 충분히 구분되도록 하여 가독성을 확보
• 구현 방식:
  1. HSV 범위에서 무작위 색상 생성
  2. 배경 휘도 값에 따라 전경색 후보 범위를 다르게 설정
  3. 대비 비율이 threshold 이상인 색상만 채택
• 효과: 색상 다양성은 유지하면서도, 글자가 묻히는 경우를 방지

import colorsys
import random

def hsv_rand(h, s, v):
    hh, ss, vv = random.uniform(*h), random.uniform(*s), random.uniform(*v)
    r, g, b = colorsys.hsv_to_rgb(hh, ss, vv)
    return tuple(int(255*x) for x in (r, g, b))

def calculate_luminance(rgb):
    r, g, b = [c/255 for c in rgb]
    return 0.2126*r + 0.7152*g + 0.0722*b

def contrast_ratio(bg, fg, thresh=2.0):
    L1, L2 = calculate_luminance(bg), calculate_luminance(fg)
    return (max(L1, L2)+0.05) / (min(L1, L2)+0.05) >= thresh

2. 폰트 크기, 외곽선, 굵기 랜덤화

한글 OCR에서는 글자 크기와 스타일 변화에 대응할 수 있는 학습이 중요합니다. 고정된 스타일만 학습하면 실제 환경에서 작은 글자나 얇은 글씨를 잘 인식하지 못합니다.

• 목적: 다양한 글자 크기·굵기·외곽선 스타일에 대응
• 구현 방식:
  • 폰트 크기: 40~100px 범위에서 랜덤
  • 외곽선(stroke): 두께(0~3px)와 색상 랜덤
• 효과: 폰트와 크기가 바뀌어도 인식률 유지

from PIL import ImageFont
font_size = random.randint(40, 100)
font = ImageFont.truetype(FONT_PATH, font_size)
stroke_w = random.randint(0, 3)

3. 초성 기반 Stratified Split

데이터셋을 학습/검증 세트로 나눌 때, 문자 분포가 불균형하면 성능 검증이 왜곡될 수 있습니다.
특히, 자주 등장하지 않는 초성이 검증 세트에서 전부 빠지면 모델이 그 문자를 학습하지 못합니다.

• 목적: 모든 초성이 학습·검증에 고르게 분포하도록 유지
• 구현 방식:
  • 각 단어의 초성을 추출하여 그룹화
  • 그룹별로 무작위 분할
• 효과: 검증 정확도의 신뢰도 향상

CHO = list("ㄱㄲㄴㄷㄸㄹㅁㅂㅃㅅㅆㅇㅈㅉㅊㅋㅌㅍㅎ")
def get_choseong(ch):
    return CHO[(ord(ch)-ord("가"))//(21*28)] if "가" <= ch <= "힣" else "기타"

4. Detection/Recognition 데이터 동시 생성

OCR 파이프라인은 문자 영역 탐지(Detection)와 문자열 인식(Recognition) 두 단계로 구성됩니다. 합성 단계에서 두 작업에 필요한 데이터를 동시에 생성하면 효율성이 높아집니다.

• 목적: 한 번의 합성으로 두 작업의 학습 데이터를 모두 확보
• 구현 방식:
  • Detection 라벨: polygon 좌표 + 텍스트
  • Recognition 라벨: crop 이미지 + 텍스트
• 효과: 데이터 생성 효율 향상, 두 태스크 간 일관성 유지

5. 회전 + 직사각형 crop 방식

데이터 생성 시 이미지와 라벨 좌표를 동시에 회전하여 augmentation 효과를 주었습니다. Recognition crop은 회전된 polygon 그대로 잘라내는 사다리꼴이 아니라, 회전된 polygon을 감싸는 axis-aligned 직사각형을 잘라 저장합니다.

• 목적: 회전된 데이터에서도 라벨 불일치 없이 Recognition 입력을 일정하게 유지
• 구현 방식:
  1. 이미지와 polygon 좌표를 동일 각도로 회전
  2. polygon의 min/max 좌표를 이용해 직사각형 bbox 계산
  3. bbox 영역을 crop → 필요 시 배경 여백 포함
• 효과:
  • 기울어진 글자라도 모델 입력 형태가 일정
  • perspective 변환 없이 구현 단순화

def crop_rotated_bbox(rotated_img, rotated_points):
    xs = [p[0] for p in rotated_points]
    ys = [p[1] for p in rotated_points]
    xmin, xmax = int(min(xs)), int(max(xs))
    ymin, ymax = int(min(ys)), int(max(ys))
    return rotated_img.crop((xmin, ymin, xmax, ymax))

6. 전체 설계 방향

1. 색상 대비 최적화 → HSV 기반 색상 생성 + 대비 계산으로 가독성 확보
2. 다양한 시각 스타일 대응 → 폰트 크기·굵기·외곽선 랜덤화
3. 문자 분포 균형 유지 → 초성 기반 Stratified Split
4. 멀티태스크 데이터 동기화 → Detection/Recognition 동시 생성
5. 좌표·입력 형태 안정성 → 회전은 데이터 생성 단계에서 처리, Recognition은 직사각형 crop

PaddleOCR 모델 유형 비교

1. Recognition(SVTR)

텍스트 크롭 이미지만을 이용해 SVTR 기반 Recognition 모델을 fine-tuning했습니다. 이 방식은 데이터 준비가 비교적 간단하고, 빠르게 실험을 시작할 수 있다는 장점이 있습니다. 다만 Detection 단계에서 텍스트 위치를 잘못 잡으면, 이후 Recognition 성능이 제한되는 한계가 있습니다. 복잡한 배경이나 다양한 배치 구조에서는 Detection 오류가 누적되어 전체 인식률이 떨어질 수 있습니다.

• 장점
  • 데이터 준비와 파이프라인 구성이 단순합니다.
  • 빠른 성능 검증과 파라미터 튜닝에 유리합니다.
• 단점
  • Detection 품질에 의존도가 높습니다.
  • 실제 서비스 환경의 복잡한 레이아웃에는 취약합니다.

2. Detection(DB)

텍스트 위치를 더 정확하게 찾기 위해 DB(Differentiable Binarization) 기반 Detection 모델을 fine-tuning했습니다. DB는 속도와 정확도의 균형이 좋아 PaddleOCR에서 가장 널리 사용되는 Detection 구조이며, 이번 fine-tuning에서는 텍스트 탐지 정확도를 높여 Recognition 입력 품질을 개선하는 데 집중했습니다. Detection 품질이 향상되면서 Recognition 단계의 오류도 크게 줄어들었습니다.

• 장점
  • Recognition 입력 품질이 눈에 띄게 개선됩니다.
  • 복잡한 레이아웃이나 다양한 배경 조건에서 강해집니다.
  • 경량·고정밀 버전 모두 지원해 환경에 맞게 선택할 수 있습니다.
• 단점
  • 박스 라벨링 품질이 성능에 직접적인 영향을 미칩니다.
  • 학습 시간이 늘어날 수 있습니다.

3. End-to-End(PGNet)

Detection과 Recognition을 동시에 학습하는 PGNet 기반 End-to-End 구조를 적용했습니다. Backbone과 Neck은 공개 checkpoint를 재사용하고, Head는 분리하여 커스텀 사전에 맞춰 새로 학습했습니다. 이 방식은 두 모듈이 상호 보완적으로 최적화되므로 전체 인식 정확도를 극대화할 수 있습니다. 다만 학습 난이도가 높고, 데이터셋 품질 관리와 하이퍼파라미터 설정에 더 많은 노력이 필요합니다.

• 장점
  • Detection과 Recognition이 상호 최적화됩니다.
  • 파이프라인 전체의 추론 속도와 일관성이 높아집니다.
  • 라벨링 일관성이 유지되면 재학습 효율이 좋습니다.
• 단점
  • 학습 난이도가 높고, 데이터셋 품질 요구 수준이 높습니다.
  • 모델 구조 변경이나 Head 재학습 과정에서 오류 가능성이 증가합니다.

Head를 분리해야 하는 이유

PaddleOCR에서 fine-tuning을 진행할 때 안정적인 학습을 위해 Head를 분리합니다.
아래에서는 Head를 분리하는 이유와, 적용 시 함께 고려해야 할 사항을 정리했습니다.

1. Ultralytics와 PaddleOCR의 checkpoint 로딩 구조 비교

Ultralytics YOLO 계열은 pretrained=True 상태에서 클래스 수를 변경하면, Head 부분이 자동으로 재초기화되거나 strict=False 옵션을 통해 shape가 맞지 않는 키를 건너뛸 수 있습니다. 이 방식은 Backbone과 Neck만 그대로 두고 Head는 새로 구성되므로, 모델 구조 변경 시 비교적 유연하게 대처할 수 있습니다.

반면 PaddleOCR의 PGNet은 기본 loader가 checkpoint 전체를 strict하게 읽습니다. Backbone과 Neck만 로드하는 별도의 스위치가 제공되지 않기 때문에, Head를 분리하지 않으면 shape mismatch 오류가 발생할 가능성이 있습니다.

2. OCR에서 Head의 특성

OCR의 Head는 문자 집합(character_dict)과 시퀀스 디코딩 방식에 종속됩니다.
라벨 구성 차이가 있으면 출력 차원 불일치, 분포 불일치로 인해 학습이 불안정해질 수 있습니다.

3. Head를 분리해야 하는 이유

1. 라벨 공간 불일치
   • 공개 checkpoint는 영문/범용 데이터 기준으로 학습된 경우가 많습니다.
   • 이번처럼 한국어 확장 사전을 쓸 경우 기존 Head는 맞지 않을 수 있습니다.
2. 전이학습 단위 차이
   • Backbone/Neck은 시각 특징을 추출하므로 재사용 가치가 높지만,
   • Head는 문자 클래스 분포와 언어적 패턴을 반영하므로 데이터셋에 맞춘 재학습이 필요합니다.
3. 수렴 안정성
   • 불일치 Head를 사용하면 초기 학습에서 불필요한 gradient를 소모하고 불안정해질 수 있습니다.
   • 출력 차원을 맞춘 Head로 시작하면 적은 데이터로도 빠르게 수렴할 수 있습니다.

4. checkpoint 변환 필요성

• PaddleOCR의 사전학습 checkpoint는 backbone., neck., head. 네임스페이스로 파라미터가 구분됩니다.
• Head를 재학습하고 Backbone/Neck만 전이학습하려면 checkpoint 변환이 필요합니다.
• 변환 시 Head 파라미터를 제거하고 Backbone/Neck만 남긴 새로운 .pdparams 파일을 생성해야 합니다.

Head 처리 방식 변경 과정에서 겪은 이슈

처음에는 다음과 같은 방법을 시도했습니다.

• PaddleOCR 내부 loader를 수정하여 strict=False를 적용
• 학습 직전에 state dict에서 Head 부분만 제거하는 커스텀 로직 삽입

그러나 다음과 같은 문제가 반복적으로 발생했습니다.

• Head 관련 shape mismatch / missing key / unexpected key 오류 발생
• 학습 로그에 Head가 scratch(랜덤 초기화)로 붙었다는 메시지가 출력되며 성능 하락
• 분산 학습 환경, 재시작, 버전 차이에 따라 결과가 재현되지 않음

결국, pretrained checkpoint를 Backbone/Neck 전용으로 변환해 사용하는 것이 가장 안정적이고 재현성이 높았습니다.

해결 방법

아래 스크립트를 사용하면 Head 네임스페이스를 제거한 새로운 checkpoint를 생성할 수 있습니다.
변환된 파일을 YAML 설정의 Global.pretrained_model 경로에 지정하여 사용합니다.

# filter_ckpt.py 
import sys 
import paddle

def filter_head(in_path, out_path, drop_prefixes=("head.",)):
    # PaddleOCR의 .pdparams 로드
    state_dict = paddle.load(in_path)

    # head.* 키 제거
    kept = {k: v for k, v in state_dict.items()
            if not any(k.startswith(p) for p in drop_prefixes)}

    # 저장
    paddle.save(kept, out_path)
    print(f"[filter] saved -> {out_path} "
          f"(kept={len(kept)}, dropped={len(state_dict)-len(kept)})")

if __name__ == "__main__":
    if len(sys.argv) != 3:
        print(f"Usage: python {sys.argv[0]} <input.pdparams> <output.pdparams>")
        sys.exit(1)

    src, dst = sys.argv[1], sys.argv[2]
    filter_head(src, dst)

실행 예시:

python filter_ckpt.py \
  /workspace/idxkim/pretrained/best_accuracy.pdparams \
  /workspace/idxkim/pretrained/backbone_neck_only.pdparams

YAML 설정:

Global:
  pretrained_model: /workspace/idxkim/pretrained/backbone_neck_only.pdparams

Head 제거 확인:

import paddle
st = paddle.load("/workspace/idxkim/pretrained/backbone_neck_only.pdparams")
assert all(not k.startswith("head.") for k in st.keys())
print("✅ head.* 없음")

마무리

이번 프로젝트에서 PaddleOCR 기반 fine-tuning을 통해 도메인 특화 OCR 성능을 개선했습니다. 데이터셋 설계와 checkpoint 관리가 학습 안정성과 성능에 미치는 영향을 검증했습니다.

실험 결과, 다음과 같은 접근이 효과적이었습니다.

• 환경 설정 및 종속성 설치를 표준화하여 재현성 확보
• Head를 분리하고 Backbone/Neck 전용 checkpoint를 구성해 안정적으로 전이학습 진행
• Recognition → Detection → End-to-End 순으로 단계적 fine-tuning 적용
• 실험 로그, 하이퍼파라미터, 환경 버전을 체계적으로 기록해 재실행 가능성 보장

위 절차를 통해 복잡한 OCR 프레임워크에서도 안정적인 학습 파이프라인을 구성할 수 있었습니다. 또한, 데이터셋 품질과 checkpoint 전략이 OCR 성능 향상에 직결됨을 확인했습니다.

그런 점에서 PoC, 기술 데모, 그리고 전시용 홍보 영상은 목적은 다르지만 중요한 공통점을 공유합니다. 세 가지 모두, 완성된 제품이 아닌 “기술이 작동한다”는 메시지를 전하는 작업이며, 제약된 시간과 리소스 안에서 납득 가능한 형태로 결과를 구성하고 전달해야 합니다.

결국 핵심은 기능 구현 자체가 아니라, 그 기능을 어떻게 보여주고 해석되게 하느냐입니다. 실제 현장에서는 모델 정확도보다 신뢰성과 시각적 완성도가 더 중요하게 평가되는 경우도 많습니다.

이 글에서는 2025년 기준으로 진행된 몇 가지 실제 PoC와 전시용 기술 데모 사례를 바탕으로, 각 과제에서 어떤 구조를 설계하고, 어떤 방식으로 대응했는지를 정리해 보려 합니다.

먼저 PoC 검토 시 기본적으로 점검하는 항목들을 살펴본 뒤, 각 프로젝트별 흐름과 기술적 선택 과정을 차례로 다뤄보겠습니다.

기본 검토 순서

PoC 진행 전에는 다음 항목을 기준으로 기술적 사전 검토를 수행합니다:

1. 모델이 있는가? (기존 모델 또는 베이스라인 존재 여부)
2. 데이터셋이 있는가? (고객사 제공 여부 포함)
3. 라벨링이 되어 있는가? (라벨 품질, 포맷 일치 여부)
4. 테스트 영상이 있는가? (실제 운영 환경 기반의 입력)

PoC 진행 현황 (2025년 기준)

이제 각 사례를 중심으로, 실제 어떤 기술적 과정을 수행했는지 정리해보겠습니다.

본 포스팅에 포함된 일부 시각 자료는 실 서비스 관련 내용이 포함되어 있어, 내부 정책 또는 보안상의 이유로 사전 고지 없이 삭제될 수 있습니다.

1. PoC 완료 사례

• 고객사: A사
• 상태: PoC 완료, 금주 중 본 계약 조건 협의 예정 계약 완료

• 비고: 해당 제품의 주 담당은 아니었지만, 일부 기능 PoC를 수행했습니다.

• 주요 업무:
  • 고객 요청에 따른 Object Detection, Super Resolution 기능 PoC 수행
  • 요구 클래스에 대한 데이터셋 확보 및 전처리
  • 모델 구성 및 파이프라인 설계
  • 시각화 영상 및 결과물 제작
  • 리소스 사용량 테스트 및 GPU 견적 대응
  • 기술 미팅용 보고자료 구성

1-1. Object Detection

• 사용 모델:
  • Ultralytics YOLOv11
  • 실험 가능성과 신뢰성을 모두 고려했고, 비교적 빠르게 튜닝 가능한 구조라는 점에서 초기 테스트에 적합하다고 판단했습니다.

• 인바운드 요청: “클래스 B 탐지 가능한가?”
  → 단 1문장 요청이었고, 응답 기한은 3일, 내부 정리는 2.5일 안에 마쳐야 했습니다.

• 데이터셋 이슈:
  • COCO에는 없었고, Object365에는 있었지만 데이터셋 규모가 커서 다운로드 및 전처리에 시간이 많이 소요될 것으로 판단했습니다.
  • 클래스 B는 일상적인 대상이었으나, 공개된 pretrained 모델 중 해당 클래스를 포함한 모델은 확보되지 않았습니다.
  • 최종적으로 Roboflow에서 유사 클래스가 포함된 여러 개의 소형 데이터셋을 수집하여 병합 구성했습니다.
  • 클래스 간 중복 및 누락 여부를 수동으로 점검했고, 라벨 일관성 확보를 위해 일부 샘플은 직접 수정했습니다.
• 테스트 영상 확보 및 편집:
  • 실제로 가장 어려운 단계는 적절한 테스트 영상을 확보하는 것이었습니다.
  • 유튜브 등에서 클래스 B가 명확히 등장하는 장면을 선별하고,
    고객 요구조건, 탐지 난이도, 실적용 가능성을 모두 고려해 편집했습니다.
  • 영상은 탐지가 잘 되도록 조명, 프레임 구성, 해상도 등을 다각도로 조정했습니다.
• 반복 작업:
  • 동일 테스트 영상에 대해 다양한 모델 파라미터를 변경하며 반복 실험을 수행했습니다.
  • 그 과정에서 영상 재편집 → 데이터셋 보완 → 모델 재학습 사이클을 4~5회 반복하며,
    탐지 정확도와 시각적 신뢰도를 모두 만족시키도록 성능을 안정화했습니다.
• 산출물 구성:
  • 최종 결과물은 다음 세 가지로 구성했습니다.
    1. “됩니다.”라는 결론 문장
    2. “됩니다.”의 근거가 되는 시각화 영상
    3. 테스트 환경에서의 리소스 사용 정보 요약본
  • 시각화 영상은 테스트 영상 위에 탐지 결과를 오버레이해 생성했고,
    Object Detection 기능이 실환경에서도 충분히 유효하다는 점을 직관적으로 전달할 수 있도록 구성했습니다.

1-2. Super Resolution (화질 개선)

• 사용 모델 및 구성:
  • Real-ESRGAN (Super Resolution)
  • GFPGAN (Face Enhancement)
    → 기능적으로 구분되며 리소스 특성이 다릅니다.
• 배경 및 모델 서치:
  • 해당 주제는 대학원 시절 직접 다룬 경험이 있어,
    PoC 시점에서 모델 서치 및 구조 이해에 소요되는 시간을 절약할 수 있었습니다.
  • 검토 초기부터 Real-ESRGAN + GFPGAN 조합으로 방향을 정하고 테스트에 집중했습니다.
• 작업 흐름:
  • 화질 개선 효과를 직관적으로 비교하기 위해 원본 해상도를 인위적으로 낮춘 뒤
    전후 영상을 구성하고, 출력 퀄리티와 인식 적합성을 함께 평가했습니다.
  • upscale 비율에 따른 성능 차이, 영상 길이에 따른 처리 시간,
    단독 사용 대비 병합 사용 시의 리소스 소모를 비교했습니다.
  • 또한, 고객사 측에서 GPU 견적 문의가 있었기 때문에
    Object Detection과 달리 리소스 사용량에 대한 정량 테스트가 특히 중요했습니다.
• 특이사항:
  • 일반적인 단일 이미지 추론에서는 비교적 가볍지만,
    고해상도 영상의 프레임 전체를 연속적으로 생성하거나,
    두 모델을 동시에 사용할 경우 GPU 메모리 사용량과 latency가 급격히 증가합니다.
  • 특히 GAN 계열 모델은 inference 상황에서도 frame 단위 병렬 처리가 제대로 되지 않으면
    OOM 이슈가 발생할 수 있으므로, 분석엔진 인터페이스 설계 시
    다른 모델들과의 자원 분배 및 스케줄링 조정이 필수적입니다.
• 산출물 구성:
  • 최종 결과물은 다음 세 가지로 구성했습니다.
    1. “됩니다.”라는 결론 문장
    2. “됩니다.”의 근거가 되는 전후 비교 영상
    3. 영상 해상도, 길이, 적용 모델별 리소스 사용 요약 리포트
  • 시각화 영상은 화질 저하 전/후를 프레임 단위로 비교할 수 있도록 구성했고,
    실제 사용 환경에서의 개선 효과를 직관적으로 보여주는 데 초점을 맞췄습니다.

시스템 구성

계약 체결이 완료됨에 따라,
협약 기관의 보안 정책에 의거하여 기존에 공개되었던 일부 내용을 비공개 처리하였습니다.

A사 PoC 과제별 기본 검토 항목

PoC 구성 비교

정리

A사의 Object Detection과 Super Resolution PoC는 모두 사전 모델과 완성된 데이터 없이 시작된 과제로,
Applied AI Engineer가 데이터 확보부터 테스트셋 구성까지 전 과정을 직접 수행한 실무 사례입니다.
(단, 이 과정은 시스템 관점의 End-to-End가 아닌, 모델 파이프라인에 한정된 End-to-End 구조였습니다.)

• Object Detection은 분석엔진 인터페이스가 이미 개발되어 있던 상황에서,
  모델 성능 검증과 데이터 파이프라인 설계에 집중한 모델 관점의 End-to-End형 PoC였습니다.
  (외부 공개 데이터를 재가공해 학습하고, 테스트셋 설계 및 시각화까지 직접 수행)

• Super Resolution은 학습 없이 pretrained 모델을 활용했지만,
  영상 테스트셋은 직접 생성 및 편집하여 화질 향상 효과와 리소스 사용량을 실증적으로 검증했습니다.

→ 두 과제 모두 기술 검증은 물론, 리소스 요구 수준과 운영 가능성까지 평가한 실무 기반의 PoC로 구성되었습니다.

개인적으로 AI Engineer라면 최소한 모델 단위 End-to-End 구성 역량은 필수라고 생각합니다.
데이터 수집, 정제, 라벨링을 포함한 전처리 단계에 대한 이해와 경험이 부족하면, PoC 이후 실제 제품화 단계에서 리더나 고객사의 피드백에 적절히 대응하기 어려워질 수 있습니다. 특히 문제의 원인이 데이터에 있을 때, 모델이나 시스템만 조정해서는 해결되지 않는 경우가 많기 때문입니다.

PoC 단계에서 데이터 흐름 전반을 직접 점검하고 설계해보는 경험은
AI Engineer의 실무 역량을 근본적으로 끌어올리는 기반이 됩니다.

2. PoC 진행 중 → MOU 예정

• 고객사: B사
• 상태: PoC 진행 중, MOU 체결 예정
• 적용 방식: 영상 업로드 후 자동 분석
• 비고: 최초 해외 레퍼런스로, 실시간 영상 스트리밍 기반이 아닌 동영상 업로드 후 분석하는 후처리 구조
• 주요 담당 업무:
  • Head Detection 모델 검증 및 탐지 한계 분석
  • 카운팅 로직 설계 및 구조 전환 (기준선 → Polygon + Hysteresis 기반)
  • 카운팅 후처리 로직 구현 및 안정성 검토
  • 분석엔진 내부 인터페이스 및 시각화 연동 구현
  • 시연용 결과물 및 데모 영상 제작
  • 기준선/Zone 정의 가이드 제공 및 카메라 설치 위치 조율
  • 고객사 PoC 현장에 적용된 On-Premise 분석엔진 운영 및 서버 이슈 대응

2-1. Object Counting Logic 설계 및 구조 전환

기반 구조: Detection + Tracking 결합

• 본 PoC는 Object Detection과 Object Tracking을 결합한 후처리 구조로, 매 프레임 객체를 감지한 뒤, track_id 기반 이동 경로를 활용하여 객체의 진입/이탈 상태 변화를 판단하고 중복 없이 카운팅합니다.

• 트래킹 알고리즘은 ByteTrack, OC-SORT, BoT-SORT를 검토하였으며, 속도, ID 일관성, 실환경 적합성 기준으로 최종적으로 ByteTrack을 적용하였습니다.

초기 구조: 기준선 기반 Cross Product 방식

• PoC 초기 환경은 지하철 개찰구와 유사한 수평 통행 구조로, 객체가 정해진 방향으로만 이동하는 조건이었습니다. 이 구조에서는 기준선을 수평으로 설정하고, 객체 중심 좌표가 선을 어느 방향으로 교차하는지를 cross product로 계산하여 방향을 판별했습니다.

• 동일 객체가 중복 카운트되지 않도록 track_id 기반으로 기록하여 관리했습니다.

cross_product = movement_vec[0] * line_vec[1] - movement_vec[1] * line_vec[0]

if cross_product > 0:
    direction = "IN"
elif cross_product < 0:
    direction = "OUT"

기준선 기반 구조의 전제 조건

• 기준선은 수평 또는 수직에 가까운 직선일 것
• 객체의 Bbox 크기는 프레임 간에 큰 변동이 없어야 할 것 → 위 조건이 충족되지 않으면 방향 오판단, 중복 또는 누락 카운팅이 발생할 수 있습니다.

2-2. 구조 전환: Hysteresis 기반 Polygon Zone 방식

구조 전환 배경

• 실제 분석 대상은 지하철 계단 환경이었으며, 다음과 같은 문제점이 있었습니다:

  • 객체가 계단을 오르내리며 기준선을 반복적으로 교차
  • Head detection만으로는 기준선 교차 시점을 정확히 포착하기 어려움
  • GT 라벨 기준은 Zone 진입 여부였지만, 기준선 기반 로직과 일치하지 않음

Hysteresis란?

Hysteresis(이력현상)는 객체가 경계 근처에 있다고 해서 바로 상태를 전환하지 않고, 일정 조건이 충족될 때에만 상태 전이를 허용하는 방식입니다. 이를 통해 짧은 시간 내 진입/이탈 반복이나 오탐을 방지할 수 있습니다.

Zone 기반 로직 설계

• 아래는 계단에서 Polygon 기반 영역(Hysteresis 적용 포함)을 시각화한 이미지입니다.

현재는 모자나 대머리와 같이 특징이 뚜렷하지 않은 객체에 대한 탐지가 어려운 상황이며,
고객사와 MOU 체결 이후, Head Detection 모델 파인튜닝을 통해 개선할 예정입니다.

• 계단 상단을 Polygon 영역으로 정의하고,
  내부(inner), 외부(outer), 경계 buffer 구간을 설정해 객체의 위치 상태를 판단합니다.
• 또한, 이전 상태와의 비교 및 최소 프레임 간격 조건을 함께 고려해 카운팅을 수행합니다.

if inner_zone.contains(object_point):
    new_state = True
elif not outer_zone.contains(object_point):
    new_state = False
else:
    new_state = track_data["inside"] if track_data["inside"] is not None else counting_zone.contains(object_point)

• 프레임 간격 조건:

if new_state != track_data["inside"] and (frame_index - track_data["last_counted_frame"] >= frame_threshold):
    ...

방향 보정 (필요 시)

• Hysteresis 기반 구조는 객체의 존재 여부 판단에는 강점이 있으나, 이동 방향 자체는 제공하지 않기 때문에 필요 시 y축 좌표 변화량을 기준으로 방향을 보정합니다:

y_drift = track_data["points"][-1][1] - track_data["points"][-5][1]
direction = "DOWN" if y_drift > 0 else "UP"

이 방식은 수직 이동이 명확한 계단 환경에서 특히 유효하며, “내려온 사람만 카운트”와 같은 조건 필터링에도 적합합니다.

2-3. 시각화 및 결과물 구성

• Bounding Box 및 Track ID 시각화
• in1, out2 등 실시간 라벨 표시
• IN/OUT 오버레이 (IN: 7 OUT: 5)
• 최종 카운팅 결과 요약본 (.json)

B사 PoC 과제별 기본 검토 항목 (Object Detection 기준)

정리

본 과제는 지하철 유동인구 분석을 위한 영상 기반 카운팅 PoC로, 시간대에 따라 프레임 내 객체(Bbox) 수가 수백 개 이상 발생하는 환경입니다. 이에 따라 트래킹 및 후처리 병목이 발생할 수 있으며, 성능 최적화 및 리소스 개선은 MOU 체결 이후 단계에서 추진될 예정입니다.

• 초기에 기준선 기반 cross product 로직을 적용했으나, 계단 환경에서는 객체의 반복 교차, ID 변경, 기준 불일치 등의 문제가 발생했습니다.

• 이를 보완하기 위해 Polygon Zone + Hysteresis 기반 구조로 전환하여 상태 유지, 프레임 간 조건, 중복 방지 조건 등을 통합한 더 안정적인 카운팅 구조를 구성했습니다.

• 트래킹 알고리즘은 ByteTrack, OC-SORT, BoT-SORT를 비교 실험하였으며, ByteTrack이 속도와 ID 일관성 면에서 가장 적합하여 최종적으로 적용되었습니다.

객체를 탐지한 뒤, 어떻게 “추적하고 판단할 것인지”에 따라 전체 시스템의 신뢰도와 결과 정확도가 크게 달라진다는 점을 보여준 프로젝트였습니다.

3. 전시용 데모 및 홍보 영상

• 대상: 클라우드 행사(AWS), 산업 전시회(EXPO) 등
• 목적: 기술력, 브랜드 이미지 강조

주요 업무

• 시연용 영상에 최적화된 모델 결과 구성
• 박스, 색상, 텍스트 등 시각 요소 강조
• 프레임 수, 타이밍 등 영상 편집용 포맷 대응
• 마케팅/기획팀과 협업하며 연출 반복

특징

• 실제 성능보다 “보여지는 느낌”이 더 중요합니다.
• 기술적 난이도는 낮지만 손이 가장 많이 가는 작업입니다.
• 모델 설계부터 시각화까지 흐름을 스스로 구성한
  Full-cycle Model-level End-to-End 사례입니다.
  (이 또한 시스템 단위의 End-to-End는 아닙니다.)

3-1. AWS

• 주제 조건
  1. 제조업, 스마트팩토리 관련
  2. 카운팅 기능 포함

• ShutterStock에서 후보 영상을 탐색하고, 상사의 컨펌을 받아 영상 구매 후 연구소에 전달하였습니다.
  연구소는 라벨링 후 Detection 모델 학습을, 저는 시각화만 담당하기로 되어 있었습니다.

• 그러나 의장님의 피드백:

  “bbox 너무 식상해, 색깔도 너무 안 예쁘고.”

  → 해당 피드백으로 기존 박스 기반 구조는 폐기되었고, Segmentation 방식으로 전환되었습니다.
  이후 라벨링부터 모델 구조 변경, 시각화까지 모두 단독으로 진행하게 되었습니다.

• 이처럼 PoC 단계에서는 클래스 정의와 구조 자체가 유동적이기 때문에,
  라벨링을 외주화하기보다는 AI Engineer가 직접 손을 대는 경우가 많습니다.

  → 이 사례 역시, 간단한 요청에서 출발했지만 전체 라벨 구조와 모델 파이프라인이 바뀐 대표적인 경우입니다.

• 마케팅팀 요구사항을 반영하며 시각화 수정이 반복되었고,
  해당 영상은 행사 발표 자료 및 현장 반복 재생용으로 사용되었습니다.

• 추가 이슈
  • 기본 설계는 On-Premise 환경을 기준으로 되어 있었으나,
    행사 목적에 맞춰 클라우드 기반 제품으로의 확장 가능성을 보여주기 위해
    분석엔진과 웹 인터페이스를 AWS 환경에 임시 배포해 시연을 구성하였습니다.
  • 추론 속도를 높이고 GPU 사용률을 낮추기 위해 TensorRT 변환을 적용하여,
    클라우드 환경에서의 리소스 비용 부담도 일부 완화할 수 있었습니다.
  • 웹 시연을 대비해 사내 CCTV를 활용하여 보호구 착용 후 데모용 시연 영상을
    직접 촬영 및 편집하였습니다.
  • AI Backend 담당자가 예비군 훈련으로 부재하여
    (지금 생각해보면 고의성이 의심됩니다.)
    분석엔진 백업 운영을 본사에서 직접 대응하게 되었습니다.

3-2. AI EXPO 전시용 영상

• 주제 조건:
  1. 제조업, 스마트팩토리 관련
  2. 카운팅 기능 포함
  3. 가능하다면 로보틱스, 자율주행 관련 포함
• 전체 구성: 총 3개 영상, 약 1개월간 준비
• 작업 흐름:
  ShutterStock 영상 후보 탐색 → 상사 및 팀원과 검토 후 구매 → 전처리
  → Segmentation 라벨링 (1000장 이상, 폴리곤 기준)
  → 오버피팅 학습 → 시각화 결과 제작 → 무한 피드백 반영 → 재학습 반복
• 작업 특이사항:
  • ShutterStock 영상 후보를 고르는 과정부터 많은 시간이 소요되었으며,
    영상의 구도, 대상 객체, 연출 가능성 등을 고려해 상사와 팀원까지 모두 참여한 의사결정이 필요했습니다.
  • Segmentation 라벨링은 Roboflow에서 제공하는 세미 오토 라벨링을 도입해봤으나,
    완전 자동은 불가능했고 후처리와 수작업 보정이 많아 실제 피로도는 수동과 큰 차이가 없었습니다.
  • 영상별 요구사항이 달라 3개의 모델을 별도 구성해야 했으며, 오버피팅 기반 재학습만 각기 3~4회 이상 반복하였습니다. 이 과정에서 클래스 정의가 바뀌거나, 데이터셋이 수시로 추가됩니다.

  • 그럼에도 오탐이 발생해 시각화 코드에서 특정 ROI 구간을 지정하고,
    해당 영역에는 결과를 표시하지 않도록 처리해 영상 완성도를 맞추기도 했습니다.

    # Define restricted zones (x1, y1, x2, y2)
    restricted_zones = [
        (678, 0, 896, 81),
        (1044, 199, 1191, 273),
        (1466, 873, 1583, 983)
    ]
    
    def is_inside_zone(box, zones):
        bx1, by1, bx2, by2 = box
        for zone in zones:
            zx1, zy1, zx2, zy2 = zone
            # Check if the box is completely inside the zone
            if zx1 <= bx1 and zy1 <= by1 and zx2 >= bx2 and zy2 >= by2:
                return True
        return False
    
    # For segmentation results
    for i, mask in enumerate(masks):
        # Get mask bounding box
        rows = np.any(mask, axis=1)
        cols = np.any(mask, axis=0)
        if np.any(rows) and np.any(cols):
            y1, y2 = np.where(rows)[0][[0, -1]]
            x1, x2 = np.where(cols)[0][[0, -1]]
                
            # Skip drawing mask if inside restricted zone
            if is_inside_zone((x1, y1, x2, y2), restricted_zones):
                continue
            
        # Mask drawing code...
    

  • 협업 없이 전체 과정을 단독 수행하였으며,
    특히 1번 영상은 내부 구성원들로부터 완성도에 대한 긍정적인 평가를 받았고, 최종적으로 행사 주요 시연 영상으로 지정되었습니다.

전시용 데모 및 홍보 영상 검토 항목

세부 구성 비교 요약표

홍보 영상, 왜 가장 고생스러울까?

기능보다 시각 연출이 우선됨

• 기능 구현 여부보다 시각적 인상과 연출이 우선 기준이 됩니다.
• 수 초 단위 영상에서도 컬러, 타이밍, 박스 위치 등 세부 요소에 대한 반복 요청이 발생합니다.
• 일부 피드백은 전체 라벨 구조 변경이나 시각화 방식 변경까지 유도합니다.
• 제작 중 추가 요청이 들어오는 경우도 잦으며, 일정 변경 없이 요구사항이 누적되는 경향이 있습니다.

비전문가 중심의 피드백 루프

• 기술적 구현 난이도와 무관하게 결과에 대한 주관적 평가가 이루어집니다.
• 예시 피드백:
  • “더 극적으로 표현할 수 없나요?”
  • “왜 이 장면에서는 객체를 인식하지 못하나요?”
• 감성적 피드백에 따라 반복적인 수정이 발생하며, 기준이 명확하지 않은 경우가 많습니다.

반복되는 후속 요청과 품질 기준의 유동성

• 영상 압축, 배속 조절, 자막 위치, 색상 조정 등 세부 항목에 대한 수정이 반복됩니다.
• 실제 모델 성능보다는 시각적 일관성과 만족도를 기준으로 품질이 판단되는 구조입니다.

주요 피드백 사례:

• “이 부분은 투명하게 해달라” → “더 투명하게 해달라” → “이건 너무 투명하다”
• “이 클래스는 이 색상이 더 나아 보인다”
• “글자가 너무 크다 / 글씨체가 어울리지 않는다”
• “카운팅 숫자가 가려진다 / 위치를 바꿔달라”
• “배속 / 슬로우 효과 추가”, “좌우에 영상 클립 병합”
• “고화질로 변환 가능 여부”, “TV 재생을 고려해 영상 해상도 조정 필요”

저는 꾸미기에 소질이 없기 때문에, 초반에 시각화 요청을 구체적으로 말해주지 않으면
무한 피드백 지옥에 빠지게 됩니다.

4. 2025 AI EXPO 후기

2025년 AI EXPO에 자사 제품의 기술 담당자로 참가했습니다. 총 3일간 진행된 행사 중 첫날 부스 운영과 현장 대응을 맡았고, 제가 제작한 3종 홍보 영상과 AWS 데모용 웹 시연 영상(실제 보호구 착용 장면 포함)이 전시 부스 내에서 반복 재생되는 형태로 운영되었습니다.

첫날에 배정된 덕분에, 참관객들의 질의응답을 가장 많이 대응할 수 있었고 현장에서 다양한 피드백을 직접 들을 수 있었습니다. 유튜브 라이브 카메라를 피해 다니려 노력했지만 몇 차례 노출되었고, 보도자료 사진에도 제 모습이 실리게 되었습니다.

다른 부스들도 둘러보고 싶었지만, 여유 시간이 모자라 두 군데 정도만 짧게 방문할 수 있었습니다. 이런 전시 행사는 바로 성과로 이어지기보다는, 수개월~1년 뒤에 실질적인 문의로 연결되는 경우가 많습니다. 실제로 이번 EXPO 이후, 벌써 2건의 기업 문의가 유입되기도 했습니다.

저는 공학 석사이자 경영학 학사 출신으로, 기술과 제품 사이의 균형을 항상 고민합니다.
“어떻게 만들어야 잘 팔릴까?”는 제가 AI Engineer로서 꾸준히 갖고 있는 질문이며,
결국 기술은 제품화되고, 선택되어야 살아남는다는 점을 늘 염두에 두고 있습니다.

이번 EXPO 현장에서도 모델 성능보다는 실사용 환경에서의 경험을 중심으로 설명했습니다. 영상 분석 모델은 이미 일정 수준의 정확도에 도달해 있기 때문에, 현장에서는 알람 피로도, 사용자 맞춤 필터링, 도입 이후의 관리 용이성 등이 더 중요한 평가 요소로 작용합니다.

실제로 저는 다음과 같은 점을 강조했습니다:

• UI상에서 채널별 / 관리자별 / 모델별 / 클래스별로 세분화된 필터링 가능
• 알람 빈도나 대상 조건을 현장 환경에 맞춰 유연하게 조정 가능
• 기존 고객사 사례에서 보호구 탐지 → 물류 영역으로 확장 적용이 논의되고 있음

기능 설명을 넘어서, 기술의 유연성과 확장 가능성까지 함께 전달하는 데 중점을 두었습니다. 이는 곧 제품 설계 측면에서 실질적인 경쟁력이 무엇인지, 현장의 언어로 풀어내는 작업이기도 했습니다

이번 EXPO는 제품의 정식 런칭 이후 첫 외부 공개 무대였습니다. 내부적으로는 이전부터 납품 경험이 있었지만, 공식적인 전시는 이번이 처음이었기에 제게도 기술적 설명 이상의 의미가 있었습니다.

외국인 방문객의 대응도 중요한 경험이었습니다. 준비되지 않은 상태에서의 즉흥적인 영어 설명은 다소 어려웠고, 다음 행사부터는 기술 포인트를 영어로도 매끄럽게 전달할 수 있도록 사전 준비가 필요하겠다는 점을 느꼈습니다.

돌이켜보면, 첫날에 배정된 것도 어쩌면 의도된 선택이었는지 모릅니다.
팀 내에서 입사 순서상 막내였기 때문이죠. (물론 나이로는 막내가 아닙니다.)

당시에는 몰랐지만, 시간이 지나고 나니 알게 되는 것들이 있습니다.
그래서 기록이 중요하다는 걸 다시 한번 느꼈고, 지금이라도 남길 수 있어 다행입니다.

마무리

PoC는 늘 시간과 리소스가 빠듯한 상태에서 시작됩니다. 정해진 모델도, 준비된 데이터셋도 없이, 어떻게든 가능성을 증명해야 하는 과제가 남겨집니다. 그래서 때로는 모델보다 데이터에 더 많은 시간을 쓰게 되고, 설계보다 시각화에 더 많은 공을 들이게 됩니다. 그 과정은 외롭고 반복적이며, 방향이 맞는지 확신할 수 없는 순간도 많습니다.

그래도 끝까지 손을 놓지 않으면 “여기까지는 도달할 수 있다”는 기준선은 남길 수 있습니다.
누군가에게 보여주기 위해서든, 스스로 확인하기 위해서든 말입니다. 기술은 결국 보여지는 방식으로 이해되고, 설득은 수치보다 맥락과 타이밍에 좌우되는 경우가 많습니다.

전시 영상은 더 명확한 목적과 방향성을 갖고 제작됩니다. 기능 구현보다는 메시지 전달과 연출, 보여주는 방식의 완성도가 핵심입니다. 또한 예측 가능성이 높은 영역이기도 합니다. 결과를 어느 정도 예상하며 만들 수 있고, 요구사항에 맞춰 시각적으로 조정해 나가는 과정에 집중할 수 있습니다.

이번 전시도 그런 흐름으로 마무리되었습니다. 제가 제작한 영상이 부스에서 재생됐고, 현장에서 여러 방문자들 앞에서 제품 설명을 이어갔습니다. 피곤했지만, 좋은 질문도 몇 가지 오갔습니다.

그리고 다시 PoC 자리로 돌아왔습니다. 이 모든 과정을 마쳤어도 정식 계약으로 이어질지는 미지수입니다. 결과가 확정되지 않으면 남는 건 쓰임을 다한 산출물뿐이며, 그 앞에서 한동안 생각이 머뭅니다. 특히 처음부터 끝까지 혼자 감당한 프로젝트일수록 더 깊게 남습니다.

어떤 프로젝트는 결과로 이어지고, 어떤 프로젝트는 마음에 남은 채 조용히 사라질지도 모릅니다. 그 둘을 지금은 구분할 수 없지만, 제가 할 수 있는 일은 모든 과정을 끝까지 겪어내는 것입니다.

그리고 언젠가 그 경험이 다음 선택의 기준이 될 수 있기를 바랍니다.

카메라를 설치하는 것 자체보다 중요한 것은,
카메라의 종류, 설치 위치, 화각, 해상도, 전송 방식 등
여러 물리적·기술적 요소를 분석 목적에 맞게 정밀하게 설계하는 것입니다.

적절한 사전 설계 없이 영상만 확보한다고 해서
AI가 객체를 정확히 인식하거나, 원하는 결과를 안정적으로 제공하는 것은 어렵습니다.

이 포스팅은 실제 Vision AI 프로젝트의 설계 및 운영 경험을 바탕으로,
카메라 선택부터 설치 위치, 영상 연결 구조, 분석 설정 구성까지
실무 관점에서 반드시 고려해야 할 내용을 정리해 보았습니다.

1. CCTV 카메라의 주요 종류

Vision AI 시스템에 활용되는 CCTV는 설치 환경과 목적에 따라 카메라 형태가 달라집니다.

예를 들어 실내용은 Dome형, 외부 장거리 감시는 Bullet형이 주로 사용되며,
넓은 공간을 커버해야 하는 경우에는 PTZ나 360도 카메라가 적합합니다.

카메라의 형태는 분석 성능뿐 아니라 설치 난이도, 유지 관리에도 영향을 미치므로
환경에 맞는 타입 선택이 필요합니다.

2. 카메라 스펙이 분석에 미치는 영향

고해상도 카메라는 객체 디테일 확보에 유리하며,
센서 크기가 클수록 야간이나 저조도 환경에서 노이즈를 줄이고 색 재현력을 향상시킬 수 있습니다.

일반적으로 프레임레이트가 지나치게 낮을 경우,
순간적인 이벤트나 객체 추적 성능 저하가 발생할 수 있습니다.
예를 들어, 5fps 이하에서는 빠른 움직임을 놓치기 쉽고,
15fps 이상이면 안정적인 실시간 분석이 가능합니다.

또한 압축방식에 따라 스트림 품질 및 분석 지연시간이 영향을 받습니다.
특히 AI 분석에서는 Keyframe 간격, 압축 artifact 발생 여부 등도 중요한 고려 요소입니다.

실무에서는 화질, 성능, 시스템 부하 간의 균형이 중요합니다.

현재 담당 중인 제품은 FHD 해상도와 10~15fps 환경에 맞춰 설계되어 있으며,
처리 효율성과 분석 안정성을 확보하는 데 적합한 접근으로 평가받고 있습니다.

3. RGB/IR 촬영 특성과 Vision AI

영상의 색상 정보는 탐지 정확도에 직접적인 영향을 미칩니다.

일반적으로 RGB 카메라가 기본으로 사용되며,
실내외 대부분의 환경에서 안정적인 성능을 보입니다.

RGB 영상은 색상 정보를 그대로 보존하므로,
안전모 색상이나 작업복 구분 등 시각적 세부 요소 분석에 적합합니다.

반면 IR(Infrared) 카메라는 야간 감시나 조도 부족 환경에서
객체의 윤곽이나 움직임을 감지하는 데 강점을 가지며,
보조 수단으로 활용되는 경우가 많습니다.

분석 목적이 색상 인식이라면 RGB가 기본이며,
어두운 환경에서는 IR 카메라를 병행해 사용하는 방식이 효과적입니다.

4. 렌즈 & 화각 유형별 비교

렌즈의 초점 거리는 카메라가 확보할 수 있는
시야의 폭(FOV, Field of View)을 결정하는 핵심 요소입니다.

예를 들어 2.8mm 광각 렌즈는 넓은 영역을 한 번에 촬영할 수 있지만,
객체는 작게 보이고 왜곡이 발생할 수 있습니다.

반면 16mm 이상의 망원 렌즈는 멀리 있는 객체를 크게 포착할 수 있지만,
시야가 좁아 다른 객체를 놓칠 수 있습니다.

설치 환경과 분석 목적에 따라 광각, 표준, 망원 선택이 달라지며,
초점 거리를 수동 조절할 수 있는 Varifocal 렌즈나
원격 제어가 가능한 Motorized 렌즈도 실무에서 자주 활용됩니다.

• 3.6mm 렌즈는 일반적으로 사람의 시야각과 가장 유사한 화각을 제공합니다.
• 실내 고정 감시는 표준형 또는 Varifocal, 외부 침입 감지는 광각 또는 망원이 자주 쓰입니다.
• Motorized 렌즈는 설치 이후 원격 환경에서 시야를 조정해야 할 때 유리합니다.

5. CCTV 화각 비교 및 왜곡 분석 – 실사례 기반 4종 비교

화각은 한 대의 카메라가 커버할 수 있는 시야의 각도입니다.
객체가 화면에서 얼마나 크게 보이는지에 영향을 줍니다.

Vision AI 시스템에서는 카메라의 화각(FOV, Field of View)과
왜곡 특성이 모델의 분석 성능에 직접적인 영향을 미칩니다.

현장에서는 일반적으로 광각 렌즈(약 100~130°) 가 많이 활용됩니다. 이는 적은 수의 카메라로 넓은 공간을 커버할 수 있어 설치 수량과 비용을 줄이는 데 유리하기 때문입니다.

또한, 실제 환경에서는 카메라를 자유롭게 설치하기 어려운 경우가 많아, 넓은 화각으로 시야 확보를 우선 고려해야 하는 경우가 많습니다.

반면, 분석 정확도나 왜곡 최소화가 중요한 환경에서는 일반각(85~90°)이 더 적합할 수 있습니다. 일반각은 왜곡이 적고, 객체의 형태와 위치를 보다 정밀하게 분석할 수 있기 때문입니다.

정리

• 화각이 넓을수록 왜곡이 발생하기 쉬우며, 이는 분석 정확도 하락으로 이어질 수 있습니다.
• 특히 객체가 중앙에 위치해 있더라도,
  광각 렌즈 자체의 원근 과장 효과로 인해 왜곡 현상이 발생할 수 있습니다.
• 따라서 분석 목적에 따라 적절한 화각을 선택하고,
  렌즈 보정 특성을 함께 고려해야만 최적의 모델 성능을 확보할 수 있습니다.

6. CCTV 설치가 Vision AI 시스템에 끼치는 영향

CCTV는 영상 확보 장비를 넘어, Vision AI 시스템과 연결될 경우
설치 조건 자체가 분석 성능에 직접적인 영향을 줍니다.

따라서 “잘 보이는 곳”이 아닌,
분석 목적에 맞는 위치와 시야 조건을 고려한 설치가 중요합니다.

설치 위치는 초기에 정확히 정하는 것이 가장 효율적

설치 후에도 각도나 초점 조정은 가능하지만, 실제 현장에서는 다음과 같은 제약이 많습니다:

• 위치를 바꾸려면 방향 조정만으로는 부족하고, 배선 및 브래킷 재설치가 필요합니다.
• 대부분의 프로젝트에서 CCTV가 AI 시스템보다 먼저 설치되므로,
  화각이 맞지 않으면 분석이 지연되거나 반복 수정이 발생합니다.
• 특히 산업 및 야외 환경에서는, 설치 후 위치 변경이 사실상 불가능한 경우도 많습니다.

분석보다 더 큰 리스크는 “설치 지연”

설치 이후에도 조정은 가능하지만,
초기 설치 자체가 늦어지면 프로젝트 전체 일정에 영향을 줄 수 있습니다.

• 카메라가 없으면 화각 검토나 분석 테스트 자체가 불가능합니다.
• 위치가 확정되지 않으면 분석 조건도 설정할 수 없습니다.
• 실제로 일정이 지연된 프로젝트 상당수는 설치 시점을 확정하지 못했던 경우였습니다.

Vision AI 분석이 병행되는 프로젝트일수록,
초기에 설치를 완료하고, 운영 중 조정하는 방식이 더 현실적입니다.

“완벽한 설치 타이밍”을 기다리기보다는,
일단 시작하고 보정하는 접근이 더 성공적입니다.

단 한 번의 설치가 모든 걸 해결해주지 않습니다.
하지만 단 한 번도 설치하지 않으면, 아무것도 시작되지 않습니다.

실제 사례로 본 설치 리스크

• 각도나 초점은 조정할 수 있지만,
  설치 위치는 일단 정해지면 변경이 쉽지 않습니다.
• 여러 프로젝트에서 화각 조정은 자주 있었지만,
  위치 변경은 일정 지연·장비 재설치로 이어졌습니다.
• 현재도 진행 중인 실제 사례가 있습니다.
  PoC 완료, 모델 구축, 화각 시뮬레이션까지 마친 상태지만,
  CCTV 설치가 지연되면서 사업 마무리가 기약 없이 멈춰 있는 상황입니다.
• Vision AI 프로젝트일수록,
  설치 전 시야 조건을 검토하고 빠르게 설치에 착수할 수 있는 결정 구조가 필요합니다.
• 설치는 분석의 시작점입니다.
  미루기보다 시작하고 조정하는 것이 훨씬 실용적입니다.

7. 영상 내 객체 크기 추정

Vision AI 분석 성능은 알고리즘의 성능뿐만 아니라,
CCTV 설치 위치, 해상도, 렌즈 화각(FOV), 프레임 속도(FPS) 같은 물리적 요소가
객체 탐지의 성공 여부에 큰 영향을 미칩니다.

탐지 성능에 영향을 주는 요소들

• 해상도: 높을수록 객체가 화면에서 더 크게 보임 (권장: 1080p 이상)
• 렌즈 화각(FOV): 좁을수록 멀리 있는 객체도 더 크게 보임 (권장: 60도 이하)
• 카메라 위치: 설치 높이와 거리 조정으로 탐지 가능 범위 최적화
• 프레임 속도(FPS): 움직임 기반 분석은 최소 10fps 이상 권장
• 사전 검증: 실제 촬영 또는 시뮬레이션 기반 검증이 필수

이러한 조건이 적절히 설계되지 않으면,
객체가 화면에 너무 작게 찍혀 AI가 탐지하지 못하거나, 정확도가 떨어질 수 있습니다.

객체 크기와 탐지 성능의 관계

객체가 영상 내에서 얼마나 큰 크기로 보이느냐는,
AI 모델이 해당 객체를 정확히 검출하고 탐지할 수 있는지를
결정짓는 핵심 요소입니다.

일반적으로 화면 세로 해상도의 약 6~8% 이상에 해당하는 크기로 객체가 나타날 경우,
대부분의 모델에서 안정적인 탐지가 가능합니다.

• 720p(1280×720) 기준: 약 40~50픽셀 이상
• 1080p(1920×1080) 기준: 약 60~80픽셀 이상
• ※ 단, 모델 구조 및 학습 데이터셋에 따라 달라질 수 있습니다.

정리

• 객체가 너무 작으면 AI가 탐지하지 못하거나 탐지 정확도가 크게 떨어질 수 있습니다.
• 설치 전, 목표 객체의 거리/크기에 기반해 최소 탐지 픽셀 크기 기준을 확보해야 합니다.
• 설치 조건과 카메라 성능은 AI 분석 효과를 좌우하는 가장 기본적인 설계 변수입니다.

8. 영상 연결 방식과 스트리밍 프로토콜

영상 스트리밍은 데이터를 수신하는 과정을 넘어서,
실시간성, 지연 시간, 해상도 보존, 호환성 등 시스템 전반의 성능에 영향을 주는 핵심 요소입니다.

RTSP는 Vision AI 분석 시스템과 연동하기에 가장 일반적인 방식이지만,
브라우저에서는 직접 사용할 수 없기 때문에 미디어 서버를 통한 중계가 필요합니다.

RTMP는 방송 송출용으로 널리 사용되며,
상대적으로 낮은 지연을 제공하지만 WebRTC보다는 지연이 큰 편입니다.

WebRTC는 초저지연 특성을 지녀
브라우저 기반의 실시간 분석 결과 확인에 적합합니다.

분석 지연 시간(Latency), 사용자 대시보드 제공 여부, 다중 스트림 분배 등의 조건에 따라
여러 스트리밍 프로토콜을 혼합 설계하는 것이 일반적입니다.

9. 미디어 서버

미디어 서버는 영상 스트림을 분배, 변환, 보정, 동기화하는 핵심 인프라입니다.

예를 들어, RTSP 기반 CCTV 영상이 입력되면
이를 분석 시스템에 전달하는 동시에 WebRTC로 변환하여 대시보드에 실시간 전송할 수 있습니다.

또한 분석 결과(Bounding Box, Segmentation Mask, Pose Keypoints 등)를
영상에 Overlay하여 사용자에게 실시간으로 송출할 수 있습니다.

다수의 CCTV 스트림을 하나의 분석 파이프라인에서 처리하기 위해서는
프레임 동기화, 일시적 끊김에 대한 복원 처리, 네트워크 재접속 관리 등을
수행하는 미디어 서버가 필수적입니다.

이는 시스템의 실시간성, 안정성, 유연성을 확보하는 데 있어 핵심 구성 요소입니다.

10. 실전 대응 체크리스트 예시

아래는 실무에서 인바운드 문의를 받을 때 활용하는 예시 양식입니다.
설치 환경, 카메라 조건, 분석 대상, 성능 기대치 등을 사전에 파악할 수 있도록 구성되어 있습니다.

[신규 Inbound 양식]
모든 항목은 복수 선택 / 공란 허용됩니다.
모르거나 확인이 어려운 항목은 아시는 대로만 작성해 주셔도 됩니다.

1. 고객 정보

• End-user:
• 발주처:
• 사업명 (있을 경우):

2. 고객이 요구하는 기능 또는 상황 (복수 선택 가능)

• ☐ 특정 구역에 출입/잔류 인원 수 파악
• ☐ 야생동물, 사람 등의 침입 시 알림
• ☐ 사람이 쓰러진 상황 자동 감지
• ☐ 화재/연기 발생 시 빠른 탐지
• ☐ 보호구 착용 여부 탐지
• ☐ 사람 또는 차량의 이동 동선 파악
• ☐ 문자 또는 번호판 인식
• ☐ 얼굴 식별 또는 출입 통제
• ☐ 기타: __________

3. 카메라 / 설치 환경

3.1 설치 여부 및 기본 정보

• 설치 여부: [☐ 설치 완료 / ☐ 설치 예정 / ☐ 미정]
• CCTV 제조사: [☐ 한화비전 / ☐ 기타: _______]
• 채널 수 (카메라 대수): [ ] 대
• 카메라 타입: [☐ 고정형 / ☐ PTZ / ☐ 360도 / ☐ 어안형(Fisheye) / ☐ 기타: _______]

3.2 해상도 및 조명 조건

• 화소/해상도: [☐ 1920x1080 / ☐ 4K / ☐ 기타: _______]
• RGB/IR 여부: [☐ RGB(주간 전용) / ☐ IR(야간 전용) / ☐ 불확실]
• 야간 촬영 포함 여부: [☐ 야간 포함 / ☐ 주간만 / ☐ 불확실]
• 조명 유무: [☐ 있음 / ☐ 없음 / ☐ 불확실]

3.3 화각, 렌즈, 시야 조건

• 화각(FOV): [☐ 일반각(≤90°) / ☐ 광각(>120°) / ☐ 어안형(>180°)]
• 렌즈 초점 방식: [☐ 고정 초점 / ☐ 수동 가변 초점 / ☐ 원격 조절(모터 구동)]
• 촬영 각도: [☐ 정면 / ☐ 측면 / ☐ 사선 / ☐ 불확실]
• 시야 중첩 여부: [☐ 있음 / ☐ 없음 / ☐ 불확실]

3.4 설치 위치 및 주요 거리

• 설치 위치 및 높이: (예: 노지 외부, 2.5m)
• 주요 촬영 거리: (예: 객체까지 약 6m)

3.5 탐지 대상 관련

• 카메라 시야 캡쳐 이미지 여부: [☐ 있음 / ☐ 없음]
  (※ 설치된 CCTV 영상의 대표 화면 1~2장 첨부 가능 시 체크)
• 영상 내 객체 크기 추정 (영상 없을 경우 작성):
  (예: 화면에 사람 1~2명이 꽉 차게 보일 것으로 예상 / 5~6명까지 화면에 보일 수 있음 등)

4. AI 분석 조건

• 클래스 수 및 종류: (예: 사람, 멧돼지 = 2종)
• 샘플 영상 제공 여부: [☐ 있음 / ☐ 없음 / ☐ 확보 예정]
• 데이터 수집 방식: [☐ 고객 제공 / ☐ 당사 수집 / ☐ 미정]
• 성능 기대 수준: (예: 정확도 90% 이상, 오탐 최소화 등)
• 성능 기준 중 우선순위: [☐ 정확도 / ☐ 오탐 최소화 / ☐ 속도(Latency) / ☐ 누락 최소화 / ☐ 기타: _____]
• 결과 출력 방식: [☐ 실시간 알림 / ☐ 대시보드 / ☐ 리포트 / ☐ 불확실]

5. 요청 사항

• 요청 유형: [ ☐ 실제 도입 문의 / ☐ PoC 요청 / ☐ 기술 검토 목적 / ☐ 기타: _____ ]
• 개발 MM 요청 여부: [☐ 예 / ☐ 아니오]
• 하드웨어 관련 현황:
  [☐ 견적 필요 (스펙 제안 요청)
  ☐ 사내 GPU/서버 보유 중 (모델명: _____)
  ☐ 아직 파악되지 않음 (확인 필요)]
• 사업 기간:
• 회신 희망일시: (예: 7월 23일 14시까지)
• 예상 예산 규모 (선택):
• 추가 요청 사항/메모:

마무리: 분석 설정은 누구를 위한 것인가?

객체지향 프로그래밍(OOP)의 설계 원칙 중 하나인
SRP(Single Responsibility Principle, 단일 책임 원칙)는
“하나의 책임(Responsibility)은 하나의 변화 주체(Actor)에 귀속돼야 한다”고 말합니다.

이 원칙은 단순히 코드 구조뿐 아니라,
Vision AI 시스템의 분석 설정 방식에도 통찰을 제공할 수 있습니다.

Vision AI 시스템은 다양한 CCTV 채널에서 입력된 영상을 분석하지만,
채널마다 설치 위치, 화각, 촬영 거리, 왜곡 정도가 다르기 때문에
동일한 Vision 모델을 적용하더라도 검출 결과의 품질이나 형태는 달라질 수 있습니다.

기술적인 변수 외에도 중요한 점은,
그 결과를 해석하고 활용하는 주체(Actor)에 따라
분석 결과가 갖는 의미 자체가 달라진다는 사실입니다.

• 보안 담당자는 “누가 들어왔는가”를 주로 보고,
• 안전 관리자는 “보호구 착용 여부”를 확인하며,
• 시설 관리자는 “쓰러짐 여부나 체류 시간”을 주목합니다.

즉, 같은 객체를 대상으로 하더라도
누가 그 결과를 보고 어떻게 해석하느냐에 따라
필요한 탐지 기준, 임계값, 알림 조건은 전혀 달라져야 합니다.

그럼에도 불구하고 많은 시스템은 여전히 객체 중심으로 구성되어 있어,
하나의 분석 설정(탐지 클래스, 임계값, 알림 조건 등)을
모든 채널에 일괄 적용하는 방식을 사용하고 있습니다.

그러나 분석 설정이 객체(Object)를 기준으로 일괄 고정되어서는,
실제 업무 목적에 부합하는 유연한 대응이 어려워집니다.

따라서 분석 설정은 객체가 아니라 Actor(사용자)의 역할과 목적에 따라 구성되어야 합니다.
이러한 관점은 “Single Actor Principle(SAP)”로도 알려져 있으며,
저 또한 이 원칙에 공감하고 실무 전반에 적용하고 있습니다.

각 CCTV 채널은 특정 Actor의 목적을 위해 설치되며,

• 어떤 객체를 탐지할지,
• 어떤 조건에서 경고할지,
• 어떤 방식으로 알림을 전달할지는
  그 결과를 해석하고 책임지는 사람의 역할에 따라 달라져야 합니다.

객체 탐지 알고리즘은 “사실”을 판단하지만,
사람은 “맥락”을 해석합니다.
위에서 내려다본 시선, 정면에서 마주보는 시선, 아래에서 올려다본 시선은
동일한 객체라도 전혀 다른 의미를 만들어냅니다.

현재 담당 중인 Vision AI 제품은 이러한 SAP 관점에 따라,
CCTV 채널별뿐 아니라 사용자별로도 독립된 분석 설정을 구성하고 있으며,
모델, 클래스, 탐지 주기, 알림 주기, 임계값까지 채널 단위로 세분화해 운영되고 있습니다.

이는 단순한 기술적 구조가 아닌,
각 사용자(Actor)의 역할과 목적에 따라 책임을 분리하는 전략적 설계 방식이며,
현장에서 의미 있는 결과와 해석 가능성을 높이기 위한 구조적 기반입니다.

결국 Vision AI 시스템이 현장에서 유의미하게 작동하려면,
Object 중심이 아니라 Actor 중심의 분석 설정,
즉 SAP(Single Actor Principle)에 기반한 설계가 필요합니다.

“AI Engineer로 지원했는데 실제로는 데이터 정제만 하고 있어요.”
“AI Research Engineer와 AI Engineer의 차이가 뭔가요?”
“End-to-End AI Engineer라는 직함을 처음 봤는데, 정확히 뭘 하는 건가요?”

AI 업계에 종사하면서 자주 받는 질문들입니다. 실제로 AI 관련 직무는 회사마다, 팀마다 다르게 정의되어 있어서 지원자도, 채용하는 쪽도, 심지어 같은 팀 내에서도 혼란스러워하는 경우가 많습니다.

저도 처음 AI 커리어를 시작할 때 이런 혼란을 겪었고, 지금까지 다양한 포지션을 거치면서 각 직무의 실제 모습을 경험했습니다. 이 글에서는 제가 직접 겪은 AI 직무들의 실제 역할과 책임, 그리고 개인적인 커리어 변화 과정을 공유해보려고 합니다.

1. AI Researcher

AI Researcher는 새로운 알고리즘이나 모델 구조를 제안하고, 기존 기술의 한계를 극복하기 위한 연구를 수행하는 역할입니다. 산출물은 주로 논문이며, CVPR, NeurIPS, ICML, ICCV 등 국제 학회에 제출해 기술력을 증명합니다. 제품을 만드는 목적보다는, 이론적 기여나 SOTA 갱신, 모델의 성능 향상에 초점을 둡니다. 대부분 대학이나 대기업 산하 연구소에 소속되어 있으며, 현실의 데이터보다 논문용 정제 데이터셋과 벤치마크를 많이 다룹니다. 구현보다는 아이디어 중심의 작업을 많이 하며, 코드는 실험을 위한 도구일 뿐 핵심은 기획과 설계에 있습니다.

2. AI Research Engineer

AI Research Engineer는 AI Researcher가 제안한 논문 기반 기술을 실제로 구현하고, 실험을 통해 성능을 재현하거나 개선하는 역할입니다. 논문을 코드로 옮기고 실험 파이프라인을 구성하며, 벤치마크 데이터셋을 기반으로 다양한 실험을 반복합니다. 연구의 논리적 타당성과 구현상의 현실성 사이의 다리를 놓는 엔지니어로, 코딩 스킬과 수학적 이해력을 모두 요구받습니다.

3. AI Engineer

AI Engineer는 실제 제품이나 서비스에 적용할 AI 모델을 학습하고, 데이터셋을 구성하거나 모델의 성능을 개선하는 역할을 합니다. 주어진 목적에 맞는 모델을 선정하고, 필요한 경우 커스터마이징하거나 파인튜닝합니다. 학습된 모델을 기반으로 추론 결과를 만들어내고, 그 결과를 평가하여 다음 학습에 반영하기도 합니다. 비즈니스 요구사항과 기술 사이에서 균형을 맞추는 실무형 엔지니어입니다.

4. Applied AI Engineer

Applied AI Engineer는 고객이나 사용자의 니즈에 맞춰 AI 기술을 실질적인 문제 해결에 적용하는 엔지니어입니다. 자체적으로 Task를 정의하거나, 주어진 과제를 해결하기 위해 적절한 데이터셋을 구성하고, 모델을 실용적인 형태로 만들고 설명하는 데 집중합니다. “이건 가능한가요?”라는 질문에 기술적으로나 현실적으로 “가능합니다” 혹은 “불가능합니다”를 판단하고 설계합니다. 실제 서비스와 맞닿은 AI 개발자의 입장에 가장 가까우며, 설계적 사고와 유연한 문제해결력이 중요한 포지션입니다.

5. AI Backend Engineer

AI Backend Engineer는 학습된 AI 모델을 실제 서비스에 연동하기 위한 시스템을 구성하고, 모델의 추론 결과를 API나 소켓을 통해 전달하는 역할을 합니다. Docker 환경 구성, Python-C++ 바인딩, Redis 및 캐시 브로커 구성 등을 통해 분석엔진과 실서비스 간의 연결을 책임집니다. 모델 학습에는 직접 관여하지 않으며, 학습된 모델을 “서빙 가능한 형태”로 가공하고 실행 환경을 안정화하는 데 초점을 둡니다. 서비스 운영 단계에서 가장 가까운 위치에 있는 AI 시스템 엔지니어입니다.

6. End-to-End AI Engineer

일반적으로 End-to-End AI Engineer는 데이터 수집부터 모델 학습, 분석엔진 구현, API 연동, 결과 시각화, 운영 배포까지 전 단계를 책임집니다. 다양한 직무 간 경계를 넘나들며 기술적 소통을 주도하고, 시스템 전체의 흐름을 이해하며 실무를 진행합니다. 종종 PM 없는 PO, AI 기술 총괄 역할을 수행하게 되며, 기술 인바운드 대응이나 고객 피드백 수용까지 맡는 경우도 많습니다. 과업의 깊이보다는 넓이와 연결성을 중시하며, 혼자서 프로토타입을 구성하거나 제품화까지 이끄는 유연성이 필요한 포지션입니다.

7. Full Stack AI Engineer

Full Stack AI Engineer는 AI 모델 개발뿐 아니라 프론트엔드와 백엔드까지 아우르며, 실제 사용자에게 도달하는 시스템 전체를 구축할 수 있는 엔지니어입니다. React, FastAPI, AWS 등 다양한 기술 스택을 조합해 웹 인터페이스와 모델을 통합 구현합니다. POC, 데모, 전시용 AI 시스템을 짧은 시간 내에 만드는 데 강점을 가지며, 디자인 감각이나 사용성 고려도 병행하는 경우가 많습니다. AI와 Web 사이의 단절 없이 하나의 서비스로 완성해내는 융합형 개발자입니다.

8. 그 외 실무형 역할들 (직무로 인정받지 않지만 중요함)

실무에서 가장 시간이 오래 걸리지만, 공식 직무로 분류되지 않거나
외주/비정규직/도급 형태로 분리되는 경우가 많습니다.

AI 개발 프로세스 단계별 직무 기여도

기호 설명:

• ○ = 주도
• △ = 일부/협업
• ✕ = 관여하지 않음

  이 표는 각 직무가 관여하는 AI 개발 단계만을 나타냅니다. 투입 시간, 책임 강도, 병행 과업 수는 포함되지 않습니다.

현 조직의 AI 직무 구성

Team Leader

팀 전체 일정과 외부 대응을 총괄합니다. 고객사, 영업, 대표단과의 기술 협의에 참여하며, 내부 리소스 배분과 역할 조율을 주도합니다. 직접적인 모델 학습이나 분석엔진 개발에는 참여하지 않지만, 전반적인 방향성과 일정을 리드합니다.

(Almost) Full Stack AI Engineer

모델 결과를 기반으로 한 웹 기반 데모 제작, 검색엔진 연동, UI/UX 구성 등 시스템 전반을 폭넓게 다룹니다. Flask 기반 웹서버 구성, ChromaDB, Elasticsearch 연동 등 프론트·백엔드 경계를 넘나드는 구현이 가능하며, 분석엔진이 아닌 데모 중심의 시스템을 주로 설계하고, 필요 시 모델 파인튜닝도 수행합니다. 제품화에 가까운 프로토타입을 구성하지만, 실제 제품화 시에는 프론트엔드·백엔드 개발자가 별도로 투입됩니다. 조직 내에서는 비주력 제품을 중심으로 활동하며, 보조 기술 지원 역할도 함께 수행합니다.

End-to-End AI Engineer

AI 모델 개발부터 시스템 연동, 실서비스 대응까지 전체 흐름을 책임지며, 특히 외부 대응, 출장, 사업관리 협업이 모두 집중되는 핵심 포지션입니다. 모델을 학습하는 것뿐 아니라, 분석엔진에 탑재하고 실시간 환경에서 안정적으로 동작하도록 설계·조율합니다. 배포 이후 발생하는 이슈에 직접 대응하며, 추론 파이프라인, 테스트 구성, config 조정 등 운영 관점까지 폭넓게 다룹니다. 외부 회의 참석, 실증 환경 데이터 수집, 성능 검증, 제품화 대응까지 포함되어 있어, 실질적으로 AI 기반 시스템 전체를 관리합니다.

AI Backend Engineer

분석엔진의 추론 결과를 실서비스와 연결하는 인터페이스 개발을 핵심으로 담당합니다. Python 기반 분석엔진과 외부 시스템 사이의 REST API, WebSocket, Python-C++ 바인딩 모듈을 구현하며, Docker 환경 구성, 디코더/인코더 설정, 메모리 관리, 속도 튜닝 등도 병행합니다. 모델 학습에는 관여하지 않으며, “분석 결과가 실시간으로 서비스에 전달되도록 가공하는 역할”에 집중합니다. 또한, 시스템 내에서 예외 처리, 중단/재시작 로직, timeout 설정 등 운영 안정성을 확보하는 역할도 수행합니다.

AI Research Engineer

모델 학습을 중심으로 한 연구 개발을 전담합니다. 딥러닝 기반 구조 설계, 실험 설계, 성능 튜닝 등 학습 관련 주요 업무를 수행하며, 외부 경진대회 참가, 기술 검증, 논문 작성 등 학술적 성과에도 적극적으로 참여합니다. 모델의 구조적 완성도와 성능 향상이 주요 과업이며, 분석엔진 연동이나 실서비스 적용에는 직접 관여하지 않습니다. 기술의 원천성과 확장 가능성을 높이는 데 집중하며, 연구소 내 가장 학문 중심적인 포지션입니다.

Career Path

1. Data Analyst

저는 전형적인 CS 출신 개발자가 아닌, 상경계열 출신의 Data Analyst로서 AI 커리어를 시작했습니다. 사업관리팀 소속이었지만, 당시에는 개발자가 전혀 없는 조직에서 Python 기반 자동화 도구를 혼자 개발하며 실무를 주도했습니다. 엑셀보다는 Pandas, CLI보다는 Jupyter에 익숙했고, Slack 알림 봇, 리사이징/이름변경/비식별화 도구, 시각화 스크립트 등 다양한 툴을 만들어 데이터 흐름을 자동화했습니다.

수집부터 정제, 가공, 라벨링, 학습 테스트, 검수에 이르기까지 모든 단계를 하나의 FTP 서버 안에서 처리하도록 구성한 초기형 데이터 파이프라인을 직접 설계하고 운영했습니다.

또한, 데이터 상태를 기반으로 공정별 잔여 물량을 분석하고, 일일 리포트를 자동 생성하며, KPI 달성을 위한 추가 수집/보완 계획을 수립하는 등 정량적 관리와 품질 통제까지 총괄했습니다.

모델 학습 자체는 공식 R&R이 아니었지만, 가공단의 책임을 입증하고 “라벨링 문제로 성능이 안 나온다”는 학습단의 주장을 선제적으로 차단하기 위해 직접 라벨링한 데이터를 학습해보는 방식으로 사내 품질 검증 체계까지 구축했습니다.

정식 직무명은 Data Analyst였지만, 실제 역할은 거의 Entry-level AI Engineer에 가까웠습니다. 다만 당시에는 모델 개발보다 “데이터 상태를 분석하고 일정과 품질을 맞추는 것”이 핵심 목적이었기 때문에 경력증명서 상에는 Analyst로 기재되었으며, 이 경험은 훗날 AI Engineer로 전향하는 데 강력한 기반이 되었습니다.

2. AI Engineer

Data Analyst 시절 경험을 기반으로, 본격적으로 AI 모델 학습 중심의 업무에 전념하기 시작했습니다. 특수대학원에서 AI 전공을 병행하며, 실무와 학문을 함께 다져나간 시기이기도 했습니다. 조직 내에서는 연구소 소속으로, 주로 Vision AI 기반 Detection, Segmentation, Tracking 모델을 직접 학습하며 다양한 실험을 반복했습니다.

가장 큰 특징은 단일 모델 구조만을 고집하지 않고, 다양한 아키텍처를 바꿔가며 학습 실험을 주도했다는 점입니다. 오픈소스 기반 모델뿐 아니라, 프로젝트 목적에 맞춰 구조를 튜닝하거나 config를 조정하며 다량의 학습을 수행하는 것이 핵심 역할이었습니다.

실험 목적에 따라 필요한 경우에는 직접 데이터 수집, 정제, 라벨링까지 선행적으로 수행하기도 했습니다. Data Analyst 시절부터 데이터 흐름 전반을 이해하고 체화해온 덕분에, 학습을 위한 데이터 확보와 준비 과정도 능동적으로 처리할 수 있었습니다.

당시에는 최적화, 경량화, 서빙과 같은 후처리 단계에는 직접 관여하지 않았으며, 학습이 끝난 후 성능 지표를 기록하고, 필요시 시각화 기반 정성적 검토를 통해 모델을 개선하는 데 집중했습니다.

정식 직무는 AI Engineer였으며, 핵심 업무는 다양한 모델을 “직접 학습해보는 것” 자체에 있었습니다. 후속 배포보다는 실험적 모델링과 학습 반복 중심의 역할이었고, 학습 중심의 수행 경험이 Applied AI Engineer로 이어지는 기반이 되었습니다.

3. Applied AI Engineer

AI Engineer 시절에는 학습 자체에 집중했다면, Applied AI Engineer로 넘어오면서부터는 학습 결과를 실환경에 적용 가능하게 만드는 일에 무게가 실리기 시작했습니다.

실제 업무는 학습부터 검증, 최적화, 분석엔진 탑재 전까지의 전 과정을 직접 수행하거나 조율했습니다. 당시 제품화 중심의 조직에서, 팀의 필요와 방향성에 따라 Applied AI Engineer라는 직함이 새롭게 도입되었고 그 첫 역할로 합류하게 되었습니다.

연구소가 만든 모델을 검증하고 문제를 파악해 수정하거나, 요청한 모델이 일정 등의 사유로 전달되지 않을 경우 직접 학습부터 경량화까지 전 과정을 대신 수행하기도 했습니다.

정식 모델 개발이 아닌 PoC, 기능 시연용, 전시용 영상 제작 등을 위해 수집부터 정제, 가공, 학습, 검증, 분석엔진 적용 전 시각화까지의 전체 흐름을 혼자서 처리한 경험도 많습니다.

다양한 프로젝트에서 검증 대상이 된 모델들의 정량·정성 평가, 실제 시스템 탑재 전 리소스 체크(fps, 메모리, 실행시간 등), 성능을 보완하기 위한 추가 실험 및 보조 학습, 그리고 테스트셋 구성과 결과 분석까지 포함된 역할이었습니다.

당시에는 모델 개발과 검증의 R&R이 불명확했기 때문에, 연구소와 제품화 팀 사이의 공백을 메우는 실무 조율자 역할도 수행했습니다.

Applied AI Engineer는 말 그대로, 현실적인 제약을 반영하여 모델을 실사용 가능한 형태로 “적용”시키는 역할이었습니다. 실험보다 현장 적용, 구조보다 리소스 조건, 알고리즘보다 ROI(Return on Investment)가 중요한 상황에서 가능 여부를 판단하고, 안 되는 것을 되게 만드는 것이 Applied의 핵심이었습니다. 극단적으로는 “돼요? 안돼요?”가 실질적인 산출물이 되는 경우도 많았습니다.

4. End-to-End AI Engineer

조직 개편과 AI Backend Engineer의 퇴사로 인해, Applied AI Engineer에서 분석엔진과 시스템 연동까지 책임지는 포지션으로 확장되었습니다. 그 결과, 현재는 모델 개발뿐 아니라 모델이 탑재된 AI 시스템 전체를 책임지는 End-to-End AI Engineer 역할을 수행하고 있습니다.

기획 의도 파악, 사전 검증, 모델 설계 및 학습, 분석엔진 최적화, 시스템 반영, 성능 대응, 운영 안정화까지 AI 모델이 현장에서 쓰일 수 있도록 하기 위한 전 과정을 조율하고 실행합니다.

예를 들어, 아래와 같은 역할을 실제로 수행하고 있습니다.

• 고객 요구 사항 기반 Task 정의 및 PoC용 데이터 수집
• 라벨링 가이드 작성 및 라벨 검수/피드백
• 모델 설계 및 반복 학습
• 시각화 기반 정성 평가
• 모델 최적화 및 경량화
• 분석엔진 성능 저하 이슈 대응 (실시간성, 리소스 등)
• 외부 회의 참석 및 실서비스 이슈 실시간 해결
• 실제 웹 인터페이스에서 결과 확인 및 파라미터 조정
• 분석엔진 추론 로그 기반 이상 탐지 및 개선점 도출

기술 스택 면에서는 Python 기반 모델 프레임워크와 함께 GPU 점유율, 추론 속도, 시스템 동작 상태를 체크하며 전체 AI 파이프라인을 다룹니다. Streamlit 기반 간단한 데모도 직접 구성하지만, 복잡한 API 연동이나 시스템 설계는 AI Backend Engineer 또는 Full Stack Engineer와 협업합니다.

모델을 넘어서 시스템 전체를 보는 것이 End-to-End의 핵심입니다. 다만, 시스템 아키텍처 자체를 처음부터 설계하거나 구조적으로 리팩터링하는 CS 중심의 역량은 포함되지 않습니다. 대신 현장에서 바로 돌아가는 실체를 다룬다는 점에서, 실용적 End-to-End에 가깝다고 할 수 있습니다.

정리

Applied vs E2E, 2개월차 회고

1. End-to-End, 진짜 좋을까?

최근 신입 AI Backend Engineer가 합류했지만, 저는 여전히 E2E 역할에서 벗어나지 못하고 있습니다. 외부 회의와 출장 일정이 잦아지면서, 인수인계도 충분히 하지 못한 채 하루하루를 넘기고 있습니다. 일주일에 개발을 이틀도 못 할 정도로 일정이 쏠려 있고, 본래 집중해야 할 개발 업무는 점점 밀려만 갑니다.

전임자가 퇴사한 뒤 AI Backend 역할까지 자연스레 떠맡게 되면서 체력적, 정신적으로도 부담이 큽니다. 막상 일을 나누려 해도 애매한 부분이 많고, 실력 있는 분이긴 하지만 시스템 구조 전체를 파악하기엔 아직 시간이 더 필요합니다. 결국 모델 서치 같은 업무까지도 백엔드에게 부탁하게 되는 현실이 가끔은 미안하게 느껴지기도 합니다. 애초에 그쪽 업무는 그분의 역할이 아닌데 말이죠.

Applied에선 경험으로 커버할 수 있었던 일도 많았지만, E2E는 그렇지 않습니다. CS 기반이 부족한 저에겐 네트워크나 시스템 구조, 인터페이스 설계가 버겁게 다가오고, 이해하지 못한 채 넘기지 않으려다 보니 오히려 더 많은 리소스를 쓰게 됩니다.

2. Applied의 명료한 구조가 그리운 이유

그래서인지 Applied AI Engineer 시절이 자주 떠오릅니다. 요청 기반 업무라 실적을 수치로 드러내긴 어렵지만, 책임 범위와 산출물이 명확했고, 제 성향과도 잘 맞았습니다. 지금처럼 흐릿한 책임선 사이에서 모델, 시스템, 회의, 고객 대응까지 모두 챙겨야 하는 구조보다는, 그 시절엔 단 하나의 질문만 있으면 됐습니다.

“돼요?” / “안 돼요?”

그 한마디로 갈리는 명료한 구조가 저에겐 큰 안정감을 줬습니다. 기술이 기준을 만족하느냐 마느냐, 그 단순한 결론이 오히려 제게는 더 잘 맞았던 것 같습니다. 무엇보다 처음엔 “안 돼요”였던 걸 “되게” 만들어가는 과정이 참 매력적이었습니다. 조금씩 성능을 끌어올려 결국 OK를 받아내던 그 순간의 성취감은 지금도 생생히 기억납니다.

가끔은 퇴사한 전임자가 돌아오고, 제가 다시 Applied로 복귀할 수 있다면 좋겠다는 생각도 듭니다. 하지만 이제는 연차도 쌓였고, 더 많은 책임을 받아들여야 할 시기라는 것도 알고 있습니다.

3. 무게는 늘었지만 권한은 줄었다

사실 저에게 인수인계를 하고 나간 사람이 벌써 네 명입니다. 그 중에는 리더급 1명도 포함되어 있었고, 그 자리를 명확히 메우기도 전에 자연스레 제게로 업무가 몰려들었습니다. 공식적인 리더는 아니지만, 실질적인 리더 역할까지 떠맡게 된 셈입니다.

리더가 아니면 권한은 없고, 책임만 생깁니다. 회의와 구조 파악, 고객 대응까지도 제 몫이 되었고, 정작 본업인 개발은 손에 꼽을 만큼밖에 못 하고 있습니다. VSCode도, Cursor도 켜는 날보다 닫는 날이 많아졌습니다. 이제는 “내가 왜?”, “왜 나만?” 같은 생각조차 줄어들었습니다. 에너지를 아끼기 위해 그런 물음에 더는 힘을 쓰지 않기로 했습니다.

4. 실력은 남는다, 결국은

그래도 한 가지는 분명합니다. 실력은 늡니다. Data Analyst 시절에도 처음엔 구조도 모른 채 일을 떠맡았지만, 버티고 부딪히며 익힌 것들이 결국 지금의 밑바탕이 되었습니다. 그때처럼 지금도 매일 조금씩 영역이 확장되고 있다는 걸 체감합니다.

이직한 지 얼마 안 된 경우에는 인수인계 문서보다 먼저 조직의 구조와 사람들을 살펴봐야 합니다. 어디가 비어 있는지, 그 빈틈이 무너지면 어떤 연쇄 반응이 나에게까지 번질지 생각해야 합니다. 지금의 저는 그 연쇄 반응의 끝에 서 있는 사람입니다.

다음에 이직을 하게 된다면, E2E보다는 Applied AI Engineer 포지션에 더 집중해보고 싶습니다. 현 회사도 제안을 받아 입사했듯이, 언젠가 Applied로 다시 함께하자는 제안이 오길 조용히 기다리고 있습니다. 그 때는 서로의 기대가 일치하는 자리에서, 더 단단하게 함께 일해보고 싶습니다.

그 전까지는 지금의 자리에서 제 역할에 최선을 다할 생각입니다.
그래도 야근은 하지 않습니다. 무슨 일이 있어도 칼퇴근합니다.
최소한의 리소스는 남겨둬야 다음 날도 일할 수 있기 때문입니다.
출장은 여전히 가기 싫지만요.

• (1) Task 정의, 데이터 수집, 데이터 정제
• (2) 데이터 가공, 학습데이터셋 구축, 모델 학습 및 검증
• (3) 모델 최적화 및 경량화, 분석엔진 개발, 시스템 배포 및 운영

8. 모델 최적화 및 경량화

모델 학습과 검증이 완료되면,
실제 시스템 환경에 맞춰 모델을 최적화하고 경량화하는 단계가 필요합니다.
이 과정에서는 추론 속도, 메모리 사용량, 배치 처리 구조, 플랫폼 이식성 등
운영 환경 전반을 고려해 실무에 적합한 모델 구조를 완성합니다.

왜 필요한가?

실제 제품 환경에서는 다음과 같은 요구사항들이 모델 최적화를 필요로 합니다: