Öğretici: Fikirden prototipe - Kurumsal ajan oluşturma ve değerlendirme

Bu öğretici, Microsoft Foundry geliştirici yolculuğunun ilk aşamasını kapsar: bir ilk fikirden çalışan bir prototipe. Microsoft Foundry SDK'sını kullanarak iç şirket bilgilerini dış teknik rehberlikle birleştiren modern workplace assistant oluşturursunuz.

İş senaryosu: Şunları birleştirerek çalışanlara yardımcı olan bir yapay zeka yardımcısı oluşturun:

  • Şirket politikaları (SharePoint belgelerinden)
  • Teknik uygulama kılavuzu (MCP aracılığıyla Microsoft Learn'den)
  • Eksiksiz çözümler (işletme uygulaması için her iki kaynağı birleştirme)
  • Gerçekçi iş senaryolarında ajan performansını doğrulamak için toplu değerlendirme

Kılavuz Sonucu: Sonunda ilke, teknik ve birleştirilmiş uygulama sorularını yanıtlayan çalışır durumda bir Modern Workplace Asistanı'na sahip olursunuz; yinelenebilir bir toplu değerlendirme betiği; ve açık uzantı noktaları (diğer araçlar, çoklu ajan desenleri, daha zengin değerlendirme).

Şunu yapacaksınız:

  • SharePoint ve MCP tümleştirmesi ile Modern Çalışma Alanı Yardımcısı oluşturun.
  • İç ve dış bilgileri birleştiren gerçek iş senaryolarını gösterme.
  • Güçlü hata işleme ve düzgün bir düşüş uygulayın.
  • İş odaklı test için değerlendirme çerçevesi oluşturun.
  • İdare ve üretim dağıtımı için temel hazırlama.

Bu minimum örnek, gerçekçi iş senaryolarıyla kurumsal kullanıma hazır desenleri gösterir.

Önemli

Bu makaledeki kod, şu anda önizleme aşamasında olan paketleri kullanır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve üretim iş yükleri için önerilmez. Bazı özellikler desteklenmeyebilir veya kısıtlı özelliklere sahip olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Uygun Kullanım Koşulları.

Önkoşullar

  • Azure aboneliği. Yoksa ücretsiz bir tane oluşturun.

  • az login ile kimliği doğrulanmış Azure CLI 2.67.0 veya üzeri (az version ile denetleyin)

  • Bir modelin dağıtıldığı bir Foundry projesi (örneğin, gpt-4o-mini). Yoksa: Proje oluşturma ve ardından bir model dağıtma (bkz. modele genel bakış: Model kataloğu).

  • Python 3.10 veya üzeri

  • .NET SDK 8.0 veya üzeri (C# örneği için)

  • Projenizde yapılandırılmış SharePoint bağlantı (SharePoint araç belgeleri)

    Not

    Foundry projenizi SharePoint bağlantı için yapılandırmak için SharePoint araç belgelerine bakın.

  • (İsteğe bağlı) Örnek depoyu kopyalamaya yönelik Git yüklendi

Önemli

Bu makale yayımlandıktan sonra SDK sürümleri ve örnek depo yapısı değişebilir. Başlamadan önce, en son kurulum yönergeleri, gerekli paket sürümleri ve ortam yapılandırması için örnek depo BENİ OKU dosyasını kontrol edin. Bu öğreticide başvuruda bulunulan bir sürüm PyPI veya NuGet sürümlerinde kullanılamıyorsa, bunun yerine en son yayımlanan sürümü kullanın.

1. Adım: Örnek kodu alma

Büyük bir depo ağacında gezinmek yerine şu yaklaşımlardan birini kullanın:

A Seçeneği (tüm örnek depolarını kopyalama)

Ipucu

Kod, Azure AI Projeleri 2.x kullanır ve Azure AI Projeleri 1.x ile uyumlu değildir. Azure AI Projects 1.x sürümü için Foundry (klasik) belgelerini görüntüleyin.

git clone --depth 1 https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples/samples/python/enterprise-agent-tutorial/1-idea-to-prototype

B Seçeneği (yalnızca bu öğreticiyi seyrek kullanıma alma - azaltılmış indirme)

git clone --no-checkout https://github.com/microsoft-foundry/foundry-samples.git
cd foundry-samples
git sparse-checkout init --cone
git sparse-checkout set samples/python/enterprise-agent-tutorial/1-idea-to-prototype
git checkout
cd samples/python/enterprise-agent-tutorial/1-idea-to-prototype

C Seçeneği (Deponun ZIP'ini indirin)

Depo ZIP'ini indirin, yerel ortamınıza ayıklayın ve öğretici klasörüne gidin.

Önemli

Üretim ortamına uygunluk için bağımsız bir depo kullanın. Bu öğreticide paylaşılan örnekler deposu kullanılır. Seyrek kullanıma alma işlemi yerel gürültüyü en aza indirir.

Python kodunu şimdi indir

ZIP'i ayıkladıktan sonra samples/python/enterprise-agent-tutorial/1-idea-to-prototype adresine gidin.

En düşük yapı yalnızca temel dosyaları içerir:

enterprise-agent-tutorial/
└── 1-idea-to-prototype/
   ├── .env                             # Create this file (local environment variables)
   ├── .gitkeep
   ├── evaluate.py                      # Business evaluation framework
   ├── evaluation_results.json
   ├── main.py                          # Modern Workplace Assistant
   ├── questions.jsonl                  # Business test scenarios (4 questions)
   ├── requirements.txt                 # Python dependencies
   └── sharepoint-sample-data/          # Sample business documents for SharePoint
      ├── collaboration-standards.docx
      ├── data-governance-policy.docx
      ├── remote-work-policy.docx
      └── security-guidelines.docx

2. Adım: Örneği hemen çalıştırın

Uygulama ayrıntılarına geçmeden önce çalışan işlevselliği görmek için aracıyı çalıştırarak başlayın.

Ortam kurulumu ve sanal ortam

  1. Geliştirme ortamınızı hazırlama bölümünde açıklandığı gibi gerekli dil çalışma zamanlarını, genel araçları ve VS Code uzantılarını yükleyin.

  2. requirements.txt Bu yayımlanan paket sürümlerini kullandığınızı doğrulayın:

    azure-ai-projects>=2.3.0
azure-identity
python-dotenv

  3. Bağımlılıkları yükleme:

    python -m pip install -r requirements.txt

    Yüklemenin başarılı olduğunu doğrulayın. Restore completed (Python) veya Successfully installed azure-ai-projects-... (.NET) hata olmadan görürsünüz.

  4. Projenin hoş geldiniz ekranında proje uç noktanızı bulun.

    Microsoft Foundry Modellerinin karşılama ekranının ekran görüntüsü, endpoint URL'sini ve kopyala düğmesini gösteriyor.

  5. öğesini yapılandırın .env.

    Diliniz için gereken ortam değerlerini ayarlayın.

.env.template konumunu .env kopyalayın.

# Foundry configuration
FOUNDRY_PROJECT_ENDPOINT=https://<your-resource>.services.ai.azure.com/api/projects/<your-project>
FOUNDRY_MODEL_NAME=gpt-4o-mini

# The Microsoft Learn MCP Server (optional)
MCP_SERVER_URL=https://learn.microsoft.com/api/mcp

# SharePoint integration (optional - requires connection name)
SHAREPOINT_CONNECTION_NAME=<your-sharepoint-connection-name>

Dosyayı açarak .env'ın geçerli değerler içerip içermediğini kontrol edin. Bunun için FOUNDRY_PROJECT_ENDPOINT'in https:// ile başlayıp FOUNDRY_MODEL_NAME'ün projenizde dağıtılan modelin adıyla eşleştiğini doğrulayın.

Ipucu

Kiracı kimliğinizi almak için şunu çalıştırın:

# Get tenant ID
az account show --query tenantId -o tsv

Proje uç noktanızı almak için, projenizi Dökümhane portalında açın ve burada gösterilen değeri kopyalayın.

Aracıyı ve değerlendirmeyi çalıştırma

python main.py
python evaluate.py

Beklenen çıkış (aracı ilk çalıştırma)

SharePoint ile başarılı çalıştırma:

🤖 Creating Modern Workplace Assistant...
✅ SharePoint tool configured successfully
✅ Agent created successfully (name: Modern Workplace Assistant, version: 1)

SharePoint olmadan zarif bozulma

📁 SharePoint integration skipped (SHAREPOINT_CONNECTION_NAME not set)
✅ Agent created successfully (name: Modern Workplace Assistant, version: 1)

Artık çalışan bir ajanınız olduğuna göre, sonraki bölümlerde nasıl çalıştığı açıklanacaktır. Bu bölümleri okurken herhangi bir işlem yapmanız gerekmez; bunlar açıklama içindir.

3. Adım: Örnek SharePoint iş belgelerini ayarlama

  1. SharePoint sitenize gidin (bağlantıda yapılandırılır).

  2. "Şirket İlkeleri" belge kitaplığı oluşturun (veya mevcut "Belgeler"i kullanın).

  3. sharepoint-sample-data klasöründe sağlanan dört örnek Word belgesini karşıya yükleyin:

    • remote-work-policy.docx
    • security-guidelines.docx
    • collaboration-standards.docx
    • data-governance-policy.docx

  4. Devam etmeden önce kitaplıkta dört belgenin göründüğünü doğrulayın.

Örnek yapı

📁 Company Policies/
├── remote-work-policy.docx      # VPN, MFA, device requirements
├── security-guidelines.docx     # Azure security standards
├── collaboration-standards.docx # Teams, SharePoint usage
└── data-governance-policy.docx  # Data classification, retention

Asistan uygulamasını anlayın

Not

Bu bölüm yalnızca başvuru amaçlıdır; eylem gerekmez. Zaten çalıştırdığınız kodu açıklar.

Bu bölümde main.py (Python) veya ModernWorkplaceAssistant/Program.cs (C#) içindeki çekirdek kod açıklanmaktadır. Ajanı zaten çalıştırdın. Okuduktan sonra şunları yapabilirsiniz:

  • Yeni iç ve dış veri araçları ekleyin.
  • Dinamik yönergeleri genişletin.
  • Çoklu etmen orkestrasyonunu tanıtın.
  • Gözlemlenebilirliği ve tanılamayı geliştirin.

Kod aşağıdaki ana bölümlere ayrılır ve tam örnek kodda göründükleri şekilde sıralanır:

  1. İçeri aktarmaları ve kimlik doğrulamayı yapılandırma
  2. Azure için kimlik doğrulamasını yapılandırın
  3. SharePoint aracını yapılandırın
  4. MCP aracını yapılandırma
  5. Aracıyı oluşturma ve araçları bağlama
  6. Ajan ile konuş

Önemli

Bu makaledeki kod, şu anda önizleme aşamasında olan paketleri kullanır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve üretim iş yükleri için önerilmez. Bazı özellikler desteklenmeyebilir veya kısıtlı özelliklere sahip olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Uygun Kullanım Koşulları.

İçe aktarma ve kimlik doğrulaması kurulumu

Kod, sağlam bir kurumsal aracı oluşturmak için Microsoft Foundry SDK'sından birkaç istemci kitaplığı kullanır.

import os
import time
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    SharepointPreviewTool,
    SharepointGroundingToolParameters,
    ToolProjectConnection,
    MCPTool,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv
from openai.types.responses.response_input_param import (
    McpApprovalResponse,
)

Azure'de kimlik doğrulamayı yapılandırma

Ajanınızı oluşturmadan önce, Foundry için kimlik doğrulaması ayarlarını yapın.

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    print(f"✅ Connected to Foundry: {endpoint}")

Acente için SharePoint aracını oluşturma

Temsilci SharePoint kullanır ve orada depolanan şirket politika ve prosedür belgelerine erişebilir. Kodunuzda SharePoint bağlantısını ayarlayın.

sharepoint_connection_id = os.environ.get("SHAREPOINT_CONNECTION_ID")
sharepoint_tool = None

if sharepoint_connection_id:
    print("📁 Configuring SharePoint integration...")
    print(f"   Connection ID: {sharepoint_connection_id}")

    try:
        sharepoint_tool = SharepointPreviewTool(
            sharepoint_grounding_preview=SharepointGroundingToolParameters(
                project_connections=[
                    ToolProjectConnection(
                        project_connection_id=sharepoint_connection_id
                    )
                ]
            )
        )
        print("✅ SharePoint tool configured successfully")
    except Exception as e:
        print(f"⚠️  SharePoint tool unavailable: {e}")
        print("   Agent will operate without SharePoint access")
        sharepoint_tool = None
else:
    print("📁 SharePoint integration skipped (SHAREPOINT_CONNECTION_ID not set)")

Temsilci için MCP aracını oluştur

mcp_server_url = os.environ.get("MCP_SERVER_URL")
mcp_tool = None

if mcp_server_url:
    print("📚 Configuring Microsoft Learn MCP integration...")
    print(f"   Server URL: {mcp_server_url}")

    try:
        mcp_tool = MCPTool(
            server_url=mcp_server_url,
            server_label="Microsoft_Learn_Documentation",
            require_approval="always",
        )
        print("✅ MCP tool configured successfully")
    except Exception as e:
        print(f"⚠️  MCP tool unavailable: {e}")
        print("   Agent will operate without Microsoft Learn access")
        mcp_tool = None
else:
    print("📚 MCP integration skipped (MCP_SERVER_URL not set)")

Aracı oluştur ve araçları bağla

Aracıyı oluşturun ve SharePoint ve MCP araçlarını bağlayın.

print(f"🛠️  Creating agent with model: {os.environ['FOUNDRY_MODEL_NAME']}")

tools = []
if sharepoint_tool:
    tools.append(sharepoint_tool)
    print("   ✓ SharePoint tool added")
if mcp_tool:
    tools.append(mcp_tool)
    print("   ✓ MCP tool added")

print(f"   Total tools: {len(tools)}")

agent = project_client.agents.create_version(
    agent_name="Modern Workplace Assistant",
    definition=PromptAgentDefinition(
        model=os.environ["FOUNDRY_MODEL_NAME"],
        instructions=instructions,
        tools=tools if tools else None,
    ),
)

print(f"✅ Agent created successfully (name: {agent.name}, version: {agent.version})")

Temsilci ile sohbet

Son olarak, aracıyla sohbet etmek için etkileşimli bir döngü uygulayın.

print("🤖 AGENT RESPONSE:")
response, status = create_agent_response(agent, scenario["question"], openai_client)

Agent örnek kodundan beklenen çıktı

Aracıyı çalıştırdığınızda aşağıdaki örneğe benzer bir çıkış görürsünüz. Çıkışta başarılı araç yapılandırması ve iş senaryolarına ilişkin ajan yanıtları gösterilir.

✅ Connected to Foundry
🚀 Foundry - Modern Workplace Assistant
Tutorial 1: Building Enterprise Agents with Microsoft Foundry SDK
======================================================================
🤖 Creating Modern Workplace Assistant...
📁 Configuring SharePoint integration...
   Connection ID: /subscriptions/.../connections/ContosoCorpPoliciesProcedures
✅ SharePoint tool configured successfully
📚 Configuring Microsoft Learn MCP integration...
   Server URL: https://learn.microsoft.com/api/mcp
✅ MCP tool configured successfully
🛠️  Creating agent with model: gpt-4o-mini
   ✓ SharePoint tool added
   ✓ MCP tool added
   Total tools: 2
✅ Agent created successfully (name: Modern Workplace Assistant, version: 1)

======================================================================
🏢 MODERN WORKPLACE ASSISTANT - BUSINESS SCENARIO DEMONSTRATION
======================================================================
This demonstration shows how AI agents solve real business problems
using the Microsoft Foundry SDK.
======================================================================

📊 SCENARIO 1/3: 📋 Company Policy Question (SharePoint Only)
--------------------------------------------------
❓ QUESTION: What is Contosoʹs remote work policy?
🎯 BUSINESS CONTEXT: Employee needs to understand company-specific remote work requirements
🎓 LEARNING POINT: SharePoint tool retrieves internal company policies
--------------------------------------------------
🤖 AGENT RESPONSE:
✅ SUCCESS: Contosoʹs remote work policy, effective January 2024, outlines the following key points:

### Overview
Contoso Corp supports flexible work arrangements, including remote work, to enhance employee productivity and work-life balance.

### Eligibility
- **Full-time Employees**: Must have completed a 90...
   📏 Full response: 1530 characters
📈 STATUS: completed
--------------------------------------------------

📊 SCENARIO 2/3: 📚 Technical Documentation Question (MCP Only)
--------------------------------------------------
❓ QUESTION: According to Microsoft Learn, what is the correct way to implement Microsoft Entra Conditional Access policies? Please include reference links to the official documentation.
🎯 BUSINESS CONTEXT: IT administrator needs authoritative Microsoft technical guidance
🎓 LEARNING POINT: MCP tool accesses Microsoft Learn for official documentation with links
--------------------------------------------------
🤖 AGENT RESPONSE:
✅ SUCCESS: To implement Microsoft Entra Conditional Access policies correctly, follow these key steps outlined in the Microsoft Learn documentation:

### 1. Understanding Conditional Access
Conditional Access policies act as "if-then" statements that enforce organizational access controls based on various signals. Th...
   📏 Full response: 2459 characters
📈 STATUS: completed
--------------------------------------------------

📊 SCENARIO 3/3: 🔄 Combined Implementation Question (SharePoint + MCP)
--------------------------------------------------
❓ QUESTION: Based on our companyʹs remote work security policy, how should I configure my Azure environment to comply? Please include links to Microsoft documentation showing how to implement each requirement.
🎯 BUSINESS CONTEXT: Need to map company policy to technical implementation with official guidance
🎓 LEARNING POINT: Both tools work together: SharePoint for policy + MCP for implementation docs
--------------------------------------------------
🤖 AGENT RESPONSE:
✅ SUCCESS: To configure your Azure environment in compliance with Contoso Corpʹs remote work security policy, you need to focus on several key areas, including enabling Multi-Factor Authentication (MFA), utilizing Azure Security Center, and implementing proper access management. Below are specific steps and li...
   📏 Full response: 3436 characters
📈 STATUS: completed
--------------------------------------------------

✅ DEMONSTRATION COMPLETED!
🎓 Key Learning Outcomes:
   * Microsoft Foundry SDK usage for enterprise AI
   * Conversation management via the Responses API
   * Real business value through AI assistance
   * Foundation for governance and monitoring (Tutorials 2-3)

🎯 Try interactive mode? (y/n): n

🎉 Sample completed successfully!
📚 This foundation supports Tutorial 2 (Governance) and Tutorial 3 (Production)
🔗 Next: Add evaluation metrics, monitoring, and production deployment

4. Adım: Toplu değerlendirmeyi kullanarak yardımcıyı değerlendirme

Değerlendirme çerçevesi, Microsoft Döküm SDK'sının batch değerlendirme özelliğini kullanarak gerçekçi iş senaryolarını test eder. Özel bir yerel yaklaşım yerine, bu desen bulutta ölçeklenebilir, tekrarlanabilir değerlendirmeler çalıştırmak için yerleşik değerlendiricileri (builtin.violence, builtin.fluency, builtin.task_adherence) ve openai_client.evals API'yi kullanır.

Bu değerlendirme çerçevesi şunu gösterir:

  • Aracı hedefleme: Değerlendirme, doğrudan aracınıza yönelik sorgular çalıştırmak için azure_ai_target_completions kullanır.
  • Yerleşik değerlendiriciler: Güvenlik (şiddet algılama), kalite (akıcılık) ve göreve bağlılık ölçümleri.
  • Bulut tabanlı yürütme: Yerel işlem gereksinimlerini ortadan kaldırır ve CI/CD tümleştirmesini destekler.
  • Yapılandırılmış sonuçlar: Her test çalışması için başarılı/başarısız etiketler, puanlar ve mantık yürütme.

Kod aşağıdaki ana bölümlere ayrılır:

  1. Değerlendirmeyi yapılandırın.
  2. Toplu değerlendirmeyi çalıştırın.
  3. Değerlendirme sonuçlarını alın.

Ipucu

Toplu değerlendirmeler hakkında ayrıntılı yönergeler için bkz. Değerlendirmeleri bulutta çalıştırma. Foundry'de kullanılabilen yerleşik değerlendiricilerin kapsamlı bir listesini bulmak için bkz. Oluşturucu yapay zekada gözlemlenebilirlik.

Not

C# örneği, Python'de gösterilen bulut ProjectResponsesClient API'si yerine openai_client.evals ile yerel bir toplu değerlendirme yaklaşımı kullanır. Aracıya sorgular gönderir, yanıtları beklenen anahtar sözcüklere göre denetler ve sonuçları öğesine evaluation_results.jsonyazar. C# dilindeki bulut değerlendirme desenleri için bkz. C# Değerlendirmeleri SDK örneği.

Değerlendirmeyi yapılandırma

İlk olarak, veri şemanızı ve test ölçütlerinizi tanımlayan bir değerlendirme nesnesi oluşturun. Değerlendirmede şiddet algılama, akıcılık ve göreve bağlılık için yerleşik değerlendiriciler kullanılır.

Python'da OpenAI istemcisini doğrudan kullanın. C# dilinde proje istemcisinden bir EvaluationClient alın:

load_dotenv()
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_deployment_name = os.environ.get("FOUNDRY_MODEL_NAME", "gpt-4o-mini")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Create or retrieve the agent to evaluate
    agent = project_client.agents.create_version(
        agent_name="Modern Workplace Assistant",
        definition=PromptAgentDefinition(
            model=model_deployment_name,
            instructions="You are a helpful Modern Workplace Assistant that answers questions about company policies and technical guidance.",
        ),
    )
    print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

    # Define the data schema for evaluation
    data_source_config = DataSourceConfigCustom(
        type="custom",
        item_schema={
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"]
        },
        include_sample_schema=True,
    )

    # Define testing criteria with built-in evaluators
    testing_criteria = [
        {
            "type": "azure_ai_evaluator",
            "name": "violence_detection",
            "evaluator_name": "builtin.violence",
            "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_text}}"},
        },
        {
            "type": "azure_ai_evaluator",
            "name": "fluency",
            "evaluator_name": "builtin.fluency",
            "initialization_parameters": {"deployment_name": f"{model_deployment_name}"},
            "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_text}}"},
        },
        {
            "type": "azure_ai_evaluator",
            "name": "task_adherence",
            "evaluator_name": "builtin.task_adherence",
            "initialization_parameters": {"deployment_name": f"{model_deployment_name}"},
            "data_mapping": {"query": "{{item.query}}", "response": "{{sample.output_items}}"},
        },
    ]

    # Create the evaluation object
    eval_object = openai_client.evals.create(
        name="Agent Evaluation",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )
    print(f"Evaluation created (id: {eval_object.id}, name: {eval_object.name})")

Dizi testing_criteria , hangi değerlendiricilerin çalıştırılacaklarını belirtir:

  • builtin.violence: Yanıtlardaki şiddetli veya zararlı içeriği algılar.
  • builtin.fluency: Yanıt kalitesini ve okunabilirliğini değerlendirir (model dağıtımı gerektirir).
  • builtin.task_adherence: Ajanın yönergeleri doğru şekilde takip edip etmediğini değerlendirir.

Toplu değerlendirmeyi çalıştırma

Ajanınızı hedefleyen bir değerlendirme yürütümü oluşturun. Veri azure_ai_target_completions kaynağı aracınıza sorgular gönderir ve değerlendirme için yanıtlar yakalar:

# Define the data source for the evaluation run
data_source = {
    "type": "azure_ai_target_completions",
    "source": {
        "type": "file_content",
        "content": [
            {"item": {"query": "What is Contoso's remote work policy?"}},
            {"item": {"query": "What are the security requirements for remote employees?"}},
            {"item": {"query": "According to Microsoft Learn, how do I configure Azure AD Conditional Access?"}},
            {"item": {"query": "Based on our company policy, how should I configure Azure security to comply?"}},
        ],
    },
    "input_messages": {
        "type": "template",
        "template": [
            {"type": "message", "role": "user", "content": {"type": "input_text", "text": "{{item.query}}"}}
        ],
    },
    "target": {
        "type": "azure_ai_agent",
        "name": agent.name,
        "version": agent.version,
    },
}

# Create and submit the evaluation run
agent_eval_run: Union[RunCreateResponse, RunRetrieveResponse] = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name=f"Evaluation Run for Agent {agent.name}",
    data_source=data_source,
)
print(f"Evaluation run created (id: {agent_eval_run.id})")

Yapılandırma data_source :

  • type: azure_ai_target_completions Sorguları acente aracılığıyla yönlendirir
  • kaynak: Test sorguları içeren satır içi içerik (veri kümesi dosya kimliğini de kullanabilirsiniz)
  • input_messages: Aracı için her sorguyu biçimlendiren şablon
  • hedef: Değerlendirilecek aracı adını ve sürümünü belirtir

Değerlendirme sonuçlarını alma

Değerlendirme çalıştırmasını tamamlanana kadar düzenli olarak sorgulayın ve ardından ayrıntılı çıktı öğelerini alın.

# Poll until the evaluation run completes
while agent_eval_run.status not in ["completed", "failed"]:
    agent_eval_run = openai_client.evals.runs.retrieve(
        run_id=agent_eval_run.id,
        eval_id=eval_object.id
    )
    print(f"Waiting for eval run to complete... current status: {agent_eval_run.status}")
    time.sleep(5)

if agent_eval_run.status == "completed":
    print("\n✓ Evaluation run completed successfully!")
    print(f"Result Counts: {agent_eval_run.result_counts}")

    # Retrieve detailed output items
    output_items = list(
        openai_client.evals.runs.output_items.list(
            run_id=agent_eval_run.id,
            eval_id=eval_object.id
        )
    )
    print(f"\nOUTPUT ITEMS (Total: {len(output_items)})")
    print(f"{'-'*60}")
    pprint(output_items)
    print(f"{'-'*60}")
    print(f"Eval Run Report URL: {agent_eval_run.report_url}")
else:
    print("\n✗ Evaluation run failed.")

# Cleanup
openai_client.evals.delete(eval_id=eval_object.id)
print("Evaluation deleted")

project_client.agents.delete(agent_name=agent.name)
print("Agent deleted")

Her çıkış öğesi şunları içerir:

  • Etiket: İkili geçiş veya başarısız sonuç
  • Puan: Değerlendiricinin ölçeğindeki sayısal puan
  • Neden: Puanın neden atandığının açıklaması (LLM tabanlı değerlendiriciler için)

Toplu değerlendirmeden beklenen çıkış (evaluate.py)

Değerlendirme betiğini çalıştırdığınızda aşağıdaki örneğe benzer bir çıktı görürsünüz. Çıkışta değerlendirme nesnesi oluşturma, çalıştırma gönderimi ve sonuç alma işlemleri gösterilir:

python evaluate.py
Agent created (name: Modern_Workplace_Assistant, version: 1)
Evaluation created (id: eval_xyz789, name: Agent Evaluation)
Evaluation run created (id: run_def456)
Waiting for eval run to complete... current status: running
Waiting for eval run to complete... current status: running

✓ Evaluation run completed successfully!
Result Counts: {'passed': 2, 'failed': 0, 'errored': 0}

OUTPUT ITEMS (Total: 2)
------------------------------------------------------------
[OutputItem(id='item_1', 
            sample={'query': 'What is the largest city in France?', 
                    'output_text': 'The largest city in France is Paris...'},
            results=[{'name': 'violence_detection', 'passed': True, 'score': 0},
                     {'name': 'fluency', 'passed': True, 'score': 4, 
                      'reason': 'Response is clear and well-structured'},
                     {'name': 'task_adherence', 'passed': True, 'score': 5}]),
 OutputItem(id='item_2', ...)]
------------------------------------------------------------
Eval Run Report URL: https://ai.azure.com/...
Evaluation deleted
Agent deleted

Değerlendirme sonuçlarını anlama

Toplu değerlendirmeler, Dökümhane portalında görüntüleyebileceğiniz veya program aracılığıyla alabildiğiniz yapılandırılmış sonuçlar sağlar. Her çıkış öğesi şunları içerir:

Alan Açıklama
Etiket Eşiğe göre ikili "başarılı" veya "başarısız"
Puan Sayısal puan (ölçek değerlendirici türüne bağlıdır)
Eşik Başarı/geçiş durumunu belirleyen eşik değeri
Neden Puan için LLM tarafından oluşturulan açıklama (uygun olduğunda)

Ölçekleri değerlendirici türüne göre puanla:

  • Kalite değerlendiricileri (akıcılık, tutarlılık): 1-5 ölçek
  • Güvenlik değerlendiricileri (şiddet, kendine zarar verme): 0-7 önem derecesi (düşük daha güvenlidir)
  • Görev değerlendiricileri (task_adherence): 1-5 ölçek

Ayrıca, projenizden Değerlendirme'yi seçip değerlendirme çalıştırmasını seçerek Foundry portalında ayrıntılı sonuçları görüntüleyebilirsiniz. Portal görselleştirmeler, filtreleme ve dışarı aktarma seçenekleri sağlar.

Ipucu

Üretim senaryoları için değerlendirmeleri CI/CD işlem hattınızın bir parçası olarak çalıştırmayı göz önünde bulundurun. Bkz. Azure DevOps'ta bir değerlendirme nasıl çalıştırılır? ve Yapay zeka aracılarınızı sürekli olarak değerlendirin tümleştirme desenleri için.

Sorun giderme

Semptom Neden Çözünürlük
DefaultAzureCredential kimlik doğrulama hatası Azure CLI oturumunun süresi doldu veya oturum açılmadı Çalıştırma az login ve yeniden deneme
Model deployment not found içindeki .env model adı projenizdeki bir dağıtımla eşleşmiyor Projenizi Foundry portalında açın, Dağıtımlar'ı kontrol edin ve FOUNDRY_MODEL_NAME öğesini .env öğesinde güncelleyin.
SharePoint tool configured ancak aracı belgeleri bulamıyor Belgeler karşıya yüklenmedi veya bağlantı adı yanlış Belgelerin SharePoint kitaplığında göründüğünü ve SHAREPOINT_CONNECTION_NAME projenizdeki bağlantıyla eşleşip eşleşmediğini doğrulayın
MCP aracı zaman aşımı veya bağlantı hatası Microsoft Learn MCP sunucusuna ulaşılamıyor MCP_SERVER_URL olarak ayarlandığından ve ağınızın giden HTTPS'ye izin verdiğinden emin olun https://learn.microsoft.com/api/mcp
SharePoint üzerinde 403 Forbidden SharePoint sitesinde yetersiz izinler Oturum açmış kimliğinizin SharePoint belge kitaplığına en az Read erişimi olduğunu onaylayın

Özet

Artık sahip olduğunuz:

  • İç ve dış bilgilere dayalı çalışan tek aracılı bir prototip.
  • Kurumsal doğrulama desenlerini gösteren tekrarlanabilir bir değerlendirme betiği.
  • Net bir yükseltme yolu: daha fazla araç, çok aracılı düzenleme, daha zengin değerlendirme, dağıtım.

Bu desenler prototip-üretim sürtüşmesini azaltır: Veri kaynakları ekleyebilir, yönetişimi uygulayabilir ve temel mantığı yeniden yazmadan izlemeyi entegre edebilirsiniz.

Sonraki adımlar

Bu öğreticide, fikirden prototipe geliştirici yolculuğunun 1. aşaması gösterilmektedir. Bu minimum örnek, kurumsal yapay zeka geliştirme için temel sağlar. Yolculuğunuza devam etmek için sonraki aşamaları keşfedin:

Önerilen ek geliştirmeler

2. Aşama: Prototipden üretime

3. Aşama: Üretimden benimsemeye

Kaynakları temizleme

Artık bunlara ihtiyacınız kalmadığında, bu öğreticide oluşturduğunuz kaynakları silin:

  1. Aracısı silme: Aracı, main.py (Python) veya Program.cs (C#) sonunda otomatik olarak silinir. Çalıştırmayı yarıda kestiyseniz, Foundry portalındaki Ajanlar sayfasından el ile silin.
  2. Değerlendirme çalıştırmasını silme: Dökümhane portalında Değerlendirme'ye gidin, değerlendirme çalıştırmasını seçin ve silin.
  3. Örnek belgeleri SharePoint: Örnek .docx dosyalarını bir üretim SharePoint sitesine yüklediyseniz, bunları belge kitaplığından kaldırın.
  4. (İsteğe bağlı) Dökümhane projesini silin: Yalnızca bu öğretici için bir proje oluşturduysanız, ilişkili tüm kaynakları kaldırmak için bu projeyi Foundry portalından silin.

İlgili içerik

  • Last updated on