Memecahkan masalah fitur bantuan pengetahuan

Akses informasi mendetail terkait kegagalan, perilaku penggunaan fitur, dan latensi untuk bantuan pengetahuan generatif (GKA) dan bantuan pengetahuan generatif proaktif (PGKA). Aktifkan enable_response_debug_info untuk melihat detail pemecahan masalah ini dalam objek knowledge_assist_debug_info.

Mengonfigurasi profil percakapan untuk pemecahan masalah

Untuk mengakses informasi pemecahan masalah untuk GKA dan PGKA, Anda harus mengaktifkan kolom enable_response_debug_info di profil percakapan. Jika kolom ini dinonaktifkan, penelusuran pengetahuan akan menampilkan error NotFound saat kueri tidak memberikan hasil dan bantuan pengetahuan akan menampilkan pesan kosong. Aktifkan enable_response_debug_info untuk memberikan respons OK dengan detail tentang tidak adanya hasil. Perubahan ini memengaruhi API dan integrasi yang ada.

Bantuan pengetahuan generatif (GKA)

Untuk mendapatkan informasi pemecahan masalah mendetail untuk kueri GKA, Anda harus mengaktifkannya di profil percakapan. Saat membuat atau memperbarui profil percakapan, tetapkan kolom enable_response_debug_info ke true dalam human_agent_assistant_config, sebagai berikut.

parent:"projects/PROJECT_ID/locations/LOCATION-ID"
conversation_profile {
  display_name: "DISPLAY-NAME"
  human_agent_assistant_config {
    human_agent_suggestion_config {
      feature_configs {
        suggestion_feature {
          type: KNOWLEDGE_SEARCH
        }
        query_config {
          dialogflow_query_source {
            human_agent_side_config {
              agent: "projects/PROJECT_ID/locations/LOCATION-NAME/agents/AGENT-ID"
            }
          }
        }
        enable_response_debug_info: true
      }
    }
  }
}

Dengan kolom enable_response_debug_info yang diaktifkan, generator akan menampilkan objek knowledge_search_debug_info sebagai bagian dari SearchKnowledgeResponse beserta jawaban yang dihasilkan. Informasi ini memberikan insight berharga tentang performa dan perilaku penelusuran pengetahuan.

Detail pemecahan masalah

Objek search_knowledge_debug_info berisi beberapa informasi utama untuk membantu Anda memecahkan masalah dan memahami proses penelusuran untuk GKA.

Kegagalan penelusuran atau jawaban yang tidak membantu

Kolom datastore_response_reason memberi Anda status tingkat tinggi tentang kualitas penayangan data atau jawaban. Kolom ini membantu Anda mengidentifikasi dengan cepat alasan penelusuran mungkin gagal atau alasan kualitas jawaban mungkin menurun.

Nilai yang memungkinkan mencakup:

  • NONE: Permintaan diproses tanpa masalah tertentu untuk dilaporkan.
  • SEARCH_OUT_OF_QUOTA: Operasi penelusuran diblokir karena melebihi kuota penggunaan.
  • SEARCH_EMPTY_RESULTS: Penelusuran tidak menampilkan dokumen dari Datastore Anda.
  • ANSWER_GENERATION_GEN_AI_DISABLED: Fitur AI generatif dinonaktifkan untuk project Anda.
  • ANSWER_GENERATION_OUT_OF_QUOTA: Pembuatan jawaban diblokir karena melebihi kuota penggunaan.
  • ANSWER_GENERATION_ERROR: Terjadi error internal selama pembuatan jawaban.
  • ANSWER_GENERATION_NOT_ENOUGH_INFO: Dokumen yang diambil tidak memiliki informasi yang cukup untuk membuat jawaban.
  • ANSWER_GENERATION_RAI_FAILED: Jawaban yang dihasilkan diblokir oleh filter Responsible AI (RAI).
  • ANSWER_GENERATION_NOT_GROUNDED: Langkah verifikasi grounding menentukan bahwa jawaban yang dihasilkan tidak didukung secara faktual oleh dokumen sumber dan oleh karena itu dibuang.

Perilaku aktif

Objek search_knowledge_behavior memberi tahu Anda perilaku spesifik mana yang aktif selama permintaan GKA.

  • answer_generation_rewriter_on: Nilai true menunjukkan bahwa sistem menulis ulang kueri pengguna agar lebih efektif untuk menelusuri Datastore. Nilai false menunjukkan bahwa generator tidak menulis ulang kueri Anda.
  • end_user_metadata_included: Nilai true menunjukkan bahwa end_user_metadata diteruskan dalam panggilan ke agen penyimpanan data. Nilai false menunjukkan bahwa end_user_metadata tidak diteruskan ke agen penyimpanan data.

Informasi pemecahan masalah dari konteks yang di-ingest

Kolom ingested_context_reference_debug_info memberikan informasi pemecahan masalah terkait konteks yang di-ingest untuk membantu penelusuran.

  • project_not_allowlisted: Nilai true berarti project tidak ada dalam daftar yang diizinkan untuk menggunakan fitur referensi konteks yang di-ingest. Nilai false berarti project ada dalam daftar yang diizinkan.
  • context_reference_retrieved: Menunjukkan apakah referensi konteks berhasil diambil dari database.
  • ingested_parameters_debug_info: Daftar parameter yang di-ingest dari referensi konteks dan statusnya. Untuk setiap parameter, Anda akan melihat nama parameter dan salah satu status ingestion berikut.
    • INGESTION_STATUS_SUCCEEDED: Parameter berhasil di-ingest.
    • INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: Parameter tidak tersedia untuk di-ingest.
    • INGESTION_STATUS_PARSE_FAILED: Sistem gagal mengurai konten parameter.
    • INGESTION_STATUS_INVALID_ENTRY: Referensi konteks memiliki jumlah entri konten yang tidak terduga (hanya boleh memiliki satu).
    • INGESTION_STATUS_INVALID_FORMAT: Konten konteks tidak dalam format yang diharapkan (misalnya, JSON).
    • INGESTION_STATUS_LANGUAGE_MISMATCH: Bahasa referensi konteks tidak cocok dengan bahasa percakapan.

Latensi

{# disableFinding("data store")}

  • Objek service_latency menguraikan waktu yang dihabiskan dalam berbagai layanan internal, sehingga membantu Anda menentukan bottleneck performa.

  • internal_service_latencies: Daftar yang berisi detail latensi untuk setiap langkah internal proses. Setiap entri mencakup nama (step), jumlah waktu yang diperlukan dalam milidetik (latency_ms), serta waktu mulai (start_time) dan waktu selesai (complete_time). Nama yang memungkinkan untuk langkah proses internal adalah sebagai berikut:

    • total_data_store_agent: Mengukur total waktu yang diperlukan untuk memproses seluruh permintaan GKA, mulai dari menerima kueri hingga menampilkan jawaban akhir. Kolom ini bertindak sebagai timer gabungan untuk semua langkah penelusuran agen penyimpanan data.
    • query_rewrite: Waktu yang dihabiskan untuk menulis ulang kueri awal pengguna agar lebih efektif untuk menelusuri dokumen pengetahuan Anda.
    • search_query: Waktu yang diperlukan oleh agen penyimpanan data untuk menjalankan penelusuran terhadap penyimpanan data atau penyimpanan yang dikonfigurasi, menggunakan kueri (yang mungkin ditulis ulang).
    • summarization: Waktu yang dihabiskan untuk membuat jawaban bahasa natural yang ringkas dari hasil penelusuran yang diambil dari Datastore (giliran ReAct).
    • grounding: Waktu yang dihabiskan untuk proses verifikasi grounding. Langkah penting ini memeriksa apakah jawaban yang dihasilkan didukung secara faktual oleh dokumen sumber sebelum ditampilkan.
    • query_generation: Waktu yang dihabiskan untuk menganalisis percakapan yang sedang berlangsung dan secara proaktif membuat kueri penelusuran yang relevan.
    • generated_query_rai: Waktu yang diperlukan untuk melakukan pemeriksaan keamanan Responsible AI (RAI) pada kueri yang dibuat secara proaktif sebelum digunakan untuk penelusuran.
    • query_categorization: Waktu yang dihabiskan untuk mengategorikan kueri yang dihasilkan menggunakan Penelusuran Agen, jika fitur ini dikonfigurasi.

Contoh respons informasi pemecahan masalah

Berikut adalah contoh komprehensif tentang tampilan objek search_knowledge_debug_info dalam respons JSON. 

{
  "search_knowledge_debug_info": {
    "datastore_response_reason": "ANSWER_GENERATION_NOT_ENOUGH_INFO",
    "search_knowledge_behavior": {
      "answer_generation_rewriter_on": true,
      "end_user_metadata_included": true
    },
    "ingested_context_reference_debug_info": {
      "project_not_allowlisted": false,
      "context_reference_retrieved": true,
      "ingested_parameters_debug_info": [
        {
          "parameter": "order_id",
          "ingestion_status": "INGESTION_STATUS_SUCCEEDED"
        },
        {
          "parameter": "user_profile",
          "ingestion_status": "INGESTION_STATUS_INVALID_FORMAT"
        },
        {
          "parameter": "product_sku",
          "ingestion_status": "INGESTION_STATUS_CONTEXT_NOT_AVAILABLE"
        }
      ]
    },
    "service_latency": {
      "internal_service_latencies": [
        {
          "step": "total_data_store_agent",
          "latency_ms": 4125.781,
          "start_time": {
            "seconds": 1750969252,
            "nanos": 550649603
          },
          "complete_time": {
            "seconds": 1750969256,
            "nanos": 676430603
          }
        },
        {
          "step": "query_rewrite",
          "latency_ms": 412.0,
          "start_time": {
            "seconds": 1750969252,
            "nanos": 780119421
          },
          "complete_time": {
            "seconds": 1750969253,
            "nanos": 192119421
          }
        },
        {
          "step": "search_query",
          "latency_ms": 950.0,
          "start_time": {
            "seconds": 1750969253,
            "nanos": 192119421
          },
          "complete_time": {
            "seconds": 1750969254,
            "nanos": 142119421
          }
        },
        {
          "step": "summarization",
          "latency_ms": 721.0,
          "start_time": {
            "seconds": 1750969254,
            "nanos": 142119421
          },
          "complete_time": {
            "seconds": 1750969254,
            "nanos": 863119421
          }
        },
        {
            "step": "grounding",
            "latency_ms": 155.0,
            "start_time": {
              "seconds": 1750969254,
              "nanos": 863119421
            },
            "complete_time": {
              "seconds": 1750969255,
              "nanos": 18119421
            }
        }
      ]
    }
  }
}

Bantuan pengetahuan generatif proaktif (PGKA)

Pemecahan masalah memberikan insight mendalam tentang proses pembuatan kueri, kategorisasi, dan pengambilan jawaban. Objek knowledge_assist_debug_info adalah bagian dari knowledge_assist_answer dalam hasil saran Anda.

Saat membuat atau memperbarui profil percakapan, tetapkan kolom enable_response_debug_info ke true untuk fitur KNOWLEDGE_ASSIST, sebagai berikut.

parent: "projects/PROJECT_ID/locations/LOCATION-ID"
conversation_profile {
  display_name: "DISPLAY-NAME"
  human_agent_assistant_config {
    human_agent_suggestion_config {
      feature_configs {
        suggestion_feature {
          type: KNOWLEDGE_ASSIST
        }
        query_config {
          dialogflow_query_source {
            agent: "projects/PROJECT_ID/locations/LOCATION-ID/agents/DATASTORE-AGENT-ID"
          }
        }
        enable_response_debug_info: true
      }
    }
  }
}

Detail pemecahan masalah

Objek knowledge_assist_debug_info berisi kolom berikut untuk membantu Anda memahami siklus proses end-to-end saran proaktif.

Gagal membuat kueri

Kolom query_generation_failure_reason menjelaskan alasan percakapan mungkin tidak menghasilkan kueri penelusuran proaktif.

  • QUERY_GENERATION_FAILED: Terjadi error internal selama pembuatan kueri.
  • QUERY_GENERATION_NO_QUERY_GENERATED: Generator memutuskan untuk tidak membuat kueri. Hal ini biasanya terjadi saat topik percakapan tidak berubah atau kueri serupa baru-baru ini disarankan.
  • QUERY_GENERATION_RAI_FAILED: Filter Responsible AI (RAI) memblokir potensi kueri karena alasan keamanan.
  • NOT_IN_ALLOWLIST: Aturan pemfilteran di tingkat profil percakapan atau agen memblokir pembuatan kueri.
  • QUERY_GENERATION_QUERY_REDACTED: Generator memblokir kueri yang dihasilkan karena berisi informasi sensitif yang disamarkan.
  • QUERY_GENERATION_AGENT_LANGUAGE_MISMATCH: Pembuatan kueri gagal karena bahasa agen tidak cocok dengan bahasa pelanggan.
  • QUERY_GENERATION_TRANSLATION_LANGUAGE_MISMATCH: Pembuatan kueri gagal karena bahasa pesan yang diterjemahkan tidak cocok dengan bahasa profil percakapan.
  • QUERY_GENERATION_TRANSLATED_MESSAGE_NOT_FOUND: Generator mengharapkan pesan yang diterjemahkan untuk pembuatan kueri, tetapi tidak menemukannya.

Gagal mengategorikan kueri

Kolom query_categorization_failure_reason menjelaskan alasan kategorisasi kueri mungkin gagal.

  • QUERY_CATEGORIZATION_INVALID_CONFIG: Konfigurasi Penelusuran Agen yang diberikan untuk kategorisasi tidak valid, misalnya mesin telusur kosong.
  • QUERY_CATEGORIZATION_RESULT_NOT_FOUND: Hasil dari Penelusuran Agen tidak menyertakan hasil kategorisasi.
  • QUERY_CATEGORIZATION_FAILED: Panggilan ke Penelusuran Agen untuk kategorisasi gagal.

Status penelusuran Datastore

Kolom datastore_response_reason memberikan status penelusuran terhadap Datastore Anda setelah kueri dibuat.

  • NONE: Datastore memproses permintaan tanpa masalah tertentu untuk dilaporkan.
  • SEARCH_OUT_OF_QUOTA: Agent Assist memblokir operasi penelusuran karena melebihi kuota penggunaan.
  • SEARCH_EMPTY_RESULTS: Penelusuran tidak menampilkan dokumen dari Datastore Anda.
  • ANSWER_GENERATION_GEN_AI_DISABLED: Fitur AI generatif dinonaktifkan untuk project Anda.
  • ANSWER_GENERATION_OUT_OF_QUOTA: Agent Assist memblokir pembuatan jawaban karena melebihi kuota penggunaan.
  • ANSWER_GENERATION_ERROR: Terjadi error internal selama pembuatan jawaban.
  • ANSWER_GENERATION_NOT_ENOUGH_INFO: Dokumen yang diambil tidak memiliki informasi yang cukup untuk membuat jawaban.
  • ANSWER_GENERATION_RAI_FAILED: Filter RAI memblokir jawaban yang dihasilkan.
  • ANSWER_GENERATION_NOT_GROUNDED: Langkah verifikasi grounding menentukan bahwa dokumen sumber tidak mendukung jawaban yang dihasilkan secara faktual, sehingga jawaban tersebut dibuang.

Konfigurasi aktif

Objek knowledge_assist_behavior memberi tahu Anda konfigurasi spesifik mana yang aktif untuk permintaan tersebut.

  • answer_generation_rewriter_on: true jika generator menulis ulang kueri untuk hasil penelusuran yang lebih baik dan false jika tidak.
  • end_user_metadata_included: true jika generator meneruskan end_user_metadata ke Datastore dan false jika tidak.
  • return_query_only: true jika profil Anda dikonfigurasi untuk hanya menampilkan kueri penelusuran yang dihasilkan dan false jika profil Anda menampilkan jawaban lengkap.
  • use_pubsub_delivery: true jika generator Anda dikonfigurasi untuk mengirimkan hasil dengan Pub/Sub dan false jika tidak.
  • disable_sync_delivery: true jika pengiriman respons sinkron dinonaktifkan dan false jika pengiriman respons sinkron diaktifkan.
  • previous_queries_included: true jika generator mempertimbangkan kueri yang sebelumnya disarankan selama proses pembuatan kueri dan false jika tidak.
  • use_translated_message: true jika pesan yang diterjemahkan digunakan untuk pembuatan kueri dan false jika tidak.
  • use_custom_safety_filter_level: true jika tingkat filter keamanan kustom diterapkan. false jika generator hanya menggunakan tingkat filter keamanan default.

Informasi dari konteks yang di-ingest

Kolom ingested_context_reference_debug_info memberikan informasi debug terkait konteks yang di-ingest untuk membantu penelusuran.

  • project_not_allowlisted: Nilai true berarti project tidak ada dalam daftar yang diizinkan untuk menggunakan fitur referensi konteks yang di-ingest. Nilai false berarti project ada dalam daftar yang diizinkan.
  • context_reference_retrieved: Menunjukkan apakah referensi konteks berhasil diambil dari database.
  • ingested_parameters_debug_info: Daftar parameter yang di-ingest dari referensi konteks dan statusnya. Untuk setiap parameter, Anda akan melihat nama parameter dan salah satu status ingestion yang memungkinkan berikut.
    • INGESTION_STATUS_SUCCEEDED: Parameter berhasil di-ingest.
    • INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: Parameter tidak tersedia untuk di-ingest.
    • INGESTION_STATUS_PARSE_FAILED: Sistem gagal mengurai konten parameter.
    • INGESTION_STATUS_INVALID_ENTRY: Referensi konteks memiliki jumlah entri konten yang tidak terduga (hanya boleh memiliki satu).
    • INGESTION_STATUS_INVALID_FORMAT: Konten konteks tidak dalam format yang diharapkan.
    • INGESTION_STATUS_LANGUAGE_MISMATCH: Bahasa referensi konteks tidak cocok dengan bahasa percakapan.

Contoh respons pemecahan masalah

Berikut adalah contoh komprehensif tentang tampilan objek knowledge_assist_debug_info dalam respons. 

{
  "knowledge_assist_debug_info": {
    "query_generation_failure_reason": "QUERY_GENERATION_NO_QUERY_GENERATED",
    "query_categorization_failure_reason": "QUERY_CATEGORIZATION_FAILURE_REASON_UNSPECIFIED",
    "datastore_response_reason": "SEARCH_EMPTY_RESULTS",
    "knowledge_assist_behavior": {
      "answer_generation_rewriter_on": true,
      "end_user_metadata_included": false,
      "return_query_only": false,
      "use_pubsub_delivery": true,
      "disable_sync_delivery": true,
      "previous_queries_included": true,
      "use_translated_message": false,
      "use_custom_safety_filter_level": false
    },
    "ingested_context_reference_debug_info": {
      "project_not_allowlisted": false,
      "context_reference_retrieved": true,
      "ingested_parameters_debug_info": [
        {
          "parameter": "session_id",
          "ingestion_status": "INGESTION_STATUS_SUCCEEDED"
        }
      ]
    },
    "service_latency": {
      "internal_service_latencies": [
        {
          "step": "query_generation",
          "latency_ms": 680.5,
          "start_time": {
            "seconds": 1753123456,
            "nanos": 110220330
          },
          "complete_time": {
            "seconds": 1753123456,
            "nanos": 790720330
          }
        },
        {
          "step": "search_query",
          "latency_ms": 1050.1,
          "start_time": {
            "seconds": 1753123456,
            "nanos": 790720330
          },
          "complete_time": {
            "seconds": 1753123457,
            "nanos": 840820330
          }
        }
      ]
    }
  }
}