Kain lap

Microsoft Agent Framework mendukung Pengambilan Pembuatan Tertambah (RAG) melalui penyedia konteks yang menambahkan konten yang diambil sebelum pemanggilan model dan alat pencarian yang memungkinkan model mengambil data grounding sesuai permintaan.

Untuk pola percakapan/sesi bersama pengambilan, lihat Percakapan & Gambaran umum memori. Untuk penyiapan khusus layanan, lihat Pencarian Azure AI, Microsoft Foundry, dan Neo4j.

Menggunakan TextSearchProvider

Kelas TextSearchProvider ini adalah implementasi out-of-the-box dari penyedia konteks RAG. Ini mendukung berbagai mode operasi, misalnya melakukan pencarian untuk setiap agen yang dijalankan dengan riwayat obrolan, atau alat fungsi iklan untuk melakukan pencarian.

Ini dapat dengan mudah dilampirkan ke ChatClientAgent menggunakan AIContextProviders opsi .

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

TextSearchProvider memerlukan fungsi yang menyediakan hasil pencarian yang diberikan kueri. Ini dapat diimplementasikan menggunakan teknologi pencarian apa pun, misalnya Pencarian Azure AI, atau mesin pencari web.

Tip

Lihat Integrasi penyimpanan vektor untuk informasi selengkapnya tentang cara menggunakan penyimpanan vektor untuk hasil pencarian.

Berikut adalah contoh fungsi pencarian tiruan yang mengembalikan hasil yang telah ditentukan sebelumnya berdasarkan kueri. SourceName dan SourceLink bersifat opsional, tetapi jika disediakan akan digunakan oleh agen untuk mengutip sumber informasi saat menjawab pertanyaan pengguna.

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

Opsi TextSearchProvider

TextSearchProvider dapat disesuaikan melalui TextSearchProviderOptions kelas . Berikut adalah contoh membuat opsi untuk menjalankan pencarian sebelum setiap pemanggilan model dan menyimpan jendela bergulir singkat riwayat obrolan untuk pencarian.

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

Kelas TextSearchProvider mendukung opsi berikut melalui TextSearchProviderOptions kelas .

Option	Type	Deskripsi	Default
WaktuPencarian	`TextSearchProviderOptions.TextSearchBehavior`	Menunjukkan kapan pencarian harus dijalankan. Ada dua opsi, setiap kali agen dijalankan, atau sesuai permintaan melalui panggilan fungsi.	`TextSearchProviderOptions.TextSearchBehavior.BeforeAIInvoke`
FunctionToolName	`string`	Nama alat pencarian yang diekspos saat beroperasi dalam mode sesuai permintaan.	"Cari"
FunctionToolDescription	`string`	Deskripsi alat pencarian yang diekspos saat beroperasi dalam mode sesuai permintaan.	"Memungkinkan pencarian informasi tambahan untuk membantu menjawab pertanyaan pengguna."
ContextPrompt	`string`	Permintaan konteks diawali dengan hasil.	"## Konteks Tambahan\nPertimbangkan informasi berikut dari dokumen sumber saat merespons pengguna:"
CitationsPrompt	`string`	Instruksi ditambahkan setelah hasil untuk meminta kutipan.	"Sertakan kutipan ke dokumen sumber dengan nama dokumen dan tautan jika nama dokumen dan tautan tersedia."
ContextFormatter	`Func<IList<TextSearchProvider.TextSearchResult>, string>`	Delegasi opsional untuk sepenuhnya menyesuaikan pemformatan daftar hasil. Jika disediakan, `ContextPrompt` dan `CitationsPrompt` diabaikan.	`null`
RecentMessageMemoryLimit	`int`	Jumlah pesan percakapan terbaru (pengguna dan asisten) untuk disimpan dalam memori dan disertakan saat membuat input pencarian untuk `BeforeAIInvoke` pencarian.	`0` (dinonaktifkan)
RecentMessageRolesIncluded	`List<ChatRole>`	Daftar jenis `ChatRole` untuk memfilter pesan terbaru saat memutuskan pesan terbaru mana yang akan disertakan saat membuat input pencarian.	`ChatRole.User`

Tip

Lihat sampel .NET untuk contoh lengkap yang dapat dijalankan.

Agent Framework menyediakan kontrak penyimpanan vektor asli dan create_vector_search_tool(). Pembantu mengubah implementasi apa pun SupportsVectorSearch menjadi alat fungsi, sehingga model dapat mengambil data grounding sebelum menjawab.

Membuat alat pencarian vektor asli

Pertama, tentukan model penyimpanan vektor Anda, buat koleksi, dan muat rekamannya. Sampel berikut menggunakan InMemoryCollection dengan OpenAIEmbeddingClient, tetapi Anda dapat menyediakan koleksi Agent Framework asli yang mengimplementasikan SupportsVectorSearch. Kemudian mengekspos kategori opsional dan filter peringkat ke model, memetakan setiap hasil ke teks grounding, dan menginstruksikan agen untuk mencari sebelum menjawab:

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)

Sampel lengkap menentukan Hotel model dan memuat rekaman sumber sebelum penyiapan koleksi yang ditampilkan. Atur OPENAI_API_KEY sebelum Anda menjalankannya.

Menyesuaikan perilaku pencarian

Konfigurasikan create_vector_search_tool() dengan opsi berikut:

Option	Kegunaan
`name`	Mengatur nama fungsi yang diekspos ke model. Gunakan nama unik saat Anda menambahkan beberapa alat pencarian.
`description`	Menjelaskan kapan dan mengapa model harus menggunakan alat ini.
`approval_mode`	Mengatur persetujuan alat ke `always_require` atau `never_require`.
`search_type`	`vector` Memilih atau `keyword_hybrid` mencari. Koleksi harus mendukung mode terpilih.
`top` dan `skip`	Atur nilai halaman tetap atau gunakan nilai yang ditik `Param` yang disediakan model.
`filter`	Menerapkan portabel `Filter` atau `FilterGroup`. Filter dapat berisi nilai yang diketik `Param` yang diekspos dalam skema alat.
`result_mapper`	Mengonversi masing-masing `SearchResponse` menjadi teks atau multimodal `Content` untuk model.

Alat yang dihasilkan selalu menyertakan query string. Nilai apa pun Param dalam filter, top, atau skip pengaturan menjadi argumen alat tervalidasi tambahan. Gunakan Literal batasan numerik untuk menjaga nilai yang disediakan model dalam rentang yang diterima aplikasi Anda.

Anda dapat membuat beberapa alat untuk koleksi atau mode pencarian yang berbeda. Berikan setiap alat yang berbeda name sehingga description model dapat memilih sumber pengetahuan yang sesuai.

Pilih penyimpanan vektor asli

Implementasi Python asli tersedia untuk pencarian dalam memori, Pencarian Azure AI, PostgreSQL dengan pgvector, Qdrant, dan Redis. Mode pencarian, siklus hidup paket, perintah penginstalan, dan batasannya berbeda. Lihat Integrasi penyimpanan vektor untuk memilih dan mengonfigurasi implementasi. Halaman itu juga mengidentifikasi database yang saat ini hanya memiliki konektor Kernel Semantik terpisah.

Nota

Dukungan Go untuk fitur ini akan segera hadir. Lihat repositori Agent Framework Go untuk status terbaru.

Grafik RAG

Untuk GraphRAG menggunakan pencarian yang diperkaya traversal grafik dengan kueri Cypher, lihat Penyedia Neo4j GraphRAG.

Langkah berikutnya

Agen Deklaratif

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-09-11