Zum Hauptinhalt springen

Virtuelle Schlüssel

Ausgaben verfolgen und Modellzugriff über virtuelle Schlüssel für den Proxy steuern

Info

Einrichtung​

Anforderungen

  • Benötigt eine PostgreSQL-Datenbank (z.B. Supabase, Neon, etc.)
  • Setzen Sie DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<dbname> in Ihrer Umgebungsvariablen.
  • Setzen Sie einen Master Key. Dies ist Ihr Proxy-Admin-Schlüssel. Sie können ihn verwenden, um andere Schlüssel zu erstellen (🚨 muss mit sk- beginnen).
    • In config.yaml festlegen Setzen Sie Ihren Master Key unter general_settings:master_key, Beispiel unten
    • Umgebungsvariable festlegen Setzen Sie LITELLM_MASTER_KEY

(Der Proxy-Dockerfile prüft, ob DATABASE_URL gesetzt ist, und initialisiert dann die DB-Verbindung)

export DATABASE_URL=postgresql://<user>:<password>@<host>:<port>/<dbname>

Anschließend können Sie Schlüssel generieren, indem Sie den Endpunkt /key/generate aufrufen.

Code anzeigen

Schnellstart - Schlüssel generieren​

Schritt 1: PostgreSQL DB-URL speichern

model_list:
  - model_name: gpt-4
    litellm_params:
        model: ollama/llama2
  - model_name: gpt-3.5-turbo
    litellm_params:
        model: ollama/llama2

general_settings: 
  master_key: sk-1234 
  database_url: "postgresql://<user>:<password>@<host>:<port>/<dbname>" # 👈 KEY CHANGE

Schritt 2: LiteLLM starten

litellm --config /path/to/config.yaml

Schritt 3: Schlüssel generieren

curl 'http://0.0.0.0:4000/key/generate' \
--header 'Authorization: Bearer <your-master-key>' \
--header 'Content-Type: application/json' \
--data-raw '{"models": ["gpt-3.5-turbo", "gpt-4"], "metadata": {"user": "ishaan@berri.ai"}}'

Ausgabenverfolgung​

Ausgaben pro

Wie wird es berechnet?

Die Kosten pro Modell werden hier gespeichert und von der Funktion completion_cost berechnet.

Wie wird es verfolgt?

Die Ausgaben werden automatisch für den Schlüssel in der Tabelle "LiteLLM_VerificationTokenTable" verfolgt. Wenn dem Schlüssel eine 'user_id' oder 'team_id' zugeordnet ist, werden die Ausgaben für diesen Benutzer in der Tabelle "LiteLLM_UserTable" und für das Team in der Tabelle "LiteLLM_TeamTable" verfolgt.

Sie können die Ausgaben für einen Schlüssel abrufen, indem Sie den Endpunkt /key/info verwenden.

curl 'http://0.0.0.0:4000/key/info?key=<user-key>' \
     -X GET \
     -H 'Authorization: Bearer <your-master-key>'

Diese werden automatisch (in USD) aktualisiert, wenn Aufrufe an /completions, /chat/completions, /embeddings mit der completion_cost()-Funktion von LiteLLM erfolgen. Code anzeigen.

Beispielantwort

{
    "key": "sk-tXL0wt5-lOOVK9sfY2UacA",
    "info": {
        "token": "sk-tXL0wt5-lOOVK9sfY2UacA",
        "spend": 0.0001065, # 👈 SPEND
        "expires": "2023-11-24T23:19:11.131000Z",
        "models": [
            "gpt-3.5-turbo",
            "gpt-4",
            "claude-2"
        ],
        "aliases": {
            "mistral-7b": "gpt-3.5-turbo"
        },
        "config": {}
    }
}

Modell-Aliase​

Wenn ein Benutzer ein bestimmtes Modell verwenden soll (z.B. gpt3-5), und Sie möchten

  • versuchen, die Anfrage zu verbessern (z.B. GPT4)
  • oder zu verschlechtern (z.B. Mistral)

Hier erfahren Sie, wie Sie das tun können

Schritt 1: Eine Modellgruppe in config.yaml erstellen (Modellnamen, API-Schlüssel usw. speichern)

model_list:
  - model_name: my-free-tier
    litellm_params:
        model: huggingface/HuggingFaceH4/zephyr-7b-beta
        api_base: http://0.0.0.0:8001
  - model_name: my-free-tier
    litellm_params:
        model: huggingface/HuggingFaceH4/zephyr-7b-beta
        api_base: http://0.0.0.0:8002
  - model_name: my-free-tier
    litellm_params:
        model: huggingface/HuggingFaceH4/zephyr-7b-beta
        api_base: http://0.0.0.0:8003
  - model_name: my-paid-tier
    litellm_params:
        model: gpt-4
        api_key: my-api-key

Schritt 2: Einen Schlüssel generieren

curl -X POST "https://0.0.0.0:4000/key/generate" \
-H "Authorization: Bearer <your-master-key>" \
-H "Content-Type: application/json" \
-d '{
    "models": ["my-free-tier"], 
    "aliases": {"gpt-3.5-turbo": "my-free-tier"}, # 👈 KEY CHANGE
    "duration": "30min"
}'
  • Anfrage verbessern / verschlechtern? Ändern Sie die Alias-Zuordnung

Schritt 3: Den Schlüssel testen

curl -X POST "https://0.0.0.0:4000/key/generate" \
-H "Authorization: Bearer <user-key>" \
-H "Content-Type: application/json" \
-d '{
    "model": "gpt-3.5-turbo", 
    "messages": [
        {
            "role": "user",
            "content": "this is a test request, write a short poem"
        }
    ]
}'

Erweitert​

LiteLLM-Schlüssel im benutzerdefinierten Header übergeben​

Verwenden Sie dies, damit der LiteLLM-Proxy nach dem virtuellen Schlüssel in einem benutzerdefinierten Header anstelle des Standard-Headers "Authorization" sucht.

Schritt 1 Definieren Sie litellm_key_header_name in der litellm config.yaml

model_list:
  - model_name: fake-openai-endpoint
    litellm_params:
      model: openai/fake
      api_key: fake-key
      api_base: https://exampleopenaiendpoint-production.up.railway.app/

general_settings: 
  master_key: sk-1234 
  litellm_key_header_name: "X-Litellm-Key" # 👈 Key Change

Schritt 2 Testen Sie es

In dieser Anfrage verwendet LiteLLM den virtuellen Schlüssel im Header X-Litellm-Key

curl https://:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Litellm-Key: Bearer sk-1234" \
  -H "Authorization: Bearer bad-key" \
  -d '{
    "model": "fake-openai-endpoint",
    "messages": [
      {"role": "user", "content": "Hello, Claude gm!"}
    ]
  }'

Erwartete Antwort

Erwarten Sie eine erfolgreiche Antwort vom LiteLLM-Proxy, da der in X-Litellm-Key übergebene Schlüssel gültig ist.

{"id":"chatcmpl-f9b2b79a7c30477ab93cd0e717d1773e","choices":[{"finish_reason":"stop","index":0,"message":{"content":"\n\nHello there, how may I assist you today?","role":"assistant","tool_calls":null,"function_call":null}}],"created":1677652288,"model":"gpt-3.5-turbo-0125","object":"chat.completion","system_fingerprint":"fp_44709d6fcb","usage":{"completion_tokens":12,"prompt_tokens":9,"total_tokens":21}

Virtuelle Schlüssel aktivieren/deaktivieren​

Schlüssel deaktivieren

curl -L -X POST 'http://0.0.0.0:4000/key/block' \
-H 'Authorization: Bearer LITELLM_MASTER_KEY' \
-H 'Content-Type: application/json' \
-d '{"key": "KEY-TO-BLOCK"}'

Erwartete Antwort

{
  ...
  "blocked": true
}

Schlüssel aktivieren

curl -L -X POST 'http://0.0.0.0:4000/key/unblock' \
-H 'Authorization: Bearer LITELLM_MASTER_KEY' \
-H 'Content-Type: application/json' \
-d '{"key": "KEY-TO-UNBLOCK"}'
{
  ...
  "blocked": false
}

Benutzerdefinierte /key/generate​

Wenn Sie benutzerdefinierte Logik vor dem Generieren eines Proxy-API-Schlüssels hinzufügen müssen (Beispiel: Validierung von team_id)

1. Schreiben Sie eine benutzerdefinierte custom_generate_key_fn​

Die Eingabe für die Funktion custom_generate_key_fn ist ein einzelner Parameter: data (Typ: GenerateKeyRequest)

Die Ausgabe Ihrer custom_generate_key_fn sollte ein Wörterbuch mit der folgenden Struktur sein:

{
    "decision": False,
    "message": "This violates LiteLLM Proxy Rules. No team id provided.",
}

  • decision (Typ: bool): Ein boolescher Wert, der angibt, ob die Schlüsselgenerierung zulässig ist (True) oder nicht (False).

  • message (Typ: str, Optional): Eine optionale Nachricht, die zusätzliche Informationen zur Entscheidung liefert. Dieses Feld wird enthalten, wenn die Entscheidung False ist.

async def custom_generate_key_fn(data: GenerateKeyRequest)-> dict:
        """
        Asynchronous function for generating a key based on the input data.

        Args:
            data (GenerateKeyRequest): The input data for key generation.

        Returns:
            dict: A dictionary containing the decision and an optional message.
            {
                "decision": False,
                "message": "This violates LiteLLM Proxy Rules. No team id provided.",
            }
        """
        
        # decide if a key should be generated or not
        print("using custom auth function!")
        data_json = data.json()  # type: ignore

        # Unpacking variables
        team_id = data_json.get("team_id")
        duration = data_json.get("duration")
        models = data_json.get("models")
        aliases = data_json.get("aliases")
        config = data_json.get("config")
        spend = data_json.get("spend")
        user_id = data_json.get("user_id")
        max_parallel_requests = data_json.get("max_parallel_requests")
        metadata = data_json.get("metadata")
        tpm_limit = data_json.get("tpm_limit")
        rpm_limit = data_json.get("rpm_limit")

        if team_id is not None and team_id == "litellm-core-infra@gmail.com":
            # only team_id="litellm-core-infra@gmail.com" can make keys
            return {
                "decision": True,
            }
        else:
            print("Failed custom auth")
            return {
                "decision": False,
                "message": "This violates LiteLLM Proxy Rules. No team id provided.",
            }

2. Geben Sie den Dateipfad an (relativ zur config.yaml)​

Geben Sie den Dateipfad zur config.yaml an.

Wenn sie sich zum Beispiel im selben Verzeichnis befinden - ./config.yaml und ./custom_auth.py, sieht das so aus

model_list: 
  - model_name: "openai-model"
    litellm_params: 
      model: "gpt-3.5-turbo"

litellm_settings:
  drop_params: True
  set_verbose: True

general_settings:
  custom_key_generate: custom_auth.custom_generate_key_fn

Obergrenze für /key/generate-Parameter​

Verwenden Sie dies, wenn Sie Standard-Obergrenzen für max_budget, budget_duration oder beliebige key/generate-Parameter pro Schlüssel festlegen müssen.

Setzen Sie litellm_settings:upperbound_key_generate_params

litellm_settings:
  upperbound_key_generate_params:
    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.

Erwartetes Verhalten

  • Senden Sie eine Anfrage /key/generate mit max_budget=200
  • Der Schlüssel wird mit max_budget=100 erstellt, da 100 die Obergrenze ist.

Standard-Parameter für /key/generate​

Verwenden Sie dies, wenn Sie das Standard-max_budget oder beliebige key/generate-Parameter pro Schlüssel steuern müssen.

Wenn eine Anfrage /key/generate max_budget nicht angibt, wird der in default_key_generate_params angegebene max_budget verwendet.

Setzen Sie litellm_settings:default_key_generate_params

litellm_settings:
  default_key_generate_params:
    max_budget: 1.5000
    models: ["azure-gpt-3.5"]
    duration:     # blank means `null`
    metadata: {"setting":"default"}
    team_id: "core-infra"

✨ Schlüsselrotationen​

Info

Dies ist eine Enterprise-Funktion.

Enterprise-Preise

Holen Sie sich einen kostenlosen 7-Tage-Testschlüssel

Rotiert einen vorhandenen API-Schlüssel, während optional seine Parameter aktualisiert werden.


curl 'https://:4000/key/sk-1234/regenerate' \
  -X POST \
  -H 'Authorization: Bearer sk-1234' \
  -H 'Content-Type: application/json' \
  -d '{
    "max_budget": 100,
    "metadata": {
      "team": "core-infra"
    },
    "models": [
      "gpt-4",
      "gpt-3.5-turbo"
    ]
  }'

Mehr erfahren

👉 API-REFERENZDOKUMENTATION

Temporäre Budgeterhöhung​

Verwenden Sie den Endpunkt /key/update, um das Budget eines vorhandenen Schlüssels zu erhöhen.

curl -L -X POST 'https://:4000/key/update' \
-H 'Authorization: Bearer sk-1234' \
-H 'Content-Type: application/json' \
-d '{"key": "sk-b3Z3Lqdb_detHXSUp4ol4Q", "temp_budget_increase": 100, "temp_budget_expiry": "10d"}'

API-Referenz

Schlüsselgenerierung einschränken​

Verwenden Sie dies, um zu steuern, wer Schlüssel generieren kann. Nützlich, wenn andere Schlüssel über die UI erstellen dürfen.

litellm_settings:
  key_generation_settings:
    team_key_generation:
      allowed_team_member_roles: ["admin"]
      required_params: ["tags"] # require team admins to set tags for cost-tracking when generating a team key
    personal_key_generation: # maps to 'Default Team' on UI 
      allowed_user_roles: ["proxy_admin"]

Spezifikation​

key_generation_settings: Optional[StandardKeyGenerationConfig] = None

Typen​

class StandardKeyGenerationConfig(TypedDict, total=False):
    team_key_generation: TeamUIKeyGenerationConfig
    personal_key_generation: PersonalUIKeyGenerationConfig

class TeamUIKeyGenerationConfig(TypedDict):
    allowed_team_member_roles: List[str] # either 'user' or 'admin'
    required_params: List[str] # require params on `/key/generate` to be set if a team key (team_id in request) is being generated


class PersonalUIKeyGenerationConfig(TypedDict):
    allowed_user_roles: List[LitellmUserRoles] 
    required_params: List[str] # require params on `/key/generate` to be set if a personal key (no team_id in request) is being generated


class LitellmUserRoles(str, enum.Enum):
    """
    Admin Roles:
    PROXY_ADMIN: admin over the platform
    PROXY_ADMIN_VIEW_ONLY: can login, view all own keys, view all spend
    ORG_ADMIN: admin over a specific organization, can create teams, users only within their organization

    Internal User Roles:
    INTERNAL_USER: can login, view/create/delete their own keys, view their spend
    INTERNAL_USER_VIEW_ONLY: can login, view their own keys, view their own spend


    Team Roles:
    TEAM: used for JWT auth


    Customer Roles:
    CUSTOMER: External users -> these are customers

    """

    # Admin Roles
    PROXY_ADMIN = "proxy_admin"
    PROXY_ADMIN_VIEW_ONLY = "proxy_admin_viewer"

    # Organization admins
    ORG_ADMIN = "org_admin"

    # Internal User Roles
    INTERNAL_USER = "internal_user"
    INTERNAL_USER_VIEW_ONLY = "internal_user_viewer"

    # Team Roles
    TEAM = "team"

    # Customer Roles - External users of proxy
    CUSTOMER = "customer"

Nächste Schritte - Budgets, Ratenbegrenzungen pro virtuellem Schlüssel festlegen​

Folgen Sie dieser Dokumentation, um Budgets und Ratenbegrenzer pro virtuellem Schlüssel mit LiteLLM festzulegen.

Endpunktreferenz (Spezifikation)​

Schlüssel​

👉 API-REFERENZDOKUMENTATION​

Benutzer​

👉 API-REFERENZDOKUMENTATION​

Teams​

👉 API-REFERENZDOKUMENTATION​