대화 로그 스키마

이 문서에서는 BigQuery의 대화 분석 대화 로깅을 위한 테이블 레이아웃, 열, 이벤트 유형, 사용자 ID 필드, JSON 페이로드 구조를 설명합니다. 대화 로깅 작동 방식에 대한 개요는 대화 로깅 개요를 참조하세요.

테이블 레이아웃 및 자동 생성

로깅을 사용 설정하기 전에 데이터 에이전트와 동일한 프로젝트에 대상 데이터 세트를 만듭니다. Conversational Analytics API 서비스 에이전트는 첫 번째 로깅된 차례에 데이터 세트 위치에 테이블을 만들거나 누락된 스키마 열을 기존 호환 테이블에 추가합니다. 자동 생성된 테이블은 timestamp에서 일별로 파티션을 나누고(데이터 세트의 기본 파티션 만료 상속) event_type, agent, user_id에서 클러스터링됩니다. 테이블을 쿼리할 때는 항상 timestamp를 필터링합니다.

열

다음 표에서는 대화 로깅 대상 테이블의 열을 설명합니다.

열 유형 모드 목차
timestamp TIMESTAMP REQUIRED 이벤트의 UTC 시간입니다. 파티셔닝 열입니다.
event_id STRING NULLABLE 이벤트의 고유 ID입니다. 쓰기가 재시도되면 동일하게 유지되므로 중복을 삭제하는 데 사용할 수 있습니다.
event_type STRING NULLABLE 이벤트 유형입니다. 이벤트 유형을 참조하세요.
agent STRING NULLABLE 에이전트의 이름이나 ID가 아닌 에이전트 유형입니다 (예: ConversationalAnalyticsAgent). 에이전트를 구분하려면 데이터 에이전트 ID를 사용합니다(attributes 내 필드 참조).
session_id STRING NULLABLE 전체 대화가 아닌 한 차례의 대화입니다. 하나의 질문과 답변에 대한 모든 이벤트는 session_id를 공유합니다. 턴을 대화로 그룹화하려면 attributes의 대화 ID를 사용합니다.
invocation_id STRING NULLABLE 한 차례 내에서 한 번 실행됩니다.
user_id STRING NULLABLE 질문을 한 발신자입니다. 사용자 ID를 참고하세요.
trace_id STRING NULLABLE OpenTelemetry trace ID (16진수 문자 32개)입니다.
span_id STRING NULLABLE 대화의 실행 트리에 있는 이 작업의 ID입니다.
parent_span_id STRING NULLABLE 상위 작업의 ID입니다.
content JSON NULLABLE 이벤트 페이로드입니다. 형태는 event_type에 따라 달라집니다.
content_parts RECORD REPEATED 부분당 하나의 요소가 있는 여러 부분으로 구성된 콘텐츠 (예: mime_type, uri, object_ref, text, part_index, part_attributes, storage_mode)
attributes JSON NULLABLE 메타데이터: 데이터 에이전트 ID, 대화 ID, 내부 사용자 키, 모델 버전, 세부 토큰 사용량
latency_ms JSON NULLABLE 지연 시간 측정값(예: total_ms 및 time_to_first_token_ms)
status STRING NULLABLE OK 또는 ERROR.
error_message STRING NULLABLE 오류 세부정보 모델이 정상 중지 이외의 이유로 중지되는 경우 (예: 최대 토큰 한도에 도달하는 경우) OK LLM_RESPONSE 행에 설정할 수도 있습니다.
is_truncated BOOLEAN NULLABLE 이벤트의 텍스트 값이 512,000자 (500 * 1,024)를 초과하여 잘린 경우 true입니다. 컷 값은 ...[TRUNCATED]로 끝납니다. 삭제된 부분은 복구할 수 없습니다.

이벤트 유형

다음 표에서는 event_type 열에 표시될 수 있는 값과 각 이벤트의 데이터를 저장하는 열 또는 JSON 필드를 설명합니다.

event_type 값 설명 채워진 열 및 JSON 필드
INVOCATION_STARTING 회전 시작 없음
USER_MESSAGE_RECEIVED 사용자의 질문입니다. content.text_summary
AGENT_RESPONSE 에이전트의 답변(구조화된 객체)입니다. content.text_summary (일반 텍스트) 및 content.response(AGENT_RESPONSE 구조 참조)
LLM_RESPONSE 도구를 요청한 호출을 포함하여 각 모델 호출당 하나의 행입니다(확인된 쿼리에서 차례가 직접 답변되는 경우 작성되지 않음. 여기서 attributes.fast_path는 true임). 모델의 출력은 저장되지 않습니다. 토큰: content.usage.prompt, content.usage.completion, content.usage.total. 모델: attributes.model_version 종료 이유: attributes.finish_reason 자세한 사용법: attributes.usage_metadata (예: cached_content_token_count 및 thoughts_token_count)
INVOCATION_COMPLETED 턴별 지연 시간이 있는 턴의 끝입니다. content가 비어 있습니다. latency_ms.total_ms
EMBEDDING_SUGGESTION 임베딩을 활용할 수 있는 열에 대한 에이전트 소유자 추천입니다. 일부 상담사에게만 표시됩니다. content.reason, content.suggested_columns
INVOCATION_ERROR, AGENT_ERROR, LLM_ERROR 실패한 대화입니다. status은 ERROR이고 content은 NULL입니다. error_message (SQL 문 및 테이블 이름이 수정된 한 줄 요약)

사용자 ID

user_id 열에는 호출자의 이메일 주소(사용자의 이메일 주소, API 호출자가 서비스 계정으로 인증하는 경우 서비스 계정의 이메일 주소, 호출자에게 이메일 주소가 없는 경우 NULL(예: 일부 직원 ID 제휴 ID))가 포함됩니다. 내부 사용자 키도 모든 행의 attributes.session_metadata.user_id에 기록되므로 internal_user_key를 사용하여 고유 사용자를 집계할 수 있습니다(교차 에이전트 이벤트 뷰 만들기 참조).

서비스 계정을 통해 API를 호출할 때 대화를 자체 최종 사용자에게 할당하려면 애플리케이션에 사용자 매핑을 기록합니다. API는 로깅을 위한 최종 사용자 식별자를 허용하지 않습니다.

attributes 내부의 필드

다음 표에서는 attributes JSON 열에서 메타데이터 필드를 추출하는 데 사용되는 GoogleSQL 표현식을 보여줍니다.

필요한 항목 GoogleSQL 표현식
데이터 에이전트 ID JSON_VALUE(attributes, '$.session_metadata.state."data-agent-id"')
데이터 에이전트 전체 리소스 이름 JSON_VALUE(attributes, '$.adk.app_name')
대화 ID JSON_VALUE(attributes, '$.session_metadata.state."conversation-id"')
내부 사용자 키 JSON_VALUE(attributes, '$.session_metadata.user_id')
모델 버전(LLM_RESPONSE개 행) JSON_VALUE(attributes, '$.model_version')

AGENT_RESPONSE의 구조

에이전트의 대답을 일반 텍스트로 읽으려면 JSON_VALUE(content, '$.text_summary')를 사용합니다. 답변의 마크다운, 가정, 인사이트 부분과 명확한 질문을 결합합니다. AGENT_RESPONSE 행에서 content.response는 문자열이 아닌 JSON 객체이므로 JSON_VALUE(content, '$.response')는 NULL를 반환합니다.

다음 표에서는 content.response의 경로를 설명합니다.

content.response의 경로 유형 목차
parts ARRAY<JSON> 답변은 부분적으로 제공됩니다.
parts[].markdown STRING 답변 텍스트 (마크다운)입니다.
parts[].insight STRING 데이터에서 도출된 통계입니다.
parts[].assumption STRING 에이전트가 가정한 내용입니다.
parts[].data_result_artifact_name STRING 데이터 결과의 이름입니다.
parts[].chart_artifact_name STRING 차트 이름입니다.
followup_questions ARRAY<STRING> 추천 후속 질문입니다.
clarifying_question STRING 에이전트가 사용자에게 답변하는 대신 명확히 확인하기 위한 질문을 한 경우 설정합니다.
citation_sources JSON 답변에 인용된 소스입니다.

다음 단계