qdrant/docs/DEVELOPMENT.md

Developer's guide to Qdrant

Build Qdrant

Docker 🐳

Build your own from source

docker build . --tag=qdrant/qdrant

Or use latest pre-built image from DockerHub

docker pull qdrant/qdrant

To run the container, use the command:

docker run -p 6333:6333 qdrant/qdrant

And once you need a fine-grained setup, you can also define a storage path and custom configuration:

docker run -p 6333:6333 \
    -v $(pwd)/path/to/data:/qdrant/storage \
    -v $(pwd)/path/to/custom_config.yaml:/qdrant/config/production.yaml \
    qdrant/qdrant

• /qdrant/storage - is a place where Qdrant persists all your data. Make sure to mount it as a volume, otherwise docker will drop it with the container.
• /qdrant/config/production.yaml - is the file with engine configuration. You can override any value from the reference config

Now Qdrant should be accessible at localhost:6333.

Local development

Linux/Debian

To run Qdrant on local development environment you need to install below:

• Install Rust, follow: install rust
• Install rustfmt toolchain for Rust

  rustup component add rustfmt
  

• Install dependencies:

  sudo apt-get update -y 
  sudo apt-get upgrade -y
  sudo apt-get install -y curl unzip gcc-multilib \
      clang cmake jq \
      g++-9-aarch64-linux-gnu \
      gcc-9-aarch64-linux-gnu
  

• Install protoc from source

  PROTOC_VERSION=22.2
  
  # curl `proto` source file 
  curl -LO https://github.com/protocolbuffers/protobuf/releases//download/v$PROTOC_VERSION/protoc-$PROTOC_VERSION-linux-x86_64.zip
  
  unzip protoc-$PROTOC_VERSION-linux-x86_64.zip -d $HOME/.local
  
  export PATH="$PATH:$HOME/.local/bin"
  
  # remove source file if not needed
  rm protoc-$PROTOC_VERSION-linux-x86_64.zip
  
  # check insalled `protoc` version
  protoc --version
  

• Build and run the app

  cargo build --release --bin qdrant
  
  ./target/release/qdrant
  

Profiling

There are several benchmarks implemented in Qdrant. Benchmarks are not included in CI/CD and might take some time to execute. So the expected approach to benchmarking is to run only ones which might be affected by your changes.

To run benchmark, use the following command inside a related sub-crate:

cargo bench --bench name_of_banchmark

In this case you will see the execution timings and, if you launched this bench earlier, the difference in execution time.

Example output:

scoring-vector/basic-score-point                                                                            
                        time:   [111.81 us 112.07 us 112.31 us]
                        change: [+19.567% +20.454% +21.404%] (p = 0.00 < 0.05)
                        Performance has regressed.
Found 9 outliers among 100 measurements (9.00%)
  3 (3.00%) low severe
  3 (3.00%) low mild
  2 (2.00%) high mild
  1 (1.00%) high severe
scoring-vector/basic-score-point-10x                                                                            
                        time:   [111.86 us 112.44 us 113.04 us]
                        change: [-1.6120% -0.5554% +0.5103%] (p = 0.32 > 0.05)
                        No change in performance detected.
Found 1 outliers among 100 measurements (1.00%)
  1 (1.00%) high mild

FlameGraph and call-graph visualisation

To run benchmarks with profiler to generate FlameGraph - use the following command:

cargo bench --bench name_of_banchmark -- --profile-time=60

This command will run each benchmark iterator for 60 seconds and generate FlameGraph svg along with profiling records files. These records could later be used to generate visualisation of the call-graph.

Use pprof and the following command to generate svg with a call graph:

~/go/bin/pprof -output=profile.svg -svg ${qdrant_root}/target/criterion/${benchmark_name}/${function_name}/profile/profile.pb

API changes

REST

Qdrant uses the openapi specification to document its API.

This means changes to the API must be followed by changes to the specification. This is enforced by CI.

Here is a quick step-by-step guide:

1. code endpoints and model in Rust
2. change specs in /openapi/*ytt.yaml
3. add new schema definitions to src/schema_generator.rs
4. run /tools/generate_openapi_models.sh to generate specs
5. update integration tests openapi/tests/openapi_integration and run them with ./tests/openapi_integration_test.sh
6. expose file by starting an HTTP server, for instance python -m http.server, in /docs/redoc
7. validate specs by browsing redoc on http://localhost:8000/?v=master
8. validate openapi-merged.yaml using swagger editor

gRPC

Qdrant uses tonic to serve gRPC traffic.

Our protocol buffers are defined in lib/api/src/grpc/proto/*.proto

1. define request and response types using protocol buffers (use oneOf for enums payloads)
2. specify RPC methods inside the service definition using protocol buffers
3. cargo build will generate the struct definitions and a service trait
4. implement the service trait in Rust
5. start server cargo run --bin qdrant
6. run integration test ./tests/basic_grpc_test.sh
7. generate docs ./tools/generate_grpc_docs.sh

Here is a good tonic tutorial for reference.