> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-de/rag-and-vektordatenbanken/chromadb.md).

# ChromaDB

ChromaDB ist die **führende Open-Source-Vektordatenbank** speziell für KI-Anwendungen entwickelt. Sie bietet eine einfache, intuitive API zum Speichern, Abfragen und Verwalten hochdimensionaler Embeddings — das Rückgrat moderner RAG-Systeme, semantischer Suche, Empfehlungssysteme und LLM-Speicher.

ChromaDB nimmt die Komplexität der Vektorähnlichkeitssuche ab, sodass Sie sich auf den Aufbau von KI-Anwendungen konzentrieren können. Es unterstützt sowohl einen In-Memory-Modus für die Entwicklung als auch einen persistenten Servermodus für Produktionsbereitstellungen, mit Docker-Unterstützung für eine einfache Bereitstellung auf Clore.ai GPU-Servern.

Wichtige Funktionen:

* 🚀 **Einfache Python/JavaScript-API** — in wenigen Minuten loslegen
* 💾 **Persistenter Speicher** — Daten überleben Container-Neustarts
* 🔍 **Mehrere Distanzmetriken** — Kosinus, L2, Skalarprodukt
* 📦 **Integrierte Embeddings** — eingebaute Unterstützung für OpenAI, Cohere, sentence-transformers
* 🏗️ **Mandantenfähig** — Collections zur Organisation verschiedener Datensätze
* 🔌 **REST-API** — sprachunabhängige HTTP-Schnittstelle
* ⚡ **Schnell** — HNSW-Index für approximative nächstgelegene Nachbarschaftssuche
* 🔗 **LangChain/LlamaIndex-nativ** — erstklassige Integration

{% hint style="success" %}
Alle Beispiele können auf GPU-Servern ausgeführt werden, die über [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

***

## Serveranforderungen

| Parameter      | Minimum                         | Empfohlen                              |
| -------------- | ------------------------------- | -------------------------------------- |
| GPU            | Jede NVIDIA-GPU (optional)      | NVIDIA RTX 3080+ (für Embeddings)      |
| VRAM           | Für ChromaDB nicht erforderlich | 8–16 GB (für lokale Embedding-Modelle) |
| RAM            | 4 GB                            | 16–32 GB                               |
| CPU            | 2 Kerne                         | 8 Kerne                                |
| Festplatte     | 10 GB                           | 50–200 GB (für große Datensätze)       |
| Betriebssystem | Ubuntu 20.04+                   | Ubuntu 22.04                           |
| Docker         | Erforderlich                    | Docker + Docker Compose                |
| Ports          | 22, 8000                        | 22, 8000                               |

{% hint style="info" %}
ChromaDB selbst benötigt keine GPU — es läuft effizient auf der CPU. Allerdings **Erzeugen von Embeddings** (Umwandlung von Text in Vektoren) profitiert stark von GPU-Beschleunigung. Wenn Sie vorhaben, lokale Embedding-Modelle (sentence-transformers etc.) zu verwenden, wählen Sie einen Server mit GPU.
{% endhint %}

***

## Schnelle Bereitstellung auf CLORE.AI

### 1. Finden Sie einen geeigneten Server

Gehe zu [CLORE.AI Marketplace](https://clore.ai/marketplace) und wählen Sie:

* **Nur CPU** für ChromaDB-Server + API (speichern Sie vorab berechnete Embeddings)
* **GPU-Server** wenn Sie Embeddings auch lokal erzeugen möchten

### 2. Konfigurieren Sie Ihre Bereitstellung

**Docker-Image:**

```
chromadb/chroma:latest
```

**Portzuordnungen:**

```
22   → SSH-Zugriff
8000 → ChromaDB HTTP-API
```

**Umgebungsvariablen:**

```
IS_PERSISTENT=TRUE
ANONYMIZED_TELEMETRY=FALSE
CHROMA_SERVER_AUTH_CREDENTIALS_FILE=/chroma/auth.txt
```

**Startbefehl:**

```bash
uvicorn chromadb.app:app --host 0.0.0.0 --port 8000
```

### 3. Testen Sie die Bereitstellung

```bash
curl http://<server-ip>:8000/api/v1/heartbeat
# Erwartet: {"nanosecond heartbeat": <timestamp>}
```

***

## Schritt-für-Schritt-Einrichtung

### Schritt 1: SSH auf Ihren Server

```bash
ssh root@<your-clore-server-ip> -p <ssh-port>
```

### Schritt 2: Erstellen Sie das Datenverzeichnis

```bash
mkdir -p /workspace/chromadb/data
mkdir -p /workspace/chromadb/config
```

### Schritt 3: Starten Sie den ChromaDB-Container

```bash
docker run -d \
  --name chromadb \
  -p 8000:8000 \
  -v /workspace/chromadb/data:/chroma/chroma \
  -e IS_PERSISTENT=TRUE \
  -e ANONYMIZED_TELEMETRY=FALSE \
  -e CHROMA_SERVER_LOG_LEVEL=INFO \
  chromadb/chroma:latest
```

### Schritt 4: Überprüfen Sie, ob er läuft

```bash
# Prüfe Gesundheitszustand
curl http://localhost:8000/api/v1/heartbeat

# Version prüfen
curl http://localhost:8000/api/v1/version

# Collections auflisten
curl http://localhost:8000/api/v1/collections
```

### Schritt 5: Installieren Sie den Python-Client

```bash
pip install chromadb
pip install sentence-transformers  # Für lokale GPU-Embeddings
pip install openai                  # Für OpenAI-Embeddings
```

### Schritt 6: Testen Sie die Konnektivität aus Python

```python
import chromadb

client = chromadb.HttpClient(host="<server-ip>", port=8000)
print(f"ChromaDB version: {client.get_version()}")
print(f"Heartbeat: {client.heartbeat()}")
```

### Schritt 7: (Optional) Authentifizierung aktivieren

```bash
# Auth-Anmeldedaten erstellen
echo "admin:$2y$12$$(openssl rand -hex 16)" > /workspace/chromadb/auth.txt

# Mit aktivierter Auth ausführen
docker run -d \
  --name chromadb-auth \
  -p 8000:8000 \
  -v /workspace/chromadb/data:/chroma/chroma \
  -v /workspace/chromadb/auth.txt:/chroma/auth.txt \
  -e IS_PERSISTENT=TRUE \
  -e CHROMA_SERVER_AUTH_CREDENTIALS_FILE=/chroma/auth.txt \
  -e CHROMA_SERVER_AUTH_CREDENTIALS_PROVIDER=chromadb.auth.providers.HtpasswdFileServerAuthCredentialsProvider \
  -e CHROMA_SERVER_AUTH_PROVIDER=chromadb.auth.basic.BasicAuthServerProvider \
  chromadb/chroma:latest
```

***

## Beispielanwendungen

### Beispiel 1: Grundlegende Vektor-Store-Operationen

```python
import chromadb
from chromadb.utils import embedding_functions

# Verbindung zu ChromaDB auf Clore.ai-Server herstellen
client = chromadb.HttpClient(
    host="<your-clore-server-ip>",
    port=8000
)

# Verwenden Sie sentence-transformers für Embeddings (läuft auf GPU, falls verfügbar)
embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="all-MiniLM-L6-v2"
)

# Erstellen Sie eine Collection
collection = client.get_or_create_collection(
    name="clore_ai_docs",
    embedding_function=embedding_fn,
    metadata={"hnsw:space": "cosine"}  # Distanzmetrik
)

# Dokumente hinzufügen
documents = [
    "Clore.ai ist ein dezentraler GPU-Cloud-Marktplatz für KI-Workloads.",
    "Sie können NVIDIA RTX 4090, A100 und H100 GPUs auf Clore.ai mieten.",
    "Clore.ai unterstützt Docker-basierte Bereitstellungen für jede KI-Framework.",
    "Die Preisgestaltung auf Clore.ai ist im Vergleich zu AWS und GCP wettbewerbsfähig.",
    "Der Clore.ai-Marktplatz verfügt weltweit über Tausende von GPU-Servern.",
    "Sie können PyTorch, TensorFlow, JAX und andere ML-Frameworks bereitstellen.",
    "Clore.ai bietet Spot-Preise für kosteneffizientes GPU-Computing.",
]

ids = [f"doc_{i}" for i in range(len(documents))]

collection.add(
    documents=documents,
    ids=ids,
    metadatas=[{"source": "docs", "index": i} for i in range(len(documents))]
)

print(f"Added {len(documents)} documents to collection")
print(f"Collection size: {collection.count()} documents")
```

***

### Beispiel 2: Semantische Suche

```python
import chromadb
from chromadb.utils import embedding_functions

client = chromadb.HttpClient(host="<server-ip>", port=8000)
embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="all-MiniLM-L6-v2"
)

collection = client.get_collection(
    name="clore_ai_docs",
    embedding_function=embedding_fn
)

# Semantische Suchanfragen
queries = [
    "Wie viel kostet das Mieten einer GPU?",
    "Welche Tools für maschinelles Lernen sind verfügbar?",
    "Erzählen Sie mir etwas über die GPU-Hardwareoptionen",
]

for query in queries:
    results = collection.query(
        query_texts=[query],
        n_results=3,
        include=["documents", "distances", "metadatas"]
    )

    print(f"\n🔍 Query: {query}")
    for i, (doc, dist) in enumerate(zip(
        results["documents"][0],
        results["distances"][0]
    )):
        similarity = 1 - dist  # Distanz in Ähnlichkeit umwandeln
        print(f"  {i+1}. [{similarity:.3f}] {doc[:100]}...")
```

***

### Beispiel 3: RAG-Pipeline mit ChromaDB + OpenAI

```python
import chromadb
from chromadb.utils import embedding_functions
from openai import OpenAI

# Initialisiere Clients
chroma_client = chromadb.HttpClient(host="<server-ip>", port=8000)
openai_client = OpenAI(api_key="dein-openai-api-key")

# Verwenden Sie OpenAI-Embeddings
openai_ef = embedding_functions.OpenAIEmbeddingFunction(
    api_key="your-openai-api-key",
    model_name="text-embedding-3-small"
)

# Collection abrufen
collection = chroma_client.get_or_create_collection(
    name="knowledge_base",
    embedding_function=openai_ef
)

def add_to_knowledge_base(texts, ids=None, metadatas=None):
    """Dokumente zur ChromaDB-Wissensdatenbank hinzufügen."""
    if ids is None:
        ids = [f"doc_{i}" for i in range(len(texts))]
    collection.add(documents=texts, ids=ids, metadatas=metadatas or [{}]*len(texts))
    print(f"✓ Added {len(texts)} documents. Total: {collection.count()}")

def rag_query(question, n_context=5):
    """Relevanten Kontext abrufen und Antwort mit GPT-4 generieren."""
    # 1. Relevante Dokumente abrufen
    results = collection.query(
        query_texts=[question],
        n_results=n_context,
        include=["documents", "distances"]
    )

    context_docs = results["documents"][0]
    distances = results["distances"][0]

    # 2. Kontext-String erstellen
    context = "\n\n".join([
        f"[Quelle {i+1} (Relevanz: {1-d:.2f})]: {doc}"
        for i, (doc, d) in enumerate(zip(context_docs, distances))
    ])

    # 3. Antwort mit LLM generieren
    messages = [
        {
            "role": "system",
            "content": "Sie sind ein hilfreicher Assistent. Beantworten Sie Fragen basierend auf dem bereitgestellten Kontext. Wenn die Antwort nicht im Kontext steht, geben Sie das an."
        },
        {
            "role": "user",
            "content": f"Kontext:\n{context}\n\nFrage: {question}"
        }
    ]

    response = openai_client.chat.completions.create(
        model="gpt-4-turbo",
        messages=messages,
        temperature=0.1
    )

    answer = response.choices[0].message.content

    return {
        "question": question,
        "answer": answer,
        "sources": context_docs,
        "relevance_scores": [1 - d for d in distances]
    }

# Beispielhafte Nutzung
knowledge = [
    "Clore.ai ist ein GPU-Cloud-Marktplatz mit über 45.000 Nutzern.",
    "Clore.ai unterstützt die Bereitstellung von Workloads via Docker.",
    "GPU-Server auf Clore.ai reichen von GTX 1080 bis H100.",
    "Sie können KI-Anwendungen mit SSH-Zugang und benutzerdefinierten Ports bereitstellen.",
]
add_to_knowledge_base(knowledge)

result = rag_query("Wie viele Nutzer hat Clore.ai?")
print(f"Q: {result['question']}")
print(f"A: {result['answer']}")
```

***

### Beispiel 4: Dokumentenverwaltung mit mehreren Collections

```python
import chromadb
from chromadb.utils import embedding_functions

client = chromadb.HttpClient(host="<server-ip>", port=8000)
embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction(
    model_name="all-mpnet-base-v2"  # Höherwertige Embeddings
)

# Erstellen Sie separate Collections für verschiedene Dokumenttypen
collections = {
    "technical_docs": client.get_or_create_collection("technical_docs", embedding_function=embedding_fn),
    "faq": client.get_or_create_collection("faq", embedding_function=embedding_fn),
    "blog_posts": client.get_or_create_collection("blog_posts", embedding_function=embedding_fn),
}

# Fügen Sie Dokumente zu den jeweiligen Collections hinzu
collections["technical_docs"].add(
    documents=["Docker-Bereitungsanleitung für Clore.ai", "SSH-Konfiguration für GPU-Server"],
    ids=["tech_001", "tech_002"],
    metadatas=[{"type": "guide", "version": "v2"}, {"type": "config"}]
)

collections["faq"].add(
    documents=["F: Wie zahle ich? A: Per Kryptowährung.", "F: Welche GPUs? A: RTX bis H100."],
    ids=["faq_001", "faq_002"],
    metadatas=[{"category": "payment"}, {"category": "hardware"}]
)

# Suche über alle Collections
def search_all_collections(query, n_results=2):
    all_results = []
    for name, col in collections.items():
        results = col.query(query_texts=[query], n_results=n_results)
        for doc, dist in zip(results["documents"][0], results["distances"][0]):
            all_results.append({
                "collection": name,
                "document": doc,
                "similarity": 1 - dist
            })

    # Nach Relevanz sortieren
    all_results.sort(key=lambda x: x["similarity"], reverse=True)
    return all_results[:n_results * 2]

results = search_all_collections("Wie deploye ich mit Docker?")
for r in results:
    print(f"[{r['collection']}] ({r['similarity']:.3f}) {r['document'][:80]}...")
```

***

### Beispiel 5: Filterung und Metadaten-Abfragen

```python
import chromadb

client = chromadb.HttpClient(host="<server-ip>", port=8000)
collection = client.get_collection("technical_docs")

# Dokumente mit umfangreichen Metadaten hinzufügen
collection.add(
    documents=[
        "Anleitung: PyTorch auf NVIDIA A100 GPU-Clustern betreiben",
        "Anleitung: TensorFlow verteiltes Training auf RTX 4090",
        "Tutorial: LLM-Finetuning mit LoRA auf GPU",
        "Referenz: CUDA 12.1 Kompatibilitätsmatrix",
        "Anleitung: Docker-Netzwerk für Multi-GPU-Setups",
    ],
    ids=["d1", "d2", "d3", "d4", "d5"],
    metadatas=[
        {"type": "guide", "gpu": "A100", "framework": "pytorch", "year": 2024},
        {"type": "guide", "gpu": "RTX4090", "framework": "tensorflow", "year": 2024},
        {"type": "tutorial", "gpu": "any", "framework": "transformers", "year": 2024},
        {"type": "reference", "gpu": "any", "framework": "cuda", "year": 2023},
        {"type": "guide", "gpu": "multi", "framework": "docker", "year": 2024},
    ]
)

# Abfrage mit Metadatenfilter
results = collection.query(
    query_texts=["GPU-Trainingsanleitung"],
    n_results=3,
    where={"type": "guide"},  # Nur Anleitungen zurückgeben
    include=["documents", "metadatas", "distances"]
)

print("Gefilterte Ergebnisse (type=guide):")
for doc, meta, dist in zip(
    results["documents"][0],
    results["metadatas"][0],
    results["distances"][0]
):
    print(f"  [{1-dist:.3f}] {doc}")
    print(f"    Metadaten: {meta}")
```

***

## Konfiguration

### Docker Compose (Produktion)

```yaml
version: '3.8'

services:
  chromadb:
    image: chromadb/chroma:latest
    container_name: chromadb
    ports:
      - "8000:8000"
    volumes:
      - chromadb_data:/chroma/chroma
    environment:
      - IS_PERSISTENT=TRUE
      - ANONYMIZED_TELEMETRY=FALSE
      - CHROMA_SERVER_LOG_LEVEL=INFO
      - ALLOW_RESET=FALSE
      - CHROMA_SEGMENT_CACHE_POLICY=LRU
      - CHROMA_MEMORY_LIMIT_BYTES=2147483648  # 2 GB Cache
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/heartbeat"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  chromadb_data:
    driver: local
```

### Referenz der Umgebungsvariablen

| Variable                      | Standard | Beschreibung                                      |
| ----------------------------- | -------- | ------------------------------------------------- |
| `IS_PERSISTENT`               | `FALSE`  | Persistenten Speicher aktivieren                  |
| `ANONYMIZED_TELEMETRY`        | `TRUE`   | Nutzungs-Tracking deaktivieren                    |
| `CHROMA_SERVER_LOG_LEVEL`     | `INFO`   | Protokollierungsstufe                             |
| `CHROMA_MEMORY_LIMIT_BYTES`   | Keiner   | Maximaler Speicher für Segment-Cache              |
| `ALLOW_RESET`                 | `FALSE`  | Erlaubt das Zurücksetzen aller Daten über die API |
| `CHROMA_SERVER_AUTH_PROVIDER` | Keiner   | Authentifizierungsanbieter-Klasse                 |

***

## Leistungs-Tipps

### 1. Wählen Sie das richtige Embedding-Modell

| Modell                   | Dimensionen | Geschwindigkeit | Qualität | GPU erforderlich |
| ------------------------ | ----------- | --------------- | -------- | ---------------- |
| `all-MiniLM-L6-v2`       | 384         | Schnell         | Gut      | Nein             |
| `all-mpnet-base-v2`      | 768         | Mittel          | Besser   | Optional         |
| `text-embedding-3-small` | 1536        | Schnell         | Sehr gut | Nur API          |
| `BAAI/bge-large-en-v1.5` | 1024        | Mittel          | Beste    | Ja               |

### 2. Batch-Upserts für Geschwindigkeit

```python
# Fügen Sie in Chargen von 100–1000 hinzu für beste Leistung
BATCH_SIZE = 500

for i in range(0, len(all_documents), BATCH_SIZE):
    batch = all_documents[i:i+BATCH_SIZE]
    collection.add(
        documents=[d["text"] for d in batch],
        ids=[d["id"] for d in batch],
        metadatas=[d["meta"] for d in batch]
    )
    print(f"Batch {i//BATCH_SIZE + 1} done")
```

### 3. HNSW-Index-Tuning

```python
collection = client.create_collection(
    name="optimized",
    metadata={
        "hnsw:space": "cosine",
        "hnsw:construction_ef": 200,  # Höher = bessere Indexqualität (langsamerer Aufbau)
        "hnsw:search_ef": 100,        # Höher = bessere Recall (langsamere Suche)
        "hnsw:M": 32,                 # Höher = besserer Recall (mehr Speicher)
    }
)
```

### 4. Persistenter Client für lokale Nutzung

```python
# Für die Entwicklung direkt auf dem Clore.ai-Server
import chromadb

client = chromadb.PersistentClient(path="/workspace/chromadb/data")
# Kein Server erforderlich, schneller für Single-Process-Nutzung
```

***

## Fehlerbehebung

### Problem: Keine Verbindung zu ChromaDB möglich

```bash
# Überprüfen Sie, ob der Container läuft
docker ps | grep chromadb

# Logs prüfen
docker logs chromadb --tail 20

# Testen Sie aus dem Container heraus
docker exec chromadb curl http://localhost:8000/api/v1/heartbeat
```

### Problem: Daten nach Container-Neustart verloren

```bash
# Stellen Sie sicher, dass das Volume eingebunden ist
docker inspect chromadb | grep Mounts -A 10

# Erneut mit explizitem Volume ausführen
docker run -d -p 8000:8000 \
  -v /workspace/chromadb/data:/chroma/chroma \
  -e IS_PERSISTENT=TRUE \
  chromadb/chroma:latest
```

### Problem: Out-of-Memory-Fehler

```bash
# Speicher-Cache begrenzen
docker run -d -p 8000:8000 \
  -e CHROMA_MEMORY_LIMIT_BYTES=1073741824 \
  -v /workspace/chromadb/data:/chroma/chroma \
  chromadb/chroma:latest
```

### Problem: Langsame Embedding-Erzeugung

```bash
# Überprüfen Sie, ob die GPU für Embeddings verwendet wird
python3 -c "
import torch
from sentence_transformers import SentenceTransformer
model = SentenceTransformer('all-MiniLM-L6-v2', device='cuda')
print(f'Embedding model on: {model.device}')
"
```

### Problem: Collection nach Neustart nicht gefunden

```bash
# Überprüfen Sie, ob Persistenz aktiviert ist
curl http://localhost:8000/api/v1/collections
# Falls leer, wurde IS_PERSISTENT nicht gesetzt oder das Volume nicht gemountet
```

***

## Links

* **GitHub**: <https://github.com/chroma-core/chroma>
* **Offizielle Dokumentation**: <https://docs.trychroma.com>
* **Docker Hub**: <https://hub.docker.com/r/chromadb/chroma>
* **PyPI**: <https://pypi.org/project/chromadb>
* **Discord**: <https://discord.gg/MMeYNTmh3x>
* **CLORE.AI Marketplace**: <https://clore.ai/marketplace>

***

## Clore.ai GPU-Empfehlungen

| Anwendungsfall          | Empfohlene GPU  | Geschätzte Kosten auf Clore.ai |
| ----------------------- | --------------- | ------------------------------ |
| Entwicklung/Tests       | RTX 3090 (24GB) | \~$0.12/gpu/hr                 |
| Produktion RAG          | RTX 3090 (24GB) | \~$0.12/gpu/hr                 |
| Hochdurchsatz-Embedding | RTX 4090 (24GB) | \~$0.70/gpu/hr                 |

> 💡 Alle Beispiele in diesem Leitfaden können bereitgestellt werden auf [Clore.ai](https://clore.ai/marketplace) GPU-Servern. Durchsuchen Sie verfügbare GPUs und mieten Sie stundenweise — keine Verpflichtungen, voller Root-Zugriff.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-de/rag-and-vektordatenbanken/chromadb.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.