مشاركة عبر

قيم وكلاء الذكاء الاصطناعي لديك (معاينة) (كلاسيكي)

ينطبق فقط على:بوابة Foundry (كلاسيكية). هذه المقالة غير متاحة لبوابة Foundry الجديدة. تعرف على المزيد حول البوابة الجديدة.

‏‫ملاحظة‬

بعض الروابط في هذا المقال قد تفتح محتوى في وثائق Microsoft Foundry الجديدة بدلا من وثائق Foundry (الكلاسيكية) التي تشاهدها الآن.

مهم

العناصر التي تم وضع علامة عليها (إصدار أولي) في هذه المقالة موجودة حالياً في الإصدار الأولي العام. يتم توفير هذه المعاينة دون اتفاقية على مستوى الخدمة، ولا نوصي بها لأحمال عمل الإنتاج. بعض الميزات ربما لا تكون مدعمة أو بها بعض القدرات المقيدة. لمزيد من المعلومات، راجع شروط الاستخدام الإضافية لمعاينات مايكروسوفت Azure.

وكلاء الذكاء الاصطناعي هم مساعدون أقوياء للإنتاجية يخلقون سير عمل لتلبية احتياجات الأعمال. ومع ذلك، فإن قابلية الملاحظة تمثل تحديا بسبب أنماط تفاعلها المعقدة. في هذا المقال، تتعلم كيفية تقييم وكلاء Microsoft Foundry أو وكلاء آخرين باستخدام مقيمين مدمجين.

لبناء تطبيقات وكالية جاهزة للإنتاج وضمان قابلية الملاحظة والشفافية، يحتاج المطورون إلى أدوات لتقييم ليس فقط الناتج النهائي لسير عمل الوكيل، بل أيضا جودة وكفاءة سير العمل.

يؤدي حدث مثل مستخدم يقوم بالاستعلام عن "الطقس غدا" إلى تشغيل سير عمل عاملي. لإنتاج استجابة نهائية، يتضمن سير العمل التفكير من خلال نوايا المستخدم، وأدوات الاستدعاء، واستخدام التوليد المعزز بالاسترجاع.

‏‫ملاحظة‬

حزمة تطوير تطوير Microsoft Foundry للتقييم وبوابة Foundry في وضع معاينة عامة، لكن واجهات برمجة التطبيقات متاحة عموما لتقييم النماذج ومجموعات البيانات (لا يزال تقييم الوكيل قيد المعاينة العامة). حزمة تقييم Azure AI SDK والمقيمون الذين تم تمييزهم (معاينة) في هذا المقال موجودون حاليا في معاينة عامة في كل مكان.

في هذه العملية، يعد تقييم كل خطوة من خطوات سير العمل وجودة وسلامة المخرج النهائي أمرا بالغ الأهمية. يتم صياغة هذه الجوانب في التقييمات التالية للوكلاء:

  • تحليل النية: يقيس ما إذا كان العامل يحدد نية المستخدم بشكل صحيح.
  • دقة استدعاء الأداة: يقيس ما إذا كان العامل قد أجرى استدعاءات أداة الدالة الصحيحة لطلب المستخدم.
  • الالتزام بالمهمة: يقيس ما إذا كان الرد النهائي للوكيل يلتزم بالمهام الموكلة إليه، وفقا لرسالة النظام والخطوات السابقة.

قيم جوانب الجودة والسلامة الأخرى في سير العمل الوكيلي باستخدام مجموعة شاملة من المقيمين المدمجين. بشكل عام، يرسل الوكلاء رسائل عامل. تحويل رسائل الوكيل إلى بيانات تقييم صحيحة للمقيمين قد يكون تحديا. إذا قمت ببناء وكيلك باستخدام خدمة وكيل Foundry، يمكنك تقييمه بسلاسة عبر دعم المحولات لدينا. إذا أنشأت وكيلك خارج خدمة وكلاء Foundry، فلا يزال بإمكانك استخدام المقيمين حسب سير العمل الوكيلي الخاص بك عن طريق تحليل رسائل الوكيل إلى صيغ البيانات المطلوبة. انظر أمثلة عند تقييم وكلاء آخرين.

Get started

تثبيت حزمة المقيمين من حزمة تقييم Azure AI:

pip install azure-ai-evaluation

تقييم وكلاء مايكروسوفت فاوندري

إذا كنت تستخدم خدمة وكلاء Foundry، يمكنك تقييم وكلائك بسلاسة باستخدام دعم المحولات لدينا لوكلاء Microsoft Foundry ووكلاء Semantic Kernel. المقيمون التاليون يدعمون بيانات التقييم التي يعيدون بواسطة المحول: IntentResolution، ToolCallAccuracy، TaskAdherence، Relevance، و Groundedness.

‏‫ملاحظة‬

إذا كنت تبني وكلاء آخرين يخرجون مخططا مختلفا، حولهم إلى مخطط رسائل وكيل على نمط OpenAI عام واستخدم المقيمين السابقين. بشكل عام، إذا استطعت تحليل رسائل الوكيل إلى صيغ البيانات المطلوبة، يمكنك أيضا استخدام جميع مقيميننا.

دعم النموذج للمقيمين المدعومين بالذكاء الذكاء الاصطناعي

تدعم نماذج الاستدلال AzureOpenAI وOpenAI والنماذج غير الاستدلالية حكم نموذج اللغة الكبيرة حسب المقيمين:

Evaluators نماذج الاستدلالية كحكم (مثال: نماذج السلسلة o من Azure OpenAI / OpenAI) النماذج غير المنطقية كقاض (على سبيل المثال: gpt-4.1، gpt-4o، وما إلى ذلك) لتمكين
IntentResolution، TaskAdherence، ToolCallAccuracy، ResponseCompleteness، Coherence، Fluency، Similarity، Groundedness، ، RetrievalRelevance مدعوم مدعوم قم بتعيين معلمة is_reasoning_model=True إضافية عند تهيئة المقيمين
مقيمون آخرون غير معتمد مدعوم --

للتقييم المعقد الذي يتطلب تفكيرا دقيقا، استخدم نموذج استدلالات قوي مثل 4.1-mini تحقيق توازن بين أداء الاستدلال وكفاءة التكلفة.

دعم تقييم مكالمات الأداة

ToolCallAccuracyEvaluator يدعم التقييم في Microsoft Foundry Agent للأدوات التالية:

  • البحث عن الملفات
  • Azure AI Search
  • التأريض في Bing
  • بحث Bing المخصص
  • تأريض SharePoint
  • مترجم شفرة
  • وكيل بيانات النسيج
  • OpenAPI
  • أداة الوظيفة (الأدوات المعرفة من قبل المستخدم)

ومع ذلك، إذا استخدمت أداة غير مدعومة أثناء تشغيل الوكيل، فإن المقيم يخرج "تمريرا" وسبب عدم دعم تقييم الأدوات المستدعية، لتسهيل تصفية هذه الحالات. لتمكين التقييم، قم بتغليف الأدوات غير المدعومة كأدوات معرفة من قبل المستخدم.

يوضح هذا المثال كيفية بناء وتقييم وكيل Microsoft Foundry. وبشكل منفصل عن التقييم، تتطلب خدمة وكلاء المسبك pip install azure-ai-projects azure-identity، و project connection string المسبك، والنماذج المدعومة.

إنشاء مؤشرات ترابط العامل وتشغيله

يمكن للوكلاء استخدام الأدوات. إليك مثال لإنشاء أدوات مخصصة للوكيل لاستخدامها (باستخدام دالة الطقس الافتراضية كمثال):

from azure.ai.projects.models import FunctionTool, ToolSet
from typing import Set, Callable, Any
import json

# Define a custom Python function.
def fetch_weather(location: str) -> str:
    """
    Fetches the weather information for the specified location.

    :param location (str): The location to fetch weather for.
    :return: Weather information as a JSON string.
    :rtype: str
    """
    # In a real-world scenario, you'd integrate with a weather API.
    # In the following code snippet, we mock the response.
    mock_weather_data = {"Seattle": "Sunny, 25°C", "London": "Cloudy, 18°C", "Tokyo": "Rainy, 22°C"}
    weather = mock_weather_data.get(location, "Weather data not available for this location.")
    weather_json = json.dumps({"weather": weather})
    return weather_json

user_functions: Set[Callable[..., Any]] = {
    fetch_weather,
}

# Add tools that the agent will use. 
functions = FunctionTool(user_functions)

toolset = ToolSet()
toolset.add(functions)

AGENT_NAME = "Seattle Tourist Assistant"

إذا استخدمت Foundry (غير المركز) project، أنشئ وكيلا باستخدام مجموعة الأدوات كما يلي:

‏‫ملاحظة‬

إذا كنت تستخدم projectFoundry Hub> (الذي يدعم فقط الإصدارات الأدنى من و )، انتقل إلى أحدث مكتبة عملاء Python الخاصة ب Foundry Agent Service. لمزيد من المعلومات، راجع Foundry project تم إعدادها لتسجيل نتائج تقييم الدفعات.

قم بإنشاء عامل باستخدام مجموعة الأدوات على النحو التالي:

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

# Create an Azure AI Client from an endpoint, copied from your Foundry project.
# You need to login to Azure subscription via Azure CLI and set the environment variables
# Foundry project endpoint, example: AZURE_AI_PROJECT=https://your-account.services.ai.azure.com/api/projects/your-project
project_endpoint = os.environ["AZURE_AI_PROJECT"]  # Ensure the PROJECT_ENDPOINT environment variable is set

# Create an AIProjectClient instance
project_client = AIProjectClient(
    endpoint=project_endpoint,
    credential=DefaultAzureCredential(),  # Use Azure Default Credential for authentication
)

# Create an agent with the toolset 
agent = project_client.agents.create_agent(
    model=os.environ["MODEL_DEPLOYMENT_NAME"],  # Model deployment name
    name="my-agent",  # Name of the agent
    instructions="You are a helpful agent",  # Instructions for the agent
    toolset=toolset
)
print(f"Created agent, ID: {agent.id}")

# Create a thread for communication
thread = project_client.agents.threads.create()
print(f"Created thread, ID: {thread.id}")

# Add a message to the thread
message = project_client.agents.messages.create(
    thread_id=thread.id,
    role="user",  # Role of the message sender
    content="What is the weather in Seattle today?",  # Message content
)
print(f"Created message, ID: {message['id']}")

# Create and process an agent run
run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
print(f"Run finished with status: {run.status}")

# Check if the run failed
if run.status == "failed":
    print(f"Run failed: {run.last_error}")

# Fetch and log all messages
messages = project_client.agents.messages.list(thread_id=thread.id)
for message in messages:
    print(f"Role: {message.role}, Content: {message.content}")

تقييم تشغيل عامل واحد

بعد إنشاء تشغيل الوكلاء، استخدم المحول لتحويل بيانات خيط وكيل Microsoft Foundry إلى بيانات التقييم المطلوبة التي يمكن للمقيمين فهمها.

import json, os
from azure.ai.evaluation import AIAgentConverter, IntentResolutionEvaluator

# Initialize the converter for Microsoft Foundry agents.
converter = AIAgentConverter(project_client)

# Specify the thread and run ID.
thread_id = thread.id
run_id = run.id

converted_data = converter.convert(thread_id, run_id)

هكذا! converted_data يحتوي على جميع المدخلات المطلوبة لهؤلاء المقيمين. لا تحتاج إلى قراءة متطلبات الإدخال لكل مقيم أو القيام بأي عمل لتحليل المدخلات. اختر المقيم واتصل به في هذه الجولة الواحدة. اعتمادا على المقيمين، ندعم Azure OpenAI >أو OpenAI <نماذج الاستدلال ونماذج غير الاستدلالية للحكم:

Evaluators نماذج الاستدلالية كحكم (مثال: نماذج السلسلة o من Azure OpenAI / OpenAI) النماذج غير المنطقية كقاض (على سبيل المثال: gpt-4.1، gpt-4o، وما إلى ذلك) لتمكين
جميع مقيمي الجودة باستثناء GroundednessProEvaluator مدعوم مدعوم تعيين معلمة is_reasoning_model=True إضافية في تهيئة المقيمين
GroundednessProEvaluator المستخدم لا يحتاج إلى دعم النموذج المستخدم لا يحتاج إلى دعم النموذج --

للمهام المعقدة التي تتطلب تفكيرا دقيقا للتقييم، استخدم نموذج استدلالات قوي مثل o3-mini نماذج السلسلة O-Series المصغرة التي تصدر لاحقا لتحقيق توازن بين أداء الاستدلال وكفاءة التكلفة.

تقوم بإعداد قائمة بمقيمين الجودة والسلامة في quality_evaluators و safety_evaluators. تشير إليها عند تقييم عدة عوامل أو في سلسلة من الوكلاء.

# This is specific to agentic workflows.
from azure.ai.evaluation import IntentResolutionEvaluator, TaskAdherenceEvaluator, ToolCallAccuracyEvaluator 
# Other quality, risk, and safety metrics:
from azure.ai.evaluation import RelevanceEvaluator, CoherenceEvaluator, CodeVulnerabilityEvaluator, ContentSafetyEvaluator, IndirectAttackEvaluator, FluencyEvaluator
from azure.identity import DefaultAzureCredential

import os
from dotenv import load_dotenv
load_dotenv()

model_config = {
    "azure_deployment": os.getenv("AZURE_DEPLOYMENT_NAME"),
    "api_key": os.getenv("AZURE_API_KEY"),
    "azure_endpoint": os.getenv("AZURE_ENDPOINT"),
    "api_version": os.getenv("AZURE_API_VERSION"),
}

# example config for a reasoning model
reasoning_model_config = {
    "azure_deployment": "o3-mini",
    "api_key": os.getenv("AZURE_API_KEY"),
    "azure_endpoint": os.getenv("AZURE_ENDPOINT"),
    "api_version": os.getenv("AZURE_API_VERSION"),
}

# Evaluators you might want to use with reasoning models 
quality_evaluators = {evaluator.__name__: evaluator(model_config=reasoning_model_config, is_reasoning_model=True) for evaluator in [IntentResolutionEvaluator, TaskAdherenceEvaluator, ToolCallAccuracyEvaluator]}

# Other evaluators you might NOT want to use with reasoning models 
quality_evaluators.update({ evaluator.__name__: evaluator(model_config=model_config) for evaluator in [CoherenceEvaluator, FluencyEvaluator, RelevanceEvaluator]})

## Using Foundry (non-Hub) project endpoint, example: AZURE_AI_PROJECT=https://your-account.services.ai.azure.com/api/projects/your-project
azure_ai_project = os.environ.get("AZURE_AI_PROJECT")

safety_evaluators = {evaluator.__name__: evaluator(azure_ai_project=azure_ai_project, credential=DefaultAzureCredential()) for evaluator in [ContentSafetyEvaluator, IndirectAttackEvaluator, CodeVulnerabilityEvaluator]}

# Reference the quality and safety evaluator list above.
quality_and_safety_evaluators = {**quality_evaluators, **safety_evaluators}

for name, evaluator in quality_and_safety_evaluators.items():
    result = evaluator(**converted_data)
    print(name)
    print(json.dumps(result, indent=4))

تنسيق الإخراج

يقوم مقيمو الجودة المدعومون بمساعدة الذكاء الاصطناعي بإعادة نتيجة لزوج استعلام واستجابة. والنتيجة هي قاموس يشمل:

  • {metric_name}: يوفر درجة رقمية، على مقياس Likert (عدد صحيح من 1 إلى 5) أو عائم بين 0 و1.
  • {metric_name}_label: يوفر تسمية ثنائية إذا كان المقياس ينتج بشكل طبيعي درجة ثنائية.
  • {metric_name}_reason: يشرح سبب إعطاء درجة أو تسمية معينة لكل نقطة بيانات.
  • detailsإخراج اختياري يحتوي على معلومات تصحيح الأخطاء حول جودة تشغيل عامل واحد.:

لتحسين clarity، يقبل جميع المقيمين عتبة ثنائية (ما لم تكن مخرجاتهم ثنائية بالفعل) ويولدون مفتاحين جديدين. بالنسبة إلى حد الربط، يتم تعيين افتراضي، والذي يمكن للمستخدم تجاوزه. المفتاحان الجديدان هما:

  • {metric_name}_result: سلسلة "تمرير" أو "فشل" استنادا إلى حد الازرار.
  • {metric_name}_threshold: حد ثنائي رقمي معين افتراضيا أو من قبل المستخدم.

راجع إخراج المثال التالي لبعض المقيمين:

{
    "intent_resolution": 5.0, # likert scale: 1-5 integer 
    "intent_resolution_threshold": 3,
    "intent_resolution_result": "pass", # pass because 5 > 3 the threshold
    "intent_resolution_reason": "The assistant correctly understood the user's request to fetch the weather in Seattle. It used the appropriate tool to get the weather information and provided a clear and accurate response with the current weather conditions in Seattle. The response fully resolves the user's query with all necessary information."
}
{
    "task_adherence": 5.0, # likert scale: 1-5 integer 
    "task_adherence_threshold": 3,
    "task_adherence_result": "pass", # pass because 5 > 3 the threshold
    "task_adherence_reason": "The response accurately follows the instructions, fetches the correct weather information, and relays it back to the user without any errors or omissions."
}
{
    "tool_call_accuracy": 5,  # a score between 1-5, higher is better
    "tool_call_accuracy_threshold": 3,
    "tool_call_accuracy_result": "pass", # pass because 5 > 3 the threshold
    "details": { ... } # helpful details for debugging the tool calls made by the agent
}

تقييم عمليات تشغيل عامل متعددة أو مؤشرات الترابط

لتقييم تشغيل أو خيوط متعددة للوكلاء، استخدم واجهة برمجة التطبيقات الدفعية evaluate() للتقييم غير المتزامن. أولا، حول بيانات خيط الوكيل إلى ملف باستخدام دعم المحول:

import json
from azure.ai.evaluation import AIAgentConverter

# Initialize the converter.
converter = AIAgentConverter(project_client)

# Specify a file path to save the agent output (evaluation input data) to.
filename = os.path.join(os.getcwd(), "evaluation_input_data.jsonl")

evaluation_data = converter.prepare_evaluation_data(thread_ids=thread_id, filename=filename) 

print(f"Evaluation data saved to {filename}")

من خلال إعداد بيانات التقييم في سطر واحد من الكود، يمكنك اختيار المقيمين لتقييم جودة الوكيل وتقديم تقييم دفعي. في المثال التالي، يرجى الرجوع إلى نفس قائمة مقيم الجودة والسلامة في قسم تقييم تشغيلquality_and_safety_evaluators وكيل واحد:

import os
from dotenv import load_dotenv
load_dotenv()

# Batch evaluation API (local):
from azure.ai.evaluation import evaluate

response = evaluate(
    data=filename,
    evaluation_name="agent demo - batch run",
    evaluators=quality_and_safety_evaluators,
    # optionally, log your results to your Foundry project for rich visualization 
    azure_ai_project=os.environ.get("AZURE_AI_PROJECT"),  # example: https://your-account.services.ai.azure.com/api/projects/your-project
)
# Inspect the average scores at a high level.
print(response["metrics"])
# Use the URL to inspect the results on the UI.
print(f'Foundry URL: {response.get("studio_url")}')

بعد اختيار الرابط، يتم إعادة توجيهك إلى Foundry. عرض نتائج التقييم في project Foundry الخاص بك وقم بتصحيح أخطاء تطبيقك. استخدم حقول المنطق ونتائج النجاح/الرسوب لتقييم جودة وأداء طلباتك في السلامة. يمكنك تشغيل عمليات تشغيل متعددة ومقارنتها لاختبار التراجع أو التحسينات.

استخدم مكتبة عميل Azure AI Evaluation SDK لتقييم وكلاء Microsoft Foundry مع دعم المحولات، مما يتيح الملاحظة والشفافية في سير عمل الوكلاء.

تقييم العوامل الأخرى

إذا استخدمت وكلاء خارج خدمة الوكلاء، يمكنك تقييمهم من خلال إعداد البيانات المناسبة للمقيمين الذين تختارهم.

عادة ما يرسل الوكلاء رسائل للتفاعل مع المستخدم أو وكلاء آخرين. تقبل المقيمون المدمجين أنواع بيانات بسيطة مثل السلاسل في query، response، ووفقا ground_truthلمتطلبات إدخال البيانات ذات الدور الواحد. ومع ذلك، قد يكون استخراج هذه الأنواع البسيطة من بيانات الوكلاء تحديا بسبب أنماط التفاعل المعقدة بين الوكلاء واختلافات الأطر. على سبيل المثال، يمكن لاستعلام مستخدم واحد تشغيل قائمة طويلة من رسائل العامل، عادة مع استدعاءات أدوات متعددة تم استدعاؤها.

كما هو موضح في المثال التالي، يمكنك تمكين دعم رسائل الوكيل للمقيمين المدمجين التاليين لتقييم هذه الجوانب من سير العمل الوكيلي. قد يأخذ tool_callstool_definitions هؤلاء المقيمون أو كمعايير فريدة للوكلاء عند تقييم الوكلاء.

Evaluator query response tool_calls tool_definitions
IntentResolutionEvaluator مطلوب: Union[str, list[Message]] مطلوب: Union[str, list[Message]] لا ينطبق اختياري: list[ToolCall]
ToolCallAccuracyEvaluator مطلوب: Union[str, list[Message]] اختياري: Union[str, list[Message]] اختياري: Union[dict, list[ToolCall]] مطلوب: list[ToolDefinition]
TaskAdherenceEvaluator مطلوب: Union[str, list[Message]] مطلوب: Union[str, list[Message]] لا ينطبق اختياري: list[ToolCall]
GroundednessEvaluator مطلوب: Union[str, list[Message]] مطلوب: Union[str, list[Message]] لا ينطبق مطلوب: list[ToolCall]
  • Message: dict رسالة على غرار OpenAI تصف تفاعلات العامل مع مستخدم، حيث query يجب أن يتضمن رسالة النظام كرسالة أولى.
  • ToolCall: dict الذي يحدد استدعاءات الأداة التي تم استدعاؤها أثناء تفاعلات العامل مع المستخدم.
  • ToolDefinition: dict الذي يصف الأدوات المتاحة للعامل.

ل ToolCallAccuracyEvaluator، يجب عليك توفير إما response أو tool_calls.

GroundednessEvaluator يتطلب tool_definitions تقييم مدى تأريض استجابات الوكيل بالنسبة لمخرجات الأدوات التي يستقبلها الوكيل.

الأمثلة التالية تظهر تنسيقي البيانات: بيانات الوكيل البسيطة ورسائل الوكيل. ومع ذلك، وبسبب المتطلبات الفريدة لهؤلاء المقيمين، يرجى الرجوع إلى دفاتر العينات التي توضح مسارات الإدخال الممكنة لكل مقيم.

جميع مقيمات الجودة المدمجة المدعومة بمساعدة الذكاء الاصطناعي تخرج نجاحا أو رسولا لكل مدخل.

بيانات الوكيل البسيطة

في صيغة بيانات الوكلاء البسيطة، query و response هي سلاسل بايثون بسيطة. على سبيل المثال: 

import os
import json
from azure.ai.evaluation import AzureOpenAIModelConfiguration
from azure.identity import DefaultAzureCredential
from azure.ai.evaluation import IntentResolutionEvaluator, ResponseCompletenessEvaluator
  
model_config = AzureOpenAIModelConfiguration(
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    api_version=os.environ["AZURE_OPENAI_API_VERSION"],
    azure_deployment=os.environ["MODEL_DEPLOYMENT_NAME"],
)
 
intent_resolution_evaluator = IntentResolutionEvaluator(model_config)

# Evaluate the query and response as strings.
# The following is a positive example. Intent is identified and understood and the response correctly resolves user intent.
result = intent_resolution_evaluator(
    query="What are the opening hours of the Eiffel Tower?",
    response="Opening hours of the Eiffel Tower are 9:00 AM to 11:00 PM.",
)
print(json.dumps(result, indent=4))

انظر المخرج التالي (راجع تنسيق الإخراج للتفاصيل):

{
    "intent_resolution": 5.0,
    "intent_resolution_result": "pass",
    "intent_resolution_threshold": 3,
    "intent_resolution_reason": "The response provides the opening hours of the Eiffel Tower, which directly addresses the user's query. The information is clear, accurate, and complete, fully resolving the user's intent.",
}

استدعاءات أداة الوكيل والتعريفات

راجع الأمثلة التالية ل tool_calls و tool_definitions ل ToolCallAccuracyEvaluator:

import json 

query = "How is the weather in Seattle?"
tool_calls = [{
                    "type": "tool_call",
                    "tool_call_id": "call_CUdbkBfvVBla2YP3p24uhElJ",
                    "name": "fetch_weather",
                    "arguments": {
                        "location": "Seattle"
                    }
            },
            {
                    "type": "tool_call",
                    "tool_call_id": "call_CUdbkBfvVBla2YP3p24uhElJ",
                    "name": "fetch_weather",
                    "arguments": {
                        "location": "London"
                    }
            }]

tool_definitions = [{
                    "name": "fetch_weather",
                    "description": "Fetches the weather information for the specified location.",
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "location": {
                                "type": "string",
                                "description": "The location to fetch weather for."
                            }
                        }
                    }
                }]

from azure.ai.evaluation import ToolCallAccuracyEvaluator

tool_call_accuracy = ToolCallAccuracyEvaluator(model_config) # reuse the config defined above
response = tool_call_accuracy(query=query, tool_calls=tool_calls, tool_definitions=tool_definitions)
print(json.dumps(response, indent=4))

انظر الإخراج التالي ( تنسيق الإخراج المرجعي للحصول على التفاصيل):

{
    "tool_call_accuracy": 3,  # a score between 1-5, higher is better
    "tool_call_accuracy_result": "fail",
    "tool_call_accuracy_threshold": 4,
    "details": { ... } # helpful details for debugging the tool calls made by the agent
}

مخطط رسالة الوكيل

في صيغة رسالة الوكيل، query و response هي قوائم برسائل على نمط OpenAI. تحديدا، query يحمل التفاعلات السابقة بين الوكيل والمستخدم التي تؤدي إلى آخر استفسار للمستخدم ويتطلب رسالة النظام (للوكيل) في أعلى القائمة. response تحمل آخر رسالة من الوكيل استجابة لآخر استفسار للمستخدم.

تنسيق الإدخال المتوقع للمقيمين هو قائمة رسائل Python على النحو التالي:

[
  {
    "role": "system" | "user" | "assistant" | "tool",
    "createdAt": "ISO 8601 timestamp",     // Optional for 'system'
    "run_id": "string",                    // Optional, only for assistant/tool in tool call context
    "tool_call_id": "string",              // Optional, only for tool/tool_result
    "name": "string",                      // Present if it's a tool call
    "arguments": { ... },                  // Parameters passed to the tool (if tool call)
    "content": [
      {
        "type": "text" | "tool_call" | "tool_result",
        "text": "string",                  // if type == text
        "tool_call_id": "string",         // if type == tool_call
        "name": "string",                 // tool name if type == tool_call
        "arguments": { ... },             // tool args if type == tool_call
        "tool_result": { ... }            // result if type == tool_result
      }
    ]
  }
]

نموذج كائنات الاستعلام والاستجابة:

query = [
    {
        "role": "system",
        "content": "You are an AI assistant interacting with Azure Maps services to serve user requests."
    },
    {
        "createdAt": "2025-04-25T23:55:43Z",
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Find the address for coordinates 41.8781,-87.6298."
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:45Z",
        "run_id": "run_DGE8RWPS8A9SmfCg61waRx9u",
        "role": "assistant",
        "content": [
            {
                "type": "tool_call",
                "tool_call_id": "call_nqNyhOFRw4FmF50jaCCq2rDa",
                "name": "azure_maps_reverse_address_search",
                "arguments": {
                    "lat": "41.8781",
                    "lon": "-87.6298"
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:47Z",
        "run_id": "run_DGE8RWPS8A9SmfCg61waRx9u",
        "tool_call_id": "call_nqNyhOFRw4FmF50jaCCq2rDa",
        "role": "tool",
        "content": [
            {
                "type": "tool_result",
                "tool_result": {
                    "address": "300 South Federal Street, Chicago, IL 60604",
                    "position": {
                        "lat": "41.8781",
                        "lon": "-87.6298"
                    }
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:48Z",
        "run_id": "run_DGE8RWPS8A9SmfCg61waRx9u",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "The address for the coordinates 41.8781, -87.6298 is 300 South Federal Street, Chicago, IL 60604."
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:50Z",
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "What timezone corresponds to 41.8781,-87.6298?"
            }
        ]
    },
]

response = [
    {
        "createdAt": "2025-04-25T23:55:52Z",
        "run_id": "run_DmnhUGqYd1vCBolcjjODVitB",
        "role": "assistant",
        "content": [
            {
                "type": "tool_call",
                "tool_call_id": "call_qi2ug31JqzDuLy7zF5uiMbGU",
                "name": "azure_maps_timezone",
                "arguments": {
                    "lat": 41.878100000000003,
                    "lon": -87.629800000000003
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:54Z",
        "run_id": "run_DmnhUGqYd1vCBolcjjODVitB",
        "tool_call_id": "call_qi2ug31JqzDuLy7zF5uiMbGU",
        "role": "tool",
        "content": [
            {
                "type": "tool_result",
                "tool_result": {
                    "ianaId": "America/Chicago",
                    "utcOffset": None,
                    "abbreviation": None,
                    "isDaylightSavingTime": None
                }
            }
        ]
    },
    {
        "createdAt": "2025-04-25T23:55:55Z",
        "run_id": "run_DmnhUGqYd1vCBolcjjODVitB",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "The timezone for the coordinates 41.8781, -87.6298 is America/Chicago."
            }
        ]
    }
]

‏‫ملاحظة‬

يعرض المقيم تحذيرا إذا لم يكن الاستعلام (سجل المحادثة حتى الجولة الحالية) أو استجابة الوكيل (الاستجابة للاستفسار) بالشكل المتوقع.

لمثال على تقييم رسائل الوكيل باستخدام ToolCallAccuracyEvaluator، انظر:

import json

# The user asked a question.
query = [
    {
        "role": "system",
        "content": "You are a friendly and helpful customer service agent."
    },
    # Past interactions are omitted. 
    # ...
    {
        "createdAt": "2025-03-14T06:14:20Z",
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": "Hi, I need help with the last 2 orders on my account #888. Could you please update me on their status?"
            }
        ]
    }
]
# The agent emits multiple messages to fulfill the request.
response = [
    {
        "createdAt": "2025-03-14T06:14:30Z",
        "run_id": "0",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "Hello! Let me quickly look up your account details."
            }
        ]
    },
    {
        "createdAt": "2025-03-14T06:14:35Z",
        "run_id": "0",
        "role": "assistant",
        "content": [
            {
                "type": "tool_call",
                "tool_call_id": "tool_call_20250310_001",
                "name": "get_orders",
                "arguments": {
                    "account_number": "888"
                }
            }
        ]
    },
    # Many more messages are omitted. 
    # ...
    # Here is the agent's final response:
    {
        "createdAt": "2025-03-14T06:15:05Z",
        "run_id": "0",
        "role": "assistant",
        "content": [
            {
                "type": "text",
                "text": "The order with ID 123 has been shipped and is expected to be delivered on March 15, 2025. However, the order with ID 124 is delayed and should now arrive by March 20, 2025. Is there anything else I can help you with?"
            }
        ]
    }
]

# An example of tool definitions available to the agent:
tool_definitions = [
    {
        "name": "get_orders",
        "description": "Get the list of orders for a given account number.",
        "parameters": {
            "type": "object",
            "properties": {
                "account_number": {
                    "type": "string",
                    "description": "The account number to get the orders for."
                }
            }
        }
    },
    # Other tool definitions are omitted. 
    # ...
]

result = tool_call_accuracy(
    query=query,
    response=response,
    tool_definitions=tool_definitions 
)
print(json.dumps(result, indent=4))

انظر الإخراج التالي ( تنسيق الإخراج المرجعي للحصول على التفاصيل):

{
    "tool_call_accuracy": 2,  # a score between 1-5, higher is better
    "tool_call_accuracy_result": "fail",
    "tool_call_accuracy_threshold": 3,
    "details": { ... } # helpful details for debugging the tool calls made by the agent
}

يساعد مخطط التقييم هذا في تحليل بيانات الوكيل خارج خدمة الوكلاء، مما يتيح استخدام مقيمين مدمجين لدعم قابلية الملاحظة في سير عمل الوكلاء.

دفاتر ملاحظات العينة

جرب عينة لكل من هؤلاء المقيمين:

المحتوى ذو الصلة

  • Last updated on