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

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

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

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

시작하기 전에

QueryData로 맥락 제공

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

  • alloydb PostgreSQL용 AlloyDB의 경우
  • Spanner용 GoogleSQL의 경우 spanner_reference
  • 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/cloud-db-nl2sql/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": "cloud-db-nl2sql",
            "region": "us-central1",
            "cluster_id": "sqlgen-magic",
            "instance_id": "sqlgen-magic-primary",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/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/cloud-db-nl2sql/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": "cloud-db-nl2sql"
            "region": "us-central1"
            "instance_id": "evalbench"
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/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
  }
}

Cloud SQL 및 PostgreSQL용 Cloud SQL

{
  "parent": "projects/cloud-db-nl2sql/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": "cloud-db-nl2sql",
            "region": "us-central1",
            "instance_id": "sqlgen-magic-primary",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/cloud-db-nl2sql/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: 데이터 소스에 관한 정보를 포함합니다.
  • 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."
}