내부 사용자 셀프 서비스

내부 사용자 셀프 서비스 (Internal User Self-Serve)

내부 사용자가 Proxy UI에서 자신의 키를 직접 만들 수 있게 해주는 기능이에요. 관리자가 역할과 예산을 설정해 두면, 사용자는 초대 링크로 로그인해 본인 키를 생성·조회·삭제하고 자신의 지출을 볼 수 있어요.

사용자가 Proxy UI에서 자신의 키를 만들 수 있게 하기

  1. 프록시에 팀 권한을 가진 사용자 추가
  • UI
  • API

Internal Users → +New User로 이동하세요.

LiteLLM에 새 Internal User를 만들고 internal_user 역할을 부여하세요.

    curl -X POST '<PROXY_BASE_URL>/user/new' \  
    -H 'Authorization: Bearer <PROXY...KEY>' \  
    -H 'Content-Type: application/json' \  
    -D '{  
        "user_email": "[email protected]",  
        "user_role": "internal_user" # 👈 THIS ALLOWS USER TO CREATE/VIEW/DELETE THEIR OWN KEYS + SEE THEIR SPEND  
    }'

예상 응답

    {  
        "user_id": "e9d45c7c-b20b-4ff8-ae76-3f479a7b1d7d", 👈 USE IN STEP 2  
        "user_email": "<YOUR_USERS_EMAIL>",  
        "user_role": "internal_user",  
        ...  
    }

LiteLLM 내부 사용자에게 사용 가능한 UI 역할은 다음과 같아요.

Admin 역할:

  • proxy_admin: 플랫폼의 관리자
  • proxy_admin_viewer: 로그인, 모든 키 조회, 모든 지출 조회 가능. 키 생성/삭제, 새 사용자 추가는 불가.

Internal User 역할:

  • internal_user: 로그인, 자신의 키 조회/생성/삭제, 자신의 지출 조회 가능. 새 사용자 추가는 불가.
  • internal_user_viewer: 로그인, 자신의 키 조회, 자신의 지출 조회 가능. 키 생성/삭제, 새 사용자 추가는 불가.
  1. 사용자와 초대 링크 공유
  • UI
  • API

사용자에게 초대 링크를 복사해 주세요.

    curl -X POST '<PROXY_BASE_URL>/invitation/new' \  
    -H 'Authorization: Bearer <PROXY...KEY>' \  
    -H 'Content-Type: application/json' \  
    -D '{  
        "user_id": "e9d45c7c-b20b..." # 👈 USER ID FROM STEP 1  
    }'

예상 응답

    {  
        "id": "a2f0918f-43b0-4770-a664-96ddd192966e",  
        "user_id": "e9d45c7c-b20b..",  
        "is_accepted": false,  
        "accepted_at": null,  
        "expires_at": "2024-06-13T00:02:16.454000Z", # 👈 VALID FOR 7d  
        "created_at": "2024-06-06T00:02:16.454000Z",  
        "created_by": "116544810872468347480",  
        "updated_at": "2024-06-06T00:02:16.454000Z",  
        "updated_by": "116544810872468347480"  
    }

초대 링크:

    http://0.0.0.0:4000/ui/onboarding?id=a2f0918f-43b0-4770-a664-96ddd192966e  
      
    # <YOUR_PROXY_BASE_URL>/ui/onboarding?id=<id>

info

사용자에게 온보딩 링크를 이메일로 보내려면 이메일 알림을 사용하세요.

  1. 사용자가 이메일 + 비밀번호 인증으로 로그인

info

LiteLLM Enterprise: SSO 로그인 활성화

  1. 사용자가 이제 자신의 키를 만들 수 있음

사용자가 Usage, Caching Analytics를 볼 수 있게 하기

  1. Internal Users → +Invite User로 이동

역할을 Admin Viewer로 설정하세요. 이는 사용량, 캐싱 분석만 조회할 수 있다는 뜻이에요.

  1. 사용자와 초대 링크 공유

  1. 사용자가 이메일 + 비밀번호 인증으로 로그인

  1. 사용자가 이제 Usage, Caching Analytics를 볼 수 있음

사용 가능한 역할

LiteLLM 내부 사용자에게 사용 가능한 UI 역할은 다음과 같아요.

Admin 역할:

  • proxy_admin: 플랫폼의 관리자
  • proxy_admin_viewer: 로그인, 모든 키 조회, 모든 지출 조회 가능. 키 생성/삭제, 새 사용자 추가는 불가.

Internal User 역할:

  • internal_user: 로그인, 자신의 키 조회/생성/삭제, 자신의 지출 조회 가능. 새 사용자 추가는 불가.
  • internal_user_viewer: 로그인, 자신의 키 조회, 자신의 지출 조회 가능. 키 생성/삭제, 새 사용자 추가는 불가.

팀 역할:

  • admin: 팀에 새 멤버 추가, 팀 권한 제어, 팀 전용 모델 추가(팀의 파인튜닝 모델을 온보딩할 때 유용) 가능.
  • user: 로그인, 자신의 키 조회, 자신의 지출 조회 가능. 키 생성/삭제(팀 권한으로 제어 가능), 새 사용자 추가는 불가.

SSO 사용자를 팀에 자동 추가

Okta, Google SSO에 대한 SSO 자동 추가 설정을 다뤄요.

Okta, Google SSO

  1. 사용자가 속한 팀 id를 담은 JWT 필드를 지정하세요.
    general_settings:  
      master_key: os.environ/LITELLM_MASTER_KEY  
      litellm_jwtauth:  
        team_ids_jwt_field: "groups" # 👈 CAN BE ANY FIELD

SSO 토큰이 이런 형태라고 가정해요. LiteLLM이 SSO 제공자로부터 받은 JWT 필드를 검사해야 한다면 이 지침을 따르세요.

    {  
      ...,  
      "groups": ["team_id_1", "team_id_2"]  
    }
  1. LiteLLM에 팀 생성
    curl -X POST '<PROXY_BASE_URL>/team/new' \  
    -H 'Authorization: Bearer <PROXY...KEY>' \  
    -H 'Content-Type: application/json' \  
    -D '{  
        "team_alias": "team_1",  
        "team_id": "team_id_1" # 👈 MUST BE THE SAME AS THE SSO GROUP ID  
    }'
  1. SSO 흐름 테스트

동작 방식 워크스루를 참고하세요.

Microsoft Entra ID SSO 그룹 할당

Microsoft Entra ID로 SSO 사용자를 팀에 자동 추가하는 튜토리얼을 따라가세요.

SSO JWT 필드 디버깅

여기로 이동

고급

커스텀 로그아웃 URL 설정

사용자가 로그아웃을 클릭했을 때 특정 URL로 리다이렉트되게 하려면 .env에 PROXY_LOGOUT_URL을 설정하세요.

    export PROXY_LOGOUT_URL="https://www.google.com"

내부 사용자 기본 최대 예산 설정

내부 사용자가 가입할 때 예산을 자동으로 적용해요. 기본적으로 사용자 리셋을 위해 테이블이 10분마다 확인돼요. 변경하려면 이 문서를 참고하세요.

    litellm_settings:  
      max_internal_user_budget: 10  
      internal_user_budget_duration: "1mo" # reset every month

이렇게 하면 내부 사용자가 가입할 때 최대 예산 $10 USD가 설정돼요.

이 설정들을 UI에서 시각적으로 관리할 수도 있어요:

이 예산은 그 사용자가 만든 개인 키에만 적용돼요. UI의 Default Team 아래에 보여요.

이 예산은 기본 팀이 아닌 팀 아래에서 만든 키에는 적용되지 않아요.

사용자의 개인 max_budget은 UI에서 만드는 개인 키의 상한이기도 해요. $500 예산의 사용자는 max_budget $100인 개인 키를 만들 수 있지만, $600 요청은 max_budget (600.0) cannot exceed the caller's own max_budget (500.0)로 거부돼요. 개인 예산이 없는 사용자는 UI 세션 예산(max_ui_session_budget, 기본 $1, null은 상한 제거)이 명시적 키 max_budget의 상한으로 폴백돼요. 키에 max_budget을 두지 않으면 키 수준 상한이 없어지고, 그 키의 지출은 여전히 사용자 자신의 예산으로 제한돼요. /user/update, /user/bulk_update 또는 Internal Users 페이지를 통해 사용자의 max_budget을 바꾸면 업데이트를 처리한 인스턴스에 즉시 반영돼요. Redis가 구성되면 변경사항이 다른 프록시 인스턴스에도 브로드캐스트돼요. Redis가 없으면 다른 인스턴스는 캐시된 사용자 레코드가 만료될 때까지(약 60초) 이전 상한을 계속 적용할 수 있어요.

팀 최대 예산 설정

여기로 이동

기본 팀(Default Team)

  • UI
  • YAML

Internal Users → Default User Settings로 가서 방금 만든 팀을 기본 팀으로 설정하세요.

기본 모델도 no-default-models로 설정해 보세요. 이러면 사용자는 팀 안에서만 키를 만들 수 있게 돼요.

info

기본 팀으로 설정하기 전에 팀을 먼저 만들어야 해요.

    litellm_settings:  
      default_internal_user_params:    # Default Params used when a new user signs in Via SSO  
          user_role: "internal_user"     # one of "internal_user", "internal_user_viewer",   
          models: ["no-default-models"] # Optional[List[str]], optional): models to be used by the user  
          teams: # Optional[List[NewUserRequestTeam]], optional): teams to be used by the user  
            - team_id: "team_id_1" # Required[str]: team_id to be used by the user  
              user_role: "user" # Optional[str], optional): Default role in the team. Values: "user" or "admin". Defaults to "user"

팀 멤버 예산

팀의 각 멤버에게 적용되는 기본 최대 예산을 설정해요.

새 팀을 만들 때나 기존 팀을 업데이트할 때 설정할 수 있어요.

team_member_budget은 팀 전체에 적용되는 단일 기본값이에요. 자신의 max_budget_in_team 없이 추가된 모든 멤버는 이 값에 연결돼요. 그래서 /team/update(또는 UI의 팀 Default Budget 필드)로 바꾸면 나중에 추가되는 멤버뿐 아니라 이미 추가된 멤버에게도 다음 요청부터 적용돼요. /team/member_add에서 max_budget_in_team을 받거나 나중에 /team/member_update로 편집한 멤버는 자신의 예산을 갖게 되고 팀 기본값을 따르지 않아요.

  • UI
  • API

    curl -X POST '<PROXY_BASE_URL>/team/new' \  
    -H 'Authorization: Bearer <PROXY...KEY>' \  
    -H 'Content-Type: application/json' \  
    -D '{  
        "team_alias": "team_1",  
        "budget_duration": "10d",  
        "team_member_budget": 10  
    }'

info

기존 팀에 team_member_budget을 설정하면 아직 예산이 없는 모든 멤버에 연결되고, 그 멤버들이 이미 쌓은 지출이 즉시 그 예산에 집계돼요. 새 예산을 이미 초과한 멤버를 해제하는 방법은 나중에 추가된 예산에 기존 지출이 집계됨을 참고하세요.

팀 멤버 레이트 리밋

개별 팀 멤버에 기본 tpm/rpm 한도를 설정해요.

새 팀을 만들 때나 기존 팀을 업데이트할 때 설정할 수 있어요.

  • UI
  • API

    curl -X POST '<PROXY_BASE_URL>/team/new' \  
    -H 'Authorization: Bearer <PROXY...KEY>' \  
    -H 'Content-Type: application/json' \  
    -D '{  
        "team_alias": "team_1",  
        "team_member_rpm_limit": 100,  
        "team_member_tpm_limit": 1000  
    }'

새 팀의 기본 파라미터 설정

litellm을 SSO 제공자에 연결하면 litellm이 팀을 자동 생성할 수 있어요. 자동 생성된 팀의 기본 models, max_budget, budget_duration을 설정하려면 이 기능을 사용하세요.

동작 방식

  1. litellm이 SSO 제공자에서 groups를 가져올 때, 해당 group_id가 litellm에 team_id로 존재하는지 확인해요.
  2. team_id가 없으면 litellm이 설정한 기본 파라미터로 팀을 자동 생성해요.
  3. team_id가 이미 존재하면 litellm은 팀에 아무 설정도 적용하지 않아요.

사용법

새 팀의 기본 파라미터

    litellm_settings:  
      default_team_params:             # Applied to all /team/new calls (including SSO auto-created teams) when the field is omitted or null; an explicit budget_duration: null is honored  
        max_budget: 100                # Optional[float]: $100 budget for the team  
        budget_duration: 30d           # Optional[str]: 30 days budget_duration for the team  
        models: ["gpt-5.6-luna"]      # Optional[List[str]]: models for the team (only applied to SSO auto-created teams)  
        tpm_limit: 100000              # Optional[int]: tokens per minute limit  
        rpm_limit: 1000                # Optional[int]: requests per minute limit  
        team_member_permissions:       # Optional[List[str]]: permissions granted to non-admin team members  
          - "/team/daily/activity"     # Allow members to view team usage  
          - "/key/generate"            # Allow members to generate API keys

info

이 기본값들은 /team/new 요청에서 빠졌거나 null인 모든 필드를 채워요. budget_duration은 예외예요. 명시적으로 "budget_duration": null(UI 생성 폼의 "Never resets" 옵션)을 보내면 예산이 절대 리셋되지 않는 팀이 만들어져 구성된 기본값을 건너뛰어요.

사용자가 개인 키를 만들지 못하게 제한

사용자가 특정 팀 아래에서만 키를 만들게 하고 싶다면 유용해요.

또한 사용자가 세션 토큰을 테스트 키 채팅 창에 사용하지 못하게도 해요.

👉 여기 보기

Self Serve / SSO 흐름의 모든 설정

Self Serve / SSO 흐름의 모든 설정

    litellm_settings:  
      max_internal_user_budget: 10        # max budget for internal users  
      internal_user_budget_duration: "1mo" # reset every month  
      
      default_internal_user_params:    # Default Params used when a new user signs in Via SSO  
        user_role: "internal_user"     # one of "internal_user", "internal_user_viewer", "proxy_admin", "proxy_admin_viewer". New SSO users not in litellm will be created as this user  
        max_budget: 100                # Optional[float], optional): $100 budget for a new SSO sign in user  
        budget_duration: 30d           # Optional[str], optional): 30 days budget_duration for a new SSO sign in user  
        models: ["gpt-5.6-luna"]      # Optional[List[str]], optional): models to be used by a new SSO sign in user  
        teams: # Optional[List[NewUserRequestTeam]], optional): teams to be used by the user  
          - team_id: "team_id_1" # Required[str]: team_id to be used by the user  
            max_budget_in_team: 100 # Optional[float], optional): $100 budget for the team. Defaults to None.  
            user_role: "user" # Optional[str], optional): "user" or "admin". Defaults to "user"  
        
      default_team_params:             # Applied to all /team/new calls (including SSO auto-created teams) when the field is omitted or null; an explicit budget_duration: null is honored  
        max_budget: 100                # Optional[float]: $100 budget for the team  
        budget_duration: 30d           # Optional[str]: 30 days budget_duration for the team  
        models: ["gpt-5.6-luna"]      # Optional[List[str]]: models for the team (only applied to SSO auto-created teams)  
        tpm_limit: 100000              # Optional[int]: tokens per minute limit  
        rpm_limit: 1000                # Optional[int]: requests per minute limit  
        team_member_permissions:       # Optional[List[str]]: permissions granted to non-admin team members  
          - "/team/daily/activity"  
      
      
      upperbound_key_generate_params:    # Upperbound for /key/generate requests when self-serve flow is on  
        max_budget: 100 # Optional[float], optional): upperbound of $100, for all /key/generate requests  
        budget_duration: "10d" # Optional[str], optional): upperbound of 10 days for budget_duration values  
        duration: "30d" # Optional[str], optional): upperbound of 30 days for all /key/generate requests  
        max_parallel_requests: 1000 # (Optional[int], optional): Max number of requests that can be made in parallel. Defaults to None.  
        tpm_limit: 1000 #(Optional[int], optional): Tpm limit. Defaults to None.  
        rpm_limit: 1000 #(Optional[int], optional): Rpm limit. Defaults to None.  
      
      key_generation_settings: # Restricts who can generate keys. [Further docs](./virtual_keys.md#restricting-key-generation)  
        team_key_generation:  
          allowed_team_member_roles: ["admin"]  
        personal_key_generation: # maps to 'Default Team' on UI   
          allowed_user_roles: ["proxy_admin"]

더 읽어보기