Weaviate Patterns

Patterns canoniques pour utiliser Weaviate — particulièrement quand le besoin est hybrid retrieval BM25 + vector natif.

1. Setup

Self-hosted via Docker

# docker-compose.yml
version: '3.4'
services:
  weaviate:
    image: cr.weaviate.io/semitechnologies/weaviate:1.27.0
    ports:
      - "8080:8080"
      - "50051:50051"
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'false'
      AUTHENTICATION_APIKEY_ENABLED: 'true'
      AUTHENTICATION_APIKEY_ALLOWED_KEYS: 'mykey'
      AUTHENTICATION_APIKEY_USERS: 'admin@example.com'
      PERSISTENCE_DATA_PATH: '/var/lib/weaviate'
      ENABLE_MODULES: 'text2vec-openai,generative-openai,backup-s3'
      DEFAULT_VECTORIZER_MODULE: 'text2vec-openai'
      OPENAI_APIKEY: ${OPENAI_API_KEY}
    volumes:
      - weaviate_data:/var/lib/weaviate

volumes:
  weaviate_data:

Weaviate Cloud Services (managed)

import weaviate

client = weaviate.connect_to_weaviate_cloud(
    cluster_url="https://your-cluster.weaviate.network",
    auth_credentials=weaviate.auth.AuthApiKey("YOUR_API_KEY"),
    headers={"X-OpenAI-Api-Key": os.environ["OPENAI_API_KEY"]},
)

2. Schema definition

import weaviate.classes.config as wvc

client.collections.create(
    name="Document",
    description="Tech documentation chunks",
    vectorizer_config=wvc.Configure.Vectorizer.text2vec_openai(
        model="text-embedding-3-large",
    ),
    generative_config=wvc.Configure.Generative.openai(model="gpt-5"),
    properties=[
        wvc.Property(name="title", data_type=wvc.DataType.TEXT),
        wvc.Property(name="content", data_type=wvc.DataType.TEXT),
        wvc.Property(name="source", data_type=wvc.DataType.TEXT, skip_vectorization=True),
        wvc.Property(name="page", data_type=wvc.DataType.INT),
        wvc.Property(name="published_at", data_type=wvc.DataType.DATE),
        wvc.Property(name="tags", data_type=wvc.DataType.TEXT_ARRAY),
    ],
)

3. Insert (with auto-vectorization)

collection = client.collections.get("Document")

with collection.batch.dynamic() as batch:
    for doc in documents:
        batch.add_object(
            properties={
                "title": doc.title,
                "content": doc.content,
                "source": doc.source,
                "page": doc.page,
            },
            # Pas besoin de vector — Weaviate appelle text2vec-openai automatiquement
        )

4. Hybrid search (BM25 + vector RRF natif)

results = collection.query.hybrid(
    query="Comment configurer Postgres ?",
    alpha=0.5,  # 0=pure BM25, 1=pure vector, 0.5=50/50
    limit=10,
    return_metadata=wvc.MetadataQuery(score=True, explain_score=True),
)

for r in results.objects:
    print(f"{r.metadata.score:.3f} - {r.properties['title']}")

C'est la killer feature de Weaviate — hybrid retrieval est natif, fusionné en interne, pas un workaround côté client.

5. Generative search (RAG en 1 query)

# Query qui fait retrieval + generation en 1 appel
result = collection.generate.near_text(
    query="Comment configurer Postgres ?",
    limit=5,
    grouped_task="Réponds en français en citant les sources",
)

print(result.generated)  # Réponse LLM générée
for obj in result.objects:
    print(f"  Source: {obj.properties['source']}")

Pas besoin d'orchestrer retrieval + LLM côté client — Weaviate gère le pipeline.

6. Multi-tenancy

# Activate multi-tenancy à la création
client.collections.create(
    name="TenantDocs",
    multi_tenancy_config=wvc.Configure.multi_tenancy(enabled=True),
    # ... properties ...
)

# Add tenants
collection = client.collections.get("TenantDocs")
collection.tenants.create([wvc.Tenant(name="acme-corp"), wvc.Tenant(name="globex")])

# Insert into a tenant
acme_collection = collection.with_tenant("acme-corp")
acme_collection.data.insert(properties={"title": "Acme private doc", "content": "..."})

# Search a tenant (impossible to leak cross-tenant)
results = acme_collection.query.hybrid(query="...", limit=5)

7. Named vectors (multi-perspective)

client.collections.create(
    name="Product",
    vectorizer_config=[
        wvc.Configure.NamedVectors.text2vec_openai(name="title_vector", source_properties=["title"]),
        wvc.Configure.NamedVectors.text2vec_openai(name="description_vector", source_properties=["description"]),
        wvc.Configure.NamedVectors.text2vec_cohere(name="multilingual_vector", source_properties=["title", "description"]),
    ],
    properties=[
        wvc.Property(name="title", data_type=wvc.DataType.TEXT),
        wvc.Property(name="description", data_type=wvc.DataType.TEXT),
    ],
)

# Search par vector spécifique
results = collection.query.near_text(
    query="laptop powerful",
    target_vector="title_vector",
    limit=5,
)

Use case : produits e-commerce avec multiple "perspectives" (title vs description vs reviews).

8. Cross-references (graph-like)

# Schema avec references
client.collections.create(name="Author", properties=[
    wvc.Property(name="name", data_type=wvc.DataType.TEXT),
])

client.collections.create(
    name="Article",
    properties=[
        wvc.Property(name="title", data_type=wvc.DataType.TEXT),
        wvc.Property(name="content", data_type=wvc.DataType.TEXT),
    ],
    references=[
        wvc.ReferenceProperty(name="author", target_collection="Author"),
    ],
)

# Query qui fetch les references (graph-like)
articles = client.collections.get("Article").query.fetch_objects(
    return_references=wvc.QueryReference(link_on="author", return_properties=["name"]),
)
for a in articles.objects:
    print(f"{a.properties['title']} by {a.references['author'].objects[0].properties['name']}")

9. Backup + restore

# Backup vers S3 (configuré dans le module backup-s3)
client.backup.create(
    backup_id="my-backup-2026-04-08",
    backend="s3",
    include_collections=["Document", "Product"],
    wait_for_completion=True,
)

# Restore
client.backup.restore(
    backup_id="my-backup-2026-04-08",
    backend="s3",
    wait_for_completion=True,
)

10. Anti-patterns

1. Pas d'auth API key en self-hosted prod — accès anonyme
2. Tout dans 1 collection au lieu de multi-tenancy — fuites possibles
3. Pas d'OpenAI/Cohere API key dans env mais module activé — erreurs runtime
4. Pas de batch insert pour gros volumes — slow
5. alpha=1.0 (pure vector) sans réfléchir — perd le bénéfice hybrid
6. Schema sans skip_vectorization sur les fields techniques (id, source, date) — embeddings pollués
7. Pas de backup — perte de données catastrophique
8. Self-hosted single node en prod — pas de HA
9. Generative module sans rate limit — coûts LLM non contrôlés

Checklist

• Auth activée (API key ou OIDC)
• Schema défini avec types corrects
• skip_vectorization sur fields non-textuels
• Hybrid search alpha tuned (commencer 0.5)
• Multi-tenancy activé si SaaS
• Backup vers S3/GCS configuré
• HA cluster si prod (3 nodes minimum)
• Monitoring queries/sec + latency
• Tests RAGAS sur la qualité retrieval

Quand déléguer

• Architecture RAG → agent rag-architect (ce plugin)
• Pinecone managed → skill pinecone-patterns (ce plugin)
• Qdrant performance max → skill qdrant-patterns (ce plugin)
• pgvector simple → skill supabase-patterns (atum-stack-backend)

Ressources

• https://weaviate.io/developers/weaviate
• https://weaviate.io/developers/weaviate/concepts/hybrid-search
• https://github.com/weaviate/weaviate