mirror of
https://github.com/qdrant/landing_page.git
synced 2026-09-27 23:18:29 +02:00
100 lines
4.4 KiB
Markdown
100 lines
4.4 KiB
Markdown
---
|
|
title: Async API
|
|
short_description: "Build high-throughput, concurrent applications on Qdrant with the async Python client and ASGI-style web frameworks."
|
|
description: "Tutorial: use Qdrant's async Python API with FastAPI and other ASGI frameworks to build non-blocking, high-throughput vector search applications."
|
|
aliases:
|
|
- /documentation/tutorials/async-api/
|
|
- /documentation/database-tutorials/async-api/
|
|
weight: 4
|
|
goal: Operations
|
|
stack:
|
|
- Python
|
|
---
|
|
|
|
# Build High-Throughput Applications with Qdrant's Async API
|
|
|
|
| Time: 25 min | Level: Intermediate |
|
|
| --- | ----------- |
|
|
|
|
Asynchronous programming is being broadly adopted in the Python ecosystem. Tools such as FastAPI [have embraced this new
|
|
paradigm](https://fastapi.tiangolo.com/async/), but it is also becoming a standard for ML models served as SaaS. For example, the Cohere SDK
|
|
[provides an async client](https://github.com/cohere-ai/cohere-python/blob/856a4c3bd29e7a75fa66154b8ac9fcdf1e0745e0/src/cohere/client.py#L189) next to its synchronous counterpart.
|
|
|
|
Databases are often launched as separate services and are accessed via a network. All the interactions with them are IO-bound and can
|
|
be performed asynchronously so as not to waste time actively waiting for a server response. In Python, this is achieved by
|
|
using [`async/await`](https://docs.python.org/3/library/asyncio-task.html) syntax. That lets the interpreter switch to another task
|
|
while waiting for a response from the server.
|
|
|
|
## When to use async API
|
|
|
|
There is no need to use async API if the application you are writing will never support multiple users at once (e.g it is a script that runs once per day). However, if you are writing a web service that multiple users will use simultaneously, you shouldn't be
|
|
blocking the threads of the web server as it limits the number of concurrent requests it can handle. In this case, you should use
|
|
the async API.
|
|
|
|
Modern web frameworks like [FastAPI](https://fastapi.tiangolo.com/) and [Quart](https://quart.palletsprojects.com/en/latest/) support
|
|
async API out of the box. Mixing asynchronous code with an existing synchronous codebase might be a challenge. The `async/await` syntax
|
|
cannot be used in synchronous functions. On the other hand, calling an IO-bound operation synchronously in async code is considered
|
|
an antipattern. Therefore, if you build an async web service, exposed through an [ASGI](https://asgi.readthedocs.io/en/latest/) server,
|
|
you should use the async API for all the interactions with Qdrant.
|
|
|
|
<aside role="status">
|
|
All the async code has to be launched in an async context. Usually, it means you have to use <code>asyncio.run</code> or <code>asyncio.create_task</code> to run them.
|
|
Please refer to the <a href="https://docs.python.org/3/library/asyncio.html">asyncio documentation</a> for more details.
|
|
</aside>
|
|
|
|
### Using Qdrant asynchronously
|
|
|
|
The simplest way of running asynchronous code is to use define `async` function and use the `asyncio.run` in the following way to run it:
|
|
|
|
```python
|
|
from qdrant_client import models
|
|
|
|
import qdrant_client
|
|
import asyncio
|
|
|
|
|
|
async def main():
|
|
client = qdrant_client.AsyncQdrantClient("localhost")
|
|
|
|
# Create a collection
|
|
await client.create_collection(
|
|
collection_name="my_collection",
|
|
vectors_config=models.VectorParams(size=4, distance=models.Distance.COSINE),
|
|
)
|
|
|
|
# Insert a vector
|
|
await client.upsert(
|
|
collection_name="my_collection",
|
|
points=[
|
|
models.PointStruct(
|
|
id="5c56c793-69f3-4fbf-87e6-c4bf54c28c26",
|
|
payload={
|
|
"color": "red",
|
|
},
|
|
vector=[0.9, 0.1, 0.1, 0.5],
|
|
),
|
|
],
|
|
)
|
|
|
|
# Search for nearest neighbors
|
|
points = await client.query_points(
|
|
collection_name="my_collection",
|
|
query=[0.9, 0.1, 0.1, 0.5],
|
|
limit=2,
|
|
).points
|
|
|
|
# Your async code using AsyncQdrantClient might be put here
|
|
# ...
|
|
|
|
|
|
asyncio.run(main())
|
|
```
|
|
|
|
The `AsyncQdrantClient` provides the same methods as the synchronous counterpart `QdrantClient`. If you already have a synchronous
|
|
codebase, switching to async API is as simple as replacing `QdrantClient` with `AsyncQdrantClient` and adding `await` before each
|
|
method call.
|
|
|
|
<aside role="status">
|
|
Asynchronous client was introduced in <code>qdrant-client</code> version 1.6.1. If you are using an older version, you need to use autogenerated async clients directly.
|
|
</aside>
|