Google Home Vitals（云端）

这套信息中心和提醒可帮助您主动维护与 Google Home 生态系统的高质量集成。Google 致力于支持合作伙伴为所有客户打造优质生态系统。

该信息中心包含三个部分，每个部分都涵盖了影响整体集成质量的关键部分。

1. Google 到合作伙伴指标 - 衡量从 Google 到云后端的调用的健康状况。

2. 系统运行状况 - 合作伙伴到 Google 的指标 - 衡量从您的系统到 Google 的调用的运行状况。

3. 设备健康状况 - 状态准确性 - 衡量 Google 系统中存储的状态的准确性，这些状态用于响应用户查询。

如果指标未达到目标值，则会以红色突出显示，表示存在可能影响用户体验的问题。以下信息详细介绍了每个目标以及这些目标对用户的重要性。

如果以下按钮未直接将您带到信息中心，您可以选择概览页面，选择信息中心，然后从我的信息中心列表中选择 Google Home Vitals 信息中心（云端），以查看您的信息中心。

转到信息中心

Google 到合作伙伴指标

查询/执行成功率 >= 99.5% 指标用于衡量用户命令正确执行的频率，这有助于避免 Google 助理做出“我无法连接到设备”之类的回答，或错误地确认尚未执行的命令。

同步成功率 >= 99.5% 指标用于衡量同步请求正确执行的频率，这可确保 Google Home 中显示的设备与连接到云基础设施的设备保持同步。

如何定义“成功”？

如果 Google Home 平台收到有效响应，表明预期操作已完成或请求的状态已检索，则事务会被标记为成功。

包含非阻塞异常（例如，SUCCESS 状态伴随 lowBattery 异常）的响应会被计为成功交易。命令已到达设备，并且尽管有警告，但意图已得到满足。

如何定义“失败”？

在计算 QUERY、EXECUTE 和 SYNC 成功率时，常见平台错误代码中标记为合作伙伴可采取措施的错误会被视为“失败”。此外，在错误和异常中发现的错误也是“失败”，但以下情况除外：

执行响应状态一致性

在 EXECUTE 响应中返回 SUCCESS 状态时，响应载荷的 states 对象必须包含您正在执行的特征所定义的所有有效和更新后的状态字段。如果省略必需的状态字段，或针对复杂特征返回空的 states 对象，会导致 Google Home 平台无法解析执行结果，并将其注册为 AGENT_ISSUE 或 INVALID_RESPONSE 失败，从而降低查询和执行成功率。

查询/执行延迟时间 (p90) <= 1000 毫秒指标用于衡量请求的操作等待时间，有助于确保用户无需等待太长时间，例如，等待几秒钟后灯才会熄灭。

延迟时间指标

延迟时间是衡量集成对最终用户的响应速度的关键指标。该信息中心会跟踪第 90 百分位 (P90) 延迟时间，该延迟时间代表“最慢”用户的体验（例如，P90 为 800 毫秒意味着 90% 的请求在 800 毫秒或更短时间内得到确认）。

Google 针对状态检查和设备命令采用不同的延迟时间衡量方式，以确保技术准确性。

1. 查询延迟时间（疑问句）

这会测量 Google 请求设备当前状态时的 Cloud-to-cloud 往返时间。

• 开始：Google 向您的执行方式网址发送 action.devices.QUERY 请求。
• 测量窗口：云端接收、处理和传输完整 HTTP 响应并将其返回给 Google 所需的时间。
• 结束：Google 收到并确认来自您服务的最终响应载荷。

2. EXECUTE 延迟时间（操作）

此指标用于衡量 Google 向设备发送控制请求时的命令确认时间。

• 开始：Google 向您的执行方式网址发送 action.devices.EXECUTE 请求。
• 测量窗口：云端接收命令并返回确认响应所需的时间。
• 结束：Google 收到 SUCCESS、PENDING 或 OFFLINE 状态响应。
• 技术范围：此指标衡量 Google 云端与您的云端之间的“响应确认”时间。它不衡量物理硬件（例如灯泡）完成物理状态更改所需的时间，因为这通常涉及云到云路径之外的本地网状网络延迟。

EXECUTE/QUERY 延迟时间细分

在分析 EXECUTE 或 QUERY 延迟时间的时间戳时，总往返时间可以细分为以下顺序流：

由于此细分会比较 Google 端和合作伙伴端的时间戳，因此合作伙伴服务器必须与 NTP（网络时间协议）同步。即使是轻微的时钟漂移（50-100 毫秒），也会使计算出的运送时间（t2 - t1 和 t4 - t3）失真，从而可能导致逻辑上不可能的指标，例如负传输延迟。

[t1] 请求已发送（Google 出站）：Google 发起 intent 请求。由于 t1 未直接公开，因此通过从最终入站时间戳中减去总延迟时间来近似计算。

网络传输（t1 到 t2）：到达履单端点之前的预计网络传输和队列时间。

[t2] 收到请求（合作伙伴 Ingress）：请求到达您环境的 API Gateway 或 Ingress 服务器的确切时间戳。

合作伙伴处理（t2 到 t3）：完全在您的云环境中发生的内部执行、路由和设备处理延迟时间。

[t3] 响应已发送（合作伙伴出站流量）：您的服务将履单响应发送回 Google 的时间戳。

返回传输（t3 到 t4）：返回 Google 的返回网络路由和连接完成时间。

[t4] 请求完成（Google 入站）：Google 接收并处理最终响应。此时间戳会明确记录在 Google Cloud 日志中，显示为 receiveTimestamp。

为了说明这些指标如何关联，我们来看一个示例 EXECUTE 请求，其总记录延迟时间 (latencyMsec) 为 1700 毫秒，Google Cloud receiveTimestamp (t4) 为 2026-05-25T15:25:00.550Z。

延迟时间缩短选项

地理位置路由的架构建议

如果无法实现任播 IP，我们建议您采用以下经济实惠的替代方案，以确保用户由最近的区域数据中心提供服务。

1. 全球负载均衡 (GLB)

   请使用全球应用负载均衡器（大多数主要云服务提供商都提供），而不是静态路由。

   • 运作方式：您配置一个位于网络边缘的全球入口点（网址）。负载均衡器会自动检测来自 Google 履单集群的请求的地理来源，并将流量路由到最近的区域性健康后端。

   • 优势：这可提供任播的性能，同时显著降低配置复杂性和费用。

2. 地理位置感知 DNS (GeoDNS)

   • 运作方式：配置 DNS 提供商，使其根据 DNS 查询的地理位置将执行方式网址解析为不同的 IP 地址。

   • 实现：确保您的 DNS 提供商针对 Google 的出站流量点进行了优化。当 Google 的区域执行服务（例如，在美国、欧盟或亚洲）解析您的网域时，它们将收到该特定区域中数据中心的 IP 地址。

应用层的优化策略

除了基础架构级路由之外，您还可以在应用层实现以下策略，以减少请求处理中的延迟时间。

1. “Trampoline”代理方法

   如果您必须维护主数据中心，请使用区域级轻量级代理服务器（Trampoline）来处理初始握手。

   1. Google 访问您的全局网址。

   2. 区域代理（例如轻量级 Nginx 或 Lambda 函数）接收请求。

   3. 代理通过内部高速主干网将载荷转发到主数据库。

   优势：这可以减少“TCP 握手”时间，而这通常是长距离请求延迟的最大原因。

2. 访问令牌区域提示

   在账号关联 (OAuth) 过程中，您的系统可以识别用户的居住地所在区域。

   实现：将区域标识符编码到发给 Google 的 access_token 中。当 Google 发送履单请求时，您的网关可以立即检查令牌，并将请求路由到正确的区域集群，而无需进行数据库查找。

系统运行状况 - 合作伙伴到 Google 的指标

保持成功率 >= 99.5% 有助于确保 Google Home 中的设备状态正确、设备添加和移除、自动化操作触发以及历史事件显示在 Google Home app (GHA) 的“活动记录”标签页中。

成功率是根据您的云推送状态更新时 Google 返回的 HTTP 响应代码计算得出的。为确保合作伙伴不会因 Google 端基础设施问题而受到处罚，该指标会从失败计数中排除 Google 内部错误。计算中包含的 API 调用可在 HomeGraph API 参考文档中找到。

如何定义“成功”？

2xx（成功）：Home Graph 已成功接收并处理状态更新。

如何定义“失败”？

4xx（合作伙伴错误）表示失败，并指出从您的云发送的请求存在问题。常见代码包括：

400 无效请求

原因：由于语法无效，服务器无法处理请求。 常见原因包括 JSON 格式错误，或针对字符串值使用 null 而非 ""。

解决方案：确保请求正文是有效的 JSON（字符串字段没有格式错误的结构或 null 值），并验证 agentUserId 是否与 SYNC 响应中的值一致。

404 未找到

原因：在 HomeGraph 中找不到 deviceId 或 agentUserId（尚未同步、已解除关联或 ID 不匹配）。

解决方案：

1. 请确保 agentUserId 与 SYNC 响应中提供的值一致。
2. 使用 Home Graph SYNC API 确定 404 Not Found 错误是否由 HomeGraph 中缺少设备或用户引起。
3. 请务必在添加、移除、重命名或更新设备或账号后触发 requestSync，以确保状态保持最新。
4. 正确处理 DISCONNECT intent，以停止报告过时设备。收到 DISCONNECT intent 后，您的云服务应停止使用 Request Sync 和 Report State 向 Google 发布更改。

429 资源已用尽

原因：您的集成已超出其分配的配额。

解决方案：请参阅配额管理信息中心内“第 2a 步：调试配额问题”部分中的说明。您还可以参阅智能家居配额和限制，了解更多信息。

设备健康状况 - 状态准确性

达到或超过状态准确率 >= 99.5% 有助于确保用户在查看设备状态或使用“智能管家”等 AI 功能时看到正确的结果。如果状态准确率较低，自动化操作可能不会触发，并且历史记录条目可能不会在适当的时间显示在 GHA 的“活动”标签页中。如需了解详情，请参阅报告状态。请注意：所有受支持的特征都必须达到状态准确率目标。

1. 准确率组件

该指标源自“样本”，Google 可以根据已知的意向结果验证报告的状态。为了确保技术精确度，我们会通过两个不同的途径来评估准确性：

• 基于 QUERY 的准确性：在用户或系统主动查询设备的当前状态时进行验证。
• 基于 EXECUTE 的准确率：通过评估控制请求后报告的设备状态进行验证。

2. 信息中心指标（每小时计算）

该信息中心会根据 1 小时间隔计算准确率。为确保统计置信度并避免因低信号噪声而对集成进行惩罚，Google 强制执行最低流量阈值。如果特定特征和设备组合在 5 天的滚动时间范围内累计的样本总数少于 100 个，则其准确率在统计上被视为不显著，并设置为 不适用。

如果某个小时内两种途径都有足够的样本量，则特定状态的基准每小时准确率计算为两个独立百分比的平均值：

每小时状态准确率 =（查询准确率 % + 执行准确率 %）/ 2

其中，每个途径的定义如下：

• 查询准确率 % =（每小时查询准确样本数）/（每小时查询总样本数）
• 执行准确率 % =（每小时执行准确样本数）/（每小时执行总样本数）

特征准确率得分（按特征计算） = SUM（查询准确样本数 + 执行准确样本数）/ SUM（查询总样本数 + 执行总样本数）

由于质量得分评估的是整个生态系统中的最低性能，因此每个受支持且符合条件的特性都必须单独达到 >= 99.5% 的状态准确率目标（这不是特性的平均值）。

此视图可防止销量高、准确率高的设备掩盖销量较低的设备的准确率问题。如果合作伙伴担心未充分利用的特征会降低其得分，可以放心，很少使用的特征会自动受到最低流量检查的保护，除非达到所需的样本阈值，否则不会计入“最低类型和特征”得分。

3. 提高设备健康状况和状态准确性

当 Home Graph 中存储的状态与实时 QUERY 的结果不一致时，就会出现差异。

“缺少字段”错误

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD"
    deviceId: "curtain"
    deviceType: "action.devices.types.CURTAIN"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-13T12:20:26Z"
    queryReportStateDifferences: {
      queryState: "open_close    {
        open_percent: 0.0
        missing open_direction
      }"
      reportState: "open_close   {
        open_state {
          open_percent: 100.0
          open_direction: "LEFT"
        }
      }"
    }
    reportedTime: "2022-05-13T07:14:35Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T12:20:26Z"
    stateName: "open_state"
    traitName: "TRAIT_OPEN_CLOSE"
  }
  

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD"
    deviceId: "sensor"
    deviceType: "action.devices.types.SENSOR"
    isMissingField: true
    isOffline: false
    queriedTime: "2026-04-28T10:40:33Z"
    queryReportStateDifferences: {
      queryState: "temperature_setting {
         thermostat_mode: "off"
         thermostat_temperature_ambient: 20.0
         active_thermostat_mode: "none"
      }"
      reportState: "temperature_setting {
         thermostat_mode: "off"
         active_thermostat_mode: "none"
      }"
    }
    reportedTime: "2024-09-20T15:00:00Z"
    requestId: "123"
    result: "INACCURATE"
    snapshotTime: "2026-04-28T10:40:33Z"
    stateName: "thermostat_temperature_ambient"
    traitName: "TRAIT_TEMPERATURE_SETTING"
  }
  

原因：如果出现 DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD 或 DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD 错误，则表示针对同一设备，QUERY 响应和报告状态请求中的载荷字段集不同。

解决方案：确保两种途径中的数据结构完全相同。如果 SYNC 中包含某个特征，则其对应字段必须存在，并且在主动报告和被动查询中保持一致。

“不准确”错误

reportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_INACCURATE"
    deviceId: "outlet"
    deviceType: "action.devices.types.OUTLET"
    isMissingField: false
    isOffline: false
    queriedTime: "2026-04-12T16:02:58Z"
    queryReportStateDifferences: {
      queryState: "on_off    {
        on: false
      }"
      reportState: "on_off   {
        on: true
      }"
    }
    reportedTime: "2025-03-10T01:56:44Z"
    requestId: "abc"
    result: "INACCURATE"
    snapshotTime: "2026-04-12T16:02:58Z"
    stateName: "on"
    traitName: "TRAIT_ON_OFF"
  }
  

原因：对于 DETAILED_ACCURACY_RESULT_INACCURATE 错误，QUERY 响应中返回的值与最后一个报告状态值之间存在差异。

解决方案：确保每当设备状态发生变化时都会触发 Report State，并且 Report State 和 QUERY 始终提供完全相同的最新值和所有必填字段，以保持数据一致性。

"reportStateLog": {
   "isMissingField": false,
   "snapshotTime": "2026-04-13T07:56:21Z",
   "traitName": "TRAIT_ON_OFF",
   "detailedAccuracyResult": "DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE",
   "executionReportStateDifferences": {
      "expectedPostExecutionDeviceState": {
         "onOff": {
         "on": false
         }
      },
      "preExecutionDeviceState": {
         "onOff": {
         "on": true
         }
      },
      "executionCommand": {
         "requestId": "test001",
         "beginTimestamp": "2026-04-13T07:56:20Z",
         "action": {
         "trait": "TRAIT_ON_OFF",
         "actionType": "ONOFF_OFF"
         },
         "status": {
         "statusType": "SUCCESS_STATUS"
         },
         "endTimestamp": "2026-04-13T07:56:21Z",
         "executionType": "PARTNER_CLOUD"
      },
      "reportState": {}
   },
   "accuracy": "MISSING_REPORT_STATE",
   "deviceType": "action.devices.types.LIGHT",
   "agentId": "abc",
   "stateName": "on",
   "result": "MISSING_REPORT_STATE"
   }
  

原因：出现 DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE 错误时，合作伙伴已成功执行命令，但未向 Google 报告更新后的设备状态。

解决方案：始终在命令执行后发送报告状态更新，以便 Home Graph 接收新的设备状态。

eportStateLog: {
    accuracy: "INACCURATE"
    agentId: "abc"
    detailedAccuracyResult: "DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED"
    deviceId: "switch"
    deviceType: "action.devices.types.SWITCH"
    isMissingField: false
    isOffline: true
    queriedTime: "2026-04-13T13:53:26Z"
    queryReportStateDifferences: {
      queryState: "online    {
        online: false
      }
      "
      reportState: ""
    }
    reportedTime: "1970-01-01T00:00:00Z"
    requestId: "test001"
    result: "INACCURATE"
    snapshotTime: "2026-04-13T13:53:26Z"
    stateName: "online"
    traitName: "TRAIT_ONLINE"
   }
  

原因：对于 DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED 错误，尽管 QUERY 结果提供了当前状态，但未收到此设备的报告状态（状态为空，且报告的时间戳为纪元时间）。这表明状态更新未触发、未能到达 HomeGraph，或者设备未能成功报告其连接或运行状态的转换。

解决方案：确保针对所有状态更改触发并成功发送 Report State。验证后端逻辑是否正确处理状态更新，确认是否成功向 Google HomeGraph 传送，并确保设备持续同步其状态，以保持界面和自动化引擎的准确性。