개발수양록

Git의 무시 규칙과 비밀 관리 도구: .gitignore부터 SOPS, gitleaks까지

.gitignore와 .git/info/exclude의 차이에서 출발해, 비밀 파일을 암호화해서 커밋하는 git-secret과 SOPS, 비밀 유출을 탐지하는 gitleaks까지 정리합니다. 상황별로 어떤 도구를 쓰면 좋을지 비교합니다.

API 키나 .env 파일 같은 비밀을 Git 저장소에서 다루는 방법은 크게 세 가지입니다. 아예 추적하지 않도록 무시하기, 암호화해서 커밋하기, 실수로 커밋되는 것을 탐지하기입니다. 각 방법마다 다른 도구가 발전해 왔습니다. 이 글에서는 Git의 무시 규칙인 `.gitignore`와 `.git/info/exclude`의 차이에서 출발해, 암호화 커밋 도구인 git-secret과 SOPS, 유출 스캐너인 gitleaks까지 정리합니다.

1. .gitignore vs .git/info/exclude

둘 다 같은 문법으로 무시할 파일 패턴을 적지만, 공유 여부가 다릅니다.

.gitignore .git/info/exclude

커밋 여부

커밋됨(공유)

커밋 안 됨(로컬 전용)

적용 범위

클론한 모두

내 클론만

용도

프로젝트 공통 무시 규칙

개인적인 무시 규칙

  • .gitignore: 저장소에 커밋되어 모든 협업자에게 적용됩니다. 빌드 결과물, node_modules/ 등 "누가 클론하든 무시해야 하는 것"을 적습니다.

  • .git/info/exclude: .git/ 안에 있어 커밋되지 않고 내 로컬 클론에만 적용됩니다. 개인 메모, 로컬 도구가 만드는 파일처럼 "나만 무시하고 싶은데 팀의 `.gitignore`를 더럽히긴 싫은 것"을 적습니다.

  • 그 밖에 git config core.excludesFile`로 지정하는 전역 무시 파일(보통 `~/.config/git/ignore)도 있습니다. 이 파일은 내 머신의 모든 저장소에 적용됩니다.

셋 사이에 우선순위나 효과 차이는 없습니다. 셋 다 이미 추적 중인(tracked) 파일에는 영향을 주지 않고, 아직 추적되지 않은 파일만 무시합니다.

2. git-secret

git-secret은 저장소 안에 비밀 파일(API 키, .env, 인증서 등)을 암호화한 채로 커밋할 수 있게 해주는 서드파티 도구입니다. Git 자체 기능이 아니라 별도로 설치하는 bash 기반 도구이며, GPG 공개키 암호화를 씁니다.

2.1. 동작 방식

git secret init                 # .gitsecret/ 디렉터리 생성
git secret tell you@example.com # 복호화를 허용할 사람의 GPG 공개키 등록
git secret add .env             # 비밀 파일 지정(원본은 자동으로 .gitignore에 추가)
git secret hide                 # 등록된 공개키로 암호화한 .env.secret 생성 → 이것만 커밋
git secret reveal               # 클론한 팀원이 자기 GPG 개인키로 원본 복원

저장소가 공개되어도 암호화본만 노출되고, 등록된 GPG 키 소유자만 풀 수 있습니다. 팀원을 빼려면 git secret killperson 후 다시 hide 합니다. 단, 과거 커밋 히스토리의 암호화본은 그 사람이 여전히 풀 수 있으므로 비밀 자체를 교체해야 합니다.

2.2. 이름이 비슷한 다른 것들

  • git-secrets (AWS 제작, 복수형): 정반대 목적입니다. 커밋 내용에 AWS 키 같은 비밀이 실수로 들어가는 것을 막는 pre-commit 검사기입니다.

  • GitHub Secrets: GitHub Actions에서 쓰는 암호화된 환경 변수 저장 기능입니다.

2.3. 한계

GPG 키 관리 부담이 크고, 파일 전체를 통째로 암호화하므로 diff와 코드 리뷰가 불가능합니다. 요즘은 SOPS나 플랫폼 환경 변수(Vercel, Supabase 등), 시크릿 매니저(1Password, Doppler 등) 쪽이 더 널리 쓰입니다.

3. SOPS (Secrets OPerationS)

SOPS는 2015년 Mozilla에서 시작해 2023년 CNCF에 기증된(Sandbox 프로젝트) 암호화 파일 편집 도구입니다. 현재는 getsops 커뮤니티가 관리하며, 2026년 6월 30일 릴리스된 3.13.2가 최신입니다(2026년 8월 기준).

3.1. git-secret과의 결정적 차이: 값만 암호화

SOPS는 YAML, JSON, ENV, INI, BINARY 형식을 지원하며, 구조화된 파일에서는 키는 평문으로 두고 값만 암호화합니다.

# SOPS로 암호화한 YAML — 구조가 보인다
database:
    host: ENC[AES256_GCM,data:Tr7o...,type:str]
    password: ENC[AES256_GCM,data:CwE4...,type:str]
sops:
    age: ...
    lastmodified: "2026-08-01T..."

그래서 어떤 설정 항목이 바뀌었는지 diff와 코드 리뷰가 가능합니다. 파일 전체가 불투명한 blob이 되는 git-secret과의 가장 큰 차이입니다.

3.2. 키 백엔드: age, PGP, KMS, Vault

GPG에 묶인 git-secret과 달리 네 계열의 키 관리 방식을 지원합니다.

  • age (개인·소규모 팀에 권장 — GPG보다 훨씬 단순한 현대적 파일 암호화 도구)

  • PGP(GPG)

  • AWS KMS, GCP KMS, Azure Key Vault, HuaweiCloud KMS

  • HashiCorp Vault

클라우드 KMS를 쓰면 IAM으로 접근을 제어하므로, "퇴사자가 과거 히스토리를 풀 수 있는" 문제도 키 접근 권한 회수로 해결됩니다.

3.3. 기본 사용 흐름 (age 기준)

  1. `age-keygen -o ~/.config/sops/age/keys.txt`로 키 쌍을 생성합니다.

  2. `.sops.yaml`에 어떤 파일을 어떤 키로 암호화할지 규칙을 선언합니다.

  3. `sops secrets/prod.yaml`로 파일을 편집하면 저장할 때 자동으로 암호화됩니다.

.sops.yaml
creation_rules:
  - path_regex: secrets/.*\.yaml
    age: age1abc...  # 공개키
sops secrets/prod.yaml        # 편집기가 열리고, 저장하면 자동 암호화
sops -d secrets/prod.yaml     # 복호화 출력
sops -r -i secrets/prod.yaml  # 데이터 키 회전

encrypted_regex 옵션으로 특정 키(예: password|token)의 값만 골라 암호화하는 부분 암호화도 됩니다.

3.4. 생태계

Kubernetes GitOps 도구와 통합이 잘 되어 있습니다. Flux CD는 SOPS를 기본 지원하고, ArgoCD·Helm(helm-secrets)·Ansible(community.sops) 연동도 활발합니다.

4. gitleaks

앞의 두 도구가 비밀을 "안전하게 커밋"하는 쪽이라면, gitleaks는 반대로 비밀이 커밋되는 것을 찾아내고 막는 오픈소스 스캐너입니다. Go로 작성된 단일 바이너리이며, 가장 널리 쓰이는 비밀 탐지 SAST(Static Application Security Testing) 도구 중 하나입니다(GitHub 스타 2.7만+). 최신 릴리스는 2026년 3월의 v8.30.1입니다.

4.1. 무엇을 하나

  • AWS 키, GitHub 토큰, Slack 웹훅 등 흔한 비밀 패턴에 대한 내장 룰로 저장소를 스캔합니다. 정규식 + 엔트로피(무작위성) 검사를 조합합니다.

  • 현재 파일뿐 아니라 git 히스토리 전체를 훑습니다. 지금은 지운 비밀이라도 과거 커밋에 남아 있으면 잡아냅니다.

  • 결과는 JSON, CSV, JUnit, SARIF 형식으로 출력할 수 있어 CI 연동이 쉽습니다.

4.2. 기본 사용법

gitleaks git .            # 저장소의 커밋 히스토리 전체 스캔
gitleaks dir .            # 히스토리 없이 현재 디렉터리 파일만 스캔
gitleaks git . --pre-commit --staged   # 커밋 직전 스테이징된 변경만 검사

  • pre-commit 훅으로 걸어두면 비밀이 히스토리에 들어가기 전에 차단합니다. 사후에 발견해서 히스토리를 세척하는 것보다 훨씬 쌉니다.

  • CI에는 공식 GitHub Action(gitleaks/gitleaks-action)이 있습니다.

  • 오탐은 .gitleaks.toml`의 allowlist나 해당 줄의 `# gitleaks:allow 주석으로 무시합니다. v8.28.0부터는 주 룰과 보조 룰이 근접 거리 안에서 함께 매칭돼야 탐지로 치는 composite rules로 오탐을 줄일 수 있습니다.

4.3. 알아둘 점: 개발은 후속작으로

메인테이너(Zach Rice)는 gitleaks를 기능 완성(feature-complete) 상태로 선언했고, 앞으로는 보안 패치만 나옵니다. 신규 개발은 같은 팀이 만드는 후속작 Betterleaks로 옮겨갔습니다. Betterleaks는 CEL(Common Expression Language) 기반 룰 검증을 도입해 CredData 데이터셋 기준 98.6% 재현율을 내세웁니다. 다만 gitleaks도 여전히 사실상 표준으로 널리 쓰이고 있습니다.

4.4. git-secrets와의 비교

2절에서 언급한 AWS의 `git-secrets`와 목적이 같지만, gitleaks가 룰이 훨씬 풍부합니다(수백 개 내장 패턴). 히스토리 스캔, 리포트 형식, 유지보수 활성도 면에서도 앞서서, 요즘은 gitleaks(또는 trufflehog) 쪽이 표준에 가깝습니다.

5. 정리: 무엇을 쓸까

상황 권장

개인 로컬에서만 무시하고 싶은 파일

.git/info/exclude

팀 공통으로 무시할 파일

.gitignore

저장소에 비밀을 암호화해 커밋 (개인·소규모)

SOPS + age

저장소에 비밀을 커밋, 클라우드 IAM 연동

SOPS + KMS

비밀을 아예 커밋하지 않기

플랫폼 환경 변수(Vercel 등), 시크릿 매니저

비밀이 실수로 커밋되는 것 방지

gitleaks(pre-commit 훅 + CI)

6. 참고 자료

이 포스트는 Claude Code와 정상혁이 함께 작성했습니다.

터미널 git diff를 GitHub처럼 보기: delta와 word-diff

터미널의 git diff는 한 글자만 고쳐도 줄 전체를 빨강/초록으로 칠합니다. delta의 word-diff-regex 설정과 git 내장 word-diff를 조합해서, 한글 문서에서도 바뀐 부분만 GitHub처럼 정밀하게 강조하는 방법을 정리합니다.

GitHub UI에서 diff를 보면 바뀐 단어만 진한 배경색으로 강조됩니다. 터미널의 `git diff`는 그렇지 않습니다. 한 글자만 고쳐도 줄 전체가 빨강/초록으로 칠해집니다.

한글 문서를 쓰거나 교열할 때 이 차이가 특히 크게 느껴집니다. 문장 하나에서 조사만 바꿨는데 diff에서는 삭제 줄과 추가 줄이 통째로 나오니, 눈으로 두 줄을 대조해서 어디가 달라졌는지 찾아야 합니다.

기본 git diff 화면

남긴다 → 기록한다, 덕분에 → 이 있어서, 방식 → 방법, 흔하게 → 흔히. 네 군데가 바뀌었는데 위 화면만 보고는 바로 알기 어렵습니다.

이 글에서는 이 문제를 해결한 설정을 공유합니다. Ubuntu 24.04 + zsh + git 2.43 + scm_breeze 환경에서 확인했습니다.

1. delta 설치와 설정

delta는 git의 pager를 대체하는 도구입니다. pager는 `git diff`나 `git log`의 긴 출력을 한 화면씩 넘겨 보여주는 프로그램으로, 기본값은 `less`입니다. delta는 이 자리를 대신하면서 구문 강조, 줄 번호, 그리고 줄 안에서 바뀐 부분만 강조하는 기능을 제공합니다.

1.1. 설치

apt에도 `git-delta`가 있지만 Ubuntu 24.04에 들어 있는 버전은 2023년 6월에 나온 0.16.5입니다. 최신 버전은 2026년 3월에 나온 0.19.2로 약 3년의 차이가 있습니다. sudo 없이 최신 바이너리를 받는 편이 낫습니다.

VER=0.19.2
curl -L -o /tmp/delta.tar.gz \
  https://github.com/dandavison/delta/releases/download/$VER/delta-$VER-x86_64-unknown-linux-gnu.tar.gz
tar xzf /tmp/delta.tar.gz -C /tmp
install -m755 /tmp/delta-$VER-x86_64-unknown-linux-gnu/delta ~/.local/bin/delta
delta --version

macOS는 brew install git-delta, Arch는 `pacman -S git-delta`로 받으면 됩니다.

1.2. ~/.gitconfig 설정

~/.gitconfig
[core]
	pager = delta

[interactive]
	diffFilter = delta --color-only

[delta]
	navigate = true
	line-numbers = true
	hunk-header-decoration-style = blue box
	file-style = bold yellow
	file-decoration-style = yellow ul
	# 바뀐 부분만 배경색으로 강조 (GitHub UI와 같은 방식)
	minus-emph-style = normal "#7a2323"
	plus-emph-style = normal "#2b5b2b"
	# 한글은 음절, 영문·코드는 단어 단위로 토큰을 나눈다
	word-diff-regex = "[가-힣]|[A-Za-z0-9_]+|[^ \t]"
	max-line-distance = 1.0

[diff]
	colorMoved = default
	algorithm = histogram

[merge]
	conflictStyle = zdiff3

이제 평소처럼 `git diff`를 치면 이렇게 나옵니다.

delta 통합 뷰

바뀐 줄은 은은한 배경색, 그 줄에서 실제로 달라진 부분은 진한 배경색으로 두 단계로 구분됩니다. GitHub의 diff 화면과 같은 방식입니다.

1.3. word-diff-regex

위 설정에서 가장 중요한 줄은 `word-diff-regex`입니다. 이 줄을 빼면 아래처럼 나옵니다.

delta 기본 토큰 단위 강조

delta의 기본값은 `\w+`인데, 유니코드 단어 문자 기준이라 한글 어절 하나가 통째로 토큰이 됩니다. 그래서 `저장하는 역할을 맡는다 → 저장한다`가 어절 세 개를 통째로 칠해 버립니다. 조사 하나만 고쳐도 앞 단어까지 같이 강조되니 정밀도가 떨어집니다.

`[가-힣]`을 앞에 두면 한글은 음절 단위로 쪼개지고, `[A-Za-z0-9_]+`가 뒤에 있어서 영문 식별자와 클래스 이름은 통째로 유지됩니다. 결과적으로 "저장하는 역할을 맡는다 → 저장한다"처럼 바뀐 부분만 정확히 좁혀집니다.

Caution

이 정규식은 delta에서만 통합니다. delta는 Rust regex(유니코드 인식)를 쓰지만, git 내장 `--word-diff-regex`는 POSIX ERE라 멀티바이트 문자 범위를 처리하지 못합니다.

$ git diff --word-diff-regex='[가-힣]|[A-Za-z0-9_]+' ...
fatal: invalid regular expression: [가-힣]|[A-Za-z0-9_]+

git 쪽에서는 대신 [^[:space:]](공백이 아닌 모든 문자)를 쓰면 됩니다. 아래 인라인 word-diff 절에서 씁니다.

1.4. 같이 켜면 좋은 설정

위 `~/.gitconfig`에 끼워 둔 나머지 항목도 짧게 설명합니다.

설정 효과

interactive.diffFilter = delta --color-only

`git add -p`에서도 같은 강조가 적용됩니다

diff.colorMoved = default

내용은 그대로고 위치만 옮긴 블록을 별도 색으로 표시합니다. 절이나 함수 순서를 바꿀 때 유용합니다

diff.algorithm = histogram

문단·함수를 옮겼을 때 diff 덩어리가 더 깔끔하게 묶입니다

merge.conflictStyle = zdiff3

충돌 시 양쪽뿐 아니라 공통 조상 내용까지 보여줍니다

delta.navigate = true

pager에서 n / `N`으로 파일 사이를 건너뜁니다

2. 상황별 diff 보기

delta 통합 뷰가 기본이지만, 보는 목적에 따라 다른 방식이 더 편할 때가 있습니다.

2.1. 인라인 word-diff: 한 줄에 겹쳐 보기

delta는 삭제 줄과 추가 줄을 위아래로 나란히 보여줍니다. 문장 교열처럼 한 줄 안의 변화만 확인하고 싶을 때는 git 내장 `--word-diff`가 더 편합니다. 삭제와 추가가 한 줄에 겹쳐 나오므로 문장을 두 번 읽지 않아도 됩니다.

git diff --word-diff=color --word-diff-regex='[^[:space:]]'
인라인 word-diff

남긴(빨강)기록한(초록)`다`처럼 바로 이어져 나옵니다. `--word-diff-regex='[^[:space:]]'`가 없으면 어절 전체가 잡히므로 이 옵션은 꼭 넣어야 합니다.

delta는 --word-diff 출력 형식을 이해하지 못해 색이 깨집니다. 그래서 이 명령은 pager를 `less`로 되돌려야 합니다.

2.2. 좌우 2단 분할

넓은 화면에서 코드를 볼 때는 2단 분할이 낫습니다.

git -c delta.side-by-side=true diff
좌우 2단 분할

기본값으로 켜지 않고 필요할 때만 켜는 편을 권합니다. 한글 문장은 한 줄이 길어서 폭이 반으로 줄면 줄바꿈이 많이 생깁니다.

3. zsh + scm_breeze에 붙이기

scm_breeze를 쓰면 gd(= git diff), gdc(= git diff --cached) 같은 단축 alias가 이미 있습니다. 이들은 git 함수를 거치므로 core.pager = delta 설정을 그대로 탑니다. 즉 `gd`는 아무것도 안 해도 바로 delta로 나옵니다.

문제는 scm_breeze가 기본 제공하는 gdw(= git diff --word-diff)입니다. delta를 타면서 색이 깨지고, 한글 정규식도 안 붙어 있습니다. 이것만 다시 정의합니다.

~/.zshrc`의 scm_breeze `source 줄 뒤에 넣습니다.

~/.zshrc
# delta 는 --word-diff 출력 형식을 이해하지 못해 색이 깨지므로
# word-diff 계열만 delta 를 우회하도록 다시 정의한다.
# scm_breeze 의 git 함수를 그대로 호출하므로 gs 가 매긴 파일 번호도 쓸 수 있다.
unalias gdw 2>/dev/null
_scmb_word_diff() {
    GIT_PAGER='less -R' git diff --word-diff=color \
        --word-diff-regex='[^[:space:]]' "$@"
}
gdw()  { _scmb_word_diff "$@"; }            # 단어(한글은 음절) 단위 인라인 diff
gdwc() { _scmb_word_diff --cached "$@"; }   # 스테이징된 변경만
gdws() { _scmb_word_diff -U0 "$@"; }        # 문맥 줄 없이 바뀐 곳만
gd2()  { git -c delta.side-by-side=true diff "$@"; }   # delta 좌우 2단 분할

`unalias gdw`가 필요한 이유는, zsh에서 alias가 같은 이름의 함수보다 먼저 잡히기 때문입니다. `gds`를 쓰지 않고 `gd2`로 이름을 지은 것도 oh-my-zsh의 git 플러그인이 이미 `gds`를 쓰고 있어서입니다.

scm_breeze를 안 쓴다면 `~/.gitconfig`에 alias로 넣어도 됩니다.

~/.gitconfig
[alias]
	wd = "!git -c core.pager=less diff --word-diff=color --word-diff-regex='[^[:space:]]' "
	sd = "!git -c delta.side-by-side=true diff "

4. 정리

명령 하는 일

git diff (gd)

delta 통합 뷰. 바뀐 단어만 진한 배경색

gd2

delta 좌우 2단 분할

gdw

삭제·추가를 한 줄에 겹쳐 보는 인라인 word-diff

gdwc

스테이징된 변경만 word-diff

gdws

문맥 줄 없이 바뀐 곳만 (-U0)

한글 문서를 다룬다면 두 가지만 기억하면 됩니다.

  1. delta에는 word-diff-regex = "[가-힣]|[A-Za-z0-9_]+|[^ \t]"

  2. git 내장 word-diff에는 --word-diff-regex='[^[:space:]]'

기본값 그대로 쓰면 한글은 어절 통째로 강조돼서 GitHub만큼 정밀해지지 않습니다.

5. 참고 자료

이 포스트는 Claude Code와 정상혁이 함께 작성했습니다.

Hugging Face 오픈 모델의 호환성을 만드는 사실상의 표준들

Hugging Face에서 받은 오픈 모델을 누가 학습했든 다운로드해서 바로 실행할 수 있는 배경에는 Safetensors 가중치 포맷, transformers의 config 규약, 소수 아키텍처로의 수렴이라는 사실상의 표준이 맞물려 있습니다.

모델 레이어를 다룬 글에서 모델이 "아는 것"은 가중치(weight)라는 숫자값에 압축돼 있다고 정리했습니다. 그 가중치는 결국 파일로 저장되어 Hugging Face에서 공유됩니다. Hugging Face는 오픈 모델과 데이터셋, 데모를 올리고 내려받는 중심 플랫폼으로, 흔히 "머신러닝계의 GitHub"에 비유됩니다. 그런데 이렇게 공유된 모델은 누가 어떤 환경에서 학습했든, 다운로드해서 바로 실행할 수 있는 경우가 많습니다. 이 글은 그 호환성의 토대가 되는 사실상의 표준(de facto standard)들을 정리합니다.

크게 모델 가중치 포맷, 모델 아키텍처 규약, 메타데이터/설정 표준 세 층위로 나눠 볼 수 있습니다.

1. 모델 가중치 저장 포맷

포맷 특징

Safetensors

현재 사실상 표준. 메모리 매핑[1]이 가능하고, pickle(Python 기본 직렬화 방식)을 쓰지 않아 역직렬화 시 임의 코드가 실행되는 보안 취약점이 없습니다.

GGUF

llama.cpp 생태계의 표준. 양자화[2] 정보를 파일 자체에 포함하며, CPU·엣지를 비롯한 다양한 환경의 추론에 강합니다.

PyTorch (.bin/.pt)

pickle 기반의 레거시 포맷. 여전히 많이 쓰이지만 역직렬화 과정에 보안 우려가 있습니다.

신경망의 가중치는 텐서(tensor), 즉 숫자가 여러 차원으로 늘어선 배열에 담깁니다. 스칼라(0차원)·벡터(1차원)·행렬(2차원)을 임의 차원으로 일반화한 것으로, 각 레이어의 가중치 하나하나가 이런 텐서입니다. 텐서마다 배열의 형태(shape, 예: 4096 × 4096)와 각 숫자의 자료형(dtype, 예: float16·bfloat16)이 정해져 있습니다.

Safetensors는 이 텐서의 이름(key)과 shape, dtype, 바이너리 데이터를 단순한 헤더+바이너리 구조로 저장합니다. 그래서 어떤 프레임워크든 쉽게 읽을 수 있습니다.

다국어 지원 능력도 이 가중치 안에 들어 있습니다. 학습 시 Common Crawl, Wikipedia 등에서 수집한 수십~수백 개 언어의 텍스트 패턴이 신경망 파라미터 전체에 걸쳐 분산 표현(distributed representation) 으로 인코딩됩니다. "한국어 사전" 같은 별도 파일이 있는 게 아니라, embedding layer와 attention/FFN layer의 수치 값들에 각 언어의 문법·어휘·의미가 녹아들어 있습니다. 그래서 특정 언어만 빼거나 넣기가 쉽지 않습니다.

2. 모델 아키텍처 규약: transformers 라이브러리의 역할

Hugging Face `transformers`는 수많은 모델 아키텍처를 통일된 인터페이스로 불러오고 실행하게 해주는 오픈소스 Python 라이브러리입니다. Transformer 아키텍처에서 이름을 따왔지만 지금은 그 밖의 구조도 폭넓게 지원하며, 모델을 불러오는 방식의 사실상 표준 역할을 합니다. 모델을 어떻게 읽고 실행할지는 가중치 파일 옆에 놓인 설정 파일들이 정의합니다.

  • config.json — 모델 구조 정의 (model_type, hidden_size, num_attention_heads 등)

  • tokenizer.json / tokenizer_config.json — 토크나이저 정의. BPE(Byte Pair Encoding) 같은 알고리즘으로 다국어 텍스트를 토큰으로 분리하는 토큰 사전(vocabulary, 보통 3만~25만 토큰)을 담습니다. 한국어 "안녕하세요"도, 영어 "hello"도 이 사전의 토큰 조합으로 표현됩니다.

  • generation_config.json — 생성 파라미터

config.json 예시
{
  "model_type": "llama",
  "hidden_size": 4096,
  "num_attention_heads": 32,
  "num_hidden_layers": 32,
  "vocab_size": 32000
}

model_type`이 `"llama"`이면, 라이브러리가 `LlamaForCausalLM 클래스를 자동으로 선택해 가중치를 로드합니다. 그래서 Llama 아키텍처 기반 모델은 누가 학습했든 동일한 코드로 실행됩니다.

3. 추론 엔진 간 호환성

같은 Hugging Face 모델 하나(safetensors + config.json)를 여러 추론 엔진(학습된 모델을 받아 실제로 실행하고 응답을 생성하는 런타임)이 받아 실행할 수 있습니다. 일부는 파일을 그대로 읽고, 일부는 포맷 변환을 거칩니다.

  • transformers: Hugging Face 표준 Python 라이브러리

  • vLLM: 고성능 서빙에 특화

  • TGI(Text Generation Inference): Hugging Face 자체 서빙 엔진

  • Ollama / llama.cpp: GGUF로 변환해 CPU/엣지에서 실행

  • ONNX Runtime: ONNX(Open Neural Network Exchange) 포맷으로 변환해 실행

이것이 가능한 이유는 아키텍처가 표준화되어 있기 때문입니다. 대부분의 오픈 모델이 소수의 아키텍처(Llama, Mistral, Qwen, Gemma 등)를 따르고, 각 추론 엔진이 이 아키텍처들을 미리 구현해 둡니다.

4. 앞 글의 레이어 분류와 겹쳐 보기

앞 글에서는 LLM에 정보가 들어가는 자리를 모델 레이어와 프롬프트 레이어로 나누고, 아키텍처·디코딩 같은 축을 덧붙였습니다. Hugging Face 모델 저장소의 파일 구성을 그 분류에 겹쳐 보면 거의 일대일로 대응합니다.

파일 대응하는 레이어 담는 것

model.safetensors

모델 레이어

학습으로 결정된 가중치(텐서) 그 자체

config.json (model_type)

아키텍처 레이어

"어떤 형태로 정보를 담을 것인가" — 레이어 수, 헤드 수, 아키텍처 종류

tokenizer.json

프롬프트 레이어 (토큰화)

컨텍스트로 들어갈 텍스트를 토큰으로 쪼개는 규칙

generation_config.json

디코딩/샘플링 레이어

temperature, top-p 같은 출력 제어 기본값

바꾸려는 대상에 따라 손대는 파일이 갈립니다. 지식 자체를 바꾸려면 `model.safetensors`를, 샘플링이나 출력 길이 같은 생성 기본값만 바꾸려면 `generation_config.json`을 건드립니다. 앞 글이 "정보가 어디에 저장되는가"의 지도였다면, 이 파일 구성은 그 지도가 디스크에 실제로 어떻게 놓이는지를 보여줍니다.

5. 핵심 정리

공식적인 "표준 기구"가 정한 스펙이라기보다는, 다음 세 가지가 맞물린 결과입니다.

  1. Safetensors — 텐서를 저장하는 단순하고 안전한 바이너리 포맷

  2. transformers의 config 규약 — `config.json`의 `model_type`으로 아키텍처를 식별

  3. 소수 아키텍처로의 수렴 — 대부분의 모델이 Llama/Mistral 계열 아키텍처를 채택

이 세 가지가 맞물려 "누가 학습했든 다운받으면 바로 돌릴 수 있는" 생태계가 만들어졌습니다. ISO 같은 공식 표준이 아니라 사실상의 표준(de facto standard)입니다.

6. 참고 자료

이 포스트는 Claude Code와 정상혁이 함께 작성했습니다.

1. 파일을 통째로 읽어 들이지 않고, 디스크의 내용을 필요한 부분만 메모리 주소에 바로 연결해 다루는 방식. 큰 모델도 빠르게 로드할 수 있습니다.
2. 가중치를 더 적은 비트로 표현해(예: 16비트를 4비트로) 모델 용량과 메모리 사용량을 줄이는 기법. 약간의 정확도를 내주고 크기를 줄입니다.