Skip to content

Modul 19: Daten-Pipelines & Streaming

Datenflüsse in Go beherrschen: io.Reader/Writer-Compositors mit Tee, Pipe und MultiWriter, Backpressure-Management in Channel-Pipelines ohne Goroutine-Leaks, Kafka-Integration mit franz-go und sarama inklusive Batching und Rebalancing, effiziente Batch-Inserts mit pgx COPY und Transaktions-Chunking, sowie eine vollständige Streaming-Embedding-Pipeline von Dateien zu Chunks zu Vektoren.

Fortschritt0/5 Lektionen
91

io.Reader/Writer-Compositors: Tee, Pipe, MultiWriter

Lektion 91 von 100

Warum Compositor-Pattern die Unix-Pipe in Go sind

Die Buchhandlung »Kant & Kurve« will jeden Verkauf als Log-Eintrag speichern — und gleichzeitig in Echtzeit an ein Analysetool schicken. Ein naiver Ansatz würde die Daten zweimal schreiben: einmal für die Logdatei, einmal für den Stream. Das ist ineffizient und fehleranfällig. Die Lösung: io.Reader/Writer-Compositors. Sie erlauben es, Datenströme zu verzweigen, zu verbinden und zu duplizieren — ganz ohne die Daten selbst zu kopieren.

io.Pipe: Synchronous In-Memory-Pipelines

Ein io.Pipe verbindet einen PipeReader mit einem PipeWriter über einen synchronen In-Memory-Kanal. Schreibt der Writer, kann der Reader die Daten lesen — und das ohne Pitstop im Speicher. Perfekt für Situationen, in denen ein Goroutine-Daten erzeugt (Writer) und eine andere sie konsumiert (Reader), ohne dass der gesamte Datensatz im Speicher landen muss.

Das Fundament: io.Pipe für die Kommunikation zwischen Goroutines, ohne Puffer im propios Sinn:

// internal/pipeline/pipe.go — io.Pipe als synchroner Kanal zwischen Producer und Consumer
package pipeline

import (
	"io"
	"strings"
)

// ProcessStream liest von einem Reader, transformiert die Daten und schreibt auf den PipeWriter
func ProcessStream(r io.Reader, w *io.PipeWriter, transform func(string) string) {
	defer w.Close() // Pflicht! Sonst hängt der Reader für immer
	
	buf := make([]byte, 4096)
	for {
		n, err := r.Read(buf)
		if err != nil {
			if err != io.EOF {
				w.CloseWithError(err)
			}
			return
		}
		// Transformieren: z. B. in Großbuchstaben
		transformed := transform(string(buf[:n]))
		if _, err := w.Write([]byte(transformed)); err != nil {
			w.CloseWithError(err)
			return
		}
	}
}

// Beispielaufruf: String-Reader als Quelle, Transformierung in Großbuchstaben
func PipeExample() (string, error) {
	pr, pw := io.Pipe()
	
	// Producer-Goroutine
	go ProcessStream(strings.NewReader("daten-pipeline"), pw, strings.ToUpper)
	
	// Consumer: alles lesen
	buf := make([]byte, 4096)
	n, err := pr.Read(buf)
	if err != nil && err != io.EOF {
		return "", err
	}
	return string(buf[:n]), nil
}

// Terminal: go run .
// → DATEN-PIPELINE

Jetzt der klassische Unix-tee-Befehl als Go-Idiom: Daten gleichzeitig in mehrere Writer schicken mit io.MultiWriter:

// internal/pipeline/tee.go — Tee: Daten an mehrere Ziele gleichzeitig schreiben
package pipeline

import (
	"bytes"
	"fmt"
	"io"
	"os"
	"strings"
)

// TeeWriter dupliziert alle Daten an mehrere Writer
func TeeWriter(writers ...io.Writer) io.Writer {
	return io.MultiWriter(writers...)
}

// Beispiel: Log-Datei UND Stdout gleichzeitig beschreiben
func TeeExample() error {
	logFile, err := os.Create("pipeline.log")
	if err != nil {
		return err
	}
	defer logFile.Close()
	
	// Tee: gleichzeitig in Datei und Stdout schreiben
	tee := TeeWriter(logFile, os.Stdout)
	
	// Datenquelle
	src := strings.NewReader("Verkaufslog: Buch 978-3-423-2089-8\n")
	
	// Kopieren: src → tee (→ Datei UND Stdout)
	if _, err := io.Copy(tee, src); err != nil {
		return err
	}
	
	return nil
}

// Terminal: go run .
// → Verkaufslog: Buch 978-3-423-2089-8
// (gleichzeitig in pipeline.log geschrieben)

Für das Debugging von Pipelines unersetzlich: io.TeeReader erlaubt es, einen Datenstrom mitzulesen, ohne ihn zu essendo consumieren:

// internal/pipeline/debug.go — TeeReader für Debugging von Datenströmen
package pipeline

import (
	"bytes"
	"fmt"
	"io"
	"strings"
)

// LogReader wrappt einen Reader und loggt alles, was durchfließt
func LogReader(name string, r io.Reader) io.Reader {
	return io.TeeReader(r, &debugWriter{name: name})
}

type debugWriter struct {
	name string
	buf  bytes.Buffer
}

func (w *debugWriter) Write(p []byte) (int, error) {
	w.buf.Write(p)
	fmt.Printf("[%s] empfangen: %s", w.name, string(p))
	return len(p), nil
}

func (w *debugWriter) String() string {
	return w.buf.String()
}

// Beispiel: Datenfluss mit Logging
func TeeReaderExample() (string, error) {
	// Ur-Daten
	original := strings.NewReader("Wichtige Daten\n")
	
	// Mit Logging wrappen
	logged := LogReader("Debug", original)
	
	// Verarbeiten (alle Daten landen im Buffer)
	var buf bytes.Buffer
	if _, err := io.Copy(&buf, logged); err != nil {
		return "", err
	}
	
	return buf.String(), nil
}

// Terminal: go run .
// → [Debug] empfangen: Wichtige Daten
// → Wichtige Daten

⚠ Häufiger Fehler: io.PipeWriter.Close() vergessen aufzurufen, wenn der schreiben beendet ist. Der zugehörige PipeReader wartet dann für immer auf Daten und blockiert die konsumierende Goroutine. Der Fehler manifestiert sich als Deadlock oder Timeout — und ist schuld an den meisten »my Goroutine hangs«-Tickets in Go-Projekten. Immer defer w.Close() direkt nach dem Erstellen des Writers platzieren.

✅ Wichtige Erkenntnisse

Haken setzen, um deinen Lernfortschritt zu markieren:

    92

    Backpressure: Channel-Pipelines ohne Goroutine-Leaks

    Lektion 92 von 100

    Der Flaschenhals ist das Signal: Backpressure verstehen

    In Modul 7 (Lektion 31-35) haben wir gelernt, wie man Goroutines und Channels für nebenläufige Verarbeitung nutzt. Doch was passiert, wenn der Producer schneller Daten erzeugt als der Consumer verarbeiten kann? Ohne Backpressure-Mechanismus füllt sich der Channel bis zum Bersten — und der Producer blockiert nie. Das Ergebnis: Speicherverbrauch explodiert, Goroutines häufen sich an, und das Programm stürzt ab. Backpressure bedeutet: Der Producer wird gebremst, sobald der Consumer nicht mehr hinterherkommt.

    Die Architektur-Entscheidung dabei: Batch vs. Stream. In Modul 6: Datenarchitektur wird erklärt, wann welche Strategie die richtige ist.

    Channel-Puffer sind kein Allheilmittel

    Gepufferte Channels (make(chan T, 100)) können kurzfristige Spitzen ab federn, aber sie verschleiern nur das Problem von Backpressure. Ein gepufferter Channel mit Größe N kann maximal N Items zwischenspeichern — ist der Puffer voll, blockiert der erwartende send auf dem Channel. Ungepufferte Channels (make(chan T)) haben die Größe 0 und blockieren sofort beim ersten ungelesenen Item. Das ist kein Bug, sondern das gewünschte Verhalten für Backpressure: Der Producer wird automatisch gedrosselt.

    Ein klassisches Szenario: Eine Pipeline, die Dateien liest, Zeile für Zeile verarbeitet und die Ergebnisse speichert. Ohne Backpressure überlastet die schnelle Datei-Lese-Goroutine die langsame Speicher-Goroutine:

    // internal/pipeline/backpressure.go — Pipeline mit Backpressure durch ungepufferte Channels
    package pipeline
    
    import (
    	"bufio"
    	"context"
    	"fmt"
    	"os"
    	"strings"
    	"time"
    )
    
    // LineProcessor verarbeitet eine Zeile (simuliert langsame Verarbeitung)
    func LineProcessor(line string) string {
    	time.Sleep(50 * time.Millisecond) // Simuliere CPU-intensive Arbeit
    	return strings.ToUpper(line)
    }
    
    // ProcessFileWithBackpressure liest eine Datei zeilenweise und verarbeitet mit Backpressure
    func ProcessFileWithBackpressure(ctx context.Context, filename string) error {
    	// abgeleiteten Context mit Timeout für die gesamte Pipeline
    	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    	defer cancel()
    	
    	// Ungepufferte Channels erzwingen Backpressure
    	lines := make(chan string)      // Producer → Processor
    	results := make(chan string)    // Processor → Consumer
    	
    	// Consumer: Ergebnisse speichern (oder ausgeben)
    	go func() {
    		defer close(results)
    		for result := range results {
    			fmt.Println("Gespeichert:", result)
    		}
    	}()
    	
    	// Processor: Zeilen verarbeiten
    	go func() {
    		defer close(results)
    		for line := range lines {
    			select {
    			case <-ctx.Done():
    				return
    			case results <- LineProcessor(line):
    				// Blockiert, wenn results voll ist — Backpressure!
    			}
    		}
    	}()
    	
    	// Producer: Datei zeilenweise lesen
    	file, err := os.Open(filename)
    	if err != nil {
    		return err
    	}
    	defer file.Close()
    	
    	scanner := bufio.NewScanner(file)
    	for scanner.Scan() {
    		select {
    		case <-ctx.Done():
    			return ctx.Err()
    		case lines <- scanner.Text():
    			// Blockiert, wenn lines voll ist — Backpressure propagiert zurück!
    		}
    	}
    	
    	close(lines)
    	return scanner.Err()
    }
    
    // Terminal: Datei erstellen mit echo "Zeile 1\nZeile 2\nZeile 3" > input.txt
    // → go run .
    // → Gespeichert: ZEILE 1
    // → Gespeichert: ZEILE 2
    // → Gespeichert: ZEILE 3
    

    Jetzt die Gefahr: Was passiert, wenn der Consumer die Pipeline vorzeitig verlässt? Dann hängen Producer und Processor-Goroutines für immer, weil sie auf einen Empfänger für ihre Channels warten. Die Lösung: Done-Channels und Select-Statements in jeder Goroutine:

    // internal/pipeline/cancel.go — sicheres Abbrechen einer Pipeline
    package pipeline
    
    import (
    	"context"
    	"fmt"
    )
    
    // SafePipeline zeigt, wie man Goroutines sauber abbricht
    func SafePipeline(ctx context.Context, inputs []int) ([]int, error) {
    	// Channels für die Pipeline
    	squared := make(chan int)
    	cubed := make(chan int)
    	results := make(chan int)
    	
    	// Stage 1: Quadrat berechnen
    	go func() {
    		defer close(squared)
    		for _, n := range inputs {
    			select {
    			case <-ctx.Done():
    				return
    			case squared <- n * n:
    			}
    		}
    	}()
    	
    	// Stage 2: Kubik berechnen
    	go func() {
    		defer close(cubed)
    		for n := range squared {
    			select {
    			case <-ctx.Done():
    				return
    			case cubed <- n * n * n:
    			}
    		}
    	}()
    	
    	// Stage 3: Ergebnisse sammeln
    	go func() {
    		defer close(results)
    		for n := range cubed {
    			select {
    			case <-ctx.Done():
    				return
    			case results <- n:
    			}
    		}
    	}()
    	
    	// Ergebnisse sammeln
    	var output []int
    	for result := range results {
    		output = append(output, result)
    	}
    	
    	return output, ctx.Err()
    }
    
    func CancelExample() {
    	ctx, cancel := context.WithCancel(context.Background())
    	
    	// Pipeline starten
    	results := make(chan []int, 1)
    	go func() {
    		result, _ := SafePipeline(ctx, []int{1, 2, 3, 4, 5})
    		results <- result
    	}()
    	
    	// Nach 100ms abbrechen
    	time.AfterFunc(100*time.Millisecond, cancel)
    	
    	// Auf Ergebnis warten (wird nie kommen, wegen Cancel)
    	select {
    	case result := <-results:
    		fmt.Println("Ergebnis:", result)
    	case <-time.After(200 * time.Millisecond):
    		fmt.Println("Pipeline abgebrochen — kein Goroutine-Leak!")
    	}
    	// → Pipeline abgebrochen — kein Goroutine-Leak!
    }
    
    // Terminal: go run .
    // → Pipeline abgebrochen — kein Goroutine-Leak!
    

    Das kritische Muster: Jede Goroutine in einer Pipeline muss den Context oder ein Done-Signal überwachen. Sonst entsteht ein Goroutine-Leak, das den Speicher langsam auffrisst. Tools wie go test -race finden Datenrennen, aber Goroutine-Leaks bleiben oft unbemerkt — bis der Speicher voll ist.

    ⚠ Häufiger Fehler: In einer mehrstufigen Pipeline nur den Context in der letzten Stage prüfen. Wenn Stage 2 (Processor) den Context ignoriert, aber Stage 3 (Consumer) abbricht, schreibt Stage 2 weiterhin in einen Channel, den niemand mehr liest. Die Goroutine von Stage 1 blockiert am Send zu Stage 2 — alle Goroutines hängen. JEDE Stage muss den Context oder das Done-Signal des upstream Channels prüfen.

    ✅ Wichtige Erkenntnisse

    Haken setzen, um deinen Lernfortschritt zu markieren:

      93

      Kafka in Go: franz-go vs sarama, Batches & Rebalances

      Lektion 93 von 100

      Event-Streaming mit Apache Kafka: Die Go-Optionen

      Apache Kafka ist der De-facto-Standard für verteilte Event-Streaming-Plattformen. In der Buchhandlung könnte Kafka unterschiedlichste Events transportieren: Bestellungen, Lagerbewegungen, Kundennachrichten. Doch Kafka ist komplex — und die Go-Ökosystem bietet zwei Hauptbibliotheken: sarama (github.com/IBM/sarama) und franz-go (github.com/twmb/franz-go). Beide bauen auf der gleichen Kafka-Protokoll-Spezifikation auf, gehen aber unterschiedliche Wege.

      Im Kontext von Event-Sourcing und CQRS ist Kafka oft die zentrale Komponente. Wie Events als Quelle der Wahrheit fungieren, erklärt Modul 11: Event Sourcing & CQRS.

      franz-go: Modularität über Einfachheit

      Während sarama eine monolithische API bietet, ist franz-go in kleine, fokussierte Pakete aufgeteilt: github.com/twmb/franz-go/pkg/kgo für die Core-Funktionalität, github.com/twmb/franz-go/pkg/kmsg für Nachrichten-Dekodierung, etc. Das macht franz-go modulare und leichter, aber mit einer steileren Lernkurve. sarama hingegen bietet eine alles-inklusive API, die für die meisten Anwendungsfälle ausreicht — auf Kosten von Flexibilität.

      Der klassische Weg: sarama als all-in-one-Lösung für Producer und Consumer:

      // internal/kafka/sarama_producer.go — Producer mit sarama
      package kafka
      
      import (
      	"context"
      	"fmt"
      	"log"
      
      	"github.com/IBM/sarama"
      )
      
      // NewSaramaProducer erstellt einen synchronen Producer
      func NewSaramaProducer(brokers []string) (sarama.SyncProducer, error) {
      	config := sarama.NewConfig()
      	config.Producer.Return.Successes = true
      	config.Producer.RequiredAcks = sarama.WaitForAll // stärkste Konsistenz
      	config.Producer.Retry.Max = 3
      	
      	return sarama.NewSyncProducer(brokers, config)
      }
      
      // PublishOrder veröffentlicht eine Bestellung als Kafka-Nachricht
      func PublishOrder(ctx context.Context, producer sarama.SyncProducer, topic string, orderJSON []byte) error {
      	msg := &sarama.ProducerMessage{
      		Topic: topic,
      		Key:   sarama.StringEncoder("order_" + string(orderJSON[:8])), // erste 8 Bytes als Key
      		Value: sarama.ByteEncoder(orderJSON),
      	}
      	
      	// Synchroner Send — blockiert bis Bestätigung da ist
      	partition, offset, err := producer.SendMessage(msg)
      	if err != nil {
      		return fmt.Errorf("Kafka Send fehlgeschlagen: %w", err)
      	}
      	
      	log.Printf("Nachricht gesendet: topic=%s partition=%d offset=%d", topic, partition, offset)
      	return nil
      }
      
      // Terminal: Kafka lokal starten, dann go run .
      // → Nachricht gesendet: topic=orders partition=0 offset=42
      

      Jetzt der Consumer mit sarama — inklusive Consumer-Gruppen und Rebalancing:

      // internal/kafka/sarama_consumer.go — Consumer-Gruppe mit sarama
      package kafka
      
      import (
      	"context"
      	"fmt"
      	"log"
      	"os"
      	"os/signal"
      	"syscall"
      
      	"github.com/IBM/sarama"
      )
      
      // NewSaramaConsumer erstellt einen Consumer in einer Consumer-Gruppe
      func NewSaramaConsumer(brokers []string, groupID string, topics []string) (sarama.ConsumerGroup, error) {
      	config := sarama.NewConfig()
      	config.Consumer.Group.Session.Timeout = 10 * time.Second
      	config.Consumer.Group.Heartbeat.Interval = 3 * time.Second
      	config.Consumer.Offsets.Initial = sarama.OffsetNewest // oder OffsetOldest
      	config.Consumer.Return.Errors = true
      	
      	return sarama.NewConsumerGroup(brokers, groupID, config)
      }
      
      // ConsumeOrders konsumiert Bestellungen aus Kafka
      func ConsumeOrders(ctx context.Context, consumer sarama.ConsumerGroup, topics []string) error {
      	handler := &OrderHandler{}
      	
      	// Consumer-Gruppen müssen committen, sonst gibt es Rebalancing-Schleifen
      	for {
      		if err := consumer.Consume(ctx, topics, handler); err != nil {
      			// Rebalancing ist normal — kein Fehler!
      			if err == sarama.ErrClosedConsumerGroup {
      				return nil
      			}
      			log.Printf("Consumer-Fehler: %v", err)
      		}
      		// Wenn bei einem Error zurückgegeben wurde; kurzes Warten
      		select {
      		case <-ctx.Done():
      			return ctx.Err()
      		case <-time.After(time.Second):
      		}
      	}
      }
      
      type OrderHandler struct{}
      
      func (h *OrderHandler) Setup(sarama.ConsumerGroupSession) error {
      	log.Println("Consumer Setup fertig")
      	return nil
      }
      
      func (h *OrderHandler) Cleanup(sarama.ConsumerGroupSession) error {
      	log.Println("Consumer Cleanup")
      	return nil
      }
      
      func (h *OrderHandler) ConsumeClaim(session sarama.ConsumerGroupSession, claim sarama.ConsumerGroupClaim) error {
      	for message := range claim.Messages() {
      		log.Printf("Empfangen: topic=%s partition=%d offset=%d key=%s value=%s\n",
      			message.Topic, message.Partition, message.Offset, string(message.Key), string(message.Value))
      		
      		// Verarbeitung hier...
      		// Wichtig: Manuell committen, sonst kein Fortschritt!
      		session.MarkMessage(message, "")
      	}
      	return nil
      }
      
      func MainSarama() {
      	ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
      	defer cancel()
      	
      	consumer, err := NewSaramaConsumer([]string{"localhost:9092"}, "bookstore-group", []string{"orders"})
      	if err != nil {
      		log.Fatal(err)
      	}
      	defer consumer.Close()
      	
      	if err := ConsumeOrders(ctx, consumer, []string{"orders"}); err != nil {
      		log.Fatal(err)
      	}
      }
      
      // Terminal: Kafka mit Topic "orders" starten, dann go run .
      // → Consumer Setup fertig
      // → Empfangen: topic=orders partition=0 offset=42 key=order_... value={"id":123...}
      

      Jetzt der moderne Ansatz: franz-go mit mehr Kontrolle und Batching:

      // internal/kafka/franz_producer.go — Producer mit franz-go und Batching
      package kafka
      
      import (
      	"context"
      	"fmt"
      	"log"
      	"time"
      
      	"github.com/twmb/franz-go/pkg/kgo"
      )
      
      // NewFranzProducer erstellt einen franz-go Producer mit Batching
      func NewFranzProducer(brokers []string, topic string) (*kgo.Client, error) {
      	// franz-go verwendet eine funktionale Options-API
      	opts := []kgo.Opt{
      		kgo.SeedBrokers(brokers...),
      		kgo.DefaultProduceTopic(topic),
      		kgo.AllowAutoCreateTopics(),
      		kgo.MaxBufferRecords(1000),         // wie viele Nachrichten im Speicher
      		kgo.BatchMaxBytes(1024 * 1024),     // 1MB pro Batch
      		kgo.BatchMaxMs(100),                // 100ms Warten auf Batch-Füllung
      		kgo.RequiredAcks(kgo.AllISRAcks),    // stärkste Konsistenz
      		kgo.WithLogger(kgo.BasicLogger(log.New(os.Stdout, "franz: ", 0), kgo.LogLevelInfo)),
      	}
      	
      	client, err := kgo.NewClient(opts...)
      	if err != nil {
      		return nil, err
      	}
      	return client, nil
      }
      
      // PublishOrdersBatch veröffentlicht mehrere Bestellungen als Batch
      func PublishOrdersBatch(ctx context.Context, client *kgo.Client, orders [][]byte) error {
      	var records []*kgo.Record
      	for i, orderJSON := range orders {
      		records = append(records, &kgo.Record{
      			Key:   []byte(fmt.Sprintf("order_batch_%d", i)),
      			Value: orderJSON,
      		})
      	}
      	
      	// Asynchroner Send mit Batch-Optimierung
      	client.ProduceSync(ctx, records...)
      	
      	// Warten, bis alle Nachrichten bestätigt sind
      	if err := client.Flush(ctx); err != nil {
      		return err
      	}
      	
      	log.Printf("Batch mit %d Bestellungen gesendet", len(orders))
      	return nil
      }
      
      // Terminal: Kafka starten, dann go run .
      // → franz: Client erstellt
      // → Batch mit 10 Bestellungen gesendet
      

      Ein kritischer Punkt bei Kafka: Rebalancing. Wenn Consumer einer Gruppe hinzugefügt oder entfernt werden, distribuiert Kafka die Partitions neu. Wenn der Consumer den aktuellen Offset nicht committed hat, beginnt er bei der letzte cometten Position — was zu doppelter Verarbeitung führen kann. Die Lösung: manuelles oder automatisches Commit mit der richtigen Strategie:

      // internal/kafka/franz_consumer.go — Consumer mit franz-go und automatischem Commit
      package kafka
      
      import (
      	"context"
      	"fmt"
      	"log"
      	"os"
      	"os/signal"
      	"syscall"
      	"time"
      
      	"github.com/twmb/franz-go/pkg/kgo"
      )
      
      // NewFranzConsumer erstellt einen franz-go Consumer
      func NewFranzConsumer(brokers []string, groupID string, topics []string) (*kgo.Client, error) {
      	opts := []kgo.Opt{
      		kgo.SeedBrokers(brokers...),
      		kgo.ConsumeTopics(topics...),
      		kgo.ConsumerGroup(groupID),
      		kgo.AutoCommitInterval(5 * time.Second), // alle 5s automatisches Commit
      		kgo.OnPartitionsAssigned(func(assigned map[string][]int32) {
      			log.Printf("Partitions zugewiesen: %+v", assigned)
      		}),
      		kgo.OnPartitionsRevoked(func(revoked map[string][]int32) {
      			log.Printf("Partitions entzogen: %+v", revoked)
      			// Hier: aktuellen State speichern, bevor Rebalance abschließt
      		}),
      		kgo.DisableAutoCommit(), // wir committen manuell für mehr Kontrolle
      		kgo.WithLogger(kgo.BasicLogger(log.New(os.Stdout, "franz-consumer: ", 0), kgo.LogLevelInfo)),
      	}
      	
      	return kgo.NewClient(opts...)
      }
      
      func ConsumeWithFranz(ctx context.Context) error {
      	client, err := NewFranzConsumer([]string{"localhost:9092"}, "bookstore-franz-group", []string{"orders"})
      	if err != nil {
      		return err
      	}
      	defer client.Close()
      	
      	for {
      		// Pollen mit 500ms Timeout
      		fetches := client.PollFetches(ctx, 500)
      		if fetches.IsClientClosed() {
      			return nil
      		}
      		
      		// Alle Partitions durchgehen
      		for _, fetch := range fetches {
      			for _, topicPartition := range fetch.TopicPartitions {
      				for _, record := range topicPartition.Records {
      					log.Printf("Empfangen: topic=%s partition=%d offset=%d key=%s value=%s\n",
      						topicPartition.Topic, topicPartition.Partition, record.Offset,
      						string(record.Key), string(record.Value))
      					
      					// Nach erfolgreicher Verarbeitung committen
      					if err := client.CommitRecords(ctx, record); err != nil {
      						log.Printf("Commit fehlgeschlagen: %v", err)
      					}
      				}
      			}
      		}
      	}
      }
      
      func MainFranz() {
      	ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
      	defer cancel()
      	
      	if err := ConsumeWithFranz(ctx); err != nil {
      		log.Fatal(err)
      	}
      }
      
      // Terminal: Kafka mit Topic "orders" starten, dann go run .
      // → franz-consumer: Partitions zugewiesen: map[orders:[0]]
      // → Empfangen: topic=orders partition=0 offset=42 key=... value=...
      

      ⚠ Häufiger Fehler: Bei der Arbeit mit Consumer-Gruppen den Commit vergessen. Kafka weiß dann nicht, welche Nachrichten bereits verarbeitet wurden. Bei einem Rebalancing (z. B. weil ein Consumer neu gestartet wird) beginnt der Consumer bei der letzten committen Position — und verarbeitet alle Nachrichten dazwischen erneut. Bei nicht-idempotenten Operationen (z. B. Geldabbuchung) führt das zu doppelter Ausführung. Lösung: Immer explizit committen (manuell oder automatisch) und Operationen idempotent gestalten.

      ✅ Wichtige Erkenntnisse

      Haken setzen, um deinen Lernfortschritt zu markieren:

        94

        Batch-Inserts, COPY & Transaktions-Chunking mit pgx

        Lektion 94 von 100

        Wenn Einzel-Inserts zum Performance-Killer werden

        Stell dir vor, die Buchhandlung importiert 10.000 neue Bücher aus einer CSV-Datei. Ein Insert pro Buch wäre ineffizient: Jeder Roundtrip zum Datenbankserver kostet Netzwerk-Latenz, jeder Query-Parse kostet CPU, jede Transaktion hat Overhead. Die Lösung: Batch-Operationen. PostgreSQL bietet dafür mehrere Ansätze — und github.com/jackc/pgx/v5 macht sie alle in Go zugänglich.

        Die Datenarchitektur-Entscheidung zwischen Batch und Stream wird in Modul 6: Datenarchitektur behandelt.

        pgx Batch vs. COPY: Wann was verwenden?

        pgx.Batch und pgx.COPY sind beide Batch-Mechanismen, aber für unterschiedliche Szenarien: Batch sendet mehrere SQL-Statements als einzelne Roundtrip und ist perfekt für komplexe Inserts mit Generated Values (Serials, UUIDs). COPY ist das PostgreSQL-Protokoll für Bulk-Datenladen und ist um Größenordnungen schneller — aber nur für einfache Daten ohne Transformationen. Wenn du Daten aus CSV oder JSON lädst, ist COPY erste Wahl.

        Der einfache Einstieg: Batch-Inserts mit pgx.Batch:

        // internal/db/batch.go — Batch-Inserts mit pgx
        package db
        
        import (
        	"context"
        	"fmt"
        	"log"
        
        	"github.com/jackc/pgx/v5"
        	"github.com/jackc/pgx/v5/pgxpool"
        )
        
        // Book bestimmte die Struktur unserer Bücher
        type Book struct {
        	ISBN      string
        	Title     string
        	Author    string
        	PriceCents int64
        	Stock     int32
        }
        
        // BatchInsertBooks fügt mehrere Bücher in einer Transaktion ein
        func BatchInsertBooks(ctx context.Context, pool *pgxpool.Pool, books []Book) error {
        	// Batch erstellen
        	batch := &pgx.Batch{}
        	
        	for _, b := range books {
        		batch.Queue(`INSERT INTO books (isbn, title, author, price_cents, stock) VALUES ($1, $2, $3, $4, $5)`,
        			b.ISBN, b.Title, b.Author, b.PriceCents, b.Stock)
        	}
        	
        	// Alle Statements in einem Roundtrip ausführen
        	br := pool.SendBatch(ctx, batch)
        	defer br.Close()
        	
        	// Ergebnisse verarbeiten
        	for i := 0; i < batch.Len(); i++ {
        		_, err := br.Exec()
        		if err != nil {
        			return fmt.Errorf("Batch-Fehler bei Index %d: %w", i, err)
        		}
        	}
        	
        	log.Printf("Batch-Insert: %d Bücher inserted", len(books))
        	return nil
        }
        
        // Beispielaufruf
        func BatchExample() {
        	ctx := context.Background()
        	pool, _ := pgxpool.New(ctx, "postgres://user:password@localhost:5432/bookstore")
        	defer pool.Close()
        	
        	books := []Book{
        		{ISBN: "978-3-423-2089-8", Title: "Der Alchimist", Author: "Paulo Coelho", PriceCents: 1295, Stock: 10},
        		{ISBN: "978-3-596-52367-0", Title: "Der kleine Prinz", Author: "Antoine de Saint-Exupéry", PriceCents: 999, Stock: 15},
        		{ISBN: "978-3-8419-0658-4", Title: "Faust. Der Tragödie erster Teil", Author: "Johann Wolfgang von Goethe", PriceCents: 799, Stock: 8},
        	}
        	
        	_ = BatchInsertBooks(ctx, pool, books)
        }
        
        // Terminal: Datenbank starten, dann go run .
        // → Batch-Insert: 3 Bücher inserted
        

        Jetzt der Turbo-Modus: COPY für maximale Performance:

        // internal/db/copy.go — COPY für Bulk-Inserts
        package db
        
        import (
        	"bytes"
        	"context"
        	"fmt"
        	"log"
        	"strings"
        
        	"github.com/jackc/pgx/v5/pgxpool"
        )
        
        // CopyBooksFromCSV lädt Bücher aus CSV-Daten mit COPY
        func CopyBooksFromCSV(ctx context.Context, pool *pgxpool.Pool, csvData string) error {
        	// CSV in Zeilen zerlegen
        	lines := strings.Split(csvData, "\n")
        	if len(lines) < 2 {
        		return fmt.Errorf("keine Daten zum Importieren")
        	}
        	
        	// Headerzeile überspringen
        	var buf bytes.Buffer
        	for _, line := range lines[1:] {
        		if line == "" {
        			continue
        		}
        		// CSV-Format: isbn,title,author,price_cents,stock
        		buf.WriteString(line + "\n")
        	}
        	
        	// COPY-Befehl vorbereiten
        	copySQL := `COPY books (isbn, title, author, price_cents, stock) FROM STDIN WITH (FORMAT csv, DELIMITER ',')`
        	
        	// COPY ausführen
        	_, err := pool.CopyFrom(ctx, pgx.Identifier{"books"}, []string{"isbn", "title", "author", "price_cents", "stock"}, &buf)
        	if err != nil {
        		return fmt.Errorf("COPY fehlgeschlagen: %w", err)
        	}
        	
        	log.Printf("COPY: %d Zeilen importiert", len(lines)-1)
        	return nil
        }
        
        func CopyExample() {
        	ctx := context.Background()
        	pool, _ := pgxpool.New(ctx, "postgres://user:password@localhost:5432/bookstore")
        	defer pool.Close()
        	
        	// Beispiel-CSV-Daten
        	csvData := `isbn,title,author,price_cents,stock
        978-3-423-2089-8,Der Alchimist,Paulo Coelho,1295,10
        978-3-596-52367-0,Der kleine Prinz,Antoine de Saint-Exupéry,999,15
        978-3-8419-0658-4,Faust,Johann Wolfgang von Goethe,799,8`
        	
        	_ = CopyBooksFromCSV(ctx, pool, csvData)
        	// → COPY: 3 Zeilen importiert
        }
        
        // Terminal: Datenbank starten, dann go run .
        // → COPY: 3 Zeilen importiert
        

        Das Problem: COPY ist schnell — aber wenn zu viele Daten in einer Transaktion verarbeitet werden, kann die Transaktion zu groß werden und die Datenbank blockieren. Die Lösung: Transaktions-Chunking — große Datensätze in kleinere Batches aufteilen, die jeweils in einer eigenen Transaktion verarbeitet werden:

        // internal/db/chunked.go — Transaktions-Chunking für große Datensätze
        package db
        
        import (
        	"context"
        	"fmt"
        	"log"
        
        	"github.com/jackc/pgx/v5"
        	"github.com/jackc/pgx/v5/pgxpool"
        )
        
        const (
        	BatchSize   = 1000 // Anzahl Records pro Batch
        	MaxRetries  = 3    // Maximale Wiederholungen bei Fehlern
        )
        
        // ChunkedInsertBooks insertiert Bücher in Chunks mit eigenen Transaktionen
        func ChunkedInsertBooks(ctx context.Context, pool *pgxpool.Pool, books []Book) error {
        	for i := 0; i < len(books); i += BatchSize {
        		end := i + BatchSize
        		if end > len(books) {
        			end = len(books)
        		}
        		chunk := books[i:end]
        		
        		for attempt := 0; attempt < MaxRetries; attempt++ {
        			if err := insertChunk(ctx, pool, chunk); err != nil {
        				if attempt == MaxRetries-1 {
        					return fmt.Errorf("Chunk %d-%d fehlgeschlagen: %w", i, end, err)
        				}
        				log.Printf("Wiederhole Chunk %d-%d (Versuch %d)", i, end, attempt+2)
        				select {
        				case <-ctx.Done():
        					return ctx.Err()
        				case <-time.After(time.Second * time.Duration(attempt+1)):
        				}
        			} else {
        				break
        			}
        		}
        	}
        	
        	log.Printf("Chunked-Insert: %d Bücher in %d Chunks insertiert", len(books), (len(books)+BatchSize-1)/BatchSize)
        	return nil
        }
        
        // insertChunk fügt einen Chunk in einer Transaktion ein
        func insertChunk(ctx context.Context, pool *pgxpool.Pool, books []Book) error {
        	tx, err := pool.Begin(ctx)
        	if err != nil {
        		return err
        	}
        	defer tx.Rollback(ctx)
        	
        	batch := &pgx.Batch{}
        	for _, b := range books {
        		batch.Queue(`INSERT INTO books (isbn, title, author, price_cents, stock) VALUES ($1, $2, $3, $4, $5)`,
        			b.ISBN, b.Title, b.Author, b.PriceCents, b.Stock)
        	}
        	
        	br := tx.SendBatch(ctx, batch)
        	defer br.Close()
        	
        	for i := 0; i < batch.Len(); i++ {
        		_, err := br.Exec()
        		if err != nil {
        			return err
        		}
        	}
        	
        	return tx.Commit(ctx)
        }
        
        // Beispiel: 5000 Bücher chunked insertieren
        func ChunkedExample() {
        	ctx := context.Background()
        	pool, _ := pgxpool.New(ctx, "postgres://user:password@localhost:5432/bookstore")
        	defer pool.Close()
        	
        	// 5000 Bücher generieren
        	var books []Book
        	for i := 0; i < 5000; i++ {
        		books = append(books, Book{
        			ISBN:      fmt.Sprintf("978-0-00-%05d-0", i),
        			Title:     fmt.Sprintf("Buch Nummer %d", i),
        			Author:    "Unbekannter Autor",
        			PriceCents: int64(i % 2000 + 500),
        			Stock:     int32(i % 100),
        		})
        	}
        	
        	_ = ChunkedInsertBooks(ctx, pool, books)
        }
        
        // Terminal: Datenbank starten, dann go run .
        // → Chunked-Insert: 5000 Bücher in 5 Chunks insertiert
        

        ⚠ Häufiger Fehler: Batch-Size zu groß wählen. Ein Batch mit 10.000 Records mag in einem lokalen Test schnell sein, aber in Produktion kann das zu verschiedenen Problemen führen: Transaktions-Timeouts, Lock-Contention, Speicherverbrauch auf dem Datenbankserver, oder sogar das Erreichen der maximalen Paketgröße (typischerweise 1GB bei PostgreSQL). Die optimale Batch-Größe hängt von deinen Daten und deiner Infrastruktur ab. Starte mit 100-1000 Records und mess die Performance unter realistischen Bedingungen.

        ✅ Wichtige Erkenntnisse

        Haken setzen, um deinen Lernfortschritt zu markieren:

          95

          Streaming-Embedding-Pipeline: Files → Chunks → Vektoren

          Lektion 95 von 100

          Von rohem Text zu suchbaren Vektoren: Die RAG-Pipeline

          Retrieval Augmented Generation (RAG) ist das Herzstück moderner AI-Anwendungen: Statt das Large Language Model mit dem gesamten Wissen der Welt zu füttern, sucht RAG relevante Dokumente in Echtzeit und reicht sie als Kontext ein. Der Schlüssel dazu: eine Embedding-Pipeline, die Dokumente in Vektoren umwandelt, die dann effizient durchsucht werden können.

          Wie Embedding-Pipelines in AI-Systemen architektonisch eingebettet werden, zeigt der AI-Kurs auf /aiml.

          Embedding-Pipeline: Die drei Phasen

          Eine Embedding-Pipeline durchläuft drei Phasen: 1) Chunking — Dokumente in sinnvolle Abschnitte teilen (z. B. Sätze, Absätze, Code-Blöcke), 2) Embedding — jeden Chunk in einen Vektor umwandeln, 3) Speicherung — die Vektoren in einer Vektordatenbank (z. B. pgvector, Qdrant) ablegen. Die Qualität der Pipeline steht und fällt mit der Chunking-Strategie: Zu große Chunks verlieren Präzision, zu kleine Chunks verlieren Kontext.

          Phase 1: Chunking — Dokumente in sinnvolle Abschnitte teilen:

          // internal/pipeline/chunker.go — Text-Chunking für Embedding-Pipelines
          package pipeline
          
          import (
          	"bufio"
          	"bytes"
          	"context"
          	"io"
          	"strings"
          )
          
          // ChunkSize in Tokens ( Approximation: 1 Token ≈ 4 Zeichen für deutschen Text)
          const ChunkSize = 1000
          const ChunkOverlap = 200 // Überlappung für Kontext-Kontinuität
          
          // TextChunker teilt Text in Chunks mit Überlappung
          func TextChunker(text string, chunkSize, overlap int) []string {
          	tokens := tokenize(text)
          	var chunks []string
          	
          	for i := 0; i < len(tokens); i += chunkSize - overlap {
          		end := i + chunkSize
          		if end > len(tokens) {
          			end = len(tokens)
          		}
          		chunk := strings.Join(tokens[i:end], " ")
          		chunks = append(chunks, chunk)
          	}
          	
          	return chunks
          }
          
          // tokenize ist eine starke Vereinfachung
          // In Produktion: Tokenizer der Embedding-API oder spezialisierte Bibliothek verwenden
          func tokenize(text string) []string {
          	// Vereinfacht: Auf Wörter und Sätze splitten
          	text = strings.ReplaceAll(text, "\n", " ")
          	text = strings.ReplaceAll(text, "\r", " ")
          	
          	// Auf Sätze splitten (grob)
          	sentences := strings.Split(text, ". ")
          	
          	var tokens []string
          	for _, s := range sentences {
          		// Auf Wörter splitten
          		words := strings.Fields(s)
          		tokens = append(tokens, words...)
          	}
          	
          	return tokens
          }
          
          // FileChunker liest Dateien und teilt sie in Chunks
          func FileChunker(ctx context.Context, r io.Reader, chunkSize, overlap int) ([]string, error) {
          	// Ganze Datei lesen (für kleine Dateien)
          	data, err := io.ReadAll(r)
          	if err != nil {
          		return nil, err
          	}
          	
          	// Nach Zeilen splitten (für strukturierte Texte wie Code oder Logs)
          	var lines []string
          	scanner := bufio.NewScanner(bytes.NewReader(data))
          	for scanner.Scan() {
          		lines = append(lines, scanner.Text())
          	}
          	
          	// Leere Zeilen entfernen
          	var nonEmptyLines []string
          	for _, line := range lines {
          		if strings.TrimSpace(line) != "" {
          			nonEmptyLines = append(nonEmptyLines, line)
          		}
          	}
          	
          	// In Chunks gruppieren
          	return LineChunker(nonEmptyLines, chunkSize, overlap), nil
          }
          
          // LineChunker teilt Zeilen in Chunks
          func LineChunker(lines []string, linesPerChunk, overlap int) []string {
          	var chunks []string
          	
          	for i := 0; i < len(lines); i += linesPerChunk - overlap {
          		end := i + linesPerChunk
          		if end > len(lines) {
          			end = len(lines)
          		}
          		chunk := strings.Join(lines[i:end], "\n")
          		chunks = append(chunks, chunk)
          	}
          	
          	return chunks
          }
          
          // Terminal: Datei mit Text erstellen, dann go run .
          // → 3 Chunks erstellt
          

          Phase 2: Embeddings generieren mit der OpenAI-API:

          // internal/pipeline/embedder.go — Embedding-Generierung mit OpenAI
          package pipeline
          
          import (
          	"bytes"
          	"context"
          	"encoding/json"
          	"fmt"
          	"io"
          	"net/http"
          	"time"
          )
          
          // EmbeddingClient entsprechend der OpenAI-API
          const embeddingModel = "text-embedding-3-small"
          const embeddingAPIURL = "https://api.openai.com/v1/embeddings"
          
          // EmbedText generiert ein Embedding für einen Text-Chunk
          func EmbedText(ctx context.Context, apiKey, text string) ([]float32, error) {
          	// Rate Limiting: Maximal 100 Requests pro Minute für text-embedding-3-small
          	time.Sleep(600 * time.Millisecond)
          	
          	request := map[string]interface{}{
          		"input": text,
          		"model": embeddingModel,
          	}
          	
          	jsonData, err := json.Marshal(request)
          	if err != nil {
          		return nil, err
          	}
          	
          	req, err := http.NewRequestWithContext(ctx, "POST", embeddingAPIURL, bytes.NewBuffer(jsonData))
          	if err != nil {
          		return nil, err
          	}
          	
          	req.Header.Set("Content-Type", "application/json")
          	req.Header.Set("Authorization", "Bearer "+apiKey)
          	
          	resp, err := http.DefaultClient.Do(req)
          	if err != nil {
          		return nil, err
          	}
          	defer resp.Body.Close()
          	
          	if resp.StatusCode != http.StatusOK {
          		body, _ := io.ReadAll(resp.Body)
          		return nil, fmt.Errorf("API-Fehler %d: %s", resp.StatusCode, string(body))
          	}
          	
          	var result struct {
          		Data []struct {
          			Embedding []float32 `json:"embedding"`
          		} `json:"data"`
          	}
          	
          	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
          		return nil, err
          	}
          	
          	if len(result.Data) == 0 {
          		return nil, fmt.Errorf("kein Embedding erhalten")
          	}
          	
          	return result.Data[0].Embedding, nil
          }
          
          // BatchEmbed generiert Embeddings für mehrere Chunks
          func BatchEmbed(ctx context.Context, apiKey string, chunks []string) ([][]float32, error) {
          	// OpenAI unterstützt bis zu 2048 Chunks pro Request für text-embedding-3-*
          	const maxBatchSize = 2048
          	
          	var allEmbeddings [][]float32
          	
          	for i := 0; i < len(chunks); i += maxBatchSize {
          		end := i + maxBatchSize
          		if end > len(chunks) {
          			end = len(chunks)
          		}
          		batch := chunks[i:end]
          		
          		request := map[string]interface{}{
          			"input": batch,
          			"model": embeddingModel,
          		}
          		
          		jsonData, err := json.Marshal(request)
          		if err != nil {
          			return nil, err
          		}
          		
          		req, err := http.NewRequestWithContext(ctx, "POST", embeddingAPIURL, bytes.NewBuffer(jsonData))
          		if err != nil {
          			return nil, err
          		}
          		
          		req.Header.Set("Content-Type", "application/json")
          		req.Header.Set("Authorization", "Bearer "+apiKey)
          		
          		resp, err := http.DefaultClient.Do(req)
          		if err != nil {
          			return nil, err
          		}
          		
          		// Rate Limiting
          		time.Sleep(600 * time.Millisecond)
          		
          		defer resp.Body.Close()
          		
          		if resp.StatusCode != http.StatusOK {
          			body, _ := io.ReadAll(resp.Body)
          			return nil, fmt.Errorf("API-Fehler %d: %s", resp.StatusCode, string(body))
          		}
          		
          		var result struct {
          			Data []struct {
          				Embedding []float32 `json:"embedding"`
          			} `json:"data"`
          		}
          		
          		if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
          			return nil, err
          		}
          		
          		for _, d := range result.Data {
          			allEmbeddings = append(allEmbeddings, d.Embedding)
          		}
          	}
          	
          	return allEmbeddings, nil
          }
          
          // Terminal: mit API-Key aufrufen
          // → 3 Embeddings generiert (je 1536 Dimensionen)
          

          Phase 3: Vektoren in pgvector speichern für effiziente Ähnlichkeitsabfragen:

          // internal/pipeline/vectorstore.go — Vektoren in PostgreSQL mit pgvector speichern
          package pipeline
          
          import (
          	"context"
          	"fmt"
          	"log"
          
          	"github.com/jackc/pgx/v5/pgxpool"
          	_ "github.com/pgvector/pgvector-go"
          )
          
          // DocumentChunks enthält Chunks mit ihren Metadaten und Embeddings
          type DocumentChunk struct {
          	FileID    string
          	ChunkIndex int
          	Content   string
          	Embedding []float32
          	Metadata  map[string]string
          }
          
          // StoreChunks speichert Chunks mit Embeddings in der Datenbank
          func StoreChunks(ctx context.Context, pool *pgxpool.Pool, chunks []DocumentChunk) error {
          	// Transaktion für atomaren Insert
          	tx, err := pool.Begin(ctx)
          	if err != nil {
          		return err
          	}
          	defer tx.Rollback(ctx)
          	
          	// Tabelle erstellen (falls nicht existiert)
          	_, err = tx.Exec(ctx, `
          		CREATE TABLE IF NOT EXISTS document_chunks (
          			id SERIAL PRIMARY KEY,
          			file_id TEXT NOT NULL,
          			chunk_index INTEGER NOT NULL,
          			content TEXT NOT NULL,
          			metadata JSONB,
          			embedding vector(1536),
          			created_at TIMESTAMPTZ DEFAULT NOW()
          		)
          	`)
          	if err != nil {
          		return err
          	}
          	
          	// Batch-Insert vorbereiten
          	batch := &pgx.Batch{}
          	for _, chunk := range chunks {
          		batch.Queue(`INSERT INTO document_chunks (file_id, chunk_index, content, metadata, embedding) VALUES ($1, $2, $3, $4, $5)`,
          			chunk.FileID, chunk.ChunkIndex, chunk.Content, chunk.Metadata, chunk.Embedding)
          	}
          	
          	// Ausführen
          	br := tx.SendBatch(ctx, batch)
          	defer br.Close()
          	
          	for i := 0; i < batch.Len(); i++ {
          		_, err := br.Exec()
          		if err != nil {
          			return fmt.Errorf("Batch-Fehler bei Chunk %d: %w", i, err)
          		}
          	}
          	
          	return tx.Commit(ctx)
          }
          
          // SimilaritySearch sucht nach ähnlichen Chunks
          func SimilaritySearch(ctx context.Context, pool *pgxpool.Pool, queryEmbedding []float32, limit int) ([]DocumentChunk, error) {
          	rows, err := pool.Query(ctx, `
          		SELECT file_id, chunk_index, content, metadata
          		FROM document_chunks
          		ORDER BY embedding <=> $1
          		LIMIT $2
          	`, queryEmbedding, limit)
          	if err != nil {
          		return nil, err
          	}
          	defer rows.Close()
          	
          	var results []DocumentChunk
          	for rows.Next() {
          		var chunk DocumentChunk
          		if err := rows.Scan(&chunk.FileID, &chunk.ChunkIndex, &chunk.Content, &chunk.Metadata); err != nil {
          			return nil, err
          		}
          		results = append(results, chunk)
          	}
          	
          	return results, rows.Err()
          }
          
          // Beispiel: Komplette Pipeline von Datei zu Vektoren zu Suche
          func FullPipelineExample() {
          	ctx := context.Background()
          	
          	// 1. Datenbank-Verbindung
          	pool, _ := pgxpool.New(ctx, "postgres://user:password@localhost:5432/vector_db")
          	defer pool.Close()
          	
          	// 2. Datei chunkern
          	fileChunks, _ := FileChunker(ctx, strings.NewReader(`
          Dies ist der erste Absatz des Dokuments.
          
          Dies ist der zweite Absatz mit wichtigen Informationen.
          
          Und dies ist der dritte Absatz mit dem gesuchten Inhalt.
          `), ChunkSize, ChunkOverlap)
          	
          	// 3. Embeddings generieren (mit Mock-API-Key für das Beispiel)
          	// In Produktion: echten API-Key verwenden
          	apiKey := "sk-..."
          	embeddings, _ := BatchEmbed(ctx, apiKey, fileChunks)
          	
          	// 4. Chunks mit Embeddings speichern
          	var chunks []DocumentChunk
          	for i, chunk := range fileChunks {
          		chunks = append(chunks, DocumentChunk{
          			FileID:    "test_document.txt",
          			ChunkIndex: i,
          			Content:   chunk,
          			Embedding: embeddings[i],
          			Metadata: map[string]string{
          				"source": "example",
          				"type":    "text",
          			},
          		})
          	}
          	_ = StoreChunks(ctx, pool, chunks)
          	
          	// 5. Ähnlichkeitssuche
          	query := "wichtige Informationen finden"
          	queryEmbedding, _ := EmbedText(ctx, apiKey, query)
          	results, _ := SimilaritySearch(ctx, pool, queryEmbedding, 3)
          	
          	fmt.Println("Suchergebnisse:")
          	for i, result := range results {
          		fmt.Printf("%d. Chunk %d: %s\n", i+1, result.ChunkIndex, result.Content)
          	}
          }
          
          // Terminal: PostgreSQL mit pgvector-Erweiterung starten, dann go run .
          // → Suchergebnisse:
          // → 1. Chunk 1: Dies ist der zweite Absatz mit wichtigen Informationen.
          // → 2. Chunk 0: Dies ist der erste Absatz des Dokuments.
          // → 3. Chunk 2: Und dies ist der dritte Absatz mit dem gesuchten Inhalt.
          

          Die vollständige Pipeline in einem Stream-Verarbeitungs-Kontext (z. B. für das Verarbeiten vieler Dateien):

          // internal/pipeline/streaming.go — Streaming-Pipeline für viele Dateien
          package pipeline
          
          import (
          	"context"
          	"fmt"
          	"io/fs"
          	"log"
          	"os"
          	"path/filepath"
          	"strings"
          	"sync"
          )
          
          // ProcessDirectory verarbeitet alle Dateien in einem Verzeichnis als Stream
          func ProcessDirectory(ctx context.Context, pool *pgxpool.Pool, apiKey, dirPath string) error {
          	// FileID-Generator
          	fileCounter := 0
          	
          	// Chunks-Kanal für die Pipeline
          	chunks := make(chan DocumentChunk, 100)
          	
          	// Phase 1: Dateien lesen und chunkern (Producer)
          	var wg sync.WaitGroup
          	wg.Add(1)
          	go func() {
          		defer wg.Done()
          		defer close(chunks)
          		
          		if err := filepath.WalkDir(dirPath, func(path string, d fs.DirEntry, err error) error {
          			if err != nil {
          				return err
          			}
          			if d.IsDir() {
          				return nil
          			}
          			
          			// Nur Textdateien verarbeiten
          			if !strings.HasSuffix(path, ".txt") && !strings.HasSuffix(path, ".md") {
          				return nil
          			}
          			
          			fileID := fmt.Sprintf("file_%d", fileCounter)
          			fileCounter++
          			
          			file, err := os.Open(path)
          			if err != nil {
          				return err
          			}
          			defer file.Close()
          			
          			textChunks, err := FileChunker(ctx, file, ChunkSize, ChunkOverlap)
          			if err != nil {
          				return err
          			}
          			
          			for i, chunk := range textChunks {
          				select {
          				case <-ctx.Done():
          					return ctx.Err()
          				case chunks <- DocumentChunk{
          					FileID:    fileID,
          					ChunkIndex: i,
          					Content:   chunk,
          					Metadata: map[string]string{
          						"filename": filepath.Base(path),
          						"path":     path,
          					},
          				}:
          				}
          			}
          			
          			return nil
          		}); err != nil {
          			log.Printf("Fehler beim Verarbeiten von %s: %v", dirPath, err)
          		}
          	}()
          	
          	// Phase 2: Embeddings generieren (Processor)
          	var mu sync.Mutex
          	var allChunks []DocumentChunk
          	
          	const embeddingWorkers = 5
          	var embeddingWg sync.WaitGroup
          	
          	for i := 0; i < embeddingWorkers; i++ {
          		embeddingWg.Add(1)
          		go func(workerID int) {
          			defer embeddingWg.Done()
          			
          			for chunk := range chunks {
          				select {
          				case <-ctx.Done():
          					return
          				default:
          				}
          				
          				// Embedding generieren
          				embedding, err := EmbedText(ctx, apiKey, chunk.Content)
          				if err != nil {
          					log.Printf("Embedding-Fehler für %s:%d: %v", chunk.FileID, chunk.ChunkIndex, err)
          					continue
          				}
          				
          				chunk.Embedding = embedding
          				
          				mu.Lock()
          				allChunks = append(allChunks, chunk)
          				mu.Unlock()
          			}
          		}(i)
          	}
          	
          	// Warten, bis alle Chunks verarbeitet sind
          	wg.Wait()
          	close(chunks)
          	embeddingWg.Wait()
          	
          	// Phase 3: Alle Chunks speichern
          	if err := StoreChunks(ctx, pool, allChunks); err != nil {
          		return err
          	}
          	
          	log.Printf("Verarbeitet: %d Chunks aus %d Dateien", len(allChunks), fileCounter)
          	return nil
          }
          
          // Terminal: Verzeichnis mit Textdateien erstellen, dann go run .
          // → Verarbeitet: 42 Chunks aus 5 Dateien
          

          ⚠ Häufiger Fehler: Die Chunk-Größe nicht an den Anwendungsfall anpassen. Zu kleine Chunks (z. B. einzelne Wörter) verlieren den semantischen Kontext — das Embedding kann den Sinn nicht mehr erfassen. Zu große Chunks (z. B. ganze Bücher) sind zu unspezifisch — die Ähnlichkeitsabfrage findet nichts Präzises. typische Chunk-Größen für RAG: 256-2048 Tokens, je nach Dokumenttyp. Experimentieren ist Pflicht! Auch wichtig: Überlappungen zwischen Chunks (20-50%) helfen, Kontext über Chunk-Grenzen hinweg zu erhalten.

          ✅ Wichtige Erkenntnisse

          Haken setzen, um deinen Lernfortschritt zu markieren:

            This site uses essential cookies for Stripe payments. No tracking cookies.