데이터베이스 데이터 소스의 데이터 에이전트 컨텍스트 정의

이 페이지에서는 데이터베이스 데이터 소스를 사용하는 데이터 에이전트에 작성된 컨텍스트를 제공하는 방법을 설명합니다.

작성된 컨텍스트는 데이터 에이전트 소유자가 데이터 에이전트의 동작을 형성하고 API의 응답을 미세 조정하기 위해 제공할 수 있는 안내입니다. 효과적인 작성 컨텍스트는 대화형 분석 API 데이터 에이전트가 데이터 소스에 관한 질문에 답변하는 데 유용한 컨텍스트를 제공합니다.

AlloyDB, Spanner용 GoogleSQL, MySQL용 Cloud SQL, PostgreSQL용 Cloud SQL과 같은 데이터베이스 데이터 소스의 경우 먼저 데이터베이스에서 컨텍스트를 정의하고 저장한 후 데이터 소스 참조에서 이를 참조하여 작성된 컨텍스트를 제공합니다. 이 페이지의 예시에서는 QueryData 메서드를 사용합니다.

정확도가 높은 컨텍스트를 제공하면 API가 더 정확하고 관련성 높은 SQL 쿼리와 답변을 생성할 수 있습니다.

시작하기 전에

QueryData로 맥락 제공

QueryData 메서드를 호출할 때 QueryDataRequest.context.datasourceReferences 필드 내에 데이터 소스 및 컨텍스트 정보를 제공합니다. 데이터베이스 데이터 소스의 경우 다음 중 하나를 사용해야 합니다.

  • PostgreSQL용 AlloyDB용 alloydb
  • Spanner용 GoogleSQL의 spanner_reference
  • MySQL용 Cloud SQL 및 PostgreSQL용 Cloud SQL의 cloud_sql_reference

이러한 참조 내에서 databaseReference 필드를 사용하여 데이터베이스와 테이블을 지정합니다. 작성된 컨텍스트를 포함하려면 context_set_id를 가리키는 agentContextReference도 제공해야 합니다.

작성된 컨텍스트가 있는 QueryData 요청 예시

다음 예시에서는 alloydb을 사용하는 QueryData 요청을 보여줍니다. agent_context_reference.context_set_id 필드는 데이터베이스에 저장된 사전 작성된 컨텍스트에 연결하는 데 사용됩니다.

AlloyDB

{
 "parent": "projects/data-agents-project/locations/us-central1",
 "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
 "context": {
   "datasource_references": [
     {
       "alloydb": {
         "database_reference": {
           "project_id": "data-agents-project",
           "region": "us-central1",
           "cluster_id": "sqlgen-magic",
           "instance_id": "data-agents-primary",
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates"
         }
       }
     }
   ]
 },
 "generation_options": {
   "generate_query_result": true,
   "generate_natural_language_answer": true,
   "generate_disambiguation_question": true,
   "generate_explanation": true
 }
}

Spanner용 GoogleSQL

{
 "parent": "projects/data-agents-project/locations/us-central1",
 "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
 "context": {
   "datasource_references": [
     {
       "spanner_reference" {
         "database_reference" {
           "engine": "GOOGLE_SQL"
           "project_id": "data-agents-project"
           "instance_id": "evalbench"
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates"
         }
       }
     }
   ]
 },
 "generation_options": {
   "generate_query_result": true,
   "generate_natural_language_answer": true,
   "generate_disambiguation_question": true,
   "generate_explanation": true
 }
}

Spanner Graph

{
 "parent": "projects/data-agents-project/locations/global",
 "prompt": "Find everyone that Dana transferred money to, along with the account IDs and transfer amounts.",
 "context": {
   "datasource_references": {
     "spanner_reference": {
       "database_reference": {
         "engine": "GOOGLE_SQL",
         "project_id": "data-agents-project",
         "instance_id": "data-agents-instance",
         "database_id": "fin-graph-db",
         "graph_ids": [
           "FinGraph"
         ]
       },
       "agent_context_reference": {
         "context_set_id": "projects/data-agents-project/locations/us-central1/contextSets/fingraph-assistant"
       }
     }
   }
 },
 "generation_options": {
   "generate_query_result": true,
   "generate_natural_language_answer": true,
   "generate_disambiguation_question": true,
   "generate_explanation": true
 }
}

MySQL용 Cloud SQL

{
 "parent": "projects/data-agents-project/locations/us-central1",
 "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
 "context": {
   "datasource_references": [
     {
       "cloud_sql_reference": {
         "database_reference": {
           "engine": "MYSQL"
           "project_id": "data-agents-project",
           "region": "us-central1",
           "instance_id": "data-agents-primary",
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates"
         }
       }
     }
   ]
 },
 "generation_options": {
   "generate_query_result": true,
   "generate_natural_language_answer": true,
   "generate_disambiguation_question": true,
   "generate_explanation": true
 }
}

PostgreSQL용 Cloud SQL

{
 "parent": "projects/data-agents-project/locations/us-central1",
 "prompt": "How many accounts who have region in Prague are eligible for loans? A3 contains the data of region.",
 "context": {
   "datasource_references": [
     {
       "cloud_sql_reference": {
         "database_reference": {
           "engine": "POSTGRES"
           "project_id": "data-agents-project",
           "region": "us-central1",
           "instance_id": "data-agents-primary",
           "database_id": "financial"
         },
         "agent_context_reference": {
           "context_set_id": "projects/data-agents-project/locations/us-east1/contextSets/bdf_pg_all_templates"
         }
       }
     }
   ]
 },
 "generation_options": {
   "generate_query_result": true,
   "generate_natural_language_answer": true,
   "generate_disambiguation_question": true,
   "generate_explanation": true
 }
}

요청 본문에는 다음 필드가 포함됩니다.

  • prompt: 최종 사용자의 자연어 질문입니다.
  • context: 데이터 소스에 대한 정보가 포함됩니다.
    • datasource_references: 데이터 소스 유형을 지정합니다.
      • alloydb: 데이터베이스를 쿼리할 때 필요합니다. 이 필드는 쿼리하는 데이터베이스에 따라 변경됩니다.
        • database_reference: 데이터베이스 인스턴스와 관련된 정보를 지정합니다.
          • engine: 데이터베이스 엔진 또는 SQL 언어입니다. AlloyDB의 경우 선택사항입니다. Spanner 데이터베이스의 경우 GOOGLE_SQL로 설정합니다. MySQL용 Cloud SQL 인스턴스의 경우 MYSQL로 설정합니다. PostgreSQL용 Cloud SQL 인스턴스의 경우 POSTGRESQL로 설정합니다.
          • project_id: 데이터베이스 인스턴스의 프로젝트 ID입니다.
          • region: 데이터베이스 인스턴스의 리전입니다.
          • cluster_id: 데이터베이스 인스턴스의 클러스터 ID입니다.
          • instance_id: 데이터베이스의 인스턴스 ID입니다.
          • database_id: 데이터베이스 ID입니다.
          • graph_ids: Spanner Graph에 필요합니다. 쿼리할 Spanner 데이터베이스의 속성 그래프 이름 목록입니다(예: ["FinGraph"]). graph_ids를 생략하면 QueryData는 GQL 쿼리 대신 기본 테이블에 대해 GoogleSQL 쿼리를 생성합니다.
        • agent_context_reference: 데이터베이스에서 작성된 컨텍스트에 대한 링크입니다.
  • generationOptions: 생성할 출력 유형을 구성합니다.
    • generate_query_result: 쿼리 결과를 생성하고 반환하려면 true로 설정합니다.
    • generate_natural_language_answer: 선택사항. true로 설정하면 자연어 답변이 생성됩니다.
    • generate_explanation: 선택사항. true로 설정하면 SQL 쿼리에 대한 설명이 생성됩니다.
    • generate_disambiguation_question: 선택사항. true로 설정하면 쿼리가 모호한 경우 모호성 해소 질문을 생성합니다.

QueryData 응답 예시

다음은 QueryData 호출에 대한 성공적인 응답의 예입니다.

{
 "generated_query": "-- Count the number of accounts in Prague that are eligible for loans\nSELECT\n  COUNT(DISTINCT \"loans\".\"account_id\")\nFROM \"loans\"\nJOIN \"district\" -- Join based on district ID\n  ON \"loans\".\"district_id\" = \"district\".\"district_id\"\nWHERE\n  \"district\".\"A3\" = 'Prague'; -- Filter for the Prague region",
 "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to join the `district` table with the `loans` table to filter by region and count the distinct accounts. The `A3` column in the `district` table contains the region information, and I'll filter for 'Prague'. The `loans` table contains information about loans, including the `account_id` and `district_id`. I will join these two tables on their respective district IDs.",
 "query_result": {
   "columns": [
     {
       "name": "count"
     }
   ],
   "rows": [
     {
       "values": [
         {
           "value": "2"
         }
       ]
     }
   ],
   "total_row_count": 1
 },
 "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}