qdrant-client Python Library

repository·master·Indexed 23 days ago

https://github.com/qdrant/qdrant-client

Official Python client for the Qdrant vector search engine, version 1.18.0. Supports REST and gRPC protocols for high-performance vector search and management. Features include synchronous and asynchronous clients (AsyncQdrantClient), local mode (in-memory or disk), and integration with Qdrant Cloud. Provides capabilities for collection management, vector upserting, filtered searching, and local embedding generation via FastEmbed.

Tokens
16.7K
Snippets
18
Records
119
Agent score
79%

What's inside qdrant-client

  1. Connect to a Qdrant server or Qdrant Cloud

    master

    To connect to a remote Qdrant instance, specify the host/port or the URL.

    Connecting to a local/remote server via REST:

    from qdrant_client import QdrantClient
    
    client = QdrantClient(host="localhost", port=6333)
    # or
    client = QdrantClient(url="http://localhost:6333")

    Connecting to Qdrant Cloud:

    from qdrant_client import QdrantClient
    
    qdrant_client = QdrantClient(
        url="https://xxxxxx-xxxxx-xxxxx-xxxx-xxxxxxxxx.us-east.aws.cloud.qdrant.io:6333",
        api_key="<your-api-key>",
    )

    Running Qdrant locally with Docker:

    docker run -p 6333:6333 qdrant/qdrant:latest
    from qdrant_client import QdrantClient
    
    client = QdrantClient(host="localhost", port=6333)
  2. Set up the Python development environment

    master

    To develop for the qdrant-client, you must set up a specific Python environment using pyenv, virtualenv, and poetry.

    1. Install Python: Use pyenv to install and set the required Python version (e.g., 3.10.10).
    2. Create Virtual Environment: Use virtualenv to isolate dependencies.
    3. Install Dependencies: Use poetry install to manage project dependencies.

    Note: On MacOS, ensure gnu-sed is installed and aliased to sed using brew install gnu-sed.

    # Install Python version
    pyenv install 3.10.10
    pyenv local 3.10.10
    
    # Install specific grpcio versions
    pip install grpcio==1.59.3
    pip install grpcio-tools==1.59.3
    
    # Setup virtual environment
    pip install virtualenv
    virtualenv venv
    source venv/bin/activate
    
    # Install project dependencies
    pip install poetry
    poetry install
  3. Generate client code (REST and gRPC)

    master

    The qdrant-client relies on generated code from OpenAPI and Protobuf definitions. Use the provided shell scripts to regenerate these files. These scripts automatically fetch the necessary definitions from qdrant:dev.

    • REST Client: Generates code from OpenAPI definitions.
    • gRPC Client: Generates code from Protobuf definitions.
  4. Use Remote Inference with Qdrant Cloud

    master

    Qdrant Cloud provides predefined models for inference (available on paid plans). To use them, instantiate the client with cloud_inference=True.

    Note: Remote inference requires images to be provided as base64 encoded strings or URLs.

    from qdrant_client import QdrantClient
    
    client = QdrantClient(
        url="https://xxxxxx-xxxxx-xxxxx-xxxx-xxxxxxxxx.us-east.aws.cloud.qdrant.io:6333",
        api_key="<your-api-key>",
        cloud_inference=True,  # Enable remote inference
    )
    from qdrant_client import QdrantClient
    client = QdrantClient(
        url="https://xxxxxx-xxxxx-xxxx-xxxxxxxxx.us-east.aws.cloud.qdrant.io:6333",
        api_key="<your-api-key>",
        cloud_inference=True,  # Enable remote inference
    )
  5. Run Qdrant in local mode (In-memory or Disk)

    master

    You can run the same API without a running Qdrant server by using local mode. This is ideal for development, prototyping, testing in CI/CD, or running in Jupyter Notebooks.

    • In-memory mode: Data is lost when the process ends.
    • Disk mode: Data is persisted to the specified path.
    from qdrant_client import QdrantClient
    
    # In-memory mode
    client = QdrantClient(":memory:")
    
    # Persistent disk mode
    client = QdrantClient(path="path/to/db")
    from qdrant_client import QdrantClient
    
    client = QdrantClient(":memory:")
    # or
    client = QdrantClient(path="path/to/db")  # Persists changes to disk
  6. Use the Inference API with local FastEmbed

    master

    The Inference API allows you to create embeddings seamlessly. For local inference on CPU, install the fastembed extra:

    pip install qdrant-client[fastembed]

    To enable GPU support (mutually exclusive with fastembed):

    pip install 'qdrant-client[fastembed-gpu]'

    Usage Example: Use models.Document to wrap text and a model name. The client handles embedding generation and uploading.

    from qdrant_client import QdrantClient, models
    
    client = QdrantClient(":memory:")
    model_name = "sentence-transformers/all-MiniLM-L6-v2"
    
    # Prepare documents
    payload = [
        {"document": "Qdrant has Langchain integrations", "source": "Langchain-docs"},
        {"document": "Qdrant also has Llama Index integrations", "source": "LlamaIndex-docs"},
    ]
    docs = [models.Document(text=data["document"], model=model_name) for data in payload]
    ids = [42, 2]
    
    # Create collection with correct vector size
    client.create_collection(
        "demo_collection",
        vectors_config=models.VectorParams(size=client.get_embedding_size(model_name), distance=models.Distance.COSINE)
    )
    
    # Upload documents (embeddings are generated locally)
    client.upload_collection(
        collection_name="demo_collection",
        vectors=docs,
        ids=ids,
        payload=payload,
    )
    
    # Query using a document
    search_result = client.query_points(
        collection_name="demo_collection",
        query=models.Document(text="This is a query document", model=model_name)
    ).points
    from qdrant_client import QdrantClient, models
    
    client = QdrantClient(":memory:")
    
    model_name = "sentence-transformers/all-MiniLM-L6-v2"
    payload = [
        {"document": "Qdrant has Langchain integrations", "source": "Langchain-docs", },
        {"document": "Qdrant also has Llama Index integrations", "source": "LlamaIndex-docs"},
    ]
    docs = [models.Document(text=data["document"], model=model_name) for data in payload]
    ids = [42, 2]
    
    client.create_collection(
        "demo_collection",
        vectors_config=models.VectorParams(
            size=client.get_embedding_size(model_name), distance=models.Distance.COSINE)
    )
    
    client.upload_collection(
        collection_name="demo_collection",
        vectors=docs,
        ids=ids,
        payload=payload,
    )
    
    search_result = client.query_points(
        collection_name="demo_collection",
        query=models.Document(text="This is a query document", model=model_name)
    ).points
    print(search_result)
  7. Configure Read Consistency

    master

    Most search and count methods allow specifying consistency to control how many replicas must respond before a result is returned. Supported values include:

    • int: The specific number of replicas to query.
    • 'majority': Query all replicas, but return values present in the majority.
    • 'quorum': Query the majority of replicas, and return values present in all of them.
    • 'all': Query all replicas, and return values present in all of them.
  8. Integrate FastEmbed with Async Qdrant Client

    master

    The AsyncQdrantFastembedMixin allows an asynchronous Qdrant client to perform local inference using the fastembed library. This enables automatic embedding of text or images before they are sent to the Qdrant server, supporting both dense and sparse vectors.

    When using this mixin, the client manages the lifecycle of embedding models, including downloading, caching, and executing inference locally. It also handles the mapping of embeddings to specific vector field names in your Qdrant collections.

  9. Integrate FastEmbed with Qdrant Client via QdrantFastembedMixin

    master

    The QdrantFastembedMixin allows the Qdrant client to perform local inference using the fastembed library. This enables seamless embedding of text and images directly within the client, facilitating easy document addition and hybrid search (dense + sparse) without managing external embedding services.

    When using this mixin, the client automatically handles model loading, embedding generation, and mapping vectors to the correct collection fields.

  10. Initialize AsyncQdrantClient

    master

    The AsyncQdrantClient is the asynchronous entry point for interacting with Qdrant via REST or gRPC. It can be configured to run in-memory, locally using a persistence path, or connect to a remote Qdrant server or Qdrant Cloud.

    Connection Modes:

    • In-memory: Set location=":memory:".
    • Local (Disk): Set path="/path/to/storage".
    • Remote: Set url="<host>" or use host and port parameters.

    Key Configuration Options:

    • prefer_grpc: If True, uses the gRPC interface for custom methods.
    • api_key: Required for authentication with Qdrant Cloud.
    • https: Set to True to use HTTPS(SSL).
    • timeout: Global timeout for requests (default is 5 seconds).
    • cloud_inference: If True, enables inference of models.Document and other models in Qdrant Cloud.
    • local_inference_batch_size: Batch size for local inference when using fastembed.