Интеграция хранилища векторов

Векторные хранилища хранят данные и векторные внедрения вместе, чтобы приложения могли находить записи по семантическому подобию. В приложениях Agent Framework можно использовать векторные хранилища для получения опорных данных для Retrieval Augmented Generation (RAG) или для хранения сведений, к которым агент сможет обратиться позже.

Абстракции векторного хранилища предоставляют общие операции для коллекций и записей, сохраняя логику приложения отдельно от конкретной реализации векторного хранилища. Например, можно начать с локальной реализации и перейти на управляемую службу с минимальными изменениями.

Как работают интеграции хранилища векторов

Типичный рабочий процесс хранилища векторов включает следующие действия:

Определите модель данных, которая определяет ключ записи, поля данных и векторные поля.
Настройте генератор внедрения, если хранилище векторов не создает внедрения.
Подключитесь к хранилищу векторов и выберите или создайте коллекцию.
Создайте эмбеддинги и обновите или вставьте записи в коллекцию.
Выполните поиск коллекции с текстом или вектором в зависимости от возможностей реализации.
Передайте агенту релевантные результаты поиска в качестве контекста или предоставьте поиск как инструмент агента.

поддержка хранилища векторов .NET

Agent Framework использует автономные абстракции экосистемы ИИ .NET:

Microsoft.Extensions.VectorData предоставляет общие API-интерфейсы хранилища векторов, коллекции, записи и поиска.
Microsoft.Extensions.AI предоставляет абстракции, например IEmbeddingGenerator для создания внедрения независимо от конкретного поставщика модели.

Если компонент Agent Framework принимает векторное хранилище, можно предоставить совместимую Microsoft.Extensions.VectorData реализацию. Каждая реализация базы данных распределяется отдельно от пакета абстракций.

Основные абстракции

Абстракция	Purpose
`VectorStore`	Предоставляет операции между коллекциями и создает типизированные экземпляры коллекции.
`VectorStoreCollection<TKey, TRecord>`	Создает или удаляет коллекцию, а также создает или обновляет, извлекает либо удаляет ее записи.
`IVectorSearchable<TRecord>`	Выполняет поиск записей по вектору или по тексту, когда доступен генератор внедрения или возможность внедрения на стороне базы данных.

Доступные реализации хранилища векторов

В следующих реализациях используются общие абстракции хранилища векторов .NET. Ознакомьтесь с документацией по каждой реализации для версий пакетов, поддерживаемых типов данных и ограничений, относящихся к службе.

Implementation	Availability	Использует официально поддерживаемый пакет SDK для базы данных	Обслуживание или поставщик
Поиск с использованием ИИ Azure	В наличии	Yes	Microsoft
Azure Cosmos DB для MongoDB vCore	В наличии	Yes	Microsoft
Azure Cosmos DB для работы с NoSQL	В наличии	Yes	Microsoft
Couchbase	В наличии	Yes	Couchbase
Elasticsearch	В наличии	Yes	Elastic
Chroma	Запланировано	Неприменимо	Неприменимо
В памяти	В наличии	Неприменимо	Microsoft
Милвус	Запланировано	Неприменимо	Неприменимо
MongoDB	В наличии	Yes	Microsoft
Неон и бессерверный PostgreSQL	Используйте реализацию Postgres	Yes	Microsoft
Oracle	В наличии	Yes	Oracle
Шишка	В наличии	Нет	Microsoft
Postgres	В наличии	Yes	Microsoft
Qdrant	В наличии	Yes	Microsoft
Редис	В наличии	Yes	Microsoft
SQL Server	В наличии	Yes	Microsoft
SQLite	В наличии	Yes	Microsoft
Переменная в памяти	Устарело; используйте реализацию в памяти	Неприменимо	Microsoft
Weaviate	В наличии	Yes	Microsoft

Important

Реализации хранилища векторов приходят из нескольких хранителей. Перед использованием каждой реализации оцените качество, лицензирование, политику поддержки и совместимость версий. Некоторые реализации используют пакеты SDK базы данных, которые поставщик базы данных официально не поддерживает.

Get started

Добавление Microsoft.Extensions.VectorData.Abstractions пакет и пакет для выбранной реализации хранилища векторов.
Определите тип записи и определите его ключ, данные и векторные свойства.
Настройте IEmbeddingGenerator, если для вашей реализации требуются эмбеддинги, сгенерированные приложением.
Создайте реализацию VectorStore, а затем получите типизированный объект VectorStoreCollection<TKey, TRecord>.
Убедитесь, что коллекция существует, обновите или вставьте записи и вызовите SearchAsync с текстом или вектором.

Полные сведения о моделях данных, приеме, внедрении и поиске см. в статьях "Векторные базы данных" для .NET приложений ИИ.

поддержка хранилища векторов Python

Agent Framework предоставляет экспериментальные встроенные контракты Python для моделей хранилища векторов, операций с коллекциями, фабрик хранилищ, векторного и гибридного поиска по ключевым словам, а также инструментов поиска агентов. Контракты являются частью agent-framework-core и не требуют Pydantic, NumPy, pandas или Semantic Kernel.

Предупреждение

Собственные API Python для векторного хранилища являются экспериментальными. Ограниченные критические изменения могут возникать до того, как они становятся стабильными.

Основные абстракции

Абстракция	Purpose
`VectorStoreField` и `VectorStoreCollectionDefinition`.	Описание ключевых, данных и векторных полей, включая имена хранилища, индексы, измерения и функции расстояния.
`@vectorstoremodel` и `register_vectorstoremodel()`.	Регистрируйте классы данных, модели Pydantic, структуры msgspec, обычные классы или типы моделей, принадлежащие внешним владельцам.
`BaseVectorCollection` и `SupportsVectorUpsert`.	Определяет пакетные операции upsert, получения и удаления, жизненный цикл коллекции, преобразование записей и необязательную генерацию эмбеддингов.
`BaseVectorStore`	Определяет хранилище, содержащее список коллекций и создающее типизированные клиенты коллекций.
`BaseVectorSearch` и `SupportsVectorSearch`.	Определите векторный и гибридный поиск, разбиение по страницам, фильтры, пороговые значения оценки и результаты поиска.
`Filter`, `FilterGroup` и `Param`	Определите переносимые, доступные только для данных фильтры, включая параметры фильтра, предоставленные моделью, для средств поиска.
`InMemoryStore` и `InMemoryCollection`.	Обеспечить операции CRUD в пределах процесса и линейный поиск для разработки и тестирования.
`GenerateVectors`	Определяет, будут ли при операциях upsert создаваться все, ни одно или только выбранные векторные поля.
`create_vector_search_tool()`, `create_upsert_tool()`, `create_get_tool()` и `create_delete_tool()`	Предоставить векторный поиск и CRUD-операции для коллекций как инструменты функций Agent Framework.
`VectorStoreHistoryProvider`	Хранит историю бесед с ограниченной областью действия в коллекции, принадлежащей поставщику, с возможностью необязательного уплотнения и поиска по всей истории.
`VectorCollectionContextProvider`	Добавляет настраиваемые средства для операций CRUD и поиска для коллекции, принадлежащей вызывающей стороне.

Следующий пример определяет записи векторного хранилища путем аннотирования их ключевых, данных и векторных полей:

# 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.

Agent Framework включает реализацию в памяти для разработки и тестирования. Он хранит записи в текущем процессе и использует линейный поиск, поэтому для промышленных нагрузок используйте коннектор базы данных.

Передавайте параметры эмбеддинга для каждой операции

Передайте embeddings_options в upsert(), чтобы применить параметры провайдера ко всем создаваемым векторным полям. Используйте embeddings_options_by_field, если для разных логических векторных полей требуются разные параметры. Эти два аргумента являются взаимоисключающими.

Для внедрения запросов передайте embeddings_options в search() или create_vector_search_tool(). Agent Framework предоставляет объявленные измерения выбранного поля вектора и отклоняет конфликтующее 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}."
    ),
)

Использование векторной коллекции с агентом

Используйте 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, когда поставщик должен управлять схемой коллекции и автоматически загружать и сохранять сообщения Agent Framework. Идентификаторы приложения, арендатора, агента, источника и сеанса предотвращают случайные совпадения, однако ваше приложение всё равно должно контролировать доступ и использовать учетные данные хранилища или пространства имён с надлежащей областью действия.

При настройке эмбеддингов укажите явное имя коллекции и размерность эмбеддингов. Сжатие уменьшает только объём истории, загружаемой в контекст модели. Если включить средство поиска, поиск будет выполняться по всей расшифровке в пределах выбранной области.

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:

Реализации нативного агентного фреймворка

В следующих реализациях используются встроенные контракты Agent Framework. Некоторые также доступны как отдельные соединители Semantic Kernel, но два семейства соединителей не взаимозаменяемы.

Implementation	Пакет Agent Framework и его жизненный цикл	Отдельный коннектор Semantic Kernel	Режимы поиска	Основные ограничения
В памяти	`agent-framework-core`; выпущенный пакет с экспериментальными API векторов	Доступно	Плотный вектор с переносимыми фильтрами	Локальная линейная проверка процесса для разработки и тестирования, а не рабочей базы данных.
Поиск с использованием ИИ Azure	`agent-framework-azure-ai-search`; бета-пакет с экспериментальными API векторов	Доступно	Плотный вектор и гибридный поиск по ключевым словам	Одно поле плотного вектора верхнего уровня для каждого запроса. Некоторые пороговые значения, гибридные элементы управления отзывом текста, строгие функции после фильтрации и разрешения требуют поддержки пакета SDK или API для предварительной версии.`allow_preview=True`
Azure Cosmos DB для NoSQL	`agent-framework-azure-cosmos`; бета-пакет с экспериментальными API векторов	Доступно	Плотный вектор с переносимыми фильтрами	Ключи должны быть строками, сохраняемыми как `id`, а контейнеры используют ключ раздела `/id`. Ключевое слово и гибридный поиск не поддерживаются, а поиск Euclidean не поддерживает пороговые значения оценки.
Azure DocumentDB	`agent-framework-azure-documentdb`; альфа-пакет	Недоступно	Плотный вектор с переносимыми фильтрами метаданных	Ключи должны быть строками или целыми числами. Созданные объектные идентификаторы, гибридный и полнотекстовый поиск и вложенные пути фильтрации не поддерживаются.
DuckDB	`agent-framework-duckdb`; альфа-пакет	Недоступно	Точный плотный вектор с переносимыми фильтрами	Требуется Python 3.10+ и DuckDB 1.4.1–1.5.x. Приблизительные индексы, ключевые слова и гибридный поиск, полнотекстовый поиск и векторизация на стороне сервера не поддерживаются. Локальные файлы разрешают одновременно только один процесс записи.
MongoDB	`agent-framework-mongodb`; альфа-пакет	Доступно	Приблизительный или точный плотный вектор с переносимыми фильтрами	Требуется PyMongo 4.13.2+ и развертывание с помощью векторного поиска MongoDB. Ключевые слова и гибридный поиск, вложенные пути фильтрации, внедрение на стороне поставщика и автоматическая миграция схем не поддерживаются. Модели, которые объявляют `is_full_text_indexed`, отклоняются, а новые записи становятся доступными для поиска асинхронно.
Oracle AI Database	`agent-framework-oracle`; альфа-пакет	Доступно	Плотный вектор с переносимыми фильтрами	Требуется Oracle AI Database 26ai с `COMPATIBLE`, установленным на 23.4.0 или выше, и `python-oracledb` версии 2.2.x или 3.x. Управление индексами, ключевое слово и гибридный поиск, JSON и вложенные фильтры, векторизация на стороне сервера и миграция схем не поддерживаются.
PostgreSQL с pgvector	`agent-framework-postgres`; альфа-пакет	Доступно	Точный плотный вектор, HNSW и IVFlat	Требуется PostgreSQL 13+, pgvector 0.8.0+, существующая схема и включенное расширение. Ключевое слово и гибридный поиск не поддерживаются.
Qdrant	`agent-framework-qdrant`; альфа-пакет	Доступно	Плотный вектор с переносимыми фильтрами на стороне сервера	Для режима сервера требуется Qdrant 1.16.2+. Ключи должны быть 64-разрядными целыми числами без знака или UUID. Ключевые слова и гибридный поиск не поддерживаются, а фильтры недоступны в локальном режиме ПАКЕТА SDK.
Redis	`agent-framework-redis`; бета-пакет с экспериментальными API векторов	Доступно	Плотный вектор над записями HASH или JSON	Требуется Redis 8.0.3+ с поиском; Для записей JSON также требуется RedisJSON. Кластер Redis, поиск ключевых слов и гибридный поиск не поддерживаются.
SQL Server	`agent-framework-sql-server`; альфа-пакет	Доступно	Точный плотный вектор с переносимыми фильтрами	Требуется Python 3.10–3.14 и SQL Server 2025 или векторную базу данных Azure SQL. Приблизительные индексы, ключевые слова и гибридный поиск, векторизация на стороне сервера и миграция схем не поддерживаются.

Установите пакет соединителя предварительной версии для используемой базы данных:

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

В Python 3.10–3.14 agent-framework-postgres устанавливает бинарный дистрибутив Psycopg. В Python 3.15 и более поздних версиях используется Psycopg на чистом Python, поскольку совместимые бинарные пакеты wheel не выпускаются, поэтому на хосте должна быть установлена системная версия libpq.

Каждый соединитель реализует общую модель, коллекцию, CRUD, фильтр и контракты поиска. Возможности и ограничения, связанные с базой данных, по-прежнему применяются. Полные примеры см. в образцах Поиск с использованием ИИ Azure, DuckDB, MongoDB vector operations, MongoDB agent RAG, Oracle AI Database, Postgres, Qdrant, Redis и SQL Server.

реализации только на Semantic Kernel

Приложения могут продолжать напрямую использовать векторные хранилища Python из Semantic Kernel. Эти реализации используют отдельные контракты хранилища векторов Semantic Kernel, а не собственные контракты agent Framework. В настоящее время у следующих реализаций нет собственного соединителя Agent Framework:

Implementation	Availability	Использует официально поддерживаемый пакет SDK для базы данных	Обслуживание или поставщик
Azure Cosmos DB для MongoDB vCore	В наличии	Yes	проект Microsoft Semantic Kernel
Цветность	В наличии	Yes	проект Microsoft Semantic Kernel
Elasticsearch	Запланировано	Неприменимо	Неприменимо
Фейсс	В наличии	Yes	проект Microsoft Semantic Kernel
Неон и бессерверный PostgreSQL	Используйте реализацию Postgres	Yes	проект Microsoft Semantic Kernel
Шишка	В наличии	Yes	проект Microsoft Semantic Kernel
SQLite	Запланировано	Неприменимо	проект Microsoft Semantic Kernel
Weaviate	В наличии	Yes	проект Microsoft Semantic Kernel

Important

Использование реализации только Semantic Kernel

Установите semantic-kernel и зависимости, необходимые для выбранной вами реализации.
Определите модель с декоратором @vectorstoremodel и определите его ключ, данные и векторные поля.
Создайте коллекцию, специфичную для реализации, для этой модели.
Убедитесь, что коллекция существует, а затем обновите или вставьте записи.
Используйте API поиска коллекции для получения записей для приложения.

Инструкции по настройке реализации и полные примеры см. в разделе Векторные хранилища Semantic Kernel.

Поддержка хранилища векторов Go

Интеграция векторного хранилища пока недоступна в Agent Framework для Go. Сведения о последнем состоянии см. в репозитории Agent Framework Go .

Дальнейшие действия

Добавьте RAG в агента

Обратная связь

Были ли сведения на этой странице полезными?

Последнее обновление: 2026-10-12

Интеграция хранилища векторов

Как работают интеграции хранилища векторов

поддержка хранилища векторов .NET

Основные абстракции

Доступные реализации хранилища векторов

Get started

поддержка хранилища векторов Python

Основные абстракции

Передавайте параметры эмбеддинга для каждой операции

Использование векторной коллекции с агентом

Хранение журнала бесед в векторном хранилище

Реализации нативного агентного фреймворка

реализации только на Semantic Kernel

Использование реализации только Semantic Kernel

Поддержка хранилища векторов Go

Связанные сценарии Agent Framework

Дальнейшие действия

Обратная связь

Дополнительные ресурсы