지식 지원 기능 문제 해결

생성형 기술 자료 지원 (GKA) 및 선제적 생성형 기술 자료 지원 (PGKA) 모두의 실패, 기능 사용 동작, 지연 시간에 관한 세부정보에 액세스합니다. enable_response_debug_info를 사용 설정하여 knowledge_assist_debug_info 객체 내에서 이러한 문제 해결 세부정보를 확인합니다.

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

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

생성형 기술 자료 지원 (GKA)

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 값은 시스템에서 Datastore 검색에 더 효과적이도록 사용자 쿼리를 다시 작성했음을 나타냅니다. 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: 이 기능이 구성된 경우 Vertex AI 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: 분류를 위해 제공된 Vertex AI Search 구성이 잘못되었습니다(예: 검색엔진이 비어 있음).
  • QUERY_CATEGORIZATION_RESULT_NOT_FOUND: Vertex AI Search의 결과에 분류 결과가 포함되어 있지 않습니다.
  • QUERY_CATEGORIZATION_FAILED: 분류를 위한 Vertex AI Search 호출이 실패했습니다.

Datastore 검색 상태

datastore_response_reason 필드는 쿼리가 생성된 후 Datastore에 대한 검색 상태를 제공합니다.

  • NONE: Datastore에서 보고할 특정 문제 없이 요청을 처리했습니다.
  • 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를 Datastore에 전달한 경우 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
          }
        }
      ]
    }
  }
}