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 nonaktif, 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, seperti 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.
Pemecahan masalah untuk PGKA V2
Dengan enable_response_debug_info field yang diaktifkan, objek KnowledgeAssistDebugInfo menyertakan beberapa kolom baru khusus untuk PGKA V2. Untuk mengaksesnya, baseline_model_version dan enable_response_debug_info harus ditetapkan ke 2.0.
Berikut adalah contoh penyiapan untuk mengakses informasi pemecahan masalah di PGKA V2:
"name": "projects/PROJECT_ID/locations/LOCATION/conversationProfiles/PROFILE_ID",
"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/agents/AGENT_ID"
}
},
"conversation_model_config": {
"baseline_model_version": "2.0"
},
"disable_query_search_context": true,
"enable_response_debug_info": true,
"suggestion_trigger_event": "END_OF_UTTERANCE",
}
]
}
}
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: Nilaitruemenunjukkan bahwa sistem menulis ulang kueri pengguna agar lebih efektif untuk menelusuri Datastore. Nilaifalsemenunjukkan bahwa generator tidak menulis ulang kueri Anda.end_user_metadata_included: Nilaitruemenunjukkan bahwaend_user_metadataditeruskan dalam panggilan ke agen penyimpanan data. Nilaifalsemenunjukkan bahwaend_user_metadatatidak 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: Nilaitrueberarti project tidak ada dalam daftar yang diizinkan untuk menggunakan fitur referensi konteks yang di-ingest. Nilaifalseberarti 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 (mis., JSON).INGESTION_STATUS_LANGUAGE_MISMATCH: Bahasa referensi konteks tidak cocok dengan bahasa percakapan.
Latensi
Objek
service_latencymenguraikan waktu yang dihabiskan di 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 berakhir (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 berfungsi sebagai timer utama untuk semua langkah penelusuran datastore untuk agen.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 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 Agent Search, 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, seperti 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 jika 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.QUERY_GENERATION_EMPTY_CONVERSATION: Percakapan tidak memiliki pesan. Fitur ini hanya tersedia untuk PGKA V2.QUERY_GENERATION_EMPTY_LAST_MESSAGE: Pesan terakhir kosong atau berisi spasi kosong. Fitur ini hanya tersedia untuk PGKA V2.QUERY_GENERATION_TRIGGERING_EVENT_CONDITION_NOT_MET: Konfigurasi peristiwa pemicu (mis.,AGENT_MESSAGE) tidak cocok dengan peran pengirim pesan terakhir. Fitur ini hanya tersedia untuk PGKA V2.QUERY_GENERATION_LLM_RESPONSE_PARSE_FAILED: Sistem tidak dapat mengurai output JSON terstruktur dari model. Fitur ini hanya tersedia untuk PGKA V2.
Gagal mengategorikan kueri
Kolom query_categorization_failure_reason menjelaskan alasan kategorisasi kueri mungkin gagal.
QUERY_CATEGORIZATION_INVALID_CONFIG: Konfigurasi Agent Search yang diberikan untuk kategorisasi tidak valid, misalnya mesin telusur kosong.QUERY_CATEGORIZATION_RESULT_NOT_FOUND: Hasil dari Agent Search tidak menyertakan hasil kategorisasi.QUERY_CATEGORIZATION_FAILED: Panggilan ke Agent Search 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:truejika generator menulis ulang kueri untuk hasil penelusuran yang lebih baik danfalsejika tidak.end_user_metadata_included:truejika generator meneruskanend_user_metadatake Datastore danfalsejika tidak.return_query_only:truejika profil Anda dikonfigurasi untuk hanya menampilkan kueri penelusuran yang dihasilkan danfalsejika profil Anda menampilkan jawaban lengkap.use_pubsub_delivery:truejika generator Anda dikonfigurasi untuk mengirimkan hasil dengan Pub/Sub danfalsejika tidak.disable_sync_delivery:truejika pengiriman respons sinkron dinonaktifkan danfalsejika pengiriman respons sinkron diaktifkan.previous_queries_included:truejika generator mempertimbangkan kueri yang sebelumnya disarankan selama proses pembuatan kueri danfalsejika tidak.use_translated_message:truejika pesan yang diterjemahkan digunakan untuk pembuatan kueri danfalsejika tidak.use_custom_safety_filter_level:truejika tingkat filter keamanan kustom diterapkan.falsejika generator hanya menggunakan tingkat filter keamanan default.multiple_queries_generated: Nilaitruemenunjukkan bahwa model menghasilkan lebih dari satu kueri. Fitur ini tersedia untuk PGKA V2.query_contained_search_context: Nilaitruemenunjukkan bahwa kueri yang dihasilkan menyertakan konteks penelusuran. Fitur ini tersedia untuk PGKA V2.appended_search_context_count: Hal ini menunjukkan jumlah item konteks (mis., "produk", "OS") yang berhasil digunakan dalam penelusuran. Fitur ini tersedia untuk PGKA V2.
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: Nilaitrueberarti project tidak ada dalam daftar yang diizinkan untuk menggunakan fitur referensi konteks yang di-ingest. Nilaifalseberarti 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 untuk PGKA V1
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
}
}
]
}
}
}
Contoh respons pemecahan masalah untuk PGKA V2
Berikut adalah contoh komprehensif untuk dua skenario.
Contoh 1: Saran yang berhasil dengan flag perilaku
Skenario ini mengilustrasikan respons yang berhasil dibuat model untuk beberapa kueri dan memperkaya kueri utama dengan konteks penelusuran. Berikut adalah penjelasan kolom:
multiple_queries_generated: Menunjukkan bahwa model menghasilkan lebih dari satu topik yang relevan.query_contained_search_context: Mengonfirmasi bahwa kueri utama diperkaya dengan data terstruktur.appended_search_context_count: Jumlah pasti key-value pair (mis., nama aplikasi, OS) yang digunakan untuk menyaring penelusuran.
{
"message": {
"name": "projects/PROJECT_ID/locations/LOCATION/conversations/CONVERSATION_ID/messages/MESSAGE_ID",
"content": "My DesignApp is crashing on Mac. Also, how do I resolve the storage limit error?",
"participant_role": "END_USER"
},
"human_agent_suggestion_results": [
{
"suggest_knowledge_assist_response": {
"knowledge_assist_answer": {
"suggested_query": {
"query_text": "Troubleshoot application crashing",
"search_contexts": [
{ "key": "application name", "value": "DesignApp" },
{ "key": "operating system", "value": "Mac" }
]
},
"suggested_query_answer": {
"answer_text": "To troubleshoot the crash on Mac, ensure..."
},
"answer_record": "projects/PROJECT_ID/locations/LOCATION/answerRecords/ANSWER_RECORD_ID",
"knowledge_assist_debug_info": {
"knowledge_assist_behavior": {
"multiple_queries_generated": true,
"query_contained_search_context": true,
"appended_search_context_count": 2
}
}
},
"latest_message": "projects/PROJECT_ID/locations/LOCATION/conversations/CONVERSATION_ID/messages/MESSAGE_ID",
"context_size": 20,
"additional_suggested_query_results": [
{
"suggested_query": {
"query_text": "Resolve storage limit exceeded error",
"search_contexts": [
{ "key": "storage plan", "value": "1TB" }
]
}
}
]
}
}
]
}
Contoh 2: Saran yang dilewati dengan alasan kegagalan
Dalam skenario ini, sistem menentukan bahwa saran tidak boleh dipicu karena kondisi peristiwa tidak terpenuhi (mis., pemicu ditetapkan ke AGENT_MESSAGE, tetapi pesan terakhir berasal dari END_USER). Daripada error, sistem akan menampilkan status berhasil dengan alasan tertentu.
{
"message": {
"name": "projects/PROJECT_ID/locations/LOCATION/conversations/CONVERSATION_ID/messages/MESSAGE_ID",
"content": "I am having trouble with my account.",
"participant_role": "END_USER"
},
"human_agent_suggestion_results": [
{
"suggest_knowledge_assist_response": {
"knowledge_assist_answer": {
"knowledge_assist_debug_info": {
"query_generation_failure_reason": "QUERY_GENERATION_TRIGGERING_EVENT_CONDITION_NOT_MET"
}
},
"latest_message": "projects/PROJECT_ID/locations/LOCATION/conversations/CONVERSATION_ID/messages/MESSAGE_ID",
"context_size": 20
}
}
]
}
Alasan kegagalan umum lainnya mencakup:
QUERY_GENERATION_EMPTY_CONVERSATION: Tidak menemukan pesan dalam percakapan.QUERY_GENERATION_EMPTY_LAST_MESSAGE: Pesan terakhir kosong atau hanya berisi spasi kosong.QUERY_GENERATION_LLM_RESPONSE_PARSE_FAILED: Sistem tidak dapat mengurai output terstruktur dari LLM.