지식 지원 기능 문제 해결

생성형 지식 지원 (GKA)과 사전 예방적 생성형 지식 지원 (PGKA) 모두의 실패, 기능 사용 동작, 지연 시간에 관한 자세한 정보에 액세스합니다. knowledge_assist_debug_info 객체 내에서 이러한 문제 해결 세부정보를 보려면 enable_response_debug_info를 사용 설정하세요.

문제 해결을 위한 대화 프로필 구성하기

GKA와 PGKA 모두의 문제 해결 정보에 액세스하려면 대화 프로필에서 enable_response_debug_info 필드를 사용 설정해야 합니다. 이 필드가 사용 중지되어 있으면 쿼리에서 결과가 나오지 않을 때 지식 검색에서 NotFound 오류가 표시되고 지식 지원에서 빈 메시지가 표시됩니다. enable_response_debug_info를 사용 설정하여 결과가 부족한 이유에 대한 세부정보가 포함된 OK 응답을 제공합니다. 이 수정사항은 API 및 기존 통합에 영향을 미칩니다.

생성형 지식 지원 (GKA)

GKA 쿼리에 대한 자세한 문제 해결 정보를 확인하려면 대화 프로필에서 사용 설정해야 합니다. 대화 프로필을 만들거나 업데이트할 때 다음과 같이 human_agent_assistant_config 내에서 enable_response_debug_info 필드를 true로 설정합니다.

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

enable_response_debug_info 필드를 사용 설정하면 생성기는 생성된 답변과 함께 SearchKnowledgeResponse의 일부로 knowledge_search_debug_info 객체를 반환합니다. 이 정보는 지식 검색의 성능과 동작에 관한 유용한 정보를 제공합니다.

문제 해결 세부정보

search_knowledge_debug_info 객체에는 GKA의 검색 프로세스를 이해하고 문제를 해결하는 데 도움이 되는 여러 주요 정보가 포함되어 있습니다.

검색 실패 또는 도움이 되지 않는 답변

datastore_response_reason 필드는 데이터 서빙 또는 답변 품질에 관한 상위 수준 상태를 제공합니다. 검색이 실패한 이유 또는 대답 품질이 저하된 이유를 빠르게 파악하는 데 도움이 됩니다.

가능한 값은 다음과 같습니다.

  • NONE: 보고할 특정 문제 없이 요청이 처리되었습니다.
  • SEARCH_OUT_OF_QUOTA: 사용량 할당량을 초과하여 검색 작업이 차단되었습니다.
  • SEARCH_EMPTY_RESULTS: 검색 결과에 Datastore의 문서가 없습니다.
  • ANSWER_GENERATION_GEN_AI_DISABLED: 프로젝트에 생성형 AI 기능이 사용 중지되어 있습니다.
  • ANSWER_GENERATION_OUT_OF_QUOTA: 사용량 할당량 초과로 인해 대답 생성이 차단되었습니다.
  • ANSWER_GENERATION_ERROR: 대답 생성 중에 내부 오류가 발생했습니다.
  • ANSWER_GENERATION_NOT_ENOUGH_INFO: 검색된 문서에 답변을 생성하기에 충분한 정보가 없습니다.
  • ANSWER_GENERATION_RAI_FAILED: 생성된 대답이 책임감 있는 AI (RAI) 필터에 의해 차단되었습니다.
  • ANSWER_GENERATION_NOT_GROUNDED: 그라운딩 검증 단계에서 생성된 대답이 소스 문서에 의해 사실로 뒷받침되지 않는 것으로 확인되어 폐기되었습니다.

활성 동작

search_knowledge_behavior 객체는 GKA 요청 중에 활성화된 특정 동작을 알려줍니다.

  • answer_generation_rewriter_on: true 값은 시스템이 데이터 스토어를 검색하는 데 더 효과적이도록 사용자의 쿼리를 다시 작성했음을 나타냅니다. false 값은 생성기가 질문을 다시 작성하지 않았음을 나타냅니다.
  • end_user_metadata_included: true 값은 데이터 스토어 에이전트 호출에 end_user_metadata이 전달되었음을 나타냅니다. false 값은 end_user_metadata이 데이터 스토어 에이전트에 전달되지 않았음을 나타냅니다.

수집된 컨텍스트의 문제 해결 정보

ingested_context_reference_debug_info 필드는 검색을 지원하기 위해 인그레스된 컨텍스트와 관련된 문제 해결 정보를 제공합니다.

  • project_not_allowlisted: true 값은 프로젝트가 수집된 컨텍스트 참조 기능을 사용하기 위한 허용 목록에 없음을 의미합니다. false 값은 프로젝트가 허용 목록에 있음을 의미합니다.
  • context_reference_retrieved: 컨텍스트 참조가 데이터베이스에서 성공적으로 검색되었는지 여부를 나타냅니다.
  • ingested_parameters_debug_info: 컨텍스트 참조에서 가져온 파라미터와 해당 상태의 목록입니다. 각 파라미터에는 파라미터 이름과 다음 수집 상태 중 하나가 표시됩니다.
    • INGESTION_STATUS_SUCCEEDED: 매개변수가 성공적으로 수집되었습니다.
    • INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: 파라미터를 수집할 수 없습니다.
    • INGESTION_STATUS_PARSE_FAILED: 시스템에서 매개변수의 콘텐츠를 파싱하지 못했습니다.
    • INGESTION_STATUS_INVALID_ENTRY: 컨텍스트 참조에 예상치 못한 수의 콘텐츠 항목이 있습니다 (하나만 있어야 함).
    • INGESTION_STATUS_INVALID_FORMAT: 컨텍스트 콘텐츠가 예상 형식 (예: JSON)이 아닙니다.
    • INGESTION_STATUS_LANGUAGE_MISMATCH: 컨텍스트 참조의 언어가 대화의 언어와 일치하지 않습니다.

지연 시간

{# disableFinding("data store")}

  • service_latency 객체는 다양한 내부 서비스에서 소요된 시간을 분석하여 성능 병목 현상을 정확히 파악하는 데 도움이 됩니다.

  • internal_service_latencies: 프로세스의 각 내부 단계에 대한 지연 시간 세부정보가 포함된 목록입니다. 각 항목에는 이름(step), 소요 시간(밀리초)(latency_ms), 시작 시간(start_time), 종료 시간(complete_time)이 포함됩니다. 내부 프로세스 단계의 가능한 이름은 다음과 같습니다.

    • total_data_store_agent: 쿼리를 수신하는 시점부터 최종 답변을 반환하는 시점까지 전체 GKA 요청을 처리하는 데 걸리는 총시간을 측정합니다. 모든 데이터 스토어 에이전트 검색 단계의 전체 타이머 역할을 합니다.
    • query_rewrite: 사용자 초기 질문을 기술 자료 문서를 검색하는 데 더 효과적으로 다시 작성하는 데 걸린 시간입니다.
    • search_query: 데이터 스토어 에이전트가 구성된 데이터 스토어를 대상으로 (잠재적으로 다시 작성된) 쿼리를 사용하여 검색을 실행하는 데 걸린 시간입니다.
    • summarization: Datastore에서 가져온 검색 결과로부터 간결한 자연어 대답을 생성하는 데 걸린 시간 (ReAct 턴).
    • grounding: 그라운딩 검증 프로세스에 소요된 시간입니다. 이 중요한 단계에서는 생성된 대답이 반환되기 전에 소스 문서에 의해 사실적으로 뒷받침되는지 확인합니다.
    • query_generation: 진행 중인 대화를 분석하고 관련 검색어를 사전 예방적으로 생성하는 데 걸린 시간입니다.
    • generated_query_rai: 검색에 사용되기 전에 사전 생성된 쿼리에 책임감 있는 AI (RAI) 안전성 검사를 실행하는 데 걸리는 시간입니다.
    • query_categorization: 이 기능이 구성된 경우 Agent Search를 사용하여 생성된 질문을 분류하는 데 걸린 시간입니다.

문제 해결 정보 응답 예시

다음은 JSON 응답에서 search_knowledge_debug_info 객체가 어떻게 표시될 수 있는지 보여주는 포괄적인 예입니다. 

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

선제적 생성형 지식 지원 (PGKA)

문제 해결을 통해 질문 생성, 분류, 답변 검색 프로세스에 대한 심층적인 통계를 확인할 수 있습니다. knowledge_assist_debug_info 객체는 추천 결과 내 knowledge_assist_answer의 일부입니다.

대화 프로필을 만들거나 업데이트할 때 다음과 같이 KNOWLEDGE_ASSIST 기능의 enable_response_debug_info 필드를 true로 설정합니다.

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

문제 해결 세부정보

knowledge_assist_debug_info 객체에는 사전 제안의 엔드 투 엔드 수명 주기를 이해하는 데 도움이 되는 다음 필드가 포함되어 있습니다.

쿼리를 생성할 수 없음

query_generation_failure_reason 필드에서는 대화에서 사전 대응형 검색어가 생성되지 않은 이유를 설명합니다.

  • QUERY_GENERATION_FAILED: 쿼리 생성 중에 내부 오류가 발생했습니다.
  • QUERY_GENERATION_NO_QUERY_GENERATED: 생성기가 쿼리를 생성하지 않기로 결정했습니다. 이 문제는 일반적으로 대화 주제가 변경되지 않았거나 최근에 유사한 질문이 추천된 경우에 발생합니다.
  • QUERY_GENERATION_RAI_FAILED: 책임감 있는 AI (RAI) 필터가 안전상의 이유로 잠재적인 질문을 차단했습니다.
  • NOT_IN_ALLOWLIST: 대화 프로필 또는 에이전트 수준의 필터링 규칙으로 인해 쿼리 생성이 차단되었습니다.
  • QUERY_GENERATION_QUERY_REDACTED: 생성된 질문에 수정된 민감한 정보가 포함되어 있어 생성기가 질문을 차단했습니다.
  • QUERY_GENERATION_AGENT_LANGUAGE_MISMATCH: 상담사의 언어가 고객의 언어와 일치하지 않아 질문 생성에 실패했습니다.
  • QUERY_GENERATION_TRANSLATION_LANGUAGE_MISMATCH: 번역된 메시지의 언어가 대화 프로필의 언어와 일치하지 않아 쿼리 생성이 실패했습니다.
  • QUERY_GENERATION_TRANSLATED_MESSAGE_NOT_FOUND: 생성기에 쿼리 생성을 위한 번역된 메시지가 필요했지만 찾을 수 없습니다.

질문을 분류하지 못함

query_categorization_failure_reason 필드는 쿼리 분류가 실패한 이유를 설명합니다.

  • QUERY_CATEGORIZATION_INVALID_CONFIG: 분류를 위해 제공된 에이전트 검색 구성이 잘못되었습니다(예: 검색 엔진이 비어 있음).
  • QUERY_CATEGORIZATION_RESULT_NOT_FOUND: 에이전트 검색 결과에 분류 결과가 포함되지 않았습니다.
  • QUERY_CATEGORIZATION_FAILED: 분류를 위한 에이전트 검색 호출이 실패했습니다.

Datastore 검색 상태

datastore_response_reason 필드는 쿼리가 생성된 후 데이터 스토어에 대한 검색 상태를 제공합니다.

  • NONE: 데이터 스토어에서 보고할 특정 문제 없이 요청을 처리했습니다.
  • SEARCH_OUT_OF_QUOTA: 사용량 할당량을 초과하여 Agent Assist에서 검색 작업을 차단했습니다.
  • SEARCH_EMPTY_RESULTS: 검색 결과에 Datastore의 문서가 없습니다.
  • ANSWER_GENERATION_GEN_AI_DISABLED: 프로젝트에 생성형 AI 기능이 사용 중지되어 있습니다.
  • ANSWER_GENERATION_OUT_OF_QUOTA: 사용량 할당량을 초과하여 Agent Assist에서 답변 생성을 차단했습니다.
  • ANSWER_GENERATION_ERROR: 대답 생성 중에 내부 오류가 발생했습니다.
  • ANSWER_GENERATION_NOT_ENOUGH_INFO: 검색된 문서에 답변을 생성하기에 충분한 정보가 없습니다.
  • ANSWER_GENERATION_RAI_FAILED: RAI 필터가 생성된 대답을 차단했습니다.
  • ANSWER_GENERATION_NOT_GROUNDED: 그라운딩 검증 단계에서 소스 문서가 생성된 답변을 사실상 뒷받침하지 않는 것으로 확인되어 답변이 삭제되었습니다.

활성 구성

knowledge_assist_behavior 객체는 요청에 대해 활성화된 특정 구성을 알려줍니다.

  • answer_generation_rewriter_on: 생성기가 더 나은 검색 결과를 위해 질문을 다시 작성한 경우 true, 그렇지 않은 경우 false
  • end_user_metadata_included: 생성자가 end_user_metadata를 데이터 스토어에 전달한 경우 true, 그렇지 않은 경우 false
  • return_query_only: 프로필이 생성된 검색어만 반환하도록 구성된 경우 true, 프로필이 전체 답변을 반환하는 경우 false
  • use_pubsub_delivery: 생성기가 Pub/Sub로 결과를 전송하도록 구성된 경우 true, 그렇지 않은 경우 false
  • disable_sync_delivery: 동기 응답 전송이 사용 중지된 경우 true, 동기 응답 전송이 사용 설정된 경우 false
  • previous_queries_included: 생성기가 쿼리 생성 과정에서 이전에 제안된 쿼리를 고려한 경우 true, 고려하지 않은 경우 false
  • use_translated_message: 번역된 메시지가 질문 생성에 사용된 경우 true, 그렇지 않은 경우 false
  • use_custom_safety_filter_level: 맞춤 안전 필터 수준이 적용된 경우 true 생성기에서 기본 안전 필터 수준만 사용한 경우 false

수집된 컨텍스트의 정보

ingested_context_reference_debug_info 필드는 검색을 지원하기 위해 인그레스된 컨텍스트와 관련된 디버그 정보를 제공합니다.

  • project_not_allowlisted: true 값은 프로젝트가 수집된 컨텍스트 참조 기능을 사용하기 위한 허용 목록에 없음을 의미합니다. false 값은 프로젝트가 허용 목록에 있음을 의미합니다.
  • context_reference_retrieved: 컨텍스트 참조가 데이터베이스에서 성공적으로 검색되었는지 여부를 나타냅니다.
  • ingested_parameters_debug_info: 컨텍스트 참조에서 가져온 파라미터와 해당 상태의 목록입니다. 각 매개변수에는 매개변수 이름과 다음 가능한 수집 상태 중 하나가 표시됩니다.
    • INGESTION_STATUS_SUCCEEDED: 매개변수가 성공적으로 수집되었습니다.
    • INGESTION_STATUS_CONTEXT_NOT_AVAILABLE: 파라미터를 수집할 수 없습니다.
    • INGESTION_STATUS_PARSE_FAILED: 시스템에서 매개변수의 콘텐츠를 파싱하지 못했습니다.
    • INGESTION_STATUS_INVALID_ENTRY: 컨텍스트 참조에 예상치 못한 수의 콘텐츠 항목이 있습니다 (하나만 있어야 함).
    • INGESTION_STATUS_INVALID_FORMAT: 컨텍스트 콘텐츠가 예상 형식에 없습니다.
    • INGESTION_STATUS_LANGUAGE_MISMATCH: 컨텍스트 참조의 언어가 대화의 언어와 일치하지 않습니다.

문제 해결 응답 예시

다음은 응답에서 knowledge_assist_debug_info 객체가 어떻게 표시될 수 있는지 보여주는 포괄적인 예입니다. 

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