> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Qdrant setup

> This guide covers the deployment and configuration of Qdrant, the vector database used by the FlowX AI Platform for knowledge-base embeddings and retrieval.

## Overview

Qdrant is a vector database used by the FlowX AI Platform to store and search the dense and sparse embeddings that power Knowledge Base indexing and retrieval (RAG). It is consumed by the AI Platform services — primarily the `embedder` and `knowledgebase-rag` services.

<Info>
  **Bundled with the AI Platform.** Qdrant is shipped by FlowX as a subchart of the AI Platform Helm chart — it is deployed and version-managed by that chart, not installed separately. Configure it through the `qdrant:` block of your AI Platform values. The version is set by the chart and is not pinned in the FlowX component matrix.
</Info>

<Info>
  For more information about Qdrant, see the [Qdrant documentation](https://qdrant.tech/documentation/).
</Info>

## Prerequisites

<CardGroup cols={2}>
  <Card title="Infrastructure" icon="server">
    * Kubernetes cluster with admin access
    * Persistent storage (block storage) for vector data and snapshots
    * Network connectivity between Qdrant and the AI Platform services
  </Card>

  <Card title="FlowX Integration" icon="puzzle-piece">
    * AI Platform chart deployed (Qdrant is a subchart of it)
    * A Kubernetes secret holding the Qdrant API key
    * AI services configured with the Qdrant connection variables
  </Card>
</CardGroup>

## Deployment

Qdrant is enabled and configured through the `qdrant:` block of the AI Platform Helm values. A typical configuration:

```yaml theme={"system"}
qdrant:
  resources:
    requests:
      cpu: 200m
      memory: 1Gi
    limits:
      cpu: 2
      memory: 2Gi
  config:
    cluster:
      enabled: false
  apiKey:
    valueFrom:
      secretKeyRef:
        name: qdrant-generic
        key: apikey
```

<Info>
  The Qdrant service is exposed inside the cluster as `qdrant-headless` starting with 5.9.2 (`ai-platform-qdrant-headless` on 5.9.0/5.9.1), serving gRPC on port **6334** and the REST/health API on port **6333**. If you reference the Qdrant host explicitly in any service configuration, update it when upgrading to 5.9.2 — see the [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2#ai-platform-service-naming).
</Info>

### API key secret

Qdrant authenticates clients with an API key, supplied through a Kubernetes secret. Create a secret named `qdrant-generic` with an `apikey` entry:

```yaml theme={"system"}
apiVersion: v1
kind: Secret
metadata:
  name: qdrant-generic
type: Opaque
data:
  apikey: <base64-encoded-api-key>
```

<Tip>
  Generate a secure API key with `openssl rand -base64 32` and base64-encode it for the secret.
</Tip>

<Warning>
  The API key in the `qdrant-generic` secret must match the `QDRANT_CONNECTION_API_KEY` configured on the AI Platform services that connect to Qdrant.
</Warning>

### Storage

Provision persistent volumes for Qdrant. Recommended baseline sizes:

| Volume           | Size | Purpose           |
| ---------------- | ---- | ----------------- |
| Qdrant data      | 30Gi | Vector embeddings |
| Qdrant snapshots | 30Gi | Backup snapshots  |

<Warning>
  Size the data volume to your Knowledge Base footprint. Vector storage grows with the number and dimensionality of indexed documents.
</Warning>

## Connecting the AI Platform services

The AI Platform services read the following variables to reach Qdrant. The connection values are set by default in the chart; supply the API key from the `qdrant-generic` secret.

| Variable                          | Description                | Default Value |
| --------------------------------- | -------------------------- | ------------- |
| `QDRANT_CONNECTION_GRPC_ENDPOINT` | Qdrant gRPC endpoint       | —             |
| `QDRANT_CONNECTION_API_KEY`       | Qdrant API key             | —             |
| `QDRANT__CLUSTER__ENABLED`        | Enable Qdrant cluster mode | `true`        |

<Info>
  The `knowledgebases_design` collection is created automatically by the `embedder` service on first use — no manual provisioning step is required.
</Info>

### Search tuning (knowledgebase-rag)

These limits control the fanout of dense and sparse Qdrant queries inside the `knowledgebase-rag` service. Both are read at request time, so changing them does not require a redeploy beyond the env-var rollout.

| Variable                | Description                                                                                                                                            | Default Value |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------- |
| `QDRANT_PREFETCH_LIMIT` | Maximum points returned by each dense/sparse prefetch stage in a hybrid search before fusion. Lower values reduce Qdrant memory pressure on large KBs. | `100`         |
| `QDRANT_FUSION_LIMIT`   | Maximum points returned after RRF fusion (hybrid search) or by a single-stage dense/keyword search. Caps the reranker's input set.                     | `80`          |

<Tip>
  Defaults are tuned for typical Knowledge Bases. Raise them only if recall is insufficient for very large or long-tailed KBs; lower them if you see Qdrant memory pressure or slow queries under filter-heavy workloads.
</Tip>

### Planner seeding

| Variable               | Description                                                                                                                | Default Value |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `PLANNER_SEED_ENABLED` | When `true`, the `planner` service seeds its Qdrant benchmark collection on startup. Leave off unless seeding is required. | `false`       |

## Verification

<Steps>
  <Step title="Check Qdrant pods">
    Ensure the Qdrant pods are running:

    ```bash theme={"system"}
    kubectl get pods -l app.kubernetes.io/name=qdrant
    ```
  </Step>

  <Step title="Test the health endpoint">
    Verify Qdrant is responding on the REST port:

    ```bash theme={"system"}
    kubectl port-forward svc/qdrant-headless 6333:6333   # 5.9.0/5.9.1: svc/ai-platform-qdrant-headless
    # From another terminal
    curl http://localhost:6333/healthz
    ```
  </Step>

  <Step title="Check AI Platform integration">
    Review the embedder logs for a successful Qdrant connection:

    ```bash theme={"system"}
    kubectl logs -l app=embedder | grep -i qdrant   # 5.9.0/5.9.1: -l app=ai-platform-embedder
    ```
  </Step>
</Steps>

<Warning>
  Common connection failures: a missing `QDRANT_CONNECTION_API_KEY`, a key that does not match the `qdrant-generic` secret, or the Qdrant cluster not being fully initialized.
</Warning>

## Related resources

<CardGroup cols={2}>
  <Card title="AI Platform setup" icon="robot" href="/5.9/setup-guides/ai-platform-setup">
    Full AI Platform deployment, including the services that consume Qdrant
  </Card>

  <Card title="Knowledge Base RAG" icon="magnifying-glass" href="/5.9/ai-platform/patterns/knowledge-base-rag">
    How retrieval-augmented generation uses the vector store
  </Card>
</CardGroup>


## Related topics

- [AI Platform setup](/5.9/setup-guides/ai-platform-setup.md)
- [Deployment guidelines v5.9.0](/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9.md)
- [Deployment guidelines v5.9.1](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1.md)
- [Deployment guidelines v5.9.2](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2.md)
- [Deployment guidelines v5.10](/release-notes/v5.x/v5.10.0-july-2026/deployment-guidelines-v5.10.md)