벡터 저장소 통합

벡터 저장소는 애플리케이션이 의미 체계 유사성을 통해 레코드를 찾을 수 있도록 데이터와 해당 벡터 포함을 함께 유지합니다. 에이전트 프레임워크 애플리케이션에서 벡터 저장소를 사용하여 RAG(검색 보강 세대)에 대한 접지 데이터를 검색하거나 에이전트가 나중에 회수할 수 있는 정보를 저장할 수 있습니다.

벡터 저장소 추상화는 컬렉션 및 레코드에 대한 일반적인 작업을 제공하여 애플리케이션 논리를 특정 벡터 저장소 구현과 분리된 상태로 유지합니다. 예를 들어 로컬 구현으로 시작하고 최소한의 변경으로 관리되는 서비스로 전환할 수 있습니다.

벡터 저장소 통합 작동 방식

일반적인 벡터 저장소 워크플로에는 다음 단계가 포함됩니다.

레코드 키, 데이터 필드 및 벡터 필드를 식별하는 데이터 모델을 정의합니다.
벡터 저장소가 포함을 생성하지 않는 경우 포함 생성기를 구성합니다.
벡터 저장소에 연결하고 컬렉션을 선택하거나 만듭니다.
임베딩을 생성하고 레코드를 컬렉션에 업서트합니다.
구현의 기능에 따라 텍스트 또는 벡터를 사용하여 컬렉션을 검색합니다.
관련 검색 결과를 컨텍스트로 에이전트에 전달하거나 에이전트 도구로 검색을 노출합니다.

.NET 벡터 저장소 지원

에이전트 프레임워크는 .NET AI 에코시스템의 독립 실행형 추상화에 사용합니다.

Microsoft.Extensions.VectorData 는 공통 벡터 저장소, 컬렉션, 레코드 및 검색 API를 제공합니다.
Microsoft.Extensions.AI는 특정 모델 제공업체에 종속되지 않고 임베딩을 생성하기 위한 IEmbeddingGenerator와 같은 추상화를 제공합니다.

에이전트 프레임워크 구성 요소가 벡터 저장소를 허용하는 경우 호환되는 Microsoft.Extensions.VectorData 구현을 제공할 수 있습니다. 각 데이터베이스 구현은 추상화 패키지와 별도로 배포됩니다.

핵심 추상화

추상화	Purpose
`VectorStore`	컬렉션에서 작업을 제공하고 형식화된 컬렉션 인스턴스를 만듭니다.
`VectorStoreCollection<TKey, TRecord>`	컬렉션을 생성하거나 삭제하고 해당 레코드를 삽입 또는 업데이트, 조회 또는 삭제합니다.
`IVectorSearchable<TRecord>`	포함 생성기 또는 데이터베이스 쪽 포함 기능을 사용할 수 있는 경우 벡터 또는 텍스트로 레코드를 검색합니다.

사용 가능한 벡터 저장소 구현

다음 구현에서는 일반적인 .NET 벡터 저장소 추상화 사용 합니다. 패키지 버전, 지원되는 데이터 형식 및 서비스별 제한 사항에 대한 각 구현의 설명서를 검토합니다.

Implementation	Availability	공식적으로 지원되는 데이터베이스 SDK 사용	유지 관리자 또는 공급업체
Azure AI 검색	사용할 수 있음	예	마이크로소프트
MongoDB vCore에 대한 Azure Cosmos DB	사용할 수 있음	예	마이크로소프트
NoSQL용 Azure Cosmos DB	사용할 수 있음	예	마이크로소프트
Couchbase	사용할 수 있음	예	Couchbase
Elasticsearch	사용할 수 있음	예	Elastic
Chroma	Planned	적용할 수 없음	적용할 수 없음
메모리 내	사용할 수 있음	적용할 수 없음	마이크로소프트
Milvus	Planned	적용할 수 없음	적용할 수 없음
MongoDB	사용할 수 있음	예	마이크로소프트
Neon Serverless Postgres	Postgres 구현 사용	예	마이크로소프트
Oracle	사용할 수 있음	예	Oracle
파인콘	사용할 수 있음	No	마이크로소프트
Postgres	사용할 수 있음	예	마이크로소프트
Qdrant	사용할 수 있음	예	마이크로소프트
레디스	사용할 수 있음	예	마이크로소프트
SQL Server	사용할 수 있음	예	마이크로소프트
SQLite	사용할 수 있음	예	마이크로소프트
메모리 내 휘발성	사용되지 않음; 메모리 내 구현 사용	적용할 수 없음	마이크로소프트
Weaviate	사용할 수 있음	예	마이크로소프트

Important

벡터 저장소 구현은 여러 유지 관리자에서 제공됩니다. 사용하기 전에 각 구현의 품질, 라이선스, 지원 정책 및 버전 호환성을 평가합니다. 일부 구현에서는 데이터베이스 공급자가 공식적으로 지원하지 않는 데이터베이스 SDK를 사용합니다.

Get started

추가합니다. Microsoft.Extensions.VectorData.Abstractions 패키지 및 선택한 벡터 저장소 구현에 대한 패키지입니다.
레코드 형식을 정의하고 키, 데이터 및 벡터 속성을 식별합니다.
구현에 애플리케이션에서 생성된 임베딩이 필요한 경우 IEmbeddingGenerator를 구성하세요.
구현 VectorStore을 만든 다음 형식화된 VectorStoreCollection<TKey, TRecord>을 가져옵니다.
컬렉션이 존재하는지 확인하고, 레코드를 업서트하고, 텍스트 또는 벡터와 함께 SearchAsync를 호출합니다.

데이터 모델, 수집, 포함 및 검색에 대한 전체 소개는 .NET AI 앱에 대한 벡터 데이터베이스를 참조하세요.

Python 벡터 저장소 지원

Agent Framework는 벡터 저장소 모델, 컬렉션 작업, 저장소 팩터리, 벡터 및 키워드 하이브리드 검색 및 에이전트 검색 도구에 대한 실험적인 네이티브 Python 계약을 제공합니다. 계약은 agent-framework-core의 일부이며 Pydantic, NumPy, pandas 또는 의미 체계 커널이 필요하지 않습니다.

Warning

네이티브 Python 벡터 저장소 API는 실험적입니다. 안정화되기 전에 일부 호환성이 깨지는 변경 사항이 발생할 수 있습니다.

핵심 추상화

추상화	Purpose
`VectorStoreField` 및 `VectorStoreCollectionDefinition`	스토리지 이름, 인덱스, 차원 및 거리 함수를 비롯한 키, 데이터 및 벡터 필드를 설명합니다.
`@vectorstoremodel` 및 `register_vectorstoremodel()`	데이터 클래스, Pydantic 모델, msgspec 구조체, 일반 클래스 또는 외부 소유 모델 형식을 등록합니다.
`BaseVectorCollection` 및 `SupportsVectorUpsert`	일괄 업서트, 가져오기, 삭제, 컬렉션 수명 주기, 레코드 변환 및 선택적 임베딩 생성을 정의합니다.
`BaseVectorStore`	컬렉션을 나열하고 형식화된 컬렉션 클라이언트를 만드는 저장소를 정의합니다.
`BaseVectorSearch` 및 `SupportsVectorSearch`	벡터 및 키워드 하이브리드 검색, 페이징, 필터, 점수 임계값 및 검색 결과를 정의합니다.
`Filter`, `FilterGroup` 및 `Param`	검색 도구에 대한 모델 제공 필터 매개 변수를 포함하여 이식 가능한 데이터 전용 필터를 정의합니다.
`InMemoryStore` 및 `InMemoryCollection`	개발 및 테스트에 대한 프로세스 로컬 CRUD 및 선형 검색 검색을 제공합니다.
`GenerateVectors`	upsert가 모든 벡터 필드, 없음 또는 선택한 벡터 필드를 생성하는지 여부를 제어합니다.
`create_vector_search_tool()`	`SupportsVectorSearch` 구현을 Agent Framework 함수 도구로 노출합니다.

다음 샘플에서는 키, 데이터 및 벡터 필드에 주석을 추가하여 벡터 저장소 레코드를 정의합니다.

# 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() . 배열과 유사한 벡터 값은 NumPy 의존성을 추가하지 않고 tolist()를 통해 직렬화됩니다.

에이전트 프레임워크에는 개발 및 테스트를 위한 메모리 내 구현이 포함되어 있습니다. 현재 프로세스에 레코드를 저장하고 선형 검사를 사용하므로 프로덕션 워크로드에 데이터베이스 커넥터를 사용합니다.

다음 샘플에서는 미리 계산된 벡터를 저장하고 이식 가능한 필터 트리를 사용하여 검색합니다.

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

네이티브 에이전트 프레임워크 구현

다음 구현에서는 네이티브 에이전트 프레임워크 계약을 사용합니다. 각 커넥터는 별도의 의미 체계 커널 커넥터로도 사용할 수 있지만 두 커넥터 패밀리는 서로 교환할 수 없습니다.

Implementation	에이전트 프레임워크 패키지 및 수명 주기	별도의 의미 체계 커널 커넥터	검색 모드	주요 제한 사항
메모리 내 데이터	`agent-framework-core`; 실험적 벡터 API를 사용하여 릴리스된 패키지	가능	이식 가능한 필터가 있는 조밀한 벡터	프로덕션 데이터베이스가 아닌 개발 및 테스트를 위한 프로세스 로컬 선형 검사입니다.
Azure AI 검색	`agent-framework-azure-ai-search`; 실험적 벡터 API를 사용하여 베타 패키지	가능	밀집 벡터 및 키워드 하이브리드	쿼리당 최상위 수준의 조밀한 벡터 필드 1개. 일부 임계값, 하이브리드 텍스트 재현율 제어, 엄격한 사후 필터링 및 사용 권한에는 이를 지원하는 미리 보기 SDK/API 및 `allow_preview=True`가 필요합니다.
pgvector를 사용하는 PostgreSQL	`agent-framework-postgres`; 알파 패키지	가능	정확한 밀집 벡터, HNSW, IVFFlat	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 클러스터, 키워드 검색 및 하이브리드 검색은 지원되지 않습니다.

사용하는 데이터베이스에 대한 시험판 커넥터 패키지를 설치합니다.

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

각 커넥터는 공통 모델, 컬렉션, CRUD, 필터 및 검색 계약을 구현합니다. 데이터베이스 관련 기능 및 제한 사항은 여전히 적용됩니다. 전체 예제는 Azure AI 검색, Postgres, Qdrant 및 Redis 샘플을 참조하세요.

의미 체계 커널 전용 구현

애플리케이션은 계속해서 의미 체계 커널 Python 벡터 저장소를 직접 사용할 수 있습니다. 이러한 구현은 네이티브 에이전트 프레임워크 계약이 아닌 별도의 의미 체계 커널 벡터 저장소 계약을 사용합니다. 다음 구현에는 현재 네이티브 에이전트 프레임워크 커넥터가 없습니다.

Implementation	Availability	공식적으로 지원되는 데이터베이스 SDK 사용	유지 관리자 또는 공급업체
MongoDB vCore에 대한 Azure Cosmos DB	사용할 수 있음	예	Microsoft 의미 체계 커널 프로젝트
NoSQL용 Azure Cosmos DB	사용할 수 있음	예	Microsoft 의미 체계 커널 프로젝트
크로마	사용할 수 있음	예	Microsoft 의미 체계 커널 프로젝트
Elasticsearch	Planned	적용할 수 없음	적용할 수 없음
파이스(Faiss)	사용할 수 있음	예	Microsoft 의미 체계 커널 프로젝트
MongoDB	사용할 수 있음	예	Microsoft 의미 체계 커널 프로젝트
Neon Serverless Postgres	Postgres 구현 사용	예	Microsoft 의미 체계 커널 프로젝트
Oracle	사용할 수 있음	예	Oracle
파인콘	사용할 수 있음	예	Microsoft 의미 체계 커널 프로젝트
SQL Server	사용할 수 있음	`pyodbc`	Microsoft 의미 체계 커널 프로젝트
SQLite	Planned	적용할 수 없음	Microsoft 의미 체계 커널 프로젝트
Weaviate	사용할 수 있음	예	Microsoft 의미 체계 커널 프로젝트

Important

벡터 저장소 구현은 여러 유지 관리자에서 제공됩니다. 사용하기 전에 각 구현의 품질, 라이선스, 지원 정책 및 버전 호환성을 평가합니다.

의미 체계 커널 전용 구현 사용

semantic-kernel 및 선택한 구현에 필요한 종속성을 설치합니다.
데코레이터를 사용하여 모델을 @vectorstoremodel 정의하고 키, 데이터 및 벡터 필드를 식별합니다.
해당 모델에 대한 구현별 컬렉션을 만듭니다.
컬렉션이 존재하는지 확인한 후 레코드를 삽입하거나 업데이트합니다.
컬렉션의 검색 API를 사용하여 애플리케이션에 대한 레코드를 검색합니다.

구현 설정 및 전체 예제는 의미 체계 커널 벡터 저장소를 참조하세요.

Go 벡터 저장소 지원

벡터 저장소 통합은 아직 Agent Framework for Go에서 사용할 수 없습니다. 최신 상태는 에이전트 프레임워크 Go 리포지토리 를 참조하세요.

다음 단계

에이전트에 RAG 추가

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-09-11

벡터 저장소 통합