Claude Code & ChromaDB: Vector-Datenbanken für KI-Anwendungen

Klassische Datenbanken speichern Fakten. Vector-Datenbanken speichern Bedeutung. Das ist der Unterschied, der moderne KI-Anwendungen erst möglich macht: statt exakter Keyword-Treffer bekommst du semantisch ähnliche Inhalte — auch wenn kein einziges Wort übereinstimmt.

ChromaDB ist die meistgenutzte Open-Source-Lösung für diesen Anwendungsfall. Leichtgewichtig, in Python nativ integrierbar, lokal ausführbar ohne Cloud-Abhängigkeit — und ideal als Wissensspeicher für RAG-Anwendungen (Retrieval-Augmented Generation), die Claude Code oder andere Sprachmodelle mit eigenem Kontext ausstatten.

Dieser Artikel zeigt, wie du ChromaDB von Grund auf verstehst und produktiv einsetzt: von der ersten Collection bis zur vollständigen RAG-Pipeline.

1. Was ist ChromaDB?

ChromaDB ist eine eingebettete Vector-Datenbank, die speziell für KI-Anwendungen entwickelt wurde. Sie speichert keine klassischen Zeilen und Spalten, sondern hochdimensionale Vektoren — numerische Repräsentationen von Text, Bildern oder anderen Daten, die semantische Ähnlichkeit messbar machen.

Der entscheidende Unterschied zu einer SQL-Datenbank: Wenn du nach "Auto kaufen" suchst, findet ChromaDB auch Dokumente, die "Fahrzeug erwerben" oder "PKW-Kauf" enthalten — weil diese Begriffe im Vektorraum nahe beieinander liegen. Eine SQL-Suche mit LIKE '%Auto%' würde diese Treffer verpassen.

• Open Source: vollständig kostenlos, kein Cloud-Zwang
• Eingebettet: läuft direkt im Python-Prozess, kein separater Server nötig
• Persistent: Daten optional auf Disk gespeichert, überstehen Neustarts
• LangChain-kompatibel: direkte Integration ohne Adapter-Code

Installation ist ein einzelner Befehl:

pip install chromadb

2. Das Embeddings-Konzept verstehen

Bevor ChromaDB etwas suchen kann, muss Text in Vektoren umgewandelt werden. Diese Vektoren heißen Embeddings: Listen von Zahlen (typischerweise 384 bis 1536 Dimensionen), die die semantische Bedeutung eines Textes kodieren.

Ein einfaches Beispiel: Die Sätze "Der Hund bellt" und "Das Tier macht Lärm" haben fast identische Embedding-Vektoren — obwohl sie kein gemeinsames Wort teilen. "Die Aktie stieg" liegt dagegen im Vektorraum weit entfernt.

Embeddings machen aus dem unstrukturierten Text eines Dokuments eine Koordinate im semantischen Raum. Ähnliche Bedeutung = ähnliche Koordinaten = kurze Distanz im Vektorraum.

ChromaDB kann Embeddings selbst berechnen (mit eingebettetem Sentence-Transformers-Modell) oder externe Embedding-Funktionen verwenden. Für den Einstieg funktioniert das Standard-Modell ohne weitere Konfiguration.

3. Collections erstellen und Dokumente hinzufügen

ChromaDB organisiert Daten in Collections — vergleichbar mit Tabellen in SQL, aber ohne festes Schema. Jede Collection speichert Dokumente zusammen mit ihren Embedding-Vektoren und optionalen Metadaten.

import chromadb

# Client erstellen (in-memory für Entwicklung)
client = chromadb.Client()

# Collection anlegen
collection = client.create_collection(name="dokumentation")

# Dokumente hinzufügen
collection.add(
    documents=[
        "Claude Code ist ein KI-gestützter Code-Editor von Anthropic.",
        "ChromaDB speichert Embeddings für semantische Suche.",
        "RAG kombiniert Sprachmodelle mit externem Wissen.",
        "Vector-Datenbanken messen Ähnlichkeit über Kosinusdistanz.",
    ],
    ids=["doc1", "doc2", "doc3", "doc4"]
)

ChromaDB berechnet die Embeddings automatisch beim Hinzufügen. Die ids müssen eindeutig sein und ermöglichen späteres Abrufen oder Löschen einzelner Dokumente.

4. Similarity-Search: Semantisch ähnliche Dokumente finden

Die Kernfunktion von ChromaDB ist die Ähnlichkeitssuche. Du übergibst einen Query-Text, ChromaDB berechnet dessen Embedding, und findet die Dokumente im Vektorraum, die am nächsten liegen.

# Semantische Suche
results = collection.query(
    query_texts=["Was ist ein KI-Editor?"],
    n_results=2
)

print(results["documents"])
# [['Claude Code ist ein KI-gestützter Code-Editor von Anthropic.',
#   'RAG kombiniert Sprachmodelle mit externem Wissen.']]

print(results["distances"])
# [[0.23, 0.61]]  — kleinere Zahl = ähnlicher

Das Ergebnis ist nach Ähnlichkeit sortiert: das erste Dokument ist das semantisch relevanteste. Die Distanz von 0.23 zeigt eine hohe Übereinstimmung — obwohl der Query "KI-Editor" und das Dokument "Code-Editor" verschiedene Formulierungen verwenden.

5. Metadata-Filtering: Suche eingrenzen

Semantische Suche allein reicht oft nicht aus. In realen Anwendungen willst du zusätzlich nach strukturierten Eigenschaften filtern: Dokument-Typ, Datum, Autor, Kategorie. ChromaDB unterstützt Metadata-Filter, die mit der Vektorsuche kombiniert werden.

# Dokumente mit Metadaten hinzufügen
collection.add(
    documents=[
        "Python ist eine interpretierte Programmiersprache.",
        "TypeScript erweitert JavaScript um statische Typen.",
        "Rust bietet Speichersicherheit ohne Garbage Collector.",
    ],
    metadatas=[
        {"sprache": "Python", "typ": "tutorial", "jahr": 2026},
        {"sprache": "TypeScript", "typ": "tutorial", "jahr": 2026},
        {"sprache": "Rust", "typ": "referenz", "jahr": 2025},
    ],
    ids=["lang1", "lang2", "lang3"]
)

# Nur Tutorial-Dokumente durchsuchen
results = collection.query(
    query_texts=["typsichere Programmierung"],
    n_results=2,
    where={"typ": "tutorial"}
)

Der where-Filter akzeptiert auch komplexere Bedingungen mit $and, $or, $gt, $lt — vergleichbar mit MongoDB-Query-Syntax. So lassen sich Suchen auf bestimmte Zeiträume, Kategorien oder Quellen eingrenzen, ohne die semantische Qualität zu verlieren.

6. Persistent Storage: Daten über Neustarts hinweg

Standardmäßig ist ChromaDB in-memory — alle Daten verschwinden beim Beenden des Prozesses. Für Produktionsanwendungen brauchst du persistenten Storage, der Embeddings auf Disk speichert.

import chromadb

# Persistenter Client mit Verzeichnispfad
client = chromadb.PersistentClient(path="./chroma_data")

# Ab hier werden alle Operationen auf Disk gespeichert
collection = client.get_or_create_collection(name="wissensbasis")

# Daten überleben Prozess-Neustarts
collection.add(
    documents=["Wichtige Information, die erhalten bleiben soll."],
    ids=["permanent1"]
)

get_or_create_collection ist der produktionstaugliche Ansatz: wenn die Collection bereits existiert, wird sie geladen; wenn nicht, wird sie neu erstellt. So verhindert man doppelte Initialisierungen beim Neustart.

7. LangChain-Integration

LangChain hat eine direkte ChromaDB-Integration, die den Aufbau von RAG-Pipelines erheblich vereinfacht. Statt Embeddings und Queries manuell zu verwalten, übernimmt LangChain die Orchestrierung.

import os
from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings
from langchain.text_splitter import RecursiveCharacterTextSplitter

# API-Key sicher aus Umgebungsvariable laden
embeddings = OpenAIEmbeddings(
    api_key=os.environ["OPENAI_API_KEY"]
)

# Text aufteilen
splitter = RecursiveCharacterTextSplitter(
    chunk_size=500,
    chunk_overlap=50
)
chunks = splitter.split_text(langer_dokumenttext)

# ChromaDB über LangChain befüllen
vectorstore = Chroma.from_texts(
    texts=chunks,
    embedding=embeddings,
    persist_directory="./chroma_langchain"
)

# Als Retriever nutzen
retriever = vectorstore.as_retriever(
    search_kwargs={"k": 3}
)

Der RecursiveCharacterTextSplitter teilt lange Texte in überlappende Chunks auf — das Overlap von 50 Zeichen sorgt dafür, dass semantische Grenzen nicht mitten in einem relevanten Satz liegen.

8. Eine vollständige RAG-Anwendung bauen

Retrieval-Augmented Generation (RAG) ist das Architekturmuster, das ChromaDB zum Kern-Baustein moderner KI-Anwendungen macht. Statt ein Sprachmodell auf eigenes Wissen zu beschränken, reichert RAG jeden Prompt mit relevanten Dokumenten aus der Wissensbasis an.

import os
import chromadb
from anthropic import Anthropic

# ChromaDB-Client und Collection
chroma_client = chromadb.PersistentClient(path="./rag_data")
collection = chroma_client.get_or_create_collection("wissensbasis")

# Anthropic-Client (API-Key aus Umgebungsvariable)
anthropic = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

def rag_query(frage: str, n_docs: int = 3) -> str:
    # 1. Relevante Dokumente aus ChromaDB abrufen
    results = collection.query(
        query_texts=[frage],
        n_results=n_docs
    )
    kontext = "\n\n".join(results["documents"][0])

    # 2. Prompt mit Kontext anreichern
    prompt = f"""Beantworte die folgende Frage ausschließlich
auf Basis der bereitgestellten Dokumente.

Dokumente:
{kontext}

Frage: {frage}"""

    # 3. Sprachmodell aufrufen
    antwort = anthropic.messages.create(
        model="claude-opus-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}]
    )
    return antwort.content[0].text

# Nutzung
print(rag_query("Wie funktioniert persistenter Storage in ChromaDB?"))

Diese drei Schritte — Dokumente abrufen, Prompt anreichern, Modell aufrufen — sind das Grundprinzip jeder RAG-Anwendung. Was sich zwischen Projekten unterscheidet, ist die Qualität der Chunking-Strategie, die Anzahl abgerufener Dokumente und das Prompt-Design.

Claude Code hilft dabei, genau diese Parameter zu optimieren: du beschreibst deine Qualitätsprobleme (falsche Treffer, zu kurze Antworten, fehlende Informationen), und Claude Code analysiert die ChromaDB-Queries, das Chunking und den Prompt — und schlägt konkrete Verbesserungen vor.

Verwandte Artikel, die auf diesem Wissen aufbauen:

• Claude Code & LangChain — Chains, Agents und Memory für komplexere KI-Workflows
• Claude Code für Python-Projekte — Projektstruktur, Testing und Deployment-Workflows