Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

perf(embedding): batch Qwen3-VL message inputs (#4126)

lyingbuge372b8e42ef7
diff --git a/internal/models/api/embeddings_settings.go b/internal/models/api/embeddings_settings.go
index ecd044d9c..ad2d9c4a6 100644
--- a/internal/models/api/embeddings_settings.go
+++ b/internal/models/api/embeddings_settings.go
@@ -29,6 +29,7 @@ type EmbeddingsCompat struct {
ImageFormat *EmbeddingImageFormat `json:"image_format,omitempty"`
ImagePrompt *string `json:"image_prompt,omitempty"`
TextAsMessages *bool `json:"text_as_messages,omitempty"`
+ BatchMessages *bool `json:"batch_messages,omitempty"`
}
// EmbeddingImageFormat is how an image travels on the OpenAI embedding
@@ -41,8 +42,8 @@ const (
EmbeddingImageObject EmbeddingImageFormat = "object"
// EmbeddingImageMessages sends a chat conversation in `messages` instead
// of `input`, which is how vLLM serves multimodal embedding models
- // (https://docs.vllm.ai/en/latest/models/pooling_models.html). One
- // conversation yields one vector, so every image is its own request.
+ // (https://docs.vllm.ai/en/latest/models/pooling_models/embed/). Each
+ // conversation yields one vector; BatchMessages can batch conversations.
EmbeddingImageMessages EmbeddingImageFormat = "messages"
)
@@ -106,11 +107,14 @@ type EmbeddingsSettings struct {
// some chat templates (VLM2Vec's) expect an instruction there. Empty
// sends the image alone.
ImagePrompt string `json:",omitempty"`
- // TextAsMessages sends texts in the messages format too, one per
- // request. A model whose chat template frames its inputs only places a
- // text and an image in the same space when both pass through it; a
- // plain `input` string skips the template.
+ // TextAsMessages sends texts in the messages format too. A model whose
+ // chat template frames its inputs only places text and images in the same
+ // space when both pass through it; a plain `input` skips the template.
TextAsMessages bool `json:",omitempty"`
+ // BatchMessages enables independent conversations in a two-dimensional
+ // messages array (vLLM 0.29 supports this). False preserves the one-input
+ // request shape for older servers. Single inputs always keep that shape.
+ BatchMessages bool `json:",omitempty"`
}
// OpenAIImageFormat is the effective image format on the OpenAI shape, empty
diff --git a/internal/models/api/openaiembeddings/client.go b/internal/models/api/openaiembeddings/client.go
index f3d862be7..ec1637469 100644
--- a/internal/models/api/openaiembeddings/client.go
+++ b/internal/models/api/openaiembeddings/client.go
@@ -151,7 +151,7 @@ func (c *Client) Embed(
ctx context.Context, texts []string, kind api.EmbedInputType,
) ([][]float32, error) {
if c.cfg.Settings.TextAsMessages {
- return c.postEach(ctx, len(texts), func(i int) map[string]any {
+ return c.postMessages(ctx, len(texts), kind, func(i int) map[string]any {
return c.BuildTextMessageBody(texts[i], kind)
})
}
@@ -171,16 +171,30 @@ func (c *Client) EmbedImages(
case api.EmbeddingImageObject:
return c.post(ctx, c.BuildImageRequestBody(images, kind), len(images))
case api.EmbeddingImageMessages:
- return c.postEach(ctx, len(images), func(i int) map[string]any {
+ return c.postMessages(ctx, len(images), kind, func(i int) map[string]any {
return c.BuildImageMessageBody(images[i], kind)
})
}
return nil, fmt.Errorf("this embedding endpoint declares no image input")
}
-// postEach sends one request per input, for the messages format where a
-// conversation yields exactly one vector.
-func (c *Client) postEach(ctx context.Context, n int, body func(int) map[string]any) ([][]float32, error) {
+// postMessages preserves each input's chat template while batching independent
+// conversations on servers that support EmbeddingBatchChatRequest:
+// https://github.com/vllm-project/vllm/blob/v0.29.0/vllm/entrypoints/pooling/embed/protocol.py
+func (c *Client) postMessages(
+ ctx context.Context, n int, kind api.EmbedInputType, body func(int) map[string]any,
+) ([][]float32, error) {
+ if n == 0 {
+ return nil, nil
+ }
+ if c.cfg.Settings.BatchMessages && n > 1 {
+ conversations := make([]any, n)
+ for i := range n {
+ conversations[i] = body(i)["messages"]
+ }
+ return c.post(ctx, c.body("messages", conversations, kind), n)
+ }
+ // A single input and older endpoints keep the original flat messages.
out := make([][]float32, n)
for i := range n {
vectors, err := c.post(ctx, body(i), 1)
diff --git a/internal/models/api/openaiembeddings/golden_test.go b/internal/models/api/openaiembeddings/golden_test.go
index cba9e8f52..cab32d969 100644
--- a/internal/models/api/openaiembeddings/golden_test.go
+++ b/internal/models/api/openaiembeddings/golden_test.go
@@ -160,8 +160,8 @@ func TestImageFormatDecidesWhetherImagesAreAccepted(t *testing.T) {
assert.True(t, newClient("u", api.EmbeddingsSettings{ImageFormat: api.EmbeddingImageMessages}, 0).AcceptsImages())
}
-// A conversation yields one vector, so a batch is one request per item, and
-// texts follow images into `messages` only when the row asks.
+// Endpoints without batch_messages keep one request per conversation, and
+// texts follow images into messages only when the row asks.
func TestMessagesFormatSendsOneRequestPerItem(t *testing.T) {
t.Setenv("SSRF_WHITELIST", "127.0.0.1")
var bodies []map[string]any
@@ -210,6 +210,78 @@ func TestMessagesFormatSendsOneRequestPerItem(t *testing.T) {
}}}, bodies[0]["messages"])
}
+func TestBatchMessagesPreservesInputsAndRequestSettings(t *testing.T) {
+ for _, images := range []bool{false, true} {
+ t.Run(fmt.Sprintf("images=%v", images), func(t *testing.T) {
+ var bodies []map[string]any
+ server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ var body map[string]any
+ require.NoError(t, json.NewDecoder(r.Body).Decode(&body))
+ bodies = append(bodies, body)
+ _, _ = w.Write([]byte(`{"data":[{"index":1,"embedding":[2]},{"index":0,"embedding":[1]}]}`))
+ }))
+ defer server.Close()
+ c := newClient(server.URL+"/v1", api.EmbeddingsSettings{
+ BatchMessages: true, TextAsMessages: true, ImageFormat: api.EmbeddingImageMessages,
+ ImagePrompt: "Represent the image.", SendEncodingFormat: true,
+ InputTypeField: "input_type", InputTypeValues: map[string]string{"query": "query"},
+ ExtraBody: map[string]any{"add_special_tokens": true},
+ }, 0)
+ var got [][]float32
+ var err error
+ if images {
+ got, err = c.EmbedImages(context.Background(), []api.EmbedImage{
+ {Data: []byte{1}, MIMEType: "image/png"}, {Data: []byte{2}, MIMEType: "image/png"},
+ }, api.EmbedQuery)
+ } else {
+ got, err = c.Embed(context.Background(), []string{"a", "b"}, api.EmbedQuery)
+ }
+ require.NoError(t, err)
+ assert.Equal(t, [][]float32{{1}, {2}}, got, "response indices restore input order")
+ require.Len(t, bodies, 1)
+ body := bodies[0]
+ assert.NotContains(t, body, "input")
+ assert.Equal(t, true, body["add_special_tokens"])
+ assert.Equal(t, "float", body["encoding_format"])
+ assert.Equal(t, "query", body["input_type"])
+ conversations := body["messages"].([]any)
+ require.Len(t, conversations, 2)
+ for i, conv := range conversations {
+ messages := conv.([]any)
+ require.Len(t, messages, 1)
+ turn := messages[0].(map[string]any)
+ assert.Equal(t, "user", turn["role"])
+ content := turn["content"].([]any)
+ if images {
+ require.Len(t, content, 2)
+ assert.Equal(t, api.EmbedImage{Data: []byte{byte(i + 1)}, MIMEType: "image/png"}.DataURI(),
+ content[0].(map[string]any)["image_url"].(map[string]any)["url"])
+ assert.Equal(t, "Represent the image.", content[1].(map[string]any)["text"])
+ } else {
+ require.Len(t, content, 1)
+ assert.Equal(t, []string{"a", "b"}[i], content[0].(map[string]any)["text"])
+ }
+ }
+ })
+ }
+}
+
+func TestBatchMessagesEmptySingletonAndInvalidResponses(t *testing.T) {
+ server, _, body := serve(t, `{"data":[{"index":0,"embedding":[1]}]}`)
+ defer server.Close()
+ c := newClient(server.URL, api.EmbeddingsSettings{TextAsMessages: true, BatchMessages: true}, 0)
+ got, err := c.Embed(context.Background(), nil, api.EmbedDocument)
+ require.NoError(t, err)
+ assert.Nil(t, got)
+ assert.Nil(t, *body, "empty input sends no request")
+ _, err = c.Embed(context.Background(), []string{"a"}, api.EmbedDocument)
+ require.NoError(t, err)
+ assert.IsType(t, map[string]any{}, (*body)["messages"].([]any)[0], "singleton keeps a flat conversation")
+ _, err = c.Embed(context.Background(), []string{"a", "b"}, api.EmbedDocument)
+ require.ErrorContains(t, err, "no embedding returned for input 1",
+ "never accept a fused or incomplete batch response")
+}
+
func TestDecodesArkTextResponse(t *testing.T) {
server, path, body := serve(t, arkTextResponse)
defer server.Close()
diff --git a/internal/models/catalog/data/models.generated.json b/internal/models/catalog/data/models.generated.json
index d86802439..ddc76689f 100644
--- a/internal/models/catalog/data/models.generated.json
+++ b/internal/models/catalog/data/models.generated.json
@@ -2066,6 +2066,8 @@
"source": "https://huggingface.co/Qwen/Qwen3-VL-Embedding-8B",
"compat": {
"text_as_messages": true,
+ "batch_messages": true,
+ "max_image_batch_size": 5,
"extra_body": {
"add_special_tokens": true
}
diff --git a/internal/models/catalog/data/overrides.json b/internal/models/catalog/data/overrides.json
index 5af829e5e..615a8f048 100644
--- a/internal/models/catalog/data/overrides.json
+++ b/internal/models/catalog/data/overrides.json
@@ -976,6 +976,8 @@
"type": "Embedding",
"compat": {
"text_as_messages": true,
+ "batch_messages": true,
+ "max_image_batch_size": 5,
"extra_body": {
"add_special_tokens": true
}
diff --git a/internal/models/embedding/image_wire_test.go b/internal/models/embedding/image_wire_test.go
index ae3c7a08a..48d2e6b31 100644
--- a/internal/models/embedding/image_wire_test.go
+++ b/internal/models/embedding/image_wire_test.go
@@ -197,8 +197,9 @@ func TestSelfHostedQwen3VLEmbeddingSendsTextAndImagesThroughTheTemplate(t *testi
got, err := e.BatchEmbed(types.WithEmbedQuery(context.Background()), []string{"ab", "c"})
require.NoError(t, err)
assert.Equal(t, [][]float32{{2}, {1}}, got)
- _, err = ie.BatchEmbedImages(context.Background(), pngs(1))
+ images, err := ie.BatchEmbedImages(context.Background(), pngs(6))
require.NoError(t, err)
+ assert.Equal(t, [][]float32{{1}, {2}, {3}, {4}, {5}, {6}}, images)
message := func(part map[string]any) map[string]any {
return map[string]any{
@@ -207,12 +208,35 @@ func TestSelfHostedQwen3VLEmbeddingSendsTextAndImagesThroughTheTemplate(t *testi
"messages": []any{map[string]any{"role": "user", "content": []any{part}}},
}
}
- require.Len(t, up.requests, 3, "the messages format carries one input per request")
- assert.Equal(t, message(map[string]any{"type": "text", "text": "ab"}), up.requests[0].body)
- assert.Equal(t, message(map[string]any{"type": "text", "text": "c"}), up.requests[1].body)
- assert.Equal(t, message(map[string]any{
- "type": "image_url", "image_url": map[string]any{"url": "data:image/png;base64,iQ=="},
- }), up.requests[2].body)
+ textBatch := message(nil)
+ textBatch["messages"] = []any{
+ message(map[string]any{"type": "text", "text": "ab"})["messages"],
+ message(map[string]any{"type": "text", "text": "c"})["messages"],
+ }
+ imageMessage := func(img Image) map[string]any {
+ return message(map[string]any{"type": "image_url", "image_url": map[string]any{"url": img.DataURI()}})
+ }
+ imageBatch := message(nil)
+ conversations := make([]any, 5)
+ for i, img := range pngs(5) {
+ conversations[i] = imageMessage(img)["messages"]
+ }
+ imageBatch["messages"] = conversations
+ require.Len(t, up.requests, 3, "one text batch and image batches of five and one")
+ assert.Equal(t, textBatch, up.requests[0].body)
+ assert.Equal(t, imageBatch, up.requests[1].body)
+ assert.Equal(t, imageMessage(pngs(6)[5]), up.requests[2].body)
+}
+
+func TestSelfHostedQwenMessagesBatchCanBeDisabledForOlderServers(t *testing.T) {
+ up := newUpstream(t)
+ e := imageEmbedder(t, up, "generic", "Qwen/Qwen3-VL-Embedding-8B", "/v1",
+ &types.ModelSpecOverride{Compat: map[string]any{"batch_messages": false}})
+ got, err := e.BatchEmbed(context.Background(), []string{"ab", "c"})
+ require.NoError(t, err)
+ assert.Equal(t, [][]float32{{2}, {1}}, got)
+ require.Len(t, up.requests, 2)
+ assert.IsType(t, map[string]any{}, up.requests[0].body["messages"].([]any)[0])
}
func TestImageEmbeddingRefusesWhatTheVendorDocumentsItWillNotTake(t *testing.T) {
diff --git a/internal/models/embedding/messages_batch_live_test.go b/internal/models/embedding/messages_batch_live_test.go
new file mode 100644
index 000000000..b80f45d0f
--- /dev/null
+++ b/internal/models/embedding/messages_batch_live_test.go
@@ -0,0 +1,158 @@
+package embedding
+
+import (
+ "context"
+ "encoding/json"
+ "math"
+ "os"
+ "slices"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/models/imageprep"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/panjf2000/ants/v2"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// Opt-in integration check against an operator-selected Qwen3-VL endpoint.
+// The fixture contains {"texts":[...],"image_paths":[...]} and stays outside
+// the repository. This only calls the embedding model; it never writes an index.
+// WEKNORA_EMBEDDING_TEST_URL is the base URL including /v1.
+// Private/IP endpoints need the usual explicit SSRF_WHITELIST setting.
+// A server without batch-invariant computation can fail the strict numerical
+// bounds below even when it accepts the batch and returns correctly ordered vectors.
+func TestLiveQwenMessagesBatchParity(t *testing.T) {
+ base := os.Getenv("WEKNORA_EMBEDDING_TEST_URL")
+ fixture := os.Getenv("WEKNORA_EMBEDDING_TEST_FIXTURE")
+ if base == "" || fixture == "" {
+ t.Skip("set WEKNORA_EMBEDDING_TEST_URL and WEKNORA_EMBEDDING_TEST_FIXTURE for live parity checks")
+ }
+ var inputs struct {
+ Texts []string `json:"texts"`
+ ImagePaths []string `json:"image_paths"`
+ }
+ raw, err := os.ReadFile(fixture)
+ require.NoError(t, err)
+ require.NoError(t, json.Unmarshal(raw, &inputs))
+ require.Greater(t, len(inputs.Texts), 1)
+ require.Greater(t, len(inputs.ImagePaths), 1)
+ t.Setenv("BATCH_EMBED_SIZE", "5")
+ pool, err := ants.NewPool(5)
+ require.NoError(t, err)
+ defer pool.Release()
+ config := Config{
+ Source: types.ModelSourceRemote, Provider: "generic", ModelName: "Qwen/Qwen3-VL-Embedding-8B",
+ BaseURL: base, APIKey: os.Getenv("WEKNORA_EMBEDDING_TEST_API_KEY"), Dimensions: 4096,
+ }
+ batched, err := NewEmbedder(config, NewBatchEmbedder(pool), nil)
+ require.NoError(t, err)
+ config.Spec = &types.ModelSpecOverride{Compat: map[string]any{"batch_messages": false}}
+ serial, err := NewEmbedder(config, NewBatchEmbedder(pool), nil)
+ require.NoError(t, err)
+ config.Spec = &types.ModelSpecOverride{Compat: map[string]any{
+ "batch_messages": true, "max_batch_size": 2, "max_image_batch_size": 2,
+ }}
+ smallBatch, err := NewEmbedder(config, NewBatchEmbedder(pool), nil)
+ require.NoError(t, err)
+ ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
+ defer cancel()
+
+ t.Run("texts", func(t *testing.T) {
+ start := time.Now()
+ want, err := serial.BatchEmbed(ctx, inputs.Texts)
+ require.NoError(t, err)
+ serialTime := time.Since(start)
+ start = time.Now()
+ got, err := batched.BatchEmbedWithPool(ctx, batched, inputs.Texts)
+ require.NoError(t, err)
+ t.Logf("inputs=%d serial=%s batch=%s", len(want), serialTime, time.Since(start))
+ assertLiveVectorParity(t, want, got)
+ repeat, err := serial.BatchEmbed(ctx, inputs.Texts)
+ require.NoError(t, err)
+ t.Log("repeated serial control")
+ assertLiveVectorParity(t, want, repeat)
+ got, err = smallBatch.BatchEmbed(ctx, inputs.Texts)
+ require.NoError(t, err)
+ t.Log("batch size two")
+ assertLiveVectorParity(t, want, got)
+ reversed := slices.Clone(inputs.Texts)
+ slices.Reverse(reversed)
+ got, err = batched.BatchEmbedWithPool(ctx, batched, reversed)
+ require.NoError(t, err)
+ slices.Reverse(got)
+ t.Log("reversed batch")
+ assertLiveVectorParity(t, want, got)
+ })
+ t.Run("images", func(t *testing.T) {
+ imageBatch, ok := AsImageEmbedder(batched)
+ require.True(t, ok)
+ imageSerial, ok := AsImageEmbedder(serial)
+ require.True(t, ok)
+ images := make([]Image, len(inputs.ImagePaths))
+ for i, path := range inputs.ImagePaths {
+ data, err := os.ReadFile(path)
+ require.NoError(t, err)
+ images[i], err = imageprep.Prepare(data, imageBatch.ImageLimits())
+ require.NoError(t, err)
+ }
+ start := time.Now()
+ want, err := imageSerial.BatchEmbedImages(ctx, images)
+ require.NoError(t, err)
+ serialTime := time.Since(start)
+ start = time.Now()
+ got, err := imageBatch.BatchEmbedImages(ctx, images)
+ require.NoError(t, err)
+ t.Logf("inputs=%d serial=%s batch=%s", len(want), serialTime, time.Since(start))
+ assertLiveVectorParity(t, want, got)
+ repeat, err := imageSerial.BatchEmbedImages(ctx, images)
+ require.NoError(t, err)
+ t.Log("repeated serial control")
+ assertLiveVectorParity(t, want, repeat)
+ imageSmall, ok := AsImageEmbedder(smallBatch)
+ require.True(t, ok)
+ got, err = imageSmall.BatchEmbedImages(ctx, images)
+ require.NoError(t, err)
+ t.Log("batch size two")
+ assertLiveVectorParity(t, want, got)
+ slices.Reverse(images)
+ got, err = imageBatch.BatchEmbedImages(ctx, images)
+ require.NoError(t, err)
+ slices.Reverse(got)
+ t.Log("reversed batch")
+ assertLiveVectorParity(t, want, got)
+ })
+}
+
+func assertLiveVectorParity(t *testing.T, want, got [][]float32) {
+ t.Helper()
+ require.Len(t, got, len(want))
+ maxAbs, minCos, unequal := 0.0, 1.0, 0
+ for i := range want {
+ require.Len(t, want[i], 4096)
+ require.Len(t, got[i], 4096)
+ var dot, a2, b2 float64
+ for j, a := range want[i] {
+ b := got[i][j]
+ af, bf := float64(a), float64(b)
+ require.False(t, math.IsNaN(af) || math.IsNaN(bf) || math.IsInf(af, 0) || math.IsInf(bf, 0))
+ maxAbs = math.Max(maxAbs, math.Abs(af-bf))
+ if a != b {
+ unequal++
+ }
+ dot += af * bf
+ a2 += af * af
+ b2 += bf * bf
+ }
+ require.Greater(t, a2, 0.0)
+ require.Greater(t, b2, 0.0)
+ minCos = math.Min(minCos, dot/math.Sqrt(a2*b2))
+ }
+ t.Logf("vectors=%d dimensions=4096 unequal_components=%d max_abs_diff=%.9g min_cosine=%.12f",
+ len(got), unequal, maxAbs, minCos)
+ // GPU batching may change low-order bits; do not confuse numerical
+ // equivalence with bit-for-bit reproducibility.
+ assert.GreaterOrEqual(t, minCos, 0.99999)
+ assert.LessOrEqual(t, maxAbs, 0.001)
+}
diff --git a/internal/models/embedding/wire_test.go b/internal/models/embedding/wire_test.go
index 16182b16b..9d896c8c4 100644
--- a/internal/models/embedding/wire_test.go
+++ b/internal/models/embedding/wire_test.go
@@ -119,9 +119,17 @@ func answer(path string, body map[string]any) string {
n := itemLen(body["input"].([]any)[0])
return fmt.Sprintf(`{"data":{"embedding":[%d],"object":"embedding"}}`, n)
case body["messages"] != nil:
- turn := body["messages"].([]any)[0].(map[string]any)
- n := itemLen(turn["content"].([]any)[0])
- return fmt.Sprintf(`{"data":[{"index":0,"embedding":[%d]}]}`, n)
+ messages := body["messages"].([]any)
+ conversations := []any{messages}
+ if _, batched := messages[0].([]any); batched {
+ conversations = messages
+ }
+ for i := len(conversations) - 1; i >= 0; i-- {
+ turn := conversations[i].([]any)[0].(map[string]any)
+ n := itemLen(turn["content"].([]any)[0])
+ parts = append(parts, fmt.Sprintf(`{"index":%d,"embedding":[%d]}`, i, n))
+ }
+ return `{"data":[` + strings.Join(parts, ",") + `]}`
default:
input := body["input"].([]any)
for i := len(input) - 1; i >= 0; i-- {
diff --git a/internal/models/parity/testdata/catalog-baseline.json b/internal/models/parity/testdata/catalog-baseline.json
index 5d852f6a3..4714fcac9 100644
--- a/internal/models/parity/testdata/catalog-baseline.json
+++ b/internal/models/parity/testdata/catalog-baseline.json
@@ -101,7 +101,7 @@
"gemini/KnowledgeQA/gemini-3.7-flash": "570b30391590c3fa380e98e8323bf2187635d18db427eae3d75f9e63def26c8d",
"gemini/KnowledgeQA/gemini-3.8-flash": "6d40802ed8d3b310e1e91c186f769a4f8a298138538853cf623ad43e59c29140",
"gemini/KnowledgeQA/gemini-3snapshot": "c5931f2304774b718637f47540e78b66cbf855b4a4189c9fc0cea2040a12951d",
- "generic/Embedding/snapshotqwen3-vl-embeddingsnapshot": "5b7394b420438753d8a7c4ad58af94ceab910f1e3497c0ccef357ca357f96626",
+ "generic/Embedding/snapshotqwen3-vl-embeddingsnapshot": "a1dedaaddb23ad1449d1aef38f0f032d7bcd834bdf079c511c65ec03cccfffe4",
"generic/KnowledgeQA/gpt-5snapshot": "3e3712264316db008c1465a2d7c395072d85942d0352196e456342cef0b14eb0",
"generic/KnowledgeQA/o1snapshot": "52340886b4160a0cb9342ae33a7c81304c9dad5d22c2d1c1ce073f89860a30b1",
"generic/KnowledgeQA/o3snapshot": "782e836769e56c43d9c954ab2d563df7d2f476ae4fb4d588bb8bf3c88ae42ce6",
diff --git a/website-docs/04-api/02-api-model-system.md b/website-docs/04-api/02-api-model-system.md
index 127cfdfbd..629f4c689 100644
--- a/website-docs/04-api/02-api-model-system.md
+++ b/website-docs/04-api/02-api-model-system.md
@@ -57,6 +57,10 @@ curl "$BASE/api/v1/models/catalog/resolve?provider=deepseek&model=deepseek-v4-pr
`parameters` 会按模型目录校验(未知协议、错误的 compat 键、非法思考等级返回 400),`base_url` 经过 SSRF 校验。
+自部署的 `generic` / `Qwen3-VL-Embedding` 默认通过二维 `messages` 批量提交独立输入(已验证 vLLM 0.29.0);单条输入保留一维会话格式。文本沿用 `BATCH_EMBED_SIZE` 分批,图片批量调用的默认上限为 5 张,这是客户端的保守分批设置,可通过 `parameters.spec.compat.max_image_batch_size` 调整。上传解析仍按单张图片调度任务,不会跨任务合并图片。旧版服务若不支持二维 `messages`,可设置 `parameters.spec.compat.batch_messages=false` 恢复逐条请求;其他模型仅在显式启用该能力时使用会话批处理。
+
+批处理保持各输入的会话内容和向量索引映射,但不保证服务端跨批大小计算逐位相同。要求严格可复现时,应验证部署端的数值行为;vLLM 的 [Batch Invariance](https://docs.vllm.ai/en/v0.29.0/features/batch_invariance/) 模式需要在服务端启用,并针对实际模型验证。可设置 `WEKNORA_EMBEDDING_TEST_URL` 和 `WEKNORA_EMBEDDING_TEST_FIXTURE` 后运行 `go test ./internal/models/embedding -run '^TestLiveQwenMessagesBatchParity$' -v -count=1`:fixture 为 `{"texts":[...],"image_paths":[...]}`,文本和图片均至少两个;私有/IP 端点需配置 `SSRF_WHITELIST`,鉴权可使用 `WEKNORA_EMBEDDING_TEST_API_KEY`。该测试比较逐条、分批、倒序和重复逐条请求,记录最大绝对误差与最低余弦相似度,超过严格阈值会失败,不写入知识库。
+
响应:201 `{"success":true,"data":{ModelResponse}}`(`id,name,type,source,parameters,is_default,is_builtin,status,credentials,capabilities,...`;响应不含密钥)
```bash