Restructure inference docs (#2225)

* Break Inference page into several pages

* Make all inference code snippets testable and clean up

* Make more snippets testable

* Edits

* Document automatic query and passage prefix injection in Cloud Inference

Qdrant Cloud Inference silently applies model-specific prefixes (e.g.
"query: "/"passage: " for E5, BGE-style instruction prefix for BGE/mxbai/
Snowflake arctic-embed) so users don't need to manage them manually.
Add a section explaining this behavior, the idempotency guarantee, and
the scope (Qdrant-hosted models only; external providers handle their own).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Document short query optimization in Cloud Inference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* Update links

* Expand on external provider API key usage

* Add section about external provider API keys

* Default to header for external API keys

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Abdon Pijpelink
2026-06-24 08:11:03 +02:00
committed by GitHub
co-authored by Claude Sonnet 4.6
parent 90d072eb03
commit 478b96554f
250 changed files with 3259 additions and 2187 deletions
@@ -5,37 +5,39 @@ public class Snippet
{
public static async Task Run()
{
// @hide-start
var client = new QdrantClient(
host: "xyz-example.qdrant.io",
port: 6334,
https: true,
apiKey: "<your-api-key>"
);
// @hide-end
await client.UpsertAsync(
collectionName: "{collection_name}",
points: new List<PointStruct>
{
new()
using (RequestHeaders.Use("openai-api-key", "<YOUR_OPENAI_API_KEY>"))
await client.UpsertAsync(
collectionName: "{collection_name}",
points: new List<PointStruct>
{
Id = 1,
Vectors = new Dictionary<string, Vector>
new()
{
["large"] = new Document()
Id = 1,
Vectors = new Dictionary<string, Vector>
{
Model = "openai/text-embedding-3-small",
Text = "Recipe for baking chocolate chip cookies",
Options = { ["openai-api-key"] = "<YOUR_OPENAI_API_KEY>" },
},
["small"] = new Document()
{
Model = "openai/text-embedding-3-small",
Text = "Recipe for baking chocolate chip cookies",
Options = { ["openai-api-key"] = "<YOUR_OPENAI_API_KEY>", ["mrl"] = 64 },
["large"] = new Document()
{
Model = "openai/text-embedding-3-small",
Text = "Recipe for baking chocolate chip cookies",
},
["small"] = new Document()
{
Model = "openai/text-embedding-3-small",
Text = "Recipe for baking chocolate chip cookies",
Options = { ["mrl"] = 64 },
},
},
},
},
}
);
}
);
}
}
@@ -2,36 +2,29 @@
using Qdrant.Client;
using Qdrant.Client.Grpc;
var client = new QdrantClient(
host: "xyz-example.qdrant.io",
port: 6334,
https: true,
apiKey: "<your-api-key>"
);
await client.UpsertAsync(
collectionName: "{collection_name}",
points: new List<PointStruct>
{
new()
using (RequestHeaders.Use("openai-api-key", "<YOUR_OPENAI_API_KEY>"))
await client.UpsertAsync(
collectionName: "{collection_name}",
points: new List<PointStruct>
{
Id = 1,
Vectors = new Dictionary<string, Vector>
new()
{
["large"] = new Document()
Id = 1,
Vectors = new Dictionary<string, Vector>
{
Model = "openai/text-embedding-3-small",
Text = "Recipe for baking chocolate chip cookies",
Options = { ["openai-api-key"] = "<YOUR_OPENAI_API_KEY>" },
},
["small"] = new Document()
{
Model = "openai/text-embedding-3-small",
Text = "Recipe for baking chocolate chip cookies",
Options = { ["openai-api-key"] = "<YOUR_OPENAI_API_KEY>", ["mrl"] = 64 },
["large"] = new Document()
{
Model = "openai/text-embedding-3-small",
Text = "Recipe for baking chocolate chip cookies",
},
["small"] = new Document()
{
Model = "openai/text-embedding-3-small",
Text = "Recipe for baking chocolate chip cookies",
Options = { ["mrl"] = 64 },
},
},
},
},
}
);
}
);
```
@@ -5,14 +5,9 @@ import (
"github.com/qdrant/go-client/qdrant"
)
client, err := qdrant.NewClient(&qdrant.Config{
Host: "xyz-example.qdrant.io",
Port: 6334,
APIKey: "<paste-your-api-key-here>",
UseTLS: true,
})
ctx := qdrant.WithHeader(context.Background(), "openai-api-key", "<YOUR_OPENAI_API_KEY>")
client.Upsert(context.Background(), &qdrant.UpsertPoints{
client.Upsert(ctx, &qdrant.UpsertPoints{
CollectionName: "{collection_name}",
Points: []*qdrant.PointStruct{
{
@@ -21,16 +16,12 @@ client.Upsert(context.Background(), &qdrant.UpsertPoints{
"large": qdrant.NewVectorDocument(&qdrant.Document{
Model: "openai/text-embedding-3-small",
Text: "Recipe for baking chocolate chip cookies",
Options: qdrant.NewValueMap(map[string]any{
"openai-api-key": "<YOUR_OPENAI_API_KEY>",
}),
}),
"small": qdrant.NewVectorDocument(&qdrant.Document{
Model: "openai/text-embedding-3-small",
Text: "Recipe for baking chocolate chip cookies",
Options: qdrant.NewValueMap(map[string]any{
"openai-api-key": "<YOUR_OPENAI_API_KEY>",
"mrl": 64,
"mrl": 64,
}),
}),
}),
@@ -4,20 +4,19 @@ import static io.qdrant.client.ValueFactory.value;
import static io.qdrant.client.VectorFactory.vector;
import static io.qdrant.client.VectorsFactory.namedVectors;
import io.grpc.Context;
import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;
import io.qdrant.client.RequestHeaders;
import io.qdrant.client.grpc.Points.Document;
import io.qdrant.client.grpc.Points.PointStruct;
import java.util.List;
import java.util.Map;
QdrantClient client =
new QdrantClient(
QdrantGrpcClient.newBuilder("xyz-example.qdrant.io", 6334, true)
.withApiKey("<your-api-key")
.build());
Context ctx = RequestHeaders.withHeader(
Context.current(), "openai-api-key", "<YOUR_OPENAI_API_KEY>");
client
ctx.call(() -> client
.upsertAsync(
"{collection_name}",
List.of(
@@ -31,22 +30,14 @@ client
Document.newBuilder()
.setModel("openai/text-embedding-3-small")
.setText("Recipe for baking chocolate chip cookies")
.putAllOptions(
Map.of(
"openai-api-key", value("<YOUR_OPENAI_API_KEY>")))
.build()),
"small",
vector(
Document.newBuilder()
.setModel("openai/text-embedding-3-small")
.setText("Recipe for baking chocolate chip cookies")
.putAllOptions(
Map.of(
"openai-api-key",
value("<YOUR_OPENAI_API_KEY>"),
"mrl",
value(64)))
.putAllOptions(Map.of("mrl", value(64)))
.build()))))
.build()))
.get();
.get());
```
@@ -1,33 +1,31 @@
```python
from qdrant_client import QdrantClient, models
from qdrant_client.context_headers import headers
client = QdrantClient(
url="https://xyz-example.qdrant.io:6333",
api_key="<your-api-key>",
url="https://xyz-example.qdrant.io:6333",
api_key="<your-qdrant-api-key>",
cloud_inference=True
)
client.upsert(
collection_name="{collection_name}",
points=[
models.PointStruct(
id=1,
vector={
"large": models.Document(
text="Recipe for baking chocolate chip cookies",
model="openai/text-embedding-3-small",
options={"openai-api-key": "<YOUR_OPENAI_API_KEY>"}
),
"small": models.Document(
text="Recipe for baking chocolate chip cookies",
model="openai/text-embedding-3-small",
options={
"openai-api-key": "<YOUR_OPENAI_API_KEY>",
"mrl": 64
},
)
},
)
],
)
with headers({"openai-api-key": "<YOUR_OPENAI_API_KEY>"}):
client.upsert(
collection_name="{collection_name}",
points=[
models.PointStruct(
id=1,
vector={
"large": models.Document(
text="Recipe for baking chocolate chip cookies",
model="openai/text-embedding-3-small",
),
"small": models.Document(
text="Recipe for baking chocolate chip cookies",
model="openai/text-embedding-3-small",
options={"mrl": 64},
)
},
)
],
)
```
@@ -6,9 +6,8 @@ use qdrant_client::{
qdrant::{Document, NamedVectors, PointStruct, UpsertPointsBuilder, Value},
};
let client = Qdrant::from_url("http://localhost:6334").build()?;
client
.with_header("openai-api-key", "<YOUR_OPENAI_API_KEY>")
.upsert_points(
UpsertPointsBuilder::new(
"{collection_name}",
@@ -20,10 +19,7 @@ client
Document {
text: "Recipe for baking chocolate chip cookies".into(),
model: "openai/text-embedding-3-small".into(),
options: HashMap::<String, Value>::from_iter(vec![(
"openai-api-key".into(),
"<YOUR_OPENAI_API_KEY>".into(),
)]),
options: HashMap::new(),
},
)
.add_vector(
@@ -31,13 +27,10 @@ client
Document {
text: "Recipe for baking chocolate chip cookies".into(),
model: "openai/text-embedding-3-small".into(),
options: HashMap::<String, Value>::from_iter(vec![
(
"openai-api-key".into(),
Value::from("<YOUR_OPENAI_API_KEY>"),
),
("mrl".into(), Value::from(64)),
]),
options: HashMap::<String, Value>::from_iter(vec![(
"mrl".into(),
Value::from(64),
)]),
},
),
Payload::default(),
@@ -1,30 +1,26 @@
```typescript
import { QdrantClient } from "@qdrant/js-client-rest";
import { QdrantClient, withHeaders } from "@qdrant/js-client-rest";
const client = new QdrantClient({ host: "localhost", port: 6333 });
client.upsert("{collection_name}", {
points: [
{
id: 1,
vector: {
large: {
text: 'Recipe for baking chocolate chip cookies',
model: 'openai/text-embedding-3-small',
options: {
'openai-api-key': '<YOUR_OPENAI_API_KEY>',
await withHeaders({ 'openai-api-key': '<YOUR_OPENAI_API_KEY>' }, () =>
client.upsert("{collection_name}", {
points: [
{
id: 1,
vector: {
large: {
text: 'Recipe for baking chocolate chip cookies',
model: 'openai/text-embedding-3-small',
},
},
small: {
text: 'Recipe for baking chocolate chip cookies',
model: 'openai/text-embedding-3-small',
options: {
'openai-api-key': '<YOUR_OPENAI_API_KEY>',
mrl: 64,
small: {
text: 'Recipe for baking chocolate chip cookies',
model: 'openai/text-embedding-3-small',
options: {
mrl: 64,
},
},
},
},
},
],
});
],
})
);
```
@@ -7,16 +7,20 @@ import (
)
func Main() {
// @hide-start
client, err := qdrant.NewClient(&qdrant.Config{
Host: "xyz-example.qdrant.io",
Port: 6334,
APIKey: "<paste-your-api-key-here>",
UseTLS: true,
})
// @hide-end
if err != nil { panic(err) } // @hide
client.Upsert(context.Background(), &qdrant.UpsertPoints{
ctx := qdrant.WithHeader(context.Background(), "openai-api-key", "<YOUR_OPENAI_API_KEY>")
client.Upsert(ctx, &qdrant.UpsertPoints{
CollectionName: "{collection_name}",
Points: []*qdrant.PointStruct{
{
@@ -25,16 +29,12 @@ func Main() {
"large": qdrant.NewVectorDocument(&qdrant.Document{
Model: "openai/text-embedding-3-small",
Text: "Recipe for baking chocolate chip cookies",
Options: qdrant.NewValueMap(map[string]any{
"openai-api-key": "<YOUR_OPENAI_API_KEY>",
}),
}),
"small": qdrant.NewVectorDocument(&qdrant.Document{
Model: "openai/text-embedding-3-small",
Text: "Recipe for baking chocolate chip cookies",
Options: qdrant.NewValueMap(map[string]any{
"openai-api-key": "<YOUR_OPENAI_API_KEY>",
"mrl": 64,
"mrl": 64,
}),
}),
}),
@@ -5,8 +5,10 @@ import static io.qdrant.client.ValueFactory.value;
import static io.qdrant.client.VectorFactory.vector;
import static io.qdrant.client.VectorsFactory.namedVectors;
import io.grpc.Context;
import io.qdrant.client.QdrantClient;
import io.qdrant.client.QdrantGrpcClient;
import io.qdrant.client.RequestHeaders;
import io.qdrant.client.grpc.Points.Document;
import io.qdrant.client.grpc.Points.PointStruct;
import java.util.List;
@@ -14,13 +16,18 @@ import java.util.Map;
public class Snippet {
public static void run() throws Exception {
// @hide-start
QdrantClient client =
new QdrantClient(
QdrantGrpcClient.newBuilder("xyz-example.qdrant.io", 6334, true)
.withApiKey("<your-api-key")
.build());
// @hide-end
client
Context ctx = RequestHeaders.withHeader(
Context.current(), "openai-api-key", "<YOUR_OPENAI_API_KEY>");
ctx.call(() -> client
.upsertAsync(
"{collection_name}",
List.of(
@@ -34,23 +41,15 @@ public class Snippet {
Document.newBuilder()
.setModel("openai/text-embedding-3-small")
.setText("Recipe for baking chocolate chip cookies")
.putAllOptions(
Map.of(
"openai-api-key", value("<YOUR_OPENAI_API_KEY>")))
.build()),
"small",
vector(
Document.newBuilder()
.setModel("openai/text-embedding-3-small")
.setText("Recipe for baking chocolate chip cookies")
.putAllOptions(
Map.of(
"openai-api-key",
value("<YOUR_OPENAI_API_KEY>"),
"mrl",
value(64)))
.putAllOptions(Map.of("mrl", value(64)))
.build()))))
.build()))
.get();
.get());
}
}
@@ -1,31 +1,29 @@
from qdrant_client import QdrantClient, models
from qdrant_client.context_headers import headers
client = QdrantClient(
url="https://xyz-example.qdrant.io:6333",
api_key="<your-api-key>",
url="https://xyz-example.qdrant.io:6333",
api_key="<your-qdrant-api-key>",
cloud_inference=True
)
client.upsert(
collection_name="{collection_name}",
points=[
models.PointStruct(
id=1,
vector={
"large": models.Document(
text="Recipe for baking chocolate chip cookies",
model="openai/text-embedding-3-small",
options={"openai-api-key": "<YOUR_OPENAI_API_KEY>"}
),
"small": models.Document(
text="Recipe for baking chocolate chip cookies",
model="openai/text-embedding-3-small",
options={
"openai-api-key": "<YOUR_OPENAI_API_KEY>",
"mrl": 64
},
)
},
)
],
)
with headers({"openai-api-key": "<YOUR_OPENAI_API_KEY>"}):
client.upsert(
collection_name="{collection_name}",
points=[
models.PointStruct(
id=1,
vector={
"large": models.Document(
text="Recipe for baking chocolate chip cookies",
model="openai/text-embedding-3-small",
),
"small": models.Document(
text="Recipe for baking chocolate chip cookies",
model="openai/text-embedding-3-small",
options={"mrl": 64},
)
},
)
],
)
@@ -6,9 +6,10 @@ use qdrant_client::{
};
pub async fn main() -> anyhow::Result<()> {
let client = Qdrant::from_url("http://localhost:6334").build()?;
let client = Qdrant::from_url("http://localhost:6334").build()?; // @hide
client
.with_header("openai-api-key", "<YOUR_OPENAI_API_KEY>")
.upsert_points(
UpsertPointsBuilder::new(
"{collection_name}",
@@ -20,10 +21,7 @@ pub async fn main() -> anyhow::Result<()> {
Document {
text: "Recipe for baking chocolate chip cookies".into(),
model: "openai/text-embedding-3-small".into(),
options: HashMap::<String, Value>::from_iter(vec![(
"openai-api-key".into(),
"<YOUR_OPENAI_API_KEY>".into(),
)]),
options: HashMap::new(),
},
)
.add_vector(
@@ -31,13 +29,10 @@ pub async fn main() -> anyhow::Result<()> {
Document {
text: "Recipe for baking chocolate chip cookies".into(),
model: "openai/text-embedding-3-small".into(),
options: HashMap::<String, Value>::from_iter(vec![
(
"openai-api-key".into(),
Value::from("<YOUR_OPENAI_API_KEY>"),
),
("mrl".into(), Value::from(64)),
]),
options: HashMap::<String, Value>::from_iter(vec![(
"mrl".into(),
Value::from(64),
)]),
},
),
Payload::default(),
@@ -1,28 +1,26 @@
import { QdrantClient } from "@qdrant/js-client-rest";
import { QdrantClient, withHeaders } from "@qdrant/js-client-rest";
const client = new QdrantClient({ host: "localhost", port: 6333 });
const client = new QdrantClient({ host: "localhost", port: 6333 }); // @hide
client.upsert("{collection_name}", {
points: [
{
id: 1,
vector: {
large: {
text: 'Recipe for baking chocolate chip cookies',
model: 'openai/text-embedding-3-small',
options: {
'openai-api-key': '<YOUR_OPENAI_API_KEY>',
await withHeaders({ 'openai-api-key': '<YOUR_OPENAI_API_KEY>' }, () =>
client.upsert("{collection_name}", {
points: [
{
id: 1,
vector: {
large: {
text: 'Recipe for baking chocolate chip cookies',
model: 'openai/text-embedding-3-small',
},
},
small: {
text: 'Recipe for baking chocolate chip cookies',
model: 'openai/text-embedding-3-small',
options: {
'openai-api-key': '<YOUR_OPENAI_API_KEY>',
mrl: 64,
small: {
text: 'Recipe for baking chocolate chip cookies',
model: 'openai/text-embedding-3-small',
options: {
mrl: 64,
},
},
},
},
},
],
});
],
})
);