Skip to content

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

fix: report embedding dimension mismatches

十三分之五六七2544fedcd356
diff --git a/internal/application/service/knowledgebase_search.go b/internal/application/service/knowledgebase_search.go
index c4f7510d6..2be71595a 100644
--- a/internal/application/service/knowledgebase_search.go
+++ b/internal/application/service/knowledgebase_search.go
@@ -2,6 +2,7 @@ package service
import (
"context"
+ "fmt"
"github.com/Tencent/WeKnora/internal/application/service/retriever"
apperrors "github.com/Tencent/WeKnora/internal/errors"
@@ -41,7 +42,38 @@ func (s *knowledgeBaseService) GetQueryEmbedding(ctx context.Context, kbID strin
return nil, err
}
- return embeddingModel.Embed(ctx, queryText)
+ vector, err := embeddingModel.Embed(ctx, queryText)
+ if err != nil {
+ return nil, err
+ }
+ if err := validateQueryEmbeddingDimension(embeddingModel, len(vector)); err != nil {
+ logger.Errorf(ctx, "GetQueryEmbedding: %v", err)
+ return nil, err
+ }
+ return vector, nil
+}
+
+// validateQueryEmbeddingDimension catches provider/model configuration drift
+// before a malformed query reaches the vector store. Without this check, a
+// provider returning a different vector size is reported as the misleading
+// generic 2201 "bound store unavailable" error (or, for dimension-partitioned
+// stores, silently produces no matches).
+func validateQueryEmbeddingDimension(model embedding.Embedder, actual int) error {
+ if model == nil || actual == 0 {
+ return nil
+ }
+ expected := model.GetDimensions()
+ if expected <= 0 || expected == actual {
+ return nil
+ }
+ return apperrors.NewVectorStoreUnavailableError(
+ "embedding vector dimension does not match the configured model",
+ ).WithDetails(map[string]any{
+ "model": model.GetModelName(),
+ "expected_dimension": expected,
+ "actual_dimension": actual,
+ "hint": fmt.Sprintf("check the embedding model configuration and rebuild the affected index (%d dimensions)", expected),
+ })
}
// ResolveEmbeddingModelKeys resolves embedding model IDs to their actual model
@@ -479,6 +511,10 @@ func (s *knowledgeBaseService) resolveQueryEmbedding(
logger.Errorf(ctx, "Failed to embed query text, query text: %s, error: %v", params.QueryText, err)
return nil, err
}
+ if err := validateQueryEmbeddingDimension(embeddingModel, len(queryEmbedding)); err != nil {
+ logger.Errorf(ctx, "resolveQueryEmbedding: %v", err)
+ return nil, err
+ }
logger.Infof(ctx, "Query embedding generated successfully, embedding vector length: %d", len(queryEmbedding))
return queryEmbedding, nil
}
diff --git a/internal/application/service/knowledgebase_search_dimension_test.go b/internal/application/service/knowledgebase_search_dimension_test.go
new file mode 100644
index 000000000..d9c30e1e4
--- /dev/null
+++ b/internal/application/service/knowledgebase_search_dimension_test.go
@@ -0,0 +1,43 @@
+package service
+
+import (
+ "context"
+ "testing"
+
+ apperrors "github.com/Tencent/WeKnora/internal/errors"
+ "github.com/Tencent/WeKnora/internal/models/embedding"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+type dimensionTestEmbedder struct {
+ embedding.Embedder
+ name string
+ dimensions int
+}
+
+func (e dimensionTestEmbedder) GetModelName() string { return e.name }
+func (e dimensionTestEmbedder) GetDimensions() int { return e.dimensions }
+func (e dimensionTestEmbedder) Embed(context.Context, string) ([]float32, error) {
+ return make([]float32, 768), nil
+}
+
+func TestValidateQueryEmbeddingDimension(t *testing.T) {
+ err := validateQueryEmbeddingDimension(dimensionTestEmbedder{
+ name: "configured-embedding",
+ dimensions: 1536,
+ }, 768)
+ require.Error(t, err)
+ appErr, ok := err.(*apperrors.AppError)
+ require.True(t, ok)
+ assert.Equal(t, apperrors.ErrVectorStoreUnavailable, appErr.Code)
+ assert.Equal(t, "configured-embedding", appErr.Details.(map[string]any)["model"])
+ assert.Equal(t, 1536, appErr.Details.(map[string]any)["expected_dimension"])
+ assert.Equal(t, 768, appErr.Details.(map[string]any)["actual_dimension"])
+}
+
+func TestValidateQueryEmbeddingDimensionAllowsUnknownOrMatchingSize(t *testing.T) {
+ assert.NoError(t, validateQueryEmbeddingDimension(dimensionTestEmbedder{dimensions: 768}, 768))
+ assert.NoError(t, validateQueryEmbeddingDimension(dimensionTestEmbedder{dimensions: 0}, 768))
+ assert.NoError(t, validateQueryEmbeddingDimension(dimensionTestEmbedder{dimensions: 1536}, 0))
+}