이 문서에서는 대화형 분석 API의 QueryData 메서드를 호출하여 Spanner Graph의 QueryData를 테스트하는 방법과 컨텍스트 세트 파일을 업데이트하는 방법을 설명합니다. 자연어 질문에서 Graph Query Language(GQL) 쿼리를 생성하는 QueryData의 기능을 테스트할 수 있습니다. 생성된 GQL 쿼리가 정확하지 않으면 컨텍스트 세트 파일을 업데이트할 수 있습니다.
Spanner Graph의 컨텍스트 세트에 대한 자세한 내용은 컨텍스트 세트 개요를 참조하세요.
시작하기 전에
- Spanner 데이터베이스에
FinGraph속성 그래프 스키마와 샘플 데이터가 구성되어 있는지 확인합니다.FinGraph스키마를 만들고 샘플 데이터를 삽입하는 방법은 Spanner Graph 설정 및 쿼리를 참조하세요. - 컨텍스트 세트가 이미 생성되어 있고 컨텍스트 세트 파일이 데이터베이스에 업로드되어 있는지 확인합니다. 자세한 내용은 Spanner Studio에서 컨텍스트 세트 관리를 참조하세요.
- Google Cloud CLI를 설치하고 초기화합니다.
기존 컨텍스트 세트 ID 찾기
컨텍스트 세트로 QueryData를 테스트하거나 데이터 애플리케이션을 QueryData에 연결하려면 컨텍스트 세트 ID가 필요합니다.
Google Cloud 콘솔에서 Spanner 페이지로 이동합니다.
목록에서 인스턴스를 선택한 후 데이터베이스를 선택합니다.
탐색 메뉴에서 Spanner 스튜디오를 클릭합니다.
탐색기 창에서 사용 중인 컨텍스트 세트 옆에 있는 작업 보기를 클릭합니다.
컨텍스트 세트 수정을 클릭합니다.
컨텍스트 세트 ID에서 컨텍스트 세트 ID를 기록합니다. 컨텍스트 세트 ID 형식은
projects/my-project/locations/us-central1/contextSets/fingraph-assistant와 유사합니다.
HTTP POST를 사용하여 QueryData 테스트
Spanner Graph의 QueryData를 테스트하려면 graph_ids 필드와 컨텍스트 세트 ID가 포함된 QueryData HTTP POST 요청을 전송합니다.
다음 콘텐츠로
request.json이라는 파일을 만듭니다.{ "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": "PROJECT_ID", "instance_id": "INSTANCE_ID", "database_id": "DATABASE_ID", "graph_ids": ["FinGraph"] }, "agent_context_reference": { "context_set_id": "CONTEXT_SET_ID" } } } }, "generation_options": { "generate_query_result": true, "generate_natural_language_answer": true, "generate_explanation": true } }
다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.INSTANCE_ID: Spanner 인스턴스 ID입니다.DATABASE_ID: Spanner 데이터베이스 ID입니다.CONTEXT_SET_ID: 컨텍스트 세트 ID 찾기에서 기록한 전체 컨텍스트 세트 ID입니다.
요청을 전송합니다.
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -H "x-goog-user-project: PROJECT_ID" \ "https://geminidataanalytics.googleapis.com/v1beta/projects/PROJECT_ID/locations/global:queryData" \ -d @request.json
응답에서
generatedQuery필드(GRAPH FinGraph MATCH ...)가 정확한지 검토하고 반환된 행의queryResult필드를 검토합니다.
다른 질문을 테스트하려면 request.json에서 prompt 값을 변경하고 요청을 다시 전송합니다. 작성된 컨텍스트 없이 QueryData가 어떻게 작동하는지 확인하려면 agent_context_reference 객체를 삭제합니다.
QueryData가 컨텍스트 세트를 사용하는지 확인하려면 컨텍스트 세트에 따라 달라지는 질문(예: '비상금 계좌는 누구 소유인가요?')을 하고 agent_context_reference 객체가 있는 경우와 없는 경우의 응답을 비교합니다. 컨텍스트가 설정되지 않으면 QueryData가 'rainy day'를 필터링하고 행을 반환하지 않을 수 있습니다. 컨텍스트가 설정되면 'Rainy Day Fund'를 필터링하고 Dana를 반환합니다.
기존 컨텍스트 세트 다운로드 및 업데이트
테스트 응답에서 자연어 질문에 대해 생성된 GQL 쿼리를 개선해야 하는 것으로 나타나면 기존 컨텍스트 세트 파일을 다운로드합니다. 그런 다음 GQL 쿼리 템플릿, 패싯 또는 값 검색을 검토하고 업데이트한 후 업데이트된 컨텍스트 세트 파일을 컨텍스트 세트에 업로드할 수 있습니다.
컨텍스트 세트를 다운로드하고 업데이트하려면 다음 단계를 수행합니다.
- 탐색기 창에서 컨텍스트 세트 옆에 있는 작업 보기를 클릭합니다.
- 컨텍스트 파일 다운로드를 클릭합니다.
- 컨텍스트 엔지니어링 에이전트를 사용하여 컨텍스트 세트 빌드의 단계에 따라 자연어-GQL 쿼리 쌍을 추가하여 컨텍스트 세트를 업데이트합니다.
- 탐색기 창에서 사용 중인 컨텍스트 세트 옆에 있는 작업 보기를 클릭합니다.
- 컨텍스트 세트 수정을 클릭합니다.
- 컨텍스트 세트 파일 업로드 섹션에서 찾아보기를 클릭하고 업데이트된 컨텍스트 세트 파일을 선택합니다.
- 저장을 클릭하여 컨텍스트 세트를 업데이트합니다.
- QueryData를 다시 테스트하여 생성된 GQL 쿼리를 확인합니다.
응답의 정확성에 만족하면 QueryData 엔드포인트를 사용하여 애플리케이션을 컨텍스트 세트에 연결할 수 있습니다.
애플리케이션에 QueryData 연결
QueryData 메서드 호출에서 컨텍스트 세트 ID와 타겟 graph_ids를 설정하여 작성된 컨텍스트를 제공하고 Spanner Graph에 대한 GQL 쿼리 생성을 사용 설정합니다. 데이터베이스 데이터 소스와 함께 QueryData를 사용하는 방법에 관한 자세한 내용은 데이터베이스 데이터 소스의 데이터 에이전트 컨텍스트 정의를 참고하세요. QueryData REST API를 호출하는 커스텀 HTTP 도구를 통해 에이전트 애플리케이션을 QueryData에 연결하는 예시는 애플리케이션과 QueryData 통합을 참조하세요.
작성된 컨텍스트가 있는 QueryData 요청 예시
다음 예시에서는 FinGraph 속성 그래프에 spanner_reference 데이터베이스 데이터 소스를 사용하는 QueryData 요청을 보여줍니다. QueryData가 속성 그래프를 타겟팅하고 GQL 쿼리를 생성하도록 spanner_reference.database_reference 내에 graph_ids를 제공해야 합니다. agent_context_reference.context_set_id 필드는 데이터베이스에 저장된 사전 작성된 컨텍스트에 연결됩니다.
{ "parent": "projects/my-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": "my-project", "instance_id": "my-instance", "database_id": "fin-graph-db", "graph_ids": [ "FinGraph" ] }, "agent_context_reference": { "context_set_id": "projects/my-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 } }
요청 본문에는 다음 필드가 포함됩니다.
parent: 선택사항. 요청의 프로젝트 및 위치이며projects/PROJECT_ID/locations/LOCATION형식입니다. 요청 URL과 동일한 프로젝트 및 위치를 사용합니다.prompt: 최종 사용자의 자연어 질문입니다.context: 데이터 소스에 대한 정보가 포함됩니다.datasource_references: 데이터 소스를 지정합니다. 이 필드는 목록이 아닌 객체입니다.spanner_reference: Spanner 데이터베이스를 쿼리할 때 필요합니다.database_reference: Spanner 데이터베이스 및 속성 그래프와 관련된 정보를 지정합니다.engine: 데이터베이스의 언어입니다. Spanner Graph 데이터베이스의 경우GOOGLE_SQL로 설정합니다.project_id: Spanner 인스턴스의 프로젝트 ID입니다.instance_id: Spanner 인스턴스의 인스턴스 ID입니다.database_id: Spanner 데이터베이스의 ID입니다.graph_ids: Spanner Graph에 필요합니다. 쿼리할 데이터베이스의 속성 그래프 이름 목록입니다(예:["FinGraph"]).graph_ids를 제공하면 QueryData가 지정된 속성 그래프에 대해 GQL 쿼리를 생성합니다.graph_ids를 생략하면 QueryData는 기본 테이블에 대한 관계형 SQL 쿼리만 생성합니다.
agent_context_reference: 데이터베이스에서 작성된 컨텍스트에 대한 링크입니다.context_set_id: 데이터베이스에 저장된 컨텍스트의 전체 컨텍스트 세트 ID입니다(예:projects/my-project/locations/us-central1/contextSets/fingraph-assistant).
generation_options: 생성할 출력 유형을 구성합니다.generate_query_result: 생성된 GQL 쿼리를 실행하고 쿼리 결과를 반환하려면true로 설정합니다.generate_natural_language_answer: 선택사항.true로 설정하면 쿼리 결과를 요약하는 자연어 답변이 생성됩니다.generate_explanation: 선택사항.true로 설정하면 GQL 쿼리에 대한 설명이 생성됩니다.generate_disambiguation_question: 선택사항.true로 설정하면 자연어 프롬프트가 모호한 경우 모호성 해소 질문을 생성합니다.
QueryData 응답 예시
다음 예시는 FinGraph 속성 그래프에 대한 QueryData 호출의 성공적인 응답을 보여줍니다. REST API는 generatedQuery 및 queryResult와 같은 camelCase로 필드 이름을 반환합니다. GQL 생성은 비결정적이므로 생성된 쿼리, 열 이름, 답변 텍스트는 호출마다 다를 수 있습니다.
{
"generatedQuery": "GRAPH `FinGraph` MATCH (p:`Person` {`name`: 'Dana'})-[:`Owns`]->(src:`Account`)-[t:`Transfers`]->(dst:`Account`) MATCH (p_recipient:`Person`)-[:`Owns`]->(dst) RETURN DISTINCT p_recipient.`name` AS recipient_name, dst.`id` AS recipient_account_id, t.`amount` AS transfer_amount",
"intentExplanation": "To find everyone Dana transferred money to, we identify the person named Dana and locate the accounts they own. We trace the transfer relationships from Dana's accounts to any destination accounts, identifying the specific amounts sent and the IDs of those receiving accounts. Finally, we find the individuals who own those receiving accounts to present their names along with the account details and transfer amounts.",
"queryResult": {
"columns": [
{
"name": "recipient_name",
"type": "STRING"
},
{
"name": "recipient_account_id",
"type": "INT64"
},
{
"name": "transfer_amount",
"type": "FLOAT64"
}
],
"rows": [
{
"values": [
{
"value": "Alex"
},
{
"value": "7"
},
{
"value": "500"
}
]
},
{
"values": [
{
"value": "Lee"
},
{
"value": "16"
},
{
"value": "200"
}
]
}
],
"totalRowCount": "2"
},
"naturalLanguageAnswer": "Based on the transaction records, Dana transferred money to the following recipients:\n\n* **Alex**: Account ID **7**, with a transfer amount of **500**\n* **Lee**: Account ID **16**, with a transfer amount of **200**"
}
다음 단계
- 컨텍스트 세트에 대해 자세히 알아보세요.
- 컨텍스트 엔지니어링 에이전트를 사용하여 컨텍스트 세트를 빌드하는 방법을 알아보세요.
- Spanner Studio에서 컨텍스트 세트를 관리하는 방법 알아보기