Agent Framework Python’da Vector Store ile Ajan Bağlamı
Microsoft Agent Framework’ün Python tarafındaki vector store desteği sıfırdan yazılmadı. Semantic Kernel’de bir süredir duran vector-store API’leri bu çatıya taşındı; tipli kayıt tanımları, store/collection ayrımı, toplu yazma-okuma, embedding üretimi ve vektör arama yerli yerinde duruyor. Değişen şey, bu yapıların ajanlara bağlanma biçimi: arama artık ajana bir araç (tool) olarak verilebiliyor, konuşma geçmişi bile bir vector store üzerinde aranabilir halde tutulabiliyor.
Bu yazı Python tarafını anlatıyor..NET karşılığı için Microsoft’un Use vector stores in.NET AI apps dokümanına bakabilirsiniz. Vector-store API’leri hala deneysel (experimental) durumda, entegrasyon paketleri de alpha ya da beta seviyesinde. Kurulum ve desteklenen yetenekler için her implementasyonun kendi dokümantasyonunu açmak gerekiyor.
Önce kendi veri modeliniz
Agent Framework, modeli uygulamanın zaten sahip olduğu veri sınıfı üzerinden kuruyor; veritabanının şeması işin merkezinde durmuyor. Anahtar, veri ve vektör alanlarını VectorStoreField ile işaretliyorsunuz, @vectorstoremodel dekoratörü de collection tanımını bu işaretlemelerden türetiyor.
from dataclasses import dataclass
from typing import Annotated
from agent_framework import (
Filter,
InMemoryCollection,
VectorStoreField,
vectorstoremodel,
)
from agent_framework.openai import OpenAIEmbeddingClient
@vectorstoremodel(collection_name="documents")
@dataclass
class Document:
id: Annotated[str, VectorStoreField("key")]
category: Annotated[str, VectorStoreField("data", is_indexed=True)]
text: Annotated[str, VectorStoreField("data")]
embedding: Annotated[
list[float] | str | None,
VectorStoreField(
"vector",
dimensions=1536,
distance_function="cosine_similarity",
),
] = None
async def index_and_search() -> None:
documents: InMemoryCollection[str, Document] = InMemoryCollection(
Document, embedding_generator=OpenAIEmbeddingClient(model="text-embedding-3-small"),
)
await documents.ensure_collection_exists()
await documents.upsert([
Document(
id="release-checklist",
category="operations",
text="Verify rollback, monitoring, and owner sign-off.",
embedding="Verify rollback, monitoring, and owner sign-off.",
)
])
results = await documents.search(
"What should I check before a release?",
filter=Filter("category", "eq", "operations"),
top=3,
)
async for result in results:
print(result["record"].text, result["score"])
Örneği çalıştırmadan önce OPENAI_API_KEY ortam değişkeninin tanımlı olması gerekiyor. Kayıtlar bellekte tutulduğu için süreç yeniden başlayınca kayboluyor, embedding üretimi ise hem upsert hem de search sırasında OpenAI tarafında yapılıyor. InMemoryCollection yerine desteklenen başka bir implementasyon koyduğunuzda kodun geri kalanına dokunmanız gerekmiyor.
Dataclass tek seçenek değil. Aynı model katmanı Pydantic modellerini, msgspec struct’larını, düz sınıfları, sözlükleri ve özel codec’ler aracılığıyla dışarıdan gelen tipleri de destekliyor.
Vektör aramayı ajan aracına dönüştürmek
Semantic Kernel’de olduğu gibi aramayı doğrudan birinci sınıf bir ajan aracı olarak sunabiliyorsunuz. create_vector_search_tool aranabilir bir collection’ı sarmalıyor; aracın adını, açıklamasını, dönen sonucun biçimini, filtrelerini ve onay (approval) davranışını siz belirliyorsunuz.
Param, özel arama araçları yazmayı burada belirgin biçimde kolaylaştırıyor. Bir Param nesnesini Filter veya FilterGroup içine yerleştirdiğinizde yardımcı yapı bunu, modelin doldurabileceği tipli bir argüman olarak dışarı açıyor:
from typing import Literal
from agent_framework import Filter, Param, create_vector_search_tool
category = Param(
"category",
Literal["engineering", "operations", "product"],
required=False,
description="Only return documents from this category.",
)
search_documents = create_vector_search_tool(
collection,
name="search_documents",
description="Search the document collection.",
filter=Filter("category", "eq", category),
result_mapper=lambda result: result["record"].text,
)
Oluşan araç her zaman doğal dilde bir sorgu alıyor, category parametresini ise isteğe bağlı kabul ediyor. Literal değerleri araç şemasında bir enum’a dönüştüğü için ajan geçerli seçenekleri net görüyor. Model bu opsiyonel parametreyi doldurmazsa ilgili filtre uygulanmıyor. Daha karmaşık senaryolarda birden fazla parametreyi FilterGroup ile birleştirmek mümkün.
Context provider’lar: collection’ı bir bütün olarak ajana açmak
Tek bir odaklı arama aracı yetmediğinde VectorCollectionContextProvider devreye giriyor. Bu sağlayıcı ajana upsert, get, delete ve search araçlarını, bunların nasıl kullanılacağını anlatan yönergelerle birlikte ekleyebiliyor. Senaryoya göre yalnızca okunabilir bir bilgi koleksiyonu sunabilir, kayıt yönetimini onay mekanizmasına bağlayabilir, erişilebilir veri kümesini daraltabilir ya da varsayılan aramanın yerine kendi özel araçlarınızı koyabilirsiniz.
Embedding ayarları da işlem bazında kalıyor: veri alımında doküman embedding seçenekleri, aramada sorgu embedding seçenekleri kullanılabiliyor. Üretilen araçlar bu ayarları aynı collection’a iletiyor.
Aranabilir konuşma geçmişi
Konuşma geçmişi büyüdükçe her turda modele gönderilen bağlam da büyüyor. VectorStoreHistoryProvider konuşmanın tamamını aranabilir bir vektör koleksiyonunda saklıyor, model bağlamına ise yalnızca sıkıştırılmış bir çalışma kümesi yüklüyor.
include_search_tool=True verildiğinde ajan, kapsamlandırılmış tam dökümü arayabileceği bir araç da alıyor. Aktif bağlam sınırlı kalıyor ama geçmişte alınmış bir karara, bir gereksinime veya kullanıcı tercihine erişim kaybolmuyor; ajan her çağrıda tüm mesajları taşımak yerine ihtiyaç duyduğunda ilgili bölümü geri getiriyor.
Embedding ve arama: sağlayıcıyı koda gömmeden
Uygulamalar önceden hesaplanmış vektörleri kendileri verebilir ya da upsert ve search sırasında Agent Framework’ün bir embedding servisini çağırmasını sağlayabilir. Tüm vektör alanları üretilebileceği gibi yalnızca seçili alanlar da üretilebiliyor, doküman alımı ile sorgu üretimi için farklı sağlayıcı seçenekleri geçirilebiliyor. Vektör boyutları model tanımıyla birlikte durduğu için Agent Framework, hem üretilen hem de dışarıdan verilen vektörleri arka uçtaki store’a ulaşmadan önce doğrulayabiliyor.
Arama tarafında da entegrasyonlar arasında aynı collection API’si kullanılıyor; taşınabilir veri filtreleri ve destekleyen sistemlerde keyword-hybrid arama mevcut. Hangi indekslerin, filtrelerin, metriklerin ve arama modlarının desteklendiğini her implementasyon kendi dokümantasyonunda belirtiyor.
Desteklenen entegrasyonlar
Python tarafında halihazırda şu entegrasyonlar var:
- Azure AI Search
- Azure Cosmos DB for NoSQL
- Azure DocumentDB
- MongoDB
- Oracle AI Database 26ai
- Redis
- SQL Server ve Azure SQL
- PostgreSQL (pgvector ile)
- DuckDB
- Qdrant
- Testler ve yerel geliştirme için çekirdek in-memory store
Model katmanı ve temel işlemler bu entegrasyonların hepsinde aynı şekilde çalışıyor, buna karşılık her veritabanı kendi özelliklerini ve kısıtlarını korumaya devam ediyor. Taşınabilirlik model ve API seviyesinde kalıyor; yetenek farklarını yine sizin hesaba katmanız gerekiyor.
Nereden başlamalı
Model tanımı, arama ve ajan araçları için çalıştırılabilir vector store örnekleriyle başlamak en pratik yol. Sınırlı çalışma bağlamı ile tüm konuşma üzerinde arama birleşimini görmek içinse vector store tabanlı konuşma örneğine bakabilirsiniz.
Kullanmak istediğiniz store’un entegrasyon paketini kurup kurulum ve desteklenen yetenekler için README’sini izlemek gerekiyor. Ekip özellikle context provider deneyimi, aranabilir geçmiş ve sıradaki entegrasyon talepleri konusunda geri bildirim istiyor; bunun için Microsoft Agent Framework deposunda issue açmak öneriliyor.
Kaynaklar ve İleri Okuma
- Vector stores in Agent Framework for Python: familiar foundations, streamlined for agents (Eduard van Valkenburg)
- Microsoft Agent Framework blogu
- Microsoft Agent Framework için Cosmos DB Tabanlı Bellek
- Microsoft Agent Framework 1.0: Ajanlar Artık Ciddileşti
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
Yorum gönder