Qdrant

The Qdrant resource mounts a Qdrant collection as a filesystem: group-by payload fields become folders, points become files, and semantic search is the search command. See Qdrant Resource for the full layout and command list.

Dependencies

uv add 'mirage-ai[qdrant]'

The qdrant extra installs qdrant-client[fastembed]. fastembed powers local, in-process query embedding for the search command; filesystem browsing (ls/cat/find/grep) needs only the base client.

Connection

The same QdrantConfig works for self-hosted and cloud.

Self-hosted

from mirage import MountMode, Workspace
from mirage.resource.qdrant import QdrantConfig, QdrantResource

config = QdrantConfig(
    host="localhost",
    port=6333,
    collection="fashion",
    group_by=["gender", "articleType", "baseColour"],
    id_field="id",
    text_field="productDisplayName",
    blob_field="image_b64",
    blob_ext="jpg",
)
ws = Workspace({"/fashion/": QdrantResource(config)}, mode=MountMode.READ)

Qdrant Cloud

Use url plus an api_key:

import os

config = QdrantConfig(
    url="https://xyz.cloud.qdrant.io",
    api_key=os.environ["QDRANT_API_KEY"],
    collection="fashion",
    group_by=["gender", "articleType", "baseColour"],
    id_field="id",
)
ws = Workspace({"/fashion/": QdrantResource(config)}, mode=MountMode.READ)

Search setup

The search command embeds the query and runs Qdrant vector search. The collection must already store vectors produced by the same model (embedding_model, default sentence-transformers/all-MiniLM-L6-v2). Query embedding happens one of two ways:

Local (default): fastembed embeds the query in process.
Server-side: set cloud_inference=True to have an inference-enabled Qdrant Cloud cluster embed the query. The query text is sent to the server instead of being embedded locally.

config = QdrantConfig(
    url="https://xyz.cloud.qdrant.io",
    api_key=os.environ["QDRANT_API_KEY"],
    collection="fashion",
    group_by=["gender"],
    cloud_inference=True,
    embedding_model="sentence-transformers/all-MiniLM-L6-v2",
)

search "red running shoes" /fashion          # ranked <path>.txt:score + content
cat /fashion/Men/Shoes/White/3.txt            # follow a result to the real file

Config reference

Field	Required	Default	Description
`url`	No		Qdrant URL (Cloud or self-hosted); overrides `host`/`port`
`host`	No	`localhost`	Host when `url` is unset
`port`	No	`6333`	Port when `url` is unset
`https`	No	`false`	Use TLS for `host`/`port` connections
`api_key`	No		Qdrant Cloud API key
`collection`	No		Pin one collection; the mount root becomes that collection
`group_by`	No	`[]`	Payload fields that become nested folder levels
`id_field`	No	`id`	Field name shown for the point id; names point files
`text_field`	No		Payload field served as the `<id>.txt` embedded source text
`blob_field`	No		Payload field served as the raw blob/image file
`blob_ext`	No	`bin`	Extension for the blob file (`jpg`, `png`, …)
`vector_field`	No		Payload field holding a vector, omitted from `<id>.json`
`search_limit`	No	`10`	Default top-k returned by `search`
`max_rows`	No	`1000`	Cap on points scanned per folder listing
`embedding_model`	No	`sentence-transformers/all-MiniLM-L6-v2`	Model used to embed the query
`cloud_inference`	No	`false`	Embed the query server-side instead of with local fastembed

The mount is read-only. See Qdrant Resource for the filesystem layout and supported commands.

Getting Started

Agents

Resources

CLIs

Watch

Runtimes

Dependencies

Connection

Self-hosted

Qdrant Cloud

Search setup

Config reference

​Dependencies

​Connection

​Self-hosted

​Qdrant Cloud

​Search setup

​Config reference

Dependencies

Connection

Self-hosted

Qdrant Cloud

Search setup

Config reference