Gemini 모델 이름 꼬인다? Model Registry로 2026년엔 끝내자!

Gemini 모델 이름, 이거 진짜 헷갈리더라. 프로젝트마다, 심지어 같은 프로젝트 안에서도 모델 이름이 제멋대로 불리는 바람에 코드 여기저기서 모델을 찾아 헤매는 일이 빈번했지. 2026년 들어서도 이 문제는 여전했어.

시도와 함정

처음에는 간단하게 네이밍 컨벤션을 정해서 사용하려고 했어. 예를 들어 gemini-1.5-pro-latest 이런 식으로 말이야. 그런데 이게 생각보다 잘 안 지켜지더라. 누군가는 gemini-1.5-pro-v2라고 쓰고, 또 다른 누군가는 gemini-pro-1.5라고 쓰기도 했지.

# 모델을 로드하는 흔한 코드 (하지만 이름이 달라서 문제가 생김)
from google.generativeai import GenerativeModel

# 1. 이런 이름으로 로드 시도
try:
    model_a = GenerativeModel("gemini-1.5-pro-latest")
    print("gemini-1.5-pro-latest 로드 성공!")
except Exception as e:
    print(f"gemini-1.5-pro-latest 로드 실패: {e}")

# 2. 다른 이름으로 로드 시도
try:
    model_b = GenerativeModel("gemini-pro-1.5-v2")
    print("gemini-pro-1.5-v2 로드 성공!")
except Exception as e:
    print(f"gemini-pro-1.5-v2 로드 실패: {e}")

위 코드처럼 같은 모델인데도 이름만 다르면 로드에 실패하는 경우가 허다했어. 심지어 AttributeError나 ValueError가 뜨면서 내 코드가 왜 동작하지 않는지 한참을 파악해야 했다니까. 3시간 삽질 끝에 발견한 건, 결국 모델 이름이 제각각이라는 거였지.

원인

결국 문제는 모델 이름 관리의 부재였어. 중앙에서 모델 이름을 관리하는 시스템이 없으니, 개발자마다 임의로 이름을 붙이고 사용하면서 혼란이 가중된 거지. Gemini API 자체의 문제는 아니었지만, 우리가 모델을 어떻게 참조하느냐에 달린 문제였어.

해결

이 문제를 해결하기 위해 Model Registry를 도입하기로 했어. 간단하게 파이썬 딕셔너리를 사용해서 모델 이름과 해당 모델을 로드할 때 필요한 이름을 매핑하는 방식을 썼지.

import google.generativeai as genai
2026년 현재, Gemini API 키 설정 (실제 키 사용)
genai.configure(api_key="YOUR_GEMINI_API_KEY") # 실제 API 키로 대체하세요.
class GeminiModelRegistry:
def init(self):
self.models = {
"gemini-1.5-pro": "gemini-1.5-pro-001", # 실제 모델 ID
"gemini-1.5-flash": "gemini-1.5-flash-001",
"gemini-1.0-pro": "gemini-1.0-pro-latest",
}
self.loaded_models = {}
def get_model(self, model_alias: str):
    """
    별칭(alias)을 받아 실제 모델을 로드하거나 반환합니다.
    """
    if model_alias not in self.models:
        raise ValueError(f"'{model_alias}'에 해당하는 모델을 찾을 수 없습니다. 등록된 모델: {list(self.models.keys())}")

    if model_alias not in self.loaded_models:
        actual_model_name = self.models[model_alias]
        print(f"'{model_alias}' (실제 이름: '{actual_model_name}') 모델을 로드합니다...")
        try:
            self.loaded_models[model_alias] = genai.GenerativeModel(actual_model_name)
            print(f"'{model_alias}' 로드 성공!")
        except Exception as e:
            print(f"'{model_alias}' 로드 실패: {e}")
            raise e
    return self.loaded_models[model_alias]

Model Registry 인스턴스 생성
model_registry = GeminiModelRegistry()
이제 모델을 사용할 때는 항상 registry를 통해 접근
try:
pro_model = model_registry.get_model("gemini-1.5-pro")
print(f"사용할 모델: {pro_model.model_name}")
# pro_model.generate_content(...) 와 같이 사용
except ValueError as e:
print(e)
try:
flash_model = model_registry.get_model("gemini-1.5-flash")
print(f"사용할 모델: {flash_model.model_name}")
# flash_model.generate_content(...) 와 같이 사용
except ValueError as e:
print(e)
존재하지 않는 모델 요청 시
try:
non_existent_model = model_registry.get_model("gemini-ultra-1.0")
except ValueError as e:
print(e)

이렇게 GeminiModelRegistry 클래스를 만들어서, 우리가 사용하는 모델 별칭(alias)과 실제 Gemini API에서 사용하는 모델 이름(actual model name)을 매핑했어. 이제 코드에서는 항상 model_registry.get_model("gemini-1.5-pro") 와 같이 별칭으로 모델을 가져오면 돼.

이 방식은 모델 이름이 변경되더라도, GeminiModelRegistry 클래스만 수정하면 되기 때문에 코드 전반에 걸쳐 일관성을 유지할 수 있었어.

결과

• 코드 전반에 걸쳐 Gemini 모델 이름 사용의 일관성 확보
• 모델 이름 변경 시 영향 범위 최소화 및 관리 용이성 향상
• 모델 로드 실패 시 원인 파악 시간 단축 (등록된 모델 이름만 확인하면 되니까)

정리 — 같은 함정 안 빠지려면

• [ ] 새로운 Gemini 모델을 사용하게 되면, 가장 먼저 Model Registry에 해당 모델의 별칭과 실제 모델 이름을 등록할 것.
• [ ] 코드에서는 모델을 직접 로드하는 대신, 항상 Model Registry를 통해 모델 인스턴스를 가져올 것.
• [ ] Model Registry는 중앙 집중식으로 관리하여 모든 팀원이 동일한 레지스트리를 사용하도록 할 것.