개발자는 geminidataanalytics.googleapis.com을 통해 액세스할 수 있는 Conversational Analytics API를 사용하여, 자연어로 BigQuery, Looker, Looker Studio의 정형 데이터에 대한 질문에 대답하는 인공지능 (AI) 기반 채팅 인터페이스 또는 데이터 에이전트를 빌드할 수 있습니다. Conversational Analytics API를 사용하면 데이터 에이전트에게 비즈니스 정보 및 데이터 (컨텍스트)와 SQL, Python, 시각화 라이브러리와 같은 도구에 대한 액세스 권한을 제공할 수 있습니다. 이러한 에이전트 응답은 사용자에게 표시되며 클라이언트 애플리케이션에서 로깅할 수 있으므로 원활하고 감사 가능한 데이터 채팅 환경을 만들 수 있습니다.
Google Cloud 를 위한 Gemini에서 사용자 데이터를 사용하는 방법과 시점을 알아보세요.
Conversational Analytics API 시작하기
Conversational Analytics API를 사용하려면 먼저 아키텍처 및 주요 개념 문서를 검토하여 에이전트가 요청을 처리하는 방식, 에이전트 생성자 및 사용자의 워크플로, 대화 모드, Identity and Access Management(IAM) 역할을 파악하세요. 그런 다음 데이터 에이전트 빌드를 시작하려면 빠른 시작, Codelab, 노트북, 에이전트 개발 키트 (ADK) 및 MCP 도구 상자를 통한 안내형 환경을 선택하거나 설정 및 사전 요구사항의 단계를 따라 자체적 접근 방식을 선택하면 됩니다.
빠른 시작
Streamlit 빠른 시작 앱을 사용하여 로컬 테스트 환경에서 Conversational Analytics API와 통합합니다.
Codelab
단계별 튜토리얼을 따라 Conversational Analytics API Codelab에서 BigQuery 데이터와 함께 Python SDK를 사용하는 방법을 알아보세요.
Notebooks
다음 Conversational Analytics API Colaboratory 노트북을 사용하여 Conversational Analytics API를 시작하는 데 도움이 되는 가이드 환경을 확인하세요.
- HTTP Colaboratory 노트북: HTTP 요청을 사용하여 환경을 설정하고, 데이터 에이전트를 빌드하고, API를 호출하는 대화형 단계별 가이드를 제공합니다.
- Python SDK Colaboratory 노트북: Python SDK를 사용하여 환경을 설정하고, 데이터 에이전트를 빌드하고, API를 호출하는 대화형 단계별 가이드를 제공합니다.
에이전트 개발 키트 (ADK) 및 MCP 도구 상자
에이전트 개발 키트 (ADK)에서 ask_data_insights 함수를 사용하여 데이터에 관한 질문에 자연어로 답변하는 방법을 알아보세요.
대화형 분석 API 기능을 보여주고 실제 통합 패턴을 제공하는 대화형 분석 데모 및 도구를 검토합니다.
설정 및 기본 요건
API 또는 예시를 사용하기 전에 다음 단계를 완료하세요.
- Conversational Analytics API 사용 설정: Conversational Analytics API를 사용 설정하기 위한 기본 요건을 설명합니다.
- IAM을 사용한 대화형 분석 API 액세스 제어: ID 및 액세스 관리를 사용하여 데이터 에이전트에 대한 액세스를 공유하고 관리하는 방법을 설명합니다.
- Conversational Analytics API로 데이터 소스 인증 및 연결: API를 인증하고 BigQuery, Looker, Looker Studio 데이터에 연결을 구성하는 방법을 설명합니다.
데이터 에이전트 빌드 및 상호작용
이전 단계를 완료한 후 다음 단계에 따라 Conversational Analytics API를 사용하여 데이터 에이전트를 빌드하고 상호작용합니다.
- HTTP를 사용한 데이터 에이전트 빌드: Python으로 직접 HTTP 요청을 사용하여 데이터 에이전트를 빌드하고 상호작용하는 완전한 예시를 제공합니다.
- Python SDK를 사용한 데이터 에이전트 빌드: Python SDK를 사용하여 데이터 에이전트를 빌드하고 상호작용하는 완전한 예시를 제공합니다.
- 작성된 컨텍스트로 에이전트 동작 안내: 작성된 컨텍스트를 제공하여 에이전트 동작을 안내하고 응답 정확도를 높이는 방법을 알아봅니다. BigQuery 데이터 소스 및 Looker 데이터 소스를 사용하여 작성된 컨텍스트의 예시를 확인할 수도 있습니다.
- 대화형 분석 API 에이전트 응답을 시각화로 렌더링: Python SDK 및 Vega-Altair 라이브러리를 사용하여 API 응답의 차트 사양을 처리하고 시각화로 렌더링하는 예시를 제공합니다.
권장사항
다음 가이드를 검토하여 Conversational Analytics API 사용에 관한 권장사항을 알아보세요.
- 에이전트의 BigQuery 비용 관리: 프로젝트 수준, 사용자 수준, 쿼리 수준 지출 한도를 설정하여 Conversational Analytics API 에이전트의 BigQuery 비용을 모니터링하고 관리하는 방법을 알아봅니다.
- 효과적인 질문하기: 에이전트가 Conversational Analytics API를 최대한 활용할 수 있도록 효과적인 질문을 만드는 방법을 알아봅니다.
- Conversational Analytics API 오류 문제 해결: 일반적인 Conversational Analytics API 오류를 해결합니다.
- 알려진 제한사항: 질문, 데이터, 시각화, 질문의 제한사항 등 Conversational Analytics API의 알려진 제한사항에 관한 세부정보를 제공합니다.
주요 API 작업
이 API는 데이터 에이전트 및 대화를 관리하기 위한 다음과 같은 핵심 엔드포인트를 제공합니다.
| 작업 | HTTP 메서드 | 엔드포인트 | 설명 |
|---|---|---|---|
| 에이전트 만들기 | POST |
/v1beta/projects/*/locations/*/dataAgents |
새 데이터 에이전트를 만듭니다. |
| 에이전트 가져오기 | GET |
/v1beta/projects/*/locations/*/dataAgents/* |
특정 데이터 에이전트의 세부정보를 가져옵니다. |
| Identity and Access Management 정책 가져오기 | POST |
/v1beta/projects/*/locations/*/dataAgents/*:getIamPolicy |
특정 데이터 에이전트의 각 사용자에게 할당된 Identity and Access Management 권한을 가져옵니다. 데이터 에이전트 소유자 역할이 있는 사용자는 이 엔드포인트를 호출하여 setIAMpolicy 엔드포인트를 사용하여 다른 사용자와 데이터 에이전트를 공유하기 전에 데이터 에이전트의 Identity and Access Management 정책을 볼 수 있습니다. |
| Identity and Access Management 정책 설정 | POST |
/v1beta/projects/*/locations/*/dataAgents/*:setIamPolicy |
특정 데이터 에이전트의 Identity and Access Management 정책을 설정합니다. 데이터 에이전트 소유자 역할이 있는 사용자는 이 엔드포인트를 호출하여 다른 사용자와 데이터 에이전트를 공유해야 합니다. 이렇게 하면 해당 사용자의 Identity and Access Management 권한이 효과적으로 업데이트됩니다. |
| 에이전트 업데이트 | PATCH |
/v1beta/projects/*/locations/*/dataAgents/* |
기존 데이터 에이전트를 수정합니다. |
| 에이전트 나열 | GET |
/v1beta/projects/*/locations/*/dataAgents |
프로젝트에서 사용 가능한 데이터 에이전트를 나열합니다. |
| 액세스 가능한 에이전트 나열 | GET |
/v1beta/projects/*/locations/*/dataAgents:listaccessible |
프로젝트에서 액세스 가능한 데이터 에이전트를 나열합니다. 이 API를 호출하는 사용자에게 에이전트에 대한 get 권한이 있는 경우 데이터 에이전트에 액세스할 수 있는 것으로 간주됩니다. creator_filter 필드를 사용하여 이 메서드에서 반환하는 에이전트를 관리할 수 있습니다.
|
| 에이전트 삭제 | DELETE |
/v1beta/projects/*/locations/*/dataAgents/* |
데이터 에이전트를 삭제합니다. |
| 대화 만들기 | POST |
/v1beta/projects/*/locations/*/conversations |
새로운 지속적 대화를 시작합니다. |
| 대화 참조를 사용하여 채팅 | POST |
/v1beta/projects/*/locations/*:chat |
기존 대화와 연결된 에이전트 컨텍스트를 참조하는 채팅 메시지를 전송하여 스테이트풀(Stateful) 대화를 계속합니다. 멀티턴 대화의 경우 Google Cloud 에서 대화 기록을 저장하고 관리합니다. |
| 데이터 에이전트 참조를 사용하여 채팅 | POST |
/v1beta/projects/*/locations/*:chat |
컨텍스트를 위해 저장된 데이터 에이전트를 참조하는 스테이트리스(Stateless) 채팅 메시지를 전송합니다. 멀티턴 대화의 경우 애플리케이션이 각 요청과 함께 대화 기록을 관리하고 제공해야 합니다. |
| 인라인 컨텍스트를 사용하여 채팅 | POST |
/v1beta/projects/*/locations/*:chat |
저장된 데이터 에이전트를 사용하지 않고 요청에 모든 컨텍스트를 직접 제공하여 스테이트리스(Stateless) 채팅 메시지를 전송합니다. 멀티턴 대화의 경우 애플리케이션이 각 요청과 함께 대화 기록을 관리하고 제공해야 합니다. |
| 대화 가져오기 | GET |
/v1beta/projects/*/locations/*/conversations/* |
특정 대화의 세부정보를 가져옵니다. |
| 대화 나열 | GET |
/v1beta/projects/*/locations/*/conversations |
특정 프로젝트의 대화를 나열합니다. |
| 대화의 메시지 나열 | GET |
/v1beta/projects/*/locations/*/conversations/*/messages |
특정 대화 내의 메시지를 나열합니다. |
| 대화 삭제 | DELETE |
/v1beta/projects/*/locations/*/conversations/* |
특정 대화를 삭제합니다. 이 엔드포인트를 호출하려면 주제 관리자 Identity and Access Management 역할 또는 최소한 cloudaicompanion.topics.delete Identity and Access Management 권한이 필요합니다.
|
의견 보내기
다음 링크를 사용하여 버그를 신고하거나 기능을 요청하세요.
추가 리소스
Conversational Analytics API REST 참조는 요청 및 응답 구조의 메서드, 엔드포인트, 유형 정의에 대한 자세한 설명을 제공합니다.