Vektortároló-integrációk

A vektortárolók együtt tárolják az adatokat és azok vektorbeágyazását, hogy az alkalmazások szemantikai hasonlóság alapján találhassák meg a rekordokat. Az Agent Framework-alkalmazásokban vektortárolók használatával lekérheti a bővített generálás (RAG) lekéréséhez szükséges alapadatokat, vagy tárolhatja azokat az információkat, amelyeket az ügynök később visszahívhat.

A vektortároló absztrakciói gyakori műveleteket biztosítanak a gyűjteményekhez és rekordokhoz, így az alkalmazáslogika elkülönül az adott vektortároló implementációjától. Elindíthat például egy helyi implementációt, és minimális módosításokkal átválthat egy felügyelt szolgáltatásra.

A vektortároló-integrációk működése

Egy tipikus vektortár-munkafolyamat a következő lépéseket tartalmazza:

1. Definiáljon egy adatmodellt, amely azonosítja a rekordkulcsot, az adatmezőket és a vektormezőket.
2. Ha a vektortároló nem hoz létre beágyazást, konfiguráljon beágyazási generátort.
3. Csatlakozzon egy vektortárolóhoz, és válasszon vagy hozzon létre egy gyűjteményt.
4. Beágyazásokat és rekordokat hozhat létre a gyűjteménybe.
5. A gyűjteményben a megvalósítás képességeitől függően szöveggel vagy vektorral kereshet.
6. Adjon át releváns keresési eredményeket egy ügynöknek kontextusként, vagy tegye közzé a keresést ügynökeszközként.

.NET vektortároló támogatása

Az Agent Framework a .NET AI-ökoszisztéma önálló absztrakcióit használja:

• Microsoft.Extensions.VectorData általános vektortárat, gyűjteményt, rekordot és keresési API-kat biztosít.
• Microsoft.Extensions.AI olyan absztrakciókat biztosít, mint például IEmbeddingGenerator beágyazások létrehozása egy adott modellszolgáltatótól függetlenül.

Ha az ügynökkeretrendszer valamely összetevője elfogad egy vektortárolót, megadhat egy kompatibilis Microsoft.Extensions.VectorData megvalósítást. Minden adatbázis-implementáció külön van elosztva az absztrakciós csomagtól.

Alapvető absztrakciók

Absztrakció	Alkalmazás célja
VectorStore	Műveleteket biztosít a gyűjtemények között, és beírt gyűjteménypéldányokat hoz létre.
VectorStoreCollection<TKey, TRecord>	Létrehoz vagy töröl egy gyűjteményt, és létrehozza vagy frissíti, lekéri, illetve törli annak rekordjait.
IVectorSearchable<TRecord>	Vektor vagy szöveg alapján keres rekordokat, ha rendelkezésre áll beágyazási generátor vagy adatbázisoldali beágyazási képesség.

Elérhető vektortároló-implementációk

Az alábbi implementációk a .NET vektortároló absztrakcióit használják. Tekintse át az egyes implementációk dokumentációját a csomagverziókról, a támogatott adattípusokról és a szolgáltatásspecifikus korlátozásokról.

Megvalósítás	Availability	Hivatalosan támogatott adatbázis-SDK-t használ	Karbantartó vagy szállító
Azure AI Keresés	Elérhető	Yes	Microsoft
Azure Cosmos DB MongoDB-hez készült vCore	Elérhető	Yes	Microsoft
Azure Cosmos DB NoSQL-hez	Elérhető	Yes	Microsoft
Couchbase	Elérhető	Yes	Couchbase
Elasticsearch	Elérhető	Yes	Elastic
Chroma	Planned	Nem alkalmazható	Nem alkalmazható
Memóriában	Elérhető	Nem alkalmazható	Microsoft
Milvus	Planned	Nem alkalmazható	Nem alkalmazható
MongoDB	Elérhető	Yes	Microsoft
Neon szerver nélküli Postgres	A Postgres implementáció használata	Yes	Microsoft
Oracle	Elérhető	Yes	Oracle
Pinecone	Elérhető	No	Microsoft
Postgres	Elérhető	Yes	Microsoft
Qdrant	Elérhető	Yes	Microsoft
Redis	Elérhető	Yes	Microsoft
SQL Server	Elérhető	Yes	Microsoft
SQLite	Elérhető	Yes	Microsoft
Memóriabeli változékonyság	Elavult; a memóriabeli implementáció használata	Nem alkalmazható	Microsoft
Weaviate	Elérhető	Yes	Microsoft

Important

A vektortároló implementációi több karbantartótól származnak. Használat előtt értékelje ki az egyes implementációk minőségét, licencelési, támogatási szabályzatát és verziókompatibilitását. Egyes implementációk olyan adatbázis-SDK-kat használnak, amelyeket az adatbázis-szolgáltató hivatalosan nem támogat.

Első lépések

1. Adja hozzá a Microsoft.Extensions.VectorData.Abstractions csomag és a választott vektortároló-implementáció csomagja.
2. Definiáljon egy rekordtípust, és azonosítsa annak kulcsát, adatait és vektortulajdonságait.
3. Konfiguráljon egy IEmbeddingGenerator elemet, ha a megvalósítása alkalmazás által generált beágyazásokat igényel.
4. Hozza létre a megvalósítás VectorStore elemét, majd kérjen le egy típusos VectorStoreCollection<TKey, TRecord> példányt.
5. Győződjön meg arról, hogy a gyűjtemény létezik, szúrja be vagy frissítse a rekordokat, és hívja meg a SearchAsync elemet szöveggel vagy vektorral.

Az adatmodellek, a betöltések, a beágyazások és a keresés teljes bemutatása: Vector-adatbázisok .NET AI-alkalmazásokhoz.

Python vektortároló támogatása

Az Agent Framework kísérleti, natív Python szerződéseket biztosít vektortár-modellekhez, gyűjteményműveletekhez, tárológyárakhoz, vektor- és kulcsszó-hibrid kereséshez, valamint ügynökkeresési eszközökhöz. A szerződések a agent-framework-core részét képezik, és nem igénylik sem a Pydanticet, sem a NumPy-t, sem a pandast, sem a Szemantikus kernelt.

Warning

A natív Python vektortároló API-k kísérleti jellegűek. A korlátozott kompatibilitástörő változások a stabil állapotba kerülés előtt előfordulhatnak.

Alapvető absztrakciók

Absztrakció	Alkalmazás célja
VectorStoreField és VectorStoreCollectionDefinition	Ismertesse a kulcs-, adat- és vektormezőket, beleértve a tárolóneveket, az indexeket, a dimenziókat és a távolságfüggvényeket.
@vectorstoremodel és register_vectorstoremodel()	Regisztráljon adatosztályokat, Pydantic-modelleket, msgspec-szerkezeteket, egyszerű osztályokat vagy külső tulajdonú modelltípusokat.
BaseVectorCollection és SupportsVectorUpsert	Határozza meg a batch upsert, a get, a delete, a gyűjtemény életciklusa, a rekordkonverzió és az opcionális beágyazásgenerálás fogalmát.
BaseVectorStore	Olyan tárolót definiál, amely felsorolja a gyűjteményeket, és beírt gyűjtemény-ügyfeleket hoz létre.
BaseVectorSearch és SupportsVectorSearch	Vektor- és kulcsszó-hibrid keresés, lapozás, szűrők, pontszámküszöbök és keresési eredmények meghatározása.
Filter, FilterGroupés Param	Definiáljon hordozható, csak adatokat tartalmazó szűrőket, beleértve a modell által biztosított szűrőparamétereket a keresőeszközökhöz.
InMemoryStore és InMemoryCollection	Folyamatalapú CRUD- és lineáris vizsgálatkeresést biztosít a fejlesztéshez és a tesztekhez.
GenerateVectors	Azt szabályozza, hogy az upsert műveletek az összes, egyiket sem vagy a kiválasztott vektormezőket generálják-e.
create_vector_search_tool()	Bármely SupportsVectorSearch implementációt elérhetővé tesz az Agent Framework függvényeszközeként.

Az alábbi minta a vektortároló rekordokat a kulcs, az adatok és a vektormezők megjegyzésével határozza meg:

# 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

Közvetlenül szótárakhoz használható VectorStoreCollectionDefinition . Egy másik csomag által birtokolt modelltípusokhoz használjon register_vectorstoremodel() explicit definíciót, opcionális kódolót és dekódert. A tömbszerű vektorértékek tolist() használatával szerializálhatók NumPy-függőség hozzáadása nélkül.

Az Agent Framework egy memórián belüli implementációt tartalmaz a fejlesztéshez és a tesztekhez. A rekordok az aktuális folyamatban vannak tárolva, és lineáris vizsgálatot használnak, ezért adatbázis-összekötőt használnak az éles számítási feladatokhoz.

Az alábbi minta előre összeállított vektorokat tárol, és egy hordozható szűrőfával keresi őket:

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

Akkor használható Param , ha a modellnek szűrőértéket kell megadnia. A Python típusa, leírása és korlátozásai a keresőeszköz JSON-sémájának részévé válnak:

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

Natív ügynök-keretrendszer implementációi

Az alábbi implementációk a natív Agent Framework-szerződéseket használják. Mindegyik külön Szemantikus kernel összekötőként is elérhető, de a két összekötőcsalád nem cserélhető fel.

Megvalósítás	Ügynök-keretrendszer csomagja és életciklusa	Különálló Szemantikus kernel-összekötő	Keresési módok	Legfontosabb korlátozások
Memóriabeli	agent-framework-core; megjelent csomag kísérleti vektor API-kkal	Elérhető	Sűrű vektor hordozható szűrőkkel	Folyamat-helyi lineáris vizsgálat fejlesztéshez és tesztekhez, nem éles adatbázishoz.
Azure AI Keresés	agent-framework-azure-ai-search; bétacsomag kísérleti vektor API-kkal	Elérhető	Sűrű vektor és kulcsszó-hibrid	Lekérdezésenként egy legfelső szintű sűrű vektormező. Egyes küszöbértékek, hibrid szöveg-visszakeresési vezérlők, szigorú utólagos szűrési beállítások és engedélyek egy ezt támogató előzetes verziójú SDK/API-t és allow_preview=True igényelnek.
PostgreSQL és pgvector	agent-framework-postgres; alfa csomag	Elérhető	Egzakt sűrű vektor, HNSW és IVFFlat	A PostgreSQL 13+, a pgvector 0.8.0+, a meglévő séma és az engedélyezett bővítmény szükséges. A kulcsszó- és hibrid keresés nem támogatott.
Qdrant	agent-framework-qdrant; alfa csomag	Elérhető	Sűrű vektor kiszolgálóoldali hordozható szűrőkkel	A szerver mód használatához a Qdrant 1.16.2-es vagy újabb verziója szükséges. A kulcsoknak 64 bites egész számoknak vagy UUID-knek kell lenniük. A kulcsszó- és hibrid keresés nem támogatott, és a szűrők nem érhetők el helyi SDK módban.
Redis	agent-framework-redis; bétacsomag kísérleti vektor API-kkal	Elérhető	Sűrű vektor HASH- vagy JSON-rekordokon keresztül	A Redis 8.0.3+-ra van szükség a Keresés funkcióval; A JSON-rekordokhoz RedisJSON szükséges. A Redis Cluster, a kulcsszavas keresés és a hibrid keresés nem támogatott.

Telepítsen egy előzetes összekötőcsomagot a használt adatbázishoz:

pip install agent-framework-azure-ai-search --pre
pip install agent-framework-postgres --pre
pip install agent-framework-qdrant --pre
pip install agent-framework-redis --pre

Minden összekötő implementálja a közös modellt, gyűjteményt, CRUD-t, szűrőt és keresési szerződéseket. Az adatbázis-specifikus képességek és korlátozások továbbra is érvényesek. A teljes példákért tekintse meg a Azure AI Keresés, a Postgres, a Qdrant és a Redis mintákat.

csak Szemantikus kernel implementációk

Az alkalmazások továbbra is használhatják Szemantikus kernel Python vektortárolóját. Ezek a megvalósítások a natív Agent Framework-szerződések helyett a különálló Szemantikus kernel vektortároló-szerződéseket használják. Az alábbi implementációk jelenleg nem rendelkeznek natív Agent Framework-összekötővel:

Megvalósítás	Availability	Hivatalosan támogatott adatbázis-SDK-t használ	Karbantartó vagy szállító
Azure Cosmos DB MongoDB-hez készült vCore	Elérhető	Yes	Microsoft Szemantikus kernel projekt
Azure Cosmos DB NoSQL-hez	Elérhető	Yes	Microsoft Szemantikus kernel projekt
Chroma	Elérhető	Yes	Microsoft Szemantikus kernel projekt
Elasticsearch	Planned	Nem alkalmazható	Nem alkalmazható
Faiss	Elérhető	Yes	Microsoft Szemantikus kernel projekt
MongoDB	Elérhető	Yes	Microsoft Szemantikus kernel projekt
Neon szerver nélküli Postgres	A Postgres implementáció használata	Yes	Microsoft Szemantikus kernel projekt
Oracle	Elérhető	Yes	Oracle
Pinecone	Elérhető	Yes	Microsoft Szemantikus kernel projekt
SQL Server	Elérhető	pyodbc	Microsoft Szemantikus kernel projekt
SQLite	Planned	Nem alkalmazható	Microsoft Szemantikus kernel projekt
Weaviate	Elérhető	Yes	Microsoft Szemantikus kernel projekt

Important

A vektortároló implementációi több karbantartótól származnak. Használat előtt értékelje ki az egyes implementációk minőségét, licencelési, támogatási szabályzatát és verziókompatibilitását.

Kizárólag Szemantikus kernelt használó implementáció használata

1. Telepítse semantic-kernel és a választott implementációhoz szükséges függőségeket.
2. Definiáljon egy modellt a @vectorstoremodel dekoratőrrel, és azonosítsa annak kulcsát, adatait és vektormezőit.
3. Hozzon létre egy implementációspecifikus gyűjteményt a modellhez.
4. Győződjön meg arról, hogy a gyűjtemény létezik, majd adja hozzá a rekordokat.
5. A gyűjtemény keresési API-jaival lekérheti az alkalmazás rekordjait.

A megvalósítás beállítását és a példákat a Szemantikus kernel Vektortárolók című témakörben talál.

Go vektortár támogatása

A Vektortár integrációja még nem érhető el a Go-hoz készült Agent Frameworkben. A legújabb állapotot az Agent Framework Go-adattárában tekinthet meg.

Kapcsolódó ügynök-keretrendszer-forgatókönyvek

• RAG hozzáadása egy ügynökhöz.
• Adjon hozzá szemantikai csevegési előzményeket.
• Válasszon egy környezetszolgáltatói integrációt.

Következő lépések

RAG hozzáadása egy ügynökhöz