Jak vytvořit partnerské LLM API bez odhalení nezpracovaných klíčů poskytovatele

Partner API pro přístup LLM by neměl být tenkým obalem kolem klíčů poskytovatele. Pokud partneři, prodejci nebo zákaznické aplikace potřebují delegovaný přístup k jazykovým modelům, platforma potřebuje vlastní řídicí rovinu, bránu, vrstvu zásad, měřící kanál a provozní sady. Jinak se fakturace na úrovni poskytovatele, limity na úrovni poskytovatele a sdílené přihlašovací údaje stanou jedinými ovládacími prvky mezi integrací jednoho partnera a velmi nákladným incidentem.

Cíl je přímočarý: umožnit externím stranám využívat možnosti LLM prostřednictvím vaší platformy, zatímco vy budete udržovat přihlašovací údaje poskytovatele v soukromí, vynucovat nároky specifické pro partnery, měřit zpoplatněné využití a poskytnout partnerům dostatečnou transparentnost k budování spolehlivých klientů.

Referenční architektura

Praktický partner API má dvě hlavní části: řídicí rovinu a bránu požadavků.

Řídicí rovina spravuje partnerské organizace, aplikace, prostředí, delegované klíče API, modelové nároky, úrovně sazeb, limity útraty, fakturační podmínky, koncové body webhooku a záznamy auditu. Zde se obchodní a provozní pravidla stávají strojově čitelnými zásadami.

Brána požadavků přijímá partnerský provoz, ověřuje delegovaný klíč, vyhodnocuje zásady, aplikuje kvótu, směruje k vybranému poskytovateli modelu, zaznamenává využití a vrací metadata odpovědi viditelná pro partnery. Ve vyspělém podnikovém LLM API je tato brána také místem, kde jsou důsledně vynucovány směrování modelu, opakování, převzetí služeb při selhání, kontroly obsahu a pozorovatelnost.

Důležitá hranice je tato: partneři obdrží pouze klíče vydané vaší platformou. Nikdy neobdrží nezpracované přihlašovací údaje poskytovatele. Klíče poskytovatele upstream zůstávají v tajném úložišti vaší platformy a používají je pouze pracovníci brány nebo backendu.

Vzorec faktů, který se dá postavit

Následují fakta podporovaná dokumentací veřejných platforem a cloudu, nikoli předpoklady o nějakém konkrétním nasazení:

• Někteří poskytovatelé LLM podporují klíče v rozsahu projektu, servisní účty, přístup k modelu na úrovni projektu a limity sazeb na úrovni projektu.
• Cloudové pokyny pro rozhraní SaaS API pro více nájemců běžně oddělují správu zásad, rozhodování o zásadách a vynucování zásad, aby se omezil náhodný přístup mezi klienty.
• API brány a řídicí roviny SaaS mohou uplatňovat omezení a kvóty specifické pro nájemce, včetně úrovní sazeb, shluků a kvót.
• Fakturace SaaS založená na využití závisí na shromažďování aktivit tenanta, jejich agregaci a porovnání s fakturačními záznamy.
• Klíče idempotence jsou zdokumentovaným vzorem pro bezpečné opakování žádostí o změnu stavu API bez vytváření duplicitních vedlejších efektů.
• Standardizované hlavičky odezvy na omezení rychlosti mohou klientům pomoci porozumět limitům, zbývajícímu limitu, resetovat načasování a opakovat chování.

Doporučení je zkombinovat tyto vzory do přístupové vrstvy LLM pro partnery, kterou vlastníte, místo toho, abyste každého partnera žádali, aby se přímo integroval s každým poskytovatelem upstream modelu.

Krok 1: Definujte tenanta a model identity

Neidentifikujte partnerský provoz pouze jedním API řetězcem klíčů. Užitečný partner API potřebuje samostatné identifikátory, protože fakturace, kontrola zneužití, ladění kvót a šetření podpory často kladou různé otázky.

Vytvořte alespoň identifikátory pro:

• Partnerská organizace: smluvní externí společnost.
• Partnerská aplikace: konkrétní integrace, produkt, plugin nebo aplikace distributora.
• Prostředí: produkce, příprava, izolovaný prostor nebo vývoj.
• Koncový zákazník: Zákazník, pracovní prostor, účet nebo nájemce partnera, pokud je to smluvně povoleno a je to technicky dostupné.
• API key: delegované pověření používané k ověřování požadavků.
• ID požadavku: jedinečný identifikátor pro sledování jednoho požadavku v rámci vaší brány, volání poskytovatele, událostí využití a protokolů podpory.

Tato struktura se vyhýbá běžnému režimu selhání, kdy jednu kompromitovanou nebo hlučnou integraci lze popsat pouze jako „provoz partnera X“. Umožňuje vám také pozastavit jednu aplikaci nebo prostředí, aniž byste deaktivovali celé podnikání partnera.

Krok 2: Vydejte delegované partnerské klíče

Partnerské klíče by měly být prvotřídní objekty platformy, nikoli statické tokeny v tabulce. Každý klíč by měl mít metadata a vazby zásad:

• ID partnerské organizace
• ID aplikace
• Prostředí
• Povolené API povrchy, jako je chat, vkládání, dávka nebo generování obrázků
• Povolené aliasy modelu
• Omezení týkající se oblasti nebo rezidence dat, pokud jsou relevantní
• Úroveň limitu sazby
• Pravidlo limitu útraty nebo předplaceného zůstatku
• Čas vytvoření, čas posledního použití, vlastník a stav rotace

Pokud je to možné, ukládejte pouze hašovaný klíčový materiál, všechna tajemství odhalte pouze jednou při vytváření a podporujte rotaci bez prostojů. Praktický model rotace umožňuje dva aktivní klíče během krátkého přechodového okna, přičemž protokoly auditu ukazují, který klíč byl použit pro každý požadavek.

Krok 3: Oddělte nároky od směrování

Právo partnera používat model by nemělo být implikováno jakýmkoliv aktuálně podporovaným směrovacím kódem. Udržujte kontroly nároků explicitní a oddělené od výběru poskytovatele.

Například žádost o model: premium-reasoning by měla nejprve projít rozhodnutím o zásadách:

• Má tento partner povoleno používat alias modelu?
• Má je partnerská aplikace v tomto prostředí používat?
• Je požadavek v povolené oblasti nebo datové hranici?
• Je smlouva aktivní a v dobrém stavu?
• Splňuje partner hranice útraty, kvóty a zneužití?

Pouze po tomto rozhodnutí by směrování mělo zvolit poskytovatele upstream, projekt poskytovatele, nasazení nebo záložní cestu. To je důležité, protože změny směrování modelu jsou provozně časté. Změny nároků by měly být záměrné a kontrolovatelné.

Krok 4: Publikování stabilního partnera API Surface

Partneři potřebují stabilní chování, i když se vaši poskytovatelé upstreamu změní. Používejte vlastní aliasy modelu a popisy schopností namísto přímého odhalování názvů modelu každého poskytovatele.

Malý pří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 žádá o standard-chat. Vaše brána mapuje alias k aktuálnímu schválenému poskytovateli a modelu, s výhradou oprávnění, dostupnosti, ceny, latence, regionu a pravidel kvality.

Vyvarujte se však skrývání všech rozdílů mezi poskytovateli. Pokud mají dva aliasy modelu různá kontextová okna, podporu strukturovaného výstupu, chování při volání nástrojů, profily latence nebo regionální dostupnost, tyto rozdíly jasně zdokumentujte. Abstrakce by měla zjednodušit integraci, nikoli vytvářet překvapivé chování.

Krok 5: Vynucování kvót před voláním poskytovatele

Limity poskytovatelů jsou užitečné mantinely, ale vymáhání na úrovni partnera patří do vaší platformy. Jeden projekt upstream poskytovatele může sloužit mnoha partnerům nebo jeden partner může mít několik aplikací s různými smlouvami. Spoléhání se pouze na limity sazeb na úrovni poskytovatele nemůže tyto rozdíly jasně vyjádřit.

Před uskutečněním upstream volání použijte kontroly kvót:

• Požadavky za minutu podle klíče partnera
• Tokeny za minutu podle partnerské organizace
• Souběžné požadavky podle aplikace
• Denní nebo měsíční kvóta zúčtovatelných jednotek
• Předplacený zůstatek nebo kreditní hranice
• V případě potřeby omezení pro koncového zákazníka

U synchronních požadavků jasně odmítněte, když požadavek nelze přijmout. U asynchronních a dávkových úloh zvažte přijetí fronty odděleně od kvóty provádění. Hromadné nahrání může být přijato, ale jednotlivé úlohy by měly být stále měřeny a zastaveny, když je dosaženo limitů partnerů.

Krok 6: Vraťte signály předvídatelného limitu rychlosti

Neprůhledné 429 Too Many Requests odpovědi vytvářejí lístky podpory, kterým se lze vyhnout. Vracet signály kvót viditelné pro partnery u úspěšných a omezených odpovědí.

Užitečná odpověď může zahrnovat:

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

Doporučení:

• Dokumentujte, zda se omezení vztahují na klíč, aplikaci, organizaci, model nebo koncový bod.
• Vraťte načasování resetování, podle kterého mohou klienti jednat.
• Pro omezené odpovědi použijte Retry-After.
• Udržujte těla chyb stabilní a strojově čitelná.
• Neodhalujte interní informace poskytovatele upstream, pokud je partneři nepotřebují k ladění chování.

To usnadňuje vytváření partnerských klientů a snižuje počet opakovaných bouří během špiček provozu.

Krok 7: Použijte Idempotency pro fakturovatelnou práci

Každý koncový bod, který vytváří stav nebo fakturovatelnou práci, by měl podporovat klíče idempotence. To je důležité zejména pro úlohy asynchronního generování, hromadné odesílání, nákupy kreditů, opakované pokusy spouštěné webhookem a dlouhotrvající úlohy.

Pravidlo implementace je jednoduché: když partner zopakuje stejný požadavek se stejným klíčem idempotence v okně uchování, vrátí původní výsledek namísto vytváření duplicitní práce.

Uveďte okrajové případy explicitně:

• Jak dlouho se uchovávají záznamy idempotence
• Na který koncový bod a partnerský klíč se vztahuje klíč idempotence
• Co se stane, když je stejný klíč znovu použit s různými parametry požadavku
• Zda se neúspěšné požadavky ukládají do mezipaměti
• Jak se idempotence vztahuje na částečně dokončené dávkové úlohy

Pro zpoplatněnou práci LLM si uložte dostatek dat otisku požadavku, abyste mohli detekovat neshody parametrů, aniž byste uchovali zbytečný citlivý obsah datové části.

Krok 8: Vysílejte neměnné události použití

Nezacházejte s fakturami poskytovatelů jako se zdrojem pravdy pro partnerské fakturace. Faktury poskytovatelů obvykle neznají vaše partnerské smlouvy, pravidla pro označování, úrovně prodejců, ID koncových zákazníků nebo pracovní postup sporů. Místo toho vyšle neměnnou událost použití, když každý požadavek dosáhne stavu terminálu.

Událost použití by měla zahrnovat:

• ID partnerské organizace
• ID aplikace a prostředí
• API ID klíče, nikoli nezpracovaný klíč
• ID koncového zákazníka, pokud je poskytnuto a povoleno
• ID požadavku a ID korelace poskytovatele
• Alias modelu a model poskytovatele upstream
• Vstupní tokeny, výstupní tokeny, tokeny uložené v mezipaměti nebo jiné zúčtovatelné jednotky
• Základ ceny poskytovatele, pokud je k dispozici
• Partnerská fakturační jednotka, přirážka, čerpání kreditu nebo smluvní sazba
• Stav, třída chyb, latence a počet opakování
• Časové razítko a verze schématu

Tyto události poskytují informační panely partnerů, exporty fakturace, detekci anomálií, počítadla kvót a odsouhlasení. Ponechte stream události pouze jako přílohu. Opravy by měly být události úprav, nikoli tiché úpravy.

Krok 9: Denně sladit

Měření je užitečné pouze v případě, že je v souladu. Sestavte si každodenní proces, který porovnává vaše události používání s používáním poskytovatele, fakturami poskytovatele, zůstatky kreditu a fakturačními záznamy pro partnery.

Proces odsouhlasení by měl identifikovat:

• Požadavky přijaté vaší bránou, ale chybí události použití terminálu
• Využití poskytovatele, které nelze namapovat na požadavek partnera
• Rozdíly v počtu tokenů mezi přehledy poskytovatelů a záznamy brány
• Opakované pokusy, které byly účtovány nesprávně
• Ruční připsání kreditu, vrácení peněz a opravy fakturace
• Partneři se blíží útratě, předplacené vyčerpání nebo neobvyklý růst

Tady také finance, podpora a inženýrství potřebují stejná ID. Pokud nelze řídicí panel, řádkovou položku faktury, událost protokolu a záznam poskytovatele propojit, stanou se spory ručním vyšetřováním.

Krok 10: Sestavte provozní příručky

Partner API je externí produkt, takže provozní chování musí být naplánováno dříve, než dojde k incidentu. Napište runbooky minimálně pro tyto situace:

• Prolomený klíč partnera: zrušit nebo pozastavit jeden klíč, informovat partnera, zachovat protokoly auditu a poskytnout cestu k rotaci.
• Utékající použití: použijte nouzové čepice, pozastavte aplikaci nebo vyžádejte schválení pro další použití.
• Výpadek poskytovatele: převzetí služeb při selhání u schváleného poskytovatele nebo vrácení stabilní chyby s pokyny pro opakování.
• Vyčerpání kvóty: ukažte, zda partner musí čekat, upgradovat, zakoupit kredity nebo snížit provoz.
• Webhook replay: ověřovat podpisy, používat idempotency a sledovat pokusy o doručení událostí.
• Oprava fakturace:vytvářejte události úprav a zachovejte původní záznamy o použití.

Runbooky by měly definovat, kdo může provádět jednotlivé akce. Pozastavení jednoho klíče se liší od deaktivace partnerské organizace. Zvýšení kvóty se liší od změny smlouvy. Nouzové kontroly vyžadují auditní záznamy.

Ústupky

Brána partnera API zvyšuje latenci a provozní odpovědnost. To jsou náklady na řízení přihlašovacích údajů, kvót, směrování, fakturace a viditelnosti na úrovni partnerské smlouvy.

Přísné kvóty chrání marže a omezují zneužívání, ale mohou způsobit zbytečná selhání, pokud jsou špatně navrženy shlukové chování a pokyny pro opakování. Užitečný systém kvót má jak pevné limity, tak zdokumentované shlukové chování.

Podrobné měření zlepšuje transparentnost fakturace a výsledky podpory, ale zvyšuje povinnosti uchovávání, soukromí a odsouhlasení. Sbírejte identifikátory potřebné pro operace a fakturaci, ale vyvarujte se ukládání nezpracovaného obsahu výzev a odpovědí ve fakturačních záznamech, pokud neexistuje jasný smluvní základ a zásada dodržování předpisů.

Abstrakce modelů usnadňuje integraci partnerů, ale přílišná abstrakce může skrýt podstatné rozdíly. Partneři nemusí znát všechny podrobnosti implementace poskytovatele, ale potřebují vědět, kdy alias modelu změní kontextové limity, výstupní formáty, očekávání latence nebo regionální dostupnost.

Kontrolní seznam implementace

• Namísto sdílení přihlašovacích údajů poskytovatele vydávejte klíče partnera vlastněné platformou.
• Namapujte každý klíč na partnera, aplikaci, prostředí, nárok, kvótu a fakturační záznamy.
• Udržujte kontroly autorizace a oprávnění odděleně od směrovací logiky.
• Používejte stabilní aliasy modelu se zdokumentovanými možnostmi a limity.
• Aplikujte kontroly kvót před voláním poskytovatele upstream.
• Vracejí záhlaví s limitem rychlosti a strojově čitelné chyby.
• Vyžadovat klíče idempotence pro koncové body, které vytvářejí stavovou nebo fakturovatelnou práci.
• Po dokončení požadavku vysílat neměnné události použití.
• Srovnání použití se záznamy poskytovatele a partnerskými fakturami.
• Udržujte runbooky pro kompromitaci klíče, únikové využití, výpadek poskytovatele, vyčerpání kvóty, přehrávání webhooku a opravu fakturace.

Akční závěr

Nejbezpečnější partner API pro přístup k LLM není proxy, který přeposílá požadavky se skrytými přihlašovacími údaji. Jedná se o systém delegovaného přístupu s vlastním modelem identity, vrstvou zásad, vynucováním kvót, měřičem využití, procesem odsouhlasení a transparentností vůči partnerům.

Začněte s hranicemi kontroly: partnerské klíče, explicitní oprávnění, kontroly kvót před voláním, idempotentní koncové body měnící stav a neměnné události použití. Poté přidejte provozní vyspělost: řídicí panely, odsouhlasení, sémantika omezení rychlosti a sady incidentů. Tato architektura umožňuje partnerům stavět na schopnostech LLM, aniž by dostávali nezpracované klíče poskytovatelů, a zároveň poskytuje platformě dostatečnou kontrolu pro řízení nákladů, zneužití, spolehlivosti a fakturačních sporů.

Související čtení

• navrhování řízených klíčů API pro týmy a integrace partnerů