1. مقدمه
در این کد لبه شما یاد خواهید گرفت که چگونه با استفاده از کیت توسعه عامل (ADK ) عواملی بسازید که می توانند به سوالات مربوط به داده های ذخیره شده در BigQuery پاسخ دهند. شما همچنین این عوامل را با استفاده از سرویس GenAI Evaluation Vertex AI ارزیابی خواهید کرد:
کاری که خواهی کرد
- یک عامل تجزیه و تحلیل مکالمه در ADK بسازید
- این عامل را به مجموعه ابزار شخص اول ADK برای BigQuery مجهز کنید تا بتواند با داده های ذخیره شده در BigQuery تعامل داشته باشد.
- با استفاده از سرویس Vertex AI GenAI Evaluation یک چارچوب ارزیابی برای نماینده خود ایجاد کنید
- ارزیابی‌هایی را روی این عامل در برابر مجموعه‌ای از پاسخ‌های طلایی اجرا کنید
آنچه شما نیاز دارید
- یک مرورگر وب مانند کروم
- یک پروژه Google Cloud با فعال کردن صورتحساب، یا
- یک اکانت جیمیل بخش بعدی به شما نشان می‌دهد که چگونه می‌توانید یک اعتبار ۵ دلاری رایگان برای این کد لبه استفاده کنید و یک پروژه جدید راه‌اندازی کنید
این کد لبه برای توسعه دهندگان در تمام سطوح، از جمله مبتدیان است. شما از رابط خط فرمان در Google Cloud Shell و کد پایتون برای توسعه ADK استفاده خواهید کرد. نیازی نیست که متخصص پایتون باشید، اما درک اولیه از نحوه خواندن کد به شما در درک مفاهیم کمک می کند.
2. قبل از شروع
یک پروژه Google Cloud ایجاد کنید
- در Google Cloud Console ، در صفحه انتخاب پروژه، یک پروژه Google Cloud را انتخاب یا ایجاد کنید .
- مطمئن شوید که صورتحساب برای پروژه Cloud شما فعال است. با نحوه بررسی فعال بودن صورتحساب در پروژه آشنا شوید.
Cloud Shell را راه اندازی کنید
Cloud Shell یک محیط خط فرمان است که در Google Cloud اجرا می شود و با ابزارهای لازم از قبل بارگذاری شده است.
- روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید:
- پس از اتصال به Cloud Shell، این دستور را اجرا کنید تا احراز هویت خود را در Cloud Shell تأیید کنید:
gcloud auth list
- برای تأیید اینکه پروژه شما برای استفاده با gcloud پیکربندی شده است، دستور زیر را اجرا کنید:
gcloud config list project
- برای تنظیم پروژه خود از دستور زیر استفاده کنید:
export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID
API ها را فعال کنید
- برای فعال کردن تمام API ها و سرویس های مورد نیاز، این دستور را اجرا کنید:
gcloud services enable bigquery.googleapis.com \
aiplatform.googleapis.com \
cloudresourcemanager.googleapis.com
- در اجرای موفقیت آمیز دستور، باید پیامی مشابه تصویر زیر مشاهده کنید:
Operation "operations/..." finished successfully.
3. یک مجموعه داده BigQuery ایجاد کنید
- برای ایجاد یک مجموعه داده جدید به نام تجارت الکترونیک در BigQuery، دستور زیر را در Cloud Shell اجرا کنید:
bq mk --dataset --location=US ecommerce
زیرمجموعه ایستا از مجموعه داده عمومی BigQuery thelook_ecommerce به عنوان فایل های AVRO در یک سطل عمومی Google Cloud Storage ذخیره می شود.
- این دستور را در Cloud Shell اجرا کنید تا این فایل‌های Avro در BigQuery به‌عنوان جداول (رویدادها، order_items، محصولات، کاربران، سفارش‌ها) بارگیری شوند:
bq load --source_format=AVRO --autodetect \
ecommerce.events \
gs://sample-data-and-media/thelook_dataset_snapshot/events/*.avro.gz
bq load --source_format=AVRO --autodetect \
ecommerce.order_items \
gs://sample-data-and-media/thelook_dataset_snapshot/order_items/*.avro.gz
bq load --source_format=AVRO --autodetect \
ecommerce.products \
gs://sample-data-and-media/thelook_dataset_snapshot/products/*.avro.gz
bq load --source_format=AVRO --autodetect \
ecommerce.users \
gs://sample-data-and-media/thelook_dataset_snapshot/users/*.avro.gz
bq load --source_format=AVRO --autodetect \
ecommerce.orders \
gs://sample-data-and-media/thelook_dataset_snapshot/orders/*.avro.gz
bq load --source_format=AVRO --autodetect \
ecommerce.inventory_items \
gs://sample-data-and-media/thelook_dataset_snapshot/inventory_items/*.avro.gz
bq load --source_format=AVRO --autodetect \
ecommerce.distribution_centers \
gs://sample-data-and-media/thelook_dataset_snapshot/distribution_centers/*.avro.gz
این فرآیند ممکن است چند دقیقه طول بکشد.
- با مراجعه به کنسول BigQuery در پروژه Google Cloud خود، تأیید کنید که مجموعه داده و جداول ایجاد شده اند:
4. محیطی را برای عوامل ADK آماده کنید
به Cloud Shell برگردید و مطمئن شوید که در فهرست اصلی خود هستید. ما یک محیط پایتون مجازی ایجاد می کنیم و بسته های مورد نیاز را نصب می کنیم.
- یک برگه ترمینال جدید را در Cloud Shell باز کنید و این دستور را برای ایجاد و رفتن به پوشه ای به نام bigquery-adk-codelab اجرا کنید:
mkdir bigquery-adk-codelab
cd bigquery-adk-codelab
- ایجاد یک محیط مجازی پایتون:
python -m venv .venv
- فعال کردن محیط مجازی:
source .venv/bin/activate
- بسته های پایتون ADK و AI-Platform گوگل را نصب کنید. پلتفرم هوش مصنوعی و بسته پانداها برای ارزیابی عامل bigquery مورد نیاز است:
pip install google-adk google-cloud-aiplatform[evaluation] pandas
5. یک برنامه ADK ایجاد کنید
اکنون بیایید عامل BigQuery خود را ایجاد کنیم. این عامل برای پاسخ به سوالات زبان طبیعی در مورد داده های ذخیره شده در BigQuery طراحی خواهد شد.
- دستور adk create utility را اجرا کنید تا یک برنامه عامل جدید را با پوشه ها و فایل های لازم داربست:
adk create data_agent_app
دستورات را دنبال کنید:
- gemini-2.5-flash را برای مدل انتخاب کنید.
- Vertex AI را برای backend انتخاب کنید.
- شناسه و منطقه Google Cloud Project پیش‌فرض خود را تأیید کنید.
یک نمونه تعامل در زیر نشان داده شده است:
- روی دکمه Open Editor در Cloud Shell کلیک کنید تا Cloud Shell Editor باز شود و پوشه‌ها و فایل‌های جدید ایجاد شده را مشاهده کنید:
به فایل های تولید شده توجه کنید:
bigquery-adk-codelab/
├── .venv/
└── data_agent_app/
├── __init__.py
├── agent.py
└── .env
- init.py: پوشه را به عنوان یک ماژول پایتون علامت گذاری می کند.
- agent.py: شامل تعریف اولیه عامل است.
- . env: حاوی متغیرهای محیطی برای پروژه شما است (برای مشاهده این فایل ممکن است لازم باشد روی View > Toggle Hidden Files کلیک کنید)
هر متغیری را که به درستی از دستورات تنظیم نشده است به روز کنید:
GOOGLE_GENAI_USE_VERTEXAI=1 GOOGLE_CLOUD_PROJECT=<YOUR_GOOGLE_PROJECT_ID> GOOGLE_CLOUD_LOCATION=<YOUR_GOOGLE_CLOUD_REGION>
6. عامل خود را تعریف کنید و مجموعه ابزار BigQuery را به آن اختصاص دهید
برای تعریف یک عامل ADK که با استفاده از مجموعه ابزار BigQuery با BigQuery تعامل دارد، محتوای موجود فایل agent.py را با کد زیر جایگزین کنید.
شما باید شناسه پروژه در دستورالعمل های عامل را به شناسه پروژه واقعی خود به روز کنید:
from google.adk.agents import Agent
from google.adk.tools.bigquery import BigQueryCredentialsConfig, BigQueryToolset
import google.auth
import dotenv
dotenv.load_dotenv()
credentials, _ = google.auth.default()
credentials_config = BigQueryCredentialsConfig(credentials=credentials)
bigquery_toolset = BigQueryToolset(
credentials_config=credentials_config
)
root_agent = Agent(
model="gemini-2.5-flash",
name="bigquery_agent",
description="Agent that answers questions about BigQuery data by executing SQL queries.",
instruction=(
"""
You are a BigQuery data analysis agent.
You are able to answer questions on data stored in project-id: '<YOUR_PROJECT_ID>' on the `ecommerce` dataset.
"""
),
tools=[bigquery_toolset]
)
def get_bigquery_agent():
return root_agent
مجموعه ابزار BigQuery یک عامل را با قابلیت های واکشی ابرداده و اجرای پرس و جوهای SQL روی داده های BigQuery فراهم می کند. برای استفاده از مجموعه ابزار، باید احراز هویت کنید، که رایج‌ترین گزینه‌ها عبارتند از Application Default Credentials (ADC) برای توسعه، OAuth تعاملی برای زمانی که نماینده باید از طرف یک کاربر خاص عمل کند، یا اعتبار حساب سرویس برای تأیید هویت امن و در سطح تولید.
از اینجا می توانید با بازگشت به Cloud Shell و اجرای این دستور با نماینده خود چت کنید :
adk web
باید اعلانی ببینید که می گوید وب سرور شروع به کار کرده است:
... INFO: Started server process [2735] INFO: Waiting for application startup. +-----------------------------------------------------------------------------+ | ADK Web Server started | | | For local testing, access at http://127.0.0.1:8000. | +-----------------------------------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000
برای راه‌اندازی وب adk روی نشانی اینترنتی ارائه شده کلیک کنید - می‌توانید از نماینده خود در مورد مجموعه داده سؤالاتی بپرسید:
adk web را ببندید و Ctrl + C را در ترمینال فشار دهید تا وب سرور خاموش شود.
7. نماینده خود را برای ارزیابی آماده کنید
اکنون که عامل BigQuery خود را تعریف کرده اید، باید آن را برای ارزیابی قابل اجرا کنید.
کد زیر تابعی به نام run_conversation را تعریف می‌کند که با ایجاد یک عامل، اجرای یک جلسه و پردازش رویدادها برای بازیابی پاسخ نهایی، جریان گفتگو را مدیریت می‌کند.
- به Cloud Editor برگردید و یک فایل جدید به نام
run_agent.pyدر دایرکتوری bigquery-adk-codelab ایجاد کنید و کد زیر را کپی/پیست کنید:
from data_agent_app.agent import get_bigquery_agent
from google.adk.sessions import InMemorySessionService
from google.adk.runners import Runner
from google.genai import types
import uuid
APP_NAME = "data_agent_app"
USER_ID = "biquery_user_101"
async def run_conversation(prompt: str):
session_service = InMemorySessionService()
session_id = f"{APP_NAME}-{uuid.uuid4().hex[:8]}"
root_agent = get_bigquery_agent()
runner = Runner(
agent=root_agent,
app_name=APP_NAME,
session_service=session_service
)
session = await session_service.create_session(
app_name=APP_NAME,
user_id=USER_ID,
session_id=session_id
)
final_response_text = "Unable to retrieve final response."
try:
# Run the agent and process the events as they are generated
async for event in runner.run_async(
user_id=USER_ID,
session_id=session_id,
new_message=types.Content(role='user', parts=[types.Part(text=prompt)])
):
if event.is_final_response():
if event.content and event.content.parts:
final_response_text = event.content.parts[0].text
break
except Exception as e:
print(f"Error in run_conversation: {e}")
final_response_text = f"An error occurred: {e}"
return final_response_text
کد زیر توابع کاربردی را برای فراخوانی این تابع قابل اجرا و برگرداندن نتیجه تعریف می کند. همچنین شامل توابع کمکی است که نتایج ارزیابی را چاپ و ذخیره می کند:
- یک فایل جدید به نام
utils.pyدر دایرکتوری bigquery-adk-codelab ایجاد کنید و این کد را در فایل utils.py کپی/پیست کنید:
import json
import os
import asyncio
import run_agent
def get_agent_response(prompt: str) -> dict:
try:
response = asyncio.run(run_agent.run_conversation(prompt)) # Invoke the agent
return {"response": response}
except Exception as e:
return {"response": "Error: Agent failed to produce a response."}
def save_evaluation_results(eval_result, experiment_run):
"""Processes, saves, and prints the evaluation results for a single run."""
os.makedirs("eval_results", exist_ok=True)
output_file_path = os.path.join("eval_results", f"bq_agent_eval_results_{experiment_run}.json")
# Prepare data for JSON serialization
eval_result_dict = {
'summary_metrics': eval_result.summary_metrics,
'pointwise_metrics': eval_result.metrics_table.to_dict('records')
}
# --- Save the results as a JSON file ---
with open(output_file_path, "w") as f:
json.dump(eval_result_dict, f, indent=4)
print(f"Results for run '{experiment_run}' saved to {output_file_path}")
def print_evaluation_summary(eval_result):
pointwise_metrics = eval_result.metrics_table
# Print summary metrics for the current run
summary_metrics = eval_result.summary_metrics
if summary_metrics:
for key, value in summary_metrics.items():
metric_name = key.replace('/mean', '').replace('_', ' ').title()
print(f"- {metric_name}: {key}: {value:.2f}")
else:
print("No summary metrics found for this run.")
print("\n" + "="*50 + "\n")
if not pointwise_metrics.empty:
total_questions = len(pointwise_metrics)
avg_completeness_score = pointwise_metrics['completeness_metric/score'].mean()
avg_factual_accuracy_score = pointwise_metrics['factual_accuracy_metric/score'].mean()
print("\n" + "="*50 + "\n")
print("--- Aggregated Evaluation Summary ---")
print(f"Total questions in evaluation dataset: {total_questions}")
print(f"Average Completeness Score: {avg_completeness_score:.2f}")
print(f"Average Factual Accuracy Score: {avg_factual_accuracy_score:.2f}")
print("\n" + "="*50 + "\n")
else:
print("\nNo successful evaluation runs were completed.")
8. یک مجموعه داده ارزیابی ایجاد کنید
برای ارزیابی نماینده خود، باید یک مجموعه داده ارزیابی ایجاد کنید ، معیارهای ارزیابی خود را تعریف کنید و کار ارزیابی را اجرا کنید .
مجموعه داده ارزیابی شامل فهرستی از سؤالات ( اعلانات ) و پاسخ های صحیح مربوط به آنها ( مرجعات ) است. سرویس ارزیابی از این جفت ها برای مقایسه پاسخ های نماینده شما و تعیین دقیق بودن آنها استفاده می کند.
- یک فایل جدید به نام ارزیابی_dataset.json در دایرکتوری bigquery-adk-codelab ایجاد کنید و مجموعه داده ارزیابی زیر را کپی/پیست کنید:
[
{
"prompt": "What tables are available in the dataset `ecommerce_data`?",
"reference": "The tables available in the dataset `ecommerce_data` are: `distribution_centers`, `events`, `inventory_items`, `order_items`, `orders`, `products`, and `users`."
},
{
"prompt": "How many users are there in total?",
"reference": "There are 100,000 users in total."
},
{
"prompt": "Find the email and age of the user with id 72685.",
"reference": "The email address of user 72685 is lindseybrennan@example.org and their age is 59."
},
{
"prompt": "How many orders have a status of Complete?",
"reference": "There are 31,077 orders with a status of 'complete'."
},
{
"prompt": "Which distribution center has the highest latitude, and what is it's latitude?",
"reference": "Chicago IL is the distribution center with the highest latitude, with a latitude of 41.84."
},
{
"prompt": "Retrieve the order id for all orders with a status of cancelled placed on the 1st June 2023 before 6am.",
"reference": "The order IDs for all orders with a status of 'cancelled' placed on the 1st June 2023 before 6am are: 26622, 49223"
},
{
"prompt": "What id the full name and user ids of the top 5 users with the most orders.",
"reference": "The top 5 users with the most orders are: Kristine Pennington (user ID 77359), Anthony Bright (user ID 4137), David Bean (user ID 30740), Michelle Wright (user ID 54563), and Matthew Reynolds (user ID 41136), each with 4 total orders."
},
{
"prompt": "Which distribution center is associated with the highest average retail price of its products, and what is the average retail price?",
"reference": "The distribution center associated with the highest average retail price of its products is Houston TX, with an average retail price of $69.74."
},
{
"prompt": "How many events were of type 'purchase' in Seoul during May 2024?",
"reference": "In May 2024, there were 57 'purchase' events recorded in Seoul."
},
{
"prompt": "For orders placed in June 2023, how many took three days or longer to be delivered after they were shipped?",
"reference": "In June 2023, there were 260 orders with a time difference of of 3 days or more between when they were shipped and delivered."
},
{
"prompt": "What are the names of the products and their respective retail price that have never been sold, but have a retail price greater than $210?",
"reference": "The products that have never been sold but have a retail price greater than $210 are:\n- Tommy Hilfiger Men's 2 Button Side Vent Windowpane Trim Fit Sport Coat, with a retail price of $249.9\n- MICHAEL Michael Kors Women's Hooded Leather Jacket: $211.11"
},
{
"prompt": "List the id and first name of users between the ages of 70 and 75 who have Facebook were sourced from Facebook and are located in California.",
"reference": "The users between the ages of 70 and 75 from California with 'Facebook' as their traffic source are:\n- Julie (ID: 25379)\n- Sherry (ID: 85196)\n- Kenneth (ID: 82238)\n- Linsday (ID: 64079)\n- Matthew (ID: 99612)"
},
{
"prompt": "Identify the full name and user id of users over the age of 67 who live within 3.5 kilometers of any distribution_center.",
"reference": "The users over the age of 67 who live within 3.5 kilometers of any distribution center are:\n- William Campbell (user ID: 26082)\n- Becky Cantrell (user ID: 39008)"
},
{
"prompt": "What is the median age of users for each gender?",
"reference": "The median age for female users is 41, and the median age for male users is 41."
},
{
"prompt": "What is the average sale price of complete orders compared to returned orders, and what is the percentage difference (to two decimal places) between them?",
"reference": "The average sale price for 'Complete' orders was $59.56, while for 'Returned' orders it was $59.76. This represents a percentage difference of 0.34%."
}
]
9. معیارهای ارزیابی خود را تعریف کنید
اکنون از دو معیار سفارشی برای ارزیابی توانایی نماینده در پاسخ به سؤالات مربوط به داده‌های BigQuery شما استفاده می‌کنیم که هر دو امتیاز از 1 تا 5 را ارائه می‌کنند:
- متریک دقت واقعی: ارزیابی می کند که آیا تمام داده ها و حقایق ارائه شده در پاسخ در مقایسه با حقیقت اصلی دقیق و صحیح هستند یا خیر.
- متریک کامل بودن: این نشان می دهد که آیا پاسخ شامل تمام قطعات کلیدی اطلاعات درخواست شده توسط کاربر و ارائه در پاسخ صحیح، بدون هیچ گونه حذف مهم است یا خیر.
- در نهایت، یک فایل جدید به نام
evaluate_agent.pyدر فهرست راهنمای bigquery-adk-codelab ایجاد کنید و کد تعریف متریک را در فایل ارزیابی_agent.py کپی/پیست کنید:
import uuid
import pandas as pd
from datetime import datetime
from vertexai.preview.evaluation import EvalTask
from vertexai.preview.evaluation.metrics import (
PointwiseMetricPromptTemplate,
PointwiseMetric,
MetricPromptTemplateExamples
)
from utils import (
save_evaluation_results,
print_evaluation_summary,
get_agent_response
)
factual_accuracy_metric = PointwiseMetric(
metric="factual_accuracy_metric",
metric_prompt_template=PointwiseMetricPromptTemplate(
instruction="""You are an expert evaluator assessing the factual accuracy of an AI's answer to a user's question, given a natural language prompt and a 'reference' (ground truth) answer. Your task is to determine if all factual information in the AI's answer is precise and correct when compared to the reference.""",
criteria={
"Accuracy": """The AI's answer must present factual information (numerical values, names, dates, specific values) that are **identical** to or an exact logical derivation from the reference.
- **Wording may vary, but the core factual information must be the same.**
- No numerical discrepancies.
- No incorrect names or identifiers.
- No fabricated or misleading details.
- Note: Minor rounding of numerical values that doesn't alter the core meaning or lead to significant misrepresentation is generally acceptable, assuming the prompt doesn't ask for exact precision."""
},
rating_rubric={
"5": "Excellent: The response is entirely factually correct. **All factual information precisely matches the reference.** There are absolutely no inaccuracies or misleading details.",
"3": "Good: The response is generally accurate, but contains minor, non-critical factual inaccuracies (e.g., a negligible rounding difference or slightly wrong detail) that do not impact the core understanding.",
"1": "Poor: The response contains significant factual errors, major numerical discrepancies, or fabricated information that makes the answer incorrect or unreliable."
},
input_variables=["prompt", "reference", "response"],
),
)
completeness_metric = PointwiseMetric(
metric="completeness_metric",
metric_prompt_template=PointwiseMetricPromptTemplate(
instruction="""You are an expert evaluator assessing the completeness of an AI's answer to a user's question, given a natural language prompt and a 'reference' (ground truth) answer. Your task is to determine if the AI's answer provides all the essential information requested by the user and present in the reference.""",
criteria={
"Completeness": """The AI's answer must include **all** key pieces of information explicitly or implicitly requested by the prompt and present in the reference.
- No omissions of critical facts.
- All requested attributes (e.g., age AND email, not just one) must be present.
- If the reference provides a multi-part answer, all parts must be covered."""
},
rating_rubric={
"5": "Excellent: The response is perfectly complete. **All key information requested by the prompt and present in the reference is included.** There are absolutely no omissions.",
"3": "Good: The response is mostly complete. It has only a slight, non-critical omission that does not impact the core understanding or utility of the answer.",
"1": "Poor: The response is critically incomplete. Essential parts of the requested information are missing, making the answer less useful or unusable for the user's purpose."
},
input_variables=["prompt", "reference", "response"],
),
)
10. وظیفه ارزیابی خود را ایجاد کنید
EvalTask مجموعه داده ارزیابی و معیارهای سفارشی را می گیرد و یک آزمایش ارزیابی جدید را راه اندازی می کند.
این تابع، run_eval، موتور اصلی ارزیابی است. از طریق EvalTask حلقه می‌زند و عامل شما را روی هر سؤال در مجموعه داده اجرا می‌کند. برای هر سؤال، پاسخ نماینده را ثبت می‌کند و سپس از معیارهایی که قبلاً تعریف کرده‌اید برای درجه‌بندی آن استفاده می‌کند.
کد زیر را در پایین فایل evaluate_agent.py کپی/پیست کنید:
def run_eval():
eval_dataset = pd.read_json("evaluation_dataset.json")
# Generate a unique run name
current_time = datetime.now().strftime('%Y%m%d-%H%M%S')
experiment_run_id = f"{current_time}-{uuid.uuid4().hex[:8]}"
print(f"--- Starting evaluation: ({experiment_run_id}) ---")
# Define the evaluation task with your dataset and metrics
eval_task = EvalTask(
dataset=eval_dataset,
metrics=[
factual_accuracy_metric,
completeness_metric
],
experiment="evaluate-bq-data-agent"
)
try:
eval_result = eval_task.evaluate(
runnable=get_agent_response, experiment_run_name=experiment_run_id
)
save_evaluation_results(eval_result, experiment_run_id)
print_evaluation_summary(eval_result)
except Exception as e:
print(f"An error occurred during evaluation run: {e}")
if __name__ == "__main__":
run_eval()
نتایج خلاصه شده و در یک فایل JSON ذخیره می شوند.
11. ارزیابی خود را اجرا کنید
اکنون که نماینده، معیارهای ارزیابی و مجموعه داده ارزیابی خود را آماده کرده اید، می توانید ارزیابی را اجرا کنید.
به Cloud Shell برگردید، مطمئن شوید که در دایرکتوری bigquery-adk-codelab هستید و اسکریپت ارزیابی را با استفاده از دستور زیر اجرا کنید:
python evaluate_agent.py
با پیشرفت ارزیابی، خروجی مشابه این را خواهید دید:
All 30 metric requests are successfully computed. Evaluation Took:29.00278048400105 seconds Results for run '20250919-181822-6a13dd42' saved to eval_results/bq_agent_eval_results_20250919-181822-6a13dd42.json - Row Count: row_count: 15.00 - Factual Accuracy Metric: factual_accuracy_metric/mean: 2.60 - Factual Accuracy Metric/Std: factual_accuracy_metric/std: 1.72 - Completeness Metric: completeness_metric/mean: 3.27 - Completeness Metric/Std: completeness_metric/std: 1.98 - Latency In Seconds: latency_in_seconds/mean: 12.17 - Latency In Seconds/Std: latency_in_seconds/std: 6.06 - Failure: failure/mean: 0.00 - Failure/Std: failure/std: 0.00
تفسیر نتایج:
به پوشه eval_results در پوشه data_agent_app بروید و فایل نتیجه ارزیابی را با نام bq_agent_eval_results_*.json باز کنید:
- معیارهای خلاصه: یک نمای کلی از عملکرد نماینده خود در مجموعه داده ارائه دهید.
- معیارهای دقت واقعی و کامل بودن: نمره نزدیکتر به 5 نشان دهنده دقت و کامل بودن بالاتر است. برای هر سوال یک امتیاز به همراه توضیح کتبی در مورد دلیل دریافت آن نمره وجود خواهد داشت.
می بینیم که میانگین امتیاز برای میانگین کامل بودن و دقت واقعی به ترتیب 27/3 و 72/1 است.
نتایج خیلی خوب نیست! بیایید سعی کنیم توانایی نماینده خود را برای پاسخ دادن به سوالات بهبود دهیم.
12. نتایج ارزیابی نماینده خود را بهبود بخشید
به agent.py در فهرست bigquery-adk-codelab بروید و مدل عامل و دستورالعمل های سیستم را به روز کنید. به یاد داشته باشید که <YOUR_PROJECT_ID> را با شناسه پروژه خود جایگزین کنید:
root_agent = Agent(
model="gemini-2.5-flash",
name="bigquery_agent",
description="Agent that answers questions about BigQuery data by executing SQL queries.",
instruction=(
"""
You are a data analysis agent with access to several BigQuery tools.
Use the appropriate tools to fetch relevant BigQuery metadata and execute SQL queries.
You must use these tools to answer the user's questions.
Run these queries in the project-id: '<YOUR_PROJECT_ID>' on the `ecommerce` dataset.
"""
),
tools=[bigquery_toolset]
)
حالا به ترمینال برگردید و ارزیابی را دوباره اجرا کنید:
python evaluate_agent.py
اکنون باید ببینید که نتایج بسیار بهتر است:
================================================== --- Aggregated Evaluation Summary --- Total questions in evaluation dataset: 15 Average Completeness Score: 4.73 Average Factual Accuracy Score: 4.20 ==================================================
ارزیابی نماینده شما یک فرآیند تکراری است. برای بهبود بیشتر نتایج ارزیابی، می‌توانید دستورالعمل‌های سیستم، پارامترهای مدل یا حتی ابرداده‌ها را در BigQuery تغییر دهید - این نکات و ترفندها را برای ایده‌های بیشتر بررسی کنید.
13. پاکسازی کنید
برای جلوگیری از هزینه‌های مداوم برای حساب Google Cloud خود، مهم است که منابعی را که در طول این کارگاه ایجاد کرده‌ایم حذف کنید.
اگر مجموعه داده ها یا جداول BigQuery خاصی را برای این کد لبه ایجاد کرده اید (مثلاً مجموعه داده های تجارت الکترونیک)، ممکن است بخواهید آنها را حذف کنید:
bq rm -r $PROJECT_ID:ecommerce
برای حذف دایرکتوری bigquery-adk-codelab و محتویات آن:
cd .. # Go back to your home directory if you are still in bigquery-adk-codelab
rm -rf bigquery-adk-codelab
14. تبریک می گویم
تبریک می گویم! شما با موفقیت یک عامل BigQuery را با استفاده از Agent Development Kit (ADK) ساخته و ارزیابی کرده اید. اکنون می‌دانید که چگونه یک عامل ADK را با ابزار BigQuery راه‌اندازی کنید و عملکرد آن را با استفاده از معیارهای ارزیابی سفارشی اندازه‌گیری کنید.