이 페이지에서는 BigQuery 데이터를 대상으로 쿼리를 실행하여 비용이 발생하는 Conversational Analytics API 에이전트의 BigQuery 비용을 모니터링하고 관리하는 방법을 설명합니다. 다음 방법을 사용하여 지출을 관리하고 예기치 않은 비용을 방지할 수 있습니다.
에이전트 구성에서 big_query_max_billed_bytes 값을 설정하여 개별 쿼리의 비용을 제한합니다.
시작하기 전에
이 페이지에 설명된 비용 관리를 구현하려면 다음 요구사항을 충족해야 합니다.
결제가 사용 설정된 Google Cloud 프로젝트가 있어야 합니다.
Google Cloud 프로젝트의 할당량과 결제를 관리하려면 필요한 Identity and Access Management (IAM) 권한이 있어야 합니다.
프로젝트 및 사용자 할당량 설정
표준 BigQuery 할당량을 적용하여 Google Cloud 프로젝트 또는 개별 사용자의 지출 한도를 설정할 수 있습니다. 이러한 한도를 사용하면 전체 비용을 관리하고 개별 사용자의 과도한 지출을 방지할 수 있습니다.
매우 크거나 파티셔닝되지 않은 테이블에 빌드된 에이전트와 같이 비용이 많이 발생할 수 있는 에이전트의 경우 먼저 자체 전용 프로젝트에서 에이전트를 격리하는 것이 좋습니다. 그런 다음 프로젝트 수준 할당량을 적용하여 프로젝트의 최대 일일 비용을 제한하거나, 사용자 수준 할당량을 적용하여 사용자 간의 공정한 사용을 보장하거나, 프로젝트 수준 및 사용자 수준 할당량을 모두 적용할 수 있습니다.
에이전트 전용 프로젝트 설정
Conversational Analytics API 에이전트를 위한 전용 프로젝트를 설정하려면 다음 단계를 따르세요.
BigQuery API 서비스를 필터링하고 사용자당 일일 쿼리 사용량 할당량을 선택합니다.
할당량을 선택한 일일 한도 (예: 사용자당 일일 1TiB)로 수정합니다. 이 한도를 통해 단일 사용자가 과도한 양의 리소스를 소비할 수 없습니다.
개별 쿼리의 비용 제한
개별 사용자 쿼리로 인해 예기치 않은 과다한 요금이 발생하지 않도록 하려면 에이전트에서 big_query_max_billed_bytes 매개변수를 구성하여 쿼리당 비용 한도를 설정하면 됩니다.
상담사는 쿼리를 실행하기 전에 시험 실행을 통해 쿼리 비용을 추정합니다. 스캔할 예상 바이트가 big_query_max_billed_bytes 값을 초과하면 에이전트가 쿼리를 차단하고 사용자에게 오류 메시지를 보냅니다.
HTTP를 사용하여 또는 Python SDK를 사용하여 에이전트를 만들거나 구성할 때 published_context 필드 내에서 big_query_max_billed_bytes 매개변수를 설정할 수 있습니다. 다음 예시(textproto 형식으로 표시됨)는 샌프란시스코 가로수에 관한 질문에 답변하는 에이전트의 100MB 한도를 구성하는 요청의 구조를 보여줍니다.
parent: "projects/sample-project-name/locations/global"
data_agent_id: "sample-agent-id"
data_agent {
name: "projects/sample-project-name/locations/global/dataAgents/sample-agent-id"
data_analytics_agent {
published_context {
system_instruction: "This agent provides information about street trees in San Francisco, including their species, location, and planting date."
options {
datasource {
big_query_max_billed_bytes {
value: 104857600 #100MB
}
}
}
datasource_references {
bq {
table_references {
project_id: "bigquery-public-data"
dataset_id: "san_francisco"
table_id: "street_trees"
}
}
}
}
}
}
이 예시에서는 big_query_max_billed_bytes 매개변수가 104857600바이트 (100MB)로 설정됩니다. 이 값은 sample-agent-id 에이전트가 bigquery-public-data.san_francisco.street_trees BigQuery 테이블에서 실행하는 모든 쿼리의 한도를 설정합니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[],[],null,["# Manage BigQuery costs for Conversational Analytics API agents\n\n| This product or feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA products and features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\nThis page describes how to monitor and manage BigQuery costs for your Conversational Analytics API agents, which incur costs by running queries against your BigQuery data. You can use the following methods to control spending and prevent unexpected expenses:\n\n- [Set quotas for projects and users](#set-quotas) to apply broad spending limits for an entire project or for individual users.\n- [Limit costs for individual queries](#limit-individual-queries) by setting a `big_query_max_billed_bytes` value in the agent's configuration.\n\nBefore you begin\n----------------\n\nBefore you implement the cost controls that are described on this page, you must meet the following requirements:\n\n- You must have a Google Cloud project with billing enabled.\n- You must have the necessary Identity and Access Management (IAM) permissions to manage quotas and billing for your Google Cloud project.\n\nSet quotas for projects and users\n---------------------------------\n\nYou can set spending limits for a Google Cloud project or for individual users by applying standard [BigQuery quotas](/bigquery/quotas). These limits help you control overall costs and prevent individual users from overspending.\n\nFor agents that might incur high costs, such as an agent that is built on a very large or unpartitioned table, the recommended practice is to first isolate the agent in its own [dedicated project](#set-up-a-dedicated-project-for-your-agent). You can then apply a [project-level quota](#set-a-quota-for-the-project) to cap the project's maximum daily cost, a [user-level quota](#set-a-quota-for-users) to ensure fair use among users, or both project-level and user-level quotas.\n\n### Set up a dedicated project for your agent\n\nTo set up a dedicated project for your Conversational Analytics API agent or agents, follow these steps:\n\n1. In the Google Cloud console, [create a new Google Cloud project](/resource-manager/docs/creating-managing-projects#creating_a_project). This project will be dedicated to your agent or agents.\n2. Make sure that billing is enabled for the new project.\n3. Confirm that the agent is configured to use this new project for billing. When you configure the agent, you'll need to specify the project ID of this new project.\n\n### Set a quota for the project\n\nAfter you have set up a dedicated Google Cloud project, you can apply a quota to control costs for the entire project. To set a project-level quota, follow these steps:\n\n1. In the Google Cloud project for your agent, navigate to **IAM \\& Admin \\\u003e Quotas**.\n\n [Go to Quotas](https://console.cloud.google.com/iam-admin/quotas)\n2. Filter for the BigQuery API service, and select the **Query usage per day** quota.\n\n3. Edit the quota to your chosen daily limit (for example, 10 TiB). This limit creates a hard stop that prevents the project from exceeding the specified daily cost.\n\n### Set a quota for users\n\nTo prevent any individual user from generating a large bill, you can set a per-user quota by following these steps:\n\n1. In the Google Cloud project for your agent, navigate to **IAM \\& Admin \\\u003e Quotas**.\n\n [Go to Quotas](https://console.cloud.google.com/iam-admin/quotas)\n2. Filter for the **BigQuery API** service and select the **Query usage per day per user** quota.\n\n3. Edit the quota to your chosen daily limit (for example, 1 TiB per user per day). This limit ensures that no single user can consume an excessive amount of resources.\n\nLimit costs for individual queries\n----------------------------------\n\nTo prevent any individual user query from generating a large, unexpected bill, you can set a per-query cost limit by configuring the `big_query_max_billed_bytes` parameter on an agent.\n\nBefore the agent runs any query, the agent performs a trial run to estimate the cost of the query. If the estimated bytes to be scanned exceed the `big_query_max_billed_bytes` value, then the agent blocks the query and sends an error message to the user.\n\nYou can set the `big_query_max_billed_bytes` parameter within the `published_context` field when you create or configure an agent [with HTTP](/gemini/docs/conversational-analytics-api/build-agent-http#create_a_data_agent) or [with the Python SDK](/gemini/docs/conversational-analytics-api/build-agent-sdk#create_a_data_agent). The following example, shown in `textproto` format, illustrates the structure of a request that configures a 100 MB limit for an agent that answers questions about San Francisco street trees: \n\n parent: \"projects/sample-project-name/locations/global\"\n data_agent_id: \"sample-agent-id\"\n data_agent {\n name: \"projects/sample-project-name/locations/global/dataAgents/sample-agent-id\"\n data_analytics_agent {\n published_context {\n system_instruction: \"This agent provides information about street trees in San Francisco, including their species, location, and planting date.\"\n options {\n datasource {\n big_query_max_billed_bytes {\n value: 104857600 #100MB\n }\n }\n }\n datasource_references {\n bq {\n table_references {\n project_id: \"bigquery-public-data\"\n dataset_id: \"san_francisco\"\n table_id: \"street_trees\"\n }\n }\n }\n }\n }\n }\n\nIn this example, the `big_query_max_billed_bytes` parameter is set to `104857600` bytes (100 MB). This value establishes a limit for any queries that are run by the `sample-agent-id` agent on the `bigquery-public-data.san_francisco.street_trees` BigQuery table.\n\nFor interactive examples of how to create and configure agents, see the [Colaboratory notebooks](/gemini/docs/conversational-analytics-api/overview#interactive-colab-notebooks). For detailed information about API fields, consult the [API reference](/gemini/docs/conversational-analytics-api/reference/rest).\n\nLimitations\n-----------\n\nKeep the following limitations in mind when you're managing costs for your Conversational Analytics API agents:\n\n- These cost management tools apply only to projects that use [on-demand billing](/bigquery/pricing#on_demand_pricing) and not to projects that use [slot reservations](/bigquery/pricing#reservations_pricing).\n- Setting quotas for individual agents isn't supported. As described in [Set quotas for projects and users](#set-quotas), the recommended practice is to isolate the agent in its own project, and then apply project-level or per-user quotas to that project.\n- Tracking costs for individual agents by using [BigQuery labels](/bigquery/docs/labels-intro) isn't supported."]]
