HADR

Microsoft Agent Framework podporuje načítání rozšířené generace (RAG) prostřednictvím zprostředkovatelů kontextu, kteří přidávají načtený obsah před vyvoláním modelu a vyhledávacími nástroji, které umožňují modelu načíst základní data na vyžádání.

Vzory konverzací a relací společně s načítáním najdete v tématu Přehled konverzací a paměti. Informace o nastavení specifické pro službu najdete v tématu Azure AI Vyhledávač, Microsoft Foundry a Neo4j.

Použití TextSearchProvideru

Třída TextSearchProvider je předefinovaná implementace zprostředkovatele kontextu RAG. Podporuje různé režimy provozu, například vyhledávání jednotlivých agentů s historií chatu nebo reklamní nástroje pro vyhledávání.

Můžete ho ChatClientAgentAIContextProviders snadno připojit k použití této možnosti.

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

Vyžaduje TextSearchProvider funkci, která poskytuje výsledky hledání zadanému dotazu. Lze ji implementovat pomocí libovolné vyhledávací technologie, například Azure AI Vyhledávač nebo webového vyhledávacího webu.

Tip

Další informace o použití vektorového úložiště pro výsledky hledání najdete v tématu Integrace vektorového úložiště .

Tady je příklad napodobení vyhledávací funkce, která vrací předem definované výsledky na základě dotazu. SourceName a SourceLink jsou volitelné, ale pokud je zadaná, bude agent používat k citování zdroje informací při odpovídání na otázku uživatele.

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

Možnosti TextSearchProvider

Dá TextSearchProvider se přizpůsobit prostřednictvím TextSearchProviderOptions třídy. Tady je příklad vytvoření možností pro spuštění vyhledávání před každým vyvoláním modelu a krátké průběžné okno historie chatu pro hledání.

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

Třída TextSearchProvider podporuje následující možnosti prostřednictvím TextSearchProviderOptions třídy.

Option	Typ	Description	Výchozí
Čas hledání	`TextSearchProviderOptions.TextSearchBehavior`	Označuje, kdy má být vyhledávání provedeno. Existují dvě možnosti, při každém spuštění agenta nebo volání funkce na vyžádání.	`TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke`
FunctionToolName	`string`	Název vystaveného vyhledávacího nástroje při provozu v režimu na vyžádání.	"Hledat"
FunctionToolDescription	`string`	Popis vystaveného vyhledávacího nástroje při provozu v režimu na vyžádání.	"Umožňuje hledání dalších informací, které pomáhají zodpovědět otázku uživatele."
ContextPrompt	`string`	Kontextový řádek s předponou výsledků.	"## Další kontext\npři odpovídání na uživatele zvažte následující informace ze zdrojových dokumentů:"
CitationsPrompt	`string`	Instrukce připojená po výsledcích k vyžádání citací.	"Do zdrojového dokumentu uveďte citace s názvem dokumentu a odkazem, pokud je k dispozici název dokumentu a odkaz."
ContextFormatter	`Func<IList<TextSearchProvider.TextSearchResult>, string>`	Volitelný delegát pro úplné přizpůsobení formátování seznamu výsledků Pokud je k dispozici, `ContextPrompt` a `CitationsPrompt` jsou ignorovány.	`null`
RecentMessageMemoryLimit	`int`	Počet nedávných zpráv konverzace (uživatele i asistenta), které mají zůstat v paměti, a zahrnout při vytváření vstupu hledání hledání `BeforeAIInvoke` .	`0` (zakázáno)
RecentMessageRolesIncluded	`List<ChatRole>`	Seznam `ChatRole` typů pro filtrování posledních zpráv při rozhodování, které poslední zprávy mají být zahrnuty při vytváření vstupu hledání.	`ChatRole.User`

Tip

Kompletní příklady s možností spuštění najdete v ukázkách .NET.

Agent Framework poskytuje nativní kontrakty úložiště vektorů a create_vector_search_tool(). Pomocná rutina změní jakoukoli SupportsVectorSearch implementaci na nástroj funkce, aby model mohl načíst základní data, než odpoví.

Vytvoření nativního nástroje pro vyhledávání vektorů

Nejprve definujte model vektorového úložiště, vytvořte kolekci a načtěte její záznamy. Následující ukázka používá InMemoryCollection s OpenAIEmbeddingClient, ale můžete zadat libovolnou nativní agent framework kolekce, která implementuje SupportsVectorSearch. Pak zpřístupní volitelné filtry kategorií a hodnocení modelu, namapuje každý výsledek na zemnění textu a před odpověďmi dá agentovi pokyn, aby vyhledal:

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)

Úplná ukázka definuje Hotel model a před nastavením zobrazené kolekce načte zdrojové záznamy. Nastavte OPENAI_API_KEY před spuštěním.

Přizpůsobení chování hledání

Nakonfigurujte create_vector_search_tool() následující možnosti:

Option	Purpose
`name`	Nastaví název funkce vystavený modelu. Pokud přidáte více vyhledávacích nástrojů, použijte jedinečný název.
`description`	Vysvětluje, kdy a proč by model měl nástroj používat.
`approval_mode`	Nastaví schválení nástroje na `always_require` nebo `never_require`.
`search_type`	Vybere `vector` nebo `keyword_hybrid` vyhledá. Kolekce musí podporovat vybraný režim.
`top` a `skip`	Nastavte pevné stránkovací hodnoty nebo použijte typové `Param` hodnoty, které model poskytuje.
`filter`	Použije přenosnou `Filter` nebo `FilterGroup`. Filtr může obsahovat zadané `Param` hodnoty zveřejněné ve schématu nástroje.
`result_mapper`	Převede každou z nich `SearchResponse` na text nebo multimodální `Content` model.

Vygenerovaný nástroj vždy obsahuje query řetězec. Všechny Param hodnoty ve filtru topnebo skip nastavení se stanou dalšími ověřenými argumenty nástroje. Použití Literal a číselná omezení k zachování hodnot zadaných modelem v rozsahu, který vaše aplikace přijímá.

Můžete vytvořit více nástrojů pro různé kolekce nebo režimy hledání. Dejte každému nástroji odlišný a namedescription model tak, aby mohl vybrat příslušný zdroj znalostí.

Volba nativního úložiště vektorů

Nativní Python implementace jsou k dispozici pro vyhledávání v paměti, Azure AI Vyhledávač, PostgreSQL s pgvectorem, Qdrantem a Redisem. Jejich režimy hledání, životní cyklus balíčků, instalační příkazy a omezení se liší. Viz Integrace vektorového úložiště pro výběr a konfiguraci implementace. Tato stránka také identifikuje databáze, které aktuálně mají pouze samostatný konektor Sémantické jádro.

Poznámka:

Podpora této funkce v Go již brzy. Nejnovější stav najdete v úložišti Agent Framework Go .

Graf RAG

Pro GraphRAG s využitím procházení grafů rozšířené vyhledávání s dotazy Cypher, viz Neo4j GraphRAG Provider.

Další kroky

Deklarativní agenti

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-09-11