Kako izgraditi partnerski LLM API bez izlaganja neobrađenih ključeva dobavljača

Partner API za pristup LLM-u ne bi trebao biti tanki omot oko ključeva pružatelja usluga. Ako partneri, preprodavači ili korisničke aplikacije trebaju delegirani pristup jezičnim modelima, platforma treba vlastitu kontrolnu ravninu, pristupnik, sloj politike, cjevovod mjerenja i operativne runbookove. Inače, naplata na razini pružatelja usluga, ograničenja na razini pružatelja usluga i dijeljene vjerodajnice postaju jedina kontrola između integracije jednog partnera i vrlo skupog incidenta.

Cilj je jednostavan: dopustite vanjskim stranama da iskoriste mogućnosti LLM-a putem vaše platforme, dok vi čuvate privatnost vjerodajnica davatelja uzlaznih usluga, provodite prava specifična za partnera, mjerite naplativu upotrebu i dajte partnerima dovoljno transparentnosti za stvaranje pouzdanih klijenata.

Referentna arhitektura

Praktični partner API ima dva glavna dijela: kontrolnu razinu i pristupnik zahtjeva.

Kontrolna razina upravlja partnerskim organizacijama, aplikacijama, okruženjima, delegiranim API ključevima, ovlaštenjima modela, razinama ograničenja stope, ograničenjima potrošnje, uvjetima naplate, krajnjim točkama web-dojavnika i revizijskim zapisima. To je mjesto gdje komercijalna i operativna pravila postaju strojno čitljiva pravila.

Pristupnik zahtjeva prima partnerski promet, provjerava autentičnost delegiranog ključa, procjenjuje politiku, primjenjuje kvotu, usmjerava prema odabranom pružatelju modela, bilježi korištenje i vraća metapodatke odgovora vidljive partneru. U zrelom poduzetničkom LLM-u API, ovaj je pristupnik također mjesto na kojem se dosljedno provode usmjeravanje modela, ponovni pokušaji, prebacivanje greške, kontrole sadržaja i mogućnost promatranja.

Važna granica je sljedeća: partneri primaju samo ključeve koje je izdala vaša platforma. Nikada ne primaju sirove vjerodajnice pružatelja usluga. Ključevi pružatelja uzlaznih usluga ostaju u tajnoj trgovini vaše platforme i koriste ih samo pristupnici ili pozadinski radnici.

Uzorak činjenica oko kojeg se treba graditi

Sljedeće su činjenice potkrijepljene javnom platformom i dokumentacijom u oblaku, a ne pretpostavke o bilo kojoj implementaciji:

• Neki pružatelji LLM-a podržavaju ključeve s opsegom projekta, račune usluga, pristup modelu na razini projekta i ograničenja stopa na razini projekta.
• Cloud smjernice za SaaS API-je s više zakupaca obično odvajaju administraciju pravila, odluke o pravilima i provedbu pravila kako bi se smanjio slučajni pristup više zakupaca.
• API pristupnici i kontrolne razine SaaS-a mogu primijeniti prigušivanje i kvote specifične za zakupca, uključujući stope, burst i razine kvota.
• Naplata SaaS-a temeljena na korištenju ovisi o prikupljanju aktivnosti zakupca, njihovom prikupljanju i usklađivanju sa zapisima o naplati.
• Ključevi idempotencije su dokumentirani obrazac za siguran ponovni pokušaj API zahtjeva za promjenom stanja bez stvaranja dvostrukih nuspojava.
• Standardizirana zaglavlja odgovora o ograničenju brzine mogu pomoći klijentima da razumiju ograničenja, preostalo dopuštenje, vrijeme ponovnog postavljanja i ponašanje ponovnog pokušaja.

Preporuka je kombinirati ove uzorke u LLM pristupni sloj usmjeren prema partnerima koji posjedujete, umjesto da tražite od svakog partnera da se izravno integrira sa svakim pružateljem uzlaznog modela.

1. korak: Definirajte zakupca i model identiteta

Nemojte identificirati partnerski promet samo s jednim API nizom ključeva. Korisni partner API treba zasebne identifikatore jer naplata, pregled zlouporabe, otklanjanje grešaka u kvotama i istrage podrške često postavljaju različita pitanja.

Minimalno stvorite identifikatore za:

• Partnerska organizacija: ugovorna vanjska tvrtka.
• Partnerska aplikacija: određena aplikacija za integraciju, proizvod, dodatak ili prodavača.
• Okruženje: proizvodnja, inscenacija, sandbox ili razvoj.
• Krajnji kupac: partnerov kupac, radni prostor, račun ili zakupac, kada je to dopušteno ugovorom i tehnički dostupno.
• API ključ: delegirana vjerodajnica koja se koristi za provjeru autentičnosti zahtjeva.
• ID zahtjeva: jedinstveni identifikator za praćenje jednog zahtjeva preko vašeg pristupnika, poziva davatelja usluga, događaja korištenja i zapisa podrške.

Ova struktura izbjegava uobičajeni način neuspjeha gdje se jedna ugrožena ili šumna integracija može opisati samo kao "promet partnera X". Također vam omogućuje obustavu jedne aplikacije ili okruženja bez onemogućavanja cjelokupnog poslovanja partnera.

Korak 2: Izdavanje ključeva ovlaštenog partnera

Ključevi partnera trebaju biti prvoklasni objekti platforme, a ne statični tokeni u proračunskoj tablici. Svaki ključ treba imati metapodatke i pravila povezivanja:

• ID
partnerske organizacije
• ID aplikacije
• Okruženje
• Dopuštene API površine, kao što su chat, ugrađivanja, serija ili generiranje slika
• Dopušteni aliasi modela
• Ograničenja regije ili prebivališta podataka gdje je primjenjivo
• Razina ograničenja brzine
• Ograničenje potrošnje ili pravilo unaprijed plaćenog stanja
• Vrijeme stvaranja, vrijeme posljednje upotrebe, vlasnik i status rotacije

Pohranjujte samo raspršeni ključni materijal gdje je to moguće, izložite pune tajne samo jednom prilikom izrade i podržavajte rotaciju bez prekida rada. Praktičan model rotacije dopušta dva aktivna ključa tijekom kratkog prijelaznog prozora, s revizijskim zapisima koji pokazuju koji je ključ korišten za svaki zahtjev.

3. korak: Odvojite ovlaštenja od usmjeravanja

Pravo partnera da koristi model ne bi trebalo biti implicirano bilo kojim kodom usmjeravanja koji trenutno podržava. Neka provjere ovlaštenja budu eksplicitne i odvojene od odabira pružatelja usluga.

Na primjer, zahtjev za model: premium-reasoning prvo bi trebao proći odluku o politici:

• Smije li ovaj partner koristiti pseudonim modela?
• Smije li partnerska aplikacija to koristiti u ovom okruženju?
• Je li zahtjev unutar dopuštene regije ili granice podataka?
• Je li ugovor aktivan i u dobrom stanju?
• Je li partner unutar pragova potrošnje, kvote i zloupotrebe?

Tek nakon te odluke usmjeravanje bi trebalo odabrati uzlaznog pružatelja, projekt pružatelja, implementaciju ili rezervni put. Ovo je važno jer su operativno česte promjene rutiranja modela. Promjene prava trebaju biti namjerne i podložne provjeri.

Korak 4: Objavite stabilnog partnera API Površina

Partnerima je potrebno stabilno ponašanje čak i kada se promijene vaši uzvodni pružatelji usluga. Koristite svoje vlastite pseudonime modela i opise mogućnosti umjesto da izravno izlažete naziv modela svakog davatelja.

Mali primjer:

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 traži standard-chat. Vaš pristupnik preslikava taj alias na trenutno odobrenog pružatelja usluga i model, ovisno o pravima, dostupnosti, cijeni, kašnjenju, regiji i pravilima kvalitete.

Ipak, izbjegavajte skrivanje svih razlika u pružateljima usluga. Ako dva aliasa modela imaju različite kontekstne prozore, podršku za strukturirani izlaz, ponašanje pozivanja alata, profile latencije ili regionalnu dostupnost, jasno dokumentirajte te razlike. Apstrakcija bi trebala pojednostaviti integraciju, a ne stvoriti iznenađujuće ponašanje.

Korak 5: Nametnite kvote prije poziva davatelja usluga

Ograničenja pružatelja korisni su zaštitnici, ali provedba na razini partnera pripada vašoj platformi. Jedan projekt uzlaznog pružatelja usluga može služiti mnogim partnerima ili jedan partner može imati nekoliko aplikacija s različitim ugovorima. Oslanjanje samo na ograničenja cijena na razini pružatelja usluga ne može jasno izraziti te razlike.

Primijeni provjere kvota prije upućivanja uzvodnih poziva:

• Broj zahtjeva po minuti prema ključu partnera
• Tokeni po minuti prema partnerskoj organizaciji
• Istovremeni zahtjevi po aplikaciji
• Dnevna ili mjesečna naplativa jedinična kvota
• Unaprijed plaćeno stanje ili kreditni prag
• Ograničenja po krajnjem korisniku gdje je potrebno

Za sinkrone zahtjeve, jasno odbijte kada se zahtjev ne može prihvatiti. Za asinkrona i skupna radna opterećenja, pristup redu čekanja razmotrite odvojeno od kvote izvršenja. Skupno učitavanje može biti prihvaćeno, ali bi se pojedinačni poslovi ipak trebali mjeriti i zaustaviti kada se dostignu ograničenja partnera.

Korak 6: Vratite predvidljive signale ograničenja brzine

Neprozirni 429 Too Many Requests odgovori stvaraju prijave podrške koje se mogu izbjeći. Vrati partneru vidljive signale kvote za uspješne i prigušene odgovore.

Korisni odgovor može uključivati:

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

Preporuke:

• Dokumentirajte primjenjuju li se ograničenja po ključu, aplikaciji, organizaciji, modelu ili krajnjoj točki.
• Vrijeme ponovnog vraćanja prema kojem klijenti mogu djelovati.
• Koristite Retry-After za prigušene odgovore.
• Održavajte tijela pogrešaka stabilnima i strojno čitljivima.
• Nemojte izlagati interne podatke uzvodnog pružatelja osim ako ih partneri ne trebaju za otklanjanje pogrešaka u ponašanju.

To olakšava izgradnju partnerskih klijenata i smanjuje broj ponovnih pokušaja tijekom skokova prometa.

Korak 7: Koristite idempotenciju za naplativi posao

Svaka krajnja točka koja stvara stanje ili naplativi rad trebala bi podržavati ključeve idempotencije. Ovo je posebno važno za poslove asinkronog generiranja, skupne prijave, kupnje kredita, ponovne pokušaje pokrenute web-dojavnikom i zadatke koji se dugo izvode.

Pravilo implementacije je jednostavno: kada partner ponovi isti zahtjev s istim ključem idempotencije unutar prozora zadržavanja, vraća izvorni rezultat umjesto stvaranja duplikata.

Učinite rubne slučajeve eksplicitnim:

• Koliko se dugo čuvaju zapisi o idempotenciji
• Na koju krajnju točku i partnerski ključ je ključ idempotencije dodijeljen
• Što se događa ako se isti ključ ponovno upotrijebi s različitim parametrima zahtjeva
• Spremaju li se neuspjeli zahtjevi u predmemoriju
• Kako se idempotencija primjenjuje na djelomično dovršene skupne poslove

Za naplativi LLM rad, pohranite dovoljno podataka o otiscima zahtjeva za otkrivanje nepodudarnosti parametara bez zadržavanja nepotrebnog osjetljivog sadržaja.

Korak 8: Emitiranje nepromjenjivih događaja upotrebe

Nemojte smatrati fakture dobavljača izvorom istine za partnersku naplatu. Fakture dobavljača obično ne poznaju vaše partnerske ugovore, pravila označavanja, razine preprodavača, ID-ove krajnjih kupaca ili radni tijek sporova. Umjesto toga, emitirajte nepromjenjivi događaj upotrebe kada svaki zahtjev dosegne terminalno stanje.

Događaj korištenja trebao bi uključivati:

• ID
partnerske organizacije
• ID aplikacije i okruženje
• API ID ključa, a ne neobrađeni ključ
• ID krajnjeg kupca ako je naveden i dopušten
• ID zahtjeva i ID korelacije pružatelja usluga
• Pseudonim modela i model uzvodnog pružatelja usluga
• Ulazni tokeni, izlazni tokeni, predmemorirani tokeni ili druge naplative jedinice
• Osnova troškova pružatelja usluga kada je dostupna
• Partnerska obračunska jedinica, marža, povlačenje kredita ili ugovorna stopa
• Status, klasa pogreške, latencija i broj ponovnih pokušaja
• Vremenska oznaka i verzija sheme

Ovi događaji unose podatke o partnerskim nadzornim pločama, izvozima naplate, otkrivanju anomalija, brojačima kvota i usklađivanju. Zadržite tok događaja samo za dodavanje. Ispravci bi trebali biti događaji prilagodbe, a ne tiha uređivanja.

9. korak: Dnevno usklađivanje

Mjerenje je korisno samo ako usklađuje. Izgradite dnevni proces koji uspoređuje vaše događaje upotrebe s upotrebom pružatelja usluga uzvodno, fakturama pružatelja usluga, kreditnim saldom i zapisima o naplati prema partnerima.

Proces usklađivanja treba identificirati:

• Zahtjevi prihvaćeni od strane vašeg pristupnika, ali nedostaju događaji upotrebe terminala
• Upotreba pružatelja usluga koja se ne može preslikati na zahtjev partnera
• Razlike u broju tokena između izvješća pružatelja usluga i zapisa pristupnika
• Ponovni pokušaji koji su netočno naplaćeni
• Ručni krediti, povrati i ispravci naplate
• Partneri koji se približavaju planiranoj potrošnji, iscrpljenost unaprijed plaćenih sredstava ili neobičan rast

Ovdje također financije, podrška i inženjering trebaju iste ID-ove. Ako se nadzorna ploča, stavka fakture, događaj zapisnika i zapis pružatelja ne mogu povezati zajedno, sporovi postaju ručne istrage.

Korak 10: Izgradite operativne Runbookove

Partner API je vanjska površina proizvoda, tako da se operativno ponašanje mora planirati prije nego što dođe do incidenata. Barem napišite priručnike za ove situacije:

• Kompromitirani partnerski ključ: opozovite ili suspendirajte jedan ključ, obavijestite partnera, sačuvajte revizijske zapisnike i osigurajte putanju rotacije.
• Neprekidna upotreba: primijenite hitna ograničenja, pauzirajte aplikaciju ili zahtijevajte odobrenje za daljnju upotrebu.
• Ispad pružatelja usluga: prebacite na odobrenog pružatelja usluga ili vratite stabilnu pogrešku uz upute za ponovni pokušaj.
• Iscrpljivanje kvote: pokazuju treba li partner čekati, nadograditi, kupiti kredite ili smanjiti promet.
• Reprodukcija web-dojavnika: provjerite potpise, koristite idempotenciju i pratite pokušaje isporuke događaja.
• Ispravak naplate: kreirajte događaje prilagodbe i sačuvajte izvornu evidenciju upotrebe.

Runbooks bi trebao definirati tko može poduzeti svaku radnju. Obustava jednog ključa razlikuje se od onesposobljavanja partnerske organizacije. Povećanje kvote razlikuje se od promjene ugovora. Kontrole u hitnim slučajevima trebaju revizijske tragove.

Ustupci

Partner API pristupnik dodaje kašnjenje i operativnu odgovornost. To je trošak kontrole vjerodajnica, kvota, usmjeravanja, naplate i vidljivosti na razini partnerskog ugovora.

Stroge kvote štite margine i smanjuju zlouporabu, ali mogu stvoriti nepotrebne kvarove ako su burst ponašanje i upute za ponovni pokušaj loše osmišljene. Koristan sustav kvota ima čvrsta ograničenja i dokumentirano burst ponašanje.

Detaljno mjerenje poboljšava transparentnost naplate i rezultate podrške, ali povećava obaveze zadržavanja, privatnosti i usklađivanja. Prikupite identifikatore potrebne za operacije i naplatu, ali izbjegavajte pohranjivanje neobrađenog sadržaja upita i odgovora u evidenciji naplate osim ako ne postoji jasna ugovorna osnova i osnova usklađenosti.

Apstrakcija modela čini integracije partnera jednostavnijima, ali pretjerana apstrakcija može sakriti materijalne razlike. Partneri ne moraju znati svaki detalj implementacije pružatelja usluga, ali moraju znati kada pseudonim modela mijenja ograničenja konteksta, izlazne formate, očekivane latencije ili regionalnu dostupnost.

Kontrolni popis za implementaciju

• Izdaj partnerske ključeve u vlasništvu platforme umjesto dijeljenja vjerodajnica pružatelja usluga.
• Mapiranje svakog ključa na partnera, aplikaciju, okruženje, pravo, kvotu i zapise o naplati.
• Držite provjere autorizacije i ovlaštenja odvojene od logike usmjeravanja.
• Koristite stabilne aliase modela s dokumentiranim mogućnostima i ograničenjima.
• Primijeni provjere kvota prije poziva uzvodnog pružatelja usluga.
• Vrati zaglavlja ograničenja brzine i strojno čitljive pogreške.
• Zahtijevaj ključeve idempotencije za krajnje točke koje stvaraju stanje ili naplativi rad.
• Emitiraj nepromjenjive događaje upotrebe po završetku zahtjeva.
• Uskladite korištenje s zapisima pružatelja usluga i fakturama partnera.
• Održavajte runbookove za kompromitaciju ključa, nenamjernu upotrebu, prekid rada pružatelja usluga, iscrpljenost kvote, ponavljanje webdojavnika i ispravak naplate.

Zaključak koji se može poduzeti

Najsigurniji partner API za pristup LLM-u nije proxy koji prosljeđuje zahtjeve sa skrivenim vjerodajnicama. To je sustav delegiranog pristupa s vlastitim modelom identiteta, slojem politike, provedbom kvota, mjeračem upotrebe, postupkom usklađivanja i transparentnošću prema partnerima.

Počnite s granicama kontrole: partnerski ključevi, eksplicitna ovlaštenja, provjere kvota prije poziva, idempotentne krajnje točke koje mijenjaju stanje i nepromjenjivi događaji upotrebe. Zatim dodajte operativnu zrelost: nadzorne ploče, usklađivanje, semantiku ograničenja brzine i popise incidenata. Ova arhitektura omogućuje partnerima izgradnju LLM mogućnosti bez primanja neobrađenih ključeva dobavljača, dok platformi daje dovoljno kontrole za upravljanje troškovima, zloupotrebom, pouzdanošću i sporovima oko naplate.

Povezano čitanje

• dizajniranje upravljanih API ključeva za timove i partnere integracije