RAG

Microsoft Agent Framework unterstützt Die Abruferweiterung (Retrieval Augmented Generation, RAG) über Kontextanbieter, die abgerufene Inhalte vor dem Modellaufruf und Suchtools hinzufügen, mit denen das Modell Die Bodenungsdaten bei Bedarf abrufen kann.

Informationen zu Unterhaltungs-/Sitzungsmustern zusammen mit dem Abruf finden Sie unter "Unterhaltungen und Speicher". Dienstspezifische Einrichtung finden Sie unter Azure KI-Suche, Microsoft Foundry und Neo4j.

Verwenden von TextSearchProvider

Die TextSearchProvider Klasse ist eine out-of-the-box-Implementierung eines RAG-Kontextanbieters. Es unterstützt verschiedene Betriebsmodi, z. B. die Suche nach jedem Agent, der mit dem Chatverlauf ausgeführt wird, oder Werbefunktionstools für suchvorgänge.

Sie kann einfach mit ChatClientAgent der AIContextProviders Option verbunden werden.

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

Dies TextSearchProvider erfordert eine Funktion, die die Suchergebnisse einer Abfrage bereitstellt. Dies kann mit jeder Suchtechnologie, z. B. Azure KI-Suche, oder einer Websuchmaschine implementiert werden.

Tip

Weitere Informationen zur Verwendung eines Vektorspeichers für Suchergebnisse finden Sie unter Vector Store-Integrationen .

Hier ist ein Beispiel für eine simulierte Suchfunktion, die vordefinierte Ergebnisse basierend auf der Abfrage zurückgibt. SourceName und SourceLink optional, aber wenn angegeben, wird der Agent verwendet, um die Quelle der Informationen zu zitieren, wenn die Frage des Benutzers beantwortet wird.

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-Optionen

Die TextSearchProvider kann über die TextSearchProviderOptions Klasse angepasst werden. Hier sehen Sie ein Beispiel für das Erstellen von Optionen zum Ausführen der Suche vor jedem Modellaufruf und halten ein kurzes rollierendes Fenster des Chatverlaufs für Suchvorgänge.

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

Die TextSearchProvider Klasse unterstützt die folgenden Optionen über die TextSearchProviderOptions Klasse.

Auswahl	Type	Description	Default
Suchzeit	`TextSearchProviderOptions.TextSearchBehavior`	Gibt an, wann die Suche ausgeführt werden soll. Es gibt zwei Optionen, jedes Mal, wenn der Agent ausgeführt wird, oder bei Bedarf über Funktionsaufrufe.	`TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke`
FunctionToolName	`string`	Der Name des verfügbar gemachten Suchtools beim Betrieb im On-Demand-Modus.	"Suchen"
FunctionToolDescription	`string`	Die Beschreibung des verfügbar gemachten Suchtools beim Betrieb im On-Demand-Modus.	"Ermöglicht die Suche nach zusätzlichen Informationen, um die Frage des Benutzers zu beantworten."
ContextPrompt	`string`	Die Kontextaufforderung mit dem Präfix "Ergebnisse".	"## Zusätzlicher Kontext\nBerücksichtigen Sie beim Antworten auf den Benutzer die folgenden Informationen aus Quelldokumenten:"
ZitatePrompt	`string`	Die Anweisung, die nach ergebnissen angefügt wurde, um Zitate anzufordern.	"Fügen Sie Zitate in das Quelldokument mit Dokumentname und Link ein, wenn dokumentname und link verfügbar sind."
ContextFormatter	`Func<IList<TextSearchProvider.TextSearchResult>, string>`	Optionaler Delegat zum vollständigen Anpassen der Formatierung der Ergebnisliste. Wenn angegeben `ContextPrompt` und `CitationsPrompt` ignoriert werden.	`null`
RecentMessageMemoryLimit	`int`	Die Anzahl der zuletzt verwendeten Unterhaltungsnachrichten (sowohl Benutzer als auch Assistent), die im Arbeitsspeicher bleiben sollen, und die beim Erstellen der Sucheingabe für `BeforeAIInvoke` Suchvorgänge einbezogen werden sollen.	`0` (deaktiviert)
RecentMessageRolesIncluded	`List<ChatRole>`	Die Liste der `ChatRole` Typen, nach denen zuletzt verwendete Nachrichten gefiltert werden sollen, wenn Sie entscheiden, welche zuletzt verwendeten Nachrichten beim Erstellen der Sucheingabe einbezogen werden sollen.	`ChatRole.User`

Tip

In den .NET-Beispielen finden Sie vollständige ausführbare Beispiele.

Agent Framework bietet native Vektorspeicherverträge und create_vector_search_tool(). Der Hilfsprogramm wandelt jede SupportsVectorSearch Implementierung in ein Funktionstool um, sodass das Modell Erdungsdaten abrufen kann, bevor es antwortet.

Erstellen eines nativen Vektorsuchtools

Definieren Sie zunächst Ihr Vektorspeichermodell, erstellen Sie eine Sammlung, und laden Sie die Datensätze. Im folgenden Beispiel wird die InMemoryCollection Verwendung mit OpenAIEmbeddingClient. Sie können jedoch jede systemeigene Agent Framework-Auflistung bereitstellen, die implementiert SupportsVectorSearchwird. Anschließend werden optionale Kategorie- und Bewertungsfilter für das Modell verfügbar gemacht, die einzelnen Ergebnisse dem Erdungstext zugeordnet und der Agent angewiesen, vor der Antwort zu suchen:

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)

Im vollständigen Beispiel wird das Hotel Modell definiert und die Quelldatensätze vor dem Setup der angezeigten Auflistung geladen. Legen Sie diese Einstellung OPENAI_API_KEY fest, bevor Sie sie ausführen.

Anpassen des Suchverhaltens

Konfigurieren Sie create_vector_search_tool() mit den folgenden Optionen:

Auswahl	Purpose
`name`	Legt den Funktionsnamen fest, der für das Modell verfügbar gemacht wird. Verwenden Sie einen eindeutigen Namen, wenn Sie mehrere Suchtools hinzufügen.
`description`	Erläutert, wann und warum das Modell das Tool verwenden soll.
`approval_mode`	Legt die Toolgenehmigung auf `always_require` oder `never_require`.
`search_type`	`vector` Wählt aus oder `keyword_hybrid` sucht. Die Sammlung muss den ausgewählten Modus unterstützen.
`top` und `skip`	Legen Sie feste Auslagerungswerte fest, oder verwenden Sie typierte `Param` Werte, die das Modell bereitstellt.
`filter`	Wendet ein portables `Filter` oder `FilterGroup`. Ein Filter kann typierte `Param` Werte enthalten, die im Toolschema verfügbar gemacht werden.
`result_mapper`	Wandelt jeden `SearchResponse` text- oder multimodalen `Content` Text für das Modell um.

Das generierte Tool enthält immer eine query Zeichenfolge. Alle Param Werte im Filter, topoder skip einstellungen werden zu zusätzlichen überprüften Toolargumenten. Verwenden Sie Literal und numerische Einschränkungen, um vom Modell bereitgestellte Werte innerhalb des Bereichs beizubehalten, den Ihre Anwendung akzeptiert.

Sie können mehrere Tools für verschiedene Sammlungen oder Suchmodi erstellen. Weisen Sie jedem Tool ein eigenes name Tool zu, und description damit das Modell die entsprechende Wissensquelle auswählen kann.

Auswählen eines nativen Vektorspeichers

Native Python Implementierungen stehen für die In-Memory-Suche, Azure KI-Suche, PostgreSQL mit pgvector, Qdrant und Redis zur Verfügung. Ihre Suchmodi, paketlebenszyklus, Installationsbefehle und Einschränkungen unterscheiden sich. Siehe Vector Store-Integrationen zum Auswählen und Konfigurieren einer Implementierung. Diese Seite identifiziert auch Datenbanken, die derzeit nur über einen separaten Semantischer Kernel Connector verfügen.

Note

Unterstützung für dieses Feature wird in Kürze verfügbar sein. Den neuesten Status finden Sie im Agent Framework Go-Repository .

Graph-RAG

Informationen zu GraphRAG mithilfe der graphischen Traversal-Suche mit Cypher-Abfragen finden Sie im Neo4j GraphRAG-Anbieter.

Nächste Schritte

Deklarative Agents

Feedback

War diese Seite hilfreich?

Last updated on 2026-09-11