类class agentscope.rag

QdrantStore

class QdrantStore(VectorStoreBase)

源码Source agentscope/rag/_vdb/_qdrant.py:32–521

Qdrant 存储，负责持久化与读取数据。位于 agentscope.rag 包，继承自 VectorStoreBase。核心成员包括 get_client、create_collection、delete_collection、has_collection、insert、delete。

Each knowledge base maps to one Qdrant collection. Every point payload stores the owning document_id plus the serialized :class:~agentscope.rag.Chunk, which is reconstructed on retrieval.

示例Example

# In-memory (tests / prototyping)
store = QdrantStore(location=":memory:")

# Remote server
store = QdrantStore(
    url="http://localhost:6333",
    api_key="...",
)

async with store:
    await store.create_collection("kb-1", dimensions=768)

构造器摘要Constructor Summary

构造器Constructor	说明Description
`def __init__(location: str \| None = None, url: str \| None = None, path: str \| None = None, api_key: str \| None = None,…`	初始化 `QdrantStore` 实例。 Initialize the Qdrant vector store.

方法摘要Method Summary

方法Method	说明Description
`def get_client() -> 'AsyncQdrantClient'`	获取客户端。 Lazily create and cache the async Qdrant client.
`async def __aexit__(exc_type: type[BaseException] \| None, exc_val: BaseException \| None, exc_tb: Any) -> None`async	退出异步上下文并清理资源。 Exit the async context — close the underlying client.
`async def create_collection(name: str, dimensions: int) -> None`async	创建集合。 Create a new Qdrant collection.
`async def delete_collection(name: str) -> None`async	删除集合。 Delete a collection and all its data.
`async def has_collection(name: str) -> bool`async	判断是否具有集合。 Check whether a collection exists.
`async def insert(collection: str, records: list[VectorRecord]) -> None`async	执行插入相关操作。 Insert records into a collection.
`async def delete(collection: str, document_id: str, metadata_filter: dict[str, Any] \| None = None) -> None`async	删除数据。 Delete all records belonging to one source document.
`async def search(collection: str, query_vector: list[float], top_k: int = 5, metadata_filter: dict[str, Any] \| None = N…`async	执行搜索相关操作。 Find the most similar records to a query vector.
`async def list_documents(collection: str, metadata_filter: dict[str, Any] \| None = None) -> list[DocumentSummary]`async	列出文档。 List all distinct source documents indexed in a collection.
`async def list_chunks(collection: str, document_id: str, *, offset: int = 0, limit: int = 30, metadata_filter: dict[str…`async	列出 `list_chunks`。 List one document's chunks ordered by ``chunk_index``.

构造器详情Constructor Detail

QdrantStore

def __init__(location: str | None = None, url: str | None = None, path: str | None = None, api_key: str | None = None, distance: Literal['Cosine', 'Dot', 'Euclid', 'Manhattan'] = 'Cosine', client_kwargs: dict[str, Any] | None = None) -> None

初始化 QdrantStore 实例。

Initialize the Qdrant vector store.

参数Parameters

名称Name	类型Type	说明Description
`location`默认default `None`	str \| None	location（类型 `str \| None`）。Pass `":memory:"` for an ephemeral in-process instance. Mutually exclusive with `url` and `path`.
`url`默认default `None`	str \| None	服务地址（类型 `str \| None`）。The URL of a remote Qdrant server, e.g. `"http://localhost:6333"`.
`path`默认default `None`	str \| None	路径（类型 `str \| None`）。A local directory for an in-process, on-disk instance.
`api_key`默认default `None`	str \| None	API 密钥（类型 `str \| None`）。The API key for Qdrant Cloud or a secured server.
`distance`默认default `'Cosine'`	Literal['Cosine', 'Dot', 'Euclid', 'Manhattan']	distance（类型 `Literal['Cosine', 'Dot', 'Euclid', 'Manhattan']`）。The distance metric used when creating collections.
`client_kwargs`默认default `None`	dict[str, Any] \| None	客户端关键字参数（类型 `dict[str, Any] \| None`）。Extra keyword arguments forwarded to :class:`~qdrant_client.AsyncQdrantClient`.

源码Source agentscope/rag/_vdb/_qdrant.py:59–94

方法详情Method Detail

get_client

def get_client() -> 'AsyncQdrantClient'

获取客户端。

Lazily create and cache the async Qdrant client.

返回Returns 'AsyncQdrantClient'

返回'AsyncQdrantClient'。`AsyncQdrantClient`:

源码Source agentscope/rag/_vdb/_qdrant.py:96–113

aexit

async def __aexit__(exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: Any) -> None

async

退出异步上下文并清理资源。

Exit the async context — close the underlying client.

参数Parameters

名称Name	类型Type	说明Description
`exc_type`	type[BaseException] \| None	exc 类型（类型 `type[BaseException] \| None`）。The exc type.
`exc_val`	BaseException \| None	exc val（类型 `BaseException \| None`）。The exc val.
`exc_tb`	Any	exc tb（类型 `Any`）。The exc tb.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/rag/_vdb/_qdrant.py:115–124

create_collection

async def create_collection(name: str, dimensions: int) -> None

async

创建集合。

No-op if the collection already exists.

参数Parameters

名称Name	类型Type	说明Description
`name`	str	名称（类型 `str`）。The collection name. Typically, the knowledge base ID.
`dimensions`	int	向量维度（类型 `int`）。The fixed vector dimensionality for this collection.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/rag/_vdb/_qdrant.py:130–156

delete_collection

async def delete_collection(name: str) -> None

async

删除集合。

Delete a collection and all its data.

参数Parameters

名称Name	类型Type	说明Description
`name`	str	集合名称到删除。The collection name to delete.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/rag/_vdb/_qdrant.py:158–165

has_collection

async def has_collection(name: str) -> bool

async

判断是否具有集合。

Check whether a collection exists.

参数Parameters

名称Name	类型Type	说明Description
`name`	str	集合名称到检查。The collection name to check.

返回Returns bool

返回布尔值，表示判断结果。`bool`: `True` if the collection exists.

源码Source agentscope/rag/_vdb/_qdrant.py:167–177

insert

async def insert(collection: str, records: list[VectorRecord]) -> None

async

执行插入相关操作。

Each point payload stores the :attr:VectorRecord.document_id under the document_id key and the serialized :class:Chunk under the chunk key, so that :meth:delete can remove all records of one document.

参数Parameters

名称Name	类型Type	说明Description
`collection`	str	目标集合名称。The target collection name.
`records`	list[VectorRecord]	records（类型 `list[VectorRecord]`）。The records to insert (each carrying a :class:`Chunk` and its embedding vector).

返回Returns None

无返回值。No value is returned.

源码Source agentscope/rag/_vdb/_qdrant.py:183–225

delete

async def delete(collection: str, document_id: str, metadata_filter: dict[str, Any] | None = None) -> None

async

删除数据。

Matches the document_id payload key written by :meth:insert from :attr:VectorRecord.document_id.

参数Parameters

名称Name	类型Type	说明Description
`collection`	str	目标集合名称。The target collection name.
`document_id`	str	文档标识（类型 `str`）。The source document ID whose records should be removed.
`metadata_filter`默认default `None`	dict[str, Any] \| None	元数据过滤器（类型 `dict[str, Any] \| None`）。Restrict deletion to records matching every metadata pair in addition to the document ID. `None` disables filtering.

返回Returns None

无返回值。No value is returned.

源码Source agentscope/rag/_vdb/_qdrant.py:247–284

search

async def search(collection: str, query_vector: list[float], top_k: int = 5, metadata_filter: dict[str, Any] | None = None) -> list[VectorSearchResult]

async

执行搜索相关操作。

Find the most similar records to a query vector.

参数Parameters

名称Name	类型Type	说明Description
`collection`	str	集合到搜索。The collection to search.
`query_vector`	list[float]	查询向量化向量。The query embedding vector.
`top_k`默认default `5`	int	返回条数（类型 `int`）。Maximum number of results to return.
`metadata_filter`默认default `None`	dict[str, Any] \| None	元数据过滤器（类型 `dict[str, Any] \| None`）。If provided, restrict the search to records whose `chunk.metadata` matches every `key == value` pair in this dict (translated into a Qdrant `must` payload filter against `chunk.metadata. `).

返回Returns list[VectorSearchResult]

返回VectorSearchResult列表。`list[VectorSearchResult]`:

源码Source agentscope/rag/_vdb/_qdrant.py:290–333

list_documents

async def list_documents(collection: str, metadata_filter: dict[str, Any] | None = None) -> list[DocumentSummary]

async

列出文档。

Scrolls the collection in payload-only mode (vectors disabled) and aggregates by document_id.

参数Parameters

名称Name	类型Type	说明Description
`collection`	str	目标集合名称。The target collection name.
`metadata_filter`默认default `None`	dict[str, Any] \| None	元数据过滤器（类型 `dict[str, Any] \| None`）。If provided, restrict aggregation to records whose `chunk.metadata` matches every `key == value` pair.

返回Returns list[DocumentSummary]

返回DocumentSummary列表。`list[DocumentSummary]`:

源码Source agentscope/rag/_vdb/_qdrant.py:339–393

list_chunks

async def list_chunks(collection: str, document_id: str, *, offset: int = 0, limit: int = 30, metadata_filter: dict[str, Any] | None = None) -> list[Chunk]

async

列出 list_chunks。

Selects the page with a payload range condition offset <= chunk.chunk_index < offset + limit instead of sort-and-skip — Qdrant's scroll has no payload ordering, but because chunk_index is dense the range filter yields exactly the requested page, which is then sorted in Pyt…

参数Parameters

名称Name	类型Type	说明Description
`collection`	str	目标集合名称。The target collection name.
`document_id`	str	文档标识（类型 `str`）。The source document whose chunks should be listed.
`offset`kw默认default `0`	int	偏移量（类型 `int`）。Number of leading chunks to skip.
`limit`kw默认default `30`	int	数量上限（类型 `int`）。Maximum number of chunks to return.
`metadata_filter`kw默认default `None`	dict[str, Any] \| None	元数据过滤器（类型 `dict[str, Any] \| None`）。Extra `chunk.metadata` equality constraints.

返回Returns list[Chunk]

返回分块列表。`list[Chunk]`:

源码Source agentscope/rag/_vdb/_qdrant.py:399–475

继承成员Inherited Members

继承自Inherited from VectorStoreBase

__aenter__