Ako vytvoriť partnerské LLM API bez odhalenia kľúčov Raw Provider

Partner API pre prístup LLM by nemal byť tenký obal okolo kľúčov poskytovateľa. Ak partneri, predajcovia alebo zákaznícke aplikácie potrebujú delegovaný prístup k jazykovým modelom, platforma potrebuje vlastnú riadiacu rovinu, bránu, vrstvu politiky, merací kanál a prevádzkové príručky. V opačnom prípade sa fakturácia na úrovni poskytovateľa, limity na úrovni poskytovateľa a zdieľané poverenia stanú jedinými kontrolami medzi integráciou jedného partnera a veľmi nákladným incidentom.

Cieľ je priamočiary: nechajte externé strany využívať možnosti LLM prostredníctvom vašej platformy, pričom poverenia poskytovateľa upstream ponecháte v súkromí, presadzujete nároky špecifické pre partnerov, meriate fakturovateľné využitie a poskytujete partnerom dostatočnú transparentnosť na budovanie spoľahlivých klientov.

Referenčná architektúra

Praktický partner API má dve hlavné časti: kontrolnú rovinu a bránu požiadaviek.

Rovina riadenia spravuje partnerské organizácie, aplikácie, prostredia, delegované kľúče API, modelové nároky, úrovne limitov sadzieb, limity výdavkov, fakturačné podmienky, koncové body webhooku a záznamy auditu. Tu sa obchodné a prevádzkové pravidlá stávajú strojovo čitateľnými pravidlami.

Brána požiadaviek prijíma návštevnosť partnera, overuje delegovaný kľúč, vyhodnocuje politiku, aplikuje kvótu, smeruje k vybranému poskytovateľovi modelu, zaznamenáva použitie a vracia metadáta odpovede viditeľné pre partnera. Vo vyspelom podnikovom LLM API je táto brána tiež miestom, kde sa dôsledne vynucuje smerovanie modelu, opakované pokusy, núdzové prepnutie, kontroly obsahu a pozorovateľnosť.

Dôležitá hranica je táto: partneri dostanú iba vaše kľúče vydané platformou. Nikdy nedostanú nespracované poverenia poskytovateľa. Kľúče poskytovateľa upstream zostávajú v tajnom obchode vašej platformy a používajú ich iba pracovníci brány alebo backendu.

Vzorec faktov, na ktorom sa dá postaviť

Nasledujú fakty podporované dokumentáciou verejnej platformy a cloudu, nie predpoklady o jednom nasadení:

• Niektorí poskytovatelia LLM podporujú kľúče v rozsahu projektu, účty služieb, prístup k modelu na úrovni projektu a limity sadzieb na úrovni projektu.
• Cloudové pokyny pre SaaS API pre viacerých nájomníkov bežne oddeľujú správu pravidiel, rozhodovanie o pravidlách a presadzovanie pravidiel, aby sa znížil náhodný prístup medzi viacerými nájomníkmi.
• API brány a riadiace roviny SaaS môžu uplatňovať obmedzenia a kvóty špecifické pre nájomníkov vrátane úrovní frekvencie, zhluku a kvót.
• Fakturácia SaaS založená na použití závisí od zhromažďovania aktivít nájomníka, ich agregácie a ich zosúladenia so záznamami fakturácie.
• Kľúče idempotencie sú zdokumentovaným vzorom na bezpečné opakovanie žiadostí o zmenu stavu API bez vytvárania duplicitných vedľajších účinkov.
• Štandardizované hlavičky odozvy frekvenčného limitu môžu klientom pomôcť pochopiť limity, zostávajúci limit, resetovať načasovanie a zopakovať správanie.

Odporúčame skombinovať tieto vzory do partnerskej prístupovej vrstvy LLM, ktorú vlastníte, namiesto toho, aby ste od každého partnera žiadali priamu integráciu s každým poskytovateľom modelu upstream.

Krok 1: Definujte nájomníka a model identity

Neidentifikujte návštevnosť partnerov iba jedným reťazcom kľúčov API. Užitočný partner API potrebuje samostatné identifikátory, pretože fakturácia, kontrola zneužitia, ladenie kvót a vyšetrovanie podpory často kladú rôzne otázky.

Vytvorte aspoň identifikátory pre:

• Partnerská organizácia: zmluvná externá spoločnosť.
• Aplikácia pre partnerov: konkrétna integrácia, produkt, doplnok alebo aplikácia predajcu.
• Prostredie: produkcia, príprava, karanténa alebo vývoj.
• Koncový zákazník: zákazník, pracovný priestor, účet alebo nájomca partnera, ak je to zmluvne povolené a technicky dostupné.
• API kľúč: delegované poverenia používané na overenie žiadostí.
• ID požiadavky: jedinečný identifikátor na sledovanie jednej požiadavky v rámci vašej brány, hovorov poskytovateľa, udalostí používania a denníkov podpory.

Táto štruktúra sa vyhýba bežnému režimu zlyhania, kde jednu narušenú alebo hlučnú integráciu možno opísať iba ako „prenos partnera X“. Umožňuje vám tiež pozastaviť jednu aplikáciu alebo prostredie bez toho, aby ste deaktivovali celý biznis partnera.

Krok 2: Vydanie delegovaných partnerských kľúčov

Partnerské kľúče by mali byť prvotriedne objekty platformy, nie statické tokeny v tabuľke. Každý kľúč by mal mať metadáta a väzby pravidiel:

• ID partnerskej organizácie
• ID aplikácie
• Prostredie
• Povolené API povrchy, ako je čet, vkladanie, dávkové vytváranie alebo generovanie obrázkov
• Povolené aliasy modelu
• Obmedzenia týkajúce sa oblasti alebo bydliska údajov, ak sa uplatňujú
• Úroveň limitu sadzby
• Pravidlo limitu výdavkov alebo predplateného zostatku
• Čas vytvorenia, čas posledného použitia, vlastník a stav rotácie

Ak je to možné, ukladajte iba hašovaný kľúčový materiál, odhaľte úplné tajomstvá iba raz pri vytváraní a podporte rotáciu bez prestojov. Praktický model rotácie umožňuje dva aktívne kľúče počas krátkeho prechodového obdobia, pričom protokoly auditu ukazujú, ktorý kľúč bol použitý pre každú požiadavku.

Krok 3: Oddeľte oprávnenia od smerovania

Právo partnera na používanie modelu by nemalo byť zahrnuté v žiadnom aktuálne podporovanom smerovom kóde. Kontroly nárokov majte explicitné a oddelené od výberu poskytovateľa.

Napríklad žiadosť o model: premium-reasoning by mala najprv prejsť rozhodnutím o pravidlách:

• Má tento partner povolenie používať alias modelu?
• Môže ho partnerská aplikácia používať v tomto prostredí?
• Je požiadavka v rámci povolenej oblasti alebo hranice údajov?
• Je zmluva aktívna a v dobrom stave?
• Spĺňa partner limity výdavkov, kvót a zneužitia?

Až po tomto rozhodnutí by smerovanie malo zvoliť poskytovateľa upstream, projekt poskytovateľa, nasadenie alebo záložnú cestu. To je dôležité, pretože zmeny smerovania modelu sú prevádzkovo časté. Zmeny oprávnení by mali byť zámerné a kontrolovateľné.

4. krok: Zverejnite stabilného partnera API Surface

Partneri potrebujú stabilné správanie, aj keď sa zmenia vaši dodávatelia. Namiesto priameho odhaľovania každého názvu modelu poskytovateľa použite svoje vlastné aliasy modelu a popisy schopností.

Malý príklad:

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"
  }
}

Partner žiada o standard-chat. Vaša brána mapuje alias k aktuálnemu schválenému poskytovateľovi a modelu v závislosti od oprávnenia, dostupnosti, ceny, latencie, regiónu a pravidiel kvality.

Vyhnite sa však skrývaniu všetkých rozdielov medzi poskytovateľmi. Ak majú dva aliasy modelu rôzne kontextové okná, podporu štruktúrovaného výstupu, správanie pri volaní nástrojov, profily latencie alebo regionálnu dostupnosť, tieto rozdiely jasne zdokumentujte. Abstrakcia by mala zjednodušiť integráciu, nie vytvárať prekvapivé správanie.

Krok 5: Presadzovanie kvót pred hovormi poskytovateľa

Limity poskytovateľov sú užitočné mantinely, ale presadzovanie na úrovni partnera patrí do vašej platformy. Jeden projekt dodávateľa môže slúžiť viacerým partnerom alebo jeden partner môže mať niekoľko aplikácií s rôznymi zmluvami. Spoliehanie sa len na limity sadzieb na úrovni poskytovateľa nemôže tieto rozdiely vyjadriť čisto.

Aplikujte kontroly kvót pred uskutočnením upstream hovorov:

• Požiadavky za minútu podľa partnerského kľúča
• Tokeny za minútu podľa partnerskej organizácie
• Súbežné požiadavky podľa aplikácie
• Kvóta dennej alebo mesačnej fakturovateľnej jednotky
• Predplatený zostatok alebo kreditný limit
• Obmedzenia pre koncového zákazníka, ak sa vyžadujú

V prípade synchrónnych žiadostí jasne odmietnite, keď žiadosť nemožno prijať. Pri asynchrónnych a dávkových pracovných zaťaženiach zvážte prijatie do frontu oddelene od kvóty vykonávania. Hromadné nahrávanie môže byť prijaté, ale jednotlivé úlohy by sa mali stále merať a zastaviť, keď sa dosiahnu limity partnerov.

Krok 6: Vráťte signály predvídateľnej rýchlosti a limitu

Nepriehľadné 429 Too Many Requests odpovede vytvárajú lístky na podporu, ktorým sa dá vyhnúť. Vráťte signály kvóty viditeľné pre partnera pri úspešných a obmedzených odpovediach.

Užitočná odpoveď môže zahŕňať:

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

Odporúčania:

• Dokumentujte, či sa limity vzťahujú na kľúč, aplikáciu, organizáciu, model alebo koncový bod.
• Vráťte načasovanie resetovania, na základe ktorého môžu klienti konať.
• Použite Retry-After na obmedzené reakcie.
• Udržiavajte telá chýb stabilné a strojovo čitateľné.
• Neodhaľujte interné informácie poskytovateľa upstream, pokiaľ ich partneri nepotrebujú na ladenie správania.

To uľahčuje vytváranie partnerských klientov a znižuje počet opakovaných búrok počas špičiek v premávke.

Krok 7: Využite idempotenciu na fakturovateľnú prácu

Každý koncový bod, ktorý vytvára stav alebo fakturovateľnú prácu, by mal podporovať kľúče idempotencie. Toto je obzvlášť dôležité pre úlohy asynchrónneho generovania, hromadné odosielanie, nákupy kreditov, opakované pokusy spustené webhookom a dlhotrvajúce úlohy.

Pravidlo implementácie je jednoduché: keď partner zopakuje rovnakú požiadavku s rovnakým kľúčom idempotencie v okne uchovávania, vráti pôvodný výsledok namiesto vytvárania duplicitnej práce.

Určite okrajové prípady explicitne:

• Ako dlho sa uchovávajú záznamy idempotencie
• Na ktorý koncový bod a kľúč partnera sa vzťahuje kľúč idempotencie
• Čo sa stane, ak sa rovnaký kľúč znova použije s rôznymi parametrami požiadavky
• Či sa neúspešné žiadosti ukladajú do vyrovnávacej pamäte
• Ako sa idempotencia vzťahuje na čiastočne dokončené dávkové úlohy

Pre spoplatnenú prácu LLM si uložte dostatok údajov o odtlačkoch požiadaviek na zistenie nesúladu parametrov bez toho, aby ste uchovali nepotrebný citlivý obsah dát.

Krok 8: Vysielanie nemenných udalostí používania

Nepovažujte faktúry poskytovateľa za zdroj pravdivosti pre fakturáciu partnera. Faktúry poskytovateľa zvyčajne nepoznajú vaše partnerské zmluvy, pravidlá označovania, úrovne predajcov, ID koncových zákazníkov alebo pracovný postup sporov. Namiesto toho vygenerujte nemennú udalosť použitia, keď každá požiadavka dosiahne stav terminálu.

Udalosť použitia by mala zahŕňať:

• ID partnerskej organizácie
• ID aplikácie a prostredie
• API ID kľúča, nie nespracovaný kľúč
• ID koncového zákazníka, ak je poskytnuté a povolené
• ID žiadosti a korelačné ID poskytovateľa
• Alias modelu a model poskytovateľa upstream
• Vstupné tokeny, výstupné tokeny, tokeny uložené vo vyrovnávacej pamäti alebo iné fakturovateľné jednotky
• Základ ceny poskytovateľa, ak je k dispozícii
• Fakturačná jednotka partnera, prirážka, čerpanie kreditu alebo zmluvná sadzba
• Stav, trieda chýb, latencia a počet opakovaní
• Časová pečiatka a verzia schémy

Tieto udalosti poskytujú informačné panely partnerov, exporty fakturácie, detekciu anomálií, počítadlá kvót a vyrovnanie. Ponechajte stream udalosti len ako prílohu. Opravy by mali byť udalosti úprav, nie tiché úpravy.

Krok 9: Denné zladenie

Meranie je užitočné iba vtedy, ak je v súlade. Vytvorte denný proces, ktorý porovnáva vaše udalosti používania s používaním poskytovateľa, faktúrami poskytovateľa, kreditnými zostatkami a fakturačnými záznamami pre partnerov.

Proces vyrovnania by mal identifikovať:

• Požiadavky prijaté vašou bránou, ale chýbajúce udalosti používania terminálu
• Používanie poskytovateľa, ktoré nemožno priradiť k partnerskej žiadosti
• Rozdiely v počte tokenov medzi prehľadmi poskytovateľa a záznamami brány
• Opätovné pokusy, ktoré boli účtované nesprávne
• Manuálne kredity, vrátenia peňazí a opravy fakturácie
• Partneri sa blížia k viazaným výdavkom, predplatenému vyčerpaniu alebo neobvyklému rastu

Aj tu potrebujú financie, podpora a inžinierstvo rovnaké ID. Ak sa informačný panel, riadková položka faktúry, udalosť denníka a záznam poskytovateľa nedajú prepojiť, spory sa stanú ručným vyšetrovaním.

10. krok: Vytvorte prevádzkové príručky

Partner API je externý produkt, takže prevádzkové správanie sa musí naplánovať skôr, ako dôjde k incidentom. Napíšte runbooky minimálne pre tieto situácie:

• Kompromitovaný partnerský kľúč: odvolať alebo pozastaviť jeden kľúč, upozorniť partnera, zachovať denníky auditu a poskytnúť cestu k rotácii.
• Ubehnuté použitie: použite núdzové čiapky, pozastavte aplikáciu alebo vyžiadajte schválenie na ďalšie použitie.
• Výpadok poskytovateľa: zlyhanie u schváleného poskytovateľa alebo sa vráti stabilná chyba s pokynom na zopakovanie.
• Vyčerpanie kvóty: ukážte, či partner musí čakať, upgradovať, kúpiť kredity alebo znížiť návštevnosť.
• Prehrávanie webhooku: overte podpisy, použite idempotenciu a sledujte pokusy o doručenie udalostí.
• Oprava fakturácie: vytvorte udalosti úprav a zachovajte pôvodné záznamy o použití.

Runbooky by mali definovať, kto môže vykonať jednotlivé akcie. Pozastavenie jedného kľúča sa líši od deaktivácie partnerskej organizácie. Zvýšenie kvóty sa líši od zmeny zmluvy. Núdzové kontroly potrebujú audit trail.

Ústupky

Brána partnera API pridáva latenciu a prevádzkovú zodpovednosť. To sú náklady na kontrolu poverení, kvót, smerovania, fakturácie a viditeľnosti na úrovni partnerskej zmluvy.

Prísne kvóty chránia marže a obmedzujú zneužívanie, ale môžu spôsobiť zbytočné zlyhania, ak sú nesprávne navrhnuté burstové správanie a návod na opakovanie. Užitočný systém kvót má pevné limity aj zdokumentované zhlukové správanie.

Podrobné meranie zlepšuje transparentnosť fakturácie a výsledky podpory, zvyšuje však povinnosti uchovávania, ochrany osobných údajov a odsúhlasenia. Zhromažďujte identifikátory potrebné na operácie a fakturáciu, ale vyhnite sa ukladaniu nespracovaného obsahu výziev a odpovedí vo fakturačných záznamoch, pokiaľ neexistuje jasný zmluvný základ a súlad s predpismi.

Abstrakcia modelov zjednodušuje integráciu partnerov, ale nadmerná abstrakcia môže skryť materiálne rozdiely. Partneri nemusia poznať všetky podrobnosti implementácie poskytovateľa, ale potrebujú vedieť, kedy alias modelu zmení kontextové limity, výstupné formáty, očakávania latencie alebo regionálnu dostupnosť.

Kontrolný zoznam implementácie

• Namiesto zdieľania poverení poskytovateľa vydávajte kľúče partnerov vlastnených platformou.
• Namapujte každý kľúč na partnera, aplikáciu, prostredie, nárok, kvótu a fakturačné záznamy.
• Uchovávajte kontroly autorizácie a oprávnení oddelené od smerovacej logiky.
• Používajte stabilné aliasy modelov so zdokumentovanými možnosťami a limitmi.
• Aplikujte kontroly kvót pred hovormi poskytovateľa upstream.
• Vráťte hlavičky s limitom rýchlosti a strojovo čitateľné chyby.
• Vyžadovať kľúče idempotencie pre koncové body, ktoré vytvárajú stav alebo fakturovateľnú prácu.
• Po dokončení požiadavky vysielať nemenné udalosti používania.
• Zosúladiť používanie so záznamami poskytovateľa a partnerskými faktúrami.
• Udržiavajte runbooky pre ohrozenie kľúčov, nekontrolované využitie, výpadok poskytovateľa, vyčerpanie kvóty, prehratie webhooku a opravu fakturácie.

Uplatniteľný záver

Najbezpečnejší partner API pre prístup k LLM nie je proxy server, ktorý posiela žiadosti so skrytými povereniami. Ide o systém delegovaného prístupu s vlastným modelom identity, vrstvou pravidiel, presadzovaním kvót, meračom využitia, procesom zosúlaďovania a transparentnosťou pre partnerov.

Začnite s hranicami kontroly: partnerské kľúče, explicitné oprávnenia, kontroly kvóty pred hovorom, idempotentné koncové body meniace stav a nemenné udalosti používania. Potom pridajte prevádzkovú zrelosť: informačné panely, zosúladenie, sémantiku rýchlostného limitu a príručky incidentov. Táto architektúra umožňuje partnerom stavať na schopnostiach LLM bez toho, aby dostávali nespracované kľúče poskytovateľa, pričom platforme poskytuje dostatočnú kontrolu na riadenie nákladov, zneužívania, spoľahlivosti a sporov týkajúcich sa fakturácie.

Súvisiace čítanie

• navrhovanie riadených kľúčov API pre tímy a integrácie partnerov