기업 환경에서 라이선스 비용이나 클라우드 도입을 위해 불가피하게 오라클 데이터베이스에서 다른 데이터베이스로 전환해야 하는 일을 겪게 됩니다. 오라클은 좋은 데이터베이스이며 오랫동안 잘 사용해왔다면 오라클과 다른 데이터베이스의 차이점과 특징을 간과하여 슬픈 현실들을 마주하게 됩니다.

여기 수년간 잘 돌아가던 대출 이자 산출 쿼리가 있습니다. 문법만 바꿔서 여러 데이터베이스에서 돌려봤습니다. 그런데 오라클과 1원의 차이가 발생합니다. 같은 쿼리인데 말이죠. 특히나 금융 환경 같은 경우는 1원의 오차를 그냥 넘어갈 수 없습니다. 허용 오차는 0입니다.

이 포스트에서 그 1원의 오차가 왜 생기는지 정리해보았습니다. 원인은 생각보다 깊은 곳에 있었고, 해결책은 두 가지였습니다. 후순위 나눗셈과 명시적 형변환이었습니다. BigQuery, Spanner, PostgreSQL, MySQL, Presto, Trino 6종의 데이터베이스를 테스트해보았습니다.

2. 테스트 환경

• 원천 환경: Oracle Database 21c (대출 이자 산출 쿼리, 100,000건 데이터)
• 테스트 대상: Google BigQuery, Google Spanner, PostgreSQL, MySQL, Presto, Trino 총 6종
• 테스트 목표: Oracle 결과와 동일하게 1원도 오차가 발생하지 않도록

종합 테스트 결과 요약

같은 쿼리를 각 플랫폼에서 그대로 실행했을 때와, 후순위 나눗셈 적용 후 결과를 나란히 정리했습니다.

테스트 절차 요약

graph TD
    A[Oracle 데이터 추출] --> B[대상 DB 스키마 정의 및 데이터 로드]
    B --> C[1차 번역 쿼리 실행]
    C --> D[정합성 테스트 및 오차 발생]
    D --> E[DB별 소수점 연산 방식 분석]
    E --> F[대수적 통분 및 후순위 나눗셈 수식 설계]
    F --> G[최적화 쿼리 실행]
    G --> H[6종 DB 전수 테스트 및 결과 기록]

3. 대출 이자 수식 및 스키마 이행

3.1 스키마 매핑 분석

소수점 정밀도 손실을 막기 위해 Oracle NUMBER 타입에 BigQuery BIGNUMERIC 타입을 매핑했습니다.

BIGNUMERIC(precision, scale): 괄호 안 첫 번째 숫자는 전체 유효 자릿수, 두 번째는 소수점 이하 자릿수입니다. BIGNUMERIC(5,2)는 최대 999.99까지 표현할 수 있으며, 이자율 8.50, 14.60 같은 값을 저장합니다.

BigQuery 스키마 정의 (schema.json):

[
  {"name": "기준년월",       "type": "STRING",     "mode": "REQUIRED"},
  {"name": "고객관리번호",   "type": "BIGNUMERIC", "mode": "REQUIRED"},
  {"name": "대출관리번호",   "type": "STRING",     "mode": "REQUIRED"},
  {"name": "대출잔액",       "type": "BIGNUMERIC", "mode": "REQUIRED"},
  {"name": "약정금리",       "type": "BIGNUMERIC", "mode": "REQUIRED"},
  {"name": "대출실행일자",   "type": "DATE",       "mode": "REQUIRED"},
  {"name": "이자계산기준일", "type": "DATE",       "mode": "REQUIRED"}
]

데이터 로드 스크립트 (prepare_and_load.py):

import csv
import json
import subprocess

def prepare_csv():
    with open("oracle_data.csv", "r", encoding="utf-8") as fin:
        reader = csv.reader(fin)
        rows = list(reader)

    bq_rows = [rows[0][:7]]
    for r in rows[1:]:
        if len(r) >= 7:
            bq_rows.append(r[:7])

    with open("bq_load_data.csv", "w", newline="", encoding="utf-8") as fout:
        writer = csv.writer(fout)
        writer.writerows(bq_rows)

    print(f"Prepared bq_load_data.csv with {len(bq_rows) - 1} rows.")

def create_and_load_bq():
    schema = [
        {"name": "기준년월",       "type": "STRING",     "mode": "REQUIRED"},
        {"name": "고객관리번호",   "type": "BIGNUMERIC", "mode": "REQUIRED"},
        {"name": "대출관리번호",   "type": "STRING",     "mode": "REQUIRED"},
        {"name": "대출잔액",       "type": "BIGNUMERIC", "mode": "REQUIRED"},
        {"name": "약정금리",       "type": "BIGNUMERIC", "mode": "REQUIRED"},
        {"name": "대출실행일자",   "type": "DATE",       "mode": "REQUIRED"},
        {"name": "이자계산기준일", "type": "DATE",       "mode": "REQUIRED"},
    ]
    with open("schema.json", "w", encoding="utf-8") as sf:
        json.dump(schema, sf, indent=2, ensure_ascii=False)

    subprocess.run(["bq", "rm", "-f", "-t", "DM.월별대출이자산출"], check=False)
    cmd = [
        "bq", "load", "--source_format=CSV", "--skip_leading_rows=1",
        "DM.월별대출이자산출", "bq_load_data.csv", "schema.json"
    ]
    res = subprocess.run(cmd, capture_output=True, text=True)
    if res.returncode == 0:
        print("Successfully loaded data into BigQuery table DM.월별대출이자산출!")
    else:
        print("Failed:", res.stderr)

if __name__ == "__main__":
    prepare_csv()
    create_and_load_bq()

3.2 대출 이자 수식 정의

보통 이자는 대출 실행일 다음 날부터 계산합니다.
정산 주기 내 최소 이자를 보장하는 기산가산일수(30일) 조건이 수식에 붙어 있습니다.

TRUNC(값, 소수점_자릿수): 두 번째 인자가 소수점 이하 몇 자리까지 남길지를 결정합니다. TRUNC(76551.789, 0)은 소수점 아래를 모두 버려 76551이 됩니다. 반올림이 아니라 버림이라, 76551.999도 76551입니다.

Oracle 원천 SQL:

SELECT N10.약정금리
     , (N10.약정금리 / 100)                                                AS 연산1
     , N10.대출잔액
     , (N10.대출잔액 * (N10.약정금리 / 100))                               AS 연산2
     , (N10.이자계산기준일 - N10.대출실행일자)                              AS 연산3
     , ((N10.이자계산기준일 - N10.대출실행일자) / 365)                      AS 연산4
     , (((N10.이자계산기준일 - N10.대출실행일자) / 365) + 30 / 365)        AS 연산5
     , (N10.대출잔액 * (N10.약정금리 / 100))
       * (((N10.이자계산기준일 - N10.대출실행일자) / 365) + 30 / 365)      AS 연산6
     , TRUNC(
         (N10.대출잔액 * (N10.약정금리 / 100))
         * (((N10.이자계산기준일 - N10.대출실행일자) / 365) + 30 / 365)
       , 0)                                                                AS 이자금액
  FROM 월별대출이자산출 N10

4. 문제 발견: 그대로 번역한 쿼리에서 1원 오차 발생

Oracle 원천 SQL을 각 데이터베이스 문법에 맞게 번역하여 실행했습니다. 여기서는 BigQuery를 예시로 설명합니다.

번역 쿼리:

-- naive: 나눗셈을 수식 중간에 배치 (오차 발생 구간)
SELECT 대출관리번호
     , TRUNC(
         (CAST(대출잔액 AS BIGNUMERIC) * (CAST(약정금리 AS BIGNUMERIC) / CAST(100 AS BIGNUMERIC)))
         * ((CAST(DATE_DIFF(이자계산기준일, 대출실행일자, DAY) AS BIGNUMERIC) / CAST(365 AS BIGNUMERIC))
            + CAST(30 AS BIGNUMERIC) / CAST(365 AS BIGNUMERIC))
       , 0) AS 이자금액
  FROM `DM.월별대출이자산출`
 ORDER BY 대출관리번호

4.1 DB별 오차 발생 사례

10만 건 테스트에서 각 데이터베이스별로 확인된 번역 쿼리 오차입니다. PostgreSQL을 제외한 모든 데이터베이스에서 오차가 발생했습니다. 해결 방법과 최적화 방안은 6장과 7장에 정리하였습니다.

Spanner는 ROUND_HALF_UP 정책 특성상 +1원 상향 오차도 발생합니다. Presto와 Trino는 나눗셈 스케일 규칙이 엄격해 거의 대부분의 케이스에서 오차가 발생합니다.

4.2 오차가 집중되는 케이스만 골라 테스트

BigQuery BIGNUMERIC의 scale=38 반올림을 Python으로 에뮬레이션하여, 참값이 정수 경계에 정확히 걸리는 케이스만 추출해 5,003건을 테스트한 결과:

• 번역 쿼리 오차율: 47.43% (5,003건 중 2,373건에서 1원 하향 오차)
• 최적화 쿼리 오차율: 0.00% (0건 오차, 전건 정합)

중간 나눗셈의 반올림 오차가 누적되어 최종값이 정수 경계 아래로 내려갈 때 TRUNC가 1원 하향 오차를 만들어냅니다.

5. 원인: 데이터베이스별 수치 연산 아키텍처 차이

5.1 플랫폼별 정밀도 처리 방식 비교

대출 이자 수식의 핵심은 30 / 365 나눗셈입니다. 이 값은 무한 순환소수입니다:

각 데이터베이스는 이 무한소수를 처리하는 방식이 다릅니다.

Oracle NUMBER: 가변 길이 십진 연산

Oracle NUMBER 타입은 1바이트 지수부와 최대 20바이트 가수부로 구성된 가변 길이 Base-100 인코딩을 사용하며, 최대 38자리 십진 정밀도를 지원합니다. OCI 헤더에 정의된 OCINumber 구조체는 22바이트입니다.

/* Oracle OCI Number Type (oci.h) */
struct OCINumber {
    ub1 OCINumberData[22];
};

Oracle은 연산 단계마다 결과를 고정 스케일로 강제 정규화하지 않습니다. 중간 나눗셈에서 소수 자릿수가 조기에 잘리지 않기 때문에, 번역 쿼리로도 오차가 발생하지 않습니다. 10만 건 테스트에서 단 1건의 오차도 없었습니다.

• Oracle Database Concepts: Numeric Data Types

BigQuery BIGNUMERIC: scale=38 단계별 정규화

BIGNUMERIC은 소수점 이하 38자리 고정 소수점입니다. 연산 단계마다 결과를 38자리로 강제 정규화합니다:

참값이 정수 경계에 걸릴 때, 중간 단계의 반올림 오차가 누적되어 최종값이 진짜 정수보다 미세하게 낮아지면 TRUNC에서 1원 하향 오차가 됩니다.

• BigQuery NUMERIC/BIGNUMERIC 타입

Spanner NUMERIC: scale=9, ROUND_HALF_UP

NUMERIC은 소수점 이하 9자리로 고정되며 반올림(ROUND_HALF_UP)을 적용합니다. 절사 방향이 일정하지 않아 오차가 +1원 또는 -1원 양방향으로 발생합니다.

• Spanner NUMERIC 타입

PostgreSQL NUMERIC: 임의 정밀도 (Oracle과 동일)

연산 중 자릿수가 동적으로 확장되는 임의 정밀도(Arbitrary Precision)를 지원합니다. Oracle과 동일하게 별도 보정 없이도 오차가 발생하지 않습니다.

• PostgreSQL Numeric Types

MySQL DECIMAL: div_precision_increment 한계

나눗셈 정밀도가 시스템 변수 div_precision_increment(기본값: 4자리 추가)에 의해 제한됩니다. 이 값은 MySQL 설정에 따라 달라질 수 있으며, 이 테스트는 기본값(4) 환경에서 수행했습니다.

• MySQL Fixed-Point Types

Presto / Trino DECIMAL: max(s1, s2) 엄격 적용

ANSI SQL 나눗셈 스케일 규칙(max(s1, s2))을 엄격하게 적용하여 중간 나눗셈 결과의 소수 자릿수가 조기에 심각하게 축소됩니다. Presto는 번역 쿼리 기준 4.58% 일치율에 그칩니다.

• Trino DECIMAL
• Presto DECIMAL

플랫폼별 수치 처리 아키텍처를 정리하면 다음과 같습니다.

graph TD
    Input["수치 리터럴 입력 (예: 30/365)"] --> Oracle["Oracle NUMBER"]
    Input --> Binary["FLOAT / double (IEEE 754)"]
    Input --> Decimal["DECIMAL / NUMERIC"]

    Oracle --> OraclePhys["가변 길이 100진법 인코딩 (최대 22바이트)"]
    Binary --> BinaryPhys["고정 길이 2진법 인코딩 (8바이트)"]
    Decimal --> DecimalPhys["정수/소수부 분리 고정 인코딩 (선언 자릿수)"]

    OraclePhys --> Software["연산 중 고정 스케일 강제 정규화 없음"]
    BinaryPhys --> FPU["CPU FPU 하드웨어 병렬 연산"]
    DecimalPhys --> Premature["사칙연산 단계별 강제 스케일 정제"]

    Software --> OracleResult["중간 자릿수 유실 없는 정합성 보존"]
    FPU --> BinaryResult["2진 무한소수화 — 가수부 누적 오차"]
    Premature --> DecimalResult["나눗셈 중간 연산 시 소수 하위 잘림"]

5.2 Goldberg 이론이 설명하는 것, 설명 못하는 것

지금까지 각 데이터베이스가 소수를 서로 다른 방식으로 처리한다는 것을 봤습니다. 이 오차를 짚어볼 때 컴퓨터 과학에서 가장 많이 인용되는 논문 하나를 빼놓을 수 없습니다.

Goldberg, D. (1991). What Every Computer Scientist Should Know About Floating-Point Arithmetic. ACM Computing Surveys, 23(1), 5–48.
DOI: 10.1145/103162.103163
전문 보기

Goldberg의 1991년 논문은 IEEE 754 이진 부동소수점 연산의 수학적 토대를 제시합니다. 반올림 오차(Rounding Error), 가드 디지트(Guard Digits), 유효자리 소실(Catastrophic Cancellation)을 단일 코어 직렬 FPU 환경에서 정밀하게 증명했습니다.

FLOAT64 타입으로 연산할 때 발생하는 오차는 이 이론으로 직접 설명됩니다. 0.5나 14.6 같은 십진 소수는 이진수로 정확하게 표현할 수 없어 미세한 근사 오차가 생기고, 연산이 누적될수록 커집니다. 5.3절에서 다루는 UNION ALL 정밀도 손실가 대표적입니다 — 고정소수점 컬럼이 FLOAT64로 강제 변환되는 순간, 바로 이 이진 근사 오차가 개입합니다.

그런데 우리가 마주친 주요 오차는 FLOAT64가 아니라 BIGNUMERIC이나 NUMERIC 같은 고정소수점 타입에서 발생했습니다. 이 타입들은 이진 부동소수점을 쓰지 않으므로 Goldberg 이론의 적용 범위 밖입니다. 우리가 테스트한 환경은 Goldberg가 상정한 환경과 구조적으로 다릅니다:

1. 고정소수점 라이브러리: BigQuery BIGNUMERIC, Spanner NUMERIC 등은 이진 부동소수점 대신 소프트웨어 에뮬레이션 십진 고정소수점 라이브러리를 사용합니다.
2. 조기 정규화(Premature Normalization): 분산 환경의 데이터 일관성을 위해 이항 연산 단계마다 결과를 고정 스케일(BigQuery scale=38, Spanner scale=9)로 강제 조정합니다.
3. MPP 비결정론적 셔플: 부동소수점 덧셈은 교환법칙이 성립하나 $(A + B) + C \neq A + (B + C)$ 결합법칙이 성립하지 않습니다. 분산 집계 순서가 매 실행마다 달라지면 결과도 달라집니다.
4. CBO 대수적 변환: 비용 기반 옵티마이저가 $A \times B + A \times C$를 $A \times (B + C)$로 내부 치환할 때, 유한 정밀도 환경에서는 수치 경로가 달라집니다.

Goldberg 이론은 FLOAT64 오차를 설명하는 데 유효합니다. 다만 고정소수점 타입의 정규화 오차는 현대 분산 데이터베이스 환경에 맞는 별도의 관점이 필요합니다.

5.3 UNION ALL에서 정밀도가 희생되는 이유

고정소수점과 부동소수점을 UNION ALL로 합치면 부동소수점이 공통 상위 타입이 됩니다. BigQuery를 예시로 들면, BIGNUMERIC과 FLOAT64를 병합할 때 표현 범위가 넓은 FLOAT64를 슈퍼타입으로 결정합니다.

SQL 표준은 UNION ALL 결과 타입을 “공통 상위 타입(Supertype)”으로 결정하도록 규정합니다. 대부분의 데이터베이스는 표현 정밀도보다 표현 범위를 우선하기 때문에, 고정소수점과 부동소수점이 섞이면 부동소수점이 슈퍼타입이 됩니다. Oracle의 FLOAT 타입이 유일한 예외입니다 — FLOAT은 NUMBER의 서브타입이라 정밀도 손실이 발생하지 않습니다. 단, Oracle에도 진짜 IEEE 754 타입인 BINARY_DOUBLE이 있으며, 이 경우 다른 DB와 동일하게 정밀도가 손실됩니다.

Oracle이 이런 동작을 보이는 근본 이유 중 하나는 숫자 리터럴의 기본 타입입니다. Oracle은 정수든 소수든 모든 숫자 리터럴을 NUMBER로 처리합니다. 반면 다른 DB들은 소수 리터럴을 이진 부동소수점으로 파싱합니다.

Oracle에서는 어떤 숫자 리터럴을 써도 NUMBER 계열이라 UNION ALL에서 정밀도가 유지됩니다. BigQuery에서 1.0을 명시적 캐스팅 없이 쓰면 FLOAT64가 개입해 정밀도가 손실되는 것과 대조됩니다.

정밀도(Precision)와 범위(Range): 두 개념은 다릅니다.

• 정밀도: 소수점 몇 자리까지 정확하게 표현하는가. 고정소수점(BIGNUMERIC, DECIMAL, NUMERIC)이 훨씬 높습니다.
• 범위: 얼마나 큰 숫자까지 표현할 수 있는가. 부동소수점(FLOAT64, DOUBLE, DOUBLE PRECISION)이 훨씬 넓습니다.

데이터베이스	고정소수점 타입 / 최대 범위	비교 타입 (부동소수점)	비교 타입 최대 범위
Oracle	NUMBER / ≈ 10¹²⁶	FLOAT (NUMBER 서브타입, 십진수 저장)	≈ 10¹²⁶ → 정밀도 유지
Oracle	NUMBER / ≈ 10¹²⁶	BINARY_DOUBLE (IEEE 754, 이진수 저장)	≈ 10³⁰⁸ → 정밀도 손실
BigQuery	BIGNUMERIC / ≈ 10³⁸	FLOAT64 (IEEE 754, 이진수 저장)	≈ 10³⁰⁸ → 정밀도 손실
PostgreSQL	NUMERIC(38,22) / ≈ 10¹⁶	DOUBLE PRECISION (IEEE 754, 이진수 저장)	≈ 10³⁰⁸ → 정밀도 손실
MySQL	DECIMAL(38,22) / ≈ 10¹⁶	DOUBLE (IEEE 754, 이진수 저장)	≈ 10³⁰⁸ → 정밀도 손실
Presto / Trino	DECIMAL(38,22) / ≈ 10¹⁶	DOUBLE (IEEE 754, 이진수 저장)	≈ 10³⁰⁸ → 정밀도 손실

Oracle의 FLOAT는 다른 DB의 DOUBLE/FLOAT64와 다릅니다. Oracle 공식 문서는 이를 명확히 정의합니다:

“The FLOAT data type is a subtype of the NUMBER data type.”
“A FLOAT value is represented internally as NUMBER.”
— Oracle Database SQL Language Reference

즉, Oracle FLOAT는 IEEE 754 이진 부동소수점이 아니라 NUMBER의 서브타입으로, 내부적으로 NUMBER와 동일한 십진수 방식으로 저장됩니다. 범위도 NUMBER와 같아 사실상 같은 계열이기 때문에 UNION ALL 시 NUMBER로 유지됩니다.

Oracle에서 진짜 IEEE 754 이진 부동소수점이 필요하다면 BINARY_FLOAT(32비트)나 BINARY_DOUBLE(64비트)을 사용합니다. 이 타입들은 다른 DB의 DOUBLE과 동일한 이진 저장 방식입니다.

이 슈퍼타입 결정 규칙은 시스템 설정으로 변경할 수 없습니다. SQL 컴파일러에 하드코딩된 동작이기 때문에, 유일한 방어 수단은 명시적 캐스팅뿐입니다.

테스트 데이터: 123456789012345.6789012345678901234567 (소수부 22자리)와 1.0을 UNION ALL로 병합.

이 현상이 특히 위험한 이유는 SQL 컴파일 타임에 조용히 발생한다는 점입니다. 런타임 오류가 아니기 때문에 결과값이 그냥 틀린 값으로 반환됩니다.

실무에서 이 문제가 자주 발생하는 세 가지 상황:

1. UNION ALL로 브랜치 병합: 한 브랜치에 소수 리터럴(1.0, 0.5 등)이 포함되면 그 브랜치 전체가 FLOAT64로 추론됩니다. UNION ALL로 합쳐지는 순간 나머지 브랜치의 BIGNUMERIC 컬럼도 FLOAT64로 강제 정밀도가 손실됩니다.
2. CTE 타입 추론: WITH temp AS (SELECT 대출잔액 / 365.0 + 0.5 AS ratio ...) 소수 리터럴이 섞인 CTE는 결과 타입이 FLOAT64로 추론되어, 이후 이 CTE를 참조하는 모든 연산이 부동소수점 영역에서 진행됩니다.
3. 혼합 타입 산술: BIGNUMERIC 컬럼에 명시적 CAST 없이 소수 리터럴을 더하거나 곱하면 BigQuery는 컴파일 오류(No matching signature for operator)를 내거나, 조용히 FLOAT64로 변환합니다.

모든 경우의 해결책은 같습니다. 수식에 등장하는 모든 수치 요소를 동일한 고정소수점 타입으로 명시적으로 캐스팅합니다.

-- BigQuery: 모든 브랜치를 BIGNUMERIC으로 통일
SELECT CAST('123456789012345.6789012345678901234567' AS BIGNUMERIC) AS val
UNION ALL
SELECT CAST(1.0 AS BIGNUMERIC) AS val;
-- 결과: 123456789012345.6789012345678901234567 (100% 보존)

DB별 실증 쿼리

각 데이터베이스에서 정밀도 손실을 직접 확인하고 해결하는 방법입니다.

BigQuery : 쿼리 실행 결과로 정밀도 손실 확인

-- 정밀도 손실: BIGNUMERIC + FLOAT64 → FLOAT64
SELECT CAST('123456789012345.6789012345678901234567' AS BIGNUMERIC) AS val
UNION ALL
SELECT CAST(1.0 AS FLOAT64) AS val;

+------------------------+
|          val           |
+------------------------+
| 1.2345678901234567e+14 |   ← 과학적 표기법, 20자리 유실
|                    1.0 |
+------------------------+

-- 해결: 모든 브랜치를 BIGNUMERIC으로 통일
SELECT CAST('123456789012345.6789012345678901234567' AS BIGNUMERIC) AS val
UNION ALL
SELECT CAST(1.0 AS BIGNUMERIC) AS val;

+----------------------------------------+
|                  val                   |
+----------------------------------------+
| 123456789012345.6789012345678901234567 |   ← 100% 보존
|                                    1.0 |
+----------------------------------------+

PostgreSQL : pg_typeof()로 타입 확인

-- 정밀도 손실: NUMERIC + DOUBLE PRECISION → DOUBLE PRECISION
SELECT pg_typeof(val), val
FROM (
  SELECT CAST('123456789012345.6789012345678901234567' AS NUMERIC(38,22)) AS val
  UNION ALL
  SELECT CAST(1.0 AS DOUBLE PRECISION) AS val
) q;

    pg_typeof     |        val
------------------+--------------------
 double precision | 123456789012345.67   ← 20자리 유실
 double precision |                  1

-- 해결: 모든 브랜치를 NUMERIC으로 통일
SELECT pg_typeof(val), val
FROM (
  SELECT CAST('123456789012345.6789012345678901234567' AS NUMERIC(38,22)) AS val
  UNION ALL
  SELECT CAST(1.0 AS NUMERIC(38,22)) AS val
) q;

 pg_typeof |                  val
-----------+----------------------------------------
 numeric   | 123456789012345.6789012345678901234567  ← 100% 보존
 numeric   |           1.00000000000000000000

MySQL : DESCRIBE로 임시 테이블 스키마 확인

-- 정밀도 손실: DECIMAL + DOUBLE → DOUBLE
CREATE TEMPORARY TABLE temp_union AS
SELECT CAST('123456789012345.6789012345678901234567' AS DECIMAL(38,22)) AS val
UNION ALL
SELECT CAST(1.0 AS DOUBLE) AS val;

DESCRIBE temp_union;

+-------+--------+------+
| Field | Type   | Null |
+-------+--------+------+
| val   | double | NO   |   ← DOUBLE로 변환 (정밀도 손실)
+-------+--------+------+

-- 해결: 모든 브랜치를 DECIMAL(38,22)로 통일
CREATE TEMPORARY TABLE temp_union_safe AS
SELECT CAST('123456789012345.6789012345678901234567' AS DECIMAL(38,22)) AS val
UNION ALL
SELECT CAST(1.0 AS DECIMAL(38,22)) AS val;

DESCRIBE temp_union_safe;

+-------+----------------+------+
| Field | Type           | Null |
+-------+----------------+------+
| val   | decimal(38,22) | NO   |   ← 고정소수점 유지
+-------+----------------+------+

Presto / Trino : typeof()로 결과 타입 확인

-- 정밀도 손실: DECIMAL + DOUBLE → DOUBLE
SELECT typeof(val), val
FROM (
  SELECT CAST('123456789012345.6789012345678901234567' AS DECIMAL(38,22)) AS val
  UNION ALL
  SELECT CAST(1.0 AS DOUBLE) AS val
);

  _col0  |         _col1
---------+------------------------
 double  | 1.2345678901234567E14   ← 과학적 표기법, 20자리 유실
 double  | 1.0

-- 해결: 모든 브랜치를 DECIMAL(38,22)로 통일
SELECT typeof(val), val
FROM (
  SELECT CAST('123456789012345.6789012345678901234567' AS DECIMAL(38,22)) AS val
  UNION ALL
  SELECT CAST(1.0 AS DECIMAL(38,22)) AS val
);

     _col0      |                  _col1
----------------+----------------------------------------
 decimal(38,22) | 123456789012345.6789012345678901234567  ← 100% 보존
 decimal(38,22) | 1.0000000000000000000000

Oracle : BINARY_DOUBLE(IEEE 754)과 병합 시 정밀도 손실

Oracle FLOAT은 NUMBER 서브타입이라 정밀도 손실이 없지만, 진짜 IEEE 754 타입인 BINARY_DOUBLE과 병합하면 동일하게 정밀도가 손실됩니다. 아래 두 쿼리를 비교하면 차이가 명확합니다.

아래 쿼리는 TO_CHAR(val)로 감쌌습니다. sqlplus 클라이언트가 BINARY_DOUBLE 값을 바로 출력하지 못하는 경우가 있어 문자열로 변환한 것이며, 실제 업무 쿼리에는 필요 없습니다.

-- NUMBER + FLOAT(NUMBER 서브타입) → NUMBER 유지
SELECT TO_CHAR(val) FROM (
  SELECT CAST('123456789012345.6789012345678901234567' AS NUMBER(38,22)) AS val FROM dual
  UNION ALL
  SELECT CAST(1.0 AS FLOAT) FROM dual
);

123456789012345.6789012345678901234567  ← 소수 22자리 완전 보존
1

-- NUMBER + BINARY_DOUBLE(IEEE 754) → BINARY_DOUBLE로 변환 (정밀도 손실)
-- (BINARY_DOUBLE 표시 제약으로 짧은 값 사용)
SELECT TO_CHAR(val) FROM (
  SELECT CAST(12345.6789 AS NUMBER(10,4)) AS val FROM dual
  UNION ALL
  SELECT CAST(1.0 AS BINARY_DOUBLE) FROM dual
);

1.2345678900000001E+004   ← 과학적 표기법, 이진 근사 오차 발생
1.0E+000

1.2345678900000001E+004는 실제 값 12345.6789가 IEEE 754 이진수로 저장되면서 12345.6789000000001...로 변환된 결과입니다. 12345.6789는 이진수로 정확하게 표현할 수 없어 끝 자리에 미세한 오차가 붙습니다.

-- 해결: BINARY_DOUBLE 대신 NUMBER 계열로 통일
SELECT TO_CHAR(val) FROM (
  SELECT CAST(12345.6789 AS NUMBER(10,4)) AS val FROM dual
  UNION ALL
  SELECT CAST(1.0 AS NUMBER(10,4)) FROM dual
);

12345.6789  ← 정확히 보존
1

Oracle이 슈퍼타입 결정에서 예외로 불리는 이유는 FLOAT이 NUMBER와 같은 계열이기 때문이며, BINARY_DOUBLE(IEEE 754)을 쓰면 Oracle도 동일하게 정밀도가 손실됩니다.

6. 해결: 두 가지 핵심 기법

문제는 두 가지입니다. 해결책도 두 가지입니다.

두 문제는 독립적으로 발생합니다. 후순위 나눗셈만 적용해도 UNION ALL에서 타입이 정밀도가 손실되면 다시 오차가 생깁니다. 두 기법을 함께 써야 완전히 방어됩니다.

6.1 후순위 나눗셈: 연산 중 소수점 유실 방지

아이디어는 단순합니다. 수식 중간의 나눗셈을 모두 없애고, 딱 한 번만 TRUNC 직전에 나누는 겁니다. 수학적으로는 기존 수식과 같지만, 중간에 소수점이 잘릴 일이 없습니다.

수학적 동치 증명

번역 쿼리 수식:

대수적 통분 : 나눗셈을 마지막으로 후순위 배치:

BigQuery 적용 SQL

-- optimized: 후순위 나눗셈 — 나눗셈 1회, TRUNC 직전 최종 단계에서만
SELECT 대출관리번호
     , TRUNC(
         (CAST(대출잔액 AS BIGNUMERIC)
          * CAST(약정금리 AS BIGNUMERIC)
          * (CAST(DATE_DIFF(이자계산기준일, 대출실행일자, DAY) AS BIGNUMERIC)
             + BIGNUMERIC '30'))
         / BIGNUMERIC '36500'
       , 0) AS 이자금액
  FROM `DM.월별대출이자산출`
 ORDER BY 대출관리번호

6.2 명시적 형변환: 타입 안전성 보장

올바른 수식 설계만으로는 충분하지 않습니다. SQL에서 리터럴 상수, 함수 반환값, UNION ALL 브랜치의 타입이 하나라도 FLOAT64나 DOUBLE이면 전체 연산 결과가 부동소수점으로 수렴합니다. 수식이 아무리 정교해도 타입이 정밀도가 손실되는 순간 오차가 다시 생깁니다.

리터럴 상수 처리

BigQuery SQL에서 30이나 36500 같은 정수 리터럴은 INT64로, 소수 리터럴 0.5는 FLOAT64로 자동 추론됩니다. BIGNUMERIC 컬럼과 다른 타입 리터럴을 섞어서 산술 연산하면 컴파일 타임에 이런 오류가 납니다:

No matching signature for operator * for argument types: BIGNUMERIC, FLOAT64

오류를 마주한 개발자가 빠지기 쉬운 함정이 있습니다. 오류 메시지를 없애려고 컬럼을 반대 방향으로 낮추는 것입니다.

-- 잘못된 해결: BIGNUMERIC을 FLOAT64로 낮춰서 오류를 없앰
CAST(대출잔액 AS FLOAT64) * 약정금리 * (경과일수 + 30.0) / 36500.0

오류는 사라지지만 결과가 더 나빠집니다. FLOAT64는 IEEE 754 이진 부동소수점이라 십진 소수를 정확하게 표현하지 못합니다. 30.0이나 36500.0처럼 단순해 보이는 값도 내부적으로 근사치로 저장됩니다. 이 상태에서 계산을 이어가면 오차가 연산마다 누적되어 최종 결과에서 원치 않는 차이가 발생합니다.

올바른 방향은 반대입니다. 리터럴을 BIGNUMERIC으로 올려서 수식 전체를 고정소수점 영역에서 유지합니다.

-- 올바른 해결: 리터럴을 BIGNUMERIC으로 올림
CAST(대출잔액 AS BIGNUMERIC) * CAST(약정금리 AS BIGNUMERIC)
  * (CAST(경과일수 AS BIGNUMERIC) + BIGNUMERIC '30')
  / BIGNUMERIC '36500'

BIGNUMERIC '30' 처럼 프리픽스 리터럴 표기를 쓰면 CAST(30 AS BIGNUMERIC)과 동일하게 동작하면서 더 간결합니다.

UNION ALL 4단계 방어

Oracle에서 이식한 쿼리에 UNION ALL이 포함된 경우, 브랜치 하나의 타입 실수가 전체 결과셋을 망칩니다. 아래 4단계를 적용합니다.

Tier 1 : 모든 브랜치 수치 컬럼 명시적 형변환:

SELECT CAST(대출잔액 AS BIGNUMERIC) AS 총액 FROM 대출_브랜치A
UNION ALL
SELECT CAST(대출잔액 AS BIGNUMERIC) AS 총액 FROM 대출_브랜치B

Tier 2 : 리터럴 상수 BIGNUMERIC 기입:

SELECT BIGNUMERIC '30' AS 기산가산일수

Tier 3 : 수식 피연산자 사전 업캐스팅:

SELECT CAST(DATE_DIFF(이자계산기준일, 대출실행일자, DAY) AS BIGNUMERIC)
       / CAST(365 AS BIGNUMERIC) AS 일수비율

Tier 4 : 마이그레이션 린터: UNION ALL 구조가 있는 쿼리는 빌드 파이프라인에서 수치 컬럼 타입을 전수 테스트합니다. 배포 전에 타입 불일치를 잡아내는 게 운영 중에 오차를 발견하는 것보다 훨씬 낫습니다.

7. 6종 데이터베이스 교차 테스트 결과

7.1 테스트 자동화 스크립트

Oracle vs. BigQuery 대조 (compare_results.py):

import csv, subprocess, json, os

def run_bq_query(query):
    temp_file = "temp_query.sql"
    with open(temp_file, "w", encoding="utf-8") as f:
        f.write(query)
    cmd = f"bq query --use_legacy_sql=false --max_rows=150000 --format=json < {temp_file}"
    res = subprocess.run(cmd, shell=True, capture_output=True, text=True)
    os.remove(temp_file)
    if res.returncode != 0:
        print("Query failed:", res.stderr)
        return []
    return json.loads(res.stdout)

def main():
    oracle_rows = {}
    with open("oracle_data.csv", "r", encoding="utf-8") as fin:
        reader = csv.DictReader(fin)
        for row in reader:
            oracle_rows[row['대출관리번호']] = {
                'oracle_fee': int(row['oracle_이자금액'])
            }

    query_naive = """
    SELECT 대출관리번호,
           TRUNC(
             (CAST(대출잔액 AS BIGNUMERIC) * (CAST(약정금리 AS BIGNUMERIC) / CAST(100 AS BIGNUMERIC)))
             * ((CAST(DATE_DIFF(이자계산기준일, 대출실행일자, DAY) AS BIGNUMERIC) / CAST(365 AS BIGNUMERIC))
                + CAST(30 AS BIGNUMERIC) / CAST(365 AS BIGNUMERIC))
           , 0) AS 이자금액_naive
      FROM `DM.월별대출이자산출`
     ORDER BY 대출관리번호
    """

    query_optimized = """
    SELECT 대출관리번호,
           TRUNC(
             (CAST(대출잔액 AS BIGNUMERIC)
              * CAST(약정금리 AS BIGNUMERIC)
              * (CAST(DATE_DIFF(이자계산기준일, 대출실행일자, DAY) AS BIGNUMERIC) + BIGNUMERIC '30'))
             / BIGNUMERIC '36500'
           , 0) AS 이자금액_optimized
      FROM `DM.월별대출이자산출`
     ORDER BY 대출관리번호
    """

    print("Running naive query...")
    res_naive = {r['대출관리번호']: int(float(r['이자금액_naive'])) for r in run_bq_query(query_naive)}
    print("Running optimized query...")
    res_opt = {r['대출관리번호']: int(float(r['이자금액_optimized'])) for r in run_bq_query(query_optimized)}

    diff_naive = diff_opt = 0
    for lid, data in oracle_rows.items():
        if data['oracle_fee'] != res_naive.get(lid, -1): diff_naive += 1
        if data['oracle_fee'] != res_opt.get(lid, -1):  diff_opt += 1

    n = len(oracle_rows)
    print(f"\nTotal: {n:,}")
    print(f"naive      불일치: {diff_naive:,} / {n:,} ({diff_naive/n*100:.4f}%)")
    print(f"optimized  불일치: {diff_opt:,}  / {n:,} ({diff_opt/n*100:.4f}%)")

if __name__ == "__main__":
    main()

주의: bq CLI 기본 결과 출력 한계가 100건이므로 반드시 --max_rows=150000을 명시합니다.

정수 경계 시뮬레이션 (verify.py):

import decimal, math
from decimal import Decimal

decimal.getcontext().prec = 100

def bq_div(a, b):
    return (a / b).quantize(Decimal('1e-38'), rounding=decimal.ROUND_HALF_UP)

def run_naive(amount, rate, days):
    s1 = bq_div(rate, Decimal('100'))
    s2 = bq_div(days, Decimal('365'))
    s3 = s2 + bq_div(Decimal('30'), Decimal('365'))
    return int((amount * s1 * s3).quantize(Decimal('1'), rounding=decimal.ROUND_DOWN))

def run_optimized(amount, rate, days):
    return int(bq_div(amount * rate * (days + Decimal('30')), Decimal('36500'))
               .quantize(Decimal('1'), rounding=decimal.ROUND_DOWN))

def run_true(amount, rate, days):
    return amount * (rate / Decimal('100')) * ((days + Decimal('30')) / Decimal('365'))

def main():
    tested = naive_err = opt_err = 0
    for d in range(1, 366):
        factor = d + 30
        for r_int in range(50, 240, 5):
            rate_dec = Decimal(r_int) / Decimal('10')
            g = math.gcd(r_int * factor, 3650000)
            base_A = 3650000 // g
            for k in range(1, 5):
                amt = Decimal(base_A * k * 1000)
                if amt > 100_000_000: continue
                true_val = run_true(amt, rate_dec, Decimal(d))
                if true_val % 1 != 0: continue
                tested += 1
                if run_naive(amt, rate_dec, Decimal(d)) != int(true_val): naive_err += 1
                if run_optimized(amt, rate_dec, Decimal(d)) != int(true_val): opt_err += 1
        if tested >= 5000: break

    print(f"정수 경계 케이스: {tested}건")
    print(f"naive      오차율: {naive_err}/{tested} ({naive_err/tested*100:.2f}%)")
    print(f"optimized  오차율: {opt_err}/{tested}  ({opt_err/tested*100:.2f}%)")

if __name__ == "__main__":
    main()

7.2 BigQuery 10만 건 테스트 결과

• 번역 쿼리 BIGNUMERIC 불일치: 1건 (일치율 99.9990%)
• 최적화 쿼리 불일치: 0건 (일치율 100%)

번역 쿼리 불일치 사례:

7.3 Spanner 10만 건 테스트 결과

• 번역 쿼리 NUMERIC 불일치: 16건 (일치율 99.9840%)
• 최적화 쿼리 불일치: 0건 (일치율 100%)

Spanner는 ROUND_HALF_UP 정책으로 오차가 +1원 또는 -1원 양방향으로 발생합니다.

상향 오차 사례 (+1원):

-- Spanner naive SQL
SELECT TRUNC(
  (CAST(2193667 AS NUMERIC) * (CAST(17.1 AS NUMERIC) / CAST(100 AS NUMERIC)))
  * ((CAST(67 AS NUMERIC) / CAST(365 AS NUMERIC)) + CAST(30 AS NUMERIC) / CAST(365 AS NUMERIC))
)
-- 결과: 73,218원 (Oracle: 73,217원, +1원 격차)

-- Spanner optimized SQL (후순위 나눗셈)
SELECT TRUNC(
  CAST(2193667 AS NUMERIC) * CAST(17.1 AS NUMERIC) * (CAST(67 AS NUMERIC) + CAST(30 AS NUMERIC))
  / CAST(36500 AS NUMERIC)
)
-- 결과: 73,217원 ✅ (정합)

7.4 MySQL / Presto / Trino 결과 요약

Presto와 Trino는 번역 쿼리에서 max(s1,s2) 나눗셈 스케일 규칙으로 인해 사실상 대부분의 케이스에서 오차가 발생합니다. 후순위 나눗셈 적용 후 전건 정합을 달성했습니다.

7.5 6종 데이터베이스 종합 결과

후순위 나눗셈과 명시적 형변환을 적용한 최적화 쿼리는 Oracle을 포함한 7종 데이터베이스 전체에서 단 1건의 오차도 없이 100% 정합성을 달성했습니다.

8. 프로덕션 방어 수칙

Oracle에서 이식한 정산 쿼리를 분산 데이터베이스 환경에서 안전하게 운영하기 위한 필수 체크리스트입니다.

후순위 나눗셈 : 연산 중 소수점 유실 방지

• 나눗셈은 항상 마지막 단계로 배치 : TRUNC 직전 단 1회만 수행
• 중간 나눗셈이 불가피한 경우: 분자·분모를 먼저 곱셈으로 통합 후 단일 나눗셈으로 대체

명시적 형변환 : 정밀도 손실 방지

• 모든 수치 컬럼에 명시적 CAST(col AS BIGNUMERIC) 선언
• 소수 리터럴은 BIGNUMERIC '30' 프리픽스 또는 CAST(30 AS BIGNUMERIC) 형태로 기입
• FLOAT64 / DOUBLE 타입과의 혼합 연산 금지
• CTE 내 중간 결과 컬럼에도 타입 명시 (FLOAT64로 추론되지 않도록)

UNION ALL : 슈퍼정밀도 손실 방지

• 모든 브랜치의 수치 컬럼 타입을 동일한 고정소수점 타입으로 명시적 통일 (Tier 1)
• 상수 리터럴 브랜치도 예외 없이 타입 프리픽스 적용 (Tier 2)
• 수식 피연산자 사전 업캐스팅 (Tier 3)
• 마이그레이션 린터로 빌드 타임 사전 테스트 (Tier 4)

테스트 파이프라인

• bq CLI 대량 쿼리 시 --max_rows=150000 명시 (기본값 100건 제한 우회)
• 정수 경계 케이스 전용 시뮬레이션(verify.py) 마이그레이션 전 실행
• Oracle 원천 결과와 1:1 전수 대조 (compare_results.py) 실행

9. 결론

후순위 나눗셈과 명시적 형변환, 두 기법을 함께 적용해 6종 데이터베이스 전체에서 100% 정합성을 달성했습니다.

정리하면 이렇습니다:

수학적으로 동치인 수식이라도, 연산 순서와 타입 관리가 정밀도를 결정한다.

Oracle에서 오차가 발생하지 않았던 이유는 운이 아닙니다. Oracle NUMBER 타입이 연산 단계마다 소수 자릿수를 고정 스케일로 강제 정규화하지 않기 때문입니다.
반면 BigQuery, Spanner, MySQL, Presto, Trino는 연산 단계마다 고정 스케일 정규화를 강제 적용하므로, 중간 나눗셈이 있는 수식은 정수 경계 케이스에서 오차를 유발합니다. 여기에 UNION ALL이나 소수 리터럴이 섞이면 타입이 조용히 정밀도가 손실되어 오차가 재발합니다.

플랫폼을 바꿀 때는 수식과 타입을 함께 검토해야 합니다. / 365, / 12, / 100처럼 무한 순환소수를 만드는 나눗셈이 수식 중간에 있다면 후순위 나눗셈을 적용하고, 모든 수치 컬럼과 리터럴에 명시적 CAST를 선언해야 합니다. 어느 하나만으로는 절반만 방어한 겁니다.

GAN(Generative Adversarial Network)에서 빌려온 아이디어입니다. Generator가 만들고, Discriminator가 걸러내고, 반복하면 품질이 올라가는 구조를 AI 코드 생성에 적용해봤습니다. Gemini가 평가 기준(Sprint Contract)을 직접 작성하고, Claude가 그걸 보고 구현하고, Gemini가 다시 채점합니다. Grade A가 나올 때까지.

GitHub에서 보기 → hajekim/claude-gan

Gemini CLI (Evaluator — 네이티브 추론)
  │
  ├─ 1. Sprint Contract(JSON DoD)를 자체 추론으로 직접 작성
  ├─ 2. claude_generate MCP 도구 호출 ──▶ Claude 4.6 Sonnet (Vertex AI)
  ├─ 3. 반환된 코드를 계약 기준으로 직접 평가
  └─ 4. Grade A 달성까지 구체적 피드백으로 반복

핵심은 Claude를 서브프로세스로 띄우지 않고 MCP 도구로 등록한다는 점입니다. Gemini CLI가 세션을 주도하면서 필요할 때 claude_generate를 호출하는 방식이라, 루프 전체가 Gemini CLI 안에서 돌아갑니다.

사전 준비

• Google Cloud Project (Vertex AI API 활성화, global 리전에서 Claude 4.6 Sonnet 접근 권한)
• gcloud auth application-default login 완료
• Gemini CLI 설치 및 인증 완료
• Python 3.10+

설치

1. 리포지토리 클론

git clone https://github.com/hajekim/claude-gan.git
cd claude-gan

2. Python 의존성 설치

pip install -r requirements.txt

Anthropic Vertex AI SDK, FastMCP, python-dotenv, pytest가 들어있습니다.

3. MCP 서버 전역 등록

~/.gemini/settings.json의 mcpServers에 추가합니다:

{
  "mcpServers": {
    "claude-gan": {
      "command": "/path/to/python3",
      "args": ["/절대경로/claude-gan/src/mcp_server.py"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-gcp-project-id",
        "GOOGLE_CLOUD_LOCATION": "global",
        "PYTHONPATH": "/절대경로/claude-gan"
      }
    }
  }
}

python3 경로는 which python3로, /절대경로/claude-gan는 클론한 실제 경로로 교체합니다.

4. 기존 GEMINI.md에 GAN 지시문 추가

~/.gemini/GEMINI.md를 덮어쓰지 말고, 아래 두 항목을 기존 내용에 추가합니다. 이미 공들여 작성한 GEMINI.md가 있을 테니까요.

MCP 서버 목록에 추가:

- **claude-gan**: GAN 루프 코드 생성 전용. `claude_generate(task, contract, feedback)`으로
  Claude 4.6 Sonnet (Vertex AI)에게 구현을 위임한다.
  `save_artifact(content, filename)`, `save_progress(sprint_id, status, grade)`로 결과를 저장한다.

실행 워크플로우(ACT 단계 또는 GAN 루프 섹션)에 추가:

코드 생성이 필요한 경우, 직접 작성하지 않고 claude-gan MCP에 위임한다:
1. 작업 요구사항을 분석하여 Sprint Contract(JSON DoD)를 직접 작성한다.
2. claude_generate(task, contract, feedback="")를 호출하여 Claude의 구현을 받는다.
3. 반환된 코드를 Skeptical Judge로서 엄격하게 평가한다 (Gemini = Evaluator).
4. Grade B/C이면 구체적인 피드백으로 claude_generate를 재호출한다. 최대 3회.
5. Grade A 달성 시 save_artifact와 save_progress로 결과를 저장한다.
코드 생성이 아닌 작업(기존 코드 수정, 설정 변경 등)은 직접 처리한다.

Gemini CLI를 재시작하고 mcp list로 claude-gan가 Connected 상태인지 확인합니다.

실제로 쓰면 이렇게 됩니다

Python으로 가위바위보 게임을 만들어줘. 점수 기록 기능도 포함해줘.

Gemini가 먼저 Sprint Contract를 잡습니다:

✦ 가위바위보 게임과 점수 기록 기능을 구현하기 위한 개발 계획 PLAN.md를 작성했습니다.
  GAN 루프(Gemini가 평가자, Claude가 생성자)를 사용하여 PEP 8 표준을 준수하고
  기능적으로 완벽한 코드를 작성할 예정입니다.
  해당 계획에 동의하신다면, 상세 작업을 스프린트로 나누는 DEFINE.md를 작성하고
  구현을 시작하겠습니다. 계획을 진행할까요?

  PLAN.md 내용 요약:
   - 목표: 사용자 입력을 받아 컴퓨터와 대결하고 승/무/패 점수를 기록하는 Python 가위바위보 게임 개발.
   - 전략: Claude 4.6 Sonnet(claude_generate)을 통해 코드를 생성하고, Gemini가 이를 검증하는 GAN 루프 적용.
   - 검증 계약: 정확한 승패 로직, 점수 기록/표시, 예외 처리 및 PEP 8 준수 여부 확인.
   - 등급 기준: 완벽한 기능과 스타일(Grade A)을 목표로 함.

승인하면 Claude가 구현하고, Gemini가 채점하는 루프가 돌고, 최종 결과를 받습니다:

✦ GAN 루프(Claude Generator + Gemini Evaluator)를 통해 고품질의 가위바위보 게임 구현을 완료했습니다.

  구현 결과: rps_game.py
   - 핵심 기능:
       - 사용자 입력(rock, paper, scissors)과 컴퓨터의 무작위 선택 대결.
       - 매 라운드 종료 후 현재 점수(승, 패, 무) 실시간 표시.
       - quit 입력 시 게임이 종료되며 전체 세션의 최종 성적 요약 출력.
       - 잘못된 입력에 대한 예외 처리 및 재입력 요청.

  GAN 루프 검증 결과
   - Generator (Claude 4.6 Sonnet): 명확한 함수 구조와 가독성 높은 코드 생성.
   - Evaluator (Gemini): PEP 8 준수 여부, 점수 기록 로직의 정확성, 예외 처리 완성도를
     검토하여 Grade A로 최종 승인.

MCP 도구 목록

프로젝트 구조

claude-gan/
├── src/
│   ├── mcp_server.py                # FastMCP 서버 (stdio transport)
│   └── tools/
│       └── claude_tool.py           # Claude Vertex AI 호출 핵심 로직
├── tests/
│   └── test_claude_tool.py          # 단위 테스트
├── state/
│   └── progress.json                # 스프린트 상태 (런타임, gitignored)
├── artifacts/                       # 생성 코드 출력 (런타임, gitignored)
├── GEMINI.md                        # Gemini CLI용 Evaluator 지시문
├── gemini-extension.json.template   # Extension 매니페스트 템플릿
└── requirements.txt

직접 써보면서 느낀 건, 모델 하나한테 생성과 평가를 동시에 맡기는 것보다 역할을 분리했을 때 결과물 품질이 체감상 다릅니다. 자기가 짠 코드를 자기가 검토하면 놓치는 게 많은 건 사람도 마찬가지니까요.

Vertex AI Claude 접근 권한이 있는 GCP 프로젝트가 필요하다는 진입장벽이 있긴 합니다만, Gemini CLI를 이미 쓰고 있다면 설정 몇 줄로 바로 붙일 수 있습니다.

이런 문제들에 대한 검증된 해법이 에이전트 디자인 패턴(Agentic Design Patterns) 입니다. Antonio Gulli의 동명 저서(424페이지, 21챕터)를 기반으로 28개의 패턴을 Gemini CLI Extension으로 패키징했습니다.

무엇을 제공하는가

28개의 에이전트 스킬을 단일 Extension으로 설치하면, Gemini CLI가 사용자의 의도를 파악해 자동으로 관련 패턴 가이드를 불러옵니다. 코드 스켈레톤 생성, 패턴 추천, 코드 리뷰까지 하나의 도구에서 처리합니다.

설치

gemini extensions install https://github.com/hajekim/agentic-design-patterns-extension

설치 후 Gemini CLI를 재시작하면 28개의 스킬이 자동으로 활성화됩니다. 추가 설정은 필요하지 않습니다.

설치된 Extension 확인:

gemini extensions list

스킬 자동 활성화 — 어떻게 동작하는가

Gemini CLI는 세션 시작 시 모든 스킬의 name과 description을 색인합니다. 사용자의 요청이 스킬 설명과 의미적으로 매칭되면, 모델이 자율적으로 해당 스킬의 전체 내용을 로드합니다. 별도의 명령어 없이 자연어 요청만으로 패턴 가이드가 활성화됩니다.

한국어 요청 예시:

4개 언어(영어·한국어·일본어·중국어) 총 1,376개의 트리거 문구가 등록되어 있습니다.

슬래시 커맨드

/pattern-summary — 패턴 목록 탐색

28개 패턴 전체를 카테고리별로 한눈에 봅니다.

# 전체 28개 패턴 목록 (카테고리별 테이블)
/pattern-summary

# 특정 카테고리만 보기
/pattern-summary core
/pattern-summary reliability
/pattern-summary advanced

# 특정 패턴 상세 보기 (언제 쓰는지 + 관련 패턴 추천)
/pattern-summary planning
/pattern-summary rag

/gen-skeleton — 코드 스켈레톤 생성

패턴 이름을 인자로 넘기면 즉시 실행 가능한 Python 코드 스켈레톤을 생성합니다.

/gen-skeleton planning
/gen-skeleton rag
/gen-skeleton multi-agent-collaboration
/gen-skeleton exception-handling

생성되는 코드는 다음 규칙을 강제합니다:

• Gemini SDK: google-genai (import google.genai as genai)
• ADK: LlmAgent + Runner + InMemorySessionService
• 기본 모델: gemini-2.5-flash

스켈레톤은 Imports → Configuration → Core 패턴 구현 → Main 실행 블록 순서로 구성됩니다.

서브에이전트

@architect — 패턴 조합 추천

어떤 패턴을 써야 할지 모를 때, 문제를 설명하면 최적의 패턴 조합을 추천합니다.

@architect "피드백을 학습하는 고객 지원 봇을 만들고 싶어"
@architect "실시간 데이터를 분석해서 이상 탐지를 하는 에이전트 설계해줘"
@architect "여러 전문 에이전트가 협력해서 리포트를 작성하는 시스템 필요해"

출력 형식:

## Pattern Recommendation

Primary Pattern: `planning`
Supporting Patterns: `reflection`, `memory-management`

### Why This Combination
...

### Implementation Sequence
1. Start with `planning` — ...
2. Add `reflection` — ...

### Watch Out For
- ...

### Next Step
Run `/gen-skeleton planning` to generate the code skeleton.

@reviewer — 코드 패턴 컴플라이언스 검토

작성한 에이전트 코드를 붙여넣으면 패턴 구현 적합성과 SDK 사용 오류를 검토합니다.

@reviewer <코드 붙여넣기>

검토 항목:

출력 형식:

## Pattern Review: `rag`

### SDK Compliance
✅ Gemini SDK import correct
❌ ADK Runner: `InMemoryRunner` → use `Runner` + `InMemorySessionService`

### Pattern Implementation
✅ Retrieval step present before generation
❌ Source attribution missing

### Overall: NEEDS FIXES

MCP 서버 (스킬 검색)

Extension이 설치되면 mcp_server.py가 자동으로 MCP 서버로 등록됩니다. 모델이 직접 패턴을 검색하고 스킬 내용을 가져올 수 있으며, 대화 중 자연스럽게 호출됩니다.

list_patterns — 패턴 목록 조회

카테고리 없이 호출하면 28개 전체 목록을, 카테고리를 지정하면 해당 카테고리만 반환합니다.

# 전체 28개 목록 (카테고리별 그룹)
list_patterns()

# 특정 카테고리만
list_patterns("core")       → Core 7개 패턴
list_patterns("state")      → State Management 4개 패턴
list_patterns("reliability") → Reliability 3개 패턴
list_patterns("advanced")   → Advanced 7개 패턴
list_patterns("appendix")   → Appendix 7개 패턴

잘못된 카테고리를 입력하면 유효한 카테고리 목록을 안내합니다:

Unknown category 'xxx'. Valid categories: `core`, `state`, `reliability`, `advanced`, `appendix`.

get_skill — 스킬 전체 내용 조회

패턴 이름으로 해당 SKILL.md 전체를 반환합니다. 패턴의 정의, 트리거 문구, 구현 예제 코드를 모두 포함합니다.

get_skill("planning")
get_skill("rag")
get_skill("mcp-setup")
get_skill("multi-agent-collaboration")

오타나 불완전한 이름 입력 시 유사 패턴을 제안합니다:

# 입력: get_skill("plan")
Pattern 'plan' not found. Did you mean: `planning`?

# 입력: get_skill("memory")
Pattern 'memory' not found. Did you mean: `memory-management`?

패턴 이름을 전혀 모를 경우에는 list_patterns()로 전체 목록을 먼저 확인합니다.

search_skills — 키워드 검색

키워드가 포함된 스킬을 28개 전체에서 검색합니다. 매칭된 스킬 이름, 매칭 횟수, 첫 번째 매칭 줄 미리보기를 반환합니다.

search_skills("LangGraph")
search_skills("Thinking Budget")
search_skills("fallback")
search_skills("human approval")

출력 예시:

Found 'Thinking Budget' in 3 pattern(s):

`reasoning` (5 matches)
  → Thinking Budget controls how deeply the model reasons before responding...

`resource-aware` (3 matches)
  → Set Thinking Budget high when accuracy matters more than latency...

`appendix-reasoning-engines` (8 matches)
  → Thinking Budget is configured via thinking_config, not a separate model...

특정 기술(예: LangGraph, Chroma, Redis)이나 개념(예: retry, timeout, fallback)으로 검색해 관련 패턴을 빠르게 찾을 때 유용합니다.

권장 워크플로우

1. @architect로 패턴 추천받기
       ↓
2. /pattern-summary <패턴명>으로 상세 확인
       ↓
3. /gen-skeleton <패턴명>으로 코드 스켈레톤 생성
       ↓
4. 코드 작성
       ↓
5. @reviewer로 패턴 컴플라이언스 검토

모델 선택 가이드

Thinking Budget은 Flash와 Pro 모델에서 조절 가능한 추론 깊이 파라미터입니다. 대부분의 작업에서는 기본값(Dynamic)을 유지하면 모델이 자동으로 결정합니다.

플랫폼 호환성

Antigravity와 Claude Code에는 Skills-only 버전을 사용하세요.

Extension 관리

# 최신 버전으로 업데이트
gemini extensions update agentic-design-patterns

# 임시 비활성화 (제거 없이)
gemini extensions disable agentic-design-patterns

# 제거
gemini extensions uninstall agentic-design-patterns

Extension 구조

agentic-design-patterns/
├── gemini-extension.json      ← Extension 매니페스트
├── GEMINI.md                  ← 전역 컨텍스트 (28개 패턴 퀵레퍼런스, 모델 가이드)
├── mcp_server.py              ← 스킬 검색 MCP 서버
├── commands/
│   ├── gen-skeleton.toml      ← /gen-skeleton <패턴명>
│   └── pattern-summary.toml  ← /pattern-summary [필터]
├── agents/
│   ├── architect.md           ← @architect 서브에이전트
│   └── reviewer.md            ← @reviewer 서브에이전트
└── skills/                    ← 28개 스킬 정의
    ├── planning/SKILL.md
    ├── rag/SKILL.md
    └── ...

각 스킬은 DEFINE → PLAN → ACTION 워크플로우를 따르며, Google ADK, LangChain, LangGraph 구현 예제를 포함합니다.

설치 링크

• Extension (Gemini CLI용): hajekim/agentic-design-patterns-extension
• Skills-only (Antigravity / Claude Code용): hajekim/agentic-design-patterns-skills

현재 버전: v2.2.3

1. Agent Harness란 무엇인가

Agent Harness는 AI 모델(LLM)을 감싸는 인프라스트럭처 소프트웨어 시스템으로, 에이전트가 현실 세계에서 신뢰성 있게 작동할 수 있도록 도구 제공, 컨텍스트 관리, 안전 장치, 워크플로우 구조를 제공합니다. 핵심은 에이전트 자체(두뇌)가 아니라 에이전트가 동작하는 몸체(body) 라는 점입니다.

LangChain의 Harrison Chase는 AI 에이전트 생태계를 세 가지 계층으로 분류합니다:

Agent Harness는 이 중 가장 상위 레벨에 위치하며, 프레임워크 위에 구축되어 기본 프롬프트, 파일시스템 접근, 서브에이전트 관리, 도구 호출의 의견이 반영된(opinionated) 처리를 제공합니다. 자동차에 비유하면, 에이전트가 엔진이라면 하네스는 핸들·브레이크·내비게이션·연료 시스템을 포함한 자동차 전체입니다.

Agent Harness의 핵심 기능

• 도구 통합 레이어(Tool Integration): 웹 검색, 코드 실행, DB 쿼리, 이미지 생성 등 외부 도구를 LLM에 연결하고, 모델의 도구 호출을 감지·실행·결과 반환
• 컨텍스트 관리 & 메모리: 세션 내 대화 이력, 컨텍스트 압축(compaction), 작업 로그 관리
• 오케스트레이션: 사용자 목표를 하위 작업으로 분해하고, 각 단계에서 모델에 필요한 컨텍스트와 도구를 제공
• 신뢰성 & 안전 장치: 진행 상태 저장, 오류 복구, 유해 출력 필터링, 사용자 확인 요청

2. Ralph Loop란 무엇인가

Ralph Loop(Ralph Wiggum Technique) 은 AI 에이전트를 활용한 장기 실행 자율 작업을 위한 오케스트레이션 기법입니다. Geoffrey Huntley가 개발·대중화했으며, The Simpsons의 캐릭터 Ralph Wiggum에서 이름을 따왔습니다.

Ralph Wiggum은 사랑스럽지만 건망증이 심하고, 열정적이지만 실수를 반복하는 캐릭터입니다. AI 에이전트도 마찬가지입니다. 이전 시도를 기억하지 못하고, 같은 실수를 반복합니다. Ralph Loop의 해법은 이 한계를 극복하려 하지 않고 받아들이는 것입니다.

가장 순수한 형태

while :; do cat PROMPT.md | claude-code ; done

이 한 줄의 bash 루프가 Ralph의 본질입니다. 매 반복마다 새로운 세션(fresh context) 을 시작하고, 파일 시스템을 통한 외부 메모리 로 세션 간 연속성을 유지합니다.

Ralph Loop의 핵심 원리

① Fresh Context Per Iteration (매 반복 새 컨텍스트) 가장 중요한 원칙입니다. 각 반복이 완전히 새로운 세션으로 시작되므로 Context Rot(컨텍스트 창에 불필요하거나 충돌하는 정보가 쌓여 출력 품질이 저하되는 현상)을 완전히 회피합니다.

Michael Arnaldi의 경고: “에이전트 하네스 안에서 Ralph를 skill/command로 구현한다면, Ralph의 핵심을 놓치고 있는 것”

② 파일 기반 외부 메모리 세션 간 기억은 오직 파일로 전달됩니다:

③ 루프당 하나의 작업(One Item Per Loop) 컨텍스트 윈도우를 보존하기 위해 한 번의 반복에서 하나의 작업만 수행합니다.

④ Backpressure(역압) 에이전트의 출력을 검증하고 수정을 강제하는 메커니즘입니다. 타입 시스템, 테스트, 린터, 보안 스캐너 등이 이에 해당하며, 이 검증 휠이 빠르게 돌수록 더 많은 반복이 가능합니다.

⑤ Planning Mode vs Build Mode Planning Mode에서 모든 사양을 읽고 fix_plan.md를 생성한 뒤, Build Mode에서 항목을 하나씩 구현하는 린(lean) 루프를 반복합니다.

3. 두 개념의 관계

계층적 관계: Ralph Loop는 Agent Harness 위에서 동작한다

Ralph Loop와 Agent Harness는 경쟁 관계가 아니라 상호 보완적인 계층 관계입니다.

┌─────────────────────────────────────────────────────────────┐
│  Ralph Loop (외부 오케스트레이션 - bash while loop)           │
│  ┌──────────┐   ┌──────────┐   ┌──────────┐               │
│  │ Session 1 │──▶│ Session 2 │──▶│ Session 3 │──▶ ...      │
│  │┌────────┐│   │┌────────┐│   │┌────────┐│               │
│  ││ Agent  ││   ││ Agent  ││   ││ Agent  ││               │
│  ││Harness ││   ││Harness ││   ││Harness ││               │
│  ││ ┌────┐ ││   ││ ┌────┐ ││   ││ ┌────┐ ││               │
│  ││ │LLM │ ││   ││ │LLM │ ││   ││ │LLM │ ││               │
│  ││ │+Tool│ ││   ││ │+Tool│ ││   ││ │+Tool│ ││               │
│  ││ └────┘ ││   ││ └────┘ ││   ││ └────┘ ││               │
│  │└────────┘│   │└────────┘│   │└────────┘│               │
│  └──────────┘   └──────────┘   └──────────┘               │
│        ❌ context        ❌ context                         │
│        ✅ files          ✅ files                           │
├─────────────────────────────────────────────────────────────┤
│  [영속 계층] Git commits │ fix_plan.md │ specs/* │ AGENT.md │
└─────────────────────────────────────────────────────────────┘

ZeroSync의 용어집이 이 관계를 명확하게 정리합니다: “Agent Harness: LLM API 호출을 감싸는 프로그램. 하네스는 세션, 도구, 오케스트레이션을 관리한다. ‘같은 에이전트’라 할 때, 같은 하네스를 의미하지만 매 루프는 새로운 세션을 생성한다”.

Anthropic의 사례: 두 개념의 실제 결합

Anthropic은 Claude Agent SDK(Agent Harness)를 활용하면서, 사실상 Ralph Loop와 동일한 패턴을 공식화했습니다:

• Initializer Agent = Ralph의 Planning Mode → 환경 설정, 기능 목록(feature_list.json) 작성, init.sh 스크립트 생성
• Coding Agent = Ralph의 Build Mode → 매 세션 claude-progress.txt와 git log를 읽고, 하나의 기능 구현 후 커밋
• feature_list.json = Ralph의 specs/*, claude-progress.txt = Ralph의 fix_plan.md

이 접근법으로 발견한 핵심 교훈은 Ralph Loop의 원칙과 정확히 일치합니다: 한 번에 하나의 기능만 구현, 매 세션 클린 상태로 종료, 진행 파일과 git으로 다음 세션에 인수인계.

4. 활용 방안

방안 1: 대규모 소프트웨어 프로젝트 자율 개발

Geoffrey Huntley는 Ralph Loop로 CURSED라는 프로그래밍 언어를 3개월간 자율 운영하여 완성했습니다. LLM 학습 데이터에 없는 언어의 컴파일러(렉서, 파서, LLVM 코드젠, 표준 라이브러리)를 구축한 사례입니다. Y Combinator 해커톤에서는 6개 저장소를 하룻밤에 배포하고, 약 $297의 API 비용으로 $50,000 상당의 작업을 완료했습니다.

구현 방법:

• Agent Harness(Claude Agent SDK 또는 DeepAgents)로 코드 실행, 웹 검색, 파일 시스템 접근 제공
• Ralph Loop으로 외부 bash 루프를 돌리며 매 세션 fresh context 보장
• specs/ 디렉토리에 기능별 사양서를 작성하고, fix_plan.md로 진행 상황 추적

방안 2: IaC(Infrastructure as Code) 자동화

클라우드 인프라 코드(Terraform, Pulumi 등)를 Ralph Loop로 반복 개선할 수 있습니다.

• Planning Mode: 아키텍처 요구사항을 specs로 작성 → 인프라 구현 계획 생성
• Build Mode: 매 반복 하나의 리소스(VPC, 서브넷, GKE 클러스터 등) 구현 → terraform validate + terraform plan을 backpressure로 활용
• Agent Harness가 클라우드 API 문서 검색, 코드 실행, 보안 스캔 도구 제공

방안 3: CI/CD 파이프라인과 통합한 지속적 코드 품질 개선

Ralph Loop의 backpressure 메커니즘을 기존 CI/CD와 연결하면 강력한 자동화가 가능합니다.

• 테스트 실패 → Ralph가 자동으로 수정 시도 → 재테스트 → 통과 시 커밋
• 린터/타입체커 경고 → 자동 수정 루프
• 보안 스캐너 발견 사항 → 자동 패치 생성

방안 4: 멀티 에이전트 병렬 처리

Ralph Loop는 두 가지 형태의 병렬성을 지원합니다:

• Subagent(세션 내 병렬): 메인 Ralph의 컨텍스트 윈도우를 소비하지 않는 읽기 전용 하위 프로세스 (파일 검색, 테스트 실행, 문서 업데이트)
• Multiple Loops(세션 간 병렬): VM, 컨테이너, git worktree로 격리된 독립 Ralph 루프를 동시 실행

이를 활용하면 마이크로서비스 아키텍처의 각 서비스를 별도 Ralph Loop으로 동시 개발할 수 있습니다.

방안 5: 비코딩 영역으로의 확장

이 패턴은 코딩을 넘어 과학 연구, 금융 모델링, 기술 문서 작성 등 장기 실행이 필요한 모든 에이전트 작업에 일반화할 수 있습니다.

• 리서치 에이전트: specs에 연구 질문 정의 → 매 반복 하나의 논문/데이터소스 분석 → fix_plan.md에 발견 사항 누적
• 투자 분석 에이전트: specs에 분석 프레임워크 정의 → 매 반복 하나의 기업/지표 분석 → 최종 보고서 자동 생성

5. Part 1 핵심 요약

Agent Harness는 개별 세션의 “품질” 을 보장하고, Ralph Loop는 세션 간의 “연속성과 진행” 을 보장합니다. 이 둘은 서로 다른 계층에서 동작하는 보완적 개념입니다.

“오케스트레이션은 작전의 두뇌이고, 하네스는 손과 인프라다. 둘 다 복잡한 AI 에이전트에 필수적이다.” — Parallel AI

“Ralph는 결정론적으로 나쁘다, 비결정론적 세계에서. Ralph의 실패는 예측 가능한 패턴을 따르며, 이 한계의 예측 가능성이야말로 유용한 이유다.” — Geoffrey Huntley

가장 강력한 활용은 이 두 개념을 의도적으로 분리하되 함께 사용하는 것입니다. Agent Harness 안에서 Ralph를 구현하면 Fresh Context라는 핵심 원칙이 깨지고, Ralph 없이 Harness만 사용하면 장기 작업에서 컨텍스트 부패와 조기 완료 선언이라는 실패 모드에 빠집니다. 둘의 올바른 결합이 신뢰할 수 있는 장기 자율 AI 작업의 핵심 요소입니다.

References

• [1] What is an agent harness in the context of large-language models? https://parallel.ai/articles/what-is-an-agent-harness
• [2] Agent vs Harness: What’s the Difference? https://ezz.sh/posts/agent_vs_harness
• [3] Agent Frameworks, Runtimes, and Harnesses- oh my! https://blog.langchain.com/agent-frameworks-runtimes-and-harnesses-oh-my/
• [4] The importance of Agent Harness in 2026 https://www.philschmid.de/agent-harness-2026
• [5] Effective harnesses for long-running agents https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
• [6] The Ralph Loop: Long-Running AI Agents http://www.zerosync.co/blog/ralph-loop-technical-deep-dive
• [7] Ralph Wiggum - Viral Agentic Coding Loop, Simplified https://ralph-wiggum.ai
• [8] ralph-loop-agent - GitHub https://github.com/vercel-labs/ralph-loop-agent
• [9] Ralph Loop Revolutionizes AI Coding https://www.linkedin.com/posts/rakeshgohel01_have-you-ever-tried-using-coding-ai-agents-activity-7414649482870665217-O6LF
• [11] Ralph Mode for Deep Agents: Running an Agent Forever https://www.youtube.com/watch?v=yi4XNKcUS8Q
• [12] Ralph Loop, OpenClaw - 새로운건 없었다 https://channel.io/ko/team/blog/articles/tech-ralph-loop-openclaw-9a2e654c
• [13] 코딩 에이전트의 결과물을 개선하는 Ralph 방법론 https://discuss.pytorch.kr/t/ralph-playbook-ralph/8705
• [14] truly the ultimate ralph loop explainer https://x.com/round/status/2011926496730886407
• [15] Understanding Agent Frameworks, Runtimes & Harnesses https://www.youtube.com/watch?v=inVO14Tabn4
• [16] WTF is a Ralph Loop? https://www.youtube.com/watch?v=2ItHHAKO4T0

Part 2. Google Cloud 기반 Agent Harness 구현 방안

개요: Google Cloud 서비스 매핑

이제 Agent Harness와 Ralph Loop의 개념적 정의를 바탕으로, 이를 Google Cloud 환경에서 실제로 어떻게 구성하고 구현하는지 살펴보겠습니다.

Agent Harness는 LLM 에이전트를 감싸는 인프라 시스템으로, 도구 통합·컨텍스트 관리·메모리·보안·오케스트레이션을 제공합니다. Google Cloud는 이를 구현하기 위한 포괄적인 서비스 스택을 보유하고 있으며, 핵심 축은 ADK(Agent Development Kit) + Vertex AI Agent Engine + MCP/A2A 프로토콜 조합입니다.

Google Cloud의 Agent Harness는 8개 계층으로 구성됩니다. 아래에서 각 계층을 상세히 검토합니다.

1계층: Google ADK (Agent Development Framework)

ADK(Agent Development Kit) 는 Google이 제공하는 오픈소스 에이전트 개발 프레임워크로, 누적 700만+ 다운로드를 기록하고 있습니다. Agent Harness를 코드로 정의하는 핵심 도구입니다.

핵심 특성

• Code-first: 에이전트 로직, 도구, 오케스트레이션을 코드로 직접 정의하여 테스트·버전관리 용이
• Model-agnostic: Gemini 최적화이나 다른 LLM도 지원
• Deployment-agnostic: Agent Engine, Cloud Run, GKE 어디든 배포 가능
• Multi-language: Python, TypeScript, Go, Java 지원

ADK 프로젝트 구조

parent_folder/
├── requirements.txt          # google-adk
└── my_agent/
    ├── __init__.py            # from . import agent
    ├── agent.py               # root_agent 정의
    └── .env                   # API keys, PROJECT_ID

ADK 핵심 추상화

State에는 네 가지 스코프가 존재합니다:

• state["key"] — 세션 스코프 (현재 대화만)
• state["user:key"] — 유저 스코프 (동일 유저의 모든 세션에서 공유)
• state["app:key"] — 앱 스코프 (전체 사용자 공유)
• state["temp:key"] — 임시 (턴 종료 시 삭제)

2계층: Agent Runtime — 실행 환경 선택

배포 명령 예시

Agent Engine 배포 (SDK):

from vertexai import agent_engines
agent_engine = agent_engines.create(
    agent=my_adk_app,
    requirements=["google-adk"],
    display_name="my-agent"
)

Cloud Run 배포 (CLI):

adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=us-central1 \
  --with-ui

권장 선택: 대부분의 경우 Vertex AI Agent Engine을 우선 고려합니다. Python 에이전트에 최적화되어 있으며, 세션 관리·메모리·스케일링·보안이 내장되어 운영 부담이 최소화됩니다.

3계층: AI Models — 추론 엔진

Model Routing 전략:

• 간단한 요청 (분류, 번역) → Gemini Flash 또는 SLM
• 복잡한 추론 (다단계 계획, 코드 생성) → Gemini Pro
• 특수 보안/데이터 요건 → Self-hosted open model on GKE

4계층: Tool Integration — 에이전트의 손

(A) Built-in Tools

ADK에 내장된 도구들로, 별도 설정 없이 즉시 사용 가능합니다:

• Google Search: 실시간 웹 정보 접근
• Code Execution: 보안 샌드박스에서 코드 실행
• RAG: 엔터프라이즈 데이터에서 정보 검색
• Database Query: 클라우드 DB 구조화 데이터 접근

(B) MCP 서버 (Cloud Run 호스팅)

gcloud run deploy mcp-server \
  --image us-central1-docker.pkg.dev/$PROJECT_ID/mcp-servers/my-server:latest \
  --region=us-central1 \
  --no-allow-unauthenticated

통신 프로토콜 요약

5계층: Memory — 상태 영속성

Short-term Memory

핵심 설계 원칙: 프로덕션에서는 반드시 Stateless Agent Application + 외부 상태 저장소 패턴을 사용합니다.

Long-term Memory

• Memory Bank: Google Cloud의 관리형 장기 메모리 서비스
• Firestore / AlloyDB: 커스텀 지식 베이스 구축 시
• Vertex AI Search: RAG 기반 엔터프라이즈 지식 검색

6계층: Security & Governance — 안전장치

7계층: Observability — 모니터링 & 디버깅

8계층: Multi-Agent 패턴 — 고급 구성

지원되는 디자인 패턴

• Sequential Pattern: 에이전트 A → 에이전트 B → 에이전트 C 순차 실행
• Iterative Refinement: 작업 에이전트 → 품질 평가 에이전트 → 프롬프트 개선 → 재시도
• Coordinator Pattern: 코디네이터 에이전트가 전문 서브에이전트에 위임
• Human-in-the-Loop(HITL): 중요 결정에서 인간 개입 경로 제공

실제 활용 사례

실전 구성 시나리오: 3-Tier 접근

Tier 1: 프로토타이핑 (비용 최소화)

ADK (Python) + Gemini Flash
├── InMemorySessionService
├── Built-in Tools (Google Search)
├── ADK Dev UI (local: adk web)
└── 배포: adk deploy cloud_run --with-ui

• 비용: Gemini API 사용량만 (pay-per-use)
• 소요 시간: 30분 이내 구축 가능
• 적합: PoC, 내부 데모, 해커톤

Tier 2: 프로덕션 단일 에이전트

ADK (Python) + Gemini Pro (추론) / Flash (단순작업)
├── Vertex AI Agent Engine Runtime
├── Agent Engine Sessions (단기) + Memory Bank (장기)
├── MCP 서버 on Cloud Run (커스텀 도구)
├── Model Armor + Agent Identity (IAM)
├── Cloud Trace + Monitoring
└── 배포: agent_engines.create() via SDK

• 비용: Agent Engine ~$0.0864/vCPU-hr + 모델 사용량
• 적합: 고객 서비스 봇, 내부 업무 자동화, RAG 어시스턴트

Tier 3: 엔터프라이즈 멀티에이전트

ADK + A2A + MCP
├── Coordinator Agent + 전문 Subagents
├── GKE 또는 Agent Engine (하이브리드)
├── Apigee API Hub (엔터프라이즈 API 관리)
├── AlloyDB/Firestore (메모리) + Vertex AI Search (RAG)
├── Model Routing (Pro + Flash + Open Models)
├── Full Governance: Model Armor + IAM + VPC SC + SCC
├── Cloud Trace + Logging + Monitoring + Prometheus
└── 배포: Terraform/Pulumi IaC

• 적합: 금융 분석 시스템, 공급망 자동화, 멀티부서 에이전트 플랫폼

비용 참고 (2026년 2월 기준)

Ralph Loop 연동 포인트

Part 1에서 다룬 Ralph Loop를 Agent Harness on Google Cloud와 결합하면 장기 실행 자율 에이전트를 구현할 수 있습니다. 핵심은 Ralph Loop이 Agent Harness 외부에서 동작해야 한다는 점입니다.

[Cloud Scheduler / Cloud Build Trigger]
    │
    ▼ (주기적 또는 이벤트 기반 트리거)
[Cloud Run Job: Ralph Outer Loop]
    │
    ├── Iteration 1 → [Agent Engine: ADK Agent] → git commit
    ├── Iteration 2 → [Agent Engine: ADK Agent] → git commit
    ├── Iteration 3 → [Agent Engine: ADK Agent] → git commit
    └── ...
    │
[Cloud Source Repos / GitHub: fix_plan.md, specs/*, AGENT.md]

• Cloud Scheduler: Ralph Loop의 외부 트리거
• Cloud Run Jobs: 각 반복의 bash loop 실행
• Agent Engine: 각 세션의 Agent Harness (fresh context)
• Cloud Source Repositories / GitHub: 파일 기반 외부 메모리 (영속 계층)

이 구성으로 Anthropic이 시연한 Initializer Agent + Coding Agent 패턴을 GCP 네이티브 서비스로 완전히 재현할 수 있으며, Vertex AI의 관리형 인프라 위에서 비용 효율적으로 운영할 수 있습니다.

References (Part 2)

• [1] google/adk-docs https://github.com/google/adk-docs
• [2] Choose your agentic AI architecture components https://docs.cloud.google.com/architecture/choose-agentic-ai-architecture-components
• [3] Index - Agent Development Kit https://google.github.io/adk-docs/
• [4] Run your agent https://docs.cloud.google.com/run/docs/ai/build-and-deploy-ai-agents/deploy-adk-agent
• [5] ADK - Session, State & Memory https://arjunprabhulal.com/adk-sessions-state/
• [6] Overview of Agent Development Kit https://docs.cloud.google.com/agent-builder/agent-development-kit/overview
• [7] Vertex AI Pricing https://cloud.google.com/vertex-ai/generative-ai/pricing
• [8] Build and deploy a remote MCP server on Cloud Run https://cloud.google.com/run/docs/tutorials/deploy-remote-mcp-server
• [9] Remember this: Agent state and memory with ADK https://cloud.google.com/blog/topics/developers-practitioners/remember-this-agent-state-and-memory-with-adk
• [10] Multi-agent AI system in Google Cloud https://docs.cloud.google.com/architecture/multiagent-ai-system
• [11] Choose a design pattern for your agentic AI system https://docs.cloud.google.com/architecture/choose-design-pattern-agentic-ai-system
• [12] Deploy to Vertex AI Agent Engine https://google.github.io/adk-docs/deploy/agent-engine/
• [13] Effective harnesses for long-running agents https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents

작성일: 2026-02-12 대상: Gemini CLI (v0.3.x+), Google Antigravity IDE 목적: 양 플랫폼의 설정 체계·인증·MCP·Agent Skills·세션 관리 등의 상세 구조 분석 및 통합 활용 가이드

목차

1. 개요
2. GEMINI.md - 컨텍스트 및 메모리 파일
3. settings.json - 동작 설정 및 에이전트 모드
4. Auth 설정 - 인증 체계
5. .env 설정 - 환경변수 관리
6. Rules - 항상 적용되는 가이드라인
7. Workflows - 사용자 트리거 매크로
8. Agent Skills - 핵심 상호호환 계층
9. MCP - 외부 통합
10. Agent 아키텍처 및 특수 에이전트
11. 세션 및 작업 관리
12. 상호호환성 종합 매핑
13. 통합 실전 구성 예시 및 팁
14. 참고 자료

1. 개요

Gemini CLI는 터미널 기반 AI 에이전트이고, Antigravity는 VSCode 포크 기반의 에이전트 중심 IDE입니다. 두 도구는 동일한 Gemini 에이전트 코어 엔진을 공유하며, 핵심적인 도구 시스템과 설정 로직은 호환되지만 사용자의 작업 환경에 따라 제공되는 인터페이스와 관리 방식에서 차이가 있습니다. 핵심은 Agent Skills라는 오픈 표준(agentskills.io)을 통해 양 플랫폼 간 상호호환이 가능하다는 점입니다.

2. GEMINI.md - 컨텍스트 및 메모리 파일

GEMINI.md는 양 플랫폼에서 항상 로드되는 지속적 컨텍스트 파일로, 프로젝트별 지시사항·코딩 스타일·아키텍처 규칙을 정의합니다. 에이전트는 대화 시작 시 여러 위치의 파일을 찾아 하나의 시스템 지침으로 결합합니다.

2.1 계층 구조 비교

💡 프로젝트 내 GEMINI.md 배치 팁

• 표준 위치 (권장): 프로젝트 루트 디렉토리에 배치합니다. 에이전트가 별도 설정 없이 즉시 파일을 인식하여 적용합니다.
• 통합 관리 위치: 설정을 한곳에 모으기 위해 .gemini/GEMINI.md 경로를 사용할 수도 있습니다. 이 경우 settings.json 내의 context.fileName에 해당 경로를 명시해야 에이전트가 올바르게 로드할 수 있습니다. (13.1 통합 디렉토리 구조 참조)

• 계층적 로드: 전역 → 프로젝트 루트 → 현재 디렉토리 순으로 로드되며, 하위 폴더의 지침이 상위의 지침을 구체화하거나 덮어쓸 수 있습니다.
• 모듈화: @filename.md 구문을 사용하여 공통 컨벤션이나 아키텍처 문서를 여러 프로젝트에서 가져와 사용할 수 있습니다.

2.2 Gemini CLI의 GEMINI.md 관리 명령어

2.3 실전 GEMINI.md 작성 샘플

범용적인 개발 환경에서 사용할 수 있는 표준적인 GEMINI.md 예시입니다.

# 프로젝트 컨텍스트 (GEMINI.md)

## 0. 핵심 사고 지침 (Core Thinking Rule) - [CRITICAL]
*   **Mandatory Thinking Process**: For EVERY user request, without exception, you MUST initiate your process by calling the `sequentialthinking` tool. You are prohibited from taking any other actions (reading files, executing commands, etc.) until you have systematically analyzed the request and planned your approach within a `sequentialthinking` block.

## 1. 표준 워크플로우 (Plan-Define-Act)
모든 복합적인 작업 시 다음 절차를 엄격히 준수합니다.
1. **PLAN (계획)**: 요청을 분석하여 단계별 실행 계획을 수립하고 사용자 승인을 받습니다.
2. **DEFINE (정의)**: 승인된 계획을 상세 TODO 리스트로 분해하여 DEFINE.md에 기록합니다.
3. **ACT (실행)**: 지침에 따라 코드를 작성하고, 테스트 및 린트를 통해 최종 검증합니다.

## 2. 코딩 원칙 및 스타일 가이드
*   **Consistency**: 기존 코드의 네이밍 컨벤션과 아키텍처 패턴을 분석하여 일관성을 유지합니다.
*   **Naming**: 변수/함수는 명확한 의미를 담아야 하며, Boolean 타입은 `is`, `has` 등의 접두사를 사용합니다.
*   **Documentation**: 복잡한 로직은 '무엇'보다 '왜' 작성했는지를 설명하는 주석(Why-comment)을 추가합니다.

## 3. 검증 및 보안 (Verification & Security)
*   **Test-First**: 코드 변경 후에는 반드시 `npm test` 또는 `pytest`를 실행하여 안정성을 확인합니다.
*   **Security**: API Key나 Token 등 민감 정보는 절대 코드나 로그에 노출하지 않으며 `.env`로 관리합니다.

2.4 [Tip] 작성 언어 선택 가이드 (Korean vs English)

GEMINI.md 작성 시 언어 선택은 모델의 성능과 유지보수 효율성에 영향을 미칩니다.

• 영문 작성의 장점: 기술적 정밀도가 높고 모델이 지시 사항을 더 강력하게 수용하며, 토큰 효율성이 좋습니다. (핵심 제약 조건 작성에 권장합니다.)
• 국문 작성의 장점: 팀 내 소통이 원활하고 비즈니스 로직 및 도메인 지식을 상세히 설명하기에 유리합니다. (맥락 공유에 권장합니다.)
• 권장하는 하이브리드 방식:
  • 기술적 용어, 핵심 명령어, 제약 조건은 영문으로 작성합니다.
  • 이에 대한 구체적인 배경 설명과 맥락은 국문으로 작성합니다.

3. settings.json - 동작 설정 및 에이전트 모드

settings.json은 Gemini CLI 전용 설정 체계입니다. Antigravity는 프로젝트 루트의 .agent/ 디렉토리를 초기 설정 공간으로 인식하며 IDE 내장 설정 UI를 주로 사용하지만, 핵심 로직은 이 설정을 기반으로 동작합니다.

3.1 설정 파일 우선순위 (높을수록 우선)

1. 시스템 기본값    /etc/gemini-cli/system-defaults.json
2. 사용자 설정      ~/.gemini/settings.json
3. 프로젝트 설정    .gemini/settings.json
4. 시스템 오버라이드  /etc/gemini-cli/settings.json
5. 환경 변수        .env 파일 및 OS 환경변수
6. CLI 인수         최우선 (예: --model, -y)

Tip: JSON 에디터에서 스키마 자동완성을 사용하려면 아래 URL을 참조하십시오: https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json

3.2 전체 설정 카테고리 레퍼런스

general — 일반 설정

{
  "general": {
    "previewFeatures": false,
    "preferredEditor": "code",
    "vimMode": false,
    "disableAutoUpdate": false,
    "disableUpdateNag": false,
    "checkpointing": { "enabled": false },
    "enablePromptCompletion": false,
    "retryFetchErrors": false,
    "sessionRetention": {
      "enabled": false,
      "maxAge": "30d",
      "maxCount": 100,
      "minRetention": "1d"
    }
  }
}

model — 모델 설정

{
  "model": {
    "name": "gemini-2.5-pro",
    "maxSessionTurns": -1,
    "compressionThreshold": 0.5,
    "skipNextSpeakerCheck": true,
    "summarizeToolOutput": {
      "run_shell_command": { "tokenBudget": 2000 }
    }
  }
}

modelConfigs — 모델 프리셋 및 별칭

20개 이상의 사전 정의 모델 프리셋이 포함되어 있으며, customAliases로 확장 가능합니다.

{
  "modelConfigs": {
    "customAliases": {
      "my-fast": {
        "extends": "chat-base-3",
        "modelConfig": {
          "model": "gemini-3-flash-preview",
          "generateContentConfig": {
            "thinkingConfig": { "thinkingLevel": "LOW" }
          }
        }
      }
    }
  }
}

주요 내장 별칭: gemini-3-pro-preview, gemini-3-flash-preview, gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite, classifier, summarizer-default, web-search, web-fetch, loop-detection, chat-compression-* 등입니다.

context — 컨텍스트 파일 설정

{
  "context": {
    "fileName": ["GEMINI.md"],
    "importFormat": null,
    "discoveryMaxDirs": 200,
    "includeDirectories": [],
    "loadMemoryFromIncludeDirectories": false,
    "fileFiltering": {
      "respectGitIgnore": true,
      "respectGeminiIgnore": true,
      "enableRecursiveFileSearch": true,
      "disableFuzzySearch": false
    }
  }
}

tools — 도구 설정

{
  "tools": {
    "sandbox": "docker",
    "shell": {
      "enableInteractiveShell": true,
      "pager": "cat",
      "showColor": false,
      "inactivityTimeout": 300,
      "enableShellOutputEfficiency": true
    },
    "autoAccept": false,
    "core": null,
    "allowed": ["run_shell_command(git)", "run_shell_command(npm test)"],
    "exclude": [],
    "useRipgrep": true,
    "enableToolOutputTruncation": true,
    "truncateToolOutputThreshold": 4000000,
    "truncateToolOutputLines": 1000,
    "enableHooks": true
  }
}

security — 보안 및 인증 설정

{
  "security": {
    "disableYoloMode": false,
    "enablePermanentToolApproval": false,
    "blockGitExtensions": false,
    "folderTrust": { "enabled": false },
    "environmentVariableRedaction": {
      "enabled": false,
      "allowed": [],
      "blocked": []
    },
    "auth": {
      "selectedType": null,
      "enforcedType": null,
      "useExternal": null
    }
  }
}

security.auth.selectedType: 현재 선택된 인증 유형입니다 (OAuth, API 키 등). security.auth.enforcedType: 강제할 인증 유형입니다 (불일치 시 재인증 요구). security.auth.useExternal: 외부 인증 플로우 사용 여부입니다.

mcp — MCP 전역 설정

{
  "mcp": {
    "serverCommand": null,
    "allowed": ["my-trusted-server"],
    "excluded": ["experimental-server"]
  }
}

mcpServers — MCP 서버별 설정

{
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": { "API_KEY": "$MY_API_TOKEN" },
      "cwd": "./server-directory",
      "url": null,
      "httpUrl": null,
      "headers": {},
      "timeout": 30000,
      "trust": false,
      "description": "서버 설명",
      "includeTools": [],
      "excludeTools": []
    }
  }
}

experimental — 실험적 기능

{
  "experimental": {
    "skills": true,
    "enableAgents": false,
    "jitContext": false,
    "extensionManagement": true,
    "extensionReloading": false,
    "codebaseInvestigatorSettings": {
      "enabled": true,
      "maxNumTurns": 10,
      "maxTimeMinutes": 3,
      "thinkingBudget": 8192,
      "model": "auto"
    },
    "cliHelpAgentSettings": { "enabled": true }
  }
}

skills — Agent Skills 관리

{
  "skills": {
    "disabled": ["skill-to-disable"]
  }
}

hooks — 훅 시스템 (Gemini CLI 전용)

에이전트 루프의 특정 이벤트 시점에 스크립트를 실행하여 동작을 사용자 정의합니다.

{
  "hooks": {
    "enabled": false,
    "disabled": [],
    "notifications": true,
    "BeforeTool": [],
    "AfterTool": [],
    "BeforeAgent": [],
    "AfterAgent": [],
    "BeforeModel": [],
    "AfterModel": [],
    "BeforeToolSelection": [],
    "SessionStart": [],
    "SessionEnd": [],
    "PreCompress": [],
    "Notification": []
  }
}

• BeforeTool: 도구 실행 전 보안 취약점 검사 등을 수행합니다.
• SessionStart: 사용자가 대화를 시작할 때 현재 시스템의 로드 상황이나 특정 라이브러리 버전을 프롬프트에 주입합니다.

ui — UI 설정

{
  "ui": {
    "theme": "GitHub",
    "hideBanner": false,
    "hideTips": false,
    "hideContextSummary": false,
    "showLineNumbers": true,
    "showCitations": false,
    "showModelInfoInChat": false,
    "useFullWidth": true,
    "useAlternateBuffer": false,
    "footer": {
      "hideCWD": false,
      "hideSandboxStatus": false,
      "hideModelInfo": false,
      "hideContextPercentage": true
    },
    "customWittyPhrases": [],
    "accessibility": {
      "disableLoadingPhrases": false,
      "screenReader": false
    }
  }
}

기타 카테고리

{
  "output": { "format": "text" },
  "ide": { "enabled": false },
  "privacy": { "usageStatisticsEnabled": true },
  "useWriteTodos": true,
  "admin": {
    "secureModeEnabled": false,
    "extensions": { "enabled": true },
    "mcp": { "enabled": true }
  },
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://localhost:4317",
    "otlpProtocol": "grpc",
    "logPrompts": false
  },
  "advanced": {
    "autoConfigureMemory": false,
    "excludedEnvVars": ["DEBUG", "DEBUG_MODE"]
  }
}

3.3 실전 settings.json 작성 샘플

자주 사용되는 주요 옵션들을 결합한 종합 설정 샘플입니다.

{
  "general": {
    "previewFeatures": true,
    "vimMode": false,
    "checkpointing": { "enabled": false }
  },
  "model": {
    "name": "gemini-2.5-pro",
    "maxSessionTurns": -1,
    "compressionThreshold": 0.5
  },
  "context": {
    "fileName": ["GEMINI.md"],
    "includeDirectories": [],
    "fileFiltering": { "respectGitIgnore": true }
  },
  "tools": {
    "sandbox": "docker",
    "autoAccept": false,
    "allowed": ["run_shell_command(git)"],
    "useRipgrep": true
  },
  "experimental": {
    "skills": true,
    "enableAgents": false,
    "jitContext": false
  },
  "skills": {
    "disabled": []
  },
  "hooks": {
    "enabled": false,
    "BeforeTool": [],
    "AfterTool": [],
    "SessionStart": []
  },
  "mcpServers": {
    "myServer": {
      "command": "node",
      "args": ["server.js"]
    }
  }
}

[주요 설정 포인트 설명]

• 일반 및 모델 (general, model): 최신 기능을 미리 사용해 볼 수 있도록 previewFeatures를 활성화하고, 최적의 성능을 위해 gemini-2.5-pro 모델을 세션 제한 없이 사용하도록 구성합니다.
• 컨텍스트 및 도구 (context, tools): 프로젝트의 핵심 지침인 GEMINI.md를 우선 로드하며, 보안을 위해 Docker 샌드박스 내에서 git 관련 도구만 명시적으로 허용하도록 설정하여 안전한 자동화를 도모합니다.
• 실험적 기능 및 스킬 (experimental, skills): 차세대 핵심 기능인 Agent Skills를 활성화하여 에이전트의 전문성을 높입니다. 단, 서브에이전트 기능은 예기치 못한 도구 실행을 방지하기 위해 비활성화 상태를 유지합니다.
• 확장성 (hooks, mcpServers): 세션 시작 시 환경을 점검하거나 도구 실행 전후에 개입할 수 있는 hooks 시스템과, 외부 서비스를 연동할 수 있는 MCP 서버의 기본 구조를 포함하고 있습니다.

3.4 환경변수 참조 문법

settings.json 내 문자열 값에서 $VAR_NAME 또는 ${VAR_NAME} 구문으로 환경변수를 참조할 수 있습니다.

{
  "mcpServers": {
    "github": {
      "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN" }
    }
  }
}

3.5 Antigravity의 대응 및 에이전트 모드

Antigravity는 별도의 settings.json 없이 IDE 내 커스터마이징 UI에서 규칙/워크플로우/스킬을 관리합니다. MCP 서버 설정, 모델 선택 등은 IDE 설정 패널에서 처리합니다. 특히 Antigravity에서는 에이전트의 페르소나를 결정하는 에이전트 모드 설정이 핵심이며, IDE 하단 상태 표시줄의 모드 선택기 또는 settings.json 내 agent.mode 필드를 통해 전환할 수 있습니다.

• Code 모드: 테스트 주도 개발(TDD), 버그 수정, 신규 기능 구현 등 실제 코드 작성에 최적화된 모드입니다. 에이전트가 파일 수정 도구를 적극적으로 사용합니다.
• Architect 모드: 대규모 리팩토링 계획 수립, 시스템 설계 분석, 의존성 맵 작성 등에 사용됩니다. 코드 수정보다는 구조적 제안에 집중합니다.
• Ask 모드: 코드에 영향을 주지 않고 질문 답변, 코드 리뷰, 기술 문서 설명 등 지식 전달 위주의 작업을 수행합니다.
• 설정 예시 (settings.json):

  {
    "agent": {
      "mode": "code"
    }
  }
  

4. Auth 설정 - 인증 체계

4.1 Gemini CLI 인증 방식 개요

Gemini CLI는 크게 세 가지 계열의 인증을 지원합니다.

공통 보조 변수:

• GOOGLE_CLOUD_PROJECT: GCP 프로젝트 ID (필수인 경우 있습니다.)
• GOOGLE_CLOUD_LOCATION: GCP 리전 (예: us-central1)
• GOOGLE_GENAI_USE_VERTEXAI: true로 설정 시 Vertex AI 엔드포인트를 사용합니다.

4.2 Vertex AI 및 ADC 인증

Google Cloud Vertex AI(엔터프라이즈 환경)를 사용하기 위해 ADC(Application Default Credentials) 메커니즘을 통한 인증을 구성합니다.

4.2.1 ADC 인증 방식 선택

환경에 따라 에이전트가 인증 정보를 획득하는 방식을 결정합니다.

1. 로컬 사용자 ADC 인증 (로컬 개발 권장) 개인 개발 환경에서 자신의 Google 계정 권한을 에이전트에게 부여합니다.
   • 명령어: gcloud auth application-default login 을 실행하여 브라우저 로그인을 수행합니다.
   • 장점: 별도의 키 파일 관리 없이 안전하게 인증 정보를 유지할 수 있습니다.
2. 서비스 계정 키 인증 (서버/자동화용) CI/CD 파이프라인이나 독립된 서버 환경에서 특정 권한을 가진 키 파일을 사용합니다.
   • 설정: 환경변수 GOOGLE_APPLICATION_CREDENTIALS에 발급받은 JSON 키 파일의 절대 경로를 지정합니다.

     export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
     

4.2.2 Vertex AI 환경변수 샘플

GCP 프로젝트 정보와 Vertex AI 사용 여부를 정의합니다.

export GOOGLE_GENAI_USE_VERTEXAI=True
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="global"

4.3 settings.json을 통한 정밀 제어 및 Fallback 설정

인증 유형을 고정하거나 환경변수가 누락되었을 때의 동작을 제어할 수 있습니다.

{
  "security": {
    "auth": {
      "selectedType": "vertex-ai",
      "enforcedType": null,
      "useExternal": false
    }
  }
}

• selectedType: 현재 선택된 인증 유형입니다. /auth 명령으로 변경 시 자동 저장됩니다.
• enforcedType: 강제할 인증 유형입니다. 불일치 시 재인증을 요구하여 보안 정책을 준수하게 합니다.
• useExternal: 외부 인증 플로우 사용 여부입니다.

GCP 프로젝트/리전 Fallback 로직

시스템 환경변수가 설정되지 않은 경우 에이전트는 settings.json 내의 값을 Fallback으로 참조합니다.

• 환경변수 GOOGLE_CLOUD_PROJECT 부재 시 → settings.json의 해당 값 참조합니다.
• 환경변수 GOOGLE_CLOUD_LOCATION 부재 시 → settings.json의 해당 값 참조합니다.

💡 인증 방식 리셋 팁: 인증 방식이 꼬였을 때 ~/.gemini/settings.json의 security.auth.selectedType 값을 지우거나 수정하여 초기화할 수 있습니다.

4.4 실전 인증 구성 전략

4.5 환경변수 기반 설정 (일시용 예시)

터미널에서 즉시 인증을 설정할 때 사용하는 명령어 세트입니다.

# 1) 기존 값 제거 (충돌 방지)
unset GOOGLE_API_KEY GEMINI_API_KEY

# 2) Gemini API 키 설정 (ai.google.dev에서 발급받은 키)
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"

# 3) Vertex AI(Express) API 키를 사용할 경우
export GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"
export GOOGLE_GENAI_USE_VERTEXAI=true

# 4) Google Cloud 서비스 계정 키를 사용할 경우
export GOOGLE_APPLICATION_CREDENTIALS="/absolute/path/to/key.json"
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

위와 같이 환경변수를 설정한 뒤, gemini 명령을 실행하여 대화창 내의 /auth 메뉴에서 실제 사용할 인증 방식을 최종 선택하십시오.

4.6 Antigravity 인증 흐름

Antigravity는 VSCode 기반 UI에서 초기 실행 시 다음과 같은 순서로 안내합니다.

1. 모드 선택: Secure / Review-driven / Agent-driven / Custom 중 선택합니다.
2. Model & Auth 설정:
   • Google 계정 로그인 (gcloud / OAuth 플로우) 수행합니다.
   • Gemini API / Vertex AI API 키를 입력합니다.
3. 선택한 방법에 따라 IDE 내부에서 환경 설정을 관리합니다.

Antigravity는 별도 .env 파일을 직접 읽지는 않고, VSCode 설정 및 OS 환경변수를 활용합니다. 이미 GEMINI_API_KEY 등이 셸이나 OS에 설정되어 있다면 그대로 재사용됩니다.

참고: Antigravity는 Google 계정 로그인이 필수이며 이를 우회할 방법은 없습니다.

5. .env 설정 - 환경변수 관리

5.1 Gemini CLI의 .env 로딩 순서

CLI는 다음 순서로 .env 파일을 탐색하며, 첫 번째 발견된 파일만 로드합니다 (병합하지 않습니다):

1. 현재 작업 디렉토리의 .env
2. 상위 디렉토리로 올라가며 탐색 (.git 또는 프로젝트 루트까지)
3. ~/.gemini/.env
4. ~/.env

주의: .gemini/.env를 사용하는 것이 권장됩니다. 일반 .env는 다른 개발 도구와 설정값이 충돌할 위험이 있습니다.

5.2 전역 .env 설정 예시

어떤 디렉토리에서 gemini를 실행해도 기본값으로 사용될 전역 설정입니다.

mkdir -p ~/.gemini

cat >> ~/.gemini/.env << 'EOF'
GEMINI_API_KEY="your-gemini-api-key"
GOOGLE_CLOUD_PROJECT="your-project-id"
GOOGLE_CLOUD_LOCATION="us-central1"
EOF

5.3 프로젝트 전용 .env 설정 예시

프로젝트 루트에서 실행 시 전역 설정보다 우선하여 적용됩니다.

mkdir -p .gemini

cat >> .gemini/.env << 'EOF'
GEMINI_API_KEY="project-specific-api-key"
GOOGLE_CLOUD_PROJECT="project-specific-id"
GOOGLE_CLOUD_LOCATION="asia-northeast3"
EOF

5.4 전체 우선순위 종합 정리

설정값이 충돌할 경우 아래의 우선순위에 따라 최종 결정됩니다 (오른쪽으로 갈수록 높은 우선순위).

낮음 ←――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――――→ 높음

시스템 기본값 → 사용자 settings.json → 프로젝트 settings.json
    → 전역 .env (~/.gemini/.env) → 프로젝트 .env (.gemini/.env)
        → 셸 환경변수 (export) → CLI 인수 플래그 (--model 등)

5.5 실전 활용 팁

6. Rules - 항상 적용되는 가이드라인

Rules는 예외 없이 모든 대화에 적용되는 지침(예: 코딩 컨벤션)입니다. 에이전트의 ‘헌법’과 같은 역할을 수행합니다.

6.1 플랫폼별 규칙 적용 비교

6.2 Antigravity 규칙 상세

Antigravity는 규칙의 활성화 레벨을 세밀하게 제어할 수 있습니다.

• System Rules: Google DeepMind가 정의한 불변 규칙입니다. (수정 불가)
• Global Rules: 모든 프로젝트에 공통으로 적용되는 개인 설정입니다.
• 프로젝트 규칙: 특정 프로젝트에만 적용되며 .agent/rules/ 폴더 내에 마크다운 파일로 저장합니다. 에이전트는 이를 프로젝트 고유의 ‘원칙’으로 인식합니다.
• 시각적 관리: IDE의 ‘에이전트 브레인’ 패널에서 로드된 규칙을 실시간으로 확인하고 새로고침하거나 비활성화할 수 있습니다.

6.3 실전 Rules 작성 샘플

프로젝트의 코딩 품질과 일관성을 유지하기 위한 coding-standards.md 예시입니다.

# 프로젝트 코딩 표준 규칙

## 1. 기술 스택 및 언어
- **TypeScript Only**: 모든 신규 코드는 반드시 TypeScript를 사용해야 하며, `any` 타입 사용을 엄격히 금지합니다.
- **Functional Programming**: 가급적 순수 함수와 불변성을 지향하는 함수형 프로그래밍 스타일을 따릅니다.

## 2. 네이밍 및 구조
- **Components**: UI 컴포넌트는 PascalCase를 사용하며, 폴더명과 파일명을 일치시킵니다.
- **Hooks**: 모든 커스텀 훅은 `use` 접두사를 사용하고 `src/hooks` 경로에 배치합니다.

## 3. 문서화 및 주석
- **JSDoc**: 모든 익스포트되는 함수와 클래스에는 JSDoc 형식의 설명을 반드시 추가해야 합니다.
- **Why-Comments**: 코드의 작동 방식보다는 '왜' 이 로직이 필요한지를 설명하는 주석을 우선시합니다.

## 4. 제약 사항
- 외부 라이브러리 추가 전 반드시 `package.json`을 검토하여 중복 기능이 있는지 확인합니다.
- 모든 API 호출부는 반드시 에러 핸들링(`try-catch`)을 포함해야 합니다.

6.4. 규칙이 설정된 Antigravity

7. Workflows - 사용자 트리거 매크로

워크플로우는 사용자가 /명령어로 호출하거나 자연어로 요청하는 다단계 레시피입니다.

7.1 Antigravity Workflows (전용)

저장 위치:

• 프로젝트: .agent/workflows/
• 전역: ~/.gemini/antigravity/global_workflows/

핵심 기능:

7.1.1 워크플로우 생성 방법 및 파일 형식

워크플로우는 YAML 프론트매터 + 마크다운 단계 구조로 작성합니다.

---
description: Create a new React component with standard structure
---
# React 컴포넌트 생성

1. 사용자에게 생성할 컴포넌트의 이름을 묻습니다.
2. `src/components/[Name]` 디렉토리를 생성합니다.
3. `index.jsx` 파일을 보일러플레이트로 작성합니다. // turbo
4. `styles.css` 파일을 기본 스타일과 함께 생성합니다.

7.1.2 실전 활용 예시

예시 1: React 컴포넌트 스캐폴딩 (create-component.md)

---
description: 표준 구조의 React 컴포넌트 세트를 생성합니다.
---
# React 컴포넌트 생성 워크플로우

1. **정보 수집**: 사용자에게 생성할 컴포넌트의 이름을 확인합니다.
2. **디렉토리 생성**: `src/components/[Name]/` 경로에 새로운 디렉토리를 만듭니다.
3. **파일 작성**: // turbo
   - `index.tsx`: 컴포넌트 엔트리 파일을 작성합니다.
   - `[Name].tsx`: 기본 함수형 컴포넌트 구조를 작성합니다.
   - `styles.css`: 기본 스타일 시트를 생성합니다.
4. **등록**: 생성된 컴포넌트를 `src/components/index.ts`에 익스포트하여 등록합니다.

예시 2: API 엔드포인트 및 테스트 생성 (add-api-route.md)

---
description: 새로운 API 라우트를 추가하고 관련 단위 테스트를 작성합니다.
---
# API 개발 및 검증 워크플로우

1. **라우트 생성**: `src/pages/api/` 폴더 내에 사용자가 요청한 엔드포인트 파일을 생성합니다.
2. **로직 구현**: 해당 API의 비즈니스 로직을 표준 핸들러 형식으로 구현합니다.
3. **테스트 작성**: `tests/api/` 경로에 해당 라우트를 검증하는 단위 테스트를 작성합니다.
4. **자율 검증**: // turbo
   - `npm test` 명령어를 실행하여 테스트 성공 여부를 확인합니다.
   - 테스트 실패 시 로그를 분석하여 코드를 수정한 후 재시도합니다.

7.2 Gemini CLI의 대응

동일한 워크플로우 시스템은 없으나, 커스텀 커맨드 (.gemini/commands/*.toml) 및 훅 시스템을 통해 유사한 다단계 자동화를 구현합니다.

7.3. 워크플로우가 설정된 Antigravity

7.4 규칙과 워크플로우의 차이 비교

7.5 규칙과 워크플로우의 상호 보완적 활용

• 워크플로우 (The What - 절차): 에이전트가 수행해야 할 작업의 순서와 단계를 정의합니다.
• 규칙 (The How - 방법과 품질): 에이전트가 작업을 수행하는 과정에서 준수해야 할 품질 기준과 제약 조건을 정의합니다.

활용 시나리오 1: “보안 강화 API 개발 파이프라인”

워크플로우 정의 (.agent/workflows/secure-api.md)

# 보안 API 개발 워크플로우
1. 사용자가 요청한 엔드포인트를 생성합니다.
2. 비즈니스 로직을 구현합니다. // turbo
3. 보안 스캔 도구를 실행하여 취약점을 점검합니다.
4. 결과가 통과되면 코드를 메인 브랜치에 병합합니다.

규칙 정의 (.agent/rules/security-standards.md)

# API 보안 표준 규칙
- 모든 API 엔드포인트는 반드시 JWT 인증 미들웨어를 포함해야 합니다.
- 데이터베이스 쿼리 시 반드시 ORM의 Parameterized Query를 사용하여 SQL Injection을 방지합니다.
- 에러 응답 시 스택 트레이스 등 시스템 내부 정보를 노출하지 않습니다.

활용 시나리오 2: “디자인 시스템 기반 UI 컴포넌트 개발 (TDD)”

워크플로우 정의 (.agent/workflows/create-ui-component.md)

# UI 컴포넌트 TDD 워크플로우
1. 컴포넌트의 요구사항과 Props 명세를 확인합니다.
2. `src/components/` 경로에 테스트 파일(`.test.tsx`)을 먼저 생성합니다.
3. 테스트가 실패하는 것을 확인한 후, 컴포넌트 본체 파일(`.tsx`)을 생성합니다. // turbo
4. 스타일과 로직을 구현하여 모든 테스트를 통과시킵니다.
5. 디자인 시스템 가이드를 준수했는지 최종 검토합니다.

규칙 정의 (.agent/rules/design-system-standards.md)

# 디자인 시스템 및 품질 규칙
- **Color**: 하드코딩된 HEX 코드를 금지하며, 반드시 `theme.color.*` 토큰을 사용해야 합니다.
- **Accessibility**: 모든 대화형 요소(Button, Input)는 반드시 적절한 `aria-label`을 포함해야 합니다.
- **Testing**: 모든 UI 컴포넌트는 최소한 '렌더링 여부'와 '클릭 이벤트 발생 여부'에 대한 테스트를 포함해야 합니다.

활용 시나리오 3: “자동화된 릴리즈 및 변경 이력 관리”

워크플로우 정의 (.agent/workflows/release.md)

# 릴리즈 자동화 워크플로우
1. 마지막 태그 이후의 모든 커밋 내역을 분석합니다.
2. 분석된 내역을 바탕으로 `CHANGELOG.md` 파일을 업데이트합니다. // turbo
3. 프로젝트 버전을 한 단계 올립니다 (Patch/Minor/Major 결정).
4. 새로운 버전으로 Git 태그를 생성하고 원격에 푸시합니다.

규칙 정의 (.agent/rules/release-standards.md)

# 릴리즈 및 버저닝 규칙
- **Versioning**: 반드시 SemVer 형식을 따라야 합니다.
- **Changelog Style**: 단순 커밋 나열이 아닌, 'Feature', 'Fix', 'Breaking Changes'로 카테고리를 나누어 요약해야 합니다.
- **Exclude**: 'chore', 'refactor' 성격의 커밋은 릴리즈 노트에서 제외합니다.

8. Agent Skills - 핵심 상호호환 계층

Agent Skills는 Anthropic이 도입하고 오픈 표준(agentskills.io)으로 공개된 포맷으로, Gemini CLI와 Antigravity에서 동일한 SKILL.md 파일로 작동합니다.

8.1 Skills vs Rules vs Workflows 핵심 차이

8.2 SKILL.md 구조 (공통 표준)

---
name: deploy-staging
description: Deploys current branch to staging environment.
  Use when user asks to "deploy", "push to staging",
  or "test on staging server".
---
# Deploy to Staging

## Prerequisites
1. Verify `git status` is clean
2. Run `npm run test`

## Deployment Steps
1. Execute `./scripts/deploy.sh staging`
2. Wait for health check HTTP 200
3. Report staging URL to user

중요: description 필드가 가장 중요합니다. 에이전트가 어떤 상황에서 이 스킬을 꺼내 쓸지 결정하는 기준이 되기 때문입니다.

8.3 권장 스킬 폴더 구조

my-skill/
├── SKILL.md       (필수) 지침 및 메타데이터 파일입니다.
├── scripts/       (선택) 실행 가능한 스크립트들을 포함합니다.
├── references/    (선택) 정적 문서 자료들을 포함합니다.
└── assets/        (선택) 템플릿 및 기타 자원들을 포함합니다.

8.4 저장 위치 및 로딩 경로

• Gemini CLI: 전역 ~/.gemini/skills/ / 프로젝트 .gemini/skills/
• Antigravity: 전역 ~/.gemini/antigravity/skills/ / 프로젝트 .agent/skills/

8.5 스킬 관리 명령어 (Gemini CLI)

/skills list          # 전체 스킬 목록을 표시합니다.
/skills link <path>   # 로컬 디렉토리 심볼릭 링크를 생성합니다.
/skills disable <name> # 특정 스킬을 비활성화합니다.
/skills enable <name>  # 특정 스킬을 재활성화합니다.
/skills reload         # 모든 스킬을 다시 스캔합니다.

8.6 실전 스킬 샘플

예시 1: git-helper (버전 관리 도우미)

---
name: git-helper
description: Git 커밋 메시지 작성, PR 초안 작성을 돕습니다. "커밋해줘" 요청 시 사용합니다.
---
# Git Helper Instructions
당신은 버전 관리 전문가입니다.
1. `git diff --staged`를 분석하여 시맨틱 커밋 메시지(feat, fix 등)를 제안합니다.
2. 사용자에게 메시지 승인을 받은 후 `git commit` 명령을 수행합니다.
3. **보안 철칙**: 비밀번호나 API 키가 포함된 경우 절대 커밋하지 않고 즉시 경고합니다.

예시 2: python-quality (파이썬 품질 전문가)

---
name: python-quality
description: 파이썬 코드 품질을 검사하고 수정합니다. "코드 봐줘" 요청 시 사용합니다.
---
# Python Quality Expert
1. `pyproject.toml` 설정을 확인하고 `ruff` 또는 `black` 도구를 실행합니다.
2. 도구가 없는 경우 PEP 8 표준에 따라 수동 리뷰를 수행하고 보고합니다.
3. 이슈 발견 시 한국어로 설명하고, 개선된 코드를 직접 제안하거나 적용합니다.

9. MCP - 외부 통합

에이전트가 외부 시스템(파일, DB, SaaS 등)과 통신하기 위한 표준 프로토콜입니다.

9.1 Gemini CLI MCP 설정

{
  "mcpServers": {
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    },
    "github": {
      "command": "node",
      "args": ["./mcp/github-server.js"],
      "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN" },
      "timeout": 60000,
      "trust": false
    }
  }
}

MCP 서버 속성 상세

지원 트랜스포트 구분

gemini mcp CLI 명령어

gemini mcp add my-server python server.py
gemini mcp add --transport http http-server https://api.example.com/mcp/
gemini mcp list
gemini mcp remove my-server
/mcp

9.2 MCP 설정 비교 요약

10. Agent 아키텍처 및 특수 에이전트

10.1 Gemini CLI 실험적 에이전트 설정

{
  "experimental": {
    "enableAgents": true,
    "codebaseInvestigatorSettings": {
      "enabled": true,
      "maxNumTurns": 10,
      "maxTimeMinutes": 3,
      "thinkingBudget": 8192,
      "model": "auto"
    }
  }
}

10.2 주요 Subagents

• codebase_investigator: 프로젝트 의존성 구조 파악 및 심볼 추적을 수행합니다.
• cli_help: CLI 사용법 및 환경 설정 질문에 특화되어 있습니다.

10.3 Browser Subagent (Antigravity 전용)

실시간 웹 상호작용 및 문서 탐색을 수행하는 서브 에이전트로, 전용 프로필을 사용하여 개인정보를 보호합니다.

11. 세션 및 작업 관리

11.1 세션 보존 및 복구 (Gemini CLI)

• 체크포인트: 코드 수정 직전 스냅샷과 대화 상태를 자동 저장합니다.
• 복구: /restore 명령으로 시점을 선택하고 롤백합니다.
• 재개: gemini --resume 명령으로 과거 세션을 검색하고 재개합니다.

11.2 작업 그룹 (Antigravity)

• 할 일 연동: 에이전트가 그룹 내 할 일을 완수하며 진행률을 시각적으로 보고합니다.
• 이정표(Milestone): 검증 성공 시 이정표를 기록하고 다음 단계 계획을 수립합니다.

12. 상호호환성 종합 매핑

13. 통합 실전 구성 예시 및 팁

13.1 권장 디렉토리 구조

사용자 홈 디렉토리 (전역):

~/.gemini/
├── .env                    # 전역 인증 (API 키, GCP 프로젝트 등)
├── settings.json           # Gemini CLI 전역 설정
├── GEMINI.md               # 전역 공통 컨텍스트 (양쪽 공유)
├── skills/                 # 전역 Agent Skills (CLI용)
└── antigravity/
    ├── mcp_config.json     # Antigravity 전용 MCP 설정
    ├── skills/             # 전역 Agent Skills (IDE용)
    └── global_workflows/   # Antigravity 전용 전역 워크플로우

프로젝트 디렉토리:

my-project/
├── .gemini/                    # Gemini CLI 전용 영역
│   ├── GEMINI.md
│   ├── settings.json
│   └── skills/
│       └── deploy-staging/
│           └── SKILL.md
├── .agent/                     # Antigravity 전용 영역
│   ├── rules/
│   ├── workflows/
│   └── skills/
│       └── deploy-staging -> ../../.gemini/skills/deploy-staging  # 심볼릭 링크
└── ...

💡 심볼릭 링크 활용 팁: ln -s ../../.gemini/skills/deploy-staging .agent/skills/deploy-staging 으로 한 곳에서 수정하면 양 플랫폼에 즉시 반영됩니다.

13.2 실전 활용 팁

1. 환경 전환: 터미널 작업 중 시각적 워크플로우가 필요하면 Antigravity로 전환하십시오. 설정이 공유되어 맥락이 유지됩니다.
2. 보안 우선: settings.json에서 샌드박스를 활성화하여 신뢰할 수 없는 코드 실행을 격리하십시오.
3. 지침 최적화: GEMINI.md 수정 후 /memory refresh를 실행하여 즉시 반영하십시오.
4. CI/CD 통합: 파이프라인 자동화는 Gemini CLI와 GitHub Actions 조합이 가장 유리합니다.

14. 참고 자료

• Gemini CLI Configuration (GitHub)
• Gemini CLI Authentication (GitHub Pages)
• Gemini CLI MCP Server (GitHub Pages)
• Gemini CLI Agent Skills
• Antigravity Rules/Workflows
• Antigravity Skills Codelab
• Google Cloud Blog: Choosing Antigravity or Gemini CLI

Airbnb에서 만든 Workflow 관리 오픈소스 소프트웨어입니다. 많은 기업에서 데이터 파이프라인 운용에 인기 있게 사용되고 있습니다. DAGs(Directed Acyclic Graphs) 형태로 Workflow 수행합니다.

사전 준비사항

• MySQL 설치
• Redis 설치

Install

# Airflow 설치
pip3 install apache-airflow

# MySQL 플러그인 설치
pip3 install 'apache-airflow[mysql]'

# Celery 설치
pip3 install celery

Airflow와 메타데이터를 저장할 MySQL 플러그인을 설치합니다.

CeleryExecutor 사용을 위해서 Celery를 설치합니다. 참고로 SQLite가 디폴트로 사용이 가능합니다. Executor는 Sequential Executor만 사용 가능합니다. 다른 Executor 사용을 위해서는 메타데이터를 저장할 별도의 데이터베이스 구성을 해야 합니다.

MySQL 환경 준비

mysql -u root -p

-- 스키마 생성
create database airflow;

-- 유저 생성
create user 'airflow'@'%' identified by 'Airflow!1';

-- airflow 유저에 airflow 스키마 권한 생성
grant all privileges on airflow.* to 'airflow'@'%';
flush privileges;

Root 계정으로 로그인하여 Schema, User를 생성합니다.

Airflow 설정

# Timezone 설정
default_timezone = Asia/Seoul

# 메타데이터 저장소 설정
sql_alchemy_conn = mysql://airflow:Airflow!1@localhost:3306/airflow

# Executor DB 설정
result_backend = db+mysql://airflow:Airflow!1@localhost:3306/airflow

# Redis 설정
broker_url = redis://127.0.0.1:6379/0

# DAG 리스트 갱신 설정 (테스트니까 10초로)
dag_dir_list_interval = 10

# Executor를 설정
executor = CeleryExecutor

airflow.cfg를 수정합니다.

Airflow 명령어

# Airflow DB 초기화
airflow db init

# Airflow Admin 권한의 유저 생성
airflow users create --role Admin --username [USERNAME] --email admin --firstname [FIRST_NAME] --lastname [LAST_NAME] --password [PASSWORD]

# Airflow Webserver 기동
# -p : 포트 설정
# -D : 데몬 설정
airflow webserver -p 8080 -D

# Airflow Scheduler
# -D : 데몬 설정
airflow scheduler -D

# Celery Worker
# -q : Queue 이름
airflow celery worker -q [QUEUE_NAME]

Celery Worker는 airflow.cfg에 명시하여 자동으로 worker가 기동이 됩니다. 만약 별도의 Worker를 띄우고자 한다면 CLI로 운용할 수 있습니다.

Celery

pip install로 별도로 Celery를 설치하는 것을 보고 뭐지? 하셨을 수 있을 거 같아요. Celery는 Python으로 작성된 Asynchronous task queue/Job Queue입니다. Job을 Broker를 통해서 전달하면 하나 이상의 Worker에서 처리하는 구조입니다.

Airflow Celery Executor 사용을 위해서 본 문서에서는 Broker로 Redis를 사용하였습니다.

참조문서

• Airflow Celery Executor
• Celery를 이용한 긴 작업 처리

Amazon Athena & S3 S3(Simple Storage Service)로 AWS를 대표하는 클라우드 서비스입니다. 객체 스토리지 (Object Storage)라는 형태의 서비스로 스토리지를 추상화한 형태로써 사용자는 데이터가 어느 블럭에 저장되는지 알 필요 없이 편리하게 사용 가능한 스토리지입니다. 물론 OS에 볼륨 마운트하여 사용도 가능합니다! 하지만 I/O 속도는 블럭 스토리지에 비하면 꽤 느린 편입니다. MiniO를 이용하여 객체 스토리지를 구현할 수 있습니다. Athena는 Standard SQL을 이용하여 S3에 저장된 데이터를 간단하게 질의할 수 있는 대화형 쿼리 서비스입니다. HDFS에서 Hive를 이용하여 SQL 질의하는 구조와 유사하구나~ 하고 이해하시면 좋습니다 🥳

Preface

Amazon S3에 저장된 여러 CSV 데이터를 Athena에서 테이블을 구성할 때, 1번 라인인 Header가 들어가는 상황을 대처해봅시다.

Pre-requirements

• Amazon Web Services 어카운트
• Amazon S3
• Amazon Athena

Header Skip 설정하기

Athena에서 테이블을 생성하고자 하는 버킷에 저장된 CSV 파일들을 먼저 살펴봅시다.

스키마가 전부 동일한가요?

그렇다면, 아래 파라미터를 추가하여 테이블 생성할 때 헤더를 생성할 수 있도록 설정합시다.

Ignoring Headers

TBLPROPERTIES ('skip.header.line.count' = '1')

파라미터를 입력하여 아래와 같이 입력합니다.

Query Sample

CREATE EXTERNAL TABLE IF NOT EXISTS [TABLE] (
    `COLUMN_01` string,
    `COLUMN_02` int,
    `COLUMN_03` timestamp,
    `COLUMN_04` string
)
ROW FORMAT SERDE 'org.apache.hadoop.hive.serde2.lazy.LazySimpleSerDe'
WITH SERDEPROPERTIES (
    'serialization.format' = ',',
    'field.delim' = ','
) LOCATION 's3://athena-examples-myregion/flight/csv/';
TBLPROPERTIES (
    'skip.header.line.count' = '1'
)

Athena에서 External Table을 생성해서 테스트해봅시다. 더 이상 파일의 숫자만큼 Header값이 Row에 추가되지 않고 온전한 값이 들어가는 것을 확인할 수 있습니다.

Use case

참고 문서

AWS Athena Documents - LazySimpleSerDe for CSV, TSV, and Custom-Delimited Files - Ignoring Headers

** Google Vertex AI 간단한 소개 ** Google Cloud의 AI Platform, AutoML 등 다양한 머신러닝 서비스를 하나의 인터페이스(UI / API)에서 사용할 수 있도록 구성된 종합선물 과자세트 같은 서비스입니다. 데이터셋 구성부터 모델 생성, 학습, 테스트, 검증하고 애플리케이션에서 Endpoint로 사용할 수 있도록 배포까지 하나의 파이프라인으로 구성 가능합니다. API를 이용하여 Jupyter Notebook에서 구성할 수도 있고, 클라우드 엔지니어가 직접 UI에서 AutoML을 이용하여 개발할 수도 있습니다.

Preface

지난 이야기

지난 포스팅에서는 신용카드 이상탐지 분류 모델을 AutoML을 이용하여 만들고 훈련(Train)을 시켜보았습니다. 이어서 모델을 평가하고 컨테이너로 배포하여 엔드포인트로 서비스를 테스트 해봅시다.

Pre Hands-On Requirements

• Google Cloud Platform 계정 (Google 계정으로 무료 크레딧을 받아봅시다!)
• 아주 약간의 머신러닝 지식
  • Confusion Matrix (혼동행렬)
  • Feature Importance
  • Precision
  • Recall
  • ROC Curve
• 아주 약간의 컴퓨터 사이언스 지식
  • Application Programming Interface
  • 컨테이너🐳
  • Python 쓸 줄 안다
  • Jupyter Notebook 가 뭔지 안다
• 아주 약간의 클라우드 컴퓨팅 지식
  • CLI 쓸 줄 안다
• Vertex AI에 Fraud Detection 모델
  • Google Vertex AI로 신용카드 이상탐지 AutoML 모델 만들기 1/2편를 먼저 하고 오세요!

Hands-On

6. 모델 평가하기

AutoML을 통해 만든 Classification 분류 모델을 학습을 약 1시간 22분 걸려서 완료하였습니다. 머신러닝 모델을 학습하면 일반적으로는 평가라는 단계를 거칩니다. 이 모델의 성능이 잘 나왔는지, 살펴보는 검증의 시간인 것이지요. 자, 학습된 모델을 클릭해서 들어가봅시다! Evaluate 탭이 첫 화면으로 보일 거에요. BI 화면도 아닌 것이 무슨 그래프 여러개와 알파벳과 숫자들의 향연을 마주하시게 될 것입니다.

여러분들은 당황한 티 내지 마시고 우선 말 없이 고개를 두 번 끄덕입시다. 머신러닝도 잘 하는구나 하고 사람들이 생각할 것입니다. 좋아 자연스러웠어

6.1. Confusion Matrix 이해하기

먼저 Classification 모델에서 평가지표로 사용되는 Confusion Matrix입니다. 아! 맞다 그 전에 왜 머신러닝 용어들은 긴 영어 단어를 굳이 꿋꿋하게 쓰고 있는지 설명 드릴게요!

매우매우매우 중요합니다!!

머신러닝 논문을 읽거나 사람들과 대화할 때 영어 단어를 자주 사용하는 편입니다. 그러니까 우리도 머신러닝 스페셜리스트인냥 위장을 위해 익숙해집시다.

다시 우리가 만든 모델의 Confustion Matrix를 살펴봅시다!

각 항에는 True label, Predicted label이 있고 0,1이 써있습니다. Classification은 지도학습으로 답(label)을 알려주고 예측을 시키는 방법입니다. 우리가 예측하고 싶은 이상여부의 실제값(True label)과 예측값(Predicted label)을 비교해서 정확도를 나타내는 것입니다.

• 실제 0인데, 예측도 0인 확률 (정답입니다)
• 실제 0인데, 예측이 1인 확률
• 실제 1인데, 예측이 0인 확률
• 실제 1인데, 예측도 1인 확률 (정답입니다)

순서대로 TP(True Positive),FP(False Positive), FN(False Negative), TN(True Negative)라고 부릅니다. 그리고 이 항목들을 요리조리 더하고 나누면 Accuracy, Precision, Recall 항목을 도출할 수 있습니다.

이야기를 더하고 싶지만 사실 어려워서 도망, 제가 머리가 아픈 관계로 다음에 설명 드리도록 하고 모델 평가를 이어 하겠습니다.

성능이 엄청나군요!! 정상 처리인 0을 100% 맞췄습니다. 그리고 사기 케이스인 1을 87% 맞췄습니다.

축하합니다! 🎉🎉🎉 여러분은 자신도 모르는 사이에 이미 훌륭한 머신러닝 스페셜리스트로 진화하였습니다.👩‍🏫

6.2. Feature Importance

Confusion Matrix 밑에 요 그래프가 보이실 거에요. 모델에서 예측할 때 가장 영향이 높았던 Feature들입니다. 실제 데이터를 비식별화하여 Feature 이름만 보고 알 수 없지만, 가지고 계신 데이터를 이용해서 돌려보면, 이해도가 높기 때문에 데이터 이해와 통찰력을 더 빠르게 얻을 수 있습니다.

6.3. ROC(Receiver operating characteristic) Curve

설명하기 위해서 찾아봤더니 한국말로는 _수신자 조작 특성_이라고 부르나 봐요. 괜찮습니다. 몰라도 되요.

다 필요 없고 ROC Curve라는 그래프 선이 왼쪽 상단 모서리에 가까운 모양일수록 성능이 좋다는 뜻입니다. ROC Curve 그래프가 그리는 선 아래에 넓이를 AUC라고 부르고, Curve 그래프와 달리, 넓이로 수치화하여 성능을 표현할 수 있기 떄문에 사용합니다. 1에 가까울 수록 좋은 겁니다.

우리가 만든 모델의 ROC Curve를 봅시다. 왼쪽 상단 모서리를 찍었습니다. 값은 1입니다.

다시 한 번 말씀 드리지만, 여러분은 엄청난 Classification 모델을 만들었습니다.

대단하시니까, 쌍따봉 드립니다.

7. 엔드포인트 배포

훈련과 평가가 끝난 이 훌륭한 모델을 사용해보도록 합시다! 과거 Monolithic 애플리케이션에서는 배포를 위해 중단이 필요했습니다. 하지만 엔드포인트로 통신하며 업데이트된 모델을 중단 없이 바로 사용할 수 있도록 엔드포인트 배포를 해보도록 하겠습니다.

모델에서 DEPLOY & TEST를 클릭합니다.

그리고 Deploy your model 섹션에 위치한 DEPLOY TO ENDPOINT를 클릭합니다.

Endpoint name은 적절하게 명명하고 CONTINUE를 클릭합니다. 저는 엄청난 모델을 만든 기쁨을 표현해보았습니다.

ADVANCED SCALING OPTIONS에서 적절한 Machine type을 선택합니다.

저는 돈을 아끼고 싶기 때문에 선택지에서 가장 작은 n1-standard-2를 선택하고 DEPLOY 하겠습니다.

8. API로 서비스 테스트하기

모델을 엔드포인트로 배포 되었나요? 이제 여러분의 엄청난 모델을 서비스 할 시간입니다.

아까 만든 Jupyter Notebook을 가볼까요 OPEN JUPYTERLAB을 클릭합니다.

그 다음에 Notebook > Python 3를 클릭합니다.

빈 칸에 아래 코드를 입력한 다음 OPTION + ENTER (ALT + ENTER)를 쳐봅니다.

!pip3 install google-cloud-aiplatform --upgrade --user

해당 라인이 실행되면서 다음 칸이 추가됩니다.

그 다음 칸에 아래 코드를 넣고 Project number와 Endpoint ID를 복사해서 수정합니다.

from google.cloud import aiplatform

endpoint = aiplatform.Endpoint(
    endpoint_name="projects/YOUR-PROJECT-NUMBER/locations/us-central1/endpoints/YOUR-ENDPOINT-ID"
)

프로젝트 번호는 상단 우측에 콜론이 진화한 점 세 개 클릭 > Project settings 클릭하면 아래와 같이 Project number를 확인할 수 있습니다.

Endpoint ID는 Vertex AI > Endpoints 를 클릭합니다. 생성한 Endpoint의 ID가 보입니다.

위의 코드에 수정해서 넣은 후에 OPTION + ENTER

실행되고 새로 추가된 칸에 아래 테스트 데이터를 넣고 실행합니다.

test_instance={
    'Time': 80422,
    'Amount': 17.99,
    'V1': -0.24,
    'V2': -0.027,
    'V3': 0.064,
    'V4': -0.16,
    'V5': -0.152,
    'V6': -0.3,
    'V7': -0.03,
    'V8': -0.01,
    'V9': -0.13,
    'V10': -0.18,
    'V11': -0.16,
    'V12': 0.06,
    'V13': -0.11,
    'V14': 2.1,
    'V15': -0.07,
    'V16': -0.033,
    'V17': -0.14,
    'V18': -0.08,
    'V19': -0.062,
    'V20': -0.08,
    'V21': -0.06,
    'V22': -0.088,
    'V23': -0.03,
    'V24': 0.01,
    'V25': -0.04,
    'V26': -0.99,
    'V27': -0.13,
    'V28': 0.003
}

response = endpoint.predict([test_instance])

print('API response: ', response)

Tabular 데이터로 생각해보면 위의 JSON은 Row 1개입니다.

그 다음에 Row 1개의 데이터를 test_instance 변수에 담고 모델이 배포된 엔드포인트에 API로 던져서 결과를 받아봅시다.

Score가 매우 높습니다. 축하합니다!

이제 나의 돈 또는 크레딧을 지키기 위해 엔드포인트와 Jupyter Notebook을 삭제합시다!

프로덕션 환경이라면 그대로 유지하시면 됩니다 ㅋㅋ

다음에는 직접 개발한 ML Code로 파이프라인을 만들어보도록 하겠습니다. 고생 많으셨습니다! 🥳

참고문서

• Vertex AI:Building a fraud detection model with AutoML
• Vertex AI 소개

Kubeflow 간단한 소개

머신러닝 워크플로우를 Kubernetes에서 손쉽게 이식하고 확장 가능하게 배포 및 운영을 목적으로 시작된 프로젝트입니다. Google 내부에서 서비스에 사용하기 위해 개발된 서비스가 오픈소스 프로젝트로 릴리즈되어 시작하게 되었습니다. 국내는 당근마켓, SOCAR 등 머신러닝/딥러닝이 응용되는 애플리케이션 서비스에서 널리 적용하고 사용하고 있는 ML Model Serving Tool입니다.

Preface

Kubernetes 클러스터에 배포할 수 있습니다. 우선 이 문서에서는 Minikube에 간단하게 구성하도록 하겠습니다. 다음 포스팅에서 CentOS7에 K8s 클러스터를 구성하고 설치해보도록 하겠습니다.

Pre-Installation Requirements

• kubectl
• kustomize
• passlib (pip3)
• py_bcrypt (pip3)
• Minikube

Minikube Spec

제가 구성한 Minikube의 스펙입니다.

• 4 CPUs
• 8GB Memory
• 40GB Storage

macOS에서 Homebrew를 이용하여 손쉽게 설치할 수 있습니다. CentOS나 Ubuntu에서도 패키지 매니저를 이용하여 손쉽게 설치해봅시다!

# Intsall Minikube
brew install minikube

# Start Minikube
minikube start --cpus 4 --memory 8096 --disk-size=40g

Software Version

본 문서에서 사용된 K8s와 Kubeflow의 버전입니다.

• Kubeflow 1.3.0
• Kubernetes 1.21.2

과거 이 문서가 Kubeflow 1.15 버전을 사용할 때와는 좀 차이가 있습니다. Kubeflow 1.3.0에서는 버전 1.1x와 다르게 kustomize를 이용하여 설치하고 관리합니다.

Kustomize도 설치해보도록 합니다.

brew install kustomize

Components of Kubeflow Manifests

아래의 컴포넌트가 포함되어 있습니다. 모두 설치할 수도 있고, 필요한 것만 개별로 설치할 수도 있습니다.

• TFJob Operator
• PyTorch Operator
• MPI Operator
• MXNet Operator
• XGBoost Operator
• Notebook Controller
• Tensorboard Controller
• Central Dashboard
• Profiles + KFAM
• PodDefaults Webhook
• Jupyter Web App
• Tensorboards Web App
• Volumes Web App
• Katib
• KFServing
• Kubeflow Pipelines
• Kubeflow Tekton Pipelines

설치하기

01. Kubeflow Manifest 준비

본 문서에서 설치에 사용될 바이너리를 준비합니다. Kubeflow Manifest를 사용할 것입니다. 여러 컴포넌트가 준비가 되어 있으므로, 손쉽게 설치가 가능합니다. 또한 불필요한 컴포넌트를 제외하고 필요한 컴포넌트만 메뉴얼하게 설치도 가능합니다.

우선, GitHub에서 클론으로 가져와 manifests 디렉토리에 들어가도록 합니다.

git clone https://github.com/kubeflow/manifests
cd manifests

02. Dex 수정하기

OIDC(OpenID Connect) Identity Service인 Dex를 통해 Kubernetes 사용자 인증을 관리합니다. 그런데 이슈가 하나 있습니다. Kubeflow 1.21 이후 버전에서는 Dex Manifest가 작동하지 않는 이슈가 있습니다. 해당 이슈: Fix dex for Kubernetes 1.21 #1883

해결 방법은 간단합니다. 문서를 보면 2가지 해결안을 제시(snap or yaml)하는데, snap을 이용하는 방법보다 쉬운 yaml 수정을 하도록 하겠습니다.

사실 macOS에서 snapd가 제대로 동작을 안하네요…

아래의 파일에서 31번째 줄에 추가해주세요.

vi manifests/common/dex/base/deployment.yaml

파일을 수정할 때 31번 라인에 아래의 NAMESPACE 설정을 추가해주도록 합니다. 띄어쓰기를 반드시 신경써서 넣어줍시다.

        env:
        - name: KUBERNETES_POD_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace

아래 이미지와 같이 보이면 됩니다.

02-1. Dex 사용자 수정하기 (생략 가능)

Kubeflow Manifests에 설정된 Default User와 Password는 아래와 같습니다.

• user@example.com
• 12341234

하지만 수정해보도록 하겠습니다. bcrypt를 이용하여 비밀번호 Hash를 생성합니다.

python3 -c 'from passlib.hash import bcrypt; import getpass; print(bcrypt.using(rounds=12, ident="2y").hash(getpass.getpass()))'

마지막 라인의 Hash값을 복사하여 아래 파일에 입력합니다.

vi manifests/common/dex/base/config-map.yaml

21번 라인에 가서 User를 수정하고 Hash를 입력합니다.

 21     - email: hello@kubeflow.com
 22       hash: 요기에 입력

03. 설치하기

기본적인 세팅은 끝났습니다. 이제 간편하게 명령어 한 줄로 Kubeflow Manifests를 Minikube에 구성해보도록 하겠습니다.

while ! kustomize build example | kubectl apply -f -; do echo "Retrying to apply resources"; sleep 10; done

04. Pods 상태 확인

배포 요청한 컴포넌트들의 Pods가 정상적으로 떠있는지 확인해보도록 합니다.

kubectl get pods -A
NAMESPACE                   NAME                                                         READY   STATUS    RESTARTS   AGE
auth                        dex-5ddf47d88d-w5vbc                                         1/1     Running   1          164m
cert-manager                cert-manager-7dd5854bb4-ckkqz                                1/1     Running   0          3h3m
cert-manager                cert-manager-cainjector-64c949654c-n72pz                     1/1     Running   1          3h3m
cert-manager                cert-manager-webhook-6b57b9b886-h7htl                        1/1     Running   1          3h3m
istio-system                authservice-0                                                1/1     Running   0          174m
istio-system                cluster-local-gateway-75cb7c6c88-kw59j                       1/1     Running   0          174m
istio-system                istio-ingressgateway-79b665c95-8rsss                         1/1     Running   0          3h2m
istio-system                istiod-86457659bb-gqzng                                      1/1     Running   0          3h2m
knative-eventing            eventing-controller-575584745f-p8hhs                         1/1     Running   0          174m
knative-eventing            eventing-webhook-6d6f75c565-7zn7n                            1/1     Running   1          174m
knative-eventing            imc-controller-c8d86c869-qp5pj                               1/1     Running   0          174m
knative-eventing            imc-dispatcher-7bf75b8999-fndtx                              1/1     Running   0          174m
knative-eventing            mt-broker-controller-7778d47797-sbg2t                        1/1     Running   0          174m
knative-eventing            mt-broker-filter-857c746446-hzddr                            1/1     Running   1          174m
knative-eventing            mt-broker-ingress-685cd6b57-sz6vr                            1/1     Running   1          174m
knative-serving             activator-859796b66c-r5zsr                                   2/2     Running   2          174m
knative-serving             autoscaler-565454fb69-4kgpj                                  2/2     Running   2          174m
knative-serving             controller-dd58865b5-dlwg6                                   2/2     Running   1          174m
knative-serving             istio-webhook-68fddcc567-n7pzq                               2/2     Running   1          174m
knative-serving             networking-istio-5664b9fb9c-jlq7q                            2/2     Running   1          174m
knative-serving             webhook-6c8b54d9-nkcq8                                       2/2     Running   2          174m
kube-system                 coredns-558bd4d5db-qdl2g                                     1/1     Running   1          3h19m
kube-system                 etcd-minikube                                                1/1     Running   0          3h19m
kube-system                 kube-apiserver-minikube                                      1/1     Running   0          3h19m
kube-system                 kube-controller-manager-minikube                             1/1     Running   0          3h19m
kube-system                 kube-proxy-7qwz6                                             1/1     Running   0          3h19m
kube-system                 kube-scheduler-minikube                                      1/1     Running   0          3h19m
kube-system                 storage-provisioner                                          1/1     Running   1          3h19m
kubeflow-user-example-com   ml-pipeline-ui-artifact-767659f9df-8p8ht                     2/2     Running   0          134m
kubeflow-user-example-com   ml-pipeline-visualizationserver-6ff9f47c6b-52lpd             2/2     Running   0          134m
kubeflow                    admission-webhook-deployment-f5d8f47f8-j6spk                 1/1     Running   0          172m
kubeflow                    cache-deployer-deployment-6dbb64ddcd-sn42c                   2/2     Running   1          173m
kubeflow                    cache-server-79d58845f5-6szhs                                2/2     Running   0          173m
kubeflow                    centraldashboard-9846cbb75-d2n2c                             1/1     Running   1          172m
kubeflow                    jupyter-web-app-deployment-554975dd5d-t5jbn                  1/1     Running   0          172m
kubeflow                    katib-controller-7b98cd6865-7khbj                            1/1     Running   0          172m
kubeflow                    katib-db-manager-7f5f684dd5-rjk5z                            1/1     Running   1          172m
kubeflow                    katib-mysql-85fc9c74b8-r4j2j                                 1/1     Running   1          172m
kubeflow                    katib-ui-64fbdf4d94-kc88w                                    1/1     Running   0          172m
kubeflow                    kfserving-controller-manager-0                               2/2     Running   0          173m
kubeflow                    kubeflow-pipelines-profile-controller-596b896f8d-jjgfr       1/1     Running   0          173m
kubeflow                    metacontroller-0                                             1/1     Running   0          173m
kubeflow                    metadata-envoy-deployment-95b58bbbb-xcl2t                    1/1     Running   0          173m
kubeflow                    metadata-grpc-deployment-c8f784fdf-n8cds                     2/2     Running   3          173m
kubeflow                    metadata-writer-76b6b98985-jb8md                             2/2     Running   1          173m
kubeflow                    minio-5b65df66c9-4hjx6                                       2/2     Running   0          173m
kubeflow                    ml-pipeline-5c5d8f4959-4bb5d                                 2/2     Running   3          173m
kubeflow                    ml-pipeline-persistenceagent-6ff46967ff-k4b4s                2/2     Running   1          173m
kubeflow                    ml-pipeline-scheduledworkflow-66bdf9948d-vqdzx               2/2     Running   0          173m
kubeflow                    ml-pipeline-ui-57fdfc58cc-mdnvr                              2/2     Running   1          173m
kubeflow                    ml-pipeline-viewer-crd-64dddf4597-p9xb9                      2/2     Running   1          173m
kubeflow                    ml-pipeline-visualizationserver-77b748f8fd-vxc7s             2/2     Running   1          173m
kubeflow                    mpi-operator-d5bfb8489-2mwpr                                 1/1     Running   1          172m
kubeflow                    mxnet-operator-6cffc568b7-wd5xv                              1/1     Running   1          172m
kubeflow                    mysql-f7b9b7dd4-2pxbh                                        2/2     Running   0          173m
kubeflow                    notebook-controller-deployment-7bd85f9f7d-cdknp              1/1     Running   1          172m
kubeflow                    profiles-deployment-74b4f94d5c-skcv6                         2/2     Running   2          172m
kubeflow                    pytorch-operator-56bffbbd86-7svvr                            2/2     Running   1          172m
kubeflow                    tensorboard-controller-controller-manager-77c89cd644-hcbln   3/3     Running   3          172m
kubeflow                    tensorboards-web-app-deployment-59ff4c7bd8-7sfss             1/1     Running   0          172m
kubeflow                    tf-job-operator-859885c8c4-c7lhb                             1/1     Running   2          172m
kubeflow                    volumes-web-app-deployment-6457c9bcfc-dl5mq                  1/1     Running   0          172m
kubeflow                    workflow-controller-67bf6d848b-kczq2                         2/2     Running   2          173m
kubeflow                    xgboost-operator-deployment-c6ddb584-j7zsz                   2/2     Running   1          172m

모든 Pod의 Status가 Running을 확인하였습니다. 만약 Pods의 상태가 Running이 아닌 아래와 같은 상태라면 배포 요청한 컴포넌트들이 순차적으로 처리가 될 것입니다.

• Init:0/1
• PodInitializing
• ContainerCreating

그런데 CrashLoopBackOff이 있다면, 설정에 문제가 있거나 리소스가 부족할 수 있습니다. Log를 확인해 봅니다.

kubectl -n [NAMESPACE] logs pods/[POD_NAME]

05. Kubeflow 대시보드 접속!

Istio Ingress Gateway를 통해 대시보드에 접속해보도록 합니다.

kubectl port-forward svc/istio-ingressgateway -n istio-system 8080:80

http://127.0.0.1:8080/

참고문서

• Kubeflow Manifests
• Fix dex for Kubernetes 1.21 #1883

Vagrant 간단한 소개

단일 워크플로에서 가상 머신 환경을 구축하고 관리하기 위한 도구입니다. 현재는 HashiCorp에서 관리하고 있으며, 포터블한 가상화 개발 환경 관리 도구입니다. VirutalBox, VMWare, Docker 등과 연동하여 인스턴스를 관리할 수 있습니다. 본 문서에서는 Oracle VM VirtualBox를 사용합니다.

Preface

Vagrant를 이용하여 2개의 CentOS 7 인스턴스를 구성해봅니다.

설치하기

01. Vagrant & VirtualBox 설치

# Vagrant 설치
brew install --cask vagrant vagrant-manager

# VirtualBox 설치
brew install --cask virtualbox