使用情况和计费指标

本指南演示如何从 Copilot SDK 应用程序读取令牌计数、上下文窗口利用率、AI 信用额度和帐户配额。 TypeScript、Python、Go、.NET、Java 和 Rust 都显示了示例。

在本文中

提示

每个示例在功能上等效于语言。 默认情况下，TypeScript 代码片段已展开;从可折叠块中选择语言，以查看该 SDK 中的相同逻辑。

概述

SDK 通过两种互补机制显示使用情况数据：

  • 会话事件：运行时在轮次运行时发出的临时事件。 订阅这些数据，以获取实时、按 API 调用的数据。
  • RPC 方法：按需发出的请求/响应调用。 使用它们来快照累积的总计或查找帐户级配额。

下表将每个信号映射到公开它的 API。

信号APIScope类型
按调用令牌计数
assistant.usage 事件会话事件
上下文窗口利用率
session.usage_info 事件会话事件
上下文窗口细分（按需）session.metadata.contextInfo会话RPC
累积的 AI 信用额度和令牌总计session.usage.getMetrics会话RPC
按模型 AI 信用定价models.list服务器RPC
帐户配额和高级交互account.getQuota服务器RPC

注意

session.usage.getMetrics， session.metadata.contextInfo并在 session.metadata.recomputeContextTokens 生成的 RPC 图面中标记为实验性。 在.NET，它们会引发GHCP001试验性诊断，你禁止使用#pragma warning disable GHCP001或项目级<NoWarn>GHCP001</NoWarn>进行诊断。 如果应用程序依赖于 SDK 和 Copilot CLI 运行时，则固定 SDK 和 Copilot CLI 运行时。

下面的字段表仅列出本页上示例中使用的字段。 完整的始终当前字段引用是生成的 SDK 类型以及 流式处理会话事件，每次依赖项颠簸时，都会从 CLI 架构重新生成。 将这些内容视为事实来源，此页面作为面向任务的指南。

按调用令牌计数

对于 assistant.usage 轮次的每个模型 API 调用（包括子代理发出的调用），都会发出该事件一次。 它携带该单个调用的令牌计数和计费乘数。

下面的示例使用这些字段。 有关完整列表，请参阅 流式处理会话事件 ，包括缓存、推理、延迟和跟踪字段。

领域类型Description
modelstring此调用的模型标识符
inputTokensnumber消耗的输入令牌
outputTokensnumber生成的输出令牌
costnumber应用于此调用的高级请求乘数

提示

assistant.usage 是临时的，因此在恢复会话时会实时传送，但不会重播。 若要在事实之后读取累计总计，请调用 session.usage.getMetrics （请参阅 累积的 AI 信用额度和令牌总计）。

代码语言 navigation

TypeScript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({ streaming: true });

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

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

上下文窗口利用率

令牌计数会告知每个调用使用的内容。 上下文窗口利用率会告诉你模型提示窗口现在有多完整，这对于在自动压缩开始之前显示进度栏或警告用户非常有用。

使用 <a0/a0> 实时更新

每当上下文窗口大小发生更改时，运行时都会发出事件 session.usage_info 。 该示例使用 currentTokens 并 tokenLimit;有关完整有效负载，请参阅 流式处理会话事件 。

领域类型Description
currentTokensnumber上下文窗口中当前存在的令牌
tokenLimitnumber模型上下文窗口的最大标记数

代码语言 navigation

TypeScript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({ streaming: true });

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

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

按需细分 session.metadata.contextInfo

仅当上下文更改时才会触发事件。 若要随时读取当前细目（例如，在恢复会话后）调用 session.metadata.contextInfo。 传递0以promptTokenLimit使用运行时默认值;如果outputTokenLimit值未知，则传递0。

结果是contextInfo``null在会话初始化之前（系统提示和工具元数据已缓存）。 它把总数分解成 systemTokens， conversationTokens并 toolDefinitionsTokens和 promptTokenLimit。

代码语言 navigation

TypeScript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({});

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

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

累积的 AI 信用额度和令牌总计

session.usage.getMetrics 返回单个调用中整个会话的运行总计。 这是读取 AI 信用额度成本的最干净方法，因为它会为你聚合每个 API 调用（主代理和子代理）。

该示例使用下面的字段。 生成的 UsageGetMetricsResult 类型是完整引用。

领域类型Description
totalNanoAiunumber以 nano-AI 单元为单位的全会话式 AI 信用成本
totalPremiumRequestCostnumber乘数后所有模型的高级请求成本
modelMetricsRecord<string, ModelMetric>按模型细分;每个条目都有 usage.inputTokens， usage.outputTokens和 totalNanoAiu

注意

以 nano-AI 单位（该字段命名totalNanoAiu）报告成本。 精确转换到 AI 信用额度和高级请求会计的精确含义由GitHub Copilot计费而不是 SDK 定义-将GitHub的Copilot计费文档视为事实来源，并在向用户显示类似货币的值之前进行验证。 示例除 1e9 以方便起见，遵循 SI nano 前缀;在依赖它之前，请确认这与当前计费匹配。 和modelMetrics``tokenDetails映射由 SDK 类型系统未验证的运行时字符串（模型 ID 和令牌类型名称）进行密钥处理。

代码语言 navigation

TypeScript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({});

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

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

按模型 AI 信用定价

若要在运行轮次之前估算成本，请从 models.list中读取每个模型的令牌价格。 这是客户端上的服务器范围的调用，因此不需要会话。 每个计费批次的令牌以 AI 额度表示价格。 生成的 ModelBillingTokenPrices 类型列出每个字段，包括 cachePrice。

领域类型Description
billing.multipliernumber相对于基本费率的高级请求成本乘数
billing.tokenPrices.inputPricenumber每批输入令牌的 AI 信用成本
billing.tokenPrices.outputPricenumber每批输出令牌的 AI 信用成本
billing.tokenPrices.batchSizenumber每个计费批次的令牌数

注意

随着计划和模型的发展，价格值会发生变化。 在运行时读取它们，如下所示;切勿将数字硬编码到应用程序中。

代码语言 navigation

TypeScript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();

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

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

帐户配额和高级交互

account.getQuota报告经过身份验证的用户剩余Copilot权利。 结果的 quotaSnapshots 映射按配额类型（通常 premium_interactions） chat和 completions。 使用它可向用户显示每月津贴的剩余量，或在达到限制之前限制工作。

该示例使用下面的字段;生成的 AccountQuotaSnapshot 类型是完整引用。 密钥 quotaSnapshots 是 SDK 类型系统未验证的运行时字符串，因此请保护查找。

领域类型Description
entitlementRequestsnumber权利中包含的请求或 -1 无限制的请求
usedRequestsnumber此时间段到目前为止使用的请求
remainingPercentagenumber剩余权利百分比
resetDatestring配额重置时的 ISO 8601 日期

提示

若要读取特定用户的配额，而不是连接的全局身份验证上下文（例如，在多租户后端中），请将该用户的GitHub令牌传递给getQuota。 请参阅“多租户与服务器部署”。

代码语言 navigation

TypeScript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();

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

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

选择正确的 API

使用此摘要来确定哪种 API 适合你的用例：

  • 将实时成本或令牌计量呈现为轮次运行：订阅 assistant.usage 和 session.usage_info。
  • 在轮次或会话后显示最终成本摘要：调用 session.usage.getMetrics。
  • 在恢复时显示上下文窗口使用情况，然后再显示任何新轮次：调用 session.metadata.contextInfo。
  • 在运行工作之前估算成本：读取 models.list 令牌价格。
  • 在用户耗尽计划之前警告用户：呼叫 account.getQuota。

延伸阅读