Zgradite knjigo obračunavanja API-ja AI: ponudite, rezervirajte, poravnajte in uskladite vsak modelni klic

Obrnjeno k strankam AI API obračunavanje ne more biti mesečni izvoz neobdelane uporabe ponudnika. Če prehod izpostavi več modelov najemnikom, skupinam ali partnerjem, mora obračunavanje odgovoriti na težje vprašanje, preden obstaja račun: ali je treba to zahtevo dovoliti zdaj in kako bodo njeni stroški razloženi pozneje?

Praktični vzorec je obračunska knjiga s štirimi stopnjami: navedba, rezervacija, poravnava in uskladitev. Pred zahtevo navedite verjeten strošek. Rezervirajte dovolj proračuna za najemnika, da pokrijete dovoljeni najslabši primer. Poravnajte dejanske stroške, ko je uporaba znana. Uskladite glavno knjigo prehoda z zapisi na strani ponudnika, da ostanejo računi upravičljivi.

Ta članek opisuje to krmilno zanko za večmodelni API prehod. Uporabno je ne glede na to, ali prehod zaračunava notranjim ekipam, predplačnikom, strankam agencije ali nadaljnjim partnerjem.

Težava z zaračunavanjem: uporaba ponudnika ni račun stranke

Dejstvo: glavni ponudniki umetne inteligence ne izpostavijo enega univerzalnega števca žetonov ali ene univerzalne cene. OpenAI objavlja cene po modelu z ločenimi vhodnimi, predpomnjenimi vhodnimi in izhodnimi cenami žetonov. OpenAI prompt caching poroča o uporabi predpomnjenega žetona v polju za uporabo odziva API. Anthropic dokumentira ločene števce za običajne vhodne žetone, vhodne žetone za ustvarjanje predpomnilnika, vhodne žetone za branje predpomnilnika in izhodne žetone. Gemini cene razlikujejo vhodne, izhodne in druge kategorije žetonov, vključno z uporabo, specifično za način, kot so zvočni žetoni.

To pomeni, da prehod ne more varno zaračunavati z množenjem total_tokens z eno ceno. Potrebuje adapterje, specifične za ponudnika, za shemo zaračunavanja, nevtralno od ponudnika.

Težava postane bolj vidna v teh situacijah:

• Predplačniški krediti: prehod mora zavrniti zahteve, preden najemnik porabi pod ničlo.
• Partnerski pribitki: partner potrebuje lasten račun, namenjen stranki, ne kopije računa ponudnika.
• Pretakanje: odgovor se začne, preden je znana končna uporaba žetona.
• Sprosno predpomnjenje: predpomnjeni vnos je morda cenejši od nepredpomnjenega vnosa, vendar le, če se meri ločeno.
• Razmišljanje in uporaba orodja: nekateri modeli razkrivajo dodatne dimenzije uporabe, skrite izhodne razrede ali medijske enote.
• Spremembe cen ponudnika: račun iz prejšnjega meseca mora biti še vedno ponovljiv tudi po spremembi cenovnika.

Priporočilo: obračunavanje obravnavajte kot finančno knjigo, ki je samo dodajanje, ne kot poizvedbo na nadzorni plošči nad dnevniki zahtev.

Osnovna arhitektura

Zanesljiva arhitektura zaračunavanja ima šest komponent:

1. Račun najemnika: stranka, delovni prostor, odjemalec preprodajalec ali notranji stroškovni center.
2. Storitev cen: različice cen za ponudnika, model, obračunski razred, valuto in pravilo pribitka.
3. Ocenjevalec: izračuna ponudbo pred tiskom iz parametrov zahteve in politike modela.
4. Knjiga rezervacij: hrani proračun, preden se začne klic ponudnika.
5. Normalizator uporabe: pretvori polja uporabe, specifična za ponudnika, v notranje obračunske enote.
6. Opravila poravnave in usklajevanja: dokončajte stroške in jih primerjajte z zapisi na strani ponudnika.

Tok nadzora izgleda takole:

client request
  -> authenticate tenant and key
  -> select model and rate-card version
  -> estimate input and max output cost
  -> reserve tenant balance
  -> call provider
  -> normalize returned usage
  -> settle actual cost
  -> release unused reservation
  -> emit invoice-ready ledger event

Pomembna izbira oblikovanja je, da zahteve ne upoštevamo le. Je finančno nadzorovan pred in po izvršitvi.

1. korak: ponudba pred klicem ponudnika

Cena pred tiskom mora biti dovolj pesimistična, da uveljavi proračune, vendar dovolj razložljiva, da se pokaže strankam ali partnerjem.

Vnosi običajno vključujejo:

• ID najemnika in obračunski načrt;
• API ID ključa ali ID projekta;
• ID ponudnika in modela po uporabi pravil usmerjanja;
• ocenjeni nepredpomnjeni vhodni žetoni;
• znana primernost predpomnjenega vnosa, če je na voljo;
• max_tokens, max_output_tokens ali enakovredna izhodna omejitev;
• orodje, slika, zvok ali drugi parametri modalnosti;
• partnerski pribitek, popust ali pravilo o cenah prodajnega posrednika;
• pravilnik o valutah in zaokroževanju.

Preprosta formula citatov za ustvarjanje besedila je lahko:

estimated_cost =
  estimated_uncached_input_tokens * input_rate
+ estimated_cached_input_tokens   * cached_input_rate
+ max_output_tokens               * output_rate
+ request_fee
+ partner_markup

Priporočilo: ko končna izhodna dolžina ni znana, rezervirajte proti konfiguriranemu največjemu izhodu. Če aplikacija pusti omejitev izhoda neomejeno, mora prehod uporabiti privzeto najemnika ali model. Izvrševanje proračuna ne more biti deterministično, če ni največje odgovornosti.

To lahko zavrne nekatere zahteve, ki bi bile v praksi poceni. To je kompromis. Za predplačniške sisteme je varnejša privzeta vrednost pesimistična rezervacija z neporabljenimi sredstvi, ki se sprostijo po poravnavi. Za podjetniške stranke, ki prejemajo račune, lahko skupine dovolijo mehke presežke in ponudbo uporabijo predvsem za opozorila.

2. korak: rezervirajte proračun za najemnika

Rezervacija ščiti račun najemnika pred porabo, ki presega dovoljeno stanje. Biti mora atomičen: ali rezervacija uspe in se lahko začne klic ponudnika ali pa je zahteva zavrnjena, preden nastanejo stroški ponudnika.

Zapis o rezervaciji lahko vključuje:

{
  "reservation_id": "res_01J...",
  "tenant_id": "tenant_123",
  "api_key_id": "key_456",
  "request_id": "req_789",
  "provider": "example_provider",
  "model": "model-a",
  "rate_card_version": "2026-08-01",
  "quoted_amount": "0.032100",
  "currency": "USD",
  "status": "reserved",
  "expires_at": "2026-08-11T12:05:00Z"
}

Uporabite kratke poteke rezervacije za napake v omrežju in prekinitve povezave odjemalca. Opravilo čiščenja mora sprostiti potekle rezervacije, ki nikoli niso dosegle poravnave. Vendar ne sprostite rezervacije zgolj zato, ker je odjemalec prekinil povezavo; klic ponudnika se lahko še vedno zaključi in povzroči stroške. Ločeno navedite zahtevo ponudnika.

Priporočilo: naredite rezervacijo idempotentno z ID-jem zahteve ali ključem idempotence. Ponovni poskusi odjemalcev, prehodov ali delavcev ne smejo ustvariti več proračunskih zadržanj za isto logično zahtevo.

3. korak: normalizirajte uporabo ponudnika

Odzive ponudnika je treba pretvoriti v majhno notranjo shemo. Naj ostane stabilen tudi, ko ponudniki dodajajo nova polja uporabe.

Praktična normalizirana shema uporabe:

{
  "input_uncached_tokens": 1200,
  "input_cached_tokens": 800,
  "cache_write_tokens": 0,
  "output_tokens": 650,
  "reasoning_or_hidden_output_tokens": 0,
  "tool_or_media_units": [],
  "request_fee_units": 1,
  "provider_request_id": "prov_abc",
  "usage_source": "provider_response",
  "is_estimated": false
}

Ta shema namenoma ni enaka odgovoru katerega koli ponudnika. Zajame obračunske dimenzije, ki jih potrebujejo računi, hkrati pa ohranja zasilne lopute za enote, specifične za ponudnika.

Predpomnjeni žetoni potrebujejo svojo vrstico

Dejstvo: predpomnjenje pozivov ima lahko drugačno ceno od nepredpomnjenega vnosa. Če se predpomnjeni žetoni združijo v skupne vhodne žetone, se lahko stranki zaračuna previsoko ali pa prehod podceni stroške ponudnika. Predpomnjeni vnos mora biti prikazan kot lasten obračunski razred tako v knjigi kot na računu.

Pisanje in branje predpomnilnika nista vedno enaka

Nekateri ponudniki razlikujejo med ustvarjanjem vnosov v predpomnilniku in branjem iz predpomnilnika. Normalizator ne sme domnevati, da predpomnjeni vnos vedno pomeni eno obračunsko stopnjo. Če ima ponudnik žetone za pisanje v predpomnilnik in žetone za branje v predpomnilniku, jih preslikajte ločeno ali ohranite kot podenote, specifične za ponudnika.

Razmišljanje in skriti rezultat potrebujeta pravilnik

Nekateri modeli razkrivajo uporabo, povezano z razmišljanjem, ali skrite izhodne števce. Če ponudnik zaračuna te enote, se mora prehod odločiti, ali jih bo prikazal neposredno, uvrstil v izhodno kategorijo ali jih navedel kot ločeno vrstico računa.

Priporočilo: računi, namenjeni strankam, morajo uporabljati preprost jezik. Na primer: »reasoning output tokens« je jasnejši od neobdelanega imena polja ponudnika. Neobdelana polja naj bodo na voljo za revizijo, vendar ne silite vsake stranke, da razume notranjost ponudnika.

4. korak: poravnajte dejanske stroške

Poravnava pretvori normalizirano uporabo v končne vnose v glavno knjigo. Biti mora samo za dodajanje in se mora sklicevati na različico cenika, uporabljeno za zahtevo.

Dogovorjeni dogodek je lahko videti takole:

{
  "ledger_event_id": "led_01J...",
  "event_type": "settlement",
  "tenant_id": "tenant_123",
  "request_id": "req_789",
  "reservation_id": "res_01J...",
  "provider": "example_provider",
  "model": "model-a",
  "rate_card_version": "2026-08-01",
  "lines": [
    {
      "billing_class": "input_uncached_tokens",
      "quantity": 1200,
      "unit": "token",
      "unit_price": "0.00000250",
      "amount": "0.003000"
    },
    {
      "billing_class": "input_cached_tokens",
      "quantity": 800,
      "unit": "token",
      "unit_price": "0.00000125",
      "amount": "0.001000"
    },
    {
      "billing_class": "output_tokens",
      "quantity": 650,
      "unit": "token",
      "unit_price": "0.00001000",
      "amount": "0.006500"
    }
  ],
  "total_amount": "0.010500",
  "currency": "USD",
  "status": "settled"
}

Če je bila zahteva rezervirana za 0.032100 in poravnana na 0.010500, knjiga sprosti 0.021600 nazaj na razpoložljivo stanje.

Priporočilo: nikoli ne preračunavajte starih vrstic računa iz trenutne tabele cen. Shranite nespremenljive različice cenovnih kartic in pripnite ID različice vsaki ponudbi, rezervaciji in dogodku poravnave. V nasprotnem primeru lahko po tem, ko ponudnik posodobi cene modelov, računa ne bo več mogoče reproducirati.

Zahteve za pretakanje: najprej rezervirajte, poravnajte pozneje

Pretakanje oteži obračunavanje, ker uporabnik začne prejemati izhod, preden prehod izve končno uporabo. Odgovor je, da ne preskočite pregledov pred letom. Prehod mora rezervirati, preden odpre tok.

Uporabite ta potek dela:

1. Ocenite vhodne žetone in največje izhodne stroške.
2. Rezervirajte proračun najemnika.
3. Odpri tok ponudnika.
4. Posredovanje kosov odjemalcu.
5. Zajemi končno porabo, ko jo ponudnik pošlje ali ko je na voljo nadaljnji zapis o uporabi.
6. Poravnajte dejanske stroške in sprostite neuporabljeno rezervacijo.

Če končna uporaba ni na voljo, označite poravnavo kot ocenjeno, namesto da se pretvarjate, da je točna:

"usage_source": "gateway_estimate",
"is_estimated": true,
"reconciliation_status": "pending"

Priporočilo: dnevno usklajevanje mora dati prednost predvidenim pretočnim dogodkom, neuspelim zahtevam, časovnim omejitvam in ponovnim poskusom. To so področja, ki bodo najverjetneje povzročila razlike med zapisi prehoda in računi ponudnika.

Pravila za različico in označevanje tarife

Cenik mora biti predmet z različico in ne spremenljiva preglednica.

Najmanjše število polj:

• ponudnik;
• ID modela;
• obračunski razred;
• enota, kot je žeton, zahteva, slika, zvočna sekunda ali orodna enota;
• cena na enoto;
• valuta;
• dejanski začetni in končni časovni žig;
• politika zaokroževanja;
• najemniški načrt ali pravilo označevanja partnerja;
• referenca vira in metapodatki o odobritvi.

Pravila označevanja morajo biti izrecna. Na primer:

• Cost plus: stroški ponudnika plus 20%.
• Fiksna maloprodaja: najemnik plača fiksno ceno žetona ne glede na ceno ponudnika.
• Ravnostopenjsko: najprej 10 milijonov žetonov po eni stopnji, nato nižji.
• Vključeni krediti: uporaba porabi mesečno nadomestilo, preden se začne zaračunavanje presežka.

Kompromis: različica tarifne kartice dodaja operativno delo, vendar preprečuje, da bi spori glede računov postali arheologija. Agent za podporo strankam bi moral biti sposoben pojasniti, zakaj je bila zahteva 3. avgusta zaračunana po določeni ceni, ne da bi preveril današnje cene ponudnika.

Ločite obračunsko knjigo od analitike

Analitika in obračunavanje imata različne tolerance. Analitike je mogoče združiti, odložiti, vzorčiti ali popraviti. Obračunavanje mora biti popolno, idempotentno, revizijsko in razložljivo.

Uporabite analitiko za vprašanja, kot so:

• Katere ekipe uporabljajo največ žetonov?
• Kateri modeli rastejo najhitreje?
• Kje lahko hitro predpomnjenje zmanjša stroške?
• Kateri ključi ustvarijo neobičajno drage zahteve?

Uporabite računsko knjigo za vprašanja, kot so:

• Ali je bila ta zahteva odobrena v breme stanja najemnika?
• Katera različica cenika je povzročila to bremenitev?
• Je bila neuporabljena rezervacija sproščena?
• Ali se račun stranke ujema z poravnano uporabo?
• Ali se uporaba prehoda ujema z uporabo na strani ponudnika?

Dejstvo: Semantične konvencije OpenTelemetry GenAI vključujejo atribute uporabe žetonov, kot so vhodni in izhodni žetoni. To je uporabno za opazljivost in povezovanje sledi z dogodki stroškov. Toda atributi telemetrije niso nadomestilo za tarifne kartice, rezervacije, poravnavo, zaokroževanje in stanje računa.

Potek dela dnevnega usklajevanja

Uskladitev primerja poravnano knjigo prehoda z uporabo na strani ponudnika. Cilj ni popoln dogovor o vsakem vmesnem področju. Cilj je dovolj zgodaj zaznati materialno odstopanje, da se popravijo računi, tarife ali adapterji.

Praktično vsakodnevno delo:

1. Združi dogodke glavne knjige prehodov po ponudniku, modelu, najemniku ali API ključu, obračunskem razredu in dnevu UTC.
2. Pridobi uporabo na strani ponudnika, razvrščeno po razpoložljivih dimenzijah, kot so API ID ključa, model in dan.
3. Normalizirajte izvoze ponudnika prek iste kode adapterja, ki se uporablja za odgovore na zahteve, kjer je to mogoče.
4. Primerjajte količine in stroške glede na obračunski razred.
5. Označi odstopanje nad pragovi, kot je 0,5-odstotna količinska razlika ali kakršna koli velika absolutna razlika v stroških.
6. Razvrstite vzroke variance: ocene pretakanja, ponovni poskusi, neuspele zahteve, obračunavanje predpomnilnika, spremembe vzdevkov modela, zakasnjeni zapisi ponudnika ali manjkajoči ID-ji zahtev.
7. Ustvarite prilagoditvene dogodke namesto urejanja starih obračunskih dogodkov.

Priporočilo: uporabite ključe ponudnika API na najemnika, kjer je operativno izvedljivo, ker poenostavlja usklajevanje. Če to povzroči prevelike stroške upravljanja ključev, preslikajte notranje ID-je najemnikov v metapodatke ponudnika, kjer so podprti, in ohranite zanesljiv most ID-ja zahteve.

Stranke lahko razumejo vrstice računa

Račun, namenjen stranki, ne sme odražati ponudnika JSON. Pojasniti mora račun v stabilnih poslovnih pogojih.

Uporabni stolpci računa:

• časovno obdobje;
• najemnik, projekt ali API oznaka ključa;
• model ali profil modela;
• število zahtev;
• nepredpomnjeni vhodni žetoni;
• predpomnjeni vhodni žetoni;
• izhodni žetoni;
• medijske ali orodne enote, če je primerno;
• popusti, krediti ali pribitki;
• skupni znesek in valuta.

Za partnerje vključite veleprodajne in maloprodajne stroške samo, če to zahteva poslovni model. Številni računi preprodajalcev bi morali prikazovati samo maloprodajno porabo, medtem ko lahko partnerske nadzorne plošče prikazujejo maržo ločeno.

Kompromis: poenotena shema računov izboljša berljivost, vendar podrobnosti zaračunavanja, specifične za ponudnika, še vedno potrebujejo zaščitne lopute. Naj bodo vrstice računa privzeto enostavne in zagotovijo izvoz za napredne stranke, ki potrebujejo podrobna revizijska polja.

Kontrolni seznam za implementacijo

Pred zagonom

• Določite normalizirane obračunske razrede za vse podprte ponudnike.
• Ustvarite nespremenljive različice cenikov z datumi veljavnosti.
• Zahtevaj izhodne omejitve ali uporabi privzete nastavitve prehoda.
• Implementirajte atomske rezervacije s ključi idempotence.
• Nastavite pravila zaokroževanja za vsako valuto.
• Odločite se, kako zaračunati predpomnjene žetone, žetone za sklepanje, medijske enote in provizije.
• Ponovni preizkusi, časovne omejitve, prekinitve povezave odjemalca in napake ponudnika.
• Izdelajte mehanizem za prilagajanje dogodkov namesto urejanja poravnanih dogodkov.

Med obravnavanjem zahtev

• Preverite pristnost najemnika in ključa.
• Razreši končni model po usmeritvi in nadomestnem pravilniku.
• Izberite pravilno različico cenovnika.
• Navedite najslabši možni strošek.
• Rezervirajte stanje ali zavrnite zahtevo.
• ID zahteve ponudnika snemanja, ko je na voljo.
• Normaliziraj uporabo iz odgovora.
• Poravnava, sprostitev neuporabljene rezervacije in oddaja dogodkov pripravljenosti na račun.

Po obdelavi zahteve

• Zaženi dnevno usklajevanje glede na ponudnika, ključ, model, obračunski razred in dan.
• Preglejte ocenjene poravnave pretakanja.
• Označite uporabo modela z manjkajočimi vnosi v ceniku.
• Nadzirajte varianco, ki jo povzroča obračunavanje predpomnjenega žetona.
• Ustvarjanje predogledov računov strank pred končnim obračunom.

Napovedi za načrtovanje

Napoved: AI API obračunavanje bo postalo bolj večdimenzionalno, ne manj. Razredi žetonov, razredi predpomnilnika, medijske enote, izvajanje orodij in števci, povezani z razmišljanjem, se bodo verjetno še naprej širili, ko se bodo spreminjale zmogljivosti modela.

Predvidevanje: stranke bodo pričakovale pojasnila uporabe na ravni zahteve, ključa, projekta in računa. Mesečna vsota brez sledljivih elementov vrstic ne bo zadostovala za ekipe, ki preprodajajo API dostop ali uveljavljajo predplačniške proračune.

Predvidevanje: prehodi, ki že ločujejo ponudbo, rezervacijo, poravnavo in uskladitev, se bodo hitreje prilagodili novim cenovnim modelom, ker lahko dodajajo obračunske razrede, ne da bi prepisali celoten sistem fakturiranja.

Dejanski sklep

Če prek enega prehoda izpostavite več ponudnikov umetne inteligence, zgradite knjigo obračunavanja, preden spori glede obračunavanja povzročijo težavo. Začnite s štirimi jamstvi:

1. Vsaka plačljiva zahteva prejme ponudbo pred tiskom.
2. Vsak predplačniški ali omejeni najemnik ima rezerviran proračun, preden se začne klic ponudnika.
3. Vsak odziv ponudnika je normaliziran v stabilne obračunske razrede.
4. Vsak račun je mogoče uskladiti z uporabo na strani ponudnika in točno različico tarife, ki je bila takrat uporabljena.

Ta nadzorna zanka naredi poenoteno AI API obračunavanje razumljivo za stranke, izvršljivo za predplačniške kredite, prilagodljivo za pribitke partnerjev in revizijsko, ko se spremenijo formati cen ponudnika ali uporabe.

Sorodno branje

• združevanje sledi LLM z uporabo in zapisi o stroških
• izgradnja portalov za preprodajalce z merjenjem uporabe najemnikov
• uporaba hitrega predpomnjenja ob ohranjanju razumljivosti zaračunavanja