대화 로깅 개요

대화 로깅을 사용하면 프로젝트의 BigQuery 테이블에 Conversational Analytics API 데이터 에이전트의 대화를 기록하여 답변 품질을 검토하고, 채택을 추적하고, 비용을 모니터링할 수 있습니다. 각 차례에서 로그는 사용자의 질문, 에이전트의 답변, 지연 시간, 모델 토큰 사용량, 에이전트, 대화, 사용자별로 차례를 그룹화하는 데 필요한 식별자를 캡처합니다. 행은 BigQuery Storage Write API(gRPC)를 통해 BigQuery 에이전트 분석 스키마를 사용하여 작성됩니다. bigqueryAgentAnalyticsEnabled 및 bigqueryAgentAnalyticsTable 필드를 설정하여 데이터 소스가 BigQuery 테이블을 참조하는 데이터 에이전트에 대해 로깅을 사용 설정할 수 있습니다. 단계는 대화 로깅 사용 설정을 참조하세요.

로깅되는 내용

기록된 각 차례는 다음 정보를 기록하는 대상 테이블에 여러 이벤트 행(이벤트)을 작성합니다.

  • 사용자의 질문입니다.

  • 에이전트의 답변: 텍스트, 인사이트, 가정, 추천 후속 질문, 인용 소스, 데이터 결과 또는 차트의 이름입니다.

  • 대화당 지연 시간

  • 각 모델 호출의 모델 토큰 사용량, 모델 버전, 종료 이유(모델이 토큰 생성을 중지한 이유)

  • 데이터 에이전트 ID 및 대화 ID(대화 참조가 있는 채팅의 경우)를 사용하여 한 테이블에서 여러 에이전트를 분석할 수 있습니다.

  • 사용자 식별자입니다. 사용자 식별자에 대한 자세한 내용은 사용자 ID를 참조하세요.

  • 상태 및 오류 세부정보

기록되지 않는 내용

대화 로깅은 다음을 기록하지 않습니다.

  • 에이전트가 실행하는 SQL 쿼리: 로그에는 최종 답변과 참조된 데이터 결과 및 차트의 이름이 포함되지만 이를 생성한 쿼리는 포함되지 않습니다. 사용자가 에이전트에게 SQL을 표시하거나 설명해 달라고 명시적으로 요청하는 경우는 예외입니다. 이 경우 SQL이 답변 텍스트에 표시될 수 있습니다.

  • 에이전트의 도구 호출: 각 모델 호출은 모델이 도구를 실행하기로 결정하는 호출을 포함하여 하나의 LLM_RESPONSE 행을 작성합니다. 행이 작성되기 전에 호출된 도구의 이름과 인수를 포함하여 모델의 출력이 삭제됩니다. 토큰 사용량, 모델 버전, 완료 사유만 유지됩니다.

  • 사용자 의견: 좋아요 또는 싫어요 의견은 기록되지 않습니다.

데이터 에이전트가 없는 스테이트리스(Stateless) API 호출과 같은 일부 대화는 전혀 로깅되지 않습니다. 지원되지 않는 대화 표시 경로에 대한 자세한 내용은 제한사항을 참조하세요.

대화 로깅 작동 방식

사용자가 대화 로깅이 사용 설정된 데이터 에이전트와 채팅하면 대화 분석은 다음 단계를 통해 각 차례를 처리합니다.

  1. 구성: 에이전트 소유자가 대화 로깅을 사용 설정하고 대화형 분석 API를 사용하여 에이전트 프로젝트에서 기존 대상 데이터 세트 및 테이블 이름을 지정합니다.

  2. 질문: 사용자가 에이전트에게 질문을 보냅니다. 자체 애플리케이션에서 대화형 분석 API를 호출하는 경우 사용자에게 알릴 책임은 개발자에게 있습니다. BigQuery Studio에서 에이전트와 채팅하는 사용자에게는 대화가 로깅된다는 알림이 표시됩니다.

  3. 개인 정보 보호 검사: 에이전트가 차례를 시작하기 전에 개인 정보 보호 검사에서 채팅 사용자의 사용자 인증 정보를 사용하여 에이전트의 지식 소스 테이블(BigQuery 데이터 소스)의 메타데이터를 읽습니다. 이 검사는 테이블에서 행 수준 보안(행 액세스 정책), 열 수준 보안(정책 태그) 또는 동적 데이터 마스킹을 사용하지 않는지 확인합니다. 검사에서 정책을 찾거나 정책이 없음을 확인할 수 없는 경우 대화는 로깅되지 않으며 에이전트는 사용자의 질문에 계속 답변합니다.

  4. 답변: 상담사가 평소와 같이 사용자에게 답변합니다.

  5. 쓰기: 프로젝트의 대화형 분석 API 서비스 에이전트(service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.)가 Storage Write API(gRPC)를 통해 대상 테이블에 로그 행을 씁니다. 첫 번째로 로깅된 대화에서 서비스 에이전트는 테이블이 아직 없으면 테이블을 만듭니다.

  6. 쿼리: 일반적으로 답변이 완료된 후 몇 초 이내에 행이 표시됩니다. 배송 기간은 보장되지 않습니다.

로깅 오류는 차례를 실패하지 않으며 개인 정보 보호 검사 및 로그 쓰기로 인해 지연 시간이 추가될 수 있습니다. 로그 데이터 세트에 대한 권한이 누락되었거나, 데이터 세트가 존재하지 않거나, 할당량이 소진되어도 채팅 요청이나 API 호출이 실패하지 않습니다. 대화형 분석은 채팅 인터페이스, API 응답 또는 Cloud Logging에서 로깅 실패를 보고하지 않습니다.

개인 정보 보호, 데이터 거버넌스, 보안

에이전트의 대화 로깅을 사용 설정할 때 최종 사용자 알림, 데이터 액세스, 암호화, 네트워크 제어, 감사 로그가 로그에 적용되는 방식을 검토하세요.

최종 사용자 알림 및 로깅된 콘텐츠

다음 공지사항 및 규칙은 대화 로깅이 기록하는 내용과 로깅된 데이터를 볼 수 있는 사용자를 제어합니다.

  • BigQuery Studio의 최종 사용자 알림: 에이전트에 대화 로깅이 사용 설정된 경우 BigQuery Studio에서 에이전트와 채팅하는 사용자에게는 대화 로깅이 사용 설정될 때마다 다음 알림이 표시됩니다. 여기에는 사용자가 첫 번째 프롬프트를 보내기 전의 새 대화 화면도 포함됩니다.

    모든 프롬프트와 대답은 BigQuery에 로깅되며 데이터 세트 권한이 있는 사용자가 액세스할 수 있습니다.

  • API 사용 시 책임: 데이터 에이전트에서 대화 로깅(트레이스 로깅)을 사용 설정하고 자체 애플리케이션 또는 통합을 통해 최종 사용자가 해당 에이전트를 사용할 수 있도록 하는 경우 Google은 해당 사용자에게 알림을 표시할 수 없습니다. 관련 법률 및 최종 사용자와의 계약에 따라 로깅된 대화에 적용되는 모든 고지, 공개 또는 동의에 대한 책임은 개발자에게 있습니다. 자세한 내용은 대화형 분석 API의 보안, 개인 정보 보호, 위험, 규정 준수를 참조하세요.

  • 로그에 포함된 내용 및 로그를 볼 수 있는 사용자: 대상 테이블은 다음 개인 정보 보호 규칙에 따라 질문 및 답변 콘텐츠를 저장합니다.

    • 전체 질문 및 답변: 답변에는 기술 자료에서 반환된 값이 포함될 수 있습니다. 로그 테이블을 읽을 수 있는 사용자는 에이전트가 사용자에게 반환한 데이터를 볼 수 있으며, 여기에는 소스 테이블에서 읽을 수 없는 데이터도 포함됩니다. 이 콘텐츠를 볼 수 있는 사용자에게만 로그 데이터 세트에 대한 읽기 액세스 권한을 부여합니다.

    • 사용자 식별자 및 쓰기 위치: user_id 열은 질문을 한 호출자를 식별하고(사용자 ID 참조) 행은 에이전트 프로젝트에서 구성한 대상에만 기록됩니다.

    • 행 수준 보안, 열 수준 보안 또는 데이터 마스킹이 있는 테이블: 에이전트의 지식 소스에서 행 수준 보안(행 액세스 정책), 열 수준 보안(정책 태그) 또는 동적 데이터 마스킹을 사용하는 경우 해당 차례는 로깅되지 않습니다. 개인 정보 보호 검사는 bigquery-public-data의 테이블을 건너뛰고 뷰 뒤에 있는 테이블이 아닌 지식 소스로 선택한 테이블과 뷰만 확인합니다.

      • 이러한 정책을 사용하는 테이블의 뷰는 검사를 통과할 수 있으므로 대화가 로깅될 수 있습니다. 로깅을 사용 설정하기 전에 뷰 뒤에 있는 테이블에서 행 액세스 정책, 정책 태그 또는 데이터 마스킹을 사용하지 않는지 확인하세요.

      • 나중에 이러한 정책 중 하나를 소스 테이블에 추가하면 이미 로깅된 행이 로그 테이블에 유지됩니다. 보관 또는 거버넌스 정책에서 해당 행을 보관하는 것을 금지하는 경우 해당 행을 삭제합니다.

액세스 제어, 암호화, 네트워크 보안

다음 설정을 사용하여 대화 로그의 보관, 액세스, 암호화, 경계 보안을 관리할 수 있습니다.

  • 로그 데이터 세트의 보관 및 액세스 제어: 대상 테이블의 보관, 데이터 세트 역할, 테이블 정책, 감사 로그를 구성합니다.

    • 보관: Google은 로그 행을 삭제하지 않습니다. 정책과 일치하는 로그 데이터 세트 또는 테이블에 파티션 만료를 설정합니다(예: 90일).

    • 최소 권한: 공유 대화형 분석 API 서비스 에이전트의 쓰기 액세스 권한이 다른 테이블에 영향을 미치지 않도록 로그 데이터 세트를 다른 데이터 세트와 별도로 유지합니다. 분석가에게 로그 데이터 세트에 대한 roles/bigquery.dataViewer을 부여하거나 승인된 뷰 또는 승인된 데이터 세트에만 액세스 권한을 부여합니다.

    • 로그 테이블의 열 수준 및 행 수준 제어: content 또는 user_id와 같은 로그 테이블 자체에 정책 태그, 데이터 마스킹 또는 행 액세스 정책을 적용할 수 있습니다. 이러한 로그 테이블 제어는 기술 자료 소스 개인 정보 보호 검사에 영향을 미치지 않습니다.

    • 감사 로깅: 데이터 에이전트 구성 변경사항 및 로그 테이블 작업이 감사 로그에 기록됩니다. 자세한 내용은 감사 작업을 참조하세요.

  • CMEK, VPC 서비스 제어, 데이터 레지던시: 다음 암호화, 경계, 위치 제어가 대화 로깅에 적용됩니다.

    • CMEK: 로그 데이터 세트에서 고객 관리 Cloud KMS 키(CMEK)를 사용하는 경우 BigQuery 암호화 서비스 계정(bq-PROJECT_NUMBER@bigquery-encryption.)에 키에 대한 roles/cloudkms.cryptoKeyEncrypterDecrypter 역할을 부여합니다. 데이터 에이전트의 CMEK는 로그 테이블이 아닌 에이전트 리소스를 암호화합니다(고객 관리 암호화 키 참조).

    • VPC 서비스 제어: 서비스 경계를 사용하는 경우 에이전트 프로젝트가 포함된 경계에 geminidataanalytics.googleapis.com 및 bigquery.googleapis.com를 모두 포함합니다. 서비스 에이전트는 Google 관리 인프라에서 로그 테이블에 쓰므로 경계가 bigquery.googleapis.com를 제한하는 경우 다음과 같은 인그레스 규칙을 추가합니다. PROJECT_NUMBER를 에이전트의 프로젝트 번호로 바꿉니다.

      - ingressFrom:
          identities:
          - serviceAccount:service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.
          sources:
          - accessLevel: "*"
        ingressTo:
          operations:
          - serviceName: bigquery.googleapis.com
            methodSelectors:
            - permission: bigquery.tables.get
            - permission: bigquery.tables.create
            - permission: bigquery.tables.update
            - permission: bigquery.tables.updateData
          resources:
          - projects/PROJECT_NUMBER
      

      자세한 내용은 VPC 서비스 제어로 경계 보안 구성을 참조하세요.

    • 데이터 레지던시: 로그 행과 자동 생성된 테이블은 리소스 위치 조직 정책(gcp.resourceLocations)이 적용되는 로그 데이터 세트의 위치에 저장됩니다.

서비스 에이전트 및 호출자 기여 분석

채팅 사용자가 아닌 대화형 분석 API 서비스 에이전트가 로그 테이블을 만들고 업데이트하며 행을 추가합니다. 이러한 작업을 수행하려면 서비스 에이전트에 로그 데이터 세트에 대한 BigQuery 데이터 편집자(roles/bigquery.dataEditor) 역할이 필요합니다.

Cloud 감사 로그가 기록하는 감사 로그 항목에서 authenticationInfo.principalEmail 필드(또는 제휴 ID의 경우 authenticationInfo.principalSubject)는 각 작업을 수행한 주 구성원을 식별합니다.

  • 테이블 생성, 스키마 업데이트, 행 추가 로깅: 서비스 에이전트 service-PROJECT_NUMBER@gcp-sa-geminidataanalytics.

  • 데이터 에이전트 구성 요청(CreateDataAgent, CreateDataAgentSync, UpdateDataAgent, UpdateDataAgentSync): API를 호출하는 사용자, 서비스 계정 또는 제휴 ID입니다. 위임된 서비스 계정 사용자 인증 정보가 적용되면 이러한 항목에 authenticationInfo.serviceAccountDelegationInfo도 포함됩니다.

감사 대상 작업

Cloud 감사 로그는 다음 서비스의 대화 로깅 구성 변경사항과 로그 테이블 작업을 기록합니다.

  • 대화형 분석 API: 다음 메서드는 geminidataanalytics.googleapis.com에서 감사 로그를 생성합니다.

    • CreateDataAgent, CreateDataAgentSync, UpdateDataAgent, UpdateDataAgentSync는 대상 프로젝트, 데이터 세트, 테이블을 포함하여 에이전트의 bigqueryAgentAnalyticsEnabled 및 bigqueryAgentAnalyticsTable 필드를 기록하는 관리자 활동 감사 로그를 생성합니다.

    • SetAgentOpsObservability는 요청의 dataSourceType, telemetryEnabled, bqaaEnabled, updateMask 필드를 기록하는 관리자 활동 감사 로그를 생성합니다.

    • RetrieveAgentOpsObservability는 geminidataanalytics.googleapis.com에 해당하는 ADMIN_READ 또는 DATA_READ 감사 로그 유형이 사용 설정된 경우 데이터 액세스 분석 감사 로그를 생성합니다.

  • BigQuery: 로그 테이블에 대한 서비스 에이전트의 작업과 로그 테이블에 대해 실행하는 쿼리는 다음 감사 로그를 생성합니다.

    • 로그 테이블 생성 및 스키마 업데이트는 bigquery.googleapis.com에서 관리자 활동 감사 로그를 생성합니다.

    • Storage Write API(gRPC)를 통한 행 추가는 TableDataChange 메타데이터(WRITE_API_APPEND_ROWS)를 포함하여 google.cloud.bigquery.storage.v1.BigQueryWrite.AppendRows 메서드에 대한 데이터 액세스 감사 로그를 생성합니다. 이러한 항목은 bigquerystorage.googleapis.com가 아닌 bigquery.googleapis.com 서비스 이름을 사용합니다. 정책 거부 감사 로그만 bigquerystorage.googleapis.com를 사용합니다.

    • 로그 테이블에 대한 쿼리는 bigquery.googleapis.com에서 JobInsertion, JobChange, TableDataRead 항목과 같은 데이터 액세스 감사 로그를 생성합니다.

자세한 내용은 대화형 분석 API 감사 로깅 및 BigQuery 감사 로그 개요를 참조하세요.

제한사항

대화 로깅에는 다음과 같은 제한사항이 있습니다.

  • BigQuery Studio 에이전트 편집기의 미리보기 창은 로깅되지 않습니다.

  • 데이터 에이전트가 없는 스테이트리스(Stateless) API 호출은 로깅되지 않습니다.

  • 특정 테이블 대신 검색 범위를 사용하거나 BigQuery 테이블을 선언하지 않는 에이전트는 로깅되지 않습니다. BigQuery 테이블 없이 BigQuery 속성 그래프만 지식 소스로 구성하는 에이전트는 로깅되지 않습니다.

  • 생성된 SQL, 도구 호출, 에이전트 개발 키트(ADK) 도구 또는 요청 이벤트(TOOL_STARTING, TOOL_COMPLETED, TOOL_ERROR, LLM_REQUEST)는 로깅되지 않습니다. 답변과 데이터 결과 및 차트의 이름만 로깅됩니다. 확인된 쿼리에서 직접 답변된 대화는 LLM_RESPONSE 행을 작성하지 않으며 실패한 확인된 쿼리 대화는 로깅되지 않습니다.

  • 좋아요 또는 싫어요 사용자 의견은 기록되지 않습니다.

  • 지식 소스에서 행 액세스 정책, 열 수준 보안(정책 태그) 또는 데이터 마스킹(열에 직접 연결된 데이터 정책 포함)을 사용하는 경우 대화가 로깅되지 않습니다. 채팅 사용자에게 테이블의 정책 메타데이터를 검사할 권한이 없거나 검사 시간이 초과되는 경우와 같이 개인 정보 보호 검사에서 이러한 정책을 확인할 수 없는 경우에도 대화가 로깅되지 않습니다. 이 검사는 뷰를 통해 그 뒤에 있는 테이블을 살펴보지 않습니다.

  • BigQuery 테이블 에이전트만 지원됩니다. Looker, 데이터 스튜디오, PostgreSQL용 AlloyDB, Spanner, Cloud SQL 데이터 소스는 지원되지 않습니다.

  • 대상 데이터 세트는 에이전트와 동일한 프로젝트에 이미 있어야 합니다.

  • 기존 테이블의 스키마 변경사항은 추가 전용입니다. 충돌하는 열 유형 또는 모드는 해당 테이블에 대한 쓰기를 중지합니다.

  • 샘플링 설정 없이 모든 적격 대화가 로깅됩니다. 대신 쿼리 시점에 샘플링합니다(검토를 위해 모든 에이전트에서 질문 및 답변 샘플링 참조).

  • agent 열에는 에이전트 표시 이름이 아닌 에이전트 유형이 포함됩니다. attributes의 데이터 에이전트 ID를 사용하세요.

  • 여러 최종 사용자에 대해 하나의 서비스 계정을 사용하는 API 호출자는 모든 행에서 해당 서비스 계정의 이메일을 보게 됩니다.

  • 512,000자(500 * 1,024)를 초과하는 텍스트 값은 서픽스 ...[TRUNCATED]로 잘리며 삭제된 부분은 복구할 수 없습니다.

  • 쓰기는 제한된 재시도로 최선을 다해 수행됩니다. 쓰기에 실패한 차례는 로깅되지 않으며 재시도로 인해 중복 행이 생성될 수 있습니다(event_id를 사용하여 중복 삭제).

  • 에이전트는 프로젝트 수준 모니터링 가능성 설정을 상속하지 않습니다.

가격 책정

대화형 분석은 대화 로깅에 대해 별도로 요금을 청구하지 않습니다. 프로젝트는 BigQuery Storage Write API(gRPC) 데이터 수집, 스토리지, 분석 쿼리에 대해 표준 BigQuery 가격을 지불합니다. BigQuery Storage Write API(gRPC) 수집에는 결제 계정당 월 2TiB의 무료 사용량이 포함되며, Storage Write API(gRPC) 사용량에 공유됩니다. timestamp에서 쿼리를 필터링하여 스캔된 바이트를 줄입니다. 사전 전환 개인 정보 보호 검사는 테이블 메타데이터를 읽고 시험 이전 쿼리를 무료로 실행합니다.

다음 단계