RAG

Microsoft Struktura agentów obsługuje pobieranie rozszerzonej generacji (RAG) za pośrednictwem dostawców kontekstu, którzy dodają pobraną zawartość przed wywołaniem modelu i narzędziami wyszukiwania, które umożliwiają modelowi pobieranie danych uziomowych na żądanie.

Wzorce konwersacji/sesji obok pobierania można znaleźć w temacie Konwersacje i pamięć — omówienie. Aby zapoznać się z konfiguracją specyficzną dla usługi, zobacz Wyszukiwanie AI platformy Azure, Microsoft Foundry i Neo4j.

Korzystanie z elementu TextSearchProvider

Klasa TextSearchProvider jest wbudowaną implementacją dostawcy kontekstu RAG. Obsługuje różne tryby działania, np. wyszukiwanie każdego agenta uruchamianego z historią czatu lub narzędziami funkcji reklamowych do wyszukiwania.

Można go łatwo dołączyć do ChatClientAgent elementu przy użyciu AIContextProviders opcji .

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

Funkcja TextSearchProvider wymaga funkcji, która udostępnia wyniki wyszukiwania przy użyciu zapytania. Można to zaimplementować przy użyciu dowolnej technologii wyszukiwania, np. Wyszukiwanie AI platformy Azure lub wyszukiwarki internetowej.

Tip

Aby uzyskać więcej informacji na temat używania magazynu wektorów do wyszukiwania wyników wyszukiwania, zobacz Integracja magazynu wektorów .

Oto przykład pozornej funkcji wyszukiwania, która zwraca wstępnie zdefiniowane wyniki na podstawie zapytania. SourceName i SourceLink są opcjonalne, ale jeśli zostanie podany przez agenta, będzie używany do przytaczania źródła informacji podczas odpowiadania na pytanie użytkownika.

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

Opcje textSearchProvider

Element TextSearchProvider można dostosować za pomocą TextSearchProviderOptions klasy . Oto przykład tworzenia opcji uruchamiania wyszukiwania przed każdym wywołaniem modelu i utrzymywanie krótkiego okna kroczącego historii czatów w poszukiwaniu wyszukiwania.

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

Klasa TextSearchProvider obsługuje następujące opcje za pośrednictwem TextSearchProviderOptions klasy .

Option	Typ	Opis	Default
Czas wyszukiwania	TextSearchProviderOptions.TextSearchBehavior	Wskazuje, kiedy należy wykonać wyszukiwanie. Istnieją dwie opcje, za każdym razem, gdy agent jest uruchamiany lub na żądanie za pośrednictwem wywołania funkcji.	TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke
FunctionToolName	string	Nazwa uwidocznionego narzędzia wyszukiwania podczas pracy w trybie na żądanie.	"Wyszukaj"
FunctionToolDescription	string	Opis uwidocznionego narzędzia wyszukiwania podczas pracy w trybie na żądanie.	"Umożliwia wyszukiwanie dodatkowych informacji, aby pomóc w udzieleniu odpowiedzi na pytanie użytkownika".
ContextPrompt	string	Monit kontekstowy poprzedzony wynikami.	"## Dodatkowy kontekst\nRozważ następujące informacje z dokumentów źródłowych podczas odpowiadania użytkownikowi:"
CytatyPrompt	string	Instrukcja dołączona po wynikach w celu żądania cytatów.	"Dołącz cytaty do dokumentu źródłowego z nazwą dokumentu i linkiem, jeśli dostępna jest nazwa i link dokumentu".
ContextFormatter	Func<IList<TextSearchProvider.TextSearchResult>, string>	Opcjonalny delegat w celu pełnego dostosowania formatowania listy wyników. W przypadku podania ContextPrompt wartości i CitationsPrompt są ignorowane.	null
RecentMessageMemoryLimit	int	Liczba ostatnich wiadomości konwersacji (zarówno użytkownika, jak i asystenta), które mają być przechowywane w pamięci i uwzględniane podczas konstruowania danych wejściowych wyszukiwania wyszukiwania BeforeAIInvoke .	0 (wyłączone)
RecentMessageRolesIncluded	List<ChatRole>	Lista typów do filtrowania ostatnich komunikatów ChatRole podczas podejmowania decyzji, które ostatnie komunikaty mają być uwzględniane podczas konstruowania danych wejściowych wyszukiwania.	ChatRole.User

Tip

Zobacz przykłady .NET dla kompletnych, działających przykładów.

Struktura agenta udostępnia natywne kontrakty wektorów i create_vector_search_tool(). Pomocnik zamienia dowolną SupportsVectorSearch implementację w narzędzie funkcji, dzięki czemu model może pobrać dane uziemieniowe przed odpowiedziami.

Tworzenie natywnego narzędzia wyszukiwania wektorów

Najpierw zdefiniuj model magazynu wektorów, utwórz kolekcję i załaduj jego rekordy. W poniższym przykładzie użyto polecenia z elementem InMemoryCollectionOpenAIEmbeddingClient, ale można podać dowolną natywną kolekcję platformy Agent Framework, która implementuje SupportsVectorSearchelement . Następnie uwidacznia opcjonalne filtry kategorii i klasyfikacji do modelu, mapuje każdy wynik na tekst uziemienia i nakazuje agentowi wyszukiwanie przed uzyskaniem odpowiedzi:

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)

Pełny przykład definiuje Hotel model i ładuje rekordy źródłowe przed pokazaną konfiguracją kolekcji. Ustaw OPENAI_API_KEY przed jego uruchomieniem.

Dostosowywanie zachowania wyszukiwania

Skonfiguruj create_vector_search_tool() przy użyciu następujących opcji:

Option	Purpose
name	Ustawia nazwę funkcji uwidacznianą dla modelu. Użyj unikatowej nazwy podczas dodawania wielu narzędzi wyszukiwania.
description	Wyjaśnia, kiedy i dlaczego model powinien używać narzędzia.
approval_mode	Ustawia zatwierdzenie narzędzia na lub always_requirenever_require.
search_type	vector Wybiera lub keyword_hybrid wyszukuje. Kolekcja musi obsługiwać wybrany tryb.
top i skip	Ustaw stałe wartości stronicowania lub użyj wpisanych Param wartości, które dostarcza model.
filter	Stosuje przenośny Filter lub FilterGroup. Filtr może zawierać wpisane Param wartości uwidocznione w schemacie narzędzia.
result_mapper	Konwertuje każdą z nich SearchResponse na tekst lub wielomodalny Content dla modelu.

Wygenerowane narzędzie zawsze zawiera query ciąg. Wszystkie Param wartości w filtrze lub topskip ustawieniach stają się dodatkowymi zweryfikowanymi argumentami narzędzi. Użyj Literal ograniczeń liczbowych i , aby zachować wartości dostarczone przez model w zakresie akceptowanym przez aplikację.

Można utworzyć wiele narzędzi dla różnych kolekcji lub trybów wyszukiwania. Nadaj każdemu narzędziu odrębne name , description aby model mógł wybrać odpowiednie źródło wiedzy.

Wybieranie natywnego magazynu wektorów

Natywne implementacje Python są dostępne dla wyszukiwania w pamięci, Wyszukiwanie AI platformy Azure, PostgreSQL z pgvector, Qdrant i Redis. Ich tryby wyszukiwania, cykl życia pakietu, polecenia instalacji i ograniczenia różnią się. Zobacz Integracje magazynu wektorowego , aby wybrać i skonfigurować implementację. Ta strona identyfikuje również bazy danych, które obecnie mają tylko oddzielny łącznik Semantic Kernel.

Uwaga / Notatka

Obsługa tej funkcji w języku Go będzie dostępna wkrótce. Aktualny status znajdziesz w repozytorium Agent Framework dla Go.

Graf RAG

Aby zapoznać się z usługą GraphRAG przy użyciu przechodzenia grafu wzbogaconego wyszukiwania za pomocą zapytań Cyprher, zobacz Dostawca Neo4j GraphRAG.

Następne kroki

Agenci deklaratywne