Sådan opbygger du en partner LLM API uden at afsløre rå udbydernøgler

En partner API for LLM-adgang bør ikke være en tynd indpakning omkring udbydernøgler. Hvis partnere, forhandlere eller kundeapplikationer har brug for delegeret adgang til sprogmodeller, har platformen brug for sit eget kontrolplan, gateway, politiklag, målerpipeline og operationelle runbooks. Ellers bliver fakturering på udbyderniveau, grænser på udbyderniveau og delte legitimationsoplysninger de eneste kontroller mellem én partnerintegration og en meget dyr hændelse.

Målet er ligetil: Lad eksterne parter forbruge LLM-kapaciteter gennem din platform, mens du holder upstream-udbyderens legitimationsoplysninger private, håndhæver partnerspecifikke rettigheder, måler fakturerbar brug og giver partnere tilstrækkelig gennemsigtighed til at opbygge pålidelige kunder.

Referencearkitektur

En praktisk partner API har to hoveddele: et kontrolplan og en anmodningsgateway.

Kontrolplanet administrerer partnerorganisationer, applikationer, miljøer, delegerede API nøgler, modelrettigheder, satsgrænseniveauer, forbrugslofter, faktureringsvilkår, webhook-slutpunkter og revisionsregistreringer. Det er her, kommercielle og operationelle regler bliver maskinlæsbare politikker.

Anmodningsgatewayen modtager partnertrafik, godkender den delegerede nøgle, evaluerer politik, anvender kvote, ruter til den valgte modeludbyder, registrerer brug og returnerer partnersynlige svarmetadata. I en moden enterprise LLM API er denne gateway også hvor modelrouting, genforsøg, failover, indholdskontrol og observerbarhed håndhæves konsekvent.

Den vigtige grænse er denne: Partnere modtager kun dine platformudstedte nøgler. De modtager aldrig rå udbyderlegitimationsoplysninger. Upstream-udbydernøgler forbliver i din platformshemmelige butik og bruges kun af gateway- eller backend-medarbejdere.

Faktamønster at bygge omkring

Følgende er fakta, der understøttes af offentlig platform og cloud-dokumentation, ikke antagelser om en enkelt implementering:

• Nogle LLM-udbydere understøtter projektspecifikke nøgler, servicekonti, modeladgang på projektniveau og satsgrænser på projektniveau.
• Skyvejledning til SaaS API'er med flere lejere adskiller almindeligvis politikadministration, politikbeslutninger og håndhævelse af politik for at reducere utilsigtet adgang på tværs af lejere.
• API gateways og SaaS-kontrolplaner kan anvende lejerspecifik drosling og kvotestyring, herunder rate-, burst- og kvoteniveauer.
• Brugsbaseret SaaS-fakturering afhænger af indsamling af lejeraktivitet, sammenlægning af den og afstemning af den med faktureringsregistreringer.
• Idempotensnøgler er et dokumenteret mønster til sikker genforsøg af tilstandsændrende API anmodninger uden at skabe dobbelte bivirkninger.
• Standardiserede svaroverskrifter for hastighedsgrænser kan hjælpe kunder med at forstå grænser, resterende tillæg, nulstille timing og prøve adfærd igen.

Anbefalingen er at kombinere disse mønstre i et partnervendt LLM-adgangslag, som du ejer, i stedet for at bede alle partnere om at integrere direkte med hver upstream-modeludbyder.

Trin 1: Definer lejer og identitetsmodel

Identificer ikke partnertrafik med kun én API nøglestreng. En nyttig partner API har brug for separate identifikatorer, fordi fakturering, misbrugsgennemgang, kvotefejlfinding og supportundersøgelser ofte stiller forskellige spørgsmål.

Opret som minimum identifikatorer for:

• Partnerorganisation: den kontraherende eksterne virksomhed.
• Partnerapplikation: en specifik integrations-, produkt-, plugin- eller forhandlerapplikation.
• Miljø: produktion, iscenesættelse, sandkasse eller udvikling.
• Slutkunde: partnerens kunde, arbejdsområde, konto eller lejer, når det er kontraktligt tilladt og teknisk tilgængeligt.
• API nøgle: de delegerede legitimationsoplysninger, der bruges til at godkende anmodninger.
• Anmodnings-id: en unik identifikator til sporing af én anmodning på tværs af din gateway, udbyderopkald, brugsbegivenheder og supportlogfiler.

Denne struktur undgår den almindelige fejltilstand, hvor en kompromitteret eller støjende integration kun kan beskrives som "partner X-trafik." Det giver dig også mulighed for at suspendere én applikation eller et miljø uden at deaktivere hele partnerens virksomhed.

Trin 2: Udsted delegerede partnernøgler

Partnernøgler skal være førsteklasses platformsobjekter, ikke statiske tokens i et regneark. Hver nøgle skal have metadata og politikbindinger:

• Partnerorganisations-id
• Applikations-id
• Miljø
• Tilladte API overflader, såsom chat, indlejringer, batch- eller billedgenerering
• Tilladte modelaliasser
• Regions- eller data-residency-begrænsninger, hvor det er relevant
• Rate-limit tier
• Forbrugsloft eller forudbetalt saldoregel
• Oprettelsestidspunkt, sidst brugt tid, ejer og rotationsstatus

Gem kun hashed nøglemateriale, hvor det er muligt, afslør kun fulde hemmeligheder én gang ved oprettelsen, og understøt rotation uden nedetid. En praktisk rotationsmodel tillader to aktive nøgler under et kort overgangsvindue, med revisionslogfiler, der viser, hvilken nøgle der blev brugt til hver anmodning.

Trin 3: Adskil rettigheder fra routing

En partners ret til at bruge en model bør ikke underforstås af den routingkode, der i øjeblikket understøttes. Hold berettigelsestjek eksplicit og adskilt fra udbydervalg.

For eksempel skal en anmodning om model: premium-reasoning først bestå en politikbeslutning:

• Har denne partner tilladelse til at bruge modelaliaset?
• Har partnerapplikationen tilladelse til at bruge den i dette miljø?
• Er anmodningen inden for den tilladte region eller datagrænse?
• Er kontrakten aktiv og i et godt omdømme?
• Er partneren inden for grænserne for forbrug, kvote og misbrug?

Først efter denne beslutning bør routing vælge upstream-udbyderen, udbyderprojektet, implementeringen eller reservestien. Dette har betydning, fordi ændringer i modelruten er operationelt hyppige. Ændringer af berettigelse skal være bevidste og kan revideres.

Trin 4: Udgiv en stabil partner API Surface

Partnere har brug for stabil adfærd, selv når dine upstream-udbydere skifter. Brug dine egne modelaliasser og funktionsbeskrivelser i stedet for at afsløre alle udbyderes modelnavne direkte.

Et lille eksempel:

POST /v1/chat/completions
Authorization: Bearer partner_key_...
Idempotency-Key: job_01J7...
X-Partner-Customer-Id: customer_123

{
  "model": "standard-chat",
  "messages": [
    {"role": "user", "content": "Summarize this support thread."}
  ],
  "metadata": {
    "ticket_id": "T-44821",
    "workflow": "support_summary"
  }
}

Partneren beder om standard-chat. Din gateway kortlægger det alias til den aktuelle godkendte udbyder og model, underlagt berettigelse, tilgængelighed, pris, forsinkelse, område og kvalitetsregler.

Undgå dog at skjule alle udbyderforskelle. Hvis to modelaliasser har forskellige kontekstvinduer, understøttelse af struktureret output, værktøjsopkaldsadfærd, latensprofiler eller regional tilgængelighed, skal du dokumentere disse forskelle tydeligt. Abstraktion skal forenkle integrationen, ikke skabe overraskelsesadfærd.

Trin 5: Håndhæv kvoter før udbyderopkald

Udbydergrænser er nyttige autoværn, men håndhævelse på partnerniveau hører hjemme på din platform. Et upstream-udbyderprojekt kan tjene mange partnere, eller en partner kan have flere ansøgninger med forskellige kontrakter. At kun stole på takstgrænser på udbyderniveau kan ikke udtrykke disse forskelle rent.

Anvend kvotekontrol, før du foretager upstream-opkald:

• Anmodninger pr. minut af partnernøgle
• Tokens pr. minut af partnerorganisation
• Samtidige anmodninger efter applikation
• Daglig eller månedlig fakturerbar enhedskvote
• Forudbetalt saldo eller kredittærskel
• Per-end-customer caps, hvor det kræves

For synkrone anmodninger, afvis klart, når anmodningen ikke kan accepteres. For asynkrone og batch-arbejdsbelastninger skal du overveje køadgang adskilt fra eksekveringskvoten. En batchupload kan accepteres, men individuelle opgaver bør stadig måles og stoppes, når partnergrænserne er nået.

Trin 6: Returner forudsigelige hastighedsgrænsesignaler

Uigennemsigtige 429 Too Many Requests svar skaber supportbilletter, der kan undgås. Returner partner-synlige kvotesignaler ved vellykkede og begrænsede svar.

Et nyttigt svar kan omfatte:

RateLimit-Limit: 600;w=60
RateLimit-Remaining: 42
RateLimit-Reset: 17
Retry-After: 17
X-Request-Id: req_01J8...

Anbefalinger:

• Dokumentér, om der gælder grænser pr. nøgle, applikation, organisation, model eller slutpunkt.
• Timing for returnering af nulstilling, som kunderne kan handle på.
• Brug Retry-After til begrænsede svar.
• Hold fejltekster stabile og maskinlæsbare.
• Undlad ikke at afsløre upstream-udbyderens interne dele, medmindre partnere har brug for dem til at fejlfinde adfærd.

Dette gør partnerklienter nemmere at bygge og reducerer storme, der skal prøves igen under trafikstigninger.

Trin 7: Brug idempotens til fakturerbart arbejde

Ethvert slutpunkt, der opretter stats- eller fakturerbart arbejde, bør understøtte idempotensnøgler. Dette er især vigtigt for async-genereringsjob, batch-indsendelser, kreditkøb, webhook-udløste genforsøg og langvarige opgaver.

Implementeringsreglen er enkel: Når en partner gentager den samme anmodning med den samme idempotensnøgle inde i opbevaringsvinduet, skal du returnere det oprindelige resultat i stedet for at oprette duplikatarbejde.

Gør kantstilfældene eksplicitte:

• Hvor længe opbevares idempotensregistreringer
• Hvilket slutpunkt og partnernøgle idempotensnøglen er omfattet af
• Hvad sker der, hvis den samme nøgle genbruges med forskellige anmodningsparametre
• Om mislykkede anmodninger er cachelagret
• Hvordan idempotens gælder for delvist afsluttede batchjobs

For fakturerbart LLM-arbejde skal du gemme nok anmodningsfingeraftryksdata til at detektere parameteruoverensstemmelser uden at beholde unødvendigt følsomt nyttelastindhold.

Trin 8: Udsend uforanderlige brugshændelser

Behandl ikke udbyderfakturaer som kilden til sandhed for partnerfakturering. Udbyderfakturaer kender normalt ikke dine partnerkontrakter, opmærkningsregler, forhandlerniveauer, slutkunde-id'er eller tvistarbejdsgang. Udsend i stedet en uforanderlig brugshændelse, når hver anmodning når en terminaltilstand.

En brugshændelse skal indeholde:

• Partnerorganisation-id
• Applikations-id og miljø
• API nøgle-id, ikke den rå nøgle
• Slutkunde-id, hvis angivet og tilladt
• Anmodnings-id og udbyder-korrelations-id
• Modelalias og upstream-udbydermodel
• Input-tokens, output-tokens, cachede tokens eller andre fakturerbare enheder
• Udbyderomkostningsbasis, når tilgængelig
• Partnerfaktureringsenhed, opmærkning, kreditudtrækning eller kontraktsats
• Status, fejlklasse, forsinkelse og antal genforsøg
• Tidsstempel og skemaversion

Disse hændelser feeds med partnerdashboards, faktureringseksport, registrering af uregelmæssigheder, kvotetællere og afstemning. Behold begivenhedsstrømmen kun ved at tilføje. Rettelser bør være justeringshændelser, ikke tavse redigeringer.

Trin 9: Afstem dagligt

Målemåling er kun nyttig, hvis den afstemmes. Byg en daglig proces, der sammenligner dine brugshændelser med upstream-udbyderbrug, udbyderfakturaer, kreditsaldi og partner-vendte faktureringsregistreringer.

Afstemningsprocessen bør identificere:

• Anmodninger accepteret af din gateway, men manglende terminalbrugsbegivenheder
• Udbyderbrug, der ikke kan tilknyttes en partneranmodning
• Tokenantal forskelle mellem udbyderrapporter og gateway-registreringer
• Gentageforsøg, der blev faktureret forkert
• Manuelle kreditter, refusioner og faktureringskorrektioner
• Partnere nærmer sig forpligtede forbrug, forudbetalt udmattelse eller usædvanlig vækst

Det er også her, økonomi, support og teknik har brug for de samme id'er. Hvis betjeningspanelet, fakturalinjeposten, loghændelsen og udbyderregistreringen ikke kan bindes sammen, bliver tvister til manuelle undersøgelser.

Trin 10: Byg operationelle runbooks

En partner API er en ekstern produktoverflade, så operationel adfærd skal planlægges, før der sker hændelser. Skriv som minimum runbooks til disse situationer:

• Kompromitteret partnernøgle: tilbagekald eller suspender én nøgle, underret partneren, bevar revisionslogfiler og angiv en rotationssti.
• Udløbsbrug: påfør nødlofter, sæt en applikation på pause, eller kræve godkendelse for yderligere brug.
• Udbyderafbrydelse: oversendes ikke til en godkendt udbyder eller returnerer en stabil fejl med vejledning igen.
• Kvoteopbrug: viser, om partneren skal vente, opgradere, købe kreditter eller reducere trafikken.
• Webhook-genafspilning: bekræft signaturer, brug idempotens og spor leveringsforsøg på hændelser.
• Faktureringskorrektion: opret justeringsbegivenheder og bevar de oprindelige brugsregistreringer.

Runbooks bør definere, hvem der kan udføre hver handling. Suspendering af én nøgle er anderledes end at deaktivere en partnerorganisation. At hæve en kvote er anderledes end at ændre en kontrakt. Nødkontrol har brug for revisionsspor.

Trade-offs

En Partner API-gateway tilføjer forsinkelse og driftsansvar. Det er omkostningerne ved at kontrollere legitimationsoplysninger, kvoter, routing, fakturering og synlighed på partnerkontraktniveau.

Strenge kvoter beskytter marginer og reducerer misbrug, men de kan skabe unødvendige fejl, hvis burst-adfærd og genforsøgsvejledning er dårligt designet. Et nyttigt kvotesystem har både hårde grænser og dokumenteret burst-adfærd.

Detaljeret måling forbedrer faktureringsgennemsigtighed og supportresultater, men det øger opbevarings-, privatlivs- og afstemningsforpligtelser. Indsaml de identifikatorer, der er nødvendige for drift og fakturering, men undgå at gemme rå prompt- og svarindhold i faktureringsregistreringer, medmindre der er et klart kontraktmæssigt og overholdelsesgrundlag.

Modelabstraktion gør partnerintegrationer enklere, men overdreven abstraktion kan skjule materielle forskelle. Partnere behøver ikke at kende alle udbyderimplementeringsdetaljer, men de skal vide, hvornår et modelalias ændrer kontekstgrænser, outputformater, ventetidsforventninger eller regional tilgængelighed.

Implementeringstjekliste

• Udsted platformejede partnernøgler i stedet for at dele udbyderoplysninger.
• Kortlæg hver nøgle til partner-, applikations-, miljø-, berettigelses-, kvote- og faktureringsregistreringer.
• Hold godkendelses- og berettigelsestjek adskilt fra routinglogik.
• Brug stabile modelaliasser med dokumenterede muligheder og begrænsninger.
• Anvend kvotekontroller før opstrømsudbyderopkald.
• Returhastighedsgrænseoverskrifter og maskinlæsbare fejl.
• Kræv idempotensnøgler til slutpunkter, der opretter stats- eller fakturerbart arbejde.
• Udsend uforanderlige brugsbegivenheder, når anmodningen er fuldført.
• Afstem brug med udbyderregistreringer og partnerfakturaer.
• Vedligeholde runbooks for nøglekompromis, løbsk brug, udbyderafbrydelse, kvoteopbrug, genafspilning af webhook og faktureringskorrektion.

Handlingsbar konklusion

Den sikreste partner API for LLM-adgang er ikke en proxy, der videresender anmodninger med skjulte legitimationsoplysninger. Det er et delegeret adgangssystem med sin egen identitetsmodel, politiklag, kvotehåndhævelse, forbrugsmåler, afstemningsproces og partnervendt gennemsigtighed.

Start med kontrolgrænserne: partnernøgler, eksplicitte rettigheder, kontrol af kvoter forud for opkald, idempotente tilstandsændrende slutpunkter og uforanderlige brugshændelser. Tilføj derefter operationel modenhed: dashboards, afstemning, hastighedsgrænsesemantik og hændelses-runbooks. Denne arkitektur lader partnere bygge videre på LLM-kapaciteter uden at modtage rå udbydernøgler, samtidig med at den giver platformen tilstrækkelig kontrol til at administrere omkostninger, misbrug, pålidelighed og faktureringstvister.

Relateret læsning

• designer styret API for teams og partnere integrationer