컨텍스트 엔지니어링 에이전트를 사용하여 컨텍스트 세트 빌드 및 최적화

미리보기

이 기능에는 서비스별 약관의 일반 서비스 약관 섹션에 있는 'GA 이전 제품 또는 서비스 약관'과 생성형 AI 프리뷰 제품 추가 약관이 적용됩니다. GA 이전 기능은 '있는 그대로' 제공되며 지원이 제한될 수 있습니다. 자세한 내용은 출시 단계 설명을 참조하세요.

데이터 에이전트 애플리케이션에서 높은 QueryData 쿼리 정확성과 짧은 온라인 지연 시간을 달성하려면 컨텍스트 엔지니어링 에이전트를 사용하여 컨텍스트 세트를 빌드, 평가, 최적화하면 됩니다. 이 에이전트는 컨텍스트 생성, 업로드, 최적화를 자동화하여 애플리케이션이 자연어 질문에 빠르고 결정론적이며 설명 가능한 답변을 반환하도록 도와줍니다.

컨텍스트 세트 및 QueryData에 대한 자세한 내용은 컨텍스트 세트 개요 및 QueryData 개요를 참조하세요.

비즈니스 애플리케이션에 맞춤설정된 컨텍스트를 QueryData에 제공하면 시스템이 미묘한 사용자 의도를 해결하고 100% 에 가까운 쿼리 품질을 제공하는 데 필요한 정확한 비즈니스 규칙을 제공할 수 있습니다. CLI 또는 IDE에서 작업할 때 컨텍스트 엔지니어링 에이전트는 버전 제어를 위해 작업공간에 로컬 파일을 저장하면서 컨텍스트 세트를 Google Cloud 에 자동으로 업로드합니다.

컨텍스트 엔지니어링 에이전트

컨텍스트 엔지니어링 에이전트는 CLI 또는 IDE에서 직접 설계 시간 어시스턴트 역할을 합니다. 수동 컨텍스트 작성은 상세한 쿼리 패턴을 직접 작성하고, 모든 표현 변형을 예측하고, 반복 전반에 걸쳐 쿼리 실패를 수동으로 진단해야 합니다. 컨텍스트 엔지니어링 에이전트는 기준 컨텍스트를 부트스트랩하고, 정답 평가 데이터 세트를 선별하고, 정확성 격차를 해결하기 위해 반복적으로 힐 클라이밍을 수행하고, 컨텍스트가 새로운 질문에 걸쳐 일반화됨을 증명함으로써 이러한 오버헤드를 제거합니다.

자연어를 사용하여 에이전트와 대화하여 최적화 워크플로를 진행합니다. "내 애플리케이션 요구사항에 맞게 컨텍스트 세트를 최적화해 줘"와 같은 프롬프트로 시작합니다.

시작하기 전에

컨텍스트 엔지니어링 에이전트를 사용하기 전에 다음 섹션의 기본 요건을 완료하세요. 데이터베이스 인스턴스가 다른 리전에 있더라도 us-central1, us-east1, europe-west4, asia-southeast1 리전에서 컨텍스트 세트를 만들고 저장할 수 있습니다.

필수 서비스 사용 설정

프로젝트에 다음 서비스를 사용 설정합니다.

• Gemini 기반 Data Analytics API
• Gemini for Google Cloud API
• Knowledge Catalog API

데이터베이스 준비

PostgreSQL용 AlloyDB 인스턴스를 준비하고 에이전트의 액세스를 구성합니다.

• AlloyDB 클러스터 및 인스턴스를 만들고 데이터베이스를 만들거나 기존 인스턴스 및 데이터베이스를 사용합니다.
• AlloyDB 인스턴스에서 Data API 액세스를 사용 설정합니다. 비공개 IP를 사용하는 경우 에이전트가 스키마를 검사하고 쿼리를 검증할 수 있도록 기본 인스턴스에서 Data API 액세스(dataApiAccess) 필드를 ENABLED로 설정합니다. Data API 액세스가 사용 설정되지 않은 상태로 생성된 인스턴스의 경우 Data API 액세스 사용 설정을 참조하거나 Google Cloud 콘솔에서 구성하세요.

필수 역할 및 권한

컨텍스트 엔지니어링 에이전트를 사용하고 컨텍스트 세트를 관리하는 데 필요한 권한을 얻으려면 다음 Identity and Access Management(IAM) 역할 및 데이터베이스 권한을 구성하세요.

• 클러스터에 IAM 사용자 또는 서비스 계정을 추가합니다. 자세한 내용은 IAM 인증 관리를 참조하세요.
• 프로젝트 수준에서 IAM 사용자 또는 서비스 계정에 roles/alloydb.databaseUser, roles/serviceusage.serviceUsageConsumer, roles/geminidataanalytics.queryDataUser, roles/mcp.toolUser 역할을 부여합니다. 자세한 내용은 프로젝트에 IAM 정책 바인딩 추가를 참조하세요.
• 컨텍스트 세트를 만들고, 업로드하고, 관리하려면 프로젝트 수준에서 IAM 사용자 또는 서비스 계정에 Dataplex 카탈로그 편집자(roles/dataplex.catalogEditor) 또는 Dataplex 카탈로그 관리자(roles/dataplex.catalogAdmin) 역할을 부여합니다. 자세한 내용은 컨텍스트 세트 권한을 참조하세요.
• 시맨틱 값 검색(google_ml.embedding)을 사용하는 경우 Vertex AI API를 사용 설정하고 AlloyDB 클러스터의 서비스 계정에 roles/aiplatform.user 역할을 부여합니다.

• postgres 사용자와 같은 수퍼유저 권한이 있는 사용자로 로그인하여 IAM 사용자 또는 서비스 계정에 읽기 전용 데이터베이스 권한을 부여합니다.

  GRANT SELECT ON ALL TABLES IN SCHEMA public TO "USER_NAME";
  

  USER_NAME을 사용자의 이메일 주소로 바꿉니다(서비스 계정의 경우 . 서픽스 생략). 테이블이 public 이외의 커스텀 스키마에 있는 경우 GRANT USAGE ON SCHEMA SCHEMA_NAME TO "USER_NAME"; 및 GRANT SELECT ON ALL TABLES IN SCHEMA SCHEMA_NAME TO "USER_NAME";도 실행합니다. 자세한 내용은 IAM 사용자에게 데이터베이스 권한 부여를 참조하세요.

개발 환경 준비

로컬 개발 환경 또는 IDE에서 컨텍스트 세트를 빌드하고 최적화할 수 있습니다.

uv 설치

컨텍스트 엔지니어링 에이전트가 기본 Python 패키지를 관리하려면 uv가 필요합니다.

1. uv 설치의 안내에 따라 uv를 설치합니다.

2. uv이 설치되어 있고 명령줄에서 액세스할 수 있는지 확인합니다.

   uv --version

컨텍스트 엔지니어링 에이전트 설치

원하는 개발 환경에 컨텍스트 엔지니어링 에이전트 플러그인을 설치합니다.

Antigravity CLI

1. Antigravity CLI를 설치합니다. Antigravity CLI 시작하기를 참고하세요.
2. 컨텍스트 엔지니어링 에이전트 플러그인을 설치합니다.

   agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin

3. Antigravity CLI를 시작합니다.

   agy

나중에 플러그인을 업데이트하려면 agy plugin uninstall db-context-engineering 다음에 agy plugin install https://github.com/GoogleCloudPlatform/db-context-enrichment/tree/main/plugin를 실행합니다.

Claude Code

1. 플러그인 마켓플레이스를 추가합니다.

   /plugin marketplace add https://github.com/GoogleCloudPlatform/db-context-enrichment.git

2. 플러그인 설치:

   /plugin install db-context-engineering@db-context-enrichment-marketplace

3. 플러그인을 새로고침하여 변경사항을 활성화합니다.

   /reload-plugins

나중에 플러그인을 업데이트하려면 /plugin update db-context-engineering@db-context-enrichment-marketplace를 실행합니다.

Gemini CLI(지원 중단됨)

참고: Gemini CLI 지원은 지원 중단되었습니다. Gemini CLI를 사용하는 경우 Antigravity CLI로 마이그레이션하세요. 자세한 내용은 Gemini CLI에서 마이그레이션을 참조하세요.

1. Gemini CLI를 설치합니다. Gemini CLI 시작하기를 참고하세요.
2. 확장 프로그램을 설치합니다.

   gemini extensions install https://github.com/GoogleCloudPlatform/db-context-enrichment

나중에 확장 프로그램을 업데이트하려면 gemini extensions update google-cloud-db-context-engineering를 실행합니다.

Google Cloud로 인증

1. 개발 환경을 인증하도록 애플리케이션 기본 사용자 인증 정보(ADC)를 구성합니다.

   gcloud auth application-default login

2. 모델 컨텍스트 프로토콜(MCP) 도구에서 Google Cloud 프로젝트를 사용할 수 있도록 사용자 인증 정보의 할당량 프로젝트를 설정합니다.

   gcloud auth application-default set-quota-project PROJECT_ID

   PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.

데이터베이스에 연결

1. 에이전트 환경을 시작하고 에이전트에게 데이터베이스 연결을 설정하도록 요청합니다(예: '데이터베이스 연결 설정을 도와줘'). 에이전트는 스키마를 읽고 SQL을 검증할 수 있도록 .context-engineering/tools.yaml 구성 파일을 만드는 과정을 안내합니다. (.context-engineering/tools.yaml가 생성되기 전에 시작 시 초기 toolbox MCP 서버 연결 경고가 표시될 수 있습니다.)

2. MCP 서버 연결을 새로고침하여 .context-engineering/tools.yaml 구성을 적용합니다.

   • Antigravity CLI: /mcp를 실행하고 toolbox(또는 db-context-engineering_toolbox)를 선택하여 다시 시작합니다.
   • Claude Code: /mcp를 실행하고 toolbox를 선택한 다음 Reconnect를 선택합니다.
   • Gemini CLI: /mcp refresh(또는 /mcp reload)를 실행합니다.

컨텍스트 빌드 및 최적화

컨텍스트 엔지니어링 에이전트는 초기 부트스트랩부터 검증된 일반화 가능성에 이르기까지 엔드 투 엔드 수명 주기를 통해 컨텍스트 세트를 안내합니다.

기준 컨텍스트 세트 부트스트랩

빈 페이지에서 컨텍스트를 만들지 않도록 에이전트는 데이터베이스 스키마와 함께 비즈니스 요구사항, 문서, 샘플 SQL 쿼리와 같은 사용 가능한 애플리케이션 아티팩트를 검사합니다. 에이전트는 데이터베이스 모델을 기반으로 하는 기본 쿼리 템플릿과 쿼리 패싯이 포함된 초기 기준 컨텍스트 세트를 도출합니다.

기준 컨텍스트를 생성하고 검증한 후 에이전트는 이를 Google Cloud 에 직접 업로드하고 컨텍스트 세트 리소스 이름을 반환합니다.

애플리케이션 아티팩트에서 평가 및 홀드아웃 데이터 세트 만들기

정확성을 체계적으로 개선하려면 확인된 SQL 쿼리와 페어링된 정답 질문이 필요합니다. 평가 벤치마크가 아직 없는 경우 에이전트는 애플리케이션 코드, 이전 쿼리, 데이터베이스 스키마에서 비즈니스 시나리오를 추출하여 벤치마크를 생성할 수 있습니다.

데이터 세트 생성 중에 에이전트는 두 가지 고유한 세트를 만듭니다.

• 학습 벤치마크: 반복 최적화 중에 사용되는 대표적인 질문-SQL 쌍의 모음입니다.
• 홀드아웃 데이터 세트: 일반화 가능성을 테스트하기 위해 예약된, 학습 벤치마크와 도메인이 유사한 별도의 질문 세트입니다.

힐 클라이밍으로 정확도 최적화

힐 클라이밍 최적화에서 에이전트는 컨텍스트 세트를 반복적으로 미세 조정하여 QueryData 정확도를 거의 100%에 가깝게 높입니다.

• 평가: 에이전트는 QueryData API를 사용하여 학습 벤치마크를 기준으로 현재 컨텍스트 세트를 테스트하고 정확도를 평가합니다.
• 격차 진단: 에이전트는 쿼리 실패를 분석하고 근본 원인(예: 누락된 테이블 조인, 연결되지 않은 비공개 항목, 복잡한 필터 조건)을 식별하고 타겟팅된 수정사항을 수립합니다.
• 정제 및 업로드: 에이전트는 쿼리 템플릿, 쿼리 가짓수, 값 검색을 추가하거나 개선하여 격차를 해소하고 업데이트된 컨텍스트 세트를 CLI에서 Google Cloud 에 자동으로 업로드합니다.
• 반복: 에이전트는 정확성이 최적의 점수로 수렴될 때까지 여러 라운드에 걸쳐 이 주기를 반복합니다.

다음 다이어그램은 체계적인 언덕 오르기 워크플로를 보여줍니다.

홀드아웃 데이터 세트로 일반화 가능성 입증

학습 벤치마크에서 높은 정확성을 달성하는 것이 필요하지만 프로덕션 트래픽에는 개발 중에 본 적이 없는 표현 변형과 복잡한 복합 질문이 포함됩니다.

힐 클라이밍 최적화가 수렴되면 에이전트는 결과 컨텍스트 세트를 홀드아웃 데이터 세트에 대해 테스트합니다. 이 단계에서는 컨텍스트 세트가 초기 벤치마크에 과적합되지 않고 새로운 사용자 입력에 깔끔하게 일반화되는지 확인합니다. 에이전트는 보이지 않는 질문 변형과 복합 필터(예: '델 마르에서 좋은 학교 근처에 있고 바다 전망이 있는 신혼부부를 위한 주택을 찾아줘') 전반의 정확성을 보여주는 일반화 가능성 보고서를 생성합니다.

주문형 작성 및 추론

전체 최적화 실행 외에도 비즈니스 요구사항이 변화함에 따라 에이전트와 대화하여 타겟팅된 업데이트를 수행할 수 있습니다.

• 타겟팅된 작성: 특정 비즈니스 요구사항을 자연어로 설명하면 에이전트가 컨텍스트 항목의 형식을 지정하고 수동 수정 없이 CLI에서 직접 업로드합니다.

  • '델 마르의 좋은 학교 근처에 있는 집을 찾아 줘'에 대한 템플릿을 SQL: SELECT p.property_id, p.address FROM properties AS p JOIN schools AS s ON p.school_id = s.school_id WHERE p.city = 'Del Mar' AND s.rating >= 7로 만들어 줘'
  • "Create a facet for the filter properties.bedrooms BETWEEN 3 AND 4 AND properties.square_feet BETWEEN 1500 AND 2500 labeled 'for a starter family'."
  • "properties.city에 대한 값 검색을 만들어 줘."

• 컨텍스트 집합 전반의 일괄 업데이트: 데이터베이스 열의 이름이 변경되거나 테이블 구조가 변경되면 에이전트는 관련 없는 항목을 수정하지 않고 영향을 받는 모든 컨텍스트 항목을 동시에 업데이트할 수 있습니다.

  • "내 컨텍스트 세트에서 단독 주택을 참조하는 모든 항목의 properties.property_type = 'SFR'를 properties.property_type = 'Single Family Residential'로 바꿔 줘. 관련 없는 항목은 그대로 둡니다."

다음 단계

• 컨텍스트 세트에 대해 자세히 알아보세요.
• AlloyDB Studio에서 QueryData를 테스트하는 방법 알아보기
• QueryData를 애플리케이션과 통합하는 방법 알아보기
• AlloyDB Studio에서 컨텍스트 세트를 만들거나 삭제하는 방법을 알아보세요.