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

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

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

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

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

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

인증 및 권한 오류는 어떻게 처리하나요?

다음은 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. 오류: 사용자 역할이 있는 Looker 사용자가 데이터 에이전트와 채팅하려고 하면 500 Internal Server Error 오류가 발생합니다.

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

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

  1. Google Cloud IAM 역할:

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

  2. Looker 권한 및 역할:

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

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

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

Looker Studio Pro에서 Conversational Analytics API를 사용하려면 Pro 구독이 VPC-SC 경계 외부에 있어야 합니다.

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에서 작성된 컨텍스트로 에이전트 동작 안내 문서 페이지를 참조하세요.
  • 데이터 에이전트를 만들 때 시스템 요청 사항을 제공할 수 있습니다. 시스템 요청 사항은 데이터 에이전트의 동작을 형성할 수 있는 사용자 정의 안내입니다. 이 안내에는 비즈니스별 로직, 대답 형식 또는 데이터 프레젠테이션이 포함됩니다. 올바른 SQL 또는 Looker 쿼리와 페어링된 샘플 자연어 질문인 '표준 쿼리'를 제공할 수도 있습니다. 시스템 요청 사항에 관한 자세한 내용은 작성된 컨텍스트로 에이전트 동작 안내 문서 페이지를 참조하세요.

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

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 Explore
  • Looker Studio

BigQuery를 통해 SAP 및 Salesforce와 같은 소스에 연결하고 Looker Studio를 통해 CSV 및 Google Sheets에 연결할 수도 있습니다.

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

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

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

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

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

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

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

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