Skip to main content
Skip to content

Métriques d’utilisation et de facturation

Ce guide montre comment lire le nombre de jetons, l’utilisation de la fenêtre de contexte, le coût en crédits IA et le quota du compte dans une application utilisant SDK Copilot. Des exemples sont présentés pour TypeScript, Python, Go, .NET, Java et Rust.

Conseil

Chaque exemple est fonctionnellement équivalent entre les langages. L’extrait TypeScript est déplié par défaut : sélectionnez votre langue dans les sections repliables pour voir la même logique dans le SDK correspondant.

Vue d’ensemble

Le SDK expose les données d’utilisation par le biais de deux mécanismes complémentaires :

  • Événements de session : événements éphémères émis par l’environnement d’exécution au cours de l’exécution d’un tour. Abonnez-vous à ceux-ci pour obtenir des données en temps réel pour chaque appel d’API.
  • Méthodes RPC : appels de requête/réponse que vous effectuez à la demande. Utilisez-les pour obtenir un instantané des totaux cumulés ou consulter le quota du compte.

Le tableau ci-dessous mappe chaque signal à l’API qui l’expose.

SignalAPIScopeType
Nombre de jetons par appel
événement assistant.usageSessionÉvénement
Utilisation de la fenêtre contextuelle
événement session.usage_infoSessionÉvénement
Répartition des fenêtres contextuelles (à la demande)session.metadata.contextInfoSessionRPC
Totaux cumulés des crédits d’IA et des jetonssession.usage.getMetricsSessionRPC
Tarification des crédits IA par modèlemodels.listServeurRPC
Interactions entre le quota du compte et la version premiumaccount.getQuotaServeurRPC
Observations du quota du fournisseur propres à la session
session.quota.get et session.quota.refreshSessionRPC
Mises à jour de l’état d’admission du fournisseursession.quota_observationSessionÉvénement

session.quota.get lit l’état du runtime local ; session.quota.refresh actualise les catalogues de fournisseurs et les sources de quota. Tous deux renvoient providerQuotas, indexés par l’identité du fournisseur, l’ID de quota et le type d’observation. L’environnement d’exécution conserve un stockage des observations. Le champ hérité snapshots est une vue de compatibilité dérivée des budgets faisant autorité, et non une deuxième source d’état de quota.

La cardinalité du fournisseur est une propriété émergente de l’utilisation réelle et des observations fournies au seam. Cette API ne connaît ni n’impose le nombre de fournisseurs qu’un utilisateur peut utiliser : elle enregistre et projette zéro, une ou plusieurs entrées de manière identique. Les producteurs fournissent des références stables au niveau du fournisseur/du compte ; l’utilisation ajoute l’identité du modèle, et le quota ajoute l’identité de quota et le type d’observation. get() retourne la collection connue complète, afin que les appelants puissent sélectionner une clé exacte, un sous-ensemble ou toutes les entrées sans méthodes spécifiques au fournisseur. L’acquisition utilise les sources fournies par la couche compte/modèle en amont ; elle ne crée pas d’union et n’impose pas de filtre de fournisseur sélectionné sur les lectures.

Vérifiez observationKind, quantityKind puis acquisitionStatus avant d’interpréter une mesure. Un authoritative_budget peut fournir des métadonnées de progression et de réinitialisation. Un advisory_balance renvoie des quantités 64 bits signées indépendantes sans promettre un pourcentage, une fenêtre de réinitialisation ou un solde post-appel. Un admission_state indique l’autorisation/la capacité lors de l’admission de la demande et ne comporte aucune quantité ; il ne remplace pas un solde de compte. Conservez les valeurs manquantes et les valeurs null explicites plutôt que de les convertir en zéro. Une acquisition ayant échoué ou indisponible ne signifie pas que le quota est épuisé.

Pour Microsoft 365 Copilot, l’accès et la capacité sont des verdicts du service, tandis que les quantités sont indicatives. Par exemple, allowed/available avec les deux quantités explicitement zéro signifie 0 / 0 AIC signalé, pas 100% consommé ou état incohérent. Un droit manquant est différent d’un droit égal à zéro. La valeur sentinelle du droit d’utilisation -1 signifie un droit d’utilisation illimité sans modifier l’état de capacité signalé. Les en-têtes d’inférence peuvent refléter l’état d’admission mis en cache ; ni ces en-têtes ni une actualisation de quota à la demande ne déterminent la facturation de l’appel précédent.

Les totaux d’utilisation appartiennent à une session, et non au compte actif. Dans l’interface CLI, quitter une session Microsoft 365 Copilot non vide nécessite le démarrage d’une nouvelle session. La session précédente conserve son utilisation et son historique pour la reprise ; la nouvelle session démarre ses propres totaux.

Remarque

session.quota, session.usage.getMetrics, session.metadata.contextInfo et session.metadata.recomputeContextTokens sont marqués comme expérimentaux dans l’interface RPC générée. Dans .NET, ils émettent le diagnostic expérimental GHCP001, que vous supprimez avec #pragma warning disable GHCP001 ou avec <NoWarn>GHCP001</NoWarn> au niveau du projet. Épinglez le Kit de développement logiciel (SDK) et le runtime cli Copilot si votre application en dépend.

Les tableaux de champs ci-dessous répertorient uniquement les champs utilisés dans les exemples de cette page. La référence des champs complète et toujours à jour se compose des types du SDK générés ainsi que de Événements de session de streaming, qui est régénéré à partir du schéma CLI à chaque mise à jour des dépendances. Considérez-les comme la référence et cette page comme un guide pratique.

Nombre de jetons par appel

L’événement assistant.usage est émis une fois pour chaque appel d’API de modèle à son tour (y compris les appels effectués par les sous-agents). Il indique le nombre de tokens et le multiplicateur de facturation pour cet appel uniquement.

L’exemple ci-dessous utilise ces champs. Consultez Événements de session de streaming pour obtenir la liste complète, notamment le cache, le raisonnement, la latence et les champs de suivi.

ChampTypeDescription
modelstringIdentificateur de modèle pour cet appel
inputTokensnumberJetons d’entrée consommés
outputTokensnumberJetons de sortie produits
costnumberMultiplicateur de demande Premium appliqué à cet appel

Conseil

assistant.usage est éphémère ; il est donc diffusé en direct, mais n’est pas rejoué lorsque vous reprenez une session. Pour lire les totaux cumulés a posteriori, appelez session.usage.getMetrics (voir Crédits IA et totaux de jetons cumulés).

Langages de code 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}`,
    );
});

Utilisation de la fenêtre contextuelle

Les nombres de jetons vous indiquent ce que chaque appel a consommé. L’utilisation de la fenêtre de contexte vous indique à quel point la fenêtre de contexte du modèle est remplie actuellement, ce qui est utile pour afficher une barre de progression ou avertir l’utilisateur avant que le compactage automatique ne se déclenche.

Mises à jour en direct avec session.usage_info

Le runtime émet un session.usage_info événement chaque fois que la taille de la fenêtre de contexte change. L’exemple utilise currentTokens et tokenLimit; consultez Événements de session de streaming pour la charge utile complète.

ChampTypeDescription
currentTokensnumberTokens actuellement dans la fenêtre de contexte
tokenLimitnumberNombre maximal de jetons pour la fenêtre de contexte du modèle

Langages de code 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}%)`);
});

Décomposition à la demande avec session.metadata.contextInfo

Les événements se déclenchent uniquement lorsque le contexte change. Pour lire la répartition actuelle à tout moment, par exemple, juste après avoir repris une session, appelez session.metadata.contextInfo. Passez 0 pour promptTokenLimit afin d’utiliser la valeur par défaut de l’environnement d’exécution ; passez 0 pour outputTokenLimit si la valeur est inconnue.

Le null du résultat est contextInfo jusqu’à ce que la session ait été initialisée (l’invite système et les métadonnées de l’outil ont été mises en cache). Il décompose le total en systemTokens, conversationTokenset toolDefinitionsTokens, en même temps que le promptTokenLimit.

Langages de code 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})`,
    );
}

Totaux cumulés des crédits d’IA et des jetons

session.usage.getMetrics retourne les totaux cumulés de toute la session en un seul appel. C’est la façon la plus claire de consulter le coût en crédits IA, car elle agrège tous les appels à l’API (agent principal et sous-agents) pour vous.

L’exemple utilise les champs ci-dessous. Le type généré UsageGetMetricsResult est la référence complète.

ChampTypeDescription
totalNanoAiunumberCoût en crédits IA sur l’ensemble de la session, en nano-unités d’IA
totalPremiumRequestCostnumberCoût de la demande Premium sur tous les modèles, après les multiplicateurs
modelMetricsRecord<string, ModelMetric>Répartition par modèle ; chaque entrée a usage.inputTokens, usage.outputTokenset totalNanoAiu

Remarque

Le coût est signalé dans les unités nano-IA (le champ est nommé totalNanoAiu). La conversion exacte en crédits d’IA et la signification exacte du décompte des requêtes premium sont définies par la facturation de GitHub Copilot, et non par le SDK ; considérez la documentation de facturation de GitHub Copilot comme la référence faisant foi et vérifiez-la avant d’afficher aux utilisateurs des valeurs assimilables à des montants. Les exemples divisent les valeurs par 1e9 par souci de simplicité, conformément au préfixe SI nano ; vérifiez que cela correspond à la facturation actuelle avant de vous y fier. Les mappages modelMetrics et tokenDetails ont pour clés des chaînes définies à l’exécution (identifiants de modèle et noms de types de jeton) que le système de types SDK ne valide pas.

Langages de code 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}`,
    );
}

Tarification des crédits IA par modèle

Pour estimer le coût avant d’effectuer un tour, consultez le prix des jetons de chaque modèle dans models.list. Il s’agit d’un appel de portée serveur côté client, il ne nécessite donc pas de session. Les prix sont exprimés en crédits IA par lot de jetons facturé. Le type généré ModelBillingTokenPrices répertorie chaque champ, y compris cachePrice.

ChampTypeDescription
billing.multipliernumberMultiplicateur de coût de la demande Premium par rapport au taux de base
billing.tokenPrices.inputPricenumberCoût de crédit IA par lot de jetons d’entrée
billing.tokenPrices.outputPricenumberCoût en crédits d’IA par lot de jetons de sortie
billing.tokenPrices.batchSizenumberNombre de jetons par lot de facturation

Remarque

Les valeurs de prix changent à mesure que les plans et les modèles évoluent. Lisez-les au moment de l’exécution, comme indiqué ci-dessous ; ne codez jamais en dur les nombres dans votre application.

Langages de code 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})`,
    );
}

Interactions entre le quota du compte et la version premium

account.getQuota indique le quota Copilot restant de l’utilisateur authentifié. La table quotaSnapshots du résultat est indexée par type de quota, généralement premium_interactions, chat et completions. Utilisez-le pour montrer aux utilisateurs la quantité de leur allocation mensuelle restante ou pour effectuer un travail avant d’atteindre une limite.

L’exemple utilise les champs ci-dessous ; le type généré AccountQuotaSnapshot est la référence complète. Les quotaSnapshots clés sont des chaînes d’exécution que le système de type du Kit de développement logiciel (SDK) ne valide pas. Par conséquent, protégez vos recherches.

ChampTypeDescription
entitlementRequestsnumberDemandes incluses dans le forfait, ou -1 pour un nombre illimité
usedRequestsnumberRequêtes utilisées jusqu’à présent pendant cette période
remainingPercentagenumberPourcentage du droit restant
resetDatestringDate de réinitialisation du quota ISO 8601

Conseil

Pour lire le quota pour un utilisateur spécifique plutôt que le contexte d'authentification global de la connexion (par exemple, dans un serveur principal multilocataire), transmettez le jeton GitHub de cet utilisateur à getQuota. Consultez « Multilocataire et déploiements de serveurs ».

Langages de code 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"})`,
    );
}

Choix de l’API appropriée

Utilisez ce résumé pour déterminer l’API qui correspond à votre cas d’usage :

  • Afficher un coût en temps réel ou un compteur de jetons pendant l’exécution d’un tour : abonnez-vous à assistant.usage et session.usage_info.
  • Afficher un résumé des coûts finals après un tour ou une session : appel session.usage.getMetrics.
  • Afficher l’utilisation de la fenêtre contextuelle lors de la reprise, avant tout nouveau tour : appel session.metadata.contextInfo.
  • Estimer le coût avant l’exécution du travail : lire models.list les prix des jetons.
  • Avertir les utilisateurs avant qu’ils n’épuisent leur plan : appel account.getQuota.

Lectures complémentaires