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>

qdrant-landing/content/documentation/headless/snippets/inference/openrouter-upsert/csharp.cs

@@ -5,24 +5,26 @@ 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-openrouter-key>");
+		// @hide-end
 
-		await client.UpsertAsync(
-		    collectionName: "{collection_name}",
-		    points: new List<PointStruct>
-		    {
-		        new()
+		using (RequestHeaders.Use("openrouter-api-key", "<YOUR_OPENROUTER_API_KEY>"))
+		    await client.UpsertAsync(
+		        collectionName: "{collection_name}",
+		        points: new List<PointStruct>
 		        {
-		            Id = 1,
-		            Vectors = new Document()
+		            new()
 		            {
-		                Model = "openrouter/mistralai/mistral-embed-2312",
-		                Text = "Recipe for baking chocolate chip cookies",
-		                Options = { ["openrouter-api-key"] = "<YOUR_OPENROUTER_API_KEY>" },
+		                Id = 1,
+		                Vectors = new Document()
+		                {
+		                    Model = "openrouter/mistralai/mistral-embed-2312",
+		                    Text = "Recipe for baking chocolate chip cookies",
+		                },
 		            },
-		        },
-		    }
-		);
+		        }
+		    );
 	}
 }

qdrant-landing/content/documentation/headless/snippets/inference/openrouter-upsert/generated/csharp.md

@@ -2,23 +2,20 @@
 using Qdrant.Client;
 using Qdrant.Client.Grpc;
 
-var client = new QdrantClient(
-host: "xyz-example.qdrant.io", port: 6334, https: true, apiKey: "<your-openrouter-key>");
-
-await client.UpsertAsync(
-    collectionName: "{collection_name}",
-    points: new List<PointStruct>
-    {
-        new()
+using (RequestHeaders.Use("openrouter-api-key", "<YOUR_OPENROUTER_API_KEY>"))
+    await client.UpsertAsync(
+        collectionName: "{collection_name}",
+        points: new List<PointStruct>
         {
-            Id = 1,
-            Vectors = new Document()
+            new()
             {
-                Model = "openrouter/mistralai/mistral-embed-2312",
-                Text = "Recipe for baking chocolate chip cookies",
-                Options = { ["openrouter-api-key"] = "<YOUR_OPENROUTER_API_KEY>" },
+                Id = 1,
+                Vectors = new Document()
+                {
+                    Model = "openrouter/mistralai/mistral-embed-2312",
+                    Text = "Recipe for baking chocolate chip cookies",
+                },
             },
-        },
-    }
-);
+        }
+    );
 ```

qdrant-landing/content/documentation/headless/snippets/inference/openrouter-upsert/generated/go.md

@@ -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-openrouter-key-here>",
-	UseTLS: true,
-})
+ctx := qdrant.WithHeader(context.Background(), "openrouter-api-key", "<YOUR_OPENROUTER_API_KEY>")
 
-client.Upsert(context.Background(), &qdrant.UpsertPoints{
+client.Upsert(ctx, &qdrant.UpsertPoints{
 	CollectionName: "{collection_name}",
 	Points: []*qdrant.PointStruct{
 		{
@@ -20,9 +15,6 @@ client.Upsert(context.Background(), &qdrant.UpsertPoints{
 			Vectors: qdrant.NewVectorsDocument(&qdrant.Document{
 				Model: "openrouter/mistralai/mistral-embed-2312",
 				Text:  "Recipe for baking chocolate chip cookies",
-				Options: qdrant.NewValueMap(map[string]any{
-					"openrouter-api-key": "<YOUR_OPENROUTER_API_KEY>",
-				}),
 			}),
 		},
 	},

qdrant-landing/content/documentation/headless/snippets/inference/openrouter-upsert/generated/java.md

@@ -1,22 +1,19 @@
 ```java
 import static io.qdrant.client.PointIdFactory.id;
-import static io.qdrant.client.ValueFactory.value;
 import static io.qdrant.client.VectorsFactory.vectors;
 
+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-openrouter-key>")
-            .build());
+Context ctx = RequestHeaders.withHeader(
+    Context.current(), "openrouter-api-key", "<YOUR_OPENROUTER_API_KEY>");
 
-client
+ctx.call(() -> client
     .upsertAsync(
         "{collection_name}",
         List.of(
@@ -27,11 +24,7 @@ client
                         Document.newBuilder()
                             .setModel("openrouter/mistralai/mistral-embed-2312")
                             .setText("Recipe for baking chocolate chip cookies")
-                            .putAllOptions(
-                                Map.of(
-                                    "openrouter-api-key",
-                                    value("<YOUR_OPENROUTER_API_KEY>")))
                             .build()))
                 .build()))
-    .get();
+    .get());
 ```

qdrant-landing/content/documentation/headless/snippets/inference/openrouter-upsert/generated/python.md

@@ -1,25 +1,24 @@
 ```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>", 
+    api_key="<your-qdrant-api-key>",
     cloud_inference=True
 )
 
-client.upsert(
-    collection_name="{collection_name}",
-    points=[
-        models.PointStruct(
-            id=1,
-            vector=models.Document(
-                text="Recipe for baking chocolate chip cookies",
-                model="openrouter/mistralai/mistral-embed-2312",
-                options={
-                    "openrouter-api-key": "<your_openrouter_api_key>"
-                }
+with headers({"openrouter-api-key": "<YOUR_OPENROUTER_API_KEY>"}):
+    client.upsert(
+        collection_name="{collection_name}",
+        points=[
+            models.PointStruct(
+                id=1,
+                vector=models.Document(
+                    text="Recipe for baking chocolate chip cookies",
+                    model="openrouter/mistralai/mistral-embed-2312",
+                )
             )
-        )
-    ]
-)
+        ]
+    )
 ```

qdrant-landing/content/documentation/headless/snippets/inference/openrouter-upsert/generated/rust.md

@@ -5,18 +5,15 @@ use qdrant_client::{
 };
 use std::collections::HashMap;
 
-let client = Qdrant::from_url("<your-qdrant-url>").build()?;
-let mut options = HashMap::new();
-options.insert("openrouter-api-key".to_string(), "<YOUR_OPENROUTER_API_KEY>".into());
-
 client
+    .with_header("openrouter-api-key", "<YOUR_OPENROUTER_API_KEY>")
     .upsert_points(UpsertPointsBuilder::new("{collection_name}",
         vec![
             PointStruct::new(1,
                 Document {
                   text: "Recipe for baking chocolate chip cookies".into(),
                   model: "openrouter/mistralai/mistral-embed-2312".into(),
-                  options,
+                  options: HashMap::new(),
                   },
                 Payload::default())
             ]).wait(true))

qdrant-landing/content/documentation/headless/snippets/inference/openrouter-upsert/generated/typescript.md

@@ -1,20 +1,17 @@
 ```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: {
-                text: 'Recipe for baking chocolate chip cookies',
-                model: 'openrouter/mistralai/mistral-embed-2312',
-                options: {
-                    'openrouter-api-key': '<your_openrouter_api_key>',
+await withHeaders({ 'openrouter-api-key': '<YOUR_OPENROUTER_API_KEY>' }, () =>
+    client.upsert("{collection_name}", {
+        points: [
+            {
+                id: 1,
+                vector: {
+                    text: 'Recipe for baking chocolate chip cookies',
+                    model: 'openrouter/mistralai/mistral-embed-2312',
                 },
             },
-        },
-    ],
-});
+        ],
+    })
+);
 ```

qdrant-landing/content/documentation/headless/snippets/inference/openrouter-upsert/go.go

@@ -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-openrouter-key-here>",
 		UseTLS: true,
 	})
+	// @hide-end
 
 	if err != nil { panic(err) } // @hide
 
-	client.Upsert(context.Background(), &qdrant.UpsertPoints{
+	ctx := qdrant.WithHeader(context.Background(), "openrouter-api-key", "<YOUR_OPENROUTER_API_KEY>")
+
+	client.Upsert(ctx, &qdrant.UpsertPoints{
 		CollectionName: "{collection_name}",
 		Points: []*qdrant.PointStruct{
 			{
@@ -24,9 +28,6 @@ func Main() {
 				Vectors: qdrant.NewVectorsDocument(&qdrant.Document{
 					Model: "openrouter/mistralai/mistral-embed-2312",
 					Text:  "Recipe for baking chocolate chip cookies",
-					Options: qdrant.NewValueMap(map[string]any{
-						"openrouter-api-key": "<YOUR_OPENROUTER_API_KEY>",
-					}),
 				}),
 			},
 		},

qdrant-landing/content/documentation/headless/snippets/inference/openrouter-upsert/java.java

@@ -1,25 +1,30 @@
 package com.example.snippets_amalgamation;
 
 import static io.qdrant.client.PointIdFactory.id;
-import static io.qdrant.client.ValueFactory.value;
 import static io.qdrant.client.VectorsFactory.vectors;
 
+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;
 
 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-openrouter-key>")
                             .build());
+                // @hide-end
 
-                client
+                Context ctx = RequestHeaders.withHeader(
+                    Context.current(), "openrouter-api-key", "<YOUR_OPENROUTER_API_KEY>");
+
+                ctx.call(() -> client
                     .upsertAsync(
                         "{collection_name}",
                         List.of(
@@ -30,12 +35,8 @@ public class Snippet {
                                         Document.newBuilder()
                                             .setModel("openrouter/mistralai/mistral-embed-2312")
                                             .setText("Recipe for baking chocolate chip cookies")
-                                            .putAllOptions(
-                                                Map.of(
-                                                    "openrouter-api-key",
-                                                    value("<YOUR_OPENROUTER_API_KEY>")))
                                             .build()))
                                 .build()))
-                    .get();
+                    .get());
         }
-}
+}

qdrant-landing/content/documentation/headless/snippets/inference/openrouter-upsert/python.py

@@ -1,23 +1,22 @@
 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>", 
+    api_key="<your-qdrant-api-key>",
     cloud_inference=True
 )
 
-client.upsert(
-    collection_name="{collection_name}",
-    points=[
-        models.PointStruct(
-            id=1,
-            vector=models.Document(
-                text="Recipe for baking chocolate chip cookies",
-                model="openrouter/mistralai/mistral-embed-2312",
-                options={
-                    "openrouter-api-key": "<your_openrouter_api_key>"
-                }
+with headers({"openrouter-api-key": "<YOUR_OPENROUTER_API_KEY>"}):
+    client.upsert(
+        collection_name="{collection_name}",
+        points=[
+            models.PointStruct(
+                id=1,
+                vector=models.Document(
+                    text="Recipe for baking chocolate chip cookies",
+                    model="openrouter/mistralai/mistral-embed-2312",
+                )
             )
-        )
-    ]
-)
+        ]
+    )

qdrant-landing/content/documentation/headless/snippets/inference/openrouter-upsert/rust.rs

@@ -5,18 +5,17 @@ use qdrant_client::{
 use std::collections::HashMap;
 
 pub async fn main() -> anyhow::Result<()> {
-    let client = Qdrant::from_url("<your-qdrant-url>").build()?;
-    let mut options = HashMap::new();
-    options.insert("openrouter-api-key".to_string(), "<YOUR_OPENROUTER_API_KEY>".into());
+    let client = Qdrant::from_url("<your-qdrant-url>").build()?; // @hide
 
     client
+        .with_header("openrouter-api-key", "<YOUR_OPENROUTER_API_KEY>")
         .upsert_points(UpsertPointsBuilder::new("{collection_name}",
             vec![
                 PointStruct::new(1,
                     Document {
                       text: "Recipe for baking chocolate chip cookies".into(),
                       model: "openrouter/mistralai/mistral-embed-2312".into(),
-                      options,
+                      options: HashMap::new(),
                       },
                     Payload::default())
                 ]).wait(true))

qdrant-landing/content/documentation/headless/snippets/inference/openrouter-upsert/typescript.ts

@@ -1,18 +1,17 @@
-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: {
-                text: 'Recipe for baking chocolate chip cookies',
-                model: 'openrouter/mistralai/mistral-embed-2312',
-                options: {
-                    'openrouter-api-key': '<your_openrouter_api_key>',
+await withHeaders({ 'openrouter-api-key': '<YOUR_OPENROUTER_API_KEY>' }, () =>
+    client.upsert("{collection_name}", {
+        points: [
+            {
+                id: 1,
+                vector: {
+                    text: 'Recipe for baking chocolate chip cookies',
+                    model: 'openrouter/mistralai/mistral-embed-2312',
                 },
             },
-        },
-    ],
-});
+        ],
+    })
+);