PAÇAVRA

Microsoft Agent Framework, model çağırmadan önce alınan içeriği ekleyen bağlam sağlayıcıları ve modelin isteğe bağlı olarak topraklama verilerini almasını sağlayan arama araçları aracılığıyla Alma Artırılmış Oluşturma'yı (RAG) destekler.

Alma işlemiyle birlikte konuşma/oturum desenleri için bkz . Konuşmalara ve Belleğe genel bakış. Hizmete özgü kurulum için bkz. Azure Yapay Zeka Arama, Microsoft Foundry ve Neo4j.

TextSearchProvider kullanma

TextSearchProvider sınıfı, bir RAG bağlam sağlayıcısının kullanıma açık bir uygulamasıdır. Sohbet geçmişiyle çalışan her aracı için arama yapmak veya arama yapmak için işlev araçlarını reklam yapmak gibi farklı işlem modlarını destekler.

Seçeneği kullanılarak ChatClientAgent kolayca bir'e AIContextProviders eklenebilir.

// Configure the options for the TextSearchProvider.
TextSearchProviderOptions textSearchOptions = new()
{
    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
};

// Create the AI agent with the TextSearchProvider.
AIAgent agent = azureOpenAIClient
    .GetChatClient(deploymentName)
    .AsAIAgent(new ChatClientAgentOptions
    {
        ChatOptions = new() { Instructions = "You are a helpful support specialist. Answer questions using the provided context and cite the source document when available." },
        AIContextProviders = [new TextSearchProvider(SearchAdapter, textSearchOptions)]
    });

, TextSearchProvider sorgu verilen arama sonuçlarını sağlayan bir işlev gerektirir. Bu, Azure Yapay Zeka Arama veya web arama altyapısı gibi herhangi bir arama teknolojisi kullanılarak uygulanabilir.

Tip

Arama sonuçları için vektör deposu kullanma hakkında daha fazla bilgi için bkz. Vektör deposu tümleştirmeleri .

Burada, sorguyu temel alan önceden tanımlanmış sonuçlar döndüren bir sahte arama işlevi örneği verilmiştir. SourceName ve SourceLink isteğe bağlıdır, ancak sağlanırsa, kullanıcının sorusunu yanıtlarken bilgilerin kaynağını alıntı yapmak için aracı tarafından kullanılır.

static Task<IEnumerable<TextSearchProvider.TextSearchResult>> SearchAdapter(string query, CancellationToken cancellationToken)
{
    // The mock search inspects the user's question and returns pre-defined snippets
    // that resemble documents stored in an external knowledge source.
    List<TextSearchProvider.TextSearchResult> results = new();

    if (query.Contains("return", StringComparison.OrdinalIgnoreCase) || query.Contains("refund", StringComparison.OrdinalIgnoreCase))
    {
        results.Add(new()
        {
            SourceName = "Contoso Outdoors Return Policy",
            SourceLink = "https://contoso.com/policies/returns",
            Text = "Customers may return any item within 30 days of delivery. Items should be unused and include original packaging. Refunds are issued to the original payment method within 5 business days of inspection."
        });
    }

    return Task.FromResult<IEnumerable<TextSearchProvider.TextSearchResult>>(results);
}

TextSearchProvider Seçenekleri

TextSearchProvider sınıfı aracılığıyla TextSearchProviderOptions özelleştirilebilir. Burada, her model çağrısından önce aramayı çalıştırmak ve aramalar için sohbet geçmişinin kısa bir sıralı penceresini tutmak için seçenekler oluşturma örneği verilmiştir.

TextSearchProviderOptions textSearchOptions = new()
{
    // Run the search prior to every model invocation and keep a short rolling window of chat history for searches.
    SearchTime = TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke,
    RecentMessageMemoryLimit = 6,
};

sınıfı, TextSearchProvider sınıfı aracılığıyla TextSearchProviderOptions aşağıdaki seçenekleri destekler.

Seçenek	Type	Açıklama	Default
Arama Zamanı	TextSearchProviderOptions.TextSearchBehavior	Aramanın ne zaman yürütülmesi gerektiğini gösterir. Aracı her çalıştırıldığında veya işlev çağrısı aracılığıyla isteğe bağlı olarak iki seçenek vardır.	TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke
FunctionToolName	string	İsteğe bağlı modda çalışırken kullanıma sunulan arama aracının adı.	"Ara"
FunctionToolDescription	string	İsteğe bağlı modda çalışırken kullanıma sunulan arama aracının açıklaması.	"Kullanıcı sorusunu yanıtlamaya yardımcı olmak için ek bilgi aramaya izin verir."
ContextPrompt	string	Sonuçlara ön ekli bağlam istemi.	"## Ek Bağlam\nKullanıcıya yanıt verirken kaynak belgelerden aşağıdaki bilgileri göz önünde bulundurun:"
CitationsPrompt	string	Alıntı istemek için sonuçlardan sonra eklenen yönerge.	"Belge adı ve bağlantı varsa kaynak belgeye alıntıları ve bağlantı ekleyin."
ContextFormatter	Func<IList<TextSearchProvider.TextSearchResult>, string>	Sonuç listesinin biçimlendirmesini tamamen özelleştirmek için isteğe bağlı temsilci. Sağlandıysa ContextPrompt ve CitationsPrompt yoksayılırsa.	null
RecentMessageMemoryLimit	int	En son konuşma iletilerinin (hem kullanıcı hem de yardımcı) bellekte tutulacak ve arama girişi BeforeAIInvoke oluştururken eklenecek sayısı.	0 (devre dışı)
RecentMessageRolesIncluded	List<ChatRole>	Arama girişini oluştururken hangi son iletilerin dahilleneceğine karar verirken son iletileri filtreleyebileceğiniz türlerin listesi ChatRole .	ChatRole.User

Tip

Çalıştırılabilir örneklerin tamamı için .NET örneklerine bakın.

Agent Framework yerel vektör deposu sözleşmeleri ve create_vector_search_tool()sağlar. Yardımcı, modelin yanıt vermeden önce topraklama verilerini alabilmesi için herhangi SupportsVectorSearch bir uygulamayı bir işlev aracına dönüştürür.

Yerel vektör arama aracı oluşturma

İlk olarak vektör deposu modelinizi tanımlayın, bir koleksiyon oluşturun ve kayıtlarını yükleyin. Aşağıdaki örnek ile kullanır InMemoryCollectionOpenAIEmbeddingClient, ancak uygulayan SupportsVectorSearchherhangi bir yerel Agent Framework koleksiyonu sağlayabilirsiniz. Daha sonra isteğe bağlı kategori ve derecelendirme filtrelerini modele sunar, her sonucu topraklama metniyle eşler ve aracıya şunları yanıtlamadan önce arama talimatı verir:

import asyncio
import json
import os
from typing import Annotated, Any, Literal
from urllib.request import urlopen

from agent_framework import (
    Agent,
    Filter,
    FilterGroup,
    InMemoryCollection,
    Param,
    VectorStoreField,
    create_vector_search_tool,
    vectorstoremodel,
)
from agent_framework.openai import OpenAIChatClient, OpenAIEmbeddingClient
from dotenv import load_dotenv
async def main() -> None:
    """Create an in-memory hotel search tool and give it to an agent."""
    api_key = os.environ["OPENAI_API_KEY"]
    collection: InMemoryCollection[str, Hotel] = InMemoryCollection(
        Hotel,
        embedding_generator=OpenAIEmbeddingClient(
            model="text-embedding-3-small",
            api_key=api_key,
        ),
    )
    await collection.ensure_collection_exists()

    # 1. Load the hotel records.
    hotels = await asyncio.to_thread(load_hotels)
    await collection.upsert(hotels)

    # 2. Param values become optional model-visible filter arguments.
    # When the allowed values are known, use Literal so the tool schema exposes
    # them as an enum.
    category = Param(
        "category",
        Literal["Boutique", "Budget", "Extended-Stay", "Luxury", "Resort and Spa", "Suite"],
        description="Only return hotels in this category.",
    )
    min_rating = Param(
        "min_rating",
        float,
        description="The minimum guest rating.",
        minimum=0,
        maximum=5,
    )
    tool = create_vector_search_tool(
        collection,
        description="Search the hotel dataset, optionally filtering by category and minimum rating.",
        filter=FilterGroup(
            "and",
            (
                Filter("category", "eq", category),
                Filter("rating", "gte", min_rating),
            ),
        ),
        result_mapper=lambda result: (
            f"(hotel_id: {result['record'].hotel_id}) {result['record'].hotel_name} "
            f"(rating {result['record'].rating}) - {result['record'].description}. "
            f"Address: {result['record'].address.city}, {result['record'].address.country}."
        ),
    )

    # 3. The agent chooses whether to supply the exposed category and minimum-rating filters.
    async with Agent(
        client=OpenAIChatClient(
            model="gpt-5.4-nano",
            api_key=api_key,
        ),
        name="HotelAgent",
        instructions=(
            "Always use the search tool to answer hotel questions. "
            "Use category and minimum rating filters when the request provides them. "
            "Include the hotel_id in the answer."
        ),
        tools=[tool],
    ) as agent:
        result = await agent.run("Find a resort and spa with a rating of at least 4.")
        print(result)

Tam örnek modeli tanımlar Hotel ve gösterilen koleksiyon kurulumundan önce kaynak kayıtları yükler. Çalıştırmadan önce ayarlayın OPENAI_API_KEY .

Arama davranışını özelleştirme

Aşağıdaki seçeneklerle yapılandırın create_vector_search_tool() :

Seçenek	Purpose
name	Modele sunulan işlev adını ayarlar. Birden çok arama aracı eklerken benzersiz bir ad kullanın.
description	Modelin aracı ne zaman ve neden kullanması gerektiğini açıklar.
approval_mode	Araç onayını veya never_requireolarak always_require ayarlar.
search_type	vector Seçer veya keyword_hybrid arar. Koleksiyonun seçili modu desteklemesi gerekir.
top ve skip	Sabit disk belleği değerleri ayarlayın veya modelin sağladığı yazılan Param değerleri kullanın.
filter	Taşınabilir Filter veya FilterGroupuygular. Filtre, araç şemasında gösterilen türemiş Param değerleri içerebilir.
result_mapper	Her SearchResponse bir modeli metne veya çok modüllüye Content dönüştürür.

Oluşturulan araç her zaman bir query dize içerir. Filtre, veya skip ayarlardaki tüm Param değerler ek topdoğrulanmış araç bağımsız değişkenlerine dönüşür. Model tarafından sağlanan değerleri uygulamanızın kabul ettiği aralıkta tutmak için ve sayısal kısıtlamaları kullanın Literal .

Farklı koleksiyonlar veya arama modları için birden çok araç oluşturabilirsiniz. Modelin uygun bilgi kaynağını seçebilmesi için her ara aracı ayrı namedescription bir değer verin.

Yerel vektör deposu seçme

Yerel Python uygulamaları pgvector, Qdrant ve Redis ile bellek içi arama, Azure Yapay Zeka Arama, PostgreSQL için kullanılabilir. Arama modları, paket yaşam döngüsü, yükleme komutları ve sınırlamaları farklıdır. Bir uygulamayı seçmek ve yapılandırmak için bkz. Vektör deposu tümleştirmeleri . Bu sayfa, şu anda yalnızca ayrı bir Semantik Çekirdek bağlayıcısı olan veritabanlarını da tanımlar.

Uyarı

Bu özellik için Go desteği yakında sunulacaktır. En son durum için bkz. Agent Framework Go deposu .

Grafik RAG

Cypher sorgularıyla graf geçişi zenginleştirilmiş arama kullanan GraphRAG için bkz. Neo4j GraphRAG Sağlayıcısı.

Sonraki Adımlar

Bildirim Temelli Aracılar