컨텍스트 세트 개요

MySQL | PostgreSQL | SQL Server

컨텍스트 세트를 사용하면 대화형 언어를 사용하여 데이터베이스의 데이터와 상호작용할 수 있으며, QueryData와 같은 도구에서 대화 에이전트를 빌드하는 데 사용됩니다. 데이터베이스의 테이블 집합에 대한 컨텍스트를 정의하여 컨텍스트 세트를 만들 수 있습니다. 이 컨텍스트를 통해 QueryData는 자연어 질문을 타겟 사용 사례에 맞는 정확한 쿼리로 변환할 수 있습니다.

컨텍스트 세트는 QueryData가 정확도가 높은 쿼리를 생성할 수 있도록 지원하는 데이터베이스별 정보의 모음입니다. 컨텍스트 세트에는 QueryData가 데이터베이스 스키마와 애플리케이션의 비즈니스 로직을 이해하는 데 도움이 되는 템플릿, 패싯, 값 검색이 포함됩니다.

다음 데이터베이스가 지원됩니다.

PostgreSQL용 AlloyDB
MySQL용 Cloud SQL
PostgreSQL용 Cloud SQL
Spanner

컨텍스트 세트를 사용해야 하는 경우

컨텍스트 세트를 사용하여 다음과 같은 사용 사례에 적합한 대화형 데이터 애플리케이션을 빌드할 수 있습니다.

고객 서비스 자동화: '주문은 어디에 있나요?' 또는 '현재 잔액은 얼마인가요?'와 같은 대량 문의를 처리합니다.
전자상거래 쇼핑 도우미: '100달러 미만의 러닝화를 보여 줘'와 같은 자연어 질문으로 사용자가 대규모 제품 카탈로그를 탐색할 수 있도록 지원합니다.
현장 운영 도구: 모바일 직원이 재고 수준, 부품 가용성 또는 서비스 티켓 세부정보를 실시간으로 쿼리할 수 있습니다.

컨텍스트 세트의 작동 방식

효과적인 에이전트 애플리케이션을 빌드하려면 QueryData가 데이터 조직과 비즈니스 로직을 이해해야 합니다. 이 정보는 컨텍스트 세트 형식으로 제공됩니다.

각 컨텍스트 유형의 JSON 객체가 포함된 파일에서 컨텍스트를 정의합니다. 이러한 컨텍스트 파일은 Gemini CLI를 사용하여 작성합니다. 그런 다음 Google Cloud콘솔에서 만든 컨텍스트 세트에 컨텍스트 파일을 업로드합니다. 이 프로세스를 통해 QueryData는 데이터베이스의 특정 스키마와 애플리케이션의 비즈니스 로직을 학습할 수 있습니다.

컨텍스트 파일은 다음과 유사합니다.

{
  "templates": [
    {
      "nl_query": "Count Prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" ='Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "T.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT $value as value, 'accounts.account_type' as columns, 'Account Type' as concept_type, 0 as distance, '{}'::text as context FROM \"accounts\" T WHERE T.\"account_type\" = $value",
      "concept_type": "Account Type",
      "description": "Exact match for account types"
    }
   ]
}

최종 사용자가 자연어 질문을 하면 QueryData는 컨텍스트를 선별하는 개발자가 감사한 템플릿 및 패싯에 질문을 일치시키는 것을 우선시합니다. QueryData는 일치하는 항목을 식별하면 선택된 쿼리 템플릿과 패싯을 사용하여 데이터베이스 쿼리를 합성합니다. 그런 다음 컨텍스트 설정 로직이 데이터베이스에 대해 해당 쿼리를 실행하여 정확한 결과를 반환합니다.

컨텍스트 내에서 값 검색을 정의하는 것이 좋습니다. 값 검색을 사용하면 상담사가 값 문구를 데이터베이스 열에 저장된 특정 값에 매핑할 수 있습니다. 이렇게 하면 LLM이 실제 데이터를 기반으로 하여 용어가 District 이름인지 City인지와 같은 모호성을 해결할 수 있습니다.

에이전트가 일치하는 템플릿을 찾지 못하면 값 검색을 사용하여 자연어 문구를 데이터베이스 열에 저장된 특정 값에 매핑합니다. 이렇게 하면 LLM이 실제 데이터를 기반으로 하므로 용어가 District, Name 또는 City를 의미하는지 등 모호한 부분을 해결하는 데 도움이 됩니다.

대화형 분석 API의 QueryData 엔드포인트는 자연어 질문에서 SQL 쿼리를 생성할 수 있도록 애플리케이션과의 프로그래매틱 통합을 지원하는 에이전트 도구입니다. 대화형 애플리케이션에서는 대화 기록과 컨텍스트를 관리하는 프레임워크 내에서 QueryData 엔드포인트를 사용해야 합니다.엄격한 행 수준 보안을 유지하면서 엔티티 해결을 적용하려면 파라미터화된 보안 뷰 (PSV)를 사용하면 됩니다. 자세한 내용은 파라미터화된 보안 뷰를 사용하여 애플리케이션 데이터 보호 및 액세스 제어를 참고하세요.

컨텍스트 설정 파일

컨텍스트 설정 파일은 자연어 질문을 특정 데이터베이스의 쿼리로 변환할 때 QueryData를 안내하는 JSON 형식의 선별된 템플릿 및 패싯으로 구성됩니다. 컨텍스트를 정의하면 일반적인 쿼리 패턴에 대해 정확도가 높은 SQL이 생성됩니다.

정확도를 극대화하기 위해 설정된 컨텍스트가 예상 애플리케이션 쿼리를 정확하고 포괄적으로 다루는지 확인합니다.

컨텍스트 세트는 us-central1, us-east1, europe-west4, asia-southeast1 리전에서 만들 수 있습니다.

쿼리 템플릿

쿼리 템플릿은 대표적인 자연어 질문과 이에 상응하는 SQL 쿼리로 구성된 선별된 집합입니다. 또한 자연어-SQL 생성에 사용되는 선언적 근거를 제공하는 설명도 포함됩니다.

쿼리 템플릿 객체는 다음과 유사합니다.

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ]
},
...

쿼리 템플릿 JSON 객체의 주요 구성요소는 다음과 같습니다.

nl_query: QueryData가 처리하는 자연어 쿼리의 예입니다.
sql: 자연어 질문에 대한 SQL 쿼리입니다.
intent: 자연어 질문의 목표 또는 목적입니다. 설정하지 않으면 이 값은 기본적으로 자연어 질문으로 설정됩니다.
manifest: 일반화된 자동 생성 인텐트 형식입니다.
parameterized_intent: 템플릿이 적용되고 자동으로 생성된 인텐트 양식으로, 엔티티 값이 파라미터로 대체됩니다.
parameterized_sql: 파라미터화된 인텐트에 해당하는 템플릿이 적용된 자동 생성 SQL 쿼리입니다.

쿼리 패싯은 대표적인 자연어 조건과 이에 상응하는 SQL 술어로 구성된 선별된 집합입니다. 패싯은 필터링과 조건을 관리하므로 쿼리 템플릿이 패싯별 검색을 실행할 수 있습니다.

쿼리 패싯 객체는 다음과 유사합니다.

{
...
"facets": [
    {
      "sql_snippet": "T.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "T.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

패싯 JSON 객체의 주요 구성요소는 다음과 같습니다.

sql_snippet: SQL 스니펫입니다.
intent: SQL 술어에 대한 설명입니다.
manifest: 일반화된 자동 생성 인텐트 형식입니다.
parameterized_intent: 템플릿이 적용되고 자동으로 생성된 인텐트 양식으로, 엔티티 값이 파라미터로 대체됩니다.
parameterized_sql_snippet: 파라미터화된 인텐트에 해당하는 sql_snippet의 템플릿화된 자동 생성 형식입니다.

값 검색어

값 검색 쿼리는 매칭 함수를 사용하여 데이터베이스 내에서 값과 컨텍스트를 찾는 개발자 정의 쿼리입니다. 값 연결은 이러한 쿼리의 결과를 사용하여 일치하는 값이 포함된 테이블과 열을 식별하고, 값의 개념 유형을 이해하고, 철자 오류를 수정합니다.

QueryData API는 값 연결을 사용하여 자연어를 SQL로 더 정확하게 변환합니다. 값 검색어를 사용하면 API가 맞춤법 오류를 수정하고 데이터베이스 값을 기반으로 값 유형을 해결하여 전환 정확도를 개선할 수 있습니다.

값 연결은 자연어를 SQL로 변환하는 정확도를 개선합니다. 예를 들어 사용자가 '히스로에서 출발하는 항공편이 있나요?'라고 물으면 데이터베이스에 공항 이름이 '런던 히스로'로 저장될 수 있습니다. 값 연결이 없으면 생성된 SQL이 WHERE name = 'Heathrow'로 필터링되어 결과가 반환되지 않을 수 있습니다. 값 검색 쿼리는 에이전트가 '히드로'를 올바른 데이터베이스 값 '런던 히드로' 및 스키마 위치 (airports.name)에 매핑하도록 안내하여 생성된 SQL이 정확하도록 합니다.

값 검색어의 예는 다음과 같습니다.

{
  ...
  "value_searches": [
    {
      "query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (Standard SQL) for 3-letter airport codes"
    },
    {
      "query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
      "concept_type": "Airport Name",
      "description": "Fuzzy match using standard trigram for partial airport names"
    },
    {
      "query": "WITH SemanticMetrics AS ( SELECT T.\"city\" AS original_value, ( (google_ml.embedding('gemini-embedding-001', $value)::vector <=> google_ml.embedding('gemini-embedding-001', T.\"city\")::vector) / 2.0 ) AS normalized_dist FROM \"airports\" T WHERE T.\"city\" IS NOT NULL ) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM SemanticMetrics",
      "concept_type": "Airport City",
      "description": "Semantic search on string values for airport city names"
    }
  ]
}

값 검색 JSON 객체의 주요 구성요소는 다음과 같습니다.

query: 데이터베이스의 테이블 열에 저장된 값에 값 문구를 일치시키는 로직을 정의하는 파라미터화된 SQL 문입니다. 결과 집합은 일반적으로 일치하는 값, 스키마 위치, 개념 유형, 정규화된 거리 측정항목 (0~1)을 투영합니다.
concept_type: 값에 할당된 의미론적 라벨입니다(예: district 또는 loan_status). 이 라벨은 값 연결과 궁극적으로 QueryData API가 스키마에서 값 문구의 역할을 이해하는 데 도움이 됩니다. 또한 값의 개념과 값 문구가 표시되는 테이블 및 열을 타겟팅하는 SQL 문을 생성하는 데도 도움이 됩니다.
description: 검색 로직에 대한 설명입니다.

제한사항

컨텍스트 세트에는 다음과 같은 제한사항이 있습니다.

SQL Server용 Cloud SQL은 지원되지 않습니다.
데이터베이스의 컨텍스트 세트는 템플릿, 패싯, 값 검색만 지원합니다.
데이터베이스의 컨텍스트 세트는 대화형 분석 API의 QueryData 엔드포인트에서만 사용됩니다.

다음 단계

Cloud SQL Studio에서 컨텍스트 세트를 만들거나 삭제하는 방법을 알아봅니다.