PAÇAVRA

Microsoft Agent Framework, aracıya Yapay Zeka Bağlam Sağlayıcıları ekleyerek aracılara kolayca Alma Artırılmış Nesil (RAG) özellikleri eklemeyi destekler.

Alma işlemiyle birlikte konuşma/oturum desenleri için bkz . Konuşmalara ve Belleğe genel bakış.

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.

Tavsiye

Arama sonuçları için vektör deposu kullanma hakkında daha fazla bilgi için Vektör Depoları tümleştirme belgelerine bakın.

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	Türü	Description	Varsayılan
SearchTime	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

Tavsiye

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

Agent Framework, aracılara RAG özellikleri sağlamak için Semantik Çekirdek VectorStore koleksiyonlarının kullanılmasını destekler. Bu, Semantik Çekirdek arama işlevlerini Aracı Çerçevesi araçlarına dönüştüren köprü işleviyle elde edilir.

VectorStore'dan Arama Aracı Oluşturma

Semantik Çekirdek VectorStore koleksiyonundaki create_search_function yöntemi, .as_agent_framework_tool() kullanılarak Bir Agent Framework aracına dönüştürülebilen bir KernelFunction döndürür. Farklı vektör deposu koleksiyonlarını ayarlamayı öğrenmek için vektör deposu bağlayıcıları belgelerini kullanın.

from semantic_kernel.connectors.ai.open_ai import OpenAITextEmbedding
from semantic_kernel.connectors.azure_ai_search import AzureAISearchCollection
from semantic_kernel.functions import KernelParameterMetadata
from agent_framework.openai import OpenAIChatClient

# Define your data model
class SupportArticle:
    article_id: str
    title: str
    content: str
    category: str
    # ... other fields

# Create an Azure AI Search collection
collection = AzureAISearchCollection[str, SupportArticle](
    record_type=SupportArticle,
    embedding_generator=OpenAITextEmbedding()
)

async with collection:
    await collection.ensure_collection_exists()
    # Load your knowledge base articles into the collection
    # await collection.upsert(articles)

    # Create a search function from the collection
    search_function = collection.create_search_function(
        function_name="search_knowledge_base",
        description="Search the knowledge base for support articles and product information.",
        search_type="keyword_hybrid",
        parameters=[
            KernelParameterMetadata(
                name="query",
                description="The search query to find relevant information.",
                type="str",
                is_required=True,
                type_object=str,
            ),
            KernelParameterMetadata(
                name="top",
                description="Number of results to return.",
                type="int",
                default_value=3,
                type_object=int,
            ),
        ],
        string_mapper=lambda x: f"[{x.record.category}] {x.record.title}: {x.record.content}",
    )

    # Convert the search function to an Agent Framework tool
    search_tool = search_function.as_agent_framework_tool()

    # Create an agent with the search tool
    agent = OpenAIChatClient(model="gpt-4o").as_agent(
        instructions="You are a helpful support specialist. Use the search tool to find relevant information before answering questions. Always cite your sources.",
        tools=search_tool
    )

    # Use the agent with RAG capabilities
    response = await agent.run("How do I return a product?")
    print(response.text)

Önemli

Bu özellik için 1.38 veya üzeri bir sürüm gerekir semantic-kernel .

Arama Davranışını Özelleştirme

Arama işlevini çeşitli seçeneklerle özelleştirebilirsiniz:

# Create a search function with filtering and custom formatting
search_function = collection.create_search_function(
    function_name="search_support_articles",
    description="Search for support articles in specific categories.",
    search_type="keyword_hybrid",
    # Apply filters to restrict search scope
    filter=lambda x: x.is_published == True,
    parameters=[
        KernelParameterMetadata(
            name="query",
            description="What to search for in the knowledge base.",
            type="str",
            is_required=True,
            type_object=str,
        ),
        KernelParameterMetadata(
            name="category",
            description="Filter by category: returns, shipping, products, or billing.",
            type="str",
            type_object=str,
        ),
        KernelParameterMetadata(
            name="top",
            description="Maximum number of results to return.",
            type="int",
            default_value=5,
            type_object=int,
        ),
    ],
    # Customize how results are formatted for the agent
    string_mapper=lambda x: f"Article: {x.record.title}\nCategory: {x.record.category}\nContent: {x.record.content}\nSource: {x.record.article_id}",
)

create_search_function için kullanılabilen parametrelerle ilgili tüm ayrıntılar için Semantik Çekirdek belgelerine bakın.

Birden Çok Arama İşlevi Kullanma

Farklı bilgi etki alanları için bir aracıya birden çok arama aracısı sağlayabilirsiniz:

# Create search functions for different knowledge bases
product_search = product_collection.create_search_function(
    function_name="search_products",
    description="Search for product information and specifications.",
    search_type="semantic_hybrid",
    string_mapper=lambda x: f"{x.record.name}: {x.record.description}",
).as_agent_framework_tool()

policy_search = policy_collection.create_search_function(
    function_name="search_policies",
    description="Search for company policies and procedures.",
    search_type="keyword_hybrid",
    string_mapper=lambda x: f"Policy: {x.record.title}\n{x.record.content}",
).as_agent_framework_tool()

# Create an agent with multiple search tools
agent = chat_client.as_agent(
    instructions="You are a support agent. Use the appropriate search tool to find information before answering. Cite your sources.",
    tools=[product_search, policy_search]
)

Özel arama özellikleri sağlamak için aynı koleksiyondan farklı açıklama ve parametrelerle birden çok arama işlevi de oluşturabilirsiniz:

# Create multiple search functions from the same collection
# Generic search for broad queries
general_search = support_collection.create_search_function(
    function_name="search_all_articles",
    description="Search all support articles for general information.",
    search_type="semantic_hybrid",
    parameters=[
        KernelParameterMetadata(
            name="query",
            description="The search query.",
            type="str",
            is_required=True,
            type_object=str,
        ),
    ],
    string_mapper=lambda x: f"{x.record.title}: {x.record.content}",
).as_agent_framework_tool()

# Detailed lookup for specific article IDs
detail_lookup = support_collection.create_search_function(
    function_name="get_article_details",
    description="Get detailed information for a specific article by its ID.",
    search_type="keyword",
    top=1,
    parameters=[
        KernelParameterMetadata(
            name="article_id",
            description="The specific article ID to retrieve.",
            type="str",
            is_required=True,
            type_object=str,
        ),
    ],
    string_mapper=lambda x: f"Title: {x.record.title}\nFull Content: {x.record.content}\nLast Updated: {x.record.updated_date}",
).as_agent_framework_tool()

# Create an agent with both search functions
agent = chat_client.as_agent(
    instructions="You are a support agent. Use search_all_articles for general queries and get_article_details when you need full details about a specific article.",
    tools=[general_search, detail_lookup]
)

Bu yaklaşım, aracının kullanıcının sorgusuna göre en uygun arama stratejisini seçmesini sağlar.

Desteklenen VectorStore Bağlayıcıları

Bu düzen, aşağıdakiler dahil olmak üzere tüm Semantik Çekirdek VectorStore bağlayıcılarıyla çalışır:

• Azure Yapay Zeka Arama (AzureAISearchCollection)
• Qdrant (QdrantCollection)
• Pinecone (PineconeCollection)
• Redis (RedisCollection)
• Ağırlaştır (WeaviateCollection)
• In-Memory (InMemoryVectorStoreCollection)
• Ve daha fazlası

Her bağlayıcı, Agent Framework araçlarına bağlanabilen aynı create_search_function yöntemi sağlayarak gereksinimlerinize en uygun vektör veritabanını seçmenize olanak sağlar. Tam listeye buradan bakın.

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