Aracılığıyla paylaş

Kılavuz: 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 şirket içi bilgileri dış teknik rehberlikle birleştiren modern bir çalışma alanı yardımcısı 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ş uygulamasında kullanmak üzere her iki kaynağın birleştirilmesi)
  • Gerçekçi iş senaryolarında aracı performansını doğrulamak için grup değerlendirmesi

Öğretici sonucu: Sonunda ilke, teknik ve birleştirilmiş uygulama sorularını yanıtlayan çalışan bir Modern Workplace Yardımcısı'na sahip olursunuz; yinelenebilir bir toplu değerlendirme betiği; ve açık uzantı noktaları (diğer araçlar, çok aracılı desenler, 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 desteklenmiyor olabileceği gibi özellikleri sınırlandırılmış da olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Uygun Kullanım Koşulları.

Önkoşullar

  • Azure aboneliği. Eğer bir tane yoksa, ücretsiz olarak oluşturun.

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

  • Dağıtılmış bir modele sahip Dökümhane projesi (örneğin, ). 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)

    Uyarı

    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

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)

Tavsiye

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

Üretime geçiş için bağımsız bir depo kullanın. Bu öğreticide paylaşılan örnekler deposu kullanılır. Seyrek kontrol dışı bırakma yerel gürültüyü en aza indirir.

Python kodunu şimdi indir

ZIP'i çıkardıktan sonra 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. Bu yayımlanan paket sürümlerini kullandığınızı doğrulayın:

    azure-ai-projects==2.0.0b3
azure-identity
python-dotenv
openai

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

    python -m pip install -r requirements.txt

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

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

    Uç nokta URL'sini ve kopyala düğmesini gösteren Microsoft Foundry Modelleri hoş geldiniz ekranının ekran görüntüsü.

  5. Yapılandır .

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

öğesini konumuna kopyalayın.

# Foundry configuration
PROJECT_ENDPOINT=https://<your-project>.aiservices.azure.com
MODEL_DEPLOYMENT_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>

dosyasının geçerli değerler içerdiğini doğrulamak için dosyayı açın ve dosyanın kısmının ile başladığını, kısmının projenizde dağıtılan modelin adıyla eşleştiğini kontrol edin.

Tavsiye

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.

Ajanı 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 olmaksızın zarif bozulma

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

Çalışan bir ajanınız olduğuna göre, sonraki bölümlerde çalışma prensipleri 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ısı

📁 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ı anlama

Uyarı

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. Ajana zaten çalıştırdın. Okuduktan sonra şunları yapabilirsiniz:

  • Yeni iç ve dış veri araçları ekleyin.
  • Dinamik yönergeleri genişletin.
  • Çok ajanlı orkestrasyonu 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 üzerine 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. Temsilci 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 desteklenmiyor olabileceği gibi özellikleri sınırlandırılmış da olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Uygun Kullanım Koşulları.

Aktarımlar ve kimlik doğrulaması kurulumu

Kod, güçlü bir kurumsal aracı oluşturmak için Microsoft Foundry SDK'sından çeşitli istemci kitaplıkları 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

Agentinizi oluşturmadan önce Foundry için kimlik doğrulaması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}")

Temsilci için SharePoint aracını oluşturun

Aracı SharePoint kullanır ve burada depolanan şirket politikası 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)")

Acente için MCP aracını oluşturun

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ıyı oluşturma ve araçları bağlama

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

print(f"🛠️  Creating agent with model: {os.environ['MODEL_DEPLOYMENT_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["MODEL_DEPLOYMENT_NAME"],
        instructions=instructions,
        tools=tools if tools else None,
    ),
)

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

Temsilci ile konuş

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)

Aracı örnek kodundan beklenen çıkış

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

✅ 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 Azure AD 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 Azure AD 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: Bulut değerlendirmesini kullanarak yardımcıyı değerlendirme

Değerlendirme çerçevesi, Microsoft Foundry SDK'sının bulut 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 (, , ) ve API'yi kullanır.

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

  • Aracı hedefleme: Değerlendirme, kullanarak doğrudan ajanınıza yönelik sorgular çalıştırı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. Bulut değerlendirmesini çalıştırın.
  3. Değerlendirme sonuçlarını alın.

Tavsiye

Bulut değerlendirmeleri 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.

Uyarı

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 kelimelere göre kontrol eder ve sonuçları belirlenen alana yazar. 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 ile doğrudan OpenAI istemcisini kullanın. C# dilinde proje istemcisinden bir alın:

load_dotenv()
endpoint = os.environ["PROJECT_ENDPOINT"]
model_deployment_name = os.environ.get("MODEL_DEPLOYMENT_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 , hangi değerlendiricilerin çalıştırılacaklarını belirtir:

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

Bulut değerlendirmesini çalıştırma

Aracınızı hedefleyen bir değerlendirme çalıştırması oluşturun. Veri 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 :

  • type: Sorguları aracınız üzerinden 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

Tamamlanana kadar değerlendirme sürecini izleyin, ardından ayrıntılı çıkış öğ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)

Bulut değerlendirmesinden 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

Bulut değerlendirmeleri, Foundry 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 Description
Etiket Eşiğe göre ikili "geçiş" veya "başarısız"
Puan Sayısal puan (ölçek değerlendirici türüne bağlıdır)
Eşik Başarıyı/başarısızlığı belirleyen eşik değeri
Sebep 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.

Tavsiye

Ü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ğerlendirmeyi nasıl çalıştıracağınızı ve Yapay zeka aracılarınızı sürekli değerlendirin tümleştirme desenleri için.

Sorun giderme

Semptom Nedeni Çözüm
kimlik doğrulama hatası Azure CLI oturumunun süresi doldu veya oturum açılmadı Çalıştırma ve yeniden deneme
Model deployment not found içindeki model adı projenizdeki bir dağıtımla eşleşmiyor Projenizi Foundry portalında açın, Dağıtımlar'ı denetleyin ve 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 öğesinin olarak ayarlandığından ve ağınızın giden HTTPS bağlantılarına izin verdiğinden emin olun.
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 prototipten üretime sürtünmeyi 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

  • Daha fazla veri kaynağı ekleyin (Azure Yapay Zeka Arama, other sources).
  • Gelişmiş değerlendirme yöntemleri (yapay zeka destekli değerlendirme) uygulayın.
  • İşletmeye özgü işlemler için özel araçlar oluşturun.
  • Konuşma belleği ve kişiselleştirme ekleyin.

2. Aşama: Prototipden üretime

  • Kırmızı ekip testi ile güvenlik değerlendirmesi uygulayın.
  • Kalite ölçümleriyle kapsamlı değerlendirme veri kümeleri oluşturun.
  • Kuruluş genelinde idare ilkeleri ve model karşılaştırması uygulayın.
  • Filo izleme, CI/CD tümleştirmesi ve üretim dağıtım uç noktalarını yapılandırın.

3. Aşama: Üretimden benimsemeye

Kaynakları temizle

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ışmayı yarıda kestiyseniz, Foundry portalındaki Aracılar sayfasından manuel olarak 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