{"meta":{"title":"跨仪表板、API 和报表协调 Copilot 使用情况指标","intro":"Copilot 使用情况指标派生自相同的基础遥测，但在仪表板、API 和导出的报表之间聚合和呈现方式不同。","product":"GitHub Copilot","breadcrumbs":[{"href":"/zh/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/zh/enterprise-cloud@latest/copilot/reference","title":"参考资料"},{"href":"/zh/enterprise-cloud@latest/copilot/reference/copilot-usage-metrics","title":"Copilot 使用情况指标"},{"href":"/zh/enterprise-cloud@latest/copilot/reference/copilot-usage-metrics/reconciling-usage-metrics","title":"协调 Copilot 使用情况指标"}],"documentType":"article"},"body":"# 跨仪表板、API 和报表协调 Copilot 使用情况指标\n\nCopilot 使用情况指标派生自相同的基础遥测，但在仪表板、API 和导出的报表之间聚合和呈现方式不同。\n\nCopilot使用情况指标仪表板、API 和导出文件都使用相同的基础遥测数据，但它们聚合并呈现方式不同。 了解这些差异有助于协调各个源的数字，并在准备内部报表时信任分析。\n\n* Copilot使用情况指标仪表板在**企业**和**组织级别**提供。\n* Copilot使用情况指标 API 支持**企业、组织、存储库和用户级**记录。\n* 团队级总计未预先汇总。 它们是通过将用户-团队报表与按用户划分的使用情况指标报表联接而成的。 请参阅“[团队级Copilot使用情况指标](/zh/enterprise-cloud@latest/copilot/reference/copilot-usage-metrics/team-level-metrics)”。\n* 存储库级别报告为在所请求日期有活动的存储库提供每日的拉取请求活动情况。 请参阅“[Copilot使用情况指标中提供的数据](/zh/enterprise-cloud@latest/copilot/reference/copilot-usage-metrics/copilot-usage-metrics#repository-level-fields-api-only)”。\n\n## 先决条件\n\n基于 IDE 的 Copilot 使用指标依赖于 **来自用户 IDE 的遥测数据**。 如果开发人员在其 IDE 中禁用了遥测数据，则Copilot、API 报表或导出的数据中显示基于 \\*\\*\\*\\* IDE 的详细活动，例如按 IDE、按功能和代码行细分。 但是，即使客户端遥测不可用，服务器端遥测仍可能会在活动用户计数中显示这些用户。\n\n如果你注意到缺少用户或意外的采用率较低，请先验证 IDE 遥测设置，然后再排查其他原因。\n\nCopilot CLI 指标（`daily_active_cli_users` 和 `totals_by_cli`）从 IDE 遥测中单独收集和报告。 CLI 使用情况 **不** 会导致基于 IDE 的活动用户计数或其他 IDE 指标。\n\n不要将用于统计用户发起的 agent app 作业的 `totals_by_3rd_party_agent[].user_initiated_interaction_count` 与顶层 `user_initiated_interaction_count` 对应起来，后者用于统计来自其他受支持遥测的显式提示。\n\n## 指标对齐\n\n仪表板和 API 对关键指标使用共享定义：\n\n| 概念                                                                  | 仪表盘指标                                                                                                                                                              | API 或导出字段 | 注释 |\n| :------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------- | :- |\n| 活动用户                                                                | 每日/每周/活动用户总数                                                                                                                                                       |           |    |\n| `user_initiated_interaction_count` > 0                              | 如果用户当天在 IDE 中与 Copilot 用户交互，则被视为处于活动状态。                                                                                                                            |           |    |\n| 接受率                                                                 | 代码完成验收率                                                                                                                                                            |           |    |\n| `code_acceptance_activity_count` ÷ `code_generation_activity_count` | 两个源都以相同的方式计算接受率，尽管舍入可能有所不同。                                                                                                                                        |           |    |\n| 代理采用                                                                | 代理使用情况图表                                                                                                                                                           |           |    |\n| `totals_by_feature` 当特性 = \"代理\" 时                                    | 表示与 Copilot agent 互动的用户。                                                                                                                                           |           |    |\n| 语言的使用                                                               | 语言使用情况图表                                                                                                                                                           |           |    |\n| `totals_by_language_feature` 或 `totals_by_language_model`           | 仪表板可视化这些聚合字段。                                                                                                                                                      |           |    |\n| 采用群组/阶段                                                             | 采用队列分发（影响仪表板）                                                                                                                                                      |           |    |\n| `ai_adoption_phase`、`totals_by_ai_adoption_phase`                   | 阶段定义是共用的，但群体不同。 仪表板包含过去 28 天时间窗口内的所有活跃用户，而聚合 `totals_by_ai_adoption_phase` 字段统计的是在该记录对应的特定日期活跃的用户。 因此，仪表板和 API 队列计数和百分比不匹配。 仪表板中显示为“被动用户”的用户对应于 `No Cohort` API 值。 |           |    |\n\n有关完整的字段说明，请参阅 [GitHub Copilot 使用情况指标](/zh/enterprise-cloud@latest/copilot/reference/copilot-usage-metrics)。\n\n## 报表之间的差异\n\n表板数据、API 报告和导出文件之间存在小幅差异是正常的。 这些变化通常是由时间窗口、范围或数据新鲜度的差异引起的。\n\n### 时间范围\n\n每个数据源以不同的方式聚合数据。\n\n| 来源        | 时间窗口     | 聚合方法                        |\n| :-------- | :------- | :-------------------------- |\n| Dashboard | 28 天滚动窗口 | 在过去的28天里，指标被持续聚合，以便平滑波动。    |\n| 应用程序接口    | Daily    | 每条记录代表每个用户的单日数据，以便进行每日趋势分析。 |\n| NDJSON 导出 | Daily    | 为 BI 工具和长期报告提供 API 输出镜像。    |\n\n使报表周期与仪表板的 28 天窗口保持一致，使大多数比较更加一致。 但是，它不会使采用队列计数匹配，因为仪表板对窗口的不同用户进行计数，并且聚合的 API 字段包含每日计数。\n\n### 延迟遥测\n\n由于 IDE 遥测以异步方式处理，因此最近几天的数据可能不完整或缺失。 数据通常在 3 个完整的 UTC 天内完成。 最近每日指标看似明显下降的问题通常在遥测数据完全处理后会得到解决。\n\n### 导出时序\n\nNDJSON 文件反映导出时可用的数据。 如果在处理新遥测数据之前下载了文件，则数据可能会滞后于仪表板或 API。 在三天窗口后重新导出文件可提供最准确的视图。\n\n## `Unknown` 值\n\n`Unknown`当来自 IDE 客户端的遥测数据缺少足够的详细信息来对活动进行分类时，该值将显示在某些 API 或导出细分中。 这是预期行为，并不指示缺少数据。\n\n| 明细      | Explanation                                                                             |\n| :------ | :-------------------------------------------------------------------------------------- |\n| 语言      | 当 IDE 无法识别活动文件的编程语言时，显示为 `Unknown`。                                                     |\n| 功能 / 特点 | 在较旧的客户端发送泛型事件而不指定聊天模式（例如， `chat_panel_unknown_mode`）时显示。                                |\n| 型号      | 当事件缺少标识所使用的模型的信息时出现。 某些内部模型（例如，`gpt-4o-mini`）在用于非面向用户的操作（例如摘要或意图检测）时，可能会与`Unknown`同时出现。 |\n\n`Unknown` 值会从仪表板的可视化中排除，但会显示在 API 和 NDJSON 数据中，以确保数据完整。 随着用户升级到发送更丰富的遥测数据的较新的 IDE 和扩展版本，数据量 `Unknown` 会减少。\n\n## 通过服务器端遥测数据识别出的用户\n\nCopilot 使用情况指标结合了客户端和服务器端遥测来识别活动用户。 通过服务器端遥测确认为活动用户，但未收到任何客户端遥测的用户包含在活动用户总数中（例如 `daily_active_users`）。 在可用的情况下，这些用户也可能出现在 `totals_by_ide` 中（在按用户划分的报告中，这还包括最近检测到的 IDE 版本和 Copilot 扩展版本）。 但是，其他维度的细分项（`totals_by_feature`, `totals_by_language_feature`, `totals_by_language_model`, `totals_by_model_feature`）和代码行数指标仍将为空。\n\n这意味着顶级活动用户计数可能高于细分数组中反映的用户总数。 这是预期行为，并不指示数据错误。"}