Firestore Studio에서 QueryData 테스트

이 문서에서는 QueryData를 테스트하고 컨텍스트 세트 파일을 업데이트하는 방법을 설명합니다. 자연어 질문에서 MongoDB 호환 쿼리 언어 (MQL) 쿼리를 생성하는 QueryData의 기능을 테스트할 수 있습니다. 생성된 쿼리가 정확하지 않으면 컨텍스트 세트 파일을 업데이트할 수 있습니다.

컨텍스트 세트에 대한 자세한 내용은 컨텍스트 세트 개요를 참조하세요.

시작하기 전에

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

컨텍스트 세트 파일을 다운로드, 업데이트, 업로드하려면 IAM 사용자에게 프로젝트에 대한 Dataplex 카탈로그 편집자 (roles/dataplex.catalogEditor) 또는 Dataplex 카탈로그 관리자 (roles/dataplex.catalogAdmin) 역할이 있어야 합니다. 자세한 내용은 컨텍스트 세트 권한을 참조하세요.

QueryData 테스트

QueryData를 테스트하려면 다음 단계를 수행합니다.

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

    Firestore로 이동

  2. 컨텍스트 세트를 추가한 데이터베이스를 선택합니다. MongoDB 호환성을 갖춘 Firestore만 지원됩니다.

  3. 탐색 메뉴에서 Firestore 스튜디오 를 클릭합니다.

  4. 탐색기 창에서 사용 중인 컨텍스트 세트 옆에 있는 작업 보기를 클릭합니다.

  5. 컨텍스트 세트 테스트 를 클릭합니다.

  6. 쿼리 편집기에서 쿼리 생성 을 클릭하여 코딩 도우미 패널을 엽니다.

  7. 편집기에 자연어 질문을 입력하여 MQL 쿼리를 생성하고 생성 을 클릭합니다.

  8. MQL 쿼리의 정확성을 검토합니다.

컨텍스트 세트 다운로드 및 업데이트

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

컨텍스트 세트를 다운로드하고 업데이트하려면 다음 단계를 수행합니다.

  1. 탐색기 창에서 작업 보기를 클릭합니다.
  2. 컨텍스트 파일 다운로드 를 클릭합니다.
  3. 컨텍스트 엔지니어링 에이전트를 사용하여 컨텍스트 세트 빌드의 단계에 따라 추가 쿼리 쌍으로 컨텍스트를 업데이트합니다.
  4. 탐색기 창에서 사용 중인 컨텍스트 세트 옆에 있는 작업 보기를 클릭합니다.
  5. 컨텍스트 세트 수정 을 클릭합니다.
  6. 컨텍스트 세트 파일 업로드 섹션에서 찾아보기 를 클릭하고 업데이트된 컨텍스트 세트 파일을 선택합니다.
  7. 저장 을 클릭하여 컨텍스트 세트를 업데이트합니다.

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

컨텍스트 세트 ID 찾기

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

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

    Firestore로 이동

  2. 컨텍스트 세트를 추가한 데이터베이스를 선택합니다.

  3. 탐색 메뉴에서 Firestore 스튜디오 를 클릭합니다.

  4. 탐색기 창에서 사용 중인 컨텍스트 세트 옆에 있는 작업 보기를 클릭합니다.

  5. 컨텍스트 세트 수정 을 클릭합니다.

  6. 컨텍스트 세트 ID 에서 컨텍스트 ID를 기록합니다. 컨텍스트 세트 ID 형식은 projects/data-agents-project/locations/us-central1/contextSets/bdf_pg_all_templates와 유사합니다.

QueryData를 애플리케이션에 연결

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

컨텍스트 세트를 테스트한 후 QueryData 호출에서 데이터베이스 데이터 소스를 참조할 수 있습니다.

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

다음 예에서는 firestore_reference (MongoDB 호환성을 갖춘 Firestore) 데이터 소스를 사용하는 QueryData 요청을 보여줍니다. agent_context_reference.context_set_id 필드는 데이터베이스에 저장된 사전 작성된 컨텍스트에 연결하는 데 사용됩니다.

{
  "parent": "projects/context-set-project/locations/us-central1",
  "prompt": "How many accounts in the Prague region are eligible for loans?",
  "context": {
    "datasource_references": [
      {
        "firestore_reference": {
          "database_reference": {
            "project_id": "context-set-project",
            "region": "us-central1",
            "database_id": "financial"
          },
          "agent_context_reference": {
            "context_set_id": "projects/context-set-project/locations/us-central1/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: 데이터 소스 유형을 지정합니다.
      • firestore_reference: 데이터베이스를 쿼리할 때 필요합니다. 이 필드는 쿼리 중인 데이터베이스에 따라 변경됩니다.
        • database_reference: 데이터베이스 인스턴스와 관련된 정보를 지정합니다.
          • project_id: 데이터베이스의 프로젝트 ID입니다.
          • region: 데이터베이스의 리전입니다.
          • database_id: 데이터베이스의 ID입니다.
        • agent_context_reference: 데이터베이스의 작성된 컨텍스트에 연결합니다.
          • context_set_id: 데이터베이스에 저장된 컨텍스트의 전체 컨텍스트 세트 ID입니다. 예를 들면 projects/context-set-project/locations/us-central1/contextSets/bdf_gsql_gemini_all_templates입니다.
  • generationOptions: 생성할 출력 유형을 구성합니다.
    • generate_query_result: 쿼리 결과를 생성하고 반환하려면 true로 설정합니다.
    • generate_natural_language_answer: 선택사항입니다. true로 설정하면 자연어 답변을 생성합니다.
    • generate_explanation: 선택사항입니다. true로 설정하면 MQL 쿼리에 대한 설명을 생성합니다.
    • generate_disambiguation_question: 선택사항입니다. true로 설정하면 쿼리가 모호한 경우 모호성 해소 질문을 생성합니다.

QueryData 응답 예시

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

{
  "generated_query": "// Count the number of accounts in Prague that are eligible for loans\ndb.loans.aggregate([\n  // 1. Filter loans in the Prague region\n  { \n    $match: { \"district.name\": \"Prague\" } \n  },\n  // 2. Group by account_id to get distinct values, and count them\n  { \n    $group: { \n      _id: null, \n      uniqueAccounts: { $addToSet: \"$account_id\" } \n    } \n  },\n  // 3. Project the size of the unique accounts array\n  { \n    $project: { \n      _id: 0,\n      distinct_account_count: { $size: \"$uniqueAccounts\" } \n    } \n  }\n]);",
  "intent_explanation": "The question asks for the number of accounts eligible for loans in the Prague region. I need to filter the documents in the loans collection to only give me those in the Prague region. Then I need to group the loans by account ID to get distinct values and count them. Finally, I need to project the size of the array of unique accounts.",
  "query_result": {
    "columns": [
      {
        "name": "distinct_account_count"
      }
    ],
    "rows": [
      {
        "values": [
          {
            "value": "2"
          }
        ]
      }
    ],
    "total_row_count": 1
  },
  "natural_language_answer": "There are 2 accounts in Prague that are eligible for loans."
}

다음 단계