Integrasi penyimpanan vektor

Penyimpanan vektor menyimpan data dan penyematan vektornya bersama-sama sehingga aplikasi dapat menemukan rekaman dengan kesamaan semantik. Dalam aplikasi Agent Framework, Anda dapat menggunakan penyimpanan vektor untuk mengambil data grounding untuk Pengambilan Augmented Generation (RAG) atau untuk menyimpan informasi yang dapat diingat oleh agen nanti.

Abstraksi penyimpanan vektor menyediakan operasi umum untuk koleksi dan rekaman, menjaga logika aplikasi Anda dipisahkan dari implementasi penyimpanan vektor tertentu. Misalnya, Anda dapat memulai dengan implementasi lokal dan beralih ke layanan terkelola dengan perubahan minimal.

Cara kerja integrasi penyimpanan vektor

Alur kerja penyimpanan vektor umum mencakup langkah-langkah berikut:

  1. Tentukan model data yang mengidentifikasi kunci rekaman, bidang data, dan bidang vektor.
  2. Konfigurasikan generator penyematan jika penyimpanan vektor tidak menghasilkan penyematan.
  3. Sambungkan ke penyimpanan vektor dan pilih atau buat koleksi.
  4. Hasilkan penyematan dan upsert rekaman ke dalam koleksi.
  5. Cari koleksi dengan teks atau vektor, tergantung pada kemampuan implementasi.
  6. Teruskan hasil pencarian yang relevan ke agen sebagai konteks atau jadikan pencarian sebagai alat untuk agen.

dukungan penyimpanan vektor .NET

Agent Framework menggunakan abstraksi mandiri ekosistem AI .NET:

Di mana komponen Agent Framework menerima penyimpanan vektor, Anda dapat menyediakan implementasi yang kompatibel Microsoft.Extensions.VectorData . Setiap implementasi database didistribusikan secara terpisah dari paket abstraksi.

Abstraksi inti

Abstraksi Kegunaan
VectorStore Menyediakan operasi pada berbagai koleksi dan membuat instans koleksi berjenis.
VectorStoreCollection<TKey, TRecord> Membuat atau menghapus koleksi serta memperbarui atau menyisipkan, mengambil, atau menghapus rekamannya.
IVectorSearchable<TRecord> Mencari record berdasarkan vektor atau teks ketika generator penyematan atau kemampuan penyematan di sisi database tersedia.

Implementasi penyimpanan vektor yang tersedia

Implementasi berikut menggunakan abstraksi penyimpanan vektor .NET umum. Tinjau dokumentasi setiap implementasi untuk versi paket, jenis data yang didukung, dan batasan khusus layanan.

Implementation Availability Menggunakan SDK database yang didukung secara resmi Pemelihara atau penyedia
Pencarian Azure AI Available Yes Microsoft
Azure Cosmos DB untuk MongoDB vCore Available Yes Microsoft
Azure Cosmos DB untuk NoSQL Available Yes Microsoft
Couchbase Available Yes Couchbase
Elasticsearch Available Yes Elastic
Chroma Planned Tidak teraplikasi Tidak teraplikasi
Dalam memori Available Tidak teraplikasi Microsoft
Milvus Planned Tidak teraplikasi Tidak teraplikasi
MongoDB Available Yes Microsoft
Neon Serverless Postgres Menggunakan implementasi Postgres Yes Microsoft
Oracle Available Yes Oracle
Pinecone Available No Microsoft
Postgres Available Yes Microsoft
Qdrant Available Yes Microsoft
Redis Available Yes Microsoft
SQL Server Available Yes Microsoft
SQLite Available Yes Microsoft
Volatil dalam memori Tidak digunakan lagi; menggunakan implementasi dalam memori Tidak teraplikasi Microsoft
Weaviate Available Yes Microsoft

Important

Implementasi penyimpanan vektor disediakan oleh berbagai pengelola. Evaluasi kualitas, lisensi, kebijakan dukungan, dan kompatibilitas versi setiap implementasi sebelum Anda menggunakannya. Beberapa implementasi menggunakan SDK database yang tidak didukung oleh penyedia database secara resmi.

Get started

  1. Tambahkan Microsoft.Extensions.VectorData.Abstractions paket dan paket untuk implementasi penyimpanan vektor yang Anda pilih.
  2. Tentukan jenis catatan dan identifikasi properti kunci, data, dan vektornya.
  3. Konfigurasikan sebuah IEmbeddingGenerator jika implementasi Anda memerlukan embedding yang dihasilkan aplikasi.
  4. Buat implementasi VectorStore, lalu dapatkan jenis VectorStoreCollection<TKey, TRecord>.
  5. Pastikan koleksi ada, upsert data, dan panggil SearchAsync dengan teks atau vektor.

Untuk pengenalan lengkap model data, penyerapan, penyematan, dan pencarian, lihat Database vektor untuk aplikasi AI .NET.

dukungan penyimpanan vektor Python

Agent Framework menyediakan kontrak Python eksperimental, asli untuk model penyimpanan vektor, operasi pengumpulan, pabrik toko, pencarian vektor dan kata kunci-hibrid, dan alat pencarian agen. Kontrak tersebut adalah bagian dari agent-framework-core dan tidak memerlukan Pydantic, NumPy, pandas, atau Kernel Semantik.

Warning

API penyimpanan vektor Python asli bersifat eksperimental. Perubahan pembobolan terbatas mungkin terjadi sebelum menjadi stabil.

Abstraksi inti

Abstraksi Kegunaan
VectorStoreField dan VectorStoreCollectionDefinition Menjelaskan bidang kunci, data, dan vektor, termasuk nama penyimpanan, indeks, dimensi, dan fungsi jarak.
@vectorstoremodel dan register_vectorstoremodel() Daftarkan kelas data, model Pydantic, struct msgspec, kelas biasa, atau jenis model yang dimiliki secara eksternal.
BaseVectorCollection dan SupportsVectorUpsert Tentukan upsert batch, dapatkan, hapus, siklus hidup koleksi, konversi rekaman, dan pembuatan penyematan opsional.
BaseVectorStore Mendefinisikan penyimpanan yang mendaftar koleksi dan membuat klien koleksi berjenis.
BaseVectorSearch dan SupportsVectorSearch Tentukan pencarian vektor dan kata kunci-hibrid, penomoran halaman, filter, ambang skor, dan hasil pencarian.
Filter, FilterGroup, dan Param Tentukan filter portabel khusus data, termasuk parameter filter yang disediakan model untuk alat pencarian.
InMemoryStore dan InMemoryCollection Menyediakan CRUD lokal untuk proses dan pencarian dengan pemindaian linear untuk pengembangan dan pengujian.
GenerateVectors Menentukan apakah operasi upsert menghasilkan semua, tidak satu pun, atau bidang vektor yang dipilih.
create_vector_search_tool(), create_upsert_tool(), create_get_tool(), dan create_delete_tool() Mengekspos operasi PENCARIAN vektor dan pengumpulan CRUD sebagai alat fungsi Agent Framework.
VectorStoreHistoryProvider Menyimpan riwayat percakapan dalam cakupan tertentu di koleksi yang dimiliki penyedia, dengan pemadatan opsional dan pencarian di seluruh riwayat.
VectorCollectionContextProvider Menambahkan CRUD yang dapat dikonfigurasi dan alat pencarian untuk koleksi milik penelepon.

Sampel berikut mendefinisikan rekaman penyimpanan vektor dengan menganotasi bidang kunci, data, dan vektornya:

# 5. Dataclasses use the default registered codec.
@vectorstoremodel(collection_name="hotels")
@dataclass
class Hotel:
    hotel_id: Annotated[str, VectorStoreField("key")]
    name: Annotated[str, VectorStoreField("data", is_indexed=True)]
    description: Annotated[
        str | list[float] | None,
        VectorStoreField("vector", dimensions=3, distance_function="cosine_similarity"),
    ] = None


# 6. Pydantic models provide validation with additional round-trip cost.
@vectorstoremodel(collection_name="products")
class Product(BaseModel):
    product_id: Annotated[str, VectorStoreField("key")]
    name: Annotated[str, VectorStoreField("data", is_full_text_indexed=True)]
    vector: Annotated[list[float] | None, VectorStoreField("vector", dimensions=3)] = None

Gunakan VectorStoreCollectionDefinition langsung untuk kamus. Untuk jenis model yang dimiliki oleh paket lain, gunakan register_vectorstoremodel() dengan definisi eksplisit dan encoder dan dekoder opsional. Nilai vektor mirip array diserialkan melalui tolist() tanpa menambahkan ketergantungan NumPy.

Agent Framework mencakup implementasi dalam memori untuk pengembangan dan pengujian. Ini menyimpan rekaman dalam proses saat ini dan menggunakan pemindaian linier, jadi gunakan konektor database untuk beban kerja produksi.

Teruskan opsi embedding untuk setiap operasi

Teruskan embeddings_options ke upsert() untuk menerapkan opsi penyedia ke setiap bidang vektor yang dihasilkan. Gunakan embeddings_options_by_field saat bidang vektor logis yang berbeda memerlukan opsi yang berbeda. Kedua argumen ini saling eksklusif.

Untuk penyematan kueri, teruskan embeddings_options ke search() atau create_vector_search_tool(). Agent Framework menyediakan dimensi yang dideklarasikan bidang vektor yang dipilih dan menolak nilai yang bertentangan dimensions sebelum memanggil penyedia penyematan.

Opsi penyematan upsert memerlukan vektor yang dihasilkan dan tidak dapat dikombinasikan dengan generate_vectors=False. Opsi penyematan pencarian memerlukan generator penyematan lokal dan diabaikan saat Anda menyediakan vektor kueri yang telah dikomputasi sebelumnya.

Sampel berikut menyimpan vektor yang telah dikomputasi sebelumnya dan mencarinya dengan pohon filter portabel:

import asyncio
from dataclasses import dataclass
from typing import Annotated

from agent_framework import Filter, FilterGroup, InMemoryCollection, VectorStoreField, vectorstoremodel
@vectorstoremodel(collection_name="hotels")
@dataclass
class Hotel:
    hotel_id: Annotated[str, VectorStoreField("key")]
    name: Annotated[str, VectorStoreField("data")]
    city: Annotated[str, VectorStoreField("data")]
    rating: Annotated[float, VectorStoreField("data")]
    amenities: Annotated[list[str], VectorStoreField("data")]
    vector: Annotated[
        list[float] | None,
        VectorStoreField("vector", dimensions=2, distance_function="cosine_similarity"),
    ] = None


async def main() -> None:
    """Store precomputed vectors and search them with direct filters."""
    collection: InMemoryCollection[str, Hotel] = InMemoryCollection(Hotel)
    await collection.ensure_collection_exists()

    # 1. The sample already has vectors, so generation is disabled explicitly.
    await collection.upsert(
        [
            Hotel("hotel-1", "Harbor View", "Lisbon", 4.8, ["wifi", "pool"], [1.0, 0.1]),
            Hotel("hotel-2", "Old Town Rooms", "Lisbon", 4.1, ["wifi"], [0.8, 0.2]),
            Hotel("hotel-3", "City Center", "Seattle", 4.7, ["wifi", "gym"], [0.1, 1.0]),
        ],
        generate_vectors=False,
    )

    # 2. Filter values are ordinary data. No Python source is parsed or executed.
    search_filter = FilterGroup(
        "and",
        (
            Filter("city", "eq", "Lisbon"),
            Filter("rating", "between", (4.5, 5.0)),
            Filter("amenities", "contains", "pool"),
        ),
    )
    results = await collection.search(
        vector=[1.0, 0.0],
        filter=search_filter,
        top=5,
    )

    # 3. Search results are consumed asynchronously.
    async for result in results:
        print(f"{result['record'].name}: {result['score']:.3f}")

Gunakan Param saat model harus menyediakan nilai filter. Tipe Python, deskripsi, dan batasannya menjadi bagian dari skema JSON alat pencarian:

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

Gunakan koleksi vektor dengan agen

Gunakan VectorCollectionContextProvider saat aplikasi Anda memiliki model pengumpulan dan data. Penyedia menambahkan CRUD yang dihasilkan dan alat pencarian. Upsert dan hapus memerlukan persetujuan secara bawaan, sedangkan get dan search tidak.

Teruskan scope_filter ke rekaman grup untuk alat yang dihasilkan, tetapi jangan perlakukan filter sebagai batas otorisasi atau jaminan backend atom. Alat pencarian yang diteruskan melalui additional_search_tools tetap menyimpan filter masing-masing, jadi terapkan filter yang setara pada setiap alat khusus saat koleksi dibagikan.

collection: InMemoryCollection[str, ProjectNote] = InMemoryCollection(
    ProjectNote,
    embedding_generator=OpenAIEmbeddingClient(
        model="text-embedding-3-small",
    ),
)
await collection.ensure_collection_exists()

# Omitted mapping entries keep their safe defaults. This sample disables
# approval for upsert so the scripted interaction can run unattended;
# delete still requires approval, while get and search remain read-only.
collection_context = VectorCollectionContextProvider(
    collection,
    # This process-local collection contains records for only this sample.
    scope_filter=None,
    approval_mode={"upsert": "never_require"},
)

async with Agent(
    client=OpenAIChatClient(model="gpt-5.4-nano"),
    name="ProjectNotesAssistant",
    instructions="Use the collection tools to manage project notes. Do not invent stored notes.",
    context_providers=[collection_context],
) as agent:

Menyimpan riwayat percakapan di penyimpanan vektor

Gunakan VectorStoreHistoryProvider saat penyedia harus memiliki skema koleksi dan secara otomatis memuat dan menyimpan pesan Agent Framework. Pengidentifikasi aplikasi, tenant, agen, sumber, dan sesi tersebut mencegah tumpang tindih yang tidak disengaja, tetapi aplikasi Anda tetap harus mengotorisasi akses dan menggunakan kredensial penyimpanan atau namespace dengan cakupan yang sesuai.

Saat Anda mengonfigurasi penyematan, tentukan nama koleksi secara eksplisit dan dimensi penyematan. Pemadatan hanya mengurangi riwayat yang dimuat ke dalam konteks model. Jika Anda mengaktifkan alat pencarian, alat ini akan mencari transkrip cakupan lengkap.

history = VectorStoreHistoryProvider(
    InMemoryStore(),
    application_id="release-planning",
    tenant_id="contoso",
    agent_id="release-assistant",
    collection_name="release_planning_history_text_embedding_3_small",
    contents_format="json",
    embedding_generator=OpenAIEmbeddingClient(
        model="text-embedding-3-small",
    ),
    embedding_options={
        "dimensions": 1536,
        "encoding_format": "float",
    },
    compaction_strategy=SlidingWindowStrategy(
        keep_last_groups=2,
        preserve_system=True,
    ),
    include_search_tool=True,
)

# 2. Only the compacted projection is loaded into the model context. The
#    provider-owned search tool can still retrieve older scoped messages.
async with Agent(
    client=OpenAIChatClient(model="gpt-5.4-nano"),
    name="ReleaseAssistant",
    instructions=(
        "Help with release planning. Use the history search tool when an "
        "older detail is not present in the loaded conversation."
    ),
    context_providers=[history],
) as agent:

Implementasi Native Agent Framework

Implementasi berikut menggunakan kontrak Agent Framework asli. Sebagian juga tersedia sebagai konektor Kernel Semantik tersendiri, tetapi kedua keluarga konektor tersebut tidak dapat saling dipertukarkan.

Implementation Paket dan siklus hidup Agent Framework Pisahkan konektor Kernel Semantik Mode pencarian Batasan kunci
di dalam RAM agent-framework-core; paket yang dirilis dengan API vektor eksperimental Tersedia Vektor padat dengan filter portabel Pemindaian linier lokal proses untuk pengembangan dan pengujian, bukan database produksi.
Pencarian Azure AI agent-framework-azure-ai-search; paket beta dengan API vektor eksperimental Tersedia Vektor padat dan kata kunci-hibrid Satu bidang vektor padat tingkat atas per kueri. Beberapa ambang batas, kontrol penarikan kembali teks hibrid, pasca-pemfilteran yang ketat, dan izin memerlukan pratinjau pendukung SDK/API dan allow_preview=True.
Azure Cosmos DB for NoSQL agent-framework-azure-cosmos; paket beta dengan API vektor eksperimental Tersedia Vektor padat dengan filter portabel Kunci harus berupa string yang disimpan sebagai id, dan kontainer menggunakan /id kunci partisi. Kata kunci dan pencarian hibrid tidak didukung, dan pencarian Euclidean tidak mendukung ambang skor.
Azure DocumentDB agent-framework-azure-documentdb; paket alfa Tidak tersedia Vektor padat dengan filter metadata portabel Kunci harus berupa string atau bilangan bulat. ObjectId yang dibuat secara otomatis, pencarian hibrida dan pencarian teks lengkap, serta jalur filter bertingkat tidak didukung.
DuckDB agent-framework-duckdb; paket alfa Tidak tersedia Vektor padat eksak dengan filter portabel Memerlukan Python 3.10+ dan DuckDB 1.4.1–1.5.x. Indeks aproksimatif, pencarian kata kunci dan hibrida, pencarian teks penuh, dan vektorisasi sisi server tidak didukung. File lokal hanya mengizinkan satu proses penulisan pada satu waktu.
MongoDB agent-framework-mongodb; paket alfa Tersedia Vektor padat perkiraan atau eksak dengan filter portabel Memerlukan PyMongo 4.13.2+ dan penyebaran dengan MongoDB Vector Search. Pencarian kata kunci dan hibrida, jalur filter bertingkat, pembuatan embedding di sisi penyedia, dan migrasi skema otomatis tidak didukung. Model yang menyatakan is_full_text_indexed ditolak, dan rekaman yang baru ditulis menjadi dapat dicari secara asinkron.
Oracle AI Database agent-framework-oracle; paket alfa Tersedia Vektor padat dengan filter portabel Memerlukan Oracle AI Database 26ai dengan COMPATIBLE diatur ke 23.4.0 atau lebih tinggi dan python-oracledb 2.2.x atau 3.x. Manajemen indeks, kata kunci dan pencarian hibrid, filter JSON dan bertingkat, vektorisasi sisi server, dan migrasi skema tidak didukung.
PostgreSQL dengan pgvector agent-framework-postgres; paket alfa Tersedia Vektor padat eksak, HNSW, dan IVFFlat Memerlukan PostgreSQL 13+, pgvector 0.8.0+, skema yang ada, dan ekstensi yang diaktifkan. Kata kunci dan pencarian hibrid tidak didukung.
Qdrant agent-framework-qdrant; paket alfa Tersedia Vektor padat dengan filter portabel di sisi server Mode server memerlukan Qdrant 1.16.2 atau yang lebih baru. Kunci harus berupa bilangan bulat atau UUID 64-bit yang tidak ditandatangani. Kata kunci dan pencarian hibrid tidak didukung, dan filter tidak tersedia dalam mode SDK lokal.
Redis agent-framework-redis; paket beta dengan API vektor eksperimental Tersedia Vektor padat pada record HASH atau JSON Memerlukan Redis 8.0.3+ dengan Pencarian; Catatan JSON juga memerlukan RedisJSON. Kluster Redis, pencarian kata kunci, dan pencarian hibrid tidak didukung.
SQL Server agent-framework-sql-server; paket alfa Tersedia Vektor padat eksak dengan filter portabel Memerlukan Python 3.10–3.14 dan SQL Server 2025 atau database Azure SQL dengan dukungan vektor. Indeks aproksimasi, pencarian kata kunci dan hibrida, vektorisasi sisi server, dan migrasi skema tidak didukung.

Instal paket konektor prarilis untuk database yang Anda gunakan:

pip install agent-framework-azure-ai-search --pre
pip install agent-framework-azure-cosmos --pre
pip install agent-framework-azure-documentdb --pre
pip install agent-framework-duckdb --pre
pip install agent-framework-mongodb --pre
pip install agent-framework-oracle --pre
pip install agent-framework-postgres --pre
pip install agent-framework-qdrant --pre
pip install agent-framework-redis --pre
pip install agent-framework-sql-server --pre

Pada Python 3.10 hingga 3.14, agent-framework-postgres menginstal distribusi biner Psycopg. Pada Python 3.15 atau yang lebih baru, menggunakan Psycopg murni Python karena roda biner yang kompatibel tidak diterbitkan, sehingga host harus menyediakan instalasi sistemlibpq.

Setiap konektor mengimplementasikan model umum, koleksi, CRUD, filter, dan kontrak pencarian. Kemampuan dan pembatasan khusus database masih berlaku. Untuk contoh lengkap, lihat sampel Pencarian Azure AI, DuckDB, operasi vektor MongoDB, RAG agen MongoDB, Oracle AI Database, Postgres, Qdrant, Redis, dan SQL Server.

implementasi yang hanya menggunakan Kernel Semantik

Aplikasi dapat terus menggunakan penyimpanan vektor Python Kernel Semantik secara langsung. Implementasi ini menggunakan kontrak penyimpanan vektor Kernel Semantik terpisah daripada kontrak Agent Framework asli. Implementasi berikut saat ini tidak memiliki konektor Agent Framework asli:

Implementation Availability Menggunakan SDK database yang didukung secara resmi Pemelihara atau penyedia
Azure Cosmos DB untuk MongoDB vCore Available Yes proyek Microsoft Kernel Semantik
Chroma Available Yes proyek Microsoft Kernel Semantik
Elasticsearch Planned Tidak teraplikasi Tidak teraplikasi
Faiss Available Yes proyek Microsoft Kernel Semantik
Neon Serverless Postgres Menggunakan implementasi Postgres Yes proyek Microsoft Kernel Semantik
Pinecone Available Yes proyek Microsoft Kernel Semantik
SQLite Planned Tidak teraplikasi proyek Microsoft Kernel Semantik
Weaviate Available Yes proyek Microsoft Kernel Semantik

Important

Implementasi penyimpanan vektor disediakan oleh berbagai pengelola. Evaluasi kualitas, lisensi, kebijakan dukungan, dan kompatibilitas versi setiap implementasi sebelum Anda menggunakannya.

Menggunakan implementasi khusus Kernel Semantik

  1. Instal semantic-kernel dan dependensi yang diperlukan untuk implementasi yang Anda pilih.
  2. Tentukan model dengan @vectorstoremodel dekorator dan identifikasi bidang kunci, data, dan vektornya.
  3. Buat koleksi khusus implementasi untuk model tersebut.
  4. Pastikan koleksi tersebut ada, lalu upsert record.
  5. Gunakan API pencarian koleksi untuk mengambil rekaman untuk aplikasi Anda.

Untuk penyiapan implementasi dan contoh lengkap, lihat Kernel Semantik Vector Stores.

Dukungan penyimpanan vektor Go

Integrasi penyimpanan vektor belum tersedia di Agent Framework for Go. Lihat repositori Agent Framework Go untuk status terbaru.

Langkah berikutnya

Menambahkan RAG ke agen

  • Terakhir diperbarui pada