RONGY

Microsoft Agent Framework támogatja a kiterjesztett generáció (RAG) lekérését olyan környezetszolgáltatókon keresztül, amelyek lekért tartalmat adnak hozzá a modell meghívása előtt, és olyan keresőeszközökkel, amelyek lehetővé teszik a modell számára a földelési adatok igény szerinti lekérését.

A lekérés mellett a beszélgetési/munkamenet-mintákról a Beszélgetések > Memória áttekintésében olvashat. A szolgáltatásspecifikus beállításért lásd: Azure AI Keresés, Microsoft Foundry és Neo4j.

A TextSearchProvider használata

Az TextSearchProvider osztály egy RAG-környezetszolgáltató beépített implementációja. Különböző működési módokat támogat, például az egyes ügynökök keresését a csevegési előzményekkel futtatva, vagy hirdetési függvényeszközöket a keresésekhez.

A beállítással ChatClientAgent könnyen csatlakoztatható egy AIContextProviders adott elemhez.

// 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)]
    });

Ehhez TextSearchProvider olyan függvényre van szükség, amely megadja a keresési eredményeket egy lekérdezésben. Ez bármilyen keresési technológiával implementálható, például Azure AI Keresés vagy webes keresőmotor használatával.

Tip

A vektortárolók keresési eredményekhez való használatával kapcsolatos további információkért tekintse meg a vektortár-integrációkat .

Íme egy példa egy modellkeresési függvényre, amely a lekérdezés alapján előre definiált eredményeket ad vissza. SourceName és SourceLink nem kötelezőek, de ha meg van adva, az ügynök az információ forrására hivatkozik a felhasználó kérdésének megválaszolásakor.

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 beállításai

Az TextSearchProvider osztályon keresztül TextSearchProviderOptions testre szabható. Íme egy példa arra, hogy olyan beállításokat hozhat létre, amelyekkel minden modell meghívása előtt futtathatja a keresést, és rövid ideig tarthatja a csevegési előzményeket a keresésekhez.

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,
};

Az TextSearchProvider osztály az alábbi lehetőségeket támogatja az TextSearchProviderOptions osztályon keresztül.

Option	Típus	Leírás	Default
Keresési Idő	TextSearchProviderOptions.TextSearchBehavior	Azt jelzi, hogy mikor kell végrehajtani a keresést. Két lehetőség közül választhat, minden alkalommal, amikor az ügynök fut, vagy igény szerint függvényhívással.	TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke
FunctionToolName	string	A közzétett keresőeszköz neve igény szerinti módban való működéskor.	"Keresés"
FunctionToolDescription	string	A közzétett keresőeszköz leírása igény szerinti módban való működéskor.	"Lehetővé teszi további információk keresését a felhasználói kérdés megválaszolásához."
ContextPrompt	string	A környezeti kérés előtagja az eredményekhez.	"## További környezet\nVegye figyelembe a forrásdokumentumok következő információinak a felhasználónak való megválaszolásakor:"
CitationsPrompt	string	Az idézetek kéréséhez az eredmények után hozzáfűzött utasítás.	"Ha elérhető a dokumentum neve és hivatkozása, hivatkozzon a forrásdokumentumra."
ContextFormatter	Func<IList<TextSearchProvider.TextSearchResult>, string>	Nem kötelező delegálni az eredménylista formázásának teljes testreszabásához. Ha meg van adva, ContextPrompt és CitationsPrompt a rendszer figyelmen kívül hagyja.	null
RecentMessageMemoryLimit	int	Azoknak a legutóbbi beszélgetési üzeneteknek a száma (mind a felhasználó, mind az asszisztens), amelyek a memóriában maradnak, és belefoglalnak a keresések keresési bemenetének BeforeAIInvoke összeállításakor.	0 (letiltva)
RecentMessageRolesIncluded	List<ChatRole>	Azoknak a típusoknak a ChatRole listája, amelyekre szűrni szeretné a legutóbbi üzeneteket, amikor eldönti, hogy mely legutóbbi üzeneteket vegye figyelembe a keresési bemenet létrehozásakor.	ChatRole.User

Tip

A teljes futtatható példákért tekintse meg a .NET-mintákat .

Az Agent Framework natív vektortároló-szerződéseket és create_vector_search_tool(). A segéd minden SupportsVectorSearch implementációt függvényeszközsé alakít, így a modell a válaszok előtt lekérheti a földelési adatokat.

Natív vektorkeresési eszköz létrehozása

Először határozza meg a vektortároló-modellt, hozzon létre egy gyűjteményt, és töltse be a rekordjait. Az alábbi minta a következővel OpenAIEmbeddingClienthasználhatóInMemoryCollection, de bármilyen natív Agent Framework-gyűjteményt megadhat, amely implementálhatóSupportsVectorSearch. Ezután elérhetővé teszi az opcionális kategória- és minősítési szűrőket a modellnek, leképezi az egyes eredményeket a földelő szövegre, és arra utasítja az ügynököt, hogy keressen rá, mielőtt választ ad:

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)

A teljes minta meghatározza a Hotel modellt, és betölti a forrásrekordokat a megjelenített gyűjtemény beállítása előtt. A futtatás előtt állítsa be OPENAI_API_KEY .

Keresési viselkedés testreszabása

Konfigurálja create_vector_search_tool() a következő lehetőségeket:

Option	Alkalmazás célja
name	Beállítja a modell számára közzétett függvénynevet. Használjon egyedi nevet több keresőeszköz hozzáadásakor.
description	Ez a cikk azt ismerteti, hogy a modell mikor és miért használja az eszközt.
approval_mode	Eszközjóváhagyás beállítása a (vagynever_require) értékrealways_require.
search_type	Kiválaszt vagy vectorkeyword_hybrid keres. A gyűjteménynek támogatnia kell a kiválasztott módot.
top és skip	Állítsa be a rögzített lapozási értékeket, vagy használja a modell által biztosított beírt Param értékeket.
filter	Hordozható Filter vagy FilterGroup. A szűrő tartalmazhat az eszközsémában közzétett beírt Param értékeket.
result_mapper	Ezeket SearchResponse szöveggé vagy multimodálissá Content alakítja a modellhez.

A létrehozott eszköz mindig tartalmaz egy sztringet query . A szűrőben Paramtopvagy skip a beállításokban szereplő értékek további érvényesített eszközargumentumokká válnak. A Literal modell által megadott értékek az alkalmazás által elfogadott tartományon belül maradnak.

Több eszközt is létrehozhat különböző gyűjteményekhez vagy keresési módokhoz. Adjon külön-külön name minden eszközt, hogy description a modell kiválaszthassa a megfelelő tudásbázist.

Natív vektortároló kiválasztása

Natív Python-implementációk érhetők el a memóriabeli kereséshez, Azure AI Keresés, PostgreSQL-hez pgvector, Qdrant és Redis használatával. A keresési módok, a csomagok életciklusa, a telepítési parancsok és a korlátozások eltérőek. Implementáció kiválasztásához és konfigurálásához tekintse meg a Vector Store-integrációkat . Ez a lap azokat az adatbázisokat is azonosítja, amelyek jelenleg csak külön Szemantikus kernel összekötővel rendelkeznek.

Megjegyzés:

A funkció Go-támogatása hamarosan érkezik. A legújabb állapotot az Agent Framework Go-adattárában tekinthet meg.

Graph RAG

Ha a GraphRAG-t gráfbejárással bővített kereséssel, Cypher-lekérdezésekkel használja, tekintse meg a Neo4j GraphRAG-szolgáltatót.

Következő lépések

Deklaratív ügynökök