이 문서에서는 데이터 에이전트 애플리케이션을 빌드하기 위해 QueryData의 정확도를 개선할 수 있는 컨텍스트를 만들고 최적화하는 방법을 설명합니다. Gemini CLI에서 DB 컨텍스트 보강 확장 프로그램을 사용하면 컨텍스트 세트의 생성 및 최적화를 자동화하는 개발자 도구 모음에 액세스할 수 있습니다.
컨텍스트 세트에 대해 알아보려면 컨텍스트 세트 개요를 참고하세요.확장 프로그램은 다음 순서로 컨텍스트 세트의 생성 및 최적화를 자동화합니다.
- 애플리케이션 이해: 데이터 에이전트의 기본 비즈니스 로직을 설정하기 위해 데이터베이스 스키마, 애플리케이션 코드, 비즈니스 요구사항과 같은 아티팩트를 수집합니다.
- 데이터 세트 만들기: 대표적인 자연어 질문과 예상되는 SQL 답변이 포함된 평가 데이터 세트를 선별합니다. 이 기준 데이터 세트를 설정하는 것은 성능을 측정하고 시간이 지남에 따라 개선사항을 추적하는 데 매우 중요합니다.
- 초기 컨텍스트 생성: 데이터베이스 스키마와 선택적 애플리케이션 아티팩트에서 직접 파생된 기준 컨텍스트 세트를 빠른 시작으로 자동 생성합니다.
- 컨텍스트를 반복적으로 최적화: 데이터 세트를 평가하여 특정 쿼리가 실패하는 이유를 파악합니다. Gemini는 자동화된 추론을 사용하여 타겟팅된 컨텍스트 업데이트를 제안하고, 이를 통해 반복적으로 정확도를 높입니다.
확장 프로그램은 강력한 자동화 워크플로를 제공하지만 필요에 따라 조정할 수 있습니다. 자동화를 우회하여 더 세부적인 수준에서 컨텍스트를 작성하고 삽입할 수 있습니다. 특수 생성 명령어를 사용하면 고품질 템플릿, 패싯, 값 검색 쿼리의 생성을 제어할 수 있습니다.
시작하기 전에
에이전트를 만들기 전에 다음 기본 요건을 완료하세요.
필수 서비스 사용 설정
프로젝트에 다음 서비스를 사용 설정합니다.Spanner 인스턴스 준비
- Spanner 인스턴스를 사용할 수 있는지 확인합니다. 자세한 내용은 인스턴스 만들기를 참고하세요.
- 테이블을 만들 인스턴스에 데이터베이스를 만들어야 합니다. 자세한 내용은 Spanner 인스턴스에서 데이터베이스 만들기를 참고하세요.
이 튜토리얼을 진행하려면 Spanner 인스턴스에 데이터베이스가 있어야 합니다. 자세한 내용은 데이터베이스 만들기를 참고하세요.
필수 역할 및 권한
- 클러스터에 IAM 사용자 또는 서비스 계정을 추가합니다. 자세한 내용은 IAM 역할 적용을 참고하세요.
- 프로젝트 수준에서 IAM 사용자에게
spanner.databaseReader및geminidataanalytics.queryDataUser역할을 부여합니다. 자세한 내용은 프로젝트의 IAM 정책 바인딩 추가를 참고하세요. - 필요한 데이터베이스에 대해 프로젝트 수준에서 IAM 사용자에게 역할과 권한을 부여합니다.
개발 환경 준비
로컬 개발 환경이나 IDE에서 컨텍스트 세트 파일을 빌드할 수 있습니다. 환경을 준비하려면 다음 단계를 완료하세요.
- Gemini CLI 설치
- DB 컨텍스트 보강 확장 프로그램 설치
- 데이터베이스 연결 설정
Gemini CLI 설치
Gemini CLI를 설치하려면 Gemini CLI 시작하기를 참고하세요.
DB 컨텍스트 보강 확장 프로그램 설치
DB 컨텍스트 보강 확장 프로그램은 구조화된 컨텍스트 세트를 생성하고 이를 반복하는 안내형 대화형 워크플로를 제공합니다.
DB 컨텍스트 보강 확장 프로그램 설치에 대한 자세한 내용은 DB 컨텍스트 보강 확장 프로그램을 참고하세요.
DB 컨텍스트 보강 확장 프로그램을 설치하려면 다음 단계를 완료하세요.
DB 컨텍스트 보강 Gemini CLI 확장 프로그램을 설치합니다.
gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment(선택사항) DB 컨텍스트 보강 확장 프로그램을 업데이트합니다.
설치된 확장 프로그램 버전을 확인하려면 다음 명령어를 실행합니다.
gemini extensions list버전이
0.5.0이상인지 확인합니다. DB 컨텍스트 보강 확장 프로그램을 업데이트하려면 다음 명령어를 실행합니다.gemini extensions update mcp-db-context-enrichmentDB 컨텍스트 보강 확장 프로그램을 업데이트하거나
GEMINI_API_KEY을 바꾸려면 다음 명령어를 실행합니다.gemini extensions config mcp-db-context-enrichment GEMINI_API_KEYGEMINI_API_KEY를 Gemini API 키로 바꿉니다.
데이터베이스 연결 설정
확장 프로그램은 스키마를 가져오고 생성된 SQL 컨텍스트의 구문을 검증할 수 있는 데이터베이스 연결이 필요합니다. 확장이 데이터베이스와 상호작용하도록 하려면 인증 사용자 인증 정보를 구성하고 데이터베이스 연결 구성을 정의하세요.
애플리케이션 기본 사용자 인증 정보 구성
애플리케이션 기본 사용자 인증 정보 (ADC)를 구성하여 다음 두 가지 주요 구성요소에 사용자 인증 정보를 제공합니다.
- 도구 상자 MCP 서버: 사용자 인증 정보를 사용하여 데이터베이스에 연결하고, 스키마를 가져오고, SQL을 실행하여 유효성을 검사합니다.
- DB 컨텍스트 보강 확장 프로그램: 사용자 인증 정보를 사용하여 Gemini API를 인증하고 호출합니다.
터미널에서 다음 명령어를 실행하여 인증합니다.
gcloud auth application-default login데이터베이스 연결 파일 구성
확장 프로그램에는 컨텍스트 생성을 위한 데이터베이스 연결이 필요하며, 이는 MCP 도구 상자에서 지원하고 구성 파일 내에 정의합니다.
구성 파일은 스키마를 가져오거나 SQL을 실행하는 데 필요한 데이터베이스 소스와 도구를 지정합니다. DB 컨텍스트 보강 확장 프로그램에는 구성을 생성하는 데 도움이 되는 사전 설치된 에이전트 기술이 함께 제공됩니다.
Gemini CLI를 시작합니다.
geminiGemini CLI에 다음을 입력하여 스킬이 활성 상태인지 확인합니다.
/skills프롬프트를 입력합니다(예:
help me set up the database connection). 이 스킬은 현재 작업 디렉터리에autoctx/tools.yaml로 구성 파일을 만드는 과정을 안내합니다.Gemini CLI에서 다음 명령어를 실행하여 도구 상자 MCP 서버에
tools.yaml구성을 적용합니다./mcp reload
데이터베이스 구성 파일을 수동으로 구성하는 방법에 대한 자세한 내용은 MCP 도구 상자 구성을 참고하세요.
자동화된 워크플로로 컨텍스트 생성
컨텍스트 엔지니어링을 통해 정확도를 개선하는 것은 일반적으로 시행착오를 거치는 수동 프로세스입니다. 개발자는 쿼리가 실패한 이유를 추측하고 수정사항을 작성한 후 수동으로 테스트하는 경우가 많습니다. Gemini CLI의 DB 컨텍스트 보강 확장 프로그램은 이 개선 프로세스를 자동화합니다. 평가 데이터 세트(정답 SQL이 포함된 질문 세트)를 사용하여 성능을 측정하고 특정 쿼리가 실패하는 이유를 파악합니다. 그러면 Gemini가 정확도를 높이기 위해 특정 컨텍스트 업데이트를 자동으로 제안합니다. 다음 단계에 따라 데이터 에이전트의 정확도를 체계적으로 개선하세요.
작업공간 초기화
초기화 명령어는 데이터베이스 연결 구성 및 실험 디렉터리를 포함하여 로컬 작업공간을 설정합니다. 이 전용 작업공간을 사용하면 모든 구성, 실험, 생성된 파일이 한곳에 정리되어 컨텍스트 최적화 노력을 더 쉽게 관리하고 추적할 수 있습니다.
- 반복 최적화 흐름의 작업공간 역할을 할 새 디렉터리를 만들고 해당 디렉터리로 이동합니다.
새 디렉터리에서 Gemini CLI를 시작합니다.
gemini초기화 명령어를 실행합니다.
/autoctx:init데이터베이스 연결이 설정되지 않은 경우 에이전트가
tools.yaml파일 생성을 안내하고 로컬state.md파일과experiments디렉터리도 초기화합니다.초기화 후 작업공간은 다음과 같이 표시됩니다.
my-workspace/ └── autoctx/ ├── tools.yaml # Database connection and tools configuration ├── state.md # Local file to track the experiment progress └── experiments/ # Dedicated directory for future experiment-specific files
데이터 세트 준비 및 확장
Gemini가 컨텍스트 세트를 체계적으로 최적화할 수 있도록 하려면 대표적인 자연어 질문과 예상되는 SQL 답변 ('골든')으로 구성된 평가 데이터 세트를 준비하여 컨텍스트 세트를 평가하세요. 고품질 평가 데이터 세트는 성능을 측정하고, 쿼리 실패를 식별하고, 시간 경과에 따른 개선사항을 추적하는 데 매우 중요합니다. 데이터 세트는 자연어 질문 (NLQ)과 데이터 애플리케이션의 타겟 사용 사례를 다루는 골든 SQL이 포함된 JSON 파일이어야 합니다.
다음은 허용되는 형식의 예입니다.
[
{
"id": "example_001",
"nlq": "What is the total revenue for the top 5 products?",
"golden_sql": "SELECT product_id, sum(net_revenue) FROM sales GROUP BY product_id ORDER BY sum(net_revenue) DESC LIMIT 5;"
}
]
Gemini CLI 확장 프로그램에는 평가 목적으로 질문의 작은 기준을 만들고 확장하는 제공된 명령어가 포함되어 있습니다.
- 작업공간 폴더로 이동합니다.
새 디렉터리에서 Gemini CLI를 시작합니다.
geminiGemini CLI에서
/autoctx:generate-dataset명령어를 실행합니다./autoctx:generate-dataset에이전트의 메시지가 표시되면 시드를 제공합니다. 시드는 더 큰 데이터 세트의 생성을 안내하는 초기 예시 또는 소규모 예시 세트입니다. 시드는 다음 중 하나일 수 있습니다.
- 작은 골든 데이터 세트 파일
- 특정 자연어-SQL (NL2SQL) 골든 페어
예를 들어 다음과 같은 NL2SQL 골든 페어를 시드로 제공할 수 있습니다.
Question: "What are the names of all airports in California?" SQL: "SELECT name FROM airports WHERE state = 'CA';"에이전트가
execute_sql도구를 사용하여 구문과 실행 유효성을 검사할 권한을 요청합니다. 이 단계는 선택사항입니다.에이전트가 시드 데이터의 변형 (다양한 필터, 동의어 등 적용)으로 데이터 세트를 확장할지 묻습니다. 이 단계는 선택사항입니다.
에이전트는
execute_sql도구를 사용하여 새로 생성된 SQL 쿼리를 데이터베이스에 대해 실행하여 구문과 실행 유효성을 확인한 후 사용자에게 제공합니다.제안을 선택적으로 수락, 수정 또는 거부합니다. 승인된 쌍은 로컬에 자동으로 저장되며 평가할 준비가 됩니다.
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md ├── golden.json # Generated dataset └── experiments/
초기 컨텍스트 세트 만들기
초기 컨텍스트 세트를 생성하면 평가 및 반복 개선을 위한 기준이 제공됩니다. 이 단계에서는 데이터베이스 스키마와 애플리케이션 아티팩트를 사용하여 비즈니스 로직을 반영하는 기본 컨텍스트를 만듭니다.
Gemini CLI 확장 프로그램에는 데이터 에이전트 애플리케이션에 관한 정보(예: 애플리케이션 코드 또는 비즈니스 요구사항에 관한 정보가 포함된 파일)와 데이터베이스 스키마를 기반으로 초기 템플릿 및 패싯을 생성하는 사전 빌드된 명령어가 포함되어 있습니다. 처음부터 기준 컨텍스트 세트를 생성하려면 다음 단계를 따르세요.
- 작업공간 폴더로 이동합니다.
새 디렉터리에서 Gemini CLI를 시작합니다.
geminiGemini CLI에서
/autoctx:bootstrap명령어를 실행합니다./autoctx:bootstrap일반적으로 에이전트로부터 다음과 같은 사항을 기대할 수 있습니다.
에이전트에서 실험 이름을 지정하라는 메시지가 표시됩니다. 실험은 데이터베이스 컨텍스트 구성의 전체 수명 주기를 캡슐화하고 기준 상태, 평가 테스트 결과, 후속 반복적 경사 오르기 개선사항을 추적하는 전용 작업공간 폴더입니다. 이 이름은 워크스페이스의 실험 폴더 아래에 생성된 모든 파일을 정리하는 데 사용됩니다. 설명적이고 기억하기 쉬운 이름을 선택하세요.
에이전트가 타겟 데이터베이스에서 스키마를 가져와 나열하고, 선택적으로 추가 리소스나 파일을 제공하라는 메시지를 표시합니다. 스키마가 복잡한 경우 에이전트에서 초기 컨텍스트 세트에 사용할 특정 스키마 또는 테이블을 선택하라는 메시지도 표시합니다. 지정하지 않으면 현재 데이터베이스 스키마에서 사용할 수 있는 모든 테이블이 가정됩니다.
생성된 컨텍스트 세트를 검토하고 필요에 따라 수정합니다. 세부 조정이 완료되면 에이전트가 작업공간 폴더 아래의 로컬 디스크에 JSON 환경설정 파일을 직접 생성합니다.
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md └── experiments/ └── my-experiment/ └── bootstrap_context.json # The generated initial context set file안내에 따라 Spanner Studio에서 컨텍스트를 업로드합니다.
컨텍스트 효과 평가
Gemini CLI 확장 프로그램에는 골든 데이터 세트를 사용하여 데이터 에이전트를 평가하는 기본 제공 명령어가 포함되어 있습니다. 이 확장 프로그램은 Evalbench와 통합되어 골드 세트에 지정된 질문으로 에이전트의 QueryData API를 쿼리한 다음 생성된 SQL과 실행 결과를 골드 SQL과 비교하여 평가를 실행합니다. 평가는 현재 컨텍스트 세트의 효과를 파악하는 데 중요합니다. 생성된 SQL을 골든 데이터 세트와 비교하면 실패한 특정 쿼리를 정확히 파악하고 컨텍스트 개선이 필요한 영역을 식별할 수 있습니다.
골든 데이터 세트를 기준으로 현재 컨텍스트의 효과를 측정하려면 다음 단계를 따르세요.
- Spanner 스튜디오의 컨텍스트를 평가를 위해 타겟 컨텍스트 세트에 업로드합니다. 평가할 컨텍스트가 업로드되지 않은 경우 이 단계는 선택사항입니다.
- 작업공간 폴더로 이동합니다.
폴더에서 Gemini CLI를 시작합니다.
geminiGemini CLI에서
/autoctx:evaluate명령어를 실행합니다./autoctx:evaluate골든 데이터 세트, 평가 구성 생성 및 평가 실행을 위한 컨텍스트 세트 ID, 지정된 출력 디렉터리의 경로를 제공합니다.
완료되면 에이전트는 실험 폴더에 평가 결과를 파일로 생성하고 평가 결과를 요약합니다.
원하는 경우 실험 폴더에 CSV 파일로 저장된 상세 평가 보고서에서 평가를 수동으로 검사할 수 있습니다.
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md ├── golden.json └── experiments/ └── my-experiment/ └── bootstrap_context.json └── eval_configs/ └── <configs_for_eval_run>/ └── eval_reports/ └── <eval_id>/ └── eval_report/ ├── configs.csv ├── evals.csv ├── scores.csv └── summary.csv
갭 분석 및 컨텍스트 최적화 실행
컨텍스트 세트를 최적화하는 중요한 단계로, Gemini CLI 확장 프로그램에는 기존 컨텍스트 세트에서 격차 분석을 실행하고 품질을 개선하기 위한 변경사항을 제안하는 기본 제공 명령어가 포함되어 있습니다. 갭 분석은 특정 질문이 실패하는 이유와 컨텍스트를 개선할 수 있는 위치를 파악하는 데 중요합니다. 이 분석을 기반으로 Gemini는 자동화된 추론을 사용하여 이러한 실패를 해결하고 쿼리 정확도를 반복적으로 개선하기 위한 타겟팅된 컨텍스트 업데이트(예: 새 템플릿 또는 상품 속성)를 제안합니다.
- 작업공간 폴더로 이동합니다.
폴더에서 Gemini CLI를 시작합니다.
geminiGemini CLI에서
/autoctx:hillclimb명령어를 실행합니다./autoctx:hillclimb에이전트는 등반에 가장 적합한 평가 결과와 기본 컨텍스트를 자동으로 식별하고 옵션이 여러 개 있는 경우 확인을 요청합니다.
평가 결과를 사용할 수 없는 경우 에이전트는 데이터 세트와 컨텍스트가 설정된 평가 실행을 요청합니다.
준비가 완료되면 에이전트는 평가 결과와 기존 컨텍스트 세트를 읽은 다음 격차 분석 보고서를 생성합니다.
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md ├── golden.json └── experiments/ └── my-experiment/ └── bootstrap_context.json └── eval_configs/ └── eval_reports/ └── hillclimb/ └── gap_analysis_v1.md에이전트는 새로운 규범적 템플릿과 패싯을 제안하여 수정사항을 공식화하고, 선택적으로
execute_sql를 통해 DB에 대해 SQL을 테스트합니다.준비가 완료되면 새로운 개선된 컨텍스트 JSON 파일이 로컬로 생성되며 기준 컨텍스트 JSON 파일은 그대로 유지됩니다.
my-workspace/ └── autoctx/ ├── tools.yaml ├── state.md ├── golden.json └── experiments/ └── my-experiment/ └── bootstrap_context.json └── eval_configs/ └── eval_reports/ └── hillclimb/ ├── gap_analysis_v1.md └── improved_context_v1.md안내에 따라 Spanner 스튜디오에서 타겟 컨텍스트 세트에 컨텍스트를 업로드하여 평가부터 시작하는 다음 반복을 준비합니다.
제한사항
자동화된 워크플로는 템플릿과 패싯의 생성 및 최적화만 지원합니다. 데이터 에이전트의 값 검색을 구성하려면 값 검색 쿼리 생성을 참고하세요.
타겟팅된 컨텍스트 생성
컨텍스트 생성에 더 맞춤설정된 접근 방식을 선호하는 경우 DB 컨텍스트 보강 확장 프로그램을 사용하여 특정 컨텍스트 요소를 수동으로 생성할 수 있습니다. 다음 명령어는 컨텍스트를 JSON 파일로 작성하는 방법을 안내하여 템플릿, 패싯, 값 검색 쿼리 생성을 세부적으로 제어할 수 있도록 합니다.
타겟팅된 템플릿 생성
특정 질문-SQL 쌍을 컨텍스트 세트에 질문 템플릿으로 추가하려면 /generate_targeted_templates 명령어를 사용합니다.
컨텍스트 세트 파일 및 쿼리 템플릿에 대한 자세한 내용은 컨텍스트 세트 개요를 참고하세요.
컨텍스트 세트에 쿼리 템플릿을 추가하려면 다음 단계를 완료하세요.
Gemini CLI에서
/generate_targeted_templates명령어를 실행합니다./generate_targeted_templates쿼리 템플릿에 추가할 자연어 쿼리를 입력합니다.
쿼리 템플릿에 해당하는 SQL 쿼리를 입력합니다.
생성된 쿼리 템플릿을 검토합니다. 쿼리 템플릿을 컨텍스트 세트 파일로 저장하거나 기존 컨텍스트 세트 파일에 추가할 수 있습니다.
컨텍스트 설정 파일(예: my-cluster-psc-primary_postgres_context_set_20251104111122.json)은 명령어를 실행한 디렉터리에 저장됩니다.
타겟팅된 패싯 생성
SQL 조건을 컨텍스트 세트 파일에 패싯으로 추가하려면 /generate_targeted_facets 명령어를 사용합니다.
컨텍스트 세트 파일 및 패싯에 관한 자세한 내용은 컨텍스트 세트 개요를 참고하세요.
컨텍스트 세트 파일에 패싯을 추가하려면 다음 단계를 완료하세요.
Gemini CLI에서
/generate_targeted_facets명령어를 실행합니다./generate_targeted_facets패싯에 추가할 자연어 인텐트를 입력합니다.
패싯에 해당하는 SQL 스니펫을 입력합니다.
생성된 패싯을 검토합니다. 패싯을 컨텍스트 세트 파일에 저장하거나 기존 컨텍스트 세트 파일에 추가할 수 있습니다.
컨텍스트 설정 파일(예: my-cluster-psc-primary_postgres_context_set_20251104111122.json)은 명령어를 실행한 디렉터리에 저장됩니다.
값 검색어 생성
개념 유형 내에서 시스템이 특정 값을 검색하고 일치시키는 방법을 지정하는 값 검색을 생성하려면 /generate_targeted_value_searches 명령어를 사용하세요.
값 색인에 대한 자세한 내용은 컨텍스트 세트 개요를 참고하세요.
값 색인을 생성하려면 다음 단계를 완료하세요.
/generate_targeted_value_searches명령어를 실행합니다./generate_targeted_value_searchesspanner를 입력하여 Spanner를 데이터베이스 엔진으로 선택합니다.다음과 같이 값 검색 구성을 입력합니다.
Table name: TABLE_NAME Column name: COLUMN_NAME Concept type: CONCEPT_TYPE Match function: MATCH_FUNCTION Description: DESCRIPTION다음을 바꿉니다.
TABLE_NAME: 개념 유형과 연결된 열이 있는 테이블입니다.COLUMN_NAME: 개념 유형과 연결된 열 이름입니다.CONCEPT_TYPE: 정의할 개념 유형입니다(예:City name).MATCH_FUNCTION: 값 검색에 사용할 일치 함수입니다. 다음 함수 중 하나를 사용할 수 있습니다.EXACT_STRING_MATCH: 두 문자열 값의 정확한 일치 여부를 확인합니다. 고유 ID, 코드, 기본 키에 적합합니다.TRIGRAM_STRING_MATCH: 정규화된 트라이그램 거리를 계산하는 퍼지 일치입니다. 사용자 검색 및 이름 수정에 가장 적합합니다.
DESCRIPTION: (선택사항) 값 검색 쿼리의 설명입니다.
필요에 따라 값 검색을 추가합니다. 추가 값 색인 추가를 건너뛰면 템플릿 기반 SQL 생성이 다음 단계로 이동합니다.
생성된 값 검색을 검토합니다. 컨텍스트 세트를 컨텍스트 세트 파일로 저장하거나 기존 컨텍스트 세트 파일에 추가할 수 있습니다.
컨텍스트 설정 파일(예: my-cluster-psc-primary_postgres_context_set_20251104111122.json)은 명령어를 실행한 디렉터리에 저장됩니다.
다음 단계
- 컨텍스트 세트에 대해 자세히 알아보세요.
- Spanner Studio에서 컨텍스트 세트를 만들거나 삭제하는 방법 알아보기
- 컨텍스트 세트를 테스트하는 방법 알아보기