LiteLLM으로 Gemini 연결하기: 프록시 구성과 관리자 화면 설정

from litellm import completion

response = completion(
    model="gemini/gemini-2.0-flash",
    messages=[{"role": "user", "content": "안녕하세요"}],
)
print(response.choices[0].message.content)

Gemini를 부르는 코드는 이게 전부입니다. 이 글이 다루는 것은 이 코드를 웹서비스에 올린 다음입니다. 서버가 한 대이고 호출하는 앱도 하나라면 이대로 써도 됩니다. 앱이 둘이 되거나 누가 얼마를 썼는지 화면으로 보고 싶어지면, 같은 LiteLLM을 프록시로 세워야 합니다. SDK와 프록시가 어떻게 갈라졌는지는 LiteLLM의 역사 글에 정리해 두었고, 여기서는 Gemini 하나를 기준으로 키 발급부터 관리자 화면까지 따라갑니다.

호출 한 번으로 끝나는 Gemini 연동, 키 발급부터

LiteLLM은 모델 이름 앞에 제공사 경로를 붙여 요청을 보낼 곳을 정합니다. Gemini는 gemini/이고, 인증은 GEMINI_API_KEY 환경변수 하나입니다. 키는 Google AI Studio에서 발급받고, 코드에 적지 말고 환경변수로 넘깁니다.

pip install litellm
export GEMINI_API_KEY="발급받은 키"

응답은 어느 제공사를 쓰든 OpenAI 응답 형식이라 response.choices[0].message.content로 꺼냅니다. 모델 이름은 자주 바뀝니다. 위 예의 gemini-2.0-flash는 LiteLLM 문서의 표기를 따른 것이고, 실제로 쓸 이름은 Google AI Studio의 모델 목록에서 확인하는 편이 안전합니다.

앱마다 Gemini 키를 들고 있을 때 생기는 문제

웹서비스 백엔드, 관리자 도구, 배치 스크립트가 각자 GEMINI_API_KEY를 들고 있다고 해 봅시다. 키가 새면 어느 쪽에서 샜는지 알 수 없고, 한 곳만 막으려 해도 키를 통째로 폐기해야 합니다. 누가 얼마를 썼는지 보려면 앱마다 직접 기록하는 코드를 넣어야 합니다.

프록시는 이 키를 한곳에 모읍니다. Gemini 키는 프록시만 갖고, 앱에는 프록시가 발급한 가상 키(virtual key)를 줍니다. 앱 하나가 문제를 일으키면 그 앱의 가상 키만 끄면 됩니다.

프록시 설정 파일 하나에 모델 별칭 정하기

프록시는 config.yaml에 모델 목록을 적어 둡니다.

model_list:
  - model_name: gemini-flash
    litellm_params:
      model: gemini/gemini-2.0-flash
      api_key: os.environ/GEMINI_API_KEY

model_name은 앱이 부르는 이름이고, litellm_params.model이 실제로 호출되는 모델입니다. 앱은 gemini-flash만 알면 되므로 나중에 Gemini 버전을 올려도 앱 코드는 그대로 둘 수 있습니다. os.environ/GEMINI_API_KEY는 설정 파일에 키를 적지 않고 환경변수에서 읽겠다는 표기입니다.

관리자 화면까지 띄우는 Docker Compose 구성

가상 키와 관리자 화면에는 Postgres가 필요합니다. LiteLLM 문서는 키 관리, 관리자 화면(/ui), 비용 추적에 Postgres(DATABASE_URL)와 LITELLM_MASTER_KEY가 필요하다고 적고 있습니다. 데이터베이스를 따로 설치하지 않아도 되도록, 공식 퀵스타트는 프록시와 Postgres를 함께 올리는 Compose 파일을 제공합니다.

curl -sSLO https://github.com/BerriAI/litellm/raw/main/docker/docker-compose.quickstart.yml
docker compose -f docker-compose.quickstart.yml up -d

실행 전에 마스터 키를 정해 두어야 합니다. 문서 기준으로 마스터 키가 없으면 프록시가 시작하지 않습니다. 마스터 키는 sk-로 시작해야 하고, 다른 키를 만드는 관리자 권한을 가집니다. 퀵스타트는 솔트 키(LITELLM_SALT_KEY)도 함께 정하도록 안내하는데, 이 키는 관리자 화면에서 입력한 제공사 키를 암호화하는 데 쓰입니다. 올라오면 http://localhost:4000/ui에서 관리자 화면이 열립니다.

가상 키를 발급해 웹서비스에 연결하는 순서

관리자 화면에서는 모델 추가, 키 발급, 지출 확인을 모두 브라우저로 합니다. 위 config.yaml에 적은 모델 내용은 관리자 화면의 모델 추가 메뉴에서 같은 값으로 입력할 수도 있습니다. 로그인 방법은 버전에 따라 안내가 달라질 수 있으니 퀵스타트 문서를 따라 주세요.

모델을 넣었으면 Virtual Keys 메뉴에서 + Create New Key를 눌러 키 이름을 정하고 만듭니다. 저는 앱 하나에 키 하나를 주는 쪽을 권합니다. 이름을 앱 이름으로 붙이면 지출 화면에서 어느 앱이 쓴 돈인지 바로 보이고, 문제가 생긴 앱의 키만 끌 수 있습니다. 키를 만들 때 쓸 수 있는 모델을 제한하거나 예산을 걸 수도 있어서, 관리자 도구용 키에는 Gemini 호출만 허용하는 식으로 범위를 좁힐 수 있습니다.

웹서비스 쪽 코드는 OpenAI 클라이언트의 주소만 프록시로 바꾸면 됩니다.

import openai

client = openai.OpenAI(
    api_key="sk-발급받은-가상-키",
    base_url="http://localhost:4000",
)

response = client.chat.completions.create(
    model="gemini-flash",
    messages=[{"role": "user", "content": "안녕하세요"}],
)
print(response.choices[0].message.content)

백엔드가 Node.js라면 openai 패키지에서 baseURL만 같은 주소로 지정하면 됩니다. 앱은 이제 Gemini 키를 모르고, model에는 프록시에서 정한 별칭을 적습니다.

서버에서만 쓰는 키와 브라우저에 내려가는 응답의 구분

저라면 가상 키를 브라우저에 내려보내지 않겠습니다. 가상 키도 호출 권한을 가진 키라서, 화면 코드에 넣으면 누구든 꺼내 쓸 수 있습니다. 브라우저는 우리 백엔드 경로만 부르고, 그 백엔드가 가상 키로 프록시를 부르는 구조가 안전합니다. 관리자 화면(/ui)도 바깥에 열어 둘 이유가 없다면 내부 주소로만 접근하게 두는 편이 낫다고 봅니다.

문서로 확인한 부분과 직접 확인해야 할 부분

이 글의 명령과 설정은 LiteLLM 공식 문서를 기준으로 썼습니다. 버전에 따라 달라질 수 있는 것은 Gemini 모델 이름, 관리자 화면의 메뉴 이름과 로그인 방식, Compose 파일이 요구하는 환경변수입니다. 시작하기 전에 퀵스타트 문서와 한 번 대조해 보세요.

Redis는 이 구성에 필요하지 않습니다. 프록시를 여러 대로 늘리면 달라집니다. 문서는 키, 팀, 사용자별 속도 제한(TPM, RPM)을 Redis로 집행한다고 안내합니다.

참고: Gemini 연동 문서, 프록시 퀵스타트, 가상 키 문서, 멀티 리전 배포 문서