Hitelesítés API-kulccsal

A CLEVI átjáró az OpenAI-kompatibilis és az Anthropic-kompatibilis útvonalakon egyetlen API-kulccsal hitelesít.
Az ügyfélben két értéket kell beállítani: a kulcsot tartalmazó hitelesítési fejlécet és az SDK base URL-jét; az engedélyezett fejlécformátumok és base URL-ek specifikációnként eltérnek.
A beállítás befejezése után a modelllista lekérésével azonnal ellenőrizheti, hogy sikeres volt-e a hitelesítés.
Sikertelen hitelesítés esetén 401-es, a hitelesítés után pedig a jogosultsági vagy kvótakövetelmények nem teljesülése esetén 403-as választ ad vissza.

Az API-kulcsot a konzol API-kulcsok képernyőjén igényelje. Ugyanezen a képernyőn kezelheti a kulcs visszavonását és használati hatókörét.

Hitelesítési fejléc

Mindkét specifikáció esetén az API-kulcsot egyetlen kérésfejléc tartalmazza. Az X-API-Key vagy az Authorization fejléc egyikét kell használni; az engedélyezett formátum a specifikációtól függ.

Az OpenAI-kompatibilis útvonalon az Authorization fejléc használatakor szükség van a Bearer előtagra. Ha csak a kulcsot küldi el előtag nélkül, az átjáró elutasítja a kérést.

A fejlécnevek nem különböztetik meg a kis- és nagybetűket, ezért az Anthropic SDK által küldött x-api-key fejléc is változtatás nélkül működik. Ha mindkét fejlécet megadja, az X-API-Key értéke élvez elsőbbséget.

base URL

A korábban használt SDK-k továbbra is használhatók, ha csak a base URL-t módosítja az alábbi címre. A két cím abban különbözik, hogy tartalmazza-e a /v1 részt, ezért a specifikációnak megfelelő címet adja meg változtatás nélkül.

Hitelesítés ellenőrzése

A kulcs és a base URL beállítása után a modell lista lekérdezésével ellenőrizheti a hitelesítés állapotát. Az alábbi példák ugyanazt a lekérdezést hajtják végre curl, OpenAI SDK és Anthropic SDK használatával. Az sk-... helyére az API-kulcs képernyőjén kiadott kulcsot írja be.

A curl-lel végzett lekérdezésnél mindkét specifikáció esetén adja meg a teljes elérési utat a /v1/models végpontig. Az első parancs az OpenAI-kompatibilis útvonalon az X-API-Key fejlécet, a második parancs pedig az Anthropic-kompatibilis útvonalon az Authorization fejlécet használja.

curl https://platform.clevi.net/api/v2/aiservice/openai/v1/models \
  -H "X-API-Key: sk-..."

curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/models \
  -H "Authorization: Bearer sk-..." \
  -H "anthropic-version: 2023-06-01"

Az OpenAI SDK esetén a base_url értékeként a /v1 részt is tartalmazó címet adja meg.

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)

for model in client.models.list():
    print(model.id)

Az Anthropic SDK esetén a base_url értékeként a /v1 előtt végződő címet adja meg.
A hitelesítéshez változatlanul használja az SDK által küldött x-api-key fejlécet.

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/anthropic",
)

for model in client.models.list(limit=20).data:
    print(model.id)

Bármelyik példánál a 200-as válasz sikeres hitelesítést jelent, és a válasz data mezője tartalmazza az ezzel a kulccsal hívható modellek listáját. 401-es válasz esetén a következő szakasz sorrendje szerint ellenőrizze az okot.

Hitelesítési hiba

Ha nem létező, lejárt vagy visszavont kulcsot küld, a rendszer 401-es választ ad. Ha az OpenAI-kompatibilis útvonalat kulcs nélkül hívja meg, az alábbi törzset kapja vissza; az Anthropic-kompatibilis útvonalon az error.type értéke authentication_error.

{
  "error": {
    "message": "API key is required.",
    "type": "invalid_request_error"
  }
}

401-es válasz esetén a következő sorrendben ellenőrizze a beállításokat.

1. Ellenőrizze a kulcs állapotát az API-kulcs képernyőjén. Ha a kulcs lejárt vagy vissza lett vonva, adjon ki újat.
2. Ellenőrizze, hogy a fejléc neve X-API-Key vagy Authorization-e.
3. Ha az OpenAI-kompatibilis útvonalon Authorization fejlécet használ, ellenőrizze, hogy szerepel-e benne a Bearer előtag.

A módosítások után futtassa újra a hitelesítés ellenőrzéséről szóló szakasz modell-lista lekérdezését, és ellenőrizze, hogy 200-as válasz érkezik-e.

Együtt használt fejlécek

A következő fejlécek mindegyike opcionális. A problémák nyomon követéséhez javasoljuk az X-Request-Id megadását.

Ha az 5xx hibák ismétlődnek, kérjük, jelezze azokat a súgónak és az ügyfélszolgálatnak az X-Request-Id értékével együtt. Ha az értéket közvetlenül adta meg, az azonnal összevethető a kliens naplóival.