向量儲存整合

.NET 向量儲存支援

代理框架採用 .NET AI 生態系統的獨立抽象：

• Microsoft.Extensions.VectorData 提供常見的向量儲存、收集、記錄及搜尋 API。
• Microsoft.Extensions.AI 提供抽象，例如 IEmbeddingGenerator，可獨立於特定模型提供者產生嵌入。

當 Agent Framework 元件接受向量儲存時，你可以提供相容 Microsoft.Extensions.VectorData 的實作。 每個資料庫實作皆與抽象套件分開分發。

核心抽象概念

可用的向量儲存實作

以下實作使用常見的 .NET 向量儲存抽象。 請檢視每個實作的文件，了解套件版本、支援的資料型態及服務特定限制。

開始

1. 加入 Microsoft.Extensions.VectorData.Abstractions 套件，以及您所選向量存放區實作的套件。
2. 定義一個記錄類型，並識別其鍵、資料及向量屬性。
3. 如果您的實作需要由應用程式產生的嵌入，請設定 IEmbeddingGenerator。
4. 建立實作的 VectorStore，然後取得一個具型別的 VectorStoreCollection<TKey, TRecord>。
5. 確保該集合存在，更新記錄，並用文字或向量呼叫 SearchAsync 。

欲了解資料模型、資料擷取、嵌入與搜尋的完整介紹，請參閱 .NET AI 應用程式的向量資料庫。

Python 向量儲存支援

Agent Framework 提供實驗性的原生 Python 合約，用於向量儲存模型、收集操作、儲存工廠、向量與關鍵字混合搜尋，以及代理搜尋工具。 這些契約是 agent-framework-core 的一部分，且不需要 Pydantic、NumPy、pandas 或 語意核心。

核心抽象概念

以下範例透過為向量儲存體記錄的鍵、資料和向量欄位加上註解來定義這些記錄：

# 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

直接將 VectorStoreCollectionDefinition 用於字典。 對於由另一個套件擁有的模型型別，請使用 register_vectorstoremodel()，並搭配明確的定義以及可選的編碼器和解碼器。 類陣列的向量值可透過 tolist() 進行序列化，且無須新增 NumPy 相依性。

代理框架包含供開發與測試使用的記憶體內實作。 它會將記錄儲存在目前的程序中，並使用線性掃描，因此在正式環境中請使用資料庫連接器。

為每個操作傳遞嵌入選項

將 embeddings_options 傳遞給 upsert()，以將提供者選項套用至每個產生的向量欄位。 當不同邏輯向量場需要不同選項時才會使用 embeddings_options_by_field 。 這兩個論點是互相排斥的。

對於查詢嵌入，請將 embeddings_options 傳遞至 search() 或 create_vector_search_tool()。 代理框架會提供所選向量欄位已宣告的維度，並在呼叫嵌入提供者之前拒絕衝突的 dimensions 值。

Upsert 嵌入選項需要生成的向量，且不能與 generate_vectors=False 一起使用。 搜尋嵌入選項需要本地嵌入產生器，當你提供預先計算好的查詢向量時，這些選項會被忽略。

以下範例儲存預先計算好的向量，並以可攜式濾波樹進行搜尋：

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

當模型應該提供濾波器值時使用 Param 。 其 Python 型別、描述與限制成為搜尋工具 JSON 架構的一部分：

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

搭配 Agent 使用向量集合

當你的應用程式擁有收藏與資料模型時使用 VectorCollectionContextProvider 。 供應器會新增產生的 CRUD 和搜尋工具。 Upsert 和 Delete 預設需要核准，而 get 和 search 則不需要。

傳遞 scope_filter 以將記錄分組，供產生的工具使用，但不要將篩選條件視為授權邊界或後端的原子性保證。 透過 additional_search_tools 傳遞的搜尋工具會保留各自的篩選條件，因此在分享集合時，請為每個自訂工具套用對應的篩選條件。

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:

在向量儲存中儲存對話歷史

當提供者擁有集合架構並自動載入與儲存代理框架訊息時，請使用 VectorStoreHistoryProvider 。 其應用程式、租戶、代理、來源及會話識別碼可防止意外重疊，但你的應用程式仍必須授權存取權限，並使用適當範圍的儲存憑證或命名空間。

設定嵌入時，請提供明確的集合名稱和嵌入維度。 精簡僅會減少載入模型上下文中的歷史記錄。 如果你啟用搜尋工具，系統會搜尋整個指定範圍的逐字稿。

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:

原生代理框架實作

以下實作使用原生的代理框架合約。 有些連接器也可作為獨立的 語意核心 連接器提供，但這兩個連接器系列無法互換。

為你使用的資料庫安裝預發布的連接器套件：

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-postgres --pre
pip install agent-framework-qdrant --pre
pip install agent-framework-redis --pre
pip install agent-framework-sql-server --pre

在 Python 3.10 至 3.14 版本中，agent-framework-postgres安裝 Psycopg 的二進位發行版。 在 Python 3.15 或更新版本中，使用純 Python Psycopg，因為相容的二進位輪子未公開，主機必須提供系統libpq安裝。

每個連接器實作共通模型、集合、CRUD、篩選與搜尋合約。 資料庫專屬的能力與限制仍然適用。 完整範例請參考 Azure AI 搜尋服務、DuckDB、MongoDB 向量操作、MongoDB agent RAG、Postgres、Qdrant、Redis 及 SQL Server 範例。

僅使用 語意核心 的實作

應用程式仍可直接使用 語意核心 的 Python 向量儲存庫。 這些實作使用獨立的 語意核心 向量儲存合約，而非原生的 Agent Framework 合約。 以下實作目前沒有原生的 Agent Framework 連接器：

使用僅採用 語意核心 的實作

1. 安裝 semantic-kernel 以及你所選的實作所需的相依套件。
2. 用 @vectorstoremodel 裝飾器定義模型，並識別其鍵、資料和向量場。
3. 為該模型建立一個實作專屬的集合。
4. 請先確認該集合存在，然後對記錄執行插入或更新操作。
5. 使用收藏的搜尋 API 來取得申請所需的紀錄。

關於實作設定與完整範例，請參見 語意核心 向量儲存庫。

Go 向量儲存支援

Agent Framework for Go 尚未提供向量商店整合功能。 最新狀態請參閱 Agent Framework Go 倉庫 。