Ein Rerank-API-Key sieht aus wie ein gewöhnlicher Chat-Key, birgt aber größere Risiken: Jede Anfrage enthält die Nutzer-Query und den Text mehrerer Kandidatendokumente und wird nach Aufrufvolumen abgerechnet. Bei einem Leak können Dritte das Guthaben verbrauchen und fremde Anfragen in der Rechnung auftauchen.
Dieser Beitrag beschreibt zwei Bezugswege – die offizielle Anbieterplattform und ein inländisches AI-Gateway – sowie Rechte- und Kontingenteinstellungen bei der Erstellung, das Setzen von Umgebungsvariablen, die 401-Diagnose und den Rotationsablauf. Modellumfang und Preise entnehmen Sie unseren Modellpreisen.
Hinweis: Cohere, Jina AI, Alibaba Cloud, SiliconFlow, Volcano Engine und weitere genannte Namen gehören ihren jeweiligen Inhabern; dieser Beitrag dient nur der technischen Erläuterung. Das ZSQH AI Gateway steht in keiner Verbindung zu diesen Anbietern; Schnittstellen und Modelle richten sich nach den Angaben auf unserer Website.
1. Unterschied zwischen Rerank-Key und Chat-Key
Ein Chat-Key ruft ein Generierungsmodell auf: Eingabe sind Nachrichten, Ausgabe ist Text. Ein Rerank-Key ruft ein Reranking-Modell auf: Eingabe sind eine Query und eine Gruppe Kandidatendokumente, Ausgabe sind Relevanzscores und eine Rangfolge pro Dokument.
Die Unterschiede liegen vor allem in drei Punkten:
- Sensiblere Daten: Kandidatendokumente stammen oft aus internen Wissensdatenbanken und können Verträge, Richtlinien oder Kundeninformationen enthalten.
- Andere Abrechnung: Üblich ist die Abrechnung nach Token von Query und Dokumenten; lange Dokumente und große Kandidatenmengen erhöhen den Verbrauch.
- Engere Rechte: Viele Plattformen erlauben, den Key auf bestimmte Modelle zu begrenzen, etwa nur auf Rerank-Modelle, um Fehlbedienung zu reduzieren.
Deshalb sollten Rerank-Keys nicht mit Chat-Keys gemischt und nicht derselbe Key an mehrere Projekte ausgegeben werden. Die sinnvolle Granularität lautet „Umgebung + Projekt“.
2. Weg A: Bezug über die offizielle Anbieterplattform
Cohere, Jina AI, Alibaba Cloud Bailian, SiliconFlow, Volcano Engine und weitere Plattformen bieten Reranking-Dienste an. Einstieg und Felder unterscheiden sich, der Ablauf ist ähnlich:
- Plattform wählen: zuerst unterstützte Sprachen, maximale Dokumentlänge, Unterstützung für Chinesisch und den Datenstandort prüfen.
- Konto registrieren: inländische Plattformen verlangen meist Telefonnummer oder Unternehmensverifizierung, ausländische Plattformen E-Mail und Zahlungsmethode.
- Dienst aktivieren: in der Konsole den Rerank- oder Reranking-Dienst suchen und prüfen, ob das Zielmodell freigeschaltet ist.
- Key erstellen: im Bereich API Keys einen neuen Schlüssel anlegen und nach „Projekt-Umgebung“ benennen, zum Beispiel
rag-prod. - Limits setzen: Kontingent setzen, wenn möglich; Ablaufdatum setzen, wenn möglich; bei Modellbeschränkung nur Rerank-Modelle auswählen.
- Sofort testen: nach dem Kopieren eine minimale Anfrage senden und Authentifizierung, Modellname und Antwortstruktur prüfen.
Die Authentifizierungs-Header unterscheiden sich. Cohere und Jina verwenden üblicherweise Authorization: Bearer <key>, einige inländische Plattformen eigene Signaturverfahren. Request-Header nicht aus dem Gedächtnis schreiben, sondern aus der aktuellen offiziellen Dokumentation übernehmen.
3. Weg B: Bezug über das ZSQH AI Gateway
Wenn dem Team keine ausländische Zahlungsmethode zur Verfügung steht oder die Rechnungen mehrerer Modelle gebündelt werden sollen, ist das Gateway eine Option:
- Das ZSQH AI Gateway öffnen und die Registrierung abschließen.
- In der Konsole zur Seite „API-Schlüssel“ wechseln und einen neuen Key anlegen.
- Namen eintragen, Projekt oder Gruppe auswählen, Kontingentobergrenze und Ablaufdatum setzen.
- Das Wallet aufladen und sicherstellen, dass das Guthaben für einen Testlauf reicht.
- Den Key kopieren und im Passwortmanager speichern, nicht im Chatverlauf liegen lassen.
Das Gateway stellt die Reranking-Funktion über POST /v1/rerank bereit und unterstützt zusätzlich /rerank; die Base URL lautet https://ai.zhongshangqihang.com/v1. Wichtig: Rerank gehört nicht zur OpenAI-Chat-Completions-Spezifikation, sondern ist ein eigener Endpunkt; SDK-Methoden für Chat-Schnittstellen lassen sich nicht direkt übernehmen.
| Dimension | Offizielle Anbieterplattform | ZSQH AI Gateway |
|---|---|---|
| Registrierung und Zahlung | ausländische Plattformen meist mit Fremdwährungskarte, inländische mit Identitätsprüfung | Registrierung und Aufladung im Inland, Modalitäten gemäß Abrechnungsseite |
| Netzwerk | ausländische Endpunkte können instabil sein | inländische Direktverbindung, weniger Netzwerkaufwand bei der Fehlersuche |
| Modellumfang | nur Modelle des jeweiligen Anbieters | mehrere Upstream-Modelle über einen Zugang, gemäß Modellliste |
| Rechnung | getrennte Abrechnung je Anbieter | gebündelte Rechnung über mehrere Modelle, einfacher für die Erstattung |
| Datenweg | Anfrage direkt zum Anbieter | Weiterleitung über das Gateway, Datenverarbeitungsbedingungen prüfen |
| Geeignet für | festen Einzelanbieter, Support durch den Hersteller | mehrere Modelle, inländische Teams, einheitlicher Betrieb |
Beide Wege können parallel bestehen. Häufig bleibt ein offizielles Konto als Rückfallebene für die Produktion, während inländische Teams und Testumgebungen das Gateway nutzen. Vor der Wahl Vertragspartner, Rechnungsart und Datenbedingungen klären.
4. Vier Sicherheitseinstellungen bei der Key-Erstellung
Der Key ist nur der Anfang; die Einstellungen bei der Erstellung bestimmen, wie groß der Schaden im Fehlerfall ist.
Erstens, nach Umgebung trennen. Entwicklung, Test und Produktion erhalten jeweils einen eigenen Key, der Name enthält Projekt und Datum. So lässt sich eine Rechnung direkt zuordnen, und bei einem Leak muss nur ein Key gesperrt werden.
Zweitens, Kontingentobergrenzen setzen. Für jeden Key ein Tages- oder Monatskontingent und mindestens einen Warnschwellenwert festlegen. Der Rerank-Verbrauch hängt direkt an Dokumentanzahl und Dokumentlänge; ein fehlerhaftes Schleifenskript kann in kurzer Zeit sehr viele Anfragen erzeugen.
Drittens, Ablaufdatum setzen. Test-Keys kurz laufen lassen, Produktions-Keys nach Teamrichtlinie rotieren. Für temporäre Keys an externe Dienstleister oder Partner ist automatisches Ablaufen verlässlicher als manuelles Einsammeln.
Viertens, minimale Rechte. Wenn die Plattform Modellbereiche, IP-Whitelists oder Projektgruppen unterstützt, nur Rerank-Modelle und die nötigen Quelladressen freigeben. Nicht aus Bequemlichkeit alle Modelle für den Key öffnen.
5. Umgebungsvariablen und Auslesen im Code
Der Key gehört ausschließlich in serverseitige Umgebungsvariablen oder einen Secret Manager, nicht ins Repository und nicht ins Frontend. Minimale Konfiguration:
RERANK_API_KEY=sk-dein-schluessel
RERANK_BASE_URL=https://ai.zhongshangqihang.com/v1
Die Datei .env in .gitignore aufnehmen und beim Deployment über das Umgebungsvariablen-Panel der Plattform injizieren. Auslesen in Python:
import os
import requests
api_key = os.environ["RERANK_API_KEY"]
base_url = os.environ.get("RERANK_BASE_URL", "https://ai.zhongshangqihang.com/v1")
resp = requests.post(
f"{base_url}/rerank",
headers={"Authorization": f"Bearer {api_key}"},
json={
"model": "dein-rerank-modell",
"query": "Wie lange dauert die Testphase?",
"documents": ["Die Testphase dauert 14 Tage.", "Überweisung per Firmenkonto ist möglich."],
"top_n": 2,
},
timeout=20,
)
resp.raise_for_status()
print(resp.json()["results"])
Der Modellname richtet sich nach der Seite Modellpreise. Nutzt das Team einen Secret Manager, den Key verschlüsselt speichern und zur Laufzeit injizieren, niemals in Logs ausgeben. Bei der Fehlersuche können Request-ID und Statuscode protokolliert werden, aber nicht der vollständige Authorization-Header.
6. 401-Diagnose: Authentifizierung und fehlende Rechte trennen
401 bedeutet, dass die Identität nicht erkannt wurde; 403 bedeutet, dass die Identität erkannt wurde, aber die Berechtigung fehlt. Viele Gateways fassen beide in eine Fehlerstruktur; deshalb Antwortkörper und Fehlercode prüfen, nicht nur den Statuscode.
| Symptom | Häufige Ursache | Vorgehen |
|---|---|---|
| 401 nicht authentifiziert | Key falsch geschrieben, Leerzeichen davor/danach, beim Kopieren abgeschnitten | erneut kopieren und auf Zeilenumbrüche prüfen |
| 401 invalid token | Key gelöscht, abgelaufen oder gehört zu einem anderen Projekt | Status in der Konsole prüfen und neu erstellen |
| 401 trotz korrektem Key | Header-Feld falsch geschrieben oder Base URL zeigt auf einen anderen Dienst | Authorization und Pfad anhand der Dokumentation prüfen |
| 403 Forbidden | Key hat keine Berechtigung für das Modell, oder Konto ist gesperrt | Modellbereich und Kontostatus prüfen |
| 404 Not Found | Modellname oder Endpunktpfad falsch | /v1/rerank und Modellliste abgleichen |
| 429 Too Many Requests | Parallelität zu hoch oder Kontingentgrenze erreicht | exponentielles Backoff, Kontingent und Rate prüfen |
Die Reihenfolge der Diagnose sollte fest sein: zuerst Anfrage-URL und Header, dann Key-Status, dann Modellname, schließlich Guthaben und Rate-Limits. Diese vier Schritte als Checkliste dokumentieren; das ist schneller als jedes Mal nach Gefühl zu testen.
7. Rotation und Umgang mit einem Leak
Key-Rotation ist keine Aufgabe für den Ernstfall. Ein fester Rotationszyklus ist sinnvoll; sofort rotieren bei Personalabgang, versehentlichem Commit im Repository oder einem vollständigen Key in Logs.
- In der Konsole einen neuen Key anlegen, der Name enthält das Rotationsdatum.
- Den neuen Key zuerst in der Testumgebung eintragen und eine minimale Anfrage ausführen.
- Die Produktions-Umgebungsvariablen aktualisieren, den Dienst neu starten und Fehlerrate sowie Aufrufvolumen beobachten.
- Nachdem der alte Key keinen Traffic mehr hat, deaktivieren oder löschen.
- Die letzten Aufruflogs prüfen und fremde Quellen oder ungewöhnliche Spitzen ausschließen.
- Den Rotationstermin dokumentieren und die nächste Rotation im Teamkalender eintragen.
Besteht Verdacht auf ein Leak, zuerst den alten Key sperren, dann Rechnung und Logs prüfen – nicht zuerst die Logs löschen. Die Beweislage hilft, den Auswirkungsbereich zu bestimmen. Nach der Rotation Repository-Historie, CI-Variablen und Chatverläufe auf weitere Kopien prüfen.
8. Häufige Fragen
Kann ein Rerank-API-Key auch Chat-Modelle aufrufen?
Das hängt von der Plattform ab. Selbst wenn es technisch möglich ist, ist es nicht empfehlenswert. Ein Rerank-Key sollte nur für den Rerank-Endpunkt verwendet werden, damit nicht ein Key sowohl Generierungs- als auch Retrieval-Kosten trägt.
Darf der Key im Frontend oder in einer Mini-App liegen?
Nein. Frontend-Code und Netzwerkanfragen sind für Nutzer sichtbar; der Key wäre öffentlich. Richtig ist, dass das Frontend den eigenen Backend-Dienst aufruft und dieser den Key hält und die Anfrage weiterleitet.
Worin unterscheiden sich 401 und 403?
401 ist ein Authentifizierungsfehler: Key ungültig, abgelaufen oder Header falsch. 403 bedeutet fehlende Berechtigung: Der Key kann gültig sein, darf aber das Modell oder Projekt nicht nutzen. Zuerst code und message im Fehlerkörper prüfen.
Kann ein Key von mehreren Projekten gemeinsam genutzt werden?
Technisch meist ja, betrieblich nicht empfehlenswert. Ein gemeinsamer Key lässt sich nicht sauber abrechnen, und ein Leak trifft mehr Systeme. Mindestens nach Umgebung und Projekt trennen.
Wie oft sollte ein Key rotiert werden?
Nach der Sicherheitsrichtlinie des Teams. Üblich ist ein regelmäßiger Zyklus sowie sofortige Rotation bei Personalwechsel, Leak-Verdacht oder versehentlichem Commit. Ein allgemeingültiger Rhythmus existiert nicht; entscheidend ist ein ausführbarer Prozess.
