trustgraph/docs/tech-specs/embeddings-batch-processing.tr.md

layout	title	parent
default	Gömme İşlemleri Toplu İşleme Teknik Özellikleri	Turkish (Beta)

Gömme İşlemleri Toplu İşleme Teknik Özellikleri

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Genel Bakış

Bu teknik özellik, gömme hizmeti için, tek bir istekte birden fazla metni toplu olarak işleyebilmeyi desteklemek amacıyla yapılan optimizasyonları açıklamaktadır. Mevcut uygulama, her seferinde tek bir metni işlemektedir ve bu durum, gömme modellerinin toplu işlemler sırasında sağladığı önemli performans avantajlarından yararlanılmamasına neden olmaktadır.

1. Tek Metin İşleme Verimsizliği: Mevcut uygulama, tek metinleri bir liste içinde kullanarak, FastEmbed'in toplu işleme yeteneklerini tam olarak kullanamamaktadır.
2. Metin Başına İstek Yükü: Her metin için ayrı bir Pulsar mesajı gönderilip alınması gerekmektedir.
3. Model Çıkarım Verimsizliği: Gömme modellerinin sabit bir toplu işleme yükü vardır; küçük toplu işlemler GPU/CPU kaynaklarının israfına yol açar.
4. Çağıran Tarafında Seri İşleme: Önemli hizmetler, öğeler üzerinde döngü yaparak gömme işlemlerini tek tek gerçekleştirmektedir.

Hedefler

Toplu API Desteği: Tek bir istekte birden fazla metni işleyebilmeyi destekleyin. Geriye Dönük Uyumluluk: Tek metin isteklerine olan desteği koruyun. Önemli Verimlilik Artışı: Toplu işlemler için 5-10 kat verimlilik artışı hedefleyin. Metin Başına Azaltılmış Gecikme: Birden fazla metni gömme işlemi sırasında amortize gecikmeyi azaltın. Bellek Verimliliği: Aşırı bellek tüketimi olmadan toplu işlemleri gerçekleştirin. Sağlayıcıdan Bağımsızlık: FastEmbed, Ollama ve diğer sağlayıcılar arasında toplu işleme desteğini sağlayın. Çağıran Taraf Güncellemesi: Toplu API'nin faydalı olduğu durumlarda tüm gömme işlemlerini kullanan hizmetleri güncelleyin.

Arka Plan

Mevcut Uygulama - Gömme Hizmeti

trustgraph-flow/trustgraph/embeddings/fastembed/processor.py içindeki gömme uygulamasında önemli bir performans verimsizliği bulunmaktadır:

# fastembed/processor.py line 56
async def on_embeddings(self, text, model=None):
    use_model = model or self.default_model
    self._load_model(use_model)

    vecs = self.embeddings.embed([text])  # Single text wrapped in list

    return [v.tolist() for v in vecs]

Sorunlar:

1. Batch Boyutu 1: FastEmbed'in embed() yöntemi, toplu işleme için optimize edilmiştir, ancak bunu her zaman [text] - 1 boyutlu bir toplu işleme ile çağırıyoruz.

2. İstek Başına Ek Yük: Her gömme isteği aşağıdaki ek yükleri içerir: Pulsar mesajı serileştirme/deserileştirme Ağ gidiş-dönüş gecikmesi Model çıkarım başlatma ek yükü Python asenkron planlama ek yükü

3. Şema Sınırlaması: EmbeddingsRequest şeması yalnızca tek bir metni destekler:

   @dataclass
   class EmbeddingsRequest:
       text: str = ""  # Single text only
   

Mevcut Çağrılar - Seri İşleme

1. API Ağ Geçidi

Dosya: trustgraph-flow/trustgraph/gateway/dispatch/embeddings.py

Ağ geçidi, HTTP/WebSocket üzerinden tek metin gömme isteklerini kabul eder ve bunları gömme hizmetine yönlendirir. Şu anda toplu işlem için bir uç nokta bulunmamaktadır.

class EmbeddingsRequestor(ServiceRequestor):
    # Handles single EmbeddingsRequest -> EmbeddingsResponse
    request_schema=EmbeddingsRequest,  # Single text only
    response_schema=EmbeddingsResponse,

Etki: Harici müşteriler (web uygulamaları, betikler), N metni yerleştirmek için N adet HTTP isteği yapmalıdır.

2. Belge Gömme Hizmeti

Dosya: trustgraph-flow/trustgraph/embeddings/document_embeddings/embeddings.py

Belgeleri tek tek parçalar halinde işler:

async def on_message(self, msg, consumer, flow):
    v = msg.value()

    # Single chunk per request
    resp = await flow("embeddings-request").request(
        EmbeddingsRequest(text=v.chunk)
    )
    vectors = resp.vectors

Etki: Her belge parçası için ayrı bir gömme (embedding) çağrısı gereklidir. 100 parçadan oluşan bir belge = 100 gömme isteği.

3. Grafik Gömme Hizmeti

Dosya: trustgraph-flow/trustgraph/embeddings/graph_embeddings/embeddings.py

Varlıklar üzerinde döngü yapar ve her birini sırayla gömer:

async def on_message(self, msg, consumer, flow):
    for entity in v.entities:
        # Serial embedding - one entity at a time
        vectors = await flow("embeddings-request").embed(
            text=entity.context
        )
        entities.append(EntityEmbeddings(
            entity=entity.entity,
            vectors=vectors,
            chunk_id=entity.chunk_id,
        ))

Etki: 50 varlık içeren bir mesaj, 50 adet ardışık gömme (embedding) isteği anlamına gelir. Bu, bilgi grafiği oluşturma sırasında büyük bir darboğazdır.

4. Satır Gömme Hizmeti

Dosya: trustgraph-flow/trustgraph/embeddings/row_embeddings/embeddings.py

Benzersiz metinler üzerinde döngü yapar ve her birini sırayla gömer:

async def on_message(self, msg, consumer, flow):
    for text, (index_name, index_value) in texts_to_embed.items():
        # Serial embedding - one text at a time
        vectors = await flow("embeddings-request").embed(text=text)

        embeddings_list.append(RowIndexEmbedding(
            index_name=index_name,
            index_value=index_value,
            text=text,
            vectors=vectors
        ))

Etki: 100 benzersiz indeksli değere sahip bir tabloyu işlemek = 100 ardışık gömme isteği.

5. EmbeddingsClient (Temel İstemci)

Dosya: trustgraph-base/trustgraph/base/embeddings_client.py

Tüm iş akışı işleyicileri tarafından kullanılan istemci, yalnızca tek metin gömmesini destekler:

class EmbeddingsClient(RequestResponse):
    async def embed(self, text, timeout=30):
        resp = await self.request(
            EmbeddingsRequest(text=text),  # Single text
            timeout=timeout
        )
        return resp.vectors

Etki: Bu istemciyi kullanan tüm uygulamalar, yalnızca tek metin işlemleriyle sınırlıdır.

6. Komut Satırı Araçları

Dosya: trustgraph-cli/trustgraph/cli/invoke_embeddings.py

CLI aracı, tek bir metin argümanı alır:

def query(url, flow_id, text, token=None):
    result = flow.embeddings(text=text)  # Single text
    vectors = result.get("vectors", [])

Etki: Kullanıcılar, komut satırından toplu gömme işlemi yapamaz. Bir metin dosyasını işlemek, N sayıda çağrı gerektirir.

7. Python SDK

Python SDK, TrustGraph hizmetleriyle etkileşim kurmak için iki istemci sınıfı sağlar. Her ikisi de yalnızca tek metin gömme işlemini destekler.

Dosya: trustgraph-base/trustgraph/api/flow.py

class FlowInstance:
    def embeddings(self, text):
        """Get embeddings for a single text"""
        input = {"text": text}
        return self.request("service/embeddings", input)["vectors"]

Dosya: trustgraph-base/trustgraph/api/socket_client.py

class SocketFlowInstance:
    def embeddings(self, text: str, **kwargs: Any) -> Dict[str, Any]:
        """Get embeddings for a single text via WebSocket"""
        request = {"text": text}
        return self.client._send_request_sync(
            "embeddings", self.flow_id, request, False
        )

Etki: SDK'yı kullanan Python geliştiricilerinin, metinler üzerinde döngü yapması ve N adet API çağrısı yapması gerekir. SDK kullanıcıları için toplu gömme desteği mevcut değildir.

Performans Etkisi

Tipik belge yükleme için (1000 metin parçası): Mevcut: 1000 ayrı istek, 1000 model çıkarım çağrısı Toplu (batch_size=32): 32 istek, 32 model çıkarım çağrısı (%96,8 azalma)

Grafik gömme için (50 varlığa sahip mesaj): Mevcut: 50 ardışık bekletme çağrısı, ~5-10 saniye Toplu: 1-2 toplu çağrı, ~0,5-1 saniye (5-10 kat iyileşme)

FastEmbed ve benzeri kütüphaneler, toplu boyutun donanım sınırlarına kadar ulaştığı durumlarda, yaklaşık doğrusal bir verim ölçeklemesi sağlar (tipik olarak toplu boyutta 32-128 metin).

Teknik Tasarım

Mimari

Gömme toplu işleme optimizasyonu, aşağıdaki bileşenlerde değişiklikler gerektirir:

1. Şema Geliştirme

EmbeddingsRequest'ı, birden fazla metni destekleyecek şekilde genişletin EmbeddingsResponse'ı, birden fazla vektör kümesini döndürecek şekilde genişletin Tek metin istekleriyle uyumluluğu koruyun

Modül: trustgraph-base/trustgraph/schema/services/llm.py

2. Temel Servis Geliştirme

EmbeddingsService'ı, toplu istekleri işleyebilecek şekilde güncelleyin Toplu boyut yapılandırması ekleyin Toplu işleme duyarlı istek işleme uygulayın

Modül: trustgraph-base/trustgraph/base/embeddings_service.py

3. Sağlayıcı İşlemcisi Güncellemeleri

FastEmbed işlemcisini güncelleyin, böylece tam toplu iş yükünü embed()'a iletebilir Ollama işlemcisini güncelleyin, böylece toplu işlemleri işleyebilir (destekleniyorsa) Toplu işlemeyi desteklemeyen sağlayıcılar için yedek sıralı işlemeyi ekleyin

Modüller: trustgraph-flow/trustgraph/embeddings/fastembed/processor.py trustgraph-flow/trustgraph/embeddings/ollama/processor.py

4. İstemci Geliştirme

EmbeddingsClient'a toplu gömme yöntemini ekleyin Hem tek hem de toplu API'leri destekleyin Büyük girdiler için otomatik toplu işlemeyi ekleyin

Modül: trustgraph-base/trustgraph/base/embeddings_client.py

5. Çağrı Güncellemeleri - Akış İşlemcileri

graph_embeddings'ı, varlık bağlamlarını toplu hale getirecek şekilde güncelleyin row_embeddings'ı, indeks metinlerini toplu hale getirecek şekilde güncelleyin Mesaj toplu işlemesi mümkünse, document_embeddings'ı güncelleyin

Modüller: trustgraph-flow/trustgraph/embeddings/graph_embeddings/embeddings.py trustgraph-flow/trustgraph/embeddings/row_embeddings/embeddings.py trustgraph-flow/trustgraph/embeddings/document_embeddings/embeddings.py

6. API Ağ Geçidi Geliştirme

Toplu gömme uç noktası ekleyin İstek gövdesinde metin dizisini destekleyin

Modül: trustgraph-flow/trustgraph/gateway/dispatch/embeddings.py

7. CLI Aracı Geliştirme

Birden fazla metin veya dosya girişi desteği ekleyin Toplu boyut parametresi ekleyin

Modül: trustgraph-cli/trustgraph/cli/invoke_embeddings.py

8. Python SDK Geliştirme

embeddings_batch() yöntemini FlowInstance'e ekleyin embeddings_batch() yöntemini SocketFlowInstance'e ekleyin SDK kullanıcıları için hem tek hem de toplu API'leri destekleyin

Modüller: trustgraph-base/trustgraph/api/flow.py trustgraph-base/trustgraph/api/socket_client.py

Veri Modelleri

EmbeddingsRequest

@dataclass
class EmbeddingsRequest:
    texts: list[str] = field(default_factory=list)

Kullanım: Tek metin: EmbeddingsRequest(texts=["hello world"]) Toplu işlem: EmbeddingsRequest(texts=["text1", "text2", "text3"])

EmbeddingsResponse

@dataclass
class EmbeddingsResponse:
    error: Error | None = None
    vectors: list[list[list[float]]] = field(default_factory=list)

Yanıt yapısı: vectors[i], texts[i] için vektör kümesini içerir. Her vektör kümesi list[list[float]]'dır (modeller, her metin için birden fazla vektör döndürebilir). Örnek: 3 metin → vectors, 3 giriş içerir ve her giriş, o metnin gömülme değerlerini içerir.

API'ler

EmbeddingsClient

class EmbeddingsClient(RequestResponse):
    async def embed(
        self,
        texts: list[str],
        timeout: float = 300,
    ) -> list[list[list[float]]]:
        """
        Embed one or more texts in a single request.

        Args:
            texts: List of texts to embed
            timeout: Timeout for the operation

        Returns:
            List of vector sets, one per input text
        """
        resp = await self.request(
            EmbeddingsRequest(texts=texts),
            timeout=timeout
        )
        if resp.error:
            raise RuntimeError(resp.error.message)
        return resp.vectors

API Gateway Gömülü Veri (Embeddings) Uç Noktası

Tek bir veya toplu gömülü veri desteğini sağlayan güncellenmiş uç nokta:

POST /api/v1/embeddings
Content-Type: application/json

{
    "texts": ["text1", "text2", "text3"],
    "flow_id": "default"
}

Response:
{
    "vectors": [
        [[0.1, 0.2, ...]],
        [[0.3, 0.4, ...]],
        [[0.5, 0.6, ...]]
    ]
}

Uygulama Detayları

Aşama 1: Şema Değişiklikleri

EmbeddingsRequest:

@dataclass
class EmbeddingsRequest:
    texts: list[str] = field(default_factory=list)

Gömme Yanıtı:

@dataclass
class EmbeddingsResponse:
    error: Error | None = None
    vectors: list[list[list[float]]] = field(default_factory=list)

Güncellenmiş EmbeddingsService.on_request:

async def on_request(self, msg, consumer, flow):
    request = msg.value()
    id = msg.properties()["id"]
    model = flow("model")

    vectors = await self.on_embeddings(request.texts, model=model)
    response = EmbeddingsResponse(error=None, vectors=vectors)

    await flow("response").send(response, properties={"id": id})

2. Aşama: FastEmbed İşlemci Güncellemesi

Mevcut (Verimsiz):

async def on_embeddings(self, text, model=None):
    use_model = model or self.default_model
    self._load_model(use_model)
    vecs = self.embeddings.embed([text])  # Batch of 1
    return [v.tolist() for v in vecs]

Güncellendi:

async def on_embeddings(self, texts: list[str], model=None):
    """Embed texts - processes all texts in single model call"""
    if not texts:
        return []

    use_model = model or self.default_model
    self._load_model(use_model)

    # FastEmbed handles the full batch efficiently
    all_vecs = list(self.embeddings.embed(texts))

    # Return list of vector sets, one per input text
    return [[v.tolist()] for v in all_vecs]

3. Aşama: Grafik Gömme Hizmeti Güncellemesi

Mevcut (Sıralı):

async def on_message(self, msg, consumer, flow):
    entities = []
    for entity in v.entities:
        vectors = await flow("embeddings-request").embed(text=entity.context)
        entities.append(EntityEmbeddings(...))

Güncellendi (Toplu İşlem):

async def on_message(self, msg, consumer, flow):
    # Collect all contexts
    contexts = [entity.context for entity in v.entities]

    # Single batch embedding call
    all_vectors = await flow("embeddings-request").embed(texts=contexts)

    # Pair results with entities
    entities = [
        EntityEmbeddings(
            entity=entity.entity,
            vectors=vectors[0],  # First vector from the set
            chunk_id=entity.chunk_id,
        )
        for entity, vectors in zip(v.entities, all_vectors)
    ]

4. Aşama: Satır Gömme Hizmeti Güncellemesi

Mevcut (Sıralı):

for text, (index_name, index_value) in texts_to_embed.items():
    vectors = await flow("embeddings-request").embed(text=text)
    embeddings_list.append(RowIndexEmbedding(...))

Güncellendi (Toplu İşlem):

# Collect texts and metadata
texts = list(texts_to_embed.keys())
metadata = list(texts_to_embed.values())

# Single batch embedding call
all_vectors = await flow("embeddings-request").embed(texts=texts)

# Pair results
embeddings_list = [
    RowIndexEmbedding(
        index_name=meta[0],
        index_value=meta[1],
        text=text,
        vectors=vectors[0]  # First vector from the set
    )
    for text, meta, vectors in zip(texts, metadata, all_vectors)
]

5. Aşama: Komut Satırı Arama Aracı Geliştirme

Güncellenmiş Komut Satırı:

def main():
    parser = argparse.ArgumentParser(...)

    parser.add_argument(
        'text',
        nargs='*',  # Zero or more texts
        help='Text(s) to convert to embedding vectors',
    )

    parser.add_argument(
        '-f', '--file',
        help='File containing texts (one per line)',
    )

    parser.add_argument(
        '--batch-size',
        type=int,
        default=32,
        help='Batch size for processing (default: 32)',
    )

Kullanım:

# Single text (existing)
tg-invoke-embeddings "hello world"

# Multiple texts
tg-invoke-embeddings "text one" "text two" "text three"

# From file
tg-invoke-embeddings -f texts.txt --batch-size 64

6. Aşama: Python SDK Geliştirme

FlowInstance (HTTP istemcisi):

class FlowInstance:
    def embeddings(self, texts: list[str]) -> list[list[list[float]]]:
        """
        Get embeddings for one or more texts.

        Args:
            texts: List of texts to embed

        Returns:
            List of vector sets, one per input text
        """
        input = {"texts": texts}
        return self.request("service/embeddings", input)["vectors"]

SocketFlowInstance (WebSocket istemcisi):

class SocketFlowInstance:
    def embeddings(self, texts: list[str], **kwargs: Any) -> list[list[list[float]]]:
        """
        Get embeddings for one or more texts via WebSocket.

        Args:
            texts: List of texts to embed

        Returns:
            List of vector sets, one per input text
        """
        request = {"texts": texts}
        response = self.client._send_request_sync(
            "embeddings", self.flow_id, request, False
        )
        return response["vectors"]

SDK Kullanım Örnekleri:

# Single text
vectors = flow.embeddings(["hello world"])
print(f"Dimensions: {len(vectors[0][0])}")

# Batch embedding
texts = ["text one", "text two", "text three"]
all_vectors = flow.embeddings(texts)

# Process results
for text, vecs in zip(texts, all_vectors):
    print(f"{text}: {len(vecs[0])} dimensions")

Güvenlik Hususları

İstek Boyutu Sınırları: Kaynak tükenmesini önlemek için maksimum toplu işlem boyutunu zorlayın. Zaman Aşımı İşleme: Toplu işlem boyutu için zaman aşımını uygun şekilde ayarlayın. Bellek Sınırları: Büyük toplu işlemler için bellek kullanımını izleyin. Giriş Doğrulama: İşleme yapmadan önce toplu işlemdeki tüm metinleri doğrulayın.

Performans Hususları

Beklenen İyileştirmeler

Verim: Tek metin: ~10-50 metin/saniye (modele bağlı olarak) Toplu işlem (boyut 32): ~200-500 metin/saniye (5-10 kat iyileşme)

Metin Başına Gecikme: Tek metin: metin başına 50-200 ms Toplu işlem (boyut 32): metin başına 5-20 ms (ortalama)

Hizmete Özel İyileştirmeler:

Hizmet	Mevcut	Toplu	İyileşme
Grafik Gömme (50 varlık)	5-10 saniye	0,5-1 saniye	5-10 kat
Satır Gömme (100 metin)	10-20 saniye	1-2 saniye	5-10 kat
Belge Alma (1000 parça)	100-200 saniye	10-30 saniye	5-10 kat

Yapılandırma Parametreleri

# Recommended defaults
DEFAULT_BATCH_SIZE = 32
MAX_BATCH_SIZE = 128
BATCH_TIMEOUT_MULTIPLIER = 2.0

Test Stratejisi

Birim Testleri

Tek metin gömülmesi (geriye dönük uyumluluk) Boş toplu iş işleme Maksimum toplu iş boyutu zorlaması Kısmi toplu iş hataları için hata işleme

Entegrasyon Testleri

Pulsar üzerinden uçtan uca toplu iş gömülmesi Grafik gömme hizmeti toplu iş işleme Satır gömme hizmeti toplu iş işleme API ağ geçidi toplu iş uç noktası

Performans Testleri

Tek ve toplu iş verimini karşılaştırma Farklı toplu iş boyutları altındaki bellek kullanımı Gecikme dağılımı analizi

Geçiş Planı

Bu, önemli değişikliklere neden olan bir sürümdür. Tüm fazlar birlikte uygulanır.

1. Aşama: Şema Değişiklikleri

EmbeddingsRequest'teki text: str'ı texts: list[str] ile değiştirin EmbeddingsResponse'taki vectors türünü list[list[list[float]]] olarak değiştirin

2. Aşama: İşlemci Güncellemeleri

FastEmbed ve Ollama işlemcilerindeki on_embeddings imzasını güncelleyin Tam toplu işi tek bir model çağrısında işleyin

3. Aşama: İstemci Güncellemeleri

EmbeddingsClient.embed()'ı texts: list[str]'i kabul edecek şekilde güncelleyin

4. Aşama: Çağıran Güncellemeleri

graph_embeddings'i toplu iş varlık bağlamlarını kullanacak şekilde güncelleyin row_embeddings'i toplu iş indeks metinlerini kullanacak şekilde güncelleyin document_embeddings'i yeni şemayı kullanacak şekilde güncelleyin CLI aracını güncelleyin

5. Aşama: API Ağ Geçidi

Yeni şema için gömme uç noktasını güncelleyin

6. Aşama: Python SDK

FlowInstance.embeddings() imzasını güncelleyin SocketFlowInstance.embeddings() imzasını güncelleyin

Açık Sorular

Büyük Toplu İşlerin Akışı: Çok büyük toplu işler (>100 metin) için sonuçları akış olarak desteklemeli miyiz? Sağlayıcıya Özel Sınırlar: Farklı maksimum toplu iş boyutlarına sahip sağlayıcıları nasıl ele almalıyız? Kısmi Hata İşleme: Bir toplu işteki bir metin başarısız olursa, tüm toplu işi mi başarısız etmeliyiz yoksa kısmi sonuçları mı döndürmeliyiz? Belge Gömme Toplu İşleme: Çoklu Chunk mesajları arasında toplu işlemeyi mi yapmalıyız yoksa her mesaj için ayrı ayrı işlemeyi mi korumalıyız?

Referanslar

FastEmbed Belgeleri Ollama Gömme API'si EmbeddingsService Uygulaması GraphRAG Performans Optimizasyonu