Log in Start Free

Mixedbread

Mixedbread publishes open-weight embedding models on Hugging Face under the Apache 2.0 license. There are two ways to use them with Qdrant:

  • Run the model yourself with sentence-transformers and send the vectors to Qdrant. This works with any Qdrant deployment, and it’s what most of this page covers.
  • On Qdrant Cloud, pass text to Qdrant and let Qdrant Cloud Inference run mxbai-embed-large-v1 for you.

Mixedbread’s own documentation lists its direct embeddings API as legacy and no longer documents it. The API still responds, and the Mixedbread API (Legacy) section shows how to call it.

Models

ModelDimensionsReducibleMax Tokens per InputLanguages
mxbai-embed-large-v11024Yes512English
mxbai-embed-xsmall-v1384Yes4096English
deepset-mxbai-embed-de-large-v11024Yes512German, English

On Hugging Face, each model ID has the mixedbread-ai/ prefix, for example mixedbread-ai/mxbai-embed-large-v1. mxbai-embed-large-v1 needs a prompt on retrieval queries, and deepset-mxbai-embed-de-large-v1 needs query: and passage: prefixes. Mixedbread also publishes ColBERT models for multivector retrieval, such as mxbai-edge-colbert-v0-32m, which this page does not cover.

Through sentence-transformers, mxbai-embed-large-v1 and mxbai-embed-xsmall-v1 return vectors that are not normalized. Use the Cosine distance metric, which normalizes vectors for you and matches the cosine similarity in Mixedbread’s examples.

Setup

Install sentence-transformers and the Qdrant client:

pip install sentence-transformers qdrant-client

Load the model and create a collection sized for it. The first run downloads the model from Hugging Face, about 670 MB for mxbai-embed-large-v1.

from qdrant_client import QdrantClient, models
from sentence_transformers import SentenceTransformer

model = SentenceTransformer("mixedbread-ai/mxbai-embed-large-v1")
client = QdrantClient(url="http://localhost:6333")

client.create_collection(
    collection_name="{collection_name}",
    vectors_config=models.VectorParams(size=1024, distance=models.Distance.COSINE),
)

Embed Documents

encode_document embeds a list of documents and returns the vectors in input order, which this example uses for the point IDs:

documents = [
    "Qdrant is a vector search engine.",
    "Mixedbread publishes open-weight embedding models on Hugging Face.",
]

embeddings = model.encode_document(documents)

client.upsert(
    collection_name="{collection_name}",
    points=[
        models.PointStruct(
            id=idx,
            vector=embedding.tolist(),
            payload={"text": documents[idx]},
        )
        for idx, embedding in enumerate(embeddings)
    ],
)

sentence-transformers truncates each input to the model’s limit, 512 tokens for mxbai-embed-large-v1.

Embed Queries

For retrieval, mxbai-embed-large-v1 expects each query to start with the prompt Represent this sentence for searching relevant passages: . Documents take no prompt. encode_query adds the prompt from the model’s configuration, so pass the query text as it is:

query_vector = model.encode_query("What is Qdrant?")

hits = client.query_points(
    collection_name="{collection_name}",
    query=query_vector.tolist(),
    limit=3,
).points

Reduce Vector Size

The mxbai embedding models support Matryoshka truncation, so you can keep only the first dimensions of each vector. Pass truncate_dim when you load the model, and set the collection’s size to the same value:

small_model = SentenceTransformer("mixedbread-ai/mxbai-embed-large-v1", truncate_dim=512)

To keep the full vectors but store them in less memory, use Binary Quantization, which shrinks each vector by 32 times. Mixedbread’s model cards state that these models support binary quantization.

Mixedbread API (Legacy)

Mixedbread’s Python and TypeScript SDKs still include the direct embeddings API:

  • Python: pip install mixedbread
  • TypeScript: npm install @mixedbread/sdk

The client reads your API key from the MXBAI_API_KEY environment variable. As in Mixedbread’s own example, this code adds the query prompt to the start of the query text:

from mixedbread import Mixedbread

mxbai = Mixedbread()

document_result = mxbai.embed(model="mixedbread-ai/mxbai-embed-large-v1", input=documents)
query_result = mxbai.embed(
    model="mixedbread-ai/mxbai-embed-large-v1",
    input="Represent this sentence for searching relevant passages: What is Qdrant?",
)

import Mixedbread from "@mixedbread/sdk";

const mxbai = new Mixedbread();

const documents = [
  "Qdrant is a vector search engine.",
  "Mixedbread publishes open-weight embedding models on Hugging Face.",
];

const documentResult = await mxbai.embed({
  model: "mixedbread-ai/mxbai-embed-large-v1",
  input: documents,
});
const queryResult = await mxbai.embed({
  model: "mixedbread-ai/mxbai-embed-large-v1",
  input: "Represent this sentence for searching relevant passages: What is Qdrant?",
});

Each item in data has an embedding list of 1024 floats and the index of its input. Store and search them as in Embed Documents and Embed Queries.

Qdrant Cloud Inference

On Qdrant Cloud, Qdrant hosts mixedbread-ai/mxbai-embed-large-v1 as a paid model. Instead of a vector, send a Document with the model name mixedbread-ai/mxbai-embed-large-v1 in place of the snippet’s <the-model-to-use> placeholder. The collection’s vector size must be 1024.

# Insert new points with cloud-side inference
PUT /collections/<your-collection>/points?wait=true
{
  "points": [
    {
      "id": 1,
      "payload": { "topic": "cooking", "type": "dessert" },
      "vector": {
        "text": "Recipe for baking chocolate chip cookies",
        "model": "<the-model-to-use>"
      }
    }
  ]
}

# Search in the collection using cloud-side inference
POST /collections/<your-collection>/points/query
{
  "query": {
    "text": "How to bake cookies?",
    "model": "<the-model-to-use>"
  }
}

# Create a new vector
curl -X PUT "https://xyz-example.qdrant.io:6333/collections/<your-collection>/points?wait=true" \
  -H "Content-Type: application/json" \
  -H "api-key: <paste-your-api-key-here>" \
  -d '{
    "points": [
      {
        "id": 1,
        "payload": { "topic": "cooking", "type": "dessert" },
        "vector": {
          "text": "Recipe for baking chocolate chip cookies",
          "model": "<the-model-to-use>"
        }
      }
    ]
  }'

# Perform a search query
curl -X POST "https://xyz-example.qdrant.io:6333/collections/<your-collection>/points/query" \
  -H "Content-Type: application/json" \
  -H "api-key: <paste-your-api-key-here>" \
  -d '{
    "query": {
      "text": "How to bake cookies?",
      "model": "<the-model-to-use>"
    }
  }'

from qdrant_client import QdrantClient
from qdrant_client.models import PointStruct, Document

client = QdrantClient(
    url="https://xyz-example.qdrant.io:6333",
    api_key="<paste-your-api-key-here>",
    # IMPORTANT
    # If not enabled, inference will be performed locally
    cloud_inference=True,
)

points = [
    PointStruct(
        id=1,
        payload={"topic": "cooking", "type": "dessert"},
        vector=Document(
            text="Recipe for baking chocolate chip cookies",
            model="<the-model-to-use>"
        )
    )
]

client.upsert(collection_name="<your-collection>", points=points)

result = client.query_points(
    collection_name="<your-collection>",
    query=Document(
        text="How to bake cookies?",
        model="<the-model-to-use>"
    )
)

print(result)

import {QdrantClient} from "@qdrant/js-client-rest";

const points = [
  {
    id: 1,
    payload: { topic: "cooking", type: "dessert" },
    vector: {
        text: "Recipe for baking chocolate chip cookies",
        model: "<the-model-to-use>"
      }
  }
];

await client.upsert("<your-collection>", { wait: true, points });

const result = await client.query(
    "<your-collection>",
    {
      query: {
          text: "How to bake cookies?",
          model: "<the-model-to-use>"
      },
    }
)

console.log(result);

use qdrant_client::{
    Payload, Qdrant,
    qdrant::{Document, PointStruct, Query, QueryPointsBuilder, UpsertPointsBuilder},
};

let points = vec![PointStruct::new(
    1,
    Document {
        text: "Recipe for baking chocolate chip cookies".into(),
        model: "<the-model-to-use>".into(),
        ..Default::default()
    },
    Payload::try_from(serde_json::json!(
        {"topic": "cooking", "type": "dessert"}
    ))?,
)];

client
    .upsert_points(UpsertPointsBuilder::new("<your-collection>", points).wait(true))
    .await?;

let query_document = Document {
    text: "How to bake cookies?".into(),
    model: "<the-model-to-use>".into(),
    ..Default::default()
};

let result = client
    .query(
        QueryPointsBuilder::new("<your-collection>")
            .query(Query::new_nearest(query_document))
            .build(),
    )
    .await?;

println!("Result: {:?}", result);

import static io.qdrant.client.PointIdFactory.id;
import static io.qdrant.client.QueryFactory.nearest;
import static io.qdrant.client.ValueFactory.value;
import static io.qdrant.client.VectorsFactory.vectors;

import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;
import io.qdrant.client.grpc.Points;
import io.qdrant.client.grpc.Points.Document;
import io.qdrant.client.grpc.Points.PointStruct;
import java.util.List;
import java.util.Map;

client
    .upsertAsync(
        "<your-collection>",
        List.of(
            PointStruct.newBuilder()
                .setId(id(1))
                .setVectors(
                    vectors(
                        Document.newBuilder()
                            .setText("Recipe for baking chocolate chip cookies")
                            .setModel("<the-model-to-use>")
                            .build()))
                .putAllPayload(Map.of("topic", value("cooking"), "type", value("dessert")))
                .build()))
    .get();

List<Points.ScoredPoint> points =
    client
        .queryAsync(
            Points.QueryPoints.newBuilder()
                .setCollectionName("<your-collection>")
                .setQuery(
                    nearest(
                        Document.newBuilder()
                            .setText("How to bake cookies?")
                            .setModel("<the-model-to-use>")
                            .build()))
                .build())
        .get();

System.out.printf(points.toString());

using Qdrant.Client;
using Qdrant.Client.Grpc;
using Value = Qdrant.Client.Grpc.Value;

var client = new QdrantClient(
  host: "xyz-example.qdrant.io",
  port: 6334,
  https: true,
  apiKey: "<paste-your-api-key-here>"
);

await client.UpsertAsync(
  collectionName: "<your-collection>",
  points: new List <PointStruct> {
    new() {
      Id = 1,
        Vectors = new Document() {
          Text = "Recipe for baking chocolate chip cookies",
          Model = "<the-model-to-use>",
        },
        Payload = {
          ["topic"] = "cooking",
          ["type"] = "dessert"
        },
    },
  }
);

var points = await client.QueryAsync(
  collectionName: "<your-collection>",
  query: new Document() {
    Text = "How to bake cookies?",
    Model = "<the-model-to-use>"
  }
);

foreach(var point in points) {
  Console.WriteLine(point);
}

import (
	"context"

	"github.com/qdrant/go-client/qdrant"
)

client.Upsert(context.Background(), &qdrant.UpsertPoints{
	CollectionName: "<your-collection>",
	Points: []*qdrant.PointStruct{
		{
			Id: qdrant.NewIDNum(1),
			Vectors: qdrant.NewVectorsDocument(&qdrant.Document{
				Text:  "Recipe for baking chocolate chip cookies",
				Model: "<the-model-to-use>",
			}),
			Payload: qdrant.NewValueMap(map[string]any{
				"topic": "cooking",
				"type":  "dessert",
			}),
		},
	},
})

client.Query(context.Background(), &qdrant.QueryPoints{
	CollectionName: "<your-collection>",
	Query: qdrant.NewQueryDocument(&qdrant.Document{
		Text:  "How to bake cookies?",
		Model: "<the-model-to-use>",
	}),
})

For search queries, start the text with Represent this sentence for searching relevant passages: . Qdrant Cloud Inference leaves text that already starts with a model’s prefix unchanged, so the prompt is never added twice. For setup and billing, see Cloud Inference.

Store and Search the Vectors

Create a Collection

Match the model's dimensions and distance metric.

Upload Vectors

Batch points with payloads for filtering.

Search

Find matching points with the Query API.

Next Steps

Was this page useful?

Thank you for your feedback! 🙏

We are sorry to hear that. 😔 You can edit this page on GitHub, or create a GitHub issue.

On this page:

Ready to try Qdrant?