Skip to main content
Skip to content

Nutzungs- und Abrechnungsmetriken

In diesem Handbuch wird gezeigt, wie Tokenanzahl, Kontextfensterauslastung, KI-Kreditkosten und Kontokontingent aus einer Copilot SDK-Anwendung gelesen werden. Beispiele für TypeScript, Python, Go, .NET, Java und Rust.

Tipp

Jedes Beispiel ist über die Sprachen hinweg funktional äquivalent. Der TypeScript-Codeausschnitt ist standardmäßig erweitert. Wählen Sie Ihre Sprache aus den reduzierbaren Blöcken aus, um die gleiche Logik in diesem SDK anzuzeigen.

Überblick

Das SDK zeigt Nutzungsdaten über zwei ergänzende Mechanismen an:

  • Sitzungsereignisse: kurzlebige Ereignisse, die von der Laufzeit während der Ausführung eines Turns ausgegeben werden. Abonnieren Sie diese, um Echtzeitdaten pro API-Aufruf zu erhalten.
  • RPC-Methoden: Anforderungs-/Antwortaufrufe, die Sie bei Bedarf tätigen. Verwenden Sie diese, um eine Momentaufnahme kumulierter Gesamtwerte zu erstellen oder das Kontingent auf Kontoebene abzufragen.

Die folgende Tabelle ordnet jedes Signal der API zu, die es verfügbar macht.

SignalAPIGeltungsbereichTyp
Anzahl der Token pro Anruf
assistant.usage-EreignisSessionEvent
Auslastung des Kontextfensters
session.usage_info-EreignisSessionEvent
Aufschlüsselung des Kontextfensters (bei Bedarf)session.metadata.contextInfoSessionRPC
Kumulierte KI-Guthaben- und Token-Gesamtsummensession.usage.getMetricsSessionRPC
Preisgestaltung für KI-Credits pro Modellmodels.listServerRPC
Kontokontingent- und Premiuminteraktionenaccount.getQuotaServerRPC
Sitzungseigene Anbieterkontingentbeobachtungen
session.quota.get und session.quota.refreshSessionRPC
Updates für den Anbieter-Zulassungsstatussession.quota_observationSessionEvent

session.quota.get liest den lokalen Laufzeitstatus; session.quota.refresh aktualisiert die Anbieterkataloge und Kontingentquellen. Beide rückgaben providerQuotas, schlüsseln nach Anbieteridentität, Kontingent-ID und Beobachtungsart. Die Laufzeit hält einen Beobachtungsspeicher. Das Legacyfeld snapshots ist eine abgeleitete Kompatibilitätsansicht autoritativer Budgets, nicht eine zweite Quelle des Kontingentstatus.

Die Anbieterkardinalität ist eine ergibt sich aus der tatsächlichen Nutzung und Beobachtungen, die dem Naht zur Verfügung gestellt werden. Diese API weiß weder, noch erzwingt, wie viele Anbieter ein Benutzer verwenden kann: es zeichnet und projiziert null, ein oder viele Einträge identisch. Hersteller liefern stabile Anbieter-/kontobezogene Referenzen; Die Verwendung fügt Modellidentität hinzu, und das Kontingent fügt Kontingentidentität und Beobachtungsart hinzu. get() gibt die vollständige bekannte Auflistung zurück, sodass Aufrufer einen exakten Schlüssel, eine Teilmenge oder alle Einträge ohne anbieterspezifische Methoden auswählen können. Der Erwerb verwendet die quellen, die von der vorgelagerten Konto-/Modellschicht bereitgestellt werden; sie stellt keine Vereinigung her oder legt einen ausgewählten Anbieterfilter auf Lesevorgänge fest.

Überprüfen observationKind, quantityKindund acquisitionStatus vor dem Interpretieren eines Lesevorgangs. Ein authoritative_budget Kann Fortschritt bereitstellen und Metadaten zurücksetzen. Eine advisory_balance unabhängige signierte 64-Bit-Menge ohne vielversprechenden Prozentsatz, Rücksetzungsfenster oder Post-Call-Balance. Eine admission_state Meldeberechtigung/Kapazität auf Antrag der Zulassung und trägt keine Mengen; er ersetzt keinen Kontostand. Bewahren Sie fehlende Werte und explizite Nullen auf, anstatt sie in Null zu konvertieren. Ein fehlgeschlagener oder nicht verfügbarer Erwerb ist keine Kontingentausschöpfung.

Für Microsoft 365 Copilot sind Zugang und Kapazität Leistungsbewertungen, während Mengen beratend sind. Bei beiden Mengen bedeutet z allowed/available . B. explizit 0 / 0 AIC gemeldet, nicht 100% verbraucht oder inkonsistent. Eine fehlende Berechtigung unterscheidet sich von einer Nullberechtigung. Der -1 Berechtigungs-Sentinel bedeutet eine unbegrenzte Berechtigung, ohne den gemeldeten Kapazitätsstatus zu ändern. Rückschlüsse auf Kopfzeilen können den zwischengespeicherten Zulassungsstatus widerspiegeln; Weder diese Header noch eine Aktualisierung des On-Demand-Kontingents richten die Gebühr für den vorherigen Aufruf ein.

Die Nutzungssummen gehören zu einer Sitzung, nicht zum aktiven Konto. In der CLI erfordert der Wechsel von einer nicht leeren Microsoft 365 Copilot Sitzung das Starten einer neuen Sitzung. Die vorherige Sitzung behält ihre Nutzung und den Verlauf für den Lebenslauf bei; die neue Sitzung beginnt ihre eigenen Summen.

Hinweis

session.quota, session.usage.getMetrics, session.metadata.contextInfound session.metadata.recomputeContextTokens sind in der generierten RPC-Oberfläche experimentell gekennzeichnet. In .NET wird die experimentelle Diagnose GHCP001 ausgegeben, die Sie mit #pragma warning disable GHCP001 oder einer <NoWarn>GHCP001</NoWarn> auf Projektebene unterdrücken. Heften Sie sowohl das SDK als auch die Copilot-CLI-Laufzeitumgebung an, wenn Ihre Anwendung davon abhängt.

In den folgenden Feldtabellen sind nur die Felder aufgeführt, die in den Beispielen auf dieser Seite verwendet werden. Die vollständige, stets aktuelle Feldreferenz bilden die generierten SDK-Typen sowie Ereignisse einer Streaming-Sitzung, das bei jedem Abhängigkeitsbump aus dem CLI-Schema neu generiert wird. Betrachten Sie diese als die maßgebliche Quelle und diese Seite als einen aufgabenorientierten Leitfaden.

Anzahl der Token pro Anruf

Das assistant.usage Ereignis wird einmal für jeden Modell-API-Aufruf in einem Turn ausgegeben (einschließlich der von Unteragenten vorgenommenen Aufrufe). Es enthält die Tokenanzahl und den Abrechnungsmultiplikator für diesen einzelnen Anruf.

Im folgenden Beispiel werden diese Felder verwendet. Siehe Ereignisse einer Streaming-Sitzung für die vollständige Liste, einschließlich Feldern für Cache, Schlussfolgerung, Latenz und Nachverfolgung.

FeldTypDescription
modelstringModellkennung für diesen Aufruf
inputTokensnumberVerbrauchte Eingabetoken
outputTokensnumberErzeugte Ausgabetoken
costnumberPremium-Anforderungsmultiplikator, der auf diesen Aufruf angewendet wurde

Tipp

assistant.usage ist flüchtig, wird also live bereitgestellt, aber beim Fortsetzen einer Sitzung nicht erneut abgespielt. Um kumulierte Gesamtwerte nachträglich auszulesen, rufen Sie session.usage.getMetrics auf (siehe Kumulierte KI-Gutschriften und Token-Gesamtwerte).

Codesprachen navigation

TypeScript
session.on("assistant.usage", (event) => {
    const { model, inputTokens, outputTokens, cost } = event.data;
    console.log(
        `${model}: in=${inputTokens ?? 0} out=${outputTokens ?? 0} cost=${cost ?? 0}`,
    );
});

Auslastung des Kontextfensters

Die Anzahl der Tokens zeigt Ihnen, wie viele Tokens jeder Aufruf verbraucht hat. Die Kontextfensternutzung teilt Ihnen mit, wie voll das Eingabeaufforderungsfenster des Modells momentan ist – nützlich für die Anzeige einer Statusleiste oder Warnung des Benutzers, bevor die automatische Komprimierung gestartet wird.

Echtzeit-Updates mit session.usage_info

Die Laufzeit gibt ein session.usage_info Ereignis aus, wenn sich die Größe des Kontextfensters ändert. Das Beispiel verwendet currentTokens und tokenLimit; siehe Ereignisse einer Streaming-Sitzung für die vollständige Nutzlast.

FeldTypDescription
currentTokensnumberToken derzeit im Kontextfenster
tokenLimitnumberMaximale Token für das Kontextfenster des Modells

Codesprachen navigation

TypeScript
session.on("session.usage_info", (event) => {
    const { currentTokens, tokenLimit } = event.data;
    const pct = Math.round((currentTokens / tokenLimit) * 100);
    console.log(`Context: ${currentTokens}/${tokenLimit} (${pct}%)`);
});

On-Demand-Aufschlüsselung mit session.metadata.contextInfo

Ereignisse werden nur ausgelöst, wenn sich der Kontext ändert. Um die aktuelle Aufschlüsselung jederzeit zu lesen , z. B. direkt nach dem Fortsetzen einer Sitzung – rufen Sie session.metadata.contextInfoauf. Übergeben Sie promptTokenLimit für outputTokenLimit, um den Standardwert der Laufzeit zu verwenden; übergeben Sie 0 für 0, wenn der Wert unbekannt ist.

Das Ergebnis contextInfo ist null so lange, bis die Sitzung initialisiert wurde (die Systemaufforderung und die Toolmetadaten wurden zwischengespeichert). Es unterteilt die Gesamtsumme in systemTokens, toolDefinitionsTokens und promptTokenLimit sowie den conversationTokens.

Codesprachen navigation

TypeScript
const { contextInfo } = await session.rpc.metadata.contextInfo({
    promptTokenLimit: 0,
    outputTokenLimit: 0,
});

if (contextInfo) {
    console.log(
        `Total ${contextInfo.totalTokens}/${contextInfo.promptTokenLimit} ` +
            `(system=${contextInfo.systemTokens}, conversation=${contextInfo.conversationTokens})`,
    );
}

Kumulierte KI-Guthaben- und Token-Gesamtsummen

session.usage.getMetrics gibt die laufenden Summen für die gesamte Sitzung in einem einzelnen Aufruf zurück. Dies ist die sauberste Möglichkeit, KI-Kreditkosten zu lesen, da sie jeden API-Aufruf (Haupt-Agent und Sub-Agents) für Sie aggregiert.

Im Beispiel werden die folgenden Felder verwendet. Der generierte UsageGetMetricsResult Typ ist der vollständige Verweis.

FeldTypDescription
totalNanoAiunumberSitzungsweite KI-Kreditkosten in Nano-AI-Einheiten
totalPremiumRequestCostnumberPremium-Anforderungskosten für alle Modelle, nach Multiplikatoren
modelMetricsRecord<string, ModelMetric>Modellbasierte Aufschlüsselung; jeder Eintrag hat usage.inputTokens, usage.outputTokensund totalNanoAiu

Hinweis

Die Kosten werden in Nano-AI-Einheiten gemeldet (das Feld ist benannt totalNanoAiu). Die genaue Konvertierung in KI-Gutschriften und die genaue Bedeutung der Premium-Anforderungsabrechnung werden durch GitHub Copilot Abrechnung definiert, nicht durch das SDK– behandeln Sie GitHub Copilot Abrechnungsdokumentation als Wahrheitsquelle und überprüfen Sie vor dem Auftauchen währungsähnlicher Werte für Benutzer. Die Beispiele teilen der Einfachheit halber durch 1e9, gemäß dem SI-Präfix nano. Vergewissern Sie sich, dass dies mit der aktuellen Abrechnung übereinstimmt, bevor Sie sich darauf verlassen. Die modelMetrics- und tokenDetails-Maps verwenden Laufzeitzeichenfolgen (Modell-IDs und Namen von Tokentypen) als Schlüssel, die vom SDK-Typsystem nicht validiert werden.

Codesprachen navigation

TypeScript
const metrics = await session.rpc.usage.getMetrics();

const aiCredits = (metrics.totalNanoAiu ?? 0) / 1e9;
console.log(`AI credits used: ${aiCredits.toFixed(6)}`);
console.log(`Premium requests: ${metrics.totalPremiumRequestCost}`);

for (const [model, m] of Object.entries(metrics.modelMetrics)) {
    if (!m) continue;
    console.log(
        `${model}: in=${m.usage.inputTokens} out=${m.usage.outputTokens} ` +
            `nanoAiu=${m.totalNanoAiu ?? 0}`,
    );
}

Preisgestaltung für KI-Credits pro Modell

Um die Kosten zu schätzen, bevor Sie einen Turn ausführen, lesen Sie die Tokenpreise jedes Modells von models.list. Dies ist ein serverbezogener Aufruf auf dem Client, sodass keine Sitzung erforderlich ist. Die Preise werden in KI-Gutschriften pro Abrechnungsbatch von Token ausgedrückt. Der generierte ModelBillingTokenPrices-Typ listet jedes Feld auf, einschließlich cachePrice.

FeldTypDescription
billing.multipliernumberKostenmultiplikator für Premium-Anforderungen relativ zum Basissatz
billing.tokenPrices.inputPricenumberKI-Kreditkosten pro Batch von Eingabetoken
billing.tokenPrices.outputPricenumberKI-Kreditkosten pro Batch von Ausgabetoken
billing.tokenPrices.batchSizenumberAnzahl der Token pro Abrechnungsbatch

Hinweis

Preiswerte ändern sich, wenn Pläne und Modelle weiterentwickelt werden. Lesen Sie sie zur Laufzeit wie unten gezeigt; codieren Sie die Zahlen niemals fest in Ihre Anwendung.

Codesprachen navigation

TypeScript
const { models } = await client.rpc.models.list({});

for (const model of models) {
    const prices = model.billing?.tokenPrices;
    if (!prices) continue;
    console.log(
        `${model.id}: input=${prices.inputPrice} output=${prices.outputPrice} ` +
            `per ${prices.batchSize} tokens (x${model.billing?.multiplier ?? 1})`,
    );
}

Kontokontingent- und Premiuminteraktionen

account.getQuotameldet die verbleibende Copilot Berechtigung des authentifizierten Benutzers. Die quotaSnapshots-Zuordnung des Ergebnisses ist nach Kontingenttyp indiziert, üblicherweise premium_interactions, chat und completions. Verwenden Sie es, um Benutzern zu zeigen, wie viel von ihrem monatlichen Kontingent noch übrig ist, oder um Arbeit zu blockieren, bevor sie ein Limit erreichen.

Im Beispiel werden die folgenden Felder verwendet; Der generierte AccountQuotaSnapshot Typ ist der vollständige Verweis. Die quotaSnapshots-Schlüssel sind Zeichenfolgen zur Laufzeit, die vom SDK-Typsystem nicht überprüft werden. Sichern Sie Ihre Zugriffe daher entsprechend ab.

FeldTypDescription
entitlementRequestsnumberAnforderungen, die in der Berechtigung enthalten sind, oder -1 für unbegrenzt
usedRequestsnumberAnforderungen, die bisher in diesem Zeitraum verwendet wurden
remainingPercentagenumberProzentsatz der verbleibenden Berechtigung
resetDatestringISO 8601-Datum, an dem das Kontingent zurückgesetzt wird

Tipp

Um das Kontingent für einen bestimmten Benutzer anstelle des globalen Authentifizierungskontexts der Verbindung (z. B. in einem multimandantenbasierten Back-End) zu lesen, übergeben Sie das GitHub-Token dieses Benutzers an getQuota. Siehe Mandantenfähigkeit und Serverbereitstellungen.

Codesprachen navigation

TypeScript
const { quotaSnapshots } = await client.rpc.account.getQuota({});
const premium = quotaSnapshots["premium_interactions"];

if (premium) {
    console.log(
        `Premium interactions: ${premium.usedRequests}/${premium.entitlementRequests} ` +
            `(${premium.remainingPercentage.toFixed(1)}% left, resets ${premium.resetDate ?? "n/a"})`,
    );
}

Auswählen der richtigen API

Verwenden Sie diese Zusammenfassung, um zu entscheiden, welche API zu Ihrem Anwendungsfall passt:

  • Während der Ausführung eines Turns eine Live-Anzeige für Kosten oder Token anzeigen: Abonnieren Sie assistant.usage und session.usage_info.
  • Nach einem Turn oder einer Sitzung eine endgültige Kostenzusammenfassung anzeigen: Rufen Sie session.usage.getMetrics auf.
  • Beim Wiederaufnehmen die Nutzung des Kontextfensters anzeigen, bevor eine neuer Turn beginnt: Rufen Sie session.metadata.contextInfo auf.
  • Schätzen Sie die Kosten, bevor Sie die Aufgabe ausführen: Lesen Sie die models.list Tokenpreise.
  • Warnen Sie Benutzer, bevor sie ihren Plan erschöpfen: Anruf account.getQuota.

Weiterführende Lektüre