Google Home Vitals (Đám mây)

Bộ trang tổng quan và cảnh báo này giúp bạn chủ động duy trì khả năng tích hợp chất lượng cao với hệ sinh thái Google Home. Google cam kết hỗ trợ các đối tác phát triển một hệ sinh thái chất lượng cao cho tất cả khách hàng.

Trang tổng quan có 3 phần, mỗi phần đề cập đến một phần quan trọng góp phần vào chất lượng của quá trình tích hợp tổng thể.

1. Chỉ số từ Google đến Đối tác – Đo lường tình trạng của các lệnh gọi từ Google đến phần phụ trợ trên đám mây của bạn.

2. Tình trạng hệ thống – Chỉ số từ Đối tác đến Google – Đo lường tình trạng của các lệnh gọi từ hệ thống của bạn đến Google.

3. Tình trạng thiết bị – Độ chính xác của trạng thái – Đo lường độ chính xác của các trạng thái được lưu trữ trong hệ thống của Google, được dùng để phân phát các truy vấn của người dùng.

Khi các chỉ số không đáp ứng giá trị mục tiêu, chúng sẽ được đánh dấu màu đỏ để cho biết một vấn đề có thể ảnh hưởng đến trải nghiệm người dùng. Thông tin sau đây cung cấp thông tin chi tiết về từng mục tiêu và lý do mục tiêu đó quan trọng đối với người dùng.

Nếu nút sau đây không đưa bạn trực tiếp đến trang tổng quan, bạn có thể truy cập trang tổng quan bằng cách chọn trang Tổng quan, chọn Trang tổng quan rồi chọn Bảng tổng quan Google Home Vitals (Đám mây) trong danh sách Trang tổng quan của tôi để xem trang tổng quan.

Chuyển đến trang tổng quan

Chỉ số từ Google đến Đối tác

Chỉ số Tỷ lệ thành công của truy vấn/thực thi >= 99,5% đo lường tần suất các lệnh của người dùng được thực hiện chính xác, giúp tránh các câu trả lời của Trợ lý như "Tôi không thể truy cập thiết bị" hoặc xác nhận không chính xác một lệnh chưa được thực hiện.

Điều gì xác định một "Thành công"?

Một giao dịch được đánh dấu là thành công nếu nền tảng Google Home nhận được một phản hồi hợp lệ cho biết hành động dự định đã được thực hiện hoặc trạng thái được yêu cầu đã được truy xuất.

Các phản hồi bao gồm các trường hợp ngoại lệ không chặn (ví dụ: trạng thái SUCCESS kèm theo trường hợp ngoại lệ lowBattery) được tính là giao dịch thành công. Lệnh đã đến thiết bị và ý định đã được đáp ứng bất chấp cảnh báo.

Điều gì xác định một "Không thành công"?

Các lỗi được tìm thấy trên Mã lỗi nền tảng chung được đánh dấu là Đối tác có thể hành động được coi là "Không thành công" khi tính toán Tỷ lệ thành công của truy vấn và thực thi. Ngoài ra, các lỗi được tìm thấy trên Lỗi và trường hợp ngoại lệ cũng là "Không thành công", ngoại trừ những trường hợp sau:

Chỉ số Độ trễ của truy vấn/thực thi (p90) <= 1000 mili giây đo lường thời gian chờ hành động được yêu cầu và giúp đảm bảo người dùng không phải chờ quá lâu, ví dụ: chờ vài giây để đèn tắt.

Chỉ số độ trễ

Độ trễ là một chỉ báo quan trọng về mức độ phản hồi của quá trình tích hợp đối với người dùng cuối. Trang tổng quan theo dõi Độ trễ ở phân vị thứ 90 (P90), thể hiện trải nghiệm của những người dùng "chậm nhất" (ví dụ: P90 là 800 mili giây có nghĩa là 90% yêu cầu được xác nhận trong 800 mili giây trở xuống).

Google đo lường độ trễ theo cách khác nhau đối với các lệnh kiểm tra trạng thái so với các lệnh thiết bị để đảm bảo độ chính xác về mặt kỹ thuật.

1. Độ trễ của truy vấn (Hỏi)

Chỉ số này đo lường thời gian khứ hồi Cloud-to-cloud khi Google yêu cầu trạng thái hiện tại của một thiết bị.

• Bắt đầu: Google gửi yêu cầu action.devices.QUERY đến URL thực hiện của bạn.
• Cửa sổ đo lường: Thời gian để đám mây của bạn nhận, xử lý và truyền toàn bộ phản hồi HTTP trở lại Google.
• Kết thúc: Google nhận và xác nhận tải trọng phản hồi cuối cùng từ dịch vụ của bạn.

2. Độ trễ của thực thi (Hành động)

Chỉ số này đo lường thời gian xác nhận lệnh khi Google gửi yêu cầu kiểm soát đến một thiết bị.

• Bắt đầu: Google gửi yêu cầu action.devices.EXECUTE đến URL thực hiện của bạn.
• Cửa sổ đo lường: Thời gian để đám mây của bạn nhận lệnh và trả về phản hồi xác nhận.
• Kết thúc: Google nhận được phản hồi trạng thái SUCCESS, PENDING hoặc OFFLINE.
• Phạm vi kỹ thuật: Chỉ số này đo lường thời gian "Xác nhận phản hồi" giữa đám mây của Google và đám mây của bạn. Chỉ số này không đo lường thời gian để phần cứng thực (ví dụ: bóng đèn) hoàn tất việc thay đổi trạng thái thực, vì việc này thường liên quan đến độ trễ của mạng lưới cục bộ bên ngoài đường dẫn từ đám mây đến đám mây.

Các lựa chọn giảm độ trễ

Đề xuất về cấu trúc cho việc định tuyến theo vị trí địa lý

Nếu không thể triển khai IP Anycast, bạn nên dùng các giải pháp thay thế tiết kiệm chi phí sau đây để đảm bảo người dùng được trung tâm dữ liệu khu vực gần nhất phục vụ.

1. Cân bằng tải toàn cầu (GLB)

   Thay vì định tuyến tĩnh, hãy sử dụng Trình cân bằng tải ứng dụng toàn cầu (có sẵn từ hầu hết các nhà cung cấp dịch vụ đám mây lớn).

   • Cách hoạt động: Bạn định cấu hình một điểm truy cập toàn cầu (URL) duy nhất nằm ở rìa mạng. Trình cân bằng tải sẽ tự động phát hiện nguồn gốc địa lý của yêu cầu từ các cụm thực hiện của Google và định tuyến lưu lượng truy cập đến phần phụ trợ hoạt động gần nhất trong khu vực của bạn.

   • Lợi ích: Điều này mang lại hiệu suất của Anycast với độ phức tạp và chi phí cấu hình thấp hơn đáng kể.

2. DNS nhận biết vị trí địa lý (GeoDNS)

   • Cách hoạt động: Định cấu hình nhà cung cấp DNS để phân giải URL thực hiện của bạn thành các địa chỉ IP khác nhau dựa trên vị trí địa lý của truy vấn DNS.

   • Triển khai: Đảm bảo nhà cung cấp DNS của bạn được tối ưu hoá cho các điểm thoát của Google. Khi các dịch vụ thực hiện theo khu vực của Google (ví dụ: ở Hoa Kỳ, Liên minh Châu Âu hoặc Châu Á) phân giải miền của bạn, các dịch vụ này sẽ nhận được địa chỉ IP cho trung tâm dữ liệu ở khu vực cụ thể đó.

Chiến lược tối ưu hoá ở lớp ứng dụng

Ngoài việc định tuyến ở cấp cơ sở hạ tầng, bạn có thể triển khai các chiến lược sau đây ở lớp ứng dụng để giảm độ trễ trong quá trình xử lý yêu cầu.

1. Phương thức proxy "Trampoline"

   Nếu bạn phải duy trì một trung tâm dữ liệu chính, hãy sử dụng các máy chủ proxy nhẹ theo khu vực (Trampoline) để xử lý quá trình bắt tay ban đầu.

   1. Google truy cập URL toàn cầu của bạn.

   2. Một proxy theo khu vực (ví dụ: hàm Nginx hoặc Lambda nhẹ) nhận được yêu cầu.

   3. Proxy chuyển tiếp tải trọng qua đường trục nội bộ tốc độ cao đến cơ sở dữ liệu chính.

   Lợi ích: Điều này giúp giảm thời gian "Bắt tay TCP", thường là yếu tố đóng góp lớn nhất vào độ trễ cho các yêu cầu đường dài.

2. Gợi ý về khu vực cho mã truy cập

   Trong quá trình Liên kết tài khoản (OAuth), hệ thống của bạn có thể xác định khu vực nhà của người dùng.

   Triển khai: Mã hoá giá trị nhận dạng khu vực vào access_token được cấp cho Google. Khi Google gửi yêu cầu thực hiện, cổng của bạn có thể kiểm tra mã thông báo ngay lập tức và định tuyến yêu cầu đến cụm khu vực chính xác mà không cần tra cứu cơ sở dữ liệu.

Tình trạng hệ thống – Chỉ số từ Đối tác đến Google

Việc duy trì Tỷ lệ thành công >= 99,5% giúp đảm bảo rằng trạng thái thiết bị chính xác trong Google Home, thiết bị được thêm và xoá, quá trình tự động hoá kích hoạt, và các sự kiện trong nhật ký xuất hiện trong thẻ Hoạt động của Google Home app (GHA).

Tỷ lệ thành công được tính dựa trên mã phản hồi HTTP do Google trả về khi đám mây của bạn đẩy các bản cập nhật trạng thái. Để đảm bảo các đối tác không bị phạt vì các vấn đề về cơ sở hạ tầng ở phía Google, chỉ số này sẽ loại trừ các lỗi nội bộ của Google khỏi số lượng lỗi. Các lệnh gọi API có trong tính toán được tìm thấy trong tài liệu tham khảo HomeGraph API.

Điều gì xác định một "Thành công"?

2xx (Thành công): Home Graph đã nhận và xử lý thành công bản cập nhật trạng thái.

Điều gì xác định một "Không thành công"?

4xx (Lỗi của đối tác) thể hiện các lỗi và cho biết vấn đề với yêu cầu được gửi từ đám mây của bạn. Các mã phổ biến bao gồm:

400 Yêu cầu không hợp lệ

Nguyên nhân: Máy chủ không thể xử lý yêu cầu do cú pháp không hợp lệ. Các nguyên nhân phổ biến bao gồm JSON không hợp lệ hoặc sử dụng giá trị rỗng thay vì "" cho giá trị chuỗi.

Giải pháp: Đảm bảo nội dung yêu cầu là JSON hợp lệ (không có cấu trúc không hợp lệ hoặc giá trị rỗng cho các trường chuỗi) và xác minh rằng agentUserId khớp với giá trị từ phản hồi SYNC.

404 Không tìm thấy

Nguyên nhân: Không tìm thấy deviceId hoặc agentUserId trong HomeGraph (chưa được đồng bộ hoá, đã huỷ liên kết hoặc không khớp mã nhận dạng).

Giải pháp:

1. Đảm bảo rằng agentUserId khớp với giá trị được cung cấp trong phản hồi SYNC của bạn.
2. Sử dụng Home Graph SYNC API để xác định xem lỗi 404 Không tìm thấy là do thiếu thiết bị hay người dùng trong HomeGraph.
3. Đảm bảo kích hoạt requestSync sau khi thêm, xoá, đổi tên hoặc cập nhật thiết bị hoặc tài khoản để đảm bảo trạng thái luôn được cập nhật.
4. Xử lý đúng cách các ý định DISCONNECT để ngừng báo cáo các thiết bị lỗi thời. Sau khi nhận được ý định DISCONNECT, dịch vụ đám mây của bạn sẽ ngừng xuất bản các thay đổi lên Google bằng cách sử dụng Yêu cầu đồng bộ hoá và Báo cáo trạng thái.

429 Đã hết tài nguyên

Nguyên nhân: Quá trình tích hợp của bạn đã vượt quá hạn mức được phân bổ.

Giải pháp: Xem hướng dẫn trong phần "Bước 2a: Gỡ lỗi các vấn đề về hạn mức" trong trang tổng quan để quản lý hạn mức. Bạn cũng có thể tham khảo Hạn mức và giới hạn của Nhà thông minh để biết thêm thông tin.

Tình trạng thiết bị – Độ chính xác của trạng thái

Việc đáp ứng hoặc vượt quá Độ chính xác của trạng thái >= 99,5% giúp đảm bảo người dùng thấy kết quả chính xác khi xem trạng thái thiết bị hoặc sử dụng các tính năng AI như Hỏi Home. Nếu độ chính xác của trạng thái thấp, quá trình tự động hoá có thể không kích hoạt và các mục trong nhật ký có thể không xuất hiện trong thẻ Hoạt động của GHA vào đúng thời điểm. Để biết thêm thông tin, hãy xem bài viết Báo cáo trạng thái. Xin lưu ý: Bạn phải đáp ứng mục tiêu Độ chính xác của trạng thái trên TẤT CẢ các đặc điểm được hỗ trợ.

1. Thành phần độ chính xác

Chỉ số này được lấy từ "mẫu" mà Google có thể xác minh trạng thái được báo cáo dựa trên kết quả ý định đã biết. Để đảm bảo độ chính xác về mặt kỹ thuật, độ chính xác được đánh giá trên 2 đường dẫn riêng biệt:

• Độ chính xác dựa trên truy vấn: Được xác minh khi người dùng hoặc hệ thống chủ động truy vấn trạng thái hiện tại của một thiết bị.
• Độ chính xác dựa trên thực thi: Được xác minh bằng cách đánh giá trạng thái thiết bị sau lệnh được báo cáo lại sau yêu cầu kiểm soát.

2. Chỉ số trang tổng quan (Tính toán theo giờ)

Trang tổng quan tính toán độ chính xác dựa trên khoảng thời gian 1 giờ. Để đảm bảo độ tin cậy về mặt thống kê và tránh phạt các quá trình tích hợp có nhiễu tín hiệu thấp, Google thực thi ngưỡng khối lượng truy cập tối thiểu. Nếu một đặc điểm và tổ hợp thiết bị cụ thể tích luỹ được ít hơn 100 mẫu tổng cộng trong cửa sổ 5 ngày liên tục, thì độ chính xác của đặc điểm và tổ hợp thiết bị đó được coi là không đáng kể về mặt thống kê và được đặt thành Không áp dụng.

Khi một giờ có đủ khối lượng mẫu trên cả 2 đường dẫn, độ chính xác cơ sở theo giờ cho một trạng thái cụ thể được tính là mức trung bình của 2 tỷ lệ phần trăm độc lập:

Độ chính xác của trạng thái theo giờ = (Độ chính xác của truy vấn % + Độ chính xác của thực thi %) / 2

Trong đó, mỗi đường dẫn được xác định như sau:

• Độ chính xác của truy vấn % = (Số mẫu chính xác của truy vấn theo giờ) / (Tổng số mẫu của truy vấn theo giờ)
• Độ chính xác của thực thi % = (Số mẫu chính xác của thực thi theo giờ) / (Tổng số mẫu của thực thi theo giờ)

Điểm độ chính xác của đặc điểm (tính theo từng đặc điểm) = TỔNG(Số mẫu chính xác của truy vấn + Số mẫu chính xác của thực thi) / TỔNG(Tổng số mẫu của truy vấn + Tổng số mẫu của thực thi)

Vì Điểm chất lượng đánh giá hiệu suất tối thiểu nghiêm ngặt trên toàn bộ hệ sinh thái của bạn, nên mỗi đặc điểm được hỗ trợ và đủ điều kiện phải đáp ứng riêng mục tiêu Độ chính xác của trạng thái >= 99,5% (đây không phải là mức trung bình trên các đặc điểm).

Chế độ xem này ngăn các thiết bị có khối lượng lớn với độ chính xác tuyệt vời che giấu các vấn đề về độ chính xác trên các thiết bị có khối lượng thấp hơn. Các đối tác lo ngại về việc các đặc điểm ít được sử dụng làm giảm điểm số của họ có thể yên tâm rằng một đặc điểm ít được sử dụng sẽ tự động được bảo vệ bằng cách kiểm tra khối lượng truy cập tối thiểu và sẽ không được tính vào điểm số của Loại và Đặc điểm thấp nhất trừ phi đặc điểm đó đáp ứng ngưỡng mẫu bắt buộc.

3. Cải thiện tình trạng thiết bị và độ chính xác của trạng thái

Sự khác biệt xảy ra khi trạng thái được lưu trữ trong Home Graph không khớp với kết quả của truy vấn theo thời gian thực.

Lỗi "Thiếu trường"

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"
  }
  

Nguyên nhân: Với lỗi DETAILED_ACCURACY_RESULT_QUERY_STATE_MISSING_FIELD hoặc DETAILED_ACCURACY_RESULT_REPORT_STATE_MISSING_FIELD, tập hợp các trường tải trọng khác nhau giữa phản hồi QUERY và yêu cầu Báo cáo trạng thái cho cùng một thiết bị.

Giải pháp: Đảm bảo cấu trúc dữ liệu giống nhau ở cả 2 đường dẫn. Nếu một đặc điểm được đưa vào SYNC, thì các trường tương ứng của đặc điểm đó phải có và nhất quán trong cả báo cáo chủ động và truy vấn phản ứng.

Lỗi "Không chính xác"

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"
  }
  

Nguyên nhân: Đối với lỗi DETAILED_ACCURACY_RESULT_INACCURATE, có sự khác biệt giữa giá trị được trả về trong phản hồi QUERY và giá trị Báo cáo trạng thái cuối cùng.

Giải pháp: Đảm bảo Báo cáo trạng thái được kích hoạt bất cứ khi nào trạng thái thiết bị thay đổi và cả Báo cáo trạng thái và QUERY luôn cung cấp chính xác cùng một giá trị mới nhất và tất cả các trường bắt buộc để duy trì tính nhất quán của dữ liệu.

"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"
   }
  

Nguyên nhân: Với lỗi DETAILED_ACCURACY_RESULT_MISSING_REPORT_STATE, đối tác đã thực thi lệnh thành công nhưng không báo cáo trạng thái thiết bị đã cập nhật cho Google.

Giải pháp: Luôn gửi bản cập nhật Báo cáo trạng thái sau khi thực thi lệnh để Home Graph nhận được trạng thái thiết bị mới.

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"
   }
  

Nguyên nhân: Đối với lỗi DETAILED_ACCURACY_RESULT_NO_STATE_REPORTED, không có Báo cáo trạng thái nào được nhận cho thiết bị này (trạng thái trống và dấu thời gian được báo cáo là ở thời điểm bắt đầu kỷ nguyên), mặc dù kết quả QUERY cung cấp trạng thái hiện tại. Điều này cho biết rằng các bản cập nhật trạng thái không được kích hoạt, không đến được HomeGraph hoặc thiết bị không báo cáo thành công các quá trình chuyển đổi trong trạng thái kết nối hoặc hoạt động.

Giải pháp: Đảm bảo Báo cáo trạng thái được kích hoạt và gửi thành công cho tất cả các thay đổi trạng thái. Xác minh rằng logic phụ trợ xử lý chính xác các bản cập nhật trạng thái, xác nhận thành công việc phân phối đến Google HomeGraph và đảm bảo thiết bị liên tục đồng bộ hoá trạng thái để giữ cho giao diện người dùng và công cụ tự động hoá chính xác.