Zbuduj księgę rozliczeniową interfejsu API AI: wyceń, zarezerwuj, rozlicz i uzgodnij każdą rozmowę modelową

Skierowana do klienta AI API rozliczenia nie mogą stanowić miesięcznego eksportu pierwotnego wykorzystania dostawcy. Jeśli brama udostępnia wiele modeli najemcom, zespołom lub partnerom, zanim faktura powstanie, rozliczenia muszą odpowiedzieć na trudniejsze pytanie: czy należy teraz zezwolić na tę prośbę i jak później wyjaśni się jej koszt?

Praktyczny wzór to księga rozliczeniowa składająca się z czterech etapów: wycena, rezerwacja, rozliczenie i uzgodnienie. Przed złożeniem wniosku podaj prawdopodobny koszt. Zarezerwuj wystarczającą ilość budżetu najemcy, aby pokryć dozwolony najgorszy przypadek. Rozlicz rzeczywisty koszt po poznaniu zużycia. Uzgodnij księgę bramy z zapisami po stronie dostawcy, aby faktury pozostały możliwe do obrony.

W tym artykule opisano pętlę sterowania dla bramy obsługującej wiele modeli API. Jest to przydatne, jeśli bramka wystawia rachunki wewnętrznym zespołom, klientom przedpłaconym, klientom agencji czy partnerom na niższym szczeblu łańcucha dostaw.

Problem z rozliczeniami: korzystanie z usług dostawcy nie jest fakturą dla klienta

Fakt: główni dostawcy sztucznej inteligencji nie udostępniają jednego uniwersalnego licznika tokenów ani jednej uniwersalnej ceny. OpenAI publikuje ceny poszczególnych modeli z oddzielnymi stawkami wejściowymi, danymi wejściowymi w pamięci podręcznej i stawkami tokenów wyjściowych. OpenAI raporty dotyczące buforowania monitu buforują użycie tokenu w polu użycia odpowiedzi API. Anthropic dokumentuje oddzielne liczniki dla normalnych tokenów wejściowych, tokenów wejściowych tworzenia pamięci podręcznej, tokenów wejściowych odczytu pamięci podręcznej i tokenów wyjściowych. Gemini ceny rozróżniają dane wejściowe, wyjściowe i inne kategorie tokenów, w tym wykorzystanie specyficzne dla danej modalności, takie jak tokeny audio.

Oznacza to, że bramka nie może bezpiecznie rozliczać się poprzez pomnożenie total_tokens przez jedną cenę. Potrzebuje adapterów specyficznych dla dostawcy w ramach schematu rozliczeń neutralnego dla dostawcy.

Problem staje się bardziej widoczny w następujących sytuacjach:

• Środki przedpłacone: brama musi odrzucać żądania, zanim najemca wyda mniej niż zero.
• Narzuty partnera: partner potrzebuje własnej faktury dla klienta, a nie kopii rachunku dostawcy.
• Przesyłanie strumieniowe: odpowiedź rozpoczyna się, zanim znane jest ostateczne wykorzystanie tokena.
• Szybkie buforowanie: dane wejściowe zapisane w pamięci podręcznej mogą być tańsze niż dane wejściowe niezapisane w pamięci podręcznej, ale tylko wtedy, gdy są mierzone osobno.
• Rozumowanie i użycie narzędzi: niektóre modele ujawniają dodatkowe wymiary użycia, ukryte klasy wyników lub jednostki multimedialne.
• Zmiany cen dostawcy: faktura z ostatniego miesiąca musi być nadal odtwarzalna po zmianie arkusza stawek.

Zalecenie: traktuj rozliczenia jak księgę finansową z możliwością dołączenia, a nie jak zapytanie do panelu kontrolnego dotyczące dzienników żądań.

Podstawowa architektura

Niezawodna architektura rozliczeniowa składa się z sześciu elementów:

1. Konto najemcy: klient, obszar roboczy, klient-sprzedawca lub wewnętrzne centrum kosztów.
2. Usługa arkusza stawek: wersjonowane ceny dla dostawcy, modelu, klasy rozliczeniowej, waluty i reguły marży.
3. Estymator: oblicza wycenę przed inspekcją na podstawie parametrów żądania i zasad modelu.
4. Księga rezerwacji: przechowuje budżet przed rozpoczęciem połączenia z dostawcą.
5. Normalizator użytkowania: konwertuje pola użytkowania specyficzne dla dostawcy na wewnętrzne jednostki rozliczeniowe.
6. Zadania rozliczeniowe i uzgadniające: sfinalizuj opłaty i porównaj je z dokumentacją po stronie dostawcy.

Przebieg kontroli wygląda następująco:

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

Ważny wybór projektu polega na tym, że żądanie nie jest jedynie przestrzegane. Jest kontrolowany finansowo przed i po wykonaniu.

Krok 1: wycena przed telefonem od dostawcy

Wycena przed inspekcją powinna być na tyle pesymistyczna, aby wyegzekwować budżety, ale jednocześnie na tyle łatwa do wyjaśnienia, aby można ją było pokazać klientom lub partnerom.

Wejście zwykle obejmuje:

• identyfikator najemcy i plan rozliczeniowy;
• API identyfikator klucza lub identyfikator projektu;
• identyfikator dostawcy i modelu po zastosowaniu reguł routingu;
• szacowane tokeny wejściowe w pamięci podręcznej;
• znane uprawnienia do wprowadzania danych z pamięci podręcznej, jeśli są dostępne;
• max_tokens, max_output_tokens lub równoważny limit wyjściowy;
• narzędzie, obraz, dźwięk lub inne parametry modalności;
• reguła dotycząca narzutów, rabatów lub cen dla sprzedawców;
• Zasady dotyczące walut i zaokrągleń.

Prosty wzór wyceny do generowania tekstu mógłby wyglądać następująco:

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

Zalecenie: gdy ostateczna długość wyjściowa nie jest znana, zarezerwuj w stosunku do skonfigurowanej maksymalnej mocy wyjściowej. Jeśli aplikacja pozostawia nieograniczony limit wyjściowy, brama powinna zastosować domyślną dzierżawę lub model. Egzekwowanie budżetu nie może mieć charakteru deterministycznego, jeśli nie ma maksymalnej odpowiedzialności.

Może to spowodować odrzucenie niektórych żądań, które w praktyce byłyby tanie. Na tym polega kompromis. W przypadku systemów przedpłaconych bezpieczniejszą opcją jest rezerwacja pesymistyczna z niewykorzystanymi środkami uwalnianymi po rozliczeniu. W przypadku fakturowanych klientów korporacyjnych zespoły mogą zezwolić na niewielkie nadwyżki i wykorzystywać wycenę głównie do alertów.

Krok 2: zarezerwuj budżet najemcy

Rezerwacja chroni konto najemcy przed wydatkami przekraczającymi dozwolone saldo. Powinno to mieć charakter niepodzielny: albo rezerwacja się powiedzie i może rozpocząć się połączenie z dostawcą, albo żądanie zostanie odrzucone, zanim poniesione zostaną jakiekolwiek koszty dostawcy.

Rekord rezerwacji może zawierać:

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

Używaj krótkich terminów ważności rezerwacji w przypadku awarii sieci i rozłączeń klientów. Zadanie czyszczenia powinno zwolnić wygasłe rezerwacje, które nigdy nie osiągnęły rozliczenia. Nie zwalniaj jednak rezerwacji tylko dlatego, że klient się rozłączył; połączenie z dostawcą może nadal zostać zakończone i wiązać się z kosztami. Śledź osobno stan żądania dostawcy.

Zalecenie: ustaw rezerwację jako idempotentną na podstawie identyfikatora żądania lub klucza idempotencji. Ponowne próby od klientów, bram lub procesów roboczych nie powinny powodować wielokrotnych wstrzymań budżetu dla tego samego żądania logicznego.

Krok 3: normalizacja użycia dostawcy

Odpowiedzi dostawcy należy przekształcić w mały schemat wewnętrzny. Zachowaj stabilność, nawet jeśli dostawcy będą dodawać nowe pola użytkowania.

Praktyczny znormalizowany schemat użycia:

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

Ten schemat celowo nie jest identyczny z odpowiedzią żadnego dostawcy. Przechwytuje wymiary rozliczeniowe potrzebne na fakturach, zachowując jednocześnie luki ratunkowe dla jednostek specyficznych dla dostawcy.

Tokeny zapisane w pamięci podręcznej wymagają własnej linii

Fakt: buforowanie podpowiedzi może mieć inną cenę niż dane wejściowe niezapisane w pamięci podręcznej. Jeśli tokeny w pamięci podręcznej zostaną połączone w całkowitą liczbę tokenów wejściowych, klient może zostać obciążony zbyt dużą opłatą lub brama może zaniżyć koszt dostawcy. Dane wejściowe zapisane w pamięci podręcznej powinny pojawiać się jako osobna klasa rozliczeniowa zarówno w księdze, jak i na fakturze.

Zapisy i odczyty w pamięci podręcznej nie zawsze są takie same

Niektórzy dostawcy rozróżniają tworzenie wpisów w pamięci podręcznej i odczytywanie z pamięci podręcznej. Normalizator nie powinien zakładać, że dane wejściowe buforowane zawsze oznaczają jedną stawkę rozliczeniową. Jeśli dostawca ma tokeny zapisu w pamięci podręcznej i tokeny odczytu pamięci podręcznej, zmapuj je oddzielnie lub zachowaj jako podjednostki specyficzne dla dostawcy.

Rozumowanie i ukryte wyniki wymagają polityki

Niektóre modele ujawniają użycie związane z rozumowaniem lub ukryte liczniki wyników. Jeśli dostawca wystawia rachunki za te jednostki, brama musi zdecydować, czy wyświetlić je bezpośrednio, przypisać do kategorii wyjściowej, czy też wyszczególnić jako osobną linię faktury.

Zalecenie: faktury wystawiane klientom powinny być pisane prostym językiem. Na przykład: „rozumowanie tokenów wyjściowych” jest wyraźniejsze niż surowa nazwa pola dostawcy. Udostępniaj surowe pola do kontroli, ale nie zmuszaj każdego klienta do zrozumienia wewnętrznych informacji dostawcy.

Krok 4: rozlicz rzeczywisty koszt

Rozliczenie przekształca znormalizowane wykorzystanie w ostateczne zapisy w księdze. Powinien być przeznaczony tylko do dołączenia i odnosić się do wersji arkusza stawek użytej w żądaniu.

Rozstrzygnięte wydarzenie może wyglądać tak:

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

Jeśli żądanie zostało zarezerwowane dla 0.032100 i rozliczone w 0.010500, księga zwalnia 0.021600 z powrotem do dostępnego salda.

Zalecenie: nigdy nie przeliczaj starych wierszy faktury na podstawie aktualnej tabeli cen. Przechowuj niezmienne wersje arkuszy stawek i dołączaj identyfikator wersji do każdej wyceny, rezerwacji i zdarzenia rozliczeniowego. W przeciwnym razie odtworzenie faktury może okazać się niemożliwe po aktualizacji przez dostawcę cen modeli.

Prośby o transmisję strumieniową: najpierw zarezerwuj, rozlicz się później

Streaming komplikuje rozliczenia, ponieważ użytkownik zaczyna odbierać dane wyjściowe, zanim brama dowie się o ostatecznym wykorzystaniu. Odpowiedzią nie jest pominięcie kontroli przed lotem. Brama powinna zarezerwować miejsce przed otwarciem strumienia.

Użyj tego schematu działania:

1. Oszacuj tokeny wejściowe i maksymalny koszt wyjściowy.
2. Zarezerwuj budżet najemcy.
3. Otwórz strumień dostawcy.
4. Prześlij fragmenty do klienta.
5. Przechwytuj końcowe wykorzystanie, gdy dostawca je wyśle lub gdy dostępny będzie kolejny zapis użycia.
6. Ureguluj rzeczywisty koszt i zwolnij niewykorzystaną rezerwację.

Jeśli ostateczne wykorzystanie jest niedostępne, oznacz rozliczenie jako szacunkowe, zamiast udawać, że jest dokładne:

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

Zalecenie: codzienne uzgadnianie powinno priorytetowo traktować szacunkowe zdarzenia przesyłania strumieniowego, nieudane żądania, przekroczenia limitu czasu i ponowne próby. Są to obszary, które najprawdopodobniej powodują rozbieżności między zapisami bramki a fakturami dostawcy.

Zasady dotyczące wersji arkusza stawek i znaczników

Arkusz stawek powinien być obiektem wersjonowanym, a nie modyfikowalnym arkuszem kalkulacyjnym.

Minimalna liczba pól:

• dostawca;
• identyfikator modelu;
• klasa rozliczeń;
• jednostka, taka jak token, żądanie, obraz, sekunda audio lub jednostka narzędziowa;
• cena jednostkowa;
• waluta;
• efektywne znaczniki czasu rozpoczęcia i zakończenia;
• zasada zaokrąglania;
• plan najemcy lub reguła dotycząca znaczników partnera;
• odniesienie do źródła i metadane zatwierdzenia.

Reguły znaczników powinny być jasne. Na przykład:

• Koszt plus: koszt dostawcy plus 20%.
• Stała sprzedaż detaliczna: najemca płaci stałą cenę symboliczną niezależnie od ceny dostawcy.
• Warstwowe: pierwsze 10 milionów tokenów przy jednej stawce, potem niższej.
• Środki uwzględnione w cenie: użycie powoduje zużycie miesięcznego limitu przed rozpoczęciem naliczania opłat za nadwyżki.

Kompromis: zmiana wersji arkusza stawek zwiększa pracę operacyjną, ale zapobiega przekształceniu sporów dotyczących faktur w archeologię. Pracownik obsługi klienta powinien być w stanie wyjaśnić, dlaczego żądanie z 3 sierpnia zostało obciążone określoną stawką, bez sprawdzania dzisiejszych cen dostawcy.

Oddziel księgę rozliczeniową od analityki

Analiza i rozliczenia mają różne tolerancje. Analitykę można agregować, opóźniać, pobierać próbki lub korygować. Rozliczenia muszą być kompletne, idempotentne, możliwe do kontrolowania i wyjaśnialne.

Korzystaj z analiz w przypadku pytań takich jak:

• Które zespoły wykorzystują najwięcej tokenów?
• Które modele rosną najszybciej?
• Gdzie buforowanie podpowiedzi może obniżyć koszty?
• Które klucze generują niezwykle drogie żądania?

Użyj księgi rozliczeniowej, aby odpowiedzieć na pytania takie jak:

• Czy to żądanie zostało autoryzowane w ramach salda najemcy?
• Która wersja arkusza stawek spowodowała tę opłatę?
• Czy niewykorzystana rezerwacja została zwolniona?
• Czy faktura klienta odpowiada rozliczonemu zużyciu?
• Czy użycie bramy odpowiada użyciu po stronie dostawcy?

Fakt: Konwencje semantyczne OpenTelemetry GenAI obejmują atrybuty użycia tokenów, takie jak tokeny wejściowe i wyjściowe. Jest to przydatne ze względu na obserwowalność i łączenie śladów ze zdarzeniami kosztowymi. Jednak atrybuty telemetryczne nie zastępują arkuszy stawek, rezerwacji, rozliczeń, zaokrągleń ani stanu faktury.

Codzienny proces uzgadniania

Uzgadnianie porównuje rozliczoną księgę bramy z wykorzystaniem po stronie dostawcy. Celem nie jest idealne porozumienie na każdym polu pośrednim. Celem jest wykrycie istotnych odchyleń na tyle wcześnie, aby można było skorygować faktury, arkusze stawek lub adaptery.

Praktyczna codzienna praca:

1. Grupuj zdarzenia księgi bramy według dostawcy, modelu, dzierżawcy lub klucza API, klasy rozliczeniowej i dnia UTC.
2. Pobierz użycie po stronie dostawcy pogrupowane według dostępnych wymiarów, takich jak API identyfikator klucza, model i dzień.
3. Jeśli to możliwe, normalizuj eksport dostawcy za pomocą tego samego kodu adaptera, który jest używany do odpowiedzi na żądania.
4. Porównaj ilości i koszty według klasy rozliczeniowej.
5. Oznacz odchylenie powyżej progów, np. 0,5% różnicy w ilości lub dowolną dużą różnicę w kosztach bezwzględnych.
6. Klasyfikuj przyczyny rozbieżności: szacunki przesyłania strumieniowego, ponowne próby, nieudane żądania, księgowanie w pamięci podręcznej, zmiany aliasów modeli, opóźnione rekordy dostawców lub brakujące identyfikatory żądań.
7. Twórz zdarzenia korygujące zamiast edytować stare zdarzenia rozliczeniowe.

Zalecenie: użyj kluczy API dostawcy na każdego dzierżawcę, jeśli jest to wykonalne operacyjnie, ponieważ upraszcza to uzgadnianie. Jeśli powoduje to zbyt duże obciążenie związane z zarządzaniem kluczami, zamapuj wewnętrzne identyfikatory dzierżawy na metadane dostawcy, jeśli jest to obsługiwane, i utrzymuj niezawodny mostek identyfikatora żądań.

Linie faktury zrozumiałe dla klientów

Faktura skierowana do klienta nie powinna odzwierciedlać dostawcy JSON. Powinno wyjaśnić rachunek w stabilnych kategoriach biznesowych.

Przydatne kolumny faktury:

• zakres dat;
• najemca, projekt lub API etykieta klucza;
• modelka lub profil modelki;
• liczba żądań;
• niebuforowane tokeny wejściowe;
• buforowane tokeny wejściowe;
• tokeny wyjściowe;
• jednostki multimedialne lub narzędzia, jeśli mają zastosowanie;
• rabaty, kredyty lub narzuty;
• całkowita kwota i waluta.

W przypadku partnerów uwzględnij zarówno koszt hurtowy, jak i detaliczny, tylko jeśli wymaga tego model biznesowy. Wiele faktur od sprzedawców powinno wykazywać wyłącznie wykorzystanie detaliczne, podczas gdy panele partnerów mogą wykazywać marżę osobno.

Kompromis: ujednolicony schemat faktury poprawia czytelność, ale szczegółowe informacje rozliczeniowe specyficzne dla dostawcy nadal wymagają luk awaryjnych. Domyślnie zachowaj proste wiersze faktury i zapewnij eksport dla zaawansowanych klientów, którzy potrzebują szczegółowych pól audytu.

Lista kontrolna wdrożenia

Przed uruchomieniem

• Zdefiniuj znormalizowane klasy rozliczeniowe dla wszystkich obsługiwanych dostawców.
• Utwórz niezmienne wersje arkuszy stawek z datami obowiązywania.
• Wymagaj ograniczeń wyjściowych lub zastosuj ustawienia domyślne bramy.
• Zaimplementuj rezerwacje atomowe za pomocą kluczy idempotencji.
• Ustaw reguły zaokrąglania dla każdej waluty.
• Zdecyduj, jak fakturować tokeny przechowywane w pamięci podręcznej, tokeny wnioskowania, jednostki multimedialne i opłaty za żądania.
• Ponowne próby testowania, przekroczenia limitu czasu, rozłączenia klientów i błędy dostawcy.
• Zbuduj mechanizm zdarzeń dostosowawczych zamiast edytować rozliczone zdarzenia.

Podczas obsługi żądania

• Uwierzytelnij najemcę i klucz.
• Rozwiąż ostateczny model po routingu i zasadach awaryjnych.
• Wybierz poprawną wersję arkusza stawek.
• Podać koszt w najgorszym przypadku.
• Zarezerwuj saldo lub odrzuć prośbę.
• Zapisz identyfikator żądania dostawcy nagrań, jeśli jest dostępny.
• Normalizuj wykorzystanie odpowiedzi.
• Rozlicz, zwolnij niewykorzystaną rezerwację i wyemituj zdarzenia gotowe do wystawienia faktury.

Po rozpatrzeniu żądania

• Przeprowadzaj codzienne uzgadnianie według dostawcy, klucza, modelu, klasy rozliczeniowej i dnia.
• Przejrzyj szacunkowe rozliczenia dotyczące transmisji strumieniowej.
• Oznacz użycie modelu brakującymi wpisami w arkuszu stawek.
• Monitoruj rozbieżności spowodowane rozliczaniem tokenów w pamięci podręcznej.
• Generuj podglądy faktur klientów przed ostatecznym rozliczeniem.

Prognozy do zaplanowania

Przewidywanie: AI API rozliczenia staną się bardziej wielowymiarowe, a nie mniej. Klasy tokenów, klasy pamięci podręcznej, jednostki multimedialne, wykonywanie narzędzi i liczniki związane z rozumowaniem będą prawdopodobnie nadal się rozwijać wraz ze zmianą możliwości modelu.

Przewidywanie: klienci będą oczekiwać wyjaśnień dotyczących użytkowania na poziomie żądania, klucza, projektu i faktury. Miesięczna suma bez możliwych do prześledzenia elementów zamówienia będzie niewystarczająca dla zespołów API odsprzedających dostęp lub egzekwujących przedpłacone budżety.

Przewidywanie: bramy, które już oddzielają wycenę, rezerwację, rozliczenie i uzgadnianie, szybciej dostosują się do nowych modeli cenowych, ponieważ mogą dodawać klasy rozliczeniowe bez przepisywania całego systemu faktur.

Wniosek, który można zastosować

Jeśli udostępniasz wielu dostawców sztucznej inteligencji za pośrednictwem jednej bramy, utwórz księgę rozliczeniową, zanim spory dotyczące rozliczeń wymuszą problem. Zacznij od czterech gwarancji:

1. Każde płatne żądanie otrzymuje wycenę przed inspekcją.
2. Każdy najemca opłacany z góry lub z limitem ma zarezerwowany budżet przed rozpoczęciem połączenia z dostawcą.
3. Odpowiedź każdego dostawcy jest normalizowana w postaci stabilnych klas rozliczeniowych.
4. Każdą fakturę można rozliczyć w oparciu o wykorzystanie po stronie dostawcy i dokładną wersję arkusza stawek używaną w danym momencie.

Ta pętla kontroli sprawia, że ujednolicona sztuczna inteligencja API rozliczenia są zrozumiałe dla klientów, możliwe do wyegzekwowania w przypadku środków przedpłaconych, elastyczne w przypadku znaczników partnerów i możliwe do kontrolowania w przypadku zmiany cen dostawcy lub formatów użytkowania.

Powiązane lektury

• łączenie śladów LLM z wykorzystaniem i kosztami rekordy
• tworzenie portali sprzedawców z pomiarami wykorzystania najemców
• korzystanie z buforowania podpowiedzi przy jednoczesnym zachowaniu zrozumiałości rozliczeń