TUCH

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.

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.

Agent Framework unterstützt die Verwendung der VectorStore-Sammlungen von Semantischer Kernel, um RAG-Funktionen für Agents bereitzustellen. Dies wird durch die Brückenfunktionalität erreicht, die Semantischer Kernel Suchfunktionen in Agent Framework-Tools konvertiert.

Erstellen eines Suchtools aus VectorStore

Die create_search_function-Methode aus einer Semantischer Kernel VectorStore-Auflistung gibt eine KernelFunction zurück, die mithilfe von .as_agent_framework_tool() in ein Agent Framework-Tool konvertiert werden kann. Verwenden Sie die Dokumentation zu Vektorspeicherconnectors , um zu erfahren, wie Verschiedene Vektorspeichersammlungen eingerichtet werden.

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)

Anpassen des Suchverhaltens

Sie können die Suchfunktion mit verschiedenen Optionen anpassen:

# 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}",
)

Ausführliche Informationen zu den für create_search_function verfügbaren Parametern finden Sie in der dokumentation Semantischer Kernel.

Verwenden mehrerer Suchfunktionen

Sie können einem Agent für verschiedene Wissensdomänen mehrere Suchtools bereitstellen:

# 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]
)

Sie können auch mehrere Suchfunktionen aus derselben Sammlung mit unterschiedlichen Beschreibungen und Parametern erstellen, um spezielle Suchfunktionen bereitzustellen:

# 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]
)

Mit diesem Ansatz kann der Agent die am besten geeignete Suchstrategie basierend auf der Abfrage des Benutzers auswählen.

Unterstützte VectorStore-Connectors

Dieses Muster funktioniert mit jedem Semantischer Kernel VectorStore-Connector, einschließlich:

• Azure KI-Suche (AzureAISearchCollection)
• Qdrant (QdrantCollection)
• Pinecone (PineconeCollection)
• Redis (RedisCollection)
• Weaviate (WeaviateCollection)
• In-Memory (InMemoryVectorStoreCollection)
• Und mehr

Jeder Connector stellt die gleiche create_search_function Methode bereit, die mit Agent Framework-Tools überbrückt werden kann, sodass Sie die Vektordatenbank auswählen können, die Ihren Anforderungen am besten entspricht. Die vollständige Liste finden Sie hier.