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

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

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

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

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

시작하기 전에

쿼리하려는 데이터베이스에 대해 에이전트 컨텍스트가 업로드된 데이터 에이전트가 필요합니다. 자세한 내용은 AlloyDB용 데이터 에이전트, Spanner용 GoogleSQL용 데이터 에이전트, Cloud SQL용 데이터 에이전트, PostgreSQL용 Cloud SQL용 데이터 에이전트를 참조하세요.
다음과 같이 인스턴스에 Cloud SQL 데이터 API를 사용 설정합니다.
```
  gcloud beta sql instances patch INSTANCE_ID --data-api-access=ALLOW_DATA_API
```
INSTANCE_ID를 Cloud SQL 또는 PostgreSQL용 Cloud SQL 인스턴스의 ID로 바꿉니다.

또한 IAM 사용자 또는 서비스 계정에 데이터베이스 권한을 부여해야 합니다. 자세한 내용은 Cloud SQL에서 개별 IAM 사용자 또는 서비스 계정에 데이터베이스 권한 부여 및 PostgreSQL용 Cloud SQL에서 개별 IAM 사용자 또는 서비스 계정에 데이터베이스 권한 부여를 참조하세요.

`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
 }
}

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입니다.
    - agent_context_reference: 데이터베이스의 작성된 컨텍스트에 연결합니다.
      - context_set_id: 데이터베이스에 저장된 에이전트 컨텍스트 ID입니다. 컨텍스트 세트 ID를 찾는 방법에 관한 자세한 내용은 AlloyDB에서 에이전트 컨텍스트 ID 찾기, Spanner용 GoogleSQL에서 에이전트 컨텍스트 ID 찾기, Cloud SQL에서 에이전트 컨텍스트 ID 찾기, PostgreSQL용 Cloud SQL에서 에이전트 컨텍스트 ID 찾기를 참조하세요.
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."
}