이 글은 그 사슬을 처음부터 끝까지 한 번에 잇는 것을 목표로 한다. 정보량에서 시작해서 엔트로피, Cross Entropy, BCE, 최대우도추정, KL Divergence 순서로 간다.

시작 질문: MSE는 왜 안 되나

이진 분류에서 모델이 $z$라는 logit을 뱉고 sigmoid를 통과시켜 $\hat y = \sigma(z)$를 만든다고 하자. 정답은 $y \in {0, 1}$이다. MSE를 쓰면 손실은 이렇다.

$z$에 대한 기울기를 구해보면 문제가 드러난다.

$\sigma’(z) = \hat y(1-\hat y)$라는 항이 붙어 있다. 이 값은 $\hat y$가 0이나 1에 가까울 때 0으로 죽는다. 그런데 $\hat y$가 0에 가까운데 정답이 1인 상황은 모델이 가장 크게 틀린 상황이다. 즉 MSE + sigmoid 조합은 가장 크게 틀렸을 때 기울기가 가장 작아진다. 학습이 필요한 지점에서 학습이 멈춘다.

숫자로 보면 심각성이 분명해진다. $y=1$인데 모델이 $z=-8$을 뱉은, 완전히 틀린 경우다.

같은 상황인데 기울기 크기가 약 3000배 차이난다. MSE는 사실상 아무것도 배우지 못한다.

기울기 문제를 걷어내더라도 더 근본적인 이유가 남는다. 분류 모델의 출력은 숫자가 아니라 확률분포다. 두 확률분포가 얼마나 다른지를 재는 데 유클리드 거리를 쓸 이유가 없다. 확률분포에는 확률분포의 척도가 있고, 그 척도는 정보 이론에서 나온다.

정보량: 놀람의 크기

“내일 해가 뜬다”는 정보량이 거의 0이다. “내일 눈이 온다”는 8월이라면 정보량이 크다. 드문 사건일수록 정보량이 크다는 직관을 수식으로 옮기려면 어떤 함수여야 할까. 세 가지 조건을 걸어보자.

1. 확률이 낮을수록 정보량이 크다 (단조 감소)
2. 확률이 1인 사건의 정보량은 0이다
3. 독립인 두 사건을 함께 관측한 정보량은 각각의 합이다: $I(pq) = I(p) + I(q)$

3번이 결정적이다. 곱을 합으로 바꾸는 연속함수는 로그뿐이다. 1번과 2번까지 맞추려면 부호를 뒤집어야 한다.

로그의 밑이 2면 단위는 bit, 자연로그면 nat이다. 딥러닝 구현은 거의 항상 자연로그를 쓴다.

엔트로피: 평균 놀람

정보량은 사건 하나에 대한 값이다. 분포 전체에 대해 평균을 내면 엔트로피다.

Shannon의 source coding theorem에 따르면 이 값은 $P$를 따르는 데이터를 인코딩하는 데 필요한 최소 평균 비트 수다. 공정한 동전은 $H = 1$ bit, 항상 앞면만 나오는 동전은 $H = 0$ bit다. 후자는 결과를 전송할 필요조차 없으니 당연하다.

엔트로피는 분포 하나의 고유한 성질이다. 여기까지는 모델이 등장하지 않는다.

Cross Entropy: 틀린 코드북을 쓸 때의 비용

이제 두 분포를 등장시킨다. 실제 데이터는 $P$를 따르는데, 우리는 그걸 모르고 $Q$가 맞다고 믿고 코드북을 만들었다. 이때 실제로 드는 평균 비트 수가 Cross Entropy다.

기댓값은 실제 분포 $P$로 잡고, 로그 안에는 내 예측 $Q$가 들어간다. 이 비대칭이 핵심이다.

$Q = P$일 때 이 값은 최소가 되고, 그 최솟값이 정확히 $H(P)$다. 따라서 언제나

내 믿음이 실제와 어긋난 만큼 추가 비용을 지불한다. 그 초과분이 뒤에 나올 KL Divergence다.

딥러닝에서의 Cross Entropy

$P$를 정답 라벨 분포, $Q$를 모델 예측 분포로 두면 손실 함수가 된다. 라벨이 one-hot이면 $P$는 정답 클래스 $c$에서만 1이고 나머지는 0이므로 합이 한 항만 남는다.

정답 클래스에 부여한 확률의 음의 로그. 이게 실무에서 마주치는 Cross Entropy의 전부다. 정답에 1을 주면 손실 0, 정답 확률이 0으로 가면 손실이 무한대로 발산한다.

import torch
import torch.nn.functional as F

logits = torch.tensor([[2.0, 1.0, 0.1]])
target = torch.tensor([0])

# softmax([2.0, 1.0, 0.1]) = [0.6590, 0.2424, 0.0986]
# CE = -log(0.6590) = 0.4170
F.cross_entropy(logits, target)

BCE: 클래스가 둘일 때

Binary Cross Entropy는 별개의 개념이 아니라 클래스가 2개인 특수 케이스다. $P = (y,\ 1-y)$, $Q = (\hat y,\ 1-\hat y)$를 위 정의에 그대로 대입하면 나온다.

그럼 왜 이름을 따로 붙였을까. 두 가지 이유가 있다.

첫째는 표현의 경제성이다. 클래스가 2개면 $\hat y$ 하나만 알면 나머지는 $1 - \hat y$로 결정된다. 출력 노드 2개 + softmax는 파라미터가 중복된다. 노드 1개 + sigmoid로 충분하다.

둘째가 실질적으로 더 중요하다. multi-label 문제를 다룰 수 있다. softmax는 출력의 합을 1로 강제하므로 클래스들이 상호배타적이라고 가정한다. 반면 sigmoid + BCE는 각 클래스를 독립된 이진 문제로 취급해서 합에 제약이 없다. 사진 한 장에 “고양이”와 “실내”가 동시에 참일 수 있는 문제라면 BCE를 써야 한다.

왜 이게 “옳은” 손실인가 (최대우도추정)

여기까지는 정보 이론 쪽 해석이었다. 통계 쪽에서 접근하면 같은 식이 전혀 다른 경로로 도출된다.

파라미터 $\theta$인 모델이 데이터 ${(x_i, y_i)}$를 만들어냈을 가능성(우도)을 최대화하고 싶다. 샘플이 독립이라면 우도는 곱이고, 로그를 씌우면 합이 된다.

우변이 정확히 Cross Entropy의 합이다.

Cross Entropy 최소화 = 최대우도추정

여러 후보 중 그럴듯해 보여서 고른 손실이 아니다. “데이터를 가장 잘 설명하는 파라미터를 찾는다”는 통계학의 표준 원리를 분류 문제에 적용하면 필연적으로 나오는 식이다.

KL Divergence: 그래서 실제로 줄이고 있는 것

두 분포의 차이 자체를 재고 싶다면 Cross Entropy는 조금 불편하다. $Q = P$인 완벽한 경우에도 값이 0이 아니라 $H(P)$이기 때문이다. 그 바닥값을 빼주자.

로그 안의 분수를 쪼개면 정체가 드러난다.

정리하면 이 글 전체를 관통하는 한 줄이 나온다.

Cross Entropy = 데이터 자체의 엔트로피 + 내 예측이 틀린 만큼의 초과 비용.

그리고 여기서 실무적으로 중요한 결론이 따라 나온다. 학습 중에 정답 분포 $P$는 고정되어 있으므로 $H(P)$는 $\theta$에 대한 상수다. 상수를 빼도 argmin은 변하지 않는다.

Cross Entropy를 최소화하는 것과 KL Divergence를 최소화하는 것은 완전히 동일한 최적화 문제다. 그래서 굳이 $H(P)$를 계산하지 않고 더 싼 Cross Entropy를 쓴다.

라벨이 one-hot이면 한 걸음 더 나간다. 확률 1인 사건 하나뿐이라 $H(P) = 0$이고, 따라서

두 값이 같아진다. 앞의 예제에서 CE가 0.4170이었는데, $D_{KL}$을 직접 계산해도 $1 \cdot \log(1/0.6590) = 0.4170$으로 같은 값이다.

KL의 성질 두 가지

항상 0 이상이다. $D_{KL}(P\parallel Q) \ge 0$이고, 등호는 $P = Q$일 때만 성립한다 (Gibbs’ inequality). 앞서 $H(P,Q) \ge H(P)$라고 했던 것의 다른 표현이다.

대칭이 아니다. $D_{KL}(P \parallel Q) \ne D_{KL}(Q \parallel P)$이고 삼각부등식도 성립하지 않는다. 그래서 “KL 거리”라는 말은 엄밀히는 틀렸다. divergence라고 부르는 이유다.

이 비대칭은 성가신 결점이 아니라 실제로 쓰이는 성질이다.

• Forward KL $D_{KL}(P \parallel Q)$: $P$가 큰 곳에서 $Q$가 작으면 $\log(P/Q)$가 폭발한다. $Q$는 $P$가 존재하는 영역을 전부 덮으려 한다 (mass-covering). 지도학습이 여기 해당한다.
• Reverse KL $D_{KL}(Q \parallel P)$: 기댓값을 $Q$로 잡으므로 $Q$가 0인 영역은 아예 벌점을 받지 않는다. $Q$는 $P$의 봉우리 하나에 안전하게 몰린다 (mode-seeking). 변분추론이나 RLHF의 KL penalty가 여기 해당한다.

KL을 직접 쓰는 경우

Cross Entropy로 대체 가능한데도 KL을 명시적으로 계산하는 상황이 있다. $P$가 one-hot이 아닐 때다.

• Knowledge distillation: teacher의 softmax 분포를 $P$로 쓴다. $H(P) \ne 0$이지만 student 파라미터에 대해서는 여전히 상수라, 사실 CE를 써도 최적해는 같다. 그래도 “두 분포를 맞춘다”는 의도를 드러내려고 관례적으로 KL을 쓴다.
• VAE: latent 분포를 prior에 붙들어두는 정규화 항이 KL이다. 이건 손실의 일부라 상수항이 아니고, 실제로 값 자체가 필요하다.
• PPO 등 RL: 새 정책이 기존 정책에서 너무 멀어지지 않게 KL로 제약한다.

다시 기울기: Cross Entropy가 학습을 살리는 이유

첫 절의 문제로 돌아가자. BCE의 $z$에 대한 기울기를 구해보면 이렇게 된다.

분모의 $\hat y(1-\hat y)$가 sigmoid의 미분과 정확히 상쇄된다. MSE를 죽이던 포화 항이 사라지고, 기울기가 오차 그 자체가 된다. 크게 틀릴수록 크게 움직인다.

softmax + CE에서도 똑같은 일이 벌어진다.

이건 우연이 아니다. sigmoid와 softmax는 exp로 만들어진 함수이고, Cross Entropy는 log를 취한다. log와 exp가 서로를 지운다. 정보 이론에서 유도된 손실과 확률로 정규화하는 활성 함수가 짝이 맞도록 설계되어 있는 것이다.

구현할 때 자주 밟는 지뢰

logit을 넘겨라, 확률을 넘기지 말고. F.cross_entropy와 nn.BCEWithLogitsLoss는 내부에서 log-sum-exp trick으로 수치 안정성을 확보한다. 직접 softmax를 거친 뒤 log를 취하면 확률이 0으로 언더플로했을 때 -inf가 나오고 그대로 NaN이 된다.

nn.CrossEntropyLoss는 softmax를 이미 포함한다. 모델 마지막에 softmax를 넣고 이 손실을 쓰면 softmax가 두 번 걸린다. 에러 없이 조용히 학습만 안 되는, 가장 찾기 짜증나는 종류의 버그다. nn.BCEWithLogitsLoss와 nn.BCELoss의 관계도 동일하다.

# 나쁨: softmax 두 번
logits = model(x)
loss = nn.CrossEntropyLoss()(F.softmax(logits, dim=-1), target)

# 좋음: raw logit 그대로
logits = model(x)
loss = nn.CrossEntropyLoss()(logits, target)

F.kl_div의 인자 규약은 직관과 다르다. 첫 인자는 확률이 아니라 log 확률이고, 두 번째 인자가 확률이다 (log_target=False 기준). 게다가 기본 reduction='mean'은 원소 단위 평균이라 수식의 정의와 맞지 않는다. 분포 단위로 맞추려면 reduction='batchmean'을 써야 한다.

Label smoothing은 $P$를 건드리는 기법이다. one-hot을 살짝 뭉개서 $P = (1-\epsilon, \epsilon/(K-1), \ldots)$로 만든다. 이러면 $H(P) \ne 0$이 되어 CE와 KL의 값이 더 이상 같지 않다. 다만 여전히 상수 차이라 최적화 대상으로서는 동일하다. 손실 값의 절대 크기를 다른 실험과 비교할 때만 주의하면 된다.

정리

• 정보량 $-\log p$는 “곱을 합으로” 조건에서 필연적으로 나오는 형태다.
• 엔트로피 $H(P)$는 분포 하나의 고유한 최소 인코딩 비용이다.
• Cross Entropy $H(P,Q)$는 실제 $P$인데 $Q$를 믿고 인코딩할 때의 비용이고, 항상 $H(P)$ 이상이다.
• BCE는 클래스가 2개인 CE다. 다만 sigmoid와 짝지어 multi-label을 다룰 수 있다는 실질적 차이가 있다.
• CE 최소화는 최대우도추정과 같다. 임의로 고른 손실이 아니다.
• $H(P,Q) = H(P) + D_{KL}(P\parallel Q)$이고, 학습 중 $H(P)$는 상수다. 따라서 CE 최소화와 KL 최소화는 같은 문제이며, one-hot 라벨에서는 값까지 같다.
• KL은 비대칭이라 거리가 아니다. 그 비대칭이 mass-covering과 mode-seeking을 가른다.
• log와 exp가 상쇄되어 기울기가 $\hat y - y$로 떨어지는 것이, MSE 대신 CE를 쓰는 실전적 이유다.

The goal of this post is to connect that chain from end to end, in one pass. Starting from information content, then entropy, cross entropy, BCE, maximum likelihood estimation, and KL divergence.

The opening question: why not MSE?

Suppose in binary classification the model emits a logit $z$, passes it through a sigmoid to produce $\hat y = \sigma(z)$, and the label is $y \in {0, 1}$. With MSE the loss is

Taking the gradient with respect to $z$ exposes the problem.

There is a factor $\sigma’(z) = \hat y(1-\hat y)$ attached. It dies to zero when $\hat y$ approaches 0 or 1. But “$\hat y$ near 0 while the label is 1” is exactly the situation where the model is most badly wrong. So the MSE + sigmoid combination has its smallest gradient precisely when it is most wrong. Learning stops at the very point where learning is needed.

The numbers make the severity obvious. Take $y=1$ while the model emits $z=-8$ — completely wrong.

Same situation, gradient magnitudes about 3000x apart. MSE learns essentially nothing.

Even setting the gradient issue aside, a deeper reason remains. A classifier’s output is not a number but a probability distribution. There is no reason to measure how different two probability distributions are with Euclidean distance. Probability distributions have their own yardstick, and that yardstick comes from information theory.

Information content: the size of the surprise

“The sun rises tomorrow” carries almost zero information. “It snows tomorrow” carries a lot, if it is August. To turn the intuition that rarer events carry more information into a formula, what shape must the function have? Impose three conditions.

1. Lower probability means more information (monotonically decreasing)
2. An event with probability 1 carries zero information
3. Observing two independent events together carries the sum of their information: $I(pq) = I(p) + I(q)$

Condition 3 is the decisive one. The only continuous function that turns products into sums is the logarithm. Satisfying 1 and 2 as well requires flipping the sign.

With base 2 the unit is a bit; with the natural logarithm it is a nat. Deep learning implementations almost always use the natural logarithm.

Entropy: average surprise

Information content is a value for a single event. Averaging it over the whole distribution gives entropy.

By Shannon’s source coding theorem, this value is the minimum average number of bits needed to encode data drawn from $P$. A fair coin has $H = 1$ bit; a coin that always lands heads has $H = 0$ bits. The latter is obvious — there is no need to transmit the outcome at all.

Entropy is an intrinsic property of a single distribution. No model has entered the picture yet.

Cross entropy: the cost of using the wrong codebook

Now bring in two distributions. The real data follows $P$, but not knowing that, we believed $Q$ was correct and built our codebook from it. The average number of bits this actually costs is the cross entropy.

The expectation is taken over the true distribution $P$, while our prediction $Q$ sits inside the logarithm. That asymmetry is the whole point.

The value is minimised when $Q = P$, and that minimum is exactly $H(P)$. So always

We pay an extra cost in proportion to how far our belief diverges from reality. That excess is the KL divergence, coming up later.

Cross entropy in deep learning

Let $P$ be the label distribution and $Q$ the model’s predicted distribution, and it becomes a loss function. With a one-hot label, $P$ is 1 only at the true class $c$ and 0 elsewhere, so only one term of the sum survives.

The negative log of the probability assigned to the correct class. That is all of the cross entropy you meet in practice. Assign 1 to the correct class and the loss is 0; drive the correct-class probability toward 0 and the loss diverges to infinity.

import torch
import torch.nn.functional as F

logits = torch.tensor([[2.0, 1.0, 0.1]])
target = torch.tensor([0])

# softmax([2.0, 1.0, 0.1]) = [0.6590, 0.2424, 0.0986]
# CE = -log(0.6590) = 0.4170
F.cross_entropy(logits, target)

BCE: when there are two classes

Binary cross entropy is not a separate concept but the special case of two classes. Substituting $P = (y,\ 1-y)$ and $Q = (\hat y,\ 1-\hat y)$ straight into the definition above gives it.

So why give it its own name? Two reasons.

The first is economy of representation. With two classes, knowing $\hat y$ alone determines the rest as $1 - \hat y$. Two output nodes plus softmax means duplicated parameters. One node plus a sigmoid is enough.

The second matters more in practice: it can handle multi-label problems. Softmax forces the outputs to sum to 1, which assumes the classes are mutually exclusive. Sigmoid + BCE, by contrast, treats each class as an independent binary problem with no constraint on the sum. If “cat” and “indoors” can both be true of one photo, you need BCE.

Why this is the “right” loss (maximum likelihood estimation)

Everything so far was the information-theoretic reading. Approach it from statistics and the same formula falls out along an entirely different route.

We want to maximise the likelihood that a model with parameters $\theta$ produced the data ${(x_i, y_i)}$. If the samples are independent the likelihood is a product, and taking the logarithm turns it into a sum.

The right-hand side is exactly a sum of cross entropies.

Minimising cross entropy = maximum likelihood estimation

This is not a loss picked because it looked plausible among candidates. It is the formula that necessarily appears when you apply the standard statistical principle of “find the parameters that best explain the data” to classification.

KL divergence: what we are actually reducing

If you want to measure the difference between two distributions in its own right, cross entropy is slightly awkward — even in the perfect case $Q = P$ its value is not 0 but $H(P)$. Let us subtract that floor.

Splitting the fraction inside the logarithm reveals what it is.

Rearranged, we get the one line that runs through this whole post.

Cross entropy = the entropy inherent in the data + the excess cost of my prediction being wrong.

And a practically important conclusion follows. During training the label distribution $P$ is fixed, so $H(P)$ is a constant with respect to $\theta$. Subtracting a constant does not change the argmin.

Minimising cross entropy and minimising KL divergence are exactly the same optimisation problem. That is why we use the cheaper cross entropy rather than bothering to compute $H(P)$.

With one-hot labels we can go one step further. There is only one event with probability 1, so $H(P) = 0$, and therefore

the two values coincide. In the earlier example CE was 0.4170, and computing $D_{KL}$ directly gives $1 \cdot \log(1/0.6590) = 0.4170$ — the same value.

Two properties of KL

It is always non-negative. $D_{KL}(P\parallel Q) \ge 0$, with equality only when $P = Q$ (Gibbs’ inequality). This is another way of stating what we said earlier, $H(P,Q) \ge H(P)$.

It is not symmetric. $D_{KL}(P \parallel Q) \ne D_{KL}(Q \parallel P)$, and the triangle inequality does not hold either. Strictly speaking, then, “KL distance” is wrong. Hence divergence.

That asymmetry is not an annoying flaw but a property that is actually used.

• Forward KL $D_{KL}(P \parallel Q)$: where $P$ is large and $Q$ is small, $\log(P/Q)$ explodes. $Q$ tries to cover the whole region where $P$ has mass (mass-covering). Supervised learning falls here.
• Reverse KL $D_{KL}(Q \parallel P)$: the expectation is taken over $Q$, so regions where $Q$ is 0 are not penalised at all. $Q$ safely collapses onto one mode of $P$ (mode-seeking). Variational inference and the KL penalty in RLHF fall here.

When KL is used directly

There are situations where KL is computed explicitly even though cross entropy would do — namely when $P$ is not one-hot.

• Knowledge distillation: the teacher’s softmax distribution is used as $P$. $H(P) \ne 0$, but it is still constant with respect to the student’s parameters, so CE would in fact give the same optimum. KL is used by convention to make the intent — “match the two distributions” — explicit.
• VAE: the regularisation term that pins the latent distribution to the prior is a KL. Here it is part of the loss rather than a constant, and the value itself is genuinely needed.
• PPO and other RL: KL constrains a new policy from drifting too far from the old one.

Back to gradients: why cross entropy keeps learning alive

Return to the problem from the first section. Taking BCE’s gradient with respect to $z$:

The $\hat y(1-\hat y)$ in the denominator cancels the sigmoid’s derivative exactly. The saturating factor that killed MSE disappears, and the gradient becomes the error itself. The more wrong you are, the more you move.

The same thing happens with softmax + CE.

This is no accident. Sigmoid and softmax are built from exp, and cross entropy takes a log. The log and the exp erase each other. A loss derived from information theory and an activation that normalises into probabilities were designed to be a matched pair.

Landmines people step on when implementing this

Pass logits, not probabilities. F.cross_entropy and nn.BCEWithLogitsLoss secure numerical stability internally with the log-sum-exp trick. Applying softmax yourself and then taking a log gives -inf the moment a probability underflows to 0, and NaN follows.

nn.CrossEntropyLoss already includes the softmax. Putting a softmax at the end of the model and then using this loss applies softmax twice. No error, it just quietly fails to learn — the most irritating kind of bug to find. The relationship between nn.BCEWithLogitsLoss and nn.BCELoss is the same.

# bad: softmax twice
logits = model(x)
loss = nn.CrossEntropyLoss()(F.softmax(logits, dim=-1), target)

# good: raw logits
logits = model(x)
loss = nn.CrossEntropyLoss()(logits, target)

F.kl_div’s argument convention is not what you would guess. The first argument is not probabilities but log probabilities, and the second is probabilities (with log_target=False). Worse, the default reduction='mean' averages element-wise, which does not match the definition in the formula. To match it at the distribution level you need reduction='batchmean'.

Label smoothing is a technique that modifies $P$. It slightly blurs the one-hot into $P = (1-\epsilon, \epsilon/(K-1), \ldots)$. Now $H(P) \ne 0$, so CE and KL no longer have the same value. They still differ by a constant, though, so as optimisation targets they are identical. You only need to be careful when comparing absolute loss values against other experiments.

Summary

• Information content $-\log p$ is the form that necessarily emerges from the “products into sums” condition.
• Entropy $H(P)$ is the intrinsic minimum encoding cost of a single distribution.
• Cross entropy $H(P,Q)$ is the cost of encoding with $Q$ when reality is $P$, and it is always at least $H(P)$.
• BCE is CE with two classes. The substantive difference is that, paired with a sigmoid, it can handle multi-label problems.
• Minimising CE is maximum likelihood estimation. It is not an arbitrarily chosen loss.
• $H(P,Q) = H(P) + D_{KL}(P\parallel Q)$, and during training $H(P)$ is constant. So minimising CE and minimising KL are the same problem, and with one-hot labels even the values coincide.
• KL is asymmetric and therefore not a distance. That asymmetry is what separates mass-covering from mode-seeking.
• The log and exp cancelling so the gradient collapses to $\hat y - y$ is the practical reason to use CE instead of MSE.

핵심 아이디어는 단순하다: 정답에 있는 단어가 예측에 얼마나 등장하는가?

공통 수식: Precision, Recall, F1

모든 ROUGE 변형은 동일한 프레임워크를 따른다. 겹침(overlap)을 세는 단위만 달라질 뿐이다.

• Recall: 정답 중 얼마나 잡아냈는가 (빠뜨린 게 없나)
• Precision: 예측 중 정답에 해당하는 비율 (헛소리가 없나)
• F1: 둘의 조화 평균. HuggingFace evaluate가 기본 리포트하는 값이 이것이다.

예시 설정

아래 예시로 모든 ROUGE를 계산해본다.

정답(Reference):    "서울의 인구는 약 천만 명이고 대한민국의 수도이다"
예측(Prediction):   "서울은 대한민국의 수도이며 인구는 약 구백만 명이다"

토큰 분리 (공백 기준):

R = [서울의, 인구는, 약, 천만, 명이고, 대한민국의, 수도이다]     → m = 7
P = [서울은, 대한민국의, 수도이며, 인구는, 약, 구백만, 명이다]   → n = 7

ROUGE-1 (Unigram)

수식

각 unigram $w$에 대해, 정답에서의 출현 횟수와 예측에서의 출현 횟수 중 작은 값을 취해 합산한다.

카운팅

겹치는 토큰: {인구는, 약, 대한민국의} → $|\text{overlap}| = 3$

계산

ROUGE-2 (Bigram)

수식

unigram 대신 연속 2개 단어 쌍(bigram)으로 겹침을 센다.

카운팅

정답 bigrams (6개):
  (서울의, 인구는)       (인구는, 약)         (약, 천만)
  (천만, 명이고)         (명이고, 대한민국의)   (대한민국의, 수도이다)

예측 bigrams (6개):
  (서울은, 대한민국의)   (대한민국의, 수도이며) (수도이며, 인구는)
  (인구는, 약)           (약, 구백만)          (구백만, 명이다)

겹치는 bigram:
  (인구는, 약) ✅
  나머지 전부 ❌

$|\text{overlap}| = 1$

계산

ROUGE-2가 ROUGE-1보다 낮은 이유: “인구는”과 “약”이 각각 겹쳐도, 이 둘이 연속으로 나타나야만 bigram으로 잡힌다. “대한민국의”가 겹치지만 앞뒤 토큰이 달라서 어떤 bigram에도 기여하지 못한다.

ROUGE-L (Longest Common Subsequence)

수식

LCS(Longest Common Subsequence)의 길이를 이용한다.

$m$ = 정답 길이, $n$ = 예측 길이, $\beta = P_{lcs} / R_{lcs}$ (이렇게 설정하면 $F_{lcs} = F_1$과 동일해진다)

핵심: subsequence는 연속일 필요 없다. 원래 순서만 유지하면 건너뛸 수 있다.

LCS 구하기 (DP 테이블)

R = [서울의, 인구는, 약, 천만, 명이고, 대한민국의, 수도이다]
P = [서울은, 대한민국의, 수도이며, 인구는, 약, 구백만, 명이다]

DP 테이블 $L[i][j]$ = $R[0..i]$와 $P[0..j]$의 LCS 길이:

$\text{LCS}(R, P) = 2$ → [인구는, 약]

“대한민국의”가 양쪽에 존재하지만, 정답에서는 6번째(인구는, 약 뒤), 예측에서는 2번째(인구는, 약 앞)이므로 [인구는, 약]과 동시에 LCS에 포함될 수 없다.

계산

이 예시에서 ROUGE-L < ROUGE-1이다. ROUGE-1은 순서를 무시하고 {인구는, 약, 대한민국의} 3개를 세지만, ROUGE-L은 순서 제약 때문에 2개만 센다.

ROUGE-1 = 1.0인데 ROUGE-L이 낮은 극단 예시

R = [A, B, C]
P = [C, B, A]

ROUGE-1: overlap = {A, B, C} → 3/3 = 1.0
ROUGE-L: LCS = [A] 또는 [B] 또는 [C] → 1/3 = 0.33

모든 단어가 있지만 순서가 완전히 뒤집혀서 ROUGE-L은 크게 떨어진다. 이것이 ROUGE-L의 존재 이유다.

ROUGE-Lsum

수식

다중 문장에서 문장별로 LCS를 따로 구한 뒤 합산한다.

정답이 문장 $r_1, r_2, \ldots, r_k$로 구성될 때:

예시

정답:
  r1: "서울의 인구는 약 천만 명이다"           (5토큰)
  r2: "서울은 대한민국의 수도이다"              (3토큰)

예측:
  "서울은 대한민국의 수도이며 인구는 약 구백만 명이다"

LCS(r1, P) = [인구는, 약] → 2
LCS(r2, P) = [서울은, 대한민국의] → 2

Recall = (2 + 2) / (5 + 3) = 4/8 = 0.5

ROUGE-L을 전체에 한 번 적용하면 문장 경계를 무시해서 한 문장의 매칭이 다른 문장의 점수를 방해할 수 있다. ROUGE-Lsum은 문장별로 독립 계산하므로 요약처럼 여러 문장이 있는 태스크에서 더 공정하다.

단일 문장이면 ROUGE-L = ROUGE-Lsum.

전체 비교 정리

일반적으로: ROUGE-1 >= ROUGE-L >= ROUGE-2

ROUGE의 한계

동의어를 못 잡는다

정답: "기쁘다"
예측: "행복하다"
→ ROUGE = 0 (의미는 같지만 토큰이 다름)

길게 쓰면 Precision이 희석된다

정답: "교향곡"               → m = 1
예측: "바그너는 교향곡을 쓰려 했다"  → n = 4

Recall = 1/1 = 1.0  (정답 토큰을 다 잡음)
Precision = 1/4 = 0.25  (예측의 75%가 불필요)
F1 = 2 × (1.0 × 0.25) / (1.0 + 0.25) = 0.4

의미적 정확도를 못 본다

정답: "2023년"
예측: "2024년"
→ ROUGE-1 = 0이지만, 사실상 거의 맞춘 것

이런 한계 때문에 실무에서는 ROUGE 단독이 아니라 BERTScore(임베딩 유사도), Exact Match, Human Evaluation 등을 함께 쓴다.

파이썬으로 직접 계산

import evaluate

rouge = evaluate.load("rouge")

predictions = ["서울은 대한민국의 수도이며 인구는 약 구백만 명이다"]
references = ["서울의 인구는 약 천만 명이고 대한민국의 수도이다"]

results = rouge.compute(predictions=predictions, references=references)
print(results)
# {'rouge1': 0.4286, 'rouge2': 0.1667, 'rougeL': 0.2857, 'rougeLsum': 0.2857}

The core idea is simple: how many of the words in the reference show up in the prediction?

The shared formulas: precision, recall, F1

Every ROUGE variant follows the same framework. Only the unit in which overlap is counted changes.

• Recall: how much of the reference did we capture (did we miss anything)
• Precision: what fraction of the prediction was actually in the reference (is there any nonsense)
• F1: the harmonic mean of the two. This is what HuggingFace evaluate reports by default.

The running example

We will compute every ROUGE variant on the example below.

Reference:   "Seoul has about ten million residents and is the capital"
Prediction:  "Seoul is the capital and has about nine million residents"

Tokenised on whitespace:

R = [Seoul, has, about, ten, million, residents, and, is, the, capital]   -> m = 10
P = [Seoul, is, the, capital, and, has, about, nine, million, residents]  -> n = 10

ROUGE-1 (unigram)

Formula

For each unigram $w$, take the smaller of its count in the reference and its count in the prediction, and sum.

Counting

Overlapping tokens: everything but “ten” → $|\text{overlap}| = 9$

Computation

ROUGE-2 (bigram)

Formula

Overlap is counted over pairs of adjacent words (bigrams) instead of unigrams.

Counting

Reference bigrams (9):
  (Seoul, has)         (has, about)        (about, ten)
  (ten, million)       (million, residents) (residents, and)
  (and, is)            (is, the)           (the, capital)

Prediction bigrams (9):
  (Seoul, is)          (is, the)           (the, capital)
  (capital, and)       (and, has)          (has, about)
  (about, nine)        (nine, million)     (million, residents)

Overlapping bigrams:
  (has, about) ✅   (million, residents) ✅   (is, the) ✅   (the, capital) ✅
  everything else ❌

$|\text{overlap}| = 4$

Computation

ROUGE-2 comes out lower than ROUGE-1 because a word only counts once it appears adjacent to the right neighbour. “Seoul” and “and” overlap as unigrams, but their surrounding tokens differ, so they contribute to no bigram at all.

ROUGE-L (longest common subsequence)

Formula

This one uses the length of the LCS (longest common subsequence).

$m$ = reference length, $n$ = prediction length, $\beta = P_{lcs} / R_{lcs}$ (setting it this way makes $F_{lcs}$ identical to $F_1$).

The key point: a subsequence does not have to be contiguous. It can skip, as long as the original order is preserved.

Finding the LCS (the DP table)

R = [Seoul, has, about, ten, million, residents, and, is, the, capital]
P = [Seoul, is, the, capital, and, has, about, nine, million, residents]

DP table $L[i][j]$ = the LCS length of $R[0..i]$ and $P[0..j]$:

$\text{LCS}(R, P) = 5$ → [Seoul, has, about, million, residents]

“and”, “is”, “the” and “capital” all exist on both sides, but in the reference they come after “residents” while in the prediction they come before “has”, so they cannot be part of the LCS at the same time as [has, about, million, residents].

Computation

Here ROUGE-L < ROUGE-1. ROUGE-1 ignores order and counts 9 tokens; ROUGE-L counts only 5 because of the ordering constraint.

An extreme case where ROUGE-1 = 1.0 but ROUGE-L is low

R = [A, B, C]
P = [C, B, A]

ROUGE-1: overlap = {A, B, C} -> 3/3 = 1.0
ROUGE-L: LCS = [A] or [B] or [C] -> 1/3 = 0.33

Every word is present, but the order is completely reversed, so ROUGE-L falls sharply. This is exactly why ROUGE-L exists.

ROUGE-Lsum

Formula

For multi-sentence text, compute the LCS per reference sentence and sum.

When the reference consists of sentences $r_1, r_2, \ldots, r_k$:

Example

Reference:
  r1: "Seoul has about ten million residents"    (6 tokens)
  r2: "Seoul is the capital of South Korea"      (7 tokens)

Prediction:
  "Seoul is the capital and has about nine million residents"

LCS(r1, P) = [Seoul, has, about, million, residents] -> 5
LCS(r2, P) = [Seoul, is, the, capital] -> 4

Recall = (5 + 4) / (6 + 7) = 9/13 ~ 0.6923

Applying ROUGE-L once over the whole text ignores sentence boundaries, so a match in one sentence can get in the way of another sentence’s score. ROUGE-Lsum computes each sentence independently, which is fairer for tasks like summarisation where there are several sentences.

For a single sentence, ROUGE-L = ROUGE-Lsum.

Overall comparison

Generally: ROUGE-1 >= ROUGE-L >= ROUGE-2

The limits of ROUGE

It cannot catch synonyms

Reference:  "glad"
Prediction: "happy"
-> ROUGE = 0 (same meaning, different token)

Writing at length dilutes precision

Reference:  "symphony"                 -> m = 1
Prediction: "Wagner wrote a symphony"  -> n = 4

Recall = 1/1 = 1.0  (caught every reference token)
Precision = 1/4 = 0.25  (75% of the prediction is unnecessary)
F1 = 2 x (1.0 x 0.25) / (1.0 + 0.25) = 0.4

It does not see semantic accuracy

Reference:  "2023"
Prediction: "2024"
-> ROUGE-1 = 0, even though it is essentially almost right

Because of limits like these, practitioners use ROUGE alongside BERTScore (embedding similarity), exact match, and human evaluation rather than on its own.

Computing it in Python

import evaluate

rouge = evaluate.load("rouge")

predictions = ["Seoul is the capital and has about nine million residents"]
references = ["Seoul has about ten million residents and is the capital"]

results = rouge.compute(predictions=predictions, references=references)
print(results)
# {'rouge1': 0.9, 'rouge2': 0.4444, 'rougeL': 0.5, 'rougeLsum': 0.5}

“오리처럼 걷고, 오리처럼 꽥꽥거리면 그것은 오리다.”

덕 타이핑이란?

덕 타이핑은 객체의 타입을 클래스 선언이 아니라, 그 객체가 가진 메서드와 속성으로 판단하는 프로그래밍 철학이다. Python, JavaScript, Ruby 같은 동적 타입 언어에서 자주 볼 수 있는 접근 방식이다.

타입을 명시적으로 확인하지 않고, 필요한 동작을 그냥 호출한다. 해당 메서드나 속성이 존재하면 성공, 없으면 런타임 에러가 난다.

class Duck:
    def sound(self):
        return "꽥꽥!"

class Dog:
    def sound(self):
        return "멍멍!"

class Robot:
    def sound(self):
        return "삐빅!"

def make_sound(animal):
    # 타입 확인 없이 그냥 호출
    print(animal.sound())

make_sound(Duck())   # 꽥꽥!
make_sound(Dog())    # 멍멍!
make_sound(Robot())  # 삐빅!

Duck이든 Dog든 Robot이든, sound() 메서드만 있으면 동일하게 취급된다. “이 객체가 무엇인가”보다 “이 객체가 무엇을 할 수 있는가” 에 집중하는 셈이다.

ABC는 덕 타이핑을 깨뜨리나?

결론부터 말하면 꼭 그렇지는 않다. ABC를 어떻게 사용하느냐에 따라 달라진다.

isinstance() 강제 체크 → 덕 타이핑 깨짐

from abc import ABC, abstractmethod

class Animal(ABC):
    @abstractmethod
    def sound(self): pass

def make_sound(animal):
    if not isinstance(animal, Animal):  # 타입 직접 확인!
        raise TypeError("Animal이 아님")
    print(animal.sound())

make_sound(Robot())  # ❌ sound()가 있어도 거부됨

ABC는 명세 역할만, 체크 없음 → 덕 타이핑 유지

함수 안에서 타입을 체크하지 않으면 ABC를 써도 덕 타이핑은 그대로 동작한다. ABC가 하는 일은 “이 메서드는 꼭 구현해야 해”라는 개발자 간의 약속일 뿐이다.

register()로 절충

Animal.register(Robot)  # Robot을 Animal로 등록

print(isinstance(Robot(), Animal))  # ✅ True (상속 없이도 통과)

덕 타이핑의 유연함을 유지하면서 타입 체계도 일부 활용하는 절충안이다. 단, 개발자가 수동으로 등록해야 한다는 번거로움이 있다.

타입 힌트는 덕 타이핑과 무관하다

타입 힌트는 런타임에 완전히 무시된다. animal: Duck이라고 써도 파이썬 인터프리터는 실행 중에 이를 전혀 검사하지 않는다.

def make_sound(animal: Duck) -> str:
    return animal.sound()

make_sound(Robot())  # ✅ 아무 문제 없이 실행됨

타입 힌트가 실제로 하는 일은 다음과 같다.

• 정적 분석: mypy, pyright 같은 타입 체커가 코드 실행 전에 경고를 띄워줌
• IDE 지원: 자동완성과 경고 표시에 활용됨
• 문서화: 코드를 읽는 사람에게 의도를 전달하는 역할

mypy를 CI에 붙여 강제하면 실질적으로 덕 타이핑을 제한하는 효과가 생기지만, 이는 어디까지나 개발 단계의 검사다. 런타임 동작은 여전히 덕 타이핑이다.

Protocol: 타입 힌트를 위한 덕 타이핑

mypy를 사용하면서도 덕 타이핑의 철학을 유지하고 싶을 때 Protocol을 쓴다. Protocol의 핵심 존재 이유는 바로 타입 힌트와 정적 분석이다.

from typing import Protocol

class Soundable(Protocol):
    def sound(self) -> str: ...

def make_sound(animal: Soundable) -> str:
    # "sound() 메서드만 있으면 OK"
    return animal.sound()

class Robot:  # Soundable을 상속하지 않아도
    def sound(self):
        return "삐빅!"

make_sound(Robot())  # ✅ mypy 통과, 런타임도 통과

이를 구조적 서브타이핑(Structural Subtyping) 이라고 부른다. 상속 관계 없이 “이 메서드를 가지고 있으면 이 타입으로 간주”하는 방식으로, 타입 힌트 세계에서 덕 타이핑의 정신을 그대로 구현한다.

@runtime_checkable: 런타임에서도 사용하기

from typing import Protocol, runtime_checkable

@runtime_checkable
class Soundable(Protocol):
    def sound(self) -> str: ...

print(isinstance(Robot(), Soundable))  # ✅ True
# 메서드 존재 여부를 자동으로 확인

ABC의 register()와 비슷하지만, 개발자가 수동으로 등록할 필요 없이 메서드의 존재만으로 자동으로 판단한다.

정리

• 덕 타이핑은 “무엇인가”보다 “무엇을 할 수 있는가”로 타입을 판단한다.
• ABC는 사용 방식에 따라 덕 타이핑을 깨뜨릴 수도, 유지할 수도 있다.
• 타입 힌트는 런타임에 무시되므로 덕 타이핑에 직접 영향을 주지 않는다.
• Protocol은 타입 힌트 + 정적 분석 환경에서 덕 타이핑 철학을 유지하는 수단이다.

“If it walks like a duck and quacks like a duck, it’s a duck.”

What is duck typing?

Duck typing is the programming philosophy of judging an object’s type by the methods and attributes it has, not by its class declaration. It is a common approach in dynamically typed languages such as Python, JavaScript, and Ruby.

Rather than checking the type explicitly, you simply call the behaviour you need. If the method or attribute exists, it works; if not, you get a runtime error.

class Duck:
    def sound(self):
        return "Quack!"

class Dog:
    def sound(self):
        return "Woof!"

class Robot:
    def sound(self):
        return "Beep!"

def make_sound(animal):
    # just call it, no type check
    print(animal.sound())

make_sound(Duck())   # Quack!
make_sound(Dog())    # Woof!
make_sound(Robot())  # Beep!

Duck, Dog, Robot — all are treated identically as long as they have a sound() method. The focus is on “what can this object do?” rather than “what is this object?”

Do ABCs break duck typing?

The short answer is not necessarily. It depends on how you use them.

Forcing an isinstance() check → duck typing broken

from abc import ABC, abstractmethod

class Animal(ABC):
    @abstractmethod
    def sound(self): pass

def make_sound(animal):
    if not isinstance(animal, Animal):  # checking the type directly!
        raise TypeError("not an Animal")
    print(animal.sound())

make_sound(Robot())  # ❌ rejected even though it has sound()

ABC as specification only, no check → duck typing preserved

If you do not check the type inside the function, duck typing keeps working even with an ABC in play. All the ABC does then is act as an agreement among developers: “this method must be implemented.”

A compromise with register()

Animal.register(Robot)  # register Robot as an Animal

print(isinstance(Robot(), Animal))  # ✅ True (passes without inheritance)

This is a middle ground that keeps duck typing’s flexibility while making partial use of the type system. The drawback is that a developer has to register things manually.

Type hints have nothing to do with duck typing

Type hints are completely ignored at runtime. Writing animal: Duck does not make the Python interpreter check anything during execution.

def make_sound(animal: Duck) -> str:
    return animal.sound()

make_sound(Robot())  # ✅ runs without any problem

What type hints actually do is this:

• Static analysis: type checkers like mypy and pyright warn you before the code runs
• IDE support: used for autocompletion and warnings
• Documentation: conveying intent to whoever reads the code

Wiring mypy into CI effectively constrains duck typing, but that is a check at development time. The runtime behaviour is still duck typing.

Protocol: duck typing for type hints

When you want to use mypy and still keep the spirit of duck typing, you use Protocol. The whole reason Protocol exists is type hints and static analysis.

from typing import Protocol

class Soundable(Protocol):
    def sound(self) -> str: ...

def make_sound(animal: Soundable) -> str:
    # "having a sound() method is enough"
    return animal.sound()

class Robot:  # without inheriting from Soundable
    def sound(self):
        return "Beep!"

make_sound(Robot())  # ✅ passes mypy, passes at runtime

This is called structural subtyping. It treats an object as belonging to a type if it has the required methods, with no inheritance relationship — the spirit of duck typing, implemented inside the world of type hints.

@runtime_checkable: using it at runtime too

from typing import Protocol, runtime_checkable

@runtime_checkable
class Soundable(Protocol):
    def sound(self) -> str: ...

print(isinstance(Robot(), Soundable))  # ✅ True
# checks for the presence of the methods automatically

This resembles an ABC’s register(), but there is no manual registration: the decision is made automatically from the presence of the methods.

Summary

• Duck typing judges a type by “what it can do”, not “what it is”.
• Depending on how you use them, ABCs can either break duck typing or preserve it.
• Type hints are ignored at runtime, so they do not directly affect duck typing.
• Protocol is the way to keep the duck typing philosophy in a type-hinted, statically analysed codebase.

$A\in\mathbb{R}^{m\times n},\ B\in\mathbb{R}^{n\times p}$

내적

$A$의 $i$번째 행을 $a_i^T$, $B$의 $j$번째 열을 $b_j$라 두면

그때 $C=AB$의 원소는

즉, “$C$의 $(i,j)$”는 $A$의 $i$번째 행과 $B$의 $j$번째 열의 내적이다.

rank-1 matrix들의 합

이번엔 $A$를 열벡터로, $B$를 행벡터로 풀어 쓰면,

• $a_k\in\mathbb{R}^{m}$: $A$의 $k$번째 열
• $b_k^T\in\mathbb{R}^{1\times p}$: $B$의 $k$번째 행

그럼 행렬곱은

즉 $AB$는 이런 rank-1 행렬들을 $k=1\sim n$까지 더한 것이다.

Column space 관점 = $Ax$

$A$를 열벡터로 나타내면,

그리고 $x\in\mathbb{R}^n$을

라고 하면,

$Ax$는 $A$의 열벡터 $a_k$들의 선형결합이라서 항상 $\mathrm{Col}(A)$에 있다.

Row space 관점 = $x^TA$

이번엔 $A$를 행벡터로 나타내면,

그리고 $x\in\mathbb{R}^m$을

라고 하면,

$x^T A$는 $A$의 행벡터 $a_i^T$들의 선형결합이라서 항상 $\mathrm{Row}(A)$에 있다.

$A\in\mathbb{R}^{m\times n},\ B\in\mathbb{R}^{n\times p}$

Inner products

Write the $i$-th row of $A$ as $a_i^T$ and the $j$-th column of $B$ as $b_j$:

Then the entries of $C=AB$ are

That is, “$(i,j)$ of $C$” is the inner product of the $i$-th row of $A$ and the $j$-th column of $B$.

A sum of rank-1 matrices

This time expand $A$ into column vectors and $B$ into row vectors:

• $a_k\in\mathbb{R}^{m}$: the $k$-th column of $A$
• $b_k^T\in\mathbb{R}^{1\times p}$: the $k$-th row of $B$

The product then becomes

So $AB$ is the sum of these rank-1 matrices over $k=1$ through $n$.

The column space view = $Ax$

Writing $A$ as column vectors,

and taking $x\in\mathbb{R}^n$ to be

we get

$Ax$ is a linear combination of the column vectors $a_k$ of $A$, so it always lies in $\mathrm{Col}(A)$.

The row space view = $x^TA$

Now write $A$ as row vectors,

and take $x\in\mathbb{R}^m$ to be

which gives

$x^T A$ is a linear combination of the row vectors $a_i^T$ of $A$, so it always lies in $\mathrm{Row}(A)$.

이런 것들을 떠올려 보자:

• 기술 전문 용어: “Gecko-Embeddings”
• 틈새 용어: “DeepLearningGenius”

모델이 이 단어들을 본 적이 없다면, 의미 없는 subword로 쪼갤 가능성이 크다 (예: “XIGN” + “CODE” 또는 “xig” + “##nco” + “##de”). 이러면 용어의 고유한 의미가 사라진다.

해법은 새 단어를 모델의 어휘에 추가하고, 그 의미를 학습하도록 fine-tuning하는 것이다. 이 글에서는 sentence-transformers 라이브러리를 예로 그 방법을 보인다.

새 단어를 추가하는 두 단계

새 단어를 추가하는 건 한 단계가 아니다. 모델의 “사전”(tokenizer)과 “뇌”(모델 가중치)를 둘 다 갱신해야 한다.

1. tokenizer 갱신: 먼저 새 단어가 하나의 완결된 단위로 존재한다고 tokenizer에게 알려준다. 이러면 subword로 쪼개지지 않는다.
2. 모델 갱신 및 fine-tuning: 단어를 추가하면 모델이 임베딩 행렬에 “자리”를 만들지만, 이 새 임베딩 벡터는 그저 랜덤 노이즈다. 아무 의미가 없다. 그 단어가 들어간 새 문장들로 모델을 반드시 fine-tuning해서, 맥락으로부터 단어의 의미를 배우게 해야 한다.

새 토큰 추가하기 (코드)

sentence-transformers로 모델을 불러오고 내부 tokenizer와 임베딩 행렬을 수정해 보자.

from sentence_transformers import SentenceTransformer
import torch

# 베이스 모델 로드
model_name = 'sentence-transformers/all-MiniLM-L6-v2'
model = SentenceTransformer(model_name)

# 1. 내부 tokenizer와 모델 얻기
# 수정하려면 하위의 'transformers' 모델에 접근해야 한다
tokenizer = model.tokenizer
transformer_model = model.auto_model

print(f"Original vocabulary size: {len(tokenizer)}")

# 2. 새 단어 정의
# 중요: 모델이 'cased'인지 'uncased'인지 먼저 확인할 것!
# 이 모델('all-MiniLM-L6-v2')은 uncased라서 전부 소문자로 바꾼다.
# 소문자 버전만 추가하면 된다.
# 'cased' 모델을 쓴다면 이렇게 추가할 수도 있다: ['XIGNCODE', 'xigncode', 'Xigncode']
new_words = ['xigncode']

# 3. tokenizer에 새 토큰 추가
num_added_toks = tokenizer.add_tokens(new_words)

if num_added_toks > 0:
    print(f"Added {num_added_toks} new tokens.")

    # 4. 모델의 토큰 임베딩 크기 조정
    # 새 토큰(들)을 위해 무작위로 초기화된 벡터가 추가된다
    transformer_model.resize_token_embeddings(len(tokenizer))

    print(f"New vocabulary size: {len(tokenizer)}")
else:
    print("Tokens already exist in the vocabulary.")

# tokenizer 테스트
test_sentence = "This is a test of xigncode and XIGNCODE3."
tokenized = tokenizer.tokenize(test_sentence)

print(f"Tokenization test: {tokenized}")
# 기대 출력: ['this', 'is', 'a', 'test', 'of', 'xigncode', 'and', 'xigncode', '3']

위 출력에서 두 가지를 눈여겨보자:

1. xigncode가 단일 토큰으로 인식됐다.
2. XIGNCODE3는 ['xigncode', '3']으로 토큰화됐다. “최장 일치” 규칙이 작동한 것이고, 우리가 원하던 결과다!

fine-tuning (의미 가르치기)

이제 모델이 “xigncode”를 인식 하니, 그것이 무엇을 의미하는지 가르쳐야 한다. 그 단어가 맥락 속에서 쓰인 문장들로 fine-tuning하면 된다.

from torch.utils.data import DataLoader
from sentence_transformers import InputExample, losses, models

# 1. 학습 예제 만들기
# 새 단어에 맥락을 제공하는 문장이 필요하다.
train_examples = [
    # 맥락 부여: "xigncode"는 "anti-cheat"과 관련이 있다
    InputExample(texts=['xigncode is an anti-cheat solution.', 'This software prevents cheating in online games.']),

    # 또 다른 맥락 부여:
    InputExample(texts=['Many gamers are familiar with xigncode.', 'It is a well-known security program.'])

    # 더 잘 배우려면 예제를 훨씬 많이 추가할 것...
]

# 2. 데이터로더와 손실 함수 설정
train_dataloader = DataLoader(train_examples, shuffle=True, batch_size=16)
train_loss = losses.MultipleNegativesRankingLoss(model=model)

# 3. 모델 fine-tuning
num_epochs = 1
warmup_steps = int(len(train_dataloader) * num_epochs * 0.1)

print("Starting fine-tuning...")
model.fit(
    train_objectives=[(train_dataloader, train_loss)],
    epochs=num_epochs,
    warmup_steps=warmup_steps,
    output_path='./my-finetuned-model',
    show_progress_bar=True
)

print("Fine-tuning complete. Model saved to './my-finetuned-model'.")

새 모델 사용하기 (LangChain과 함께)

더 똑똑해진 새 모델이 ./my-finetuned-model 디렉토리에 저장됐다. sentence-transformers에서 직접 불러올 수도 있고, 저장 경로만 가리키면 LangChain에서도 쓸 수 있다.

from langchain_huggingface import HuggingFaceEmbeddings

# 로컬에 fine-tuning된 모델 디렉토리를 가리킨다
model_path = "./my-finetuned-model"

# LangChain이 모델과 새 tokenizer를 함께 로드한다
embeddings = HuggingFaceEmbeddings(
    model_name=model_path,
    model_kwargs={'device': 'cpu'}, # 가능하면 'cuda'
    encode_kwargs={'normalize_embeddings': True}
)

# 이제 이 텍스트가 더 정확한 임베딩을 만든다
text = "Tell me about the xigncode anti-cheat."
query_embedding = embeddings.embed_query(text)

print("Successfully created embedding with the new word!")
print(f"Vector dimension: {len(query_embedding)}")

놓치기 쉬운 지점: 대소문자와 subword

기억해둘 만한 중요한 지점 몇 가지:

XIGNCODE vs. xigncode (대소문자 구분)

• Uncased 모델 (all-MiniLM-L6-v2 같은): 전부 자동으로 소문자화한다. 소문자 xigncode만 추가하면 된다. XIGNCODE, xigncode, XignCode 모두 매칭된다.
• Cased 모델 (bert-base-cased 같은): XIGNCODE와 xigncode를 서로 다른 단어로 취급한다. XIGNCODE를 추가하면 정확히 그 대소문자 형태만 매칭된다. cased 모델에서는 등장할 만한 변형들을 모두 추가해두는 편이 안전하다.

[UNK] vs. subword

• 애초에 왜 이걸 하나? 새 단어(예: xigncode)가 ['xig', '##nco', '##de']로 쪼개지는 걸 막기 위해서다. 이렇게 쪼개지면 용어의 고유한 의미가 사라진다.
• [UNK]가 되지는 않나? 현대 모델(BERT, RoBERTa 등)에서는 거의 절대 그렇지 않다. 이 모델들은 subword 기반이고, 어떤 미지의 단어든 구성 조각으로 쪼개도록 설계됐다. [UNK](Unknown) 토큰은 대체로 단어 기반의 옛 모델 (Word2Vec 같은)의 유물이거나, 입력에 tokenizer의 문자 집합을 완전히 벗어난 문자가 들어 있을 때만 쓰인다.

토큰을 추가하고 fine-tuning하는 것은 모델에게 이렇게 말하는 것이다. “이 단어를 그만 쪼개라! 하나로 취급하고, 이것 이 그 의미다.”

Think of:

• Technical Jargon: “Gecko-Embeddings”
• Niche Terms: “DeepLearningGenius”

If the model has never seen these words, it will likely tokenize them into meaningless subwords (e.g., “XIGN” + “CODE” or “xig” + “##nco” + “##de”). This loses the specific meaning of your term.

The solution is to add the new words to the model’s vocabulary and fine-tune it to learn their meaning. This post will show you how, using the sentence-transformers library as an example.

The Two-Step Process to Add New Words

Adding a new word isn’t just one step. You have to update both the model’s “dictionary” (the tokenizer) and its “brain” (the model weights).

1. Update the Tokenizer: You first tell the tokenizer that your new word exists as a single, complete unit. This prevents it from being broken into subwords.
2. Update the Model & Fine-Tune: After you add the word, the model creates a “slot” for it in its embedding matrix, but this new embedding vector is just random noise. It has no meaning. You must fine-tune the model on new sentences containing your word so it can learn what that word means from its context.

Adding a New Token (The Code)

Let’s use sentence-transformers to load a model and modify its internal tokenizer and embedding matrix.

from sentence_transformers import SentenceTransformer
import torch

# Load your base model
model_name = 'sentence-transformers/all-MiniLM-L6-v2'
model = SentenceTransformer(model_name)

# 1. Get the internal tokenizer and model
# We need to access the underlying 'transformers' model to modify it
tokenizer = model.tokenizer
transformer_model = model.auto_model

print(f"Original vocabulary size: {len(tokenizer)}")

# 2. Define your new words
# IMPORTANT: Check if your model is 'cased' or 'uncased' first!
# This model ('all-MiniLM-L6-v2') is uncased, so it lowercases everything.
# We only need to add the lowercase version.
# If using a 'cased' model, you might add: ['XIGNCODE', 'xigncode', 'Xigncode']
new_words = ['xigncode']

# 3. Add new tokens to the tokenizer
num_added_toks = tokenizer.add_tokens(new_words)

if num_added_toks > 0:
    print(f"Added {num_added_toks} new tokens.")

    # 4. Resize the model's token embeddings
    # This adds a new, randomly initialized vector for our new token(s)
    transformer_model.resize_token_embeddings(len(tokenizer))

    print(f"New vocabulary size: {len(tokenizer)}")
else:
    print("Tokens already exist in the vocabulary.")

# Test the tokenizer
test_sentence = "This is a test of xigncode and XIGNCODE3."
tokenized = tokenizer.tokenize(test_sentence)

print(f"Tokenization test: {tokenized}")
# Expected output: ['this', 'is', 'a', 'test', 'of', 'xigncode', 'and', 'xigncode', '3']

In the output above, notice two things:

1. xigncode was recognized as a single token.
2. XIGNCODE3 was tokenized as ['xigncode', '3']. This is the “longest-match” rule in action and is exactly what we want!

Fine-Tuning (Teaching the Meaning)

Now that our model recognizes “xigncode”, we need to teach it what it means. We do this by fine-tuning it on sentences where the word is used in context.

from torch.utils.data import DataLoader
from sentence_transformers import InputExample, losses, models

# 1. Create training examples
# We need sentences that provide context for our new word.
train_examples = [
    # Give it context: "xigncode" is related to "anti-cheat"
    InputExample(texts=['xigncode is an anti-cheat solution.', 'This software prevents cheating in online games.']),

    # Give it another context:
    InputExample(texts=['Many gamers are familiar with xigncode.', 'It is a well-known security program.'])

    # Add many more examples for better learning...
]

# 2. Setup dataloader and loss
train_dataloader = DataLoader(train_examples, shuffle=True, batch_size=16)
train_loss = losses.MultipleNegativesRankingLoss(model=model)

# 3. Fine-tune the model
num_epochs = 1
warmup_steps = int(len(train_dataloader) * num_epochs * 0.1)

print("Starting fine-tuning...")
model.fit(
    train_objectives=[(train_dataloader, train_loss)],
    epochs=num_epochs,
    warmup_steps=warmup_steps,
    output_path='./my-finetuned-model',
    show_progress_bar=True
)

print("Fine-tuning complete. Model saved to './my-finetuned-model'.")

Using Your New Model (with LangChain)

Your new, smarter model is now saved to the ./my-finetuned-model directory. You can load it directly in sentence-transformers or, as you originally asked, in LangChain by simply pointing to the saved path.

from langchain_huggingface import HuggingFaceEmbeddings

# Point to your local, fine-tuned model directory
model_path = "./my-finetuned-model"

# LangChain will load the model and its new tokenizer
embeddings = HuggingFaceEmbeddings(
    model_name=model_path,
    model_kwargs={'device': 'cpu'}, # Use 'cuda' if available
    encode_kwargs={'normalize_embeddings': True}
)

# This text now generates a more accurate embedding
text = "Tell me about the xigncode anti-cheat."
query_embedding = embeddings.embed_query(text)

print("Successfully created embedding with the new word!")
print(f"Vector dimension: {len(query_embedding)}")

Key Gotchas: Case Sensitivity & Subwords

Our conversation highlighted a few critical points to remember:

XIGNCODE vs. xigncode (Case Sensitivity)

• Uncased Models (like all-MiniLM-L6-v2): Automatically lowercase everything. You only need to add the lowercase xigncode. It will match XIGNCODE, xigncode, and XignCode.
• Cased Models (like bert-base-cased): Treat XIGNCODE and xigncode as two different words. If you add XIGNCODE, it will only match that exact capitalization. For cased models, it’s safer to add all common variations you expect to see.

[UNK] vs. Subwords

• Why do this at all? To prevent your new word (e.g., xigncode) from being split into ['xig', '##nco', '##de']. This splitting loses the unique meaning of the term.
• Will it become [UNK]? Almost never in modern models (like BERT, RoBERTa, etc.). These models are subword-based and are designed to split any unknown word into its component pieces. The [UNK] (Unknown) token is mostly a relic of older, word-based models (like Word2Vec) or is only used if the input contains a character that is completely outside the tokenizer’s character set.

By adding the token and fine-tuning, you are telling the model: “Stop splitting this word! Treat it as one thing, and this is what it means.”