Conversational Analytics API에 관한 자주 묻는 질문(FAQ)

Conversational Analytics API가 내 데이터를 변경하거나 삭제할 수 있나요?

Conversational Analytics API는 데이터 변경 또는 삭제를 방지하기 위한 보호 장치를 사용하여 설계되었습니다.

다음은 다양한 데이터 소스에 대한 데이터 보안 처리 방식입니다.

  • BigQuery: API가 데이터 정의 언어(DDL) 및 DML 문을 차단합니다. 특히 시스템은 생성된 SQL에 대해 테스트 실행을 수행하고 SELECT 유형 쿼리만 허용합니다.
  • Looker: API가 선택, 필터, 한도와 같은 읽기 작업으로 제한되는 run_inline_query와 같은 메서드를 사용하여 Looker와 상호작용합니다. 이러한 메서드는 DDL 또는 DML 작업을 지원하지 않으며 삭제 작업이 포함되지 않습니다.
  • 데이터 스튜디오 (CSV 및 Google Sheets용): 데이터 스튜디오는 구조화된 형식을 사용하여 시각화 및 보고서를 위한 데이터를 정의하고 가져옵니다. 이 메서드로 실행되는 쿼리는 읽기 전용이며 데이터 변경을 지원하지 않습니다.
  • 데이터베이스: 시스템은 SELECT 유형 쿼리만 허용합니다. 데이터 변경 또는 삭제를 방지하려면 Conversational Analytics API와 상호작용하는 서비스 계정 또는 사용자에게 데이터베이스에 대한 읽기 전용 권한이 있는지 확인하세요.

Conversational Analytics API는 이러한 데이터 소스에서 읽기 전용으로 설계되었습니다. Conversational Analytics API의 보안에 대한 자세한 내용은 자신감 있는 채팅: Looker 대화형 분석의 보안 이해 블로그 게시물을 참고하세요.

인증 및 권한 오류를 처리하려면 어떻게 해야 하나요?

다음은 Conversational Analytics API를 사용할 때 발생할 수 있는 일반적인 인증 및 권한 오류입니다.

  1. 오류: PERMISSION_DENIED 또는 403 Write access to project ... was denied

    • 가능한 원인: 이 메시지는 Google Cloud IAM 역할에 문제가 있음을 나타내는 경우가 많습니다. API를 사용하려는 사용자 또는 서비스 계정에 Google Cloud 프로젝트에 대한 필요한 권한이 없습니다.
    • 문제 해결:
      • Google Cloud 프로젝트 소유자가 Google Cloud 프로젝트에서 올바른 IAM 역할이 사용자 또는 서비스 계정에 할당되어 있는지 확인해야 합니다. API 사용 설정 또는 함수 테스트와 같은 특정 작업에는 Project Editor와 같은 역할이 필요할 수 있습니다.
      • 리전을 전환할 때 Write access to project 'us-gcp-project-name' was denied와 같은 403 오류가 발생하면 프로젝트의 IAM 구성을 확인하세요.

  2. 오류: 500 Internal Server Error 역할이 있는 Looker 사용자가 데이터 에이전트와 채팅하려고 할 때

응답을 스트리밍할 때 503 또는 500 오류가 표시되는 이유는 무엇인가요?

기본 HTTP 또는 REST 클라이언트 (예: Python requests 라이브러리)를 사용하여 스트리밍 :chat 엔드포인트를 호출하면 API가 503 Connection reset by peer 또는 500 Internal error와 같은 일반 오류 메시지를 반환할 수 있습니다.

이러한 일반 오류는 스트림이 열리자마자 스트리밍 API가 HTTP 200 OK 헤더를 전송하기 때문에 발생합니다. 데이터 에이전트가 스트림 중에 치명적인 오류 (예: 장기 실행 쿼리의 제한 시간 또는 갑작스러운 권한 거부)를 발견하면 스트림을 종료하고 HTTP/2 트레일러에 특정 오류 코드를 포함합니다. 표준 HTTP 또는 REST 클라이언트는 이러한 후행 헤더를 파싱할 수 없으며 대신 갑작스러운 종료를 소켓 장애로 해석합니다.

스트림 중에 발생하는 오류를 처리하려면 Python SDK와 같은 공식 Google Cloud 클라이언트 라이브러리 (SDK)를 사용하는 것이 좋습니다. 이러한 gRPC 기반 SDK는 일반 네트워크 오류 대신 HTTP/2 트레일러를 파싱하고 특정 오류 코드(예: DEADLINE_EXCEEDED 또는 PERMISSION_DENIED)를 반환합니다.

Conversational Analytics API를 사용하기 위한 Looker 요구사항은 무엇인가요?

Conversational Analytics API를 사용하려면 데이터 소스와 수행하려는 작업에 따라 Google Cloud IAM과 Looker 모두에서 적절한 권한이 필요합니다.

  1. Google Cloud IAM 역할:

    • geminidataanalytics.googleapis.com API와 상호작용하려면 프로젝트에 충분한 IAM 역할이 있어야 합니다. Google Cloud 잘못 구성된 IAM 역할은 PERMISSION_DENIED 오류로 이어지는 경우가 많습니다.
    • 필요한 특정 역할은 작업에 따라 다를 수 있지만 특정 작업에는 프로젝트 편집자 와 같은 일반 역할이 필요할 수 있습니다.

  2. Looker 권한 및 역할:

    • 모델 수준 권한: 대화형 분석 및 Conversational Analytics API를 사용하려면 Looker 사용자에게 상호작용하는 모델에 대한 gemini_in_looker 권한이 포함된 Looker 역할이 할당되어야 합니다.

Conversational Analytics API를 사용하는 데 필요한 권한 및 역할에 대해 자세히 알아보려면 Conversational Analytics API IAM 역할 및 권한 부여 문서 페이지를 참조하세요.

또한 Looker 인스턴스는 특정 요구사항을 충족해야 합니다.

데이터 스튜디오 Pro에서 Conversational Analytics API를 사용하려면 Pro 구독이 VPC-SC 경계 외부에 있어야 합니다.

Conversational Analytics API를 사용하기 위한 데이터베이스 요구사항은 무엇인가요?

PostgreSQL용 AlloyDB, Spanner용 GoogleSQL, MySQL용 Cloud SQL, PostgreSQL용 Cloud SQL과 같은 데이터베이스에서 Conversational Analytics API를 사용하려면 적절한 IAM 인증 및 사용 설정을 확인해야 합니다.

  1. Google Cloud **IAM 역할**:

    • 서비스 계정 또는 사용자에게 특정 데이터베이스에 연결하고 쿼리하는 데 필요한 IAM 역할이 있어야 합니다. 일반적으로 데이터베이스에 대한 읽기 액세스 권한이 있는 역할이 포함됩니다.

  2. API 사용 설정:

    • 프로젝트에서 Cloud AI Companion API가 사용 설정되어 있는지 확인합니다. Google Cloud

IAM 인증을 사용 설정하는 방법에 대한 자세한 내용은 각 데이터베이스의 문서를 참고하세요.

Data QnA API에서 Conversational Analytics API로 마이그레이션하려면 어떻게 해야 하나요?

이전 시험용 버전의 Data QnA API(dataqna.googleapis.com)를 사용한 경우 마이그레이션 가이드에서 Conversational Analytics API(geminidataanalytics.googleapis.com)의 새 공식 엔드포인트로 마이그레이션하는 방법을 참조하세요.

데이터 에이전트의 이름과 ID는 어떻게 다른가요?

data_agent_id의 값으로 정의되는 데이터 에이전트의 ID는 데이터 에이전트의 고유 식별자입니다. 데이터 에이전트의 이름인 data_agent.name은 data_agent_id에서 정규화된 이름(FQN)으로 자동 파생되며 projects/<project>/locations/<location>/dataAgents/<data_agent_id> 형식을 취합니다.

데이터 에이전트를 만들 때 data_agent.name에 입력한 값은 무시됩니다. get, update 또는 delete 작업을 실행할 때 전체 data_agent.name이 데이터 에이전트의 고유 식별자로 처리됩니다.

Conversational Analytics API를 사용하여 데이터 에이전트를 만들 때 다음 시나리오가 적용됩니다.

  • data_agent_id를 정의하지 않으면 고유 ID가 자동으로 생성됩니다.
  • data_agent_id를 TestID 등으로 정의하면 data_agent.name에 입력한 값이 projects/<project>/locations/<location>/dataAgents/TestID로 덮어쓰여집니다.
  • FQN으로 data_agent_id를 정의하면 '잘못된 형식의 이름' 오류가 반환됩니다.

에이전트 만들기 또는 대화 만들기에서 허용되는 ID 형식은 무엇인가요?

데이터 에이전트의 경우:

projects/{project}/locations/{location}/dataAgents/{data_agent_id}

{data_agent}는 리소스 ID입니다. 63자(영문 기준) 이하여야 하고 https://google.aip.dev/122#resource-id-segments에 설명된 형식과 일치해야 합니다.

예: projects/1234567890/locations/us-central1/dataAgents/my-agent

이 필드는 자동으로 추론되고 {parent}/dataAgents/{data_agent_id}로 덮어쓰이므로 에이전트 생성 중에 이 필드를 설정하지 않는 것이 좋습니다.

대화의 경우:

projects/{project}/locations/{location}/conversations/{conversation_id}

{conversation_id}는 리소스 ID이며 63자(영문 기준) 이하여야 하고 https://google.aip.dev/122#resource-id-segments에 설명된 형식과 일치해야 합니다.

예: projects/1234567890/locations/us-central1/conversations/my-conversation

이 필드는 대화형 분석에서 자동으로 식별한 후 {parent}/conversations/{conversation_id}로 덮어쓰므로 대화 생성 중에 설정하지 않는 것이 좋습니다.

업데이트 마스크를 사용하려면 어떻게 해야 하나요?

데이터 에이전트 업데이트 흐름에서 updateMask 파라미터는 업데이트로 dataAgent 리소스에서 덮어쓸 dataAgent 필드를 지정하는 FieldMask 형식 문자열을 사용합니다. updateMask 파라미터는 필수 필드이며 다음과 같이 검증됩니다.

  • updateMask가 비어 있으면 BadRequestException이 발생하고 필드가 업데이트되지 않습니다.
  • updateMask의 모든 필드가 유효한 dataAgent 필드인 경우 해당 필드만 업데이트됩니다.
  • 유효한 필드와 잘못된 필드가 혼합되어 제공되면 잘못된 필드는 무시되고 유효한 필드만 업데이트됩니다.

getIAMPolicy 및 setIAMPolicy를 사용하여 데이터 에이전트에 대한 IAM 정책을 설정하려면 어떻게 해야 하나요?

getIamPolicy 메서드와 setIamPolicy 메서드를 사용하여 특정 에이전트의 사용자에게 IAM 역할을 할당할 수 있습니다.

다음 코드 샘플은 데이터 에이전트에 대한 IAM 정책을 가져오는 방법을 보여줍니다.

다음 코드 샘플은 데이터 에이전트에 IAM을 할당하는 방법을 보여줍니다.

Conversational Analytics API 데이터 에이전트의 메모리 기능은 무엇인가요?

  • 단일 세션 내: Conversational Analytics API는 멀티턴 대화를 지원하므로 현재 대화의 이전 부분을 참조할 수 있습니다.
  • 여러 세션 전반: Conversational Analytics API에는 관리형 대화 기록 기능이 포함되어 있어 사용자가 여러 세션에 걸쳐 채팅할 수 있습니다. 또한 Google 관리형 멀티턴 대화가 포함된 스테이트풀(Stateful) 에이전트도 지원합니다.
  • 장기 메모리: Conversational Analytics API 데이터 에이전트는 명시적인 장기 메모리 기능을 지원하지 않습니다.

Conversational Analytics API 데이터 에이전트는 같은 질문을 하면 항상 동일한 답변을 제공하나요?

  • Conversational Analytics API 데이터 에이전트의 자연어 응답은 결정론적이지 않으므로 동일한 표현으로 질문해도 에이전트가 다른 자연어 답변을 제공할 수 있습니다.
  • 데이터 쿼리 응답: 하지만 특정 데이터 검색 질문의 경우 기본적으로 생성된 쿼리(SQL 또는 Looker 쿼리)는 결정론적이어야 합니다. 기본 데이터가 변경되지 않았다고 가정하면 가져온 데이터가 동일해야 합니다.

Conversational Analytics API 데이터 에이전트의 응답 정확성을 개선하려면 어떻게 해야 하나요?

데이터 에이전트 응답의 정확성을 개선하는 한 가지 방법은 데이터 에이전트에 강력한 컨텍스트 정보를 제공하는 것입니다. 다음과 같은 방법으로 컨텍스트를 추가할 수 있습니다.

  • Looker의 시맨틱 계층에서 LookML 정의 내에 컨텍스트를 제공할 수 있습니다. 자세한 내용과 예시는 Looker에서 작성된 컨텍스트로 에이전트 동작 안내 문서 페이지를 참조하세요.
  • PostgreSQL용 AlloyDB, MySQL용 Cloud SQL, PostgreSQL용 Cloud SQL, Spanner 데이터 소스에서 데이터 및 데이터 해석 방법에 대한 안내로 테이블, 열, 스키마 설명, 제약 조건을 추가하여 컨텍스트를 제공할 수 있습니다.

  • 데이터 에이전트를 만들 때 시스템 요청 사항, 확인된 쿼리, 고급 컨텍스트를 제공할 수 있습니다.

    • 시스템 요청 사항은 데이터 에이전트의 동작을 형성할 수 있는 사용자 정의 안내입니다. 이 안내에는 비즈니스별 로직, 응답 형식 지정 또는 데이터 프레젠테이션이 포함됩니다.
    • 올바른 SQL 또는 Looker 쿼리와 페어링된 샘플 자연어 질문인 확인된 쿼리 (데이터 소스에 따라 표준 쿼리 라고도 함)를 제공할 수 있습니다.
    • PostgreSQL용 AlloyDB, MySQL용 Cloud SQL, PostgreSQL용 Cloud SQL, Spanner 데이터 소스의 경우 에이전트의 데이터 이해 및 정확성을 최적화하는 데 도움이 되는 고급 컨텍스트를 제공할 수 있습니다.

    자세한 내용은 작성된 컨텍스트로 에이전트 동작 안내를 참고하세요.

더 효과적이고 정확한 답변을 얻기 위한 질문 방법을 알아보려면 효과적으로 질문하기 페이지를 참조하세요.

에이전트가 생성한 Python 코드를 안전하게 검사하고 처리하려면 어떻게 해야 하나요?

Python으로 고급 분석을 사용 설정한 경우 데이터 에이전트가 Python 코드를 반환할 수 있습니다. 데이터 에이전트가 반환하는 Python 코드는 안전한 Google 관리형 샌드박스 내에서 실행되도록 설계되었습니다. 로컬 또는 기타 확인되지 않은 환경에서 이 코드를 실행하면 샌드박스의 보안 보호를 우회하고 악성 코드 실행과 같은 보안 위험에 시스템이 노출될 수 있습니다.

에이전트가 생성한 Python 코드를 안전하게 검사하고 처리하려면 다음 가이드라인을 따르세요.

  • 생성된 코드를 실행하기 전에 수동으로 검사합니다. 예상치 못한 네트워크 요청 (예: socket, requests 또는 urllib), 시스템 수준 명령어 (예: os.system 또는 subprocess), 심하게 난독화된 문자열 리터럴 및 변수와 같은 의심스러운 패턴을 찾습니다.
  • 확인되지 않은 코드를 로컬 머신 또는 프로덕션 환경 내에서 직접 실행하지 마세요. 민감한 사용자 인증 정보, 내부 네트워크 또는 로컬 파일 시스템에 액세스할 수 없는 안전한 격리된 샌드박스(예: Colaboratory 노트북, 임시 Docker 컨테이너 또는 가상 머신)를 사용합니다.
  • 가능한 경우 코드를 실행하기 전에 코드에서 정적 분석 도구 또는 린터를 실행하여 잠재적으로 안전하지 않은 작업 또는 알려진 악성 패턴에 플래그를 지정해야 합니다.

Conversational Analytics API를 서드 파티 애플리케이션과 통합할 수 있나요?

Conversational Analytics API를 서드 파티 애플리케이션과 통합하면 사용자가 일상적으로 사용하는 도구 내에서 직접 데이터와 상호작용할 수 있습니다.

geminidataanalytics.googleapis.com API 엔드포인트와 상호작용하는 서드 파티 애플리케이션은 애플리케이션에서 에이전트로 사용자 메시지를 전송하고 응답을 표시할 수 있어야 합니다.

통합을 빌드하려면 대화형 분석 빠른 시작 저장소에서 예시 또는 라이브러리를 참조하세요. Google 개발자 포럼을 방문하여 다른 사용자의 예시를 검색할 수도 있습니다.

Conversational Analytics API 비용은 얼마인가요?

Conversational Analytics API는 프리뷰 단계에 있으며 Google에서는 프리뷰 제품에 요금을 청구하지 않습니다. 향후 가격이 변경되면 사전 알림을 제공해 드립니다.

Conversational Analytics API는 어떤 데이터 소스를 지원하나요?

Conversational Analytics API는 다음 데이터 소스를 지원합니다.

  • BigQuery
  • Looker 탐색
  • 데이터 스튜디오
  • PostgreSQL용 AlloyDB
  • Spanner용 GoogleSQL
  • Cloud SQL 및 PostgreSQL용 Cloud SQL

BigQuery를 통해 SAP 및 Salesforce와 같은 소스에 연결하고 데이터 스튜디오를 통해 CSV 및 Google Sheets에 연결할 수도 있습니다.

Conversational Analytics API의 알려진 제한사항은 무엇인가요?

Conversational Analytics API의 알려진 제한사항에 대해 자세히 알아보려면 Conversational Analytics API 알려진 제한사항 문서 페이지를 참조하세요.

Google Cloud 프로젝트와 관련해 알아야 할 할당량이 있나요?

Google Cloud 프로젝트 선택 또는 위치에 대한 제한은 없습니다. 데이터 에이전트를 만들어 모든 프로젝트 또는 리전에 속한 지원되는 데이터 소스를 쿼리할 수 있습니다.

Conversational Analytics API는 데이터 리전화를 지원하나요?

Conversational Analytics API는 아직 데이터 저장 위치 (DRZ)를 지원하지 않으므로 특정 지리적 리전에서 에이전트를 호스팅할 수 없습니다. 데이터 리전화는 지원되지 않습니다.

Conversational Analytics API는 영어 이외의 언어를 지원하나요?

Conversational Analytics API에서 공식적으로 지원되는 유일한 언어는 영어 입니다. 기본 Gemini 모델은 여러 언어를 지원하며 일부 사용자가 영어 이외의 쿼리에 성공했다는 입증되지 않은 사례가 보고되었지만, Conversational Analytics API는 공식적으로 영어 이외의 언어를 지원하지 않습니다.