이 페이지는 Cloud Translation API를 통해 번역되었습니다.

데이터 에이전트 검사 및 호출

이 문서에서는 에이전트를 검사하고 에이전트의 컨텍스트 파일을 업데이트하는 방법을 설명합니다. 에이전트를 검사하여 자연어 질문에서 SQL 쿼리를 생성하는 기능을 테스트할 수 있습니다. 생성된 질문이 정확하지 않으면 에이전트의 컨텍스트를 업데이트할 수 있습니다.

데이터 에이전트에 대해 알아보려면 데이터 에이전트 개요를 참고하세요.

시작하기 전에

데이터 에이전트가 이미 생성되어 있고 에이전트 컨텍스트가 데이터 에이전트에 업로드되어 있는지 확인합니다. 자세한 내용은 Spanner 스튜디오에서 데이터 에이전트 관리를 참고하세요.

데이터 에이전트 검사

데이터 에이전트를 검사하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Spanner 페이지로 이동합니다.

Spanner로 이동
목록에서 인스턴스를 선택한 후 데이터베이스를 선택합니다.
탐색 메뉴에서 Spanner 스튜디오를 클릭합니다.
탐색기 창에서 데이터 에이전트 옆에 있는 작업 보기를 클릭합니다.
에이전트 검사를 클릭합니다.
쿼리 편집기에서 SQL 생성을 클릭하여 코딩 도우미 패널을 엽니다.
자연어 질문을 입력하여 SQL 쿼리를 생성하고 생성을 클릭합니다.
SQL 쿼리가 정확한지 검토합니다.

데이터 에이전트의 컨텍스트 다운로드 및 업데이트

자연어 질문에 대해 생성된 SQL 쿼리가 만족스럽지 않으면 기존 에이전트 컨텍스트 파일을 다운로드합니다. 그런 다음 쿼리 템플릿을 검토하고 업데이트한 후 업데이트된 컨텍스트 파일을 에이전트에 다시 업로드할 수 있습니다.

데이터 에이전트의 컨텍스트를 다운로드하고 업데이트하려면 다음 단계를 따르세요.

탐색기 창에서 데이터 에이전트 옆에 있는 작업 보기를 클릭합니다.
에이전트 컨텍스트 파일 다운로드를 클릭합니다.
Gemini CLI를 사용하여 컨텍스트 빌드의 단계에 따라 추가 쿼리 쌍으로 컨텍스트를 업데이트합니다.
탐색기 창에서 데이터 에이전트 옆에 있는 작업 보기를 클릭합니다.
상담사 수정을 클릭합니다.
에이전트 컨텍스트 파일 업로드 섹션에서 찾아보기를 클릭하고 업데이트된 에이전트 컨텍스트 파일을 선택합니다.
저장을 클릭하여 에이전트 컨텍스트를 업데이트합니다.

대답의 정확성에 만족하면 QueryData 엔드포인트를 사용하여 애플리케이션을 데이터 에이전트에 연결할 수 있습니다.

에이전트 컨텍스트 ID 찾기

데이터 애플리케이션을 데이터 에이전트에 연결하려면 에이전트의 컨텍스트 ID가 필요합니다.

Google Cloud 콘솔에서 Spanner 페이지로 이동합니다.

Spanner로 이동
목록에서 인스턴스를 선택한 후 데이터베이스를 선택합니다.
탐색 메뉴에서 Spanner 스튜디오를 클릭합니다.
탐색기 창에서 데이터 에이전트 옆에 있는 작업 보기를 클릭합니다.
상담사 수정을 클릭합니다.
상담사 컨텍스트 ID에서 컨텍스트 ID를 확인합니다. 에이전트 컨텍스트 ID 형식은 projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_pg_all_templates과 유사합니다.

데이터 에이전트를 애플리케이션에 연결

QueryData 메서드 호출에서 에이전트 컨텍스트 ID를 설정하여 AlloyDB, Spanner, Cloud SQL, PostgreSQL용 Cloud SQL과 같은 데이터베이스 데이터 소스에 대해 작성된 컨텍스트를 제공합니다. 자세한 내용은 데이터베이스 데이터 소스의 데이터 에이전트 컨텍스트 정의를 참고하세요.

데이터 에이전트를 검사한 후 QueryData 호출에서 데이터베이스 데이터 소스를 참조할 수 있습니다.

작성된 컨텍스트가 포함된 `QueryData` 요청의 예

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

{
  "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
  }
}

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

prompt: 최종 사용자의 자연어 질문입니다.
context: 데이터 소스에 관한 정보를 포함합니다.
- datasource_references: 데이터 소스 유형을 지정합니다.
  - spanner_reference: 데이터베이스를 쿼리할 때 필요합니다. 이 필드는 쿼리하는 데이터베이스에 따라 변경됩니다.
    - database_reference: 데이터베이스 인스턴스와 관련된 정보를 지정합니다.
      - engine: 데이터베이스의 SQL 언어입니다. Spanner 데이터베이스의 경우 GOOGLE_SQL로 설정합니다.
      - project_id: 데이터베이스 인스턴스의 프로젝트 ID입니다.
      - region: Spanner 인스턴스의 리전입니다.
      - instance_id: Spanner 인스턴스의 인스턴스 ID입니다.
      - database_id: 데이터베이스의 ID입니다.
    - agent_context_reference: 데이터베이스의 작성된 컨텍스트로 연결되는 링크입니다.
      - context_set_id: 데이터베이스에 저장된 컨텍스트의 전체 에이전트 컨텍스트 ID입니다. 예를 들면 projects/cloud-db-nl2sql/locations/us-east1/contextSets/bdf_gsql_gemini_all_templates입니다.
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."
}

다음 단계

데이터 에이전트에 대해 자세히 알아보세요.
Gemini CLI를 사용하여 컨텍스트를 빌드하는 방법 알아보기
Spanner Studio에서 데이터 에이전트를 관리하는 방법을 알아보세요.