모델 관리

모델 관리 (Model Management)

STORE_MODEL_IN_DB가 켜져 있으면 모델이 정적 config.yaml이 아니라 데이터베이스에 살아요. 즉 day-2 변경이 Admin UI에서 바로 일어나요. 모델 추가, 가격 편집, 프로바이더 키 회전, 배포 은퇴 모두 config 편집이나 프록시 재시작 없이 가능해요.

이 페이지는 그 운영 작업들을 다루어요. 첫 모델을 추가하려는 경우 Quickstart부터 시작하세요. 게이트웨이가 실행 중일 때 이 페이지로 돌아와 보유한 모델을 관리하세요.

출처: 문서

본문

모델 목록 (The model list)

Models + Endpoints로 가서 All Models 탭을 열면 게이트웨이가 현재 서빙하는 모든 모델을 볼 수 있어요. 각 행은 공용 모델 이름, 기본 프로바이더·litellm 모델, 그리고 LiteLLM이 모델 비용 맵에서 자동 매핑하는 입력·출력 토큰당 비용을 보여줘요.

각 모델의 배지가 그 원천을 알려줘요. UI나 API를 통해 추가된 모델은 database 배지를, config.yaml에서 로드된 모델은 config로 표시돼요. 이 구분은 중요해요. config 모델은 UI에서 편집할 수 없기 때문이에요(data base vs config.yaml 모델 참조). 검색 상자와 프로바이더 필터로 긴 목록을 원하는 모델로 좁혀요.

모델 검사·편집

목록에서 Model ID를 클릭해 상세 페이지를 열어요. Overview 탭은 모델 설정과 프로바이더를 요약하고, Raw JSON 탭은 전체 저장된 정의를 보여줘서 게이트웨이가 정확히 무엇을 보유하고 있는지 확인하고 싶을 때 유용해요.

Edit Settings를 클릭해 모델을 제자리에서 변경해요. 클라이언트가 호출하는 공용 모델 이름, 요청이 라우팅되는 litellm 모델 이름, 그리고 매핑된 가격을 재정의하고 싶을 때 1M 토큰당 입력·출력 비용을 업데이트할 수 있어요. 저장하면 새 요청에 즉시 적용돼요.

이 페이지에는 두 가지 동작이 더 있어요. Test Connection은 저장된 자격증명으로 모델을 프로바이더에 재검증해, 키가 여전히 동작하는지 또는 새로 편집된 설정이 클라이언트가 히트하기 전에 유효한지 확인할 수 있어요. Delete Model은 게이트웨이에서 모델을 제거하며, 데이터베이스 모델은 저장된 정의를 완전히 삭제해요.

재사용 가능한 프로바이더 자격증명

대부분 배포는 같은 프로바이더 계정 뒤에 여러 모델을 두어요. 모든 모델에 같은 API 키를 붙여넣기 대신, 이름 있는 자격증명을 한 번 만들고 재사용해요.

LLM Credentials 탭을 열고 Add Credential을 클릭해요. 프로바이더를 고르고 API 키를 입력한 뒤 자격증명에 이름을 주세요. 필드는 선택한 프로바이더에 맞춰져요. 예를 들어 Vertex AI를 선택하면 단일 키 필드 대신 Vertex Project, Vertex Location, Vertex Credentials를 줘요.

저장된 뒤 자격증명은 모델을 추가·편집하는 어디서든 사용 가능해요. Add Model 양식에서 키를 입력하는 대신 Existing Credentials 드롭다운에서 골라요. 모델 상세 페이지에서 반대 방향으로도 갈 수 있는데, 이미 구성한 모델의 자격증명을 향후 모델용 이름 있는 자격증명으로 바꾸는 Re-use Credentials 버튼이에요. 이름 있는 자격증명에 연결된 모델은 Usage 페이지에서 Credential: <name>으로 태그되어 추가 설정 없이 자격증명별 지출을 필터링할 수 있어요(자격증명 사용 추적 참조).

데이터베이스 vs config.yaml 모델

모델을 데이터베이스에 저장하는 것이 UI 주도 관리를 가능하게 해요. 환경 변수로 STORE_MODEL_IN_DB="True"를, 또는 config에서 general_settings.store_model_in_db: true를 설정해 켜요. UI의 Models + Endpoints 설정에서 런타임에 토글할 수도 있는데, config 편집이 전체 릴리스를 의미하는 클라우드 배포에 유용해요. UI 값이 config 값을 재정의해요.

활성화되면 UI나 API로 추가하는 모든 모델이 데이터베이스에 지속되어 재시작과 추가 프록시 인스턴스를 견뎌요. 그 모델들의 프로바이더 자격증명은 LITELLM_SALT_KEY를 사용해 저장 시 암호화되며(솔트 키가 설정되지 않았으면 LITELLM_MASTER_KEY로 대체), 그 값을 비밀로 유지하고 모델이 생긴 뒤에는 절대 변경하지 마세요. 옛 값으로 암호화된 자격증명은 새 값으로 복호화할 수 없기 때문이에요.

데이터베이스 저장은 config.yaml을 대체하지 않아요. 거기 정의된 모델은 계속 동작하고 데이터베이스 모델 옆에 나타나요. 유일한 차이는 config 모델이 파일이 소유하므로 UI에서 편집·삭제할 수 없다는 것이에요. config에서 변경하고 다시 로드하세요. config 형식 자체는 Config.yaml 참조.

여기서 설정은 모델과 다르게 행동해요. UI가 general_settings, router_settings, litellm_settings, environment_variables에 쓰는 모든 것은 LiteLLM_Config에 저장되고 시작 시 config.yaml 위에 겹쳐져 데이터베이스 값이 이겨요. YAML에서 같은 키를 편집한 뒤 재시작해도 적용되지 않아요. config.yaml vs 데이터베이스 설정 참조.

모델의 단일 소스 선택

프로덕션 배포에서는 모델 정의의 기본 소스 하나를 사용해요.

LiteLLM은 파일 기반과 데이터베이스 기반 모델을 동시에 로드할 수 있지만, 둘 다 모델 관리 시스템으로 사용하면 두 개의 소스가 되어요. config.yaml에서 로드된 모델은 그 파일이 소유하므로 UI를 통해 편집·삭제할 수 없어요. 모델 정의를 한 시스템에 유지하고, 관리 API로 노출되지 않는 인프라 설정에는 config.yaml 또는 환경 변수를 계속 사용하세요.

LiteLLM Terraform 프로바이더는 Admin UI가 사용하는 것과 같은 관리 API를 호출해요. 리소스를 LiteLLM 데이터베이스에 지속하므로 별도 REST 클라이언트를 만들거나 모델 변경을 위해 프록시를 재시작할 필요가 없어요.

자동화 (API)

같은 작업을 HTTP로도 할 수 있는데, CI/CD나 스크립트 대량 변경에 원하는 것이에요. 이 엔드포인트들은 store_model_in_db가 활성화되어야 해요. 꺼져 있으면 POST /model/new가 실패합니다. 모델을 지속할 곳이 없기 때문이에요.

모델 추가:

curl -X POST "http://0.0.0.0:4000/model/new" \
    -H "Authorization: Bearer $LITEL..._KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model_name": "azure-gpt-4o",
      "litellm_params": {
        "model": "azure/gpt-5.6-terra",
        "api_key": "os.environ/AZURE_API_KEY",
        "api_base": "https://my-endpoint.openai.azure.com/"
      }
    }'

나머지 작업:

모델을 만들거나 업데이트할 때 임의 model_info 필드를 연결할 수 있고, 매핑된 비용·컨텍스트 데이터와 함께 GET /model/info로 그대로 통과해요. 이는 소유 팀, 설명, 버전 같은 자체 메타데이터로 모델을 주석 처리하고 프로그래밍 방식으로 읽는 메커니즘이에요.

더 알아보기 (Learn more)

• 모델 액세스
• 모델 액세스 그룹