From 53e0333a53d9192dfdbae54efc56b642fef10fe4 Mon Sep 17 00:00:00 2001 From: wizardchen Date: Mon, 15 Jun 2026 19:16:31 +0800 Subject: [PATCH] Add embedding dimension override support --- frontend/src/api/initialization/index.ts | 3 +- frontend/src/api/model/index.ts | 1 + frontend/src/components/ModelEditorDialog.vue | 18 +++- frontend/src/i18n/locales/en-US.ts | 2 + frontend/src/i18n/locales/ko-KR.ts | 2 + frontend/src/i18n/locales/ru-RU.ts | 2 + frontend/src/i18n/locales/zh-CN.ts | 2 + frontend/src/views/settings/ModelSettings.vue | 4 +- internal/handler/initialization.go | 24 +++--- internal/models/embedding/aliyun.go | 35 +++++--- internal/models/embedding/azure_openai.go | 48 ++++------- .../models/embedding/azure_openai_test.go | 14 +++- .../embedding/config_from_model_test.go | 8 +- .../embedding/dimensions_policy_test.go | 70 ++++++++++++++++ internal/models/embedding/embedder.go | 47 ++++++----- internal/models/embedding/gemini.go | 34 +++++--- internal/models/embedding/gemini_test.go | 30 ++++++- internal/models/embedding/jina.go | 26 +++--- internal/models/embedding/llm_debug.go | 6 +- internal/models/embedding/nvidia.go | 31 ++++--- internal/models/embedding/ollama.go | 25 ++++-- internal/models/embedding/openai.go | 33 +++++--- internal/models/embedding/openai_test.go | 82 +++++++++++++++++++ internal/models/embedding/volcengine.go | 37 ++++++--- internal/models/embedding/weknoracloud.go | 43 ++++++---- internal/models/embedding/zhipu.go | 33 +++++--- internal/types/model.go | 5 +- 27 files changed, 476 insertions(+), 189 deletions(-) create mode 100644 internal/models/embedding/dimensions_policy_test.go create mode 100644 internal/models/embedding/openai_test.go diff --git a/frontend/src/api/initialization/index.ts b/frontend/src/api/initialization/index.ts index 69ea5247..3e668cb3 100644 --- a/frontend/src/api/initialization/index.ts +++ b/frontend/src/api/initialization/index.ts @@ -312,6 +312,7 @@ export function testEmbeddingModel(modelConfig: { baseUrl?: string; apiKey?: string; dimension?: number; + supportsDimensionOverride?: boolean; provider?: string; modelId?: string; } & BaseModelTestPayload): Promise<{ available: boolean; message?: string; dimension?: number }> { @@ -571,4 +572,4 @@ export function listModelProviders(modelType?: string): Promise + :disabled="!formData.supportsDimensionOverride || (formData.source === 'local' && checking)" /> @@ -335,6 +335,14 @@

+
+ +
+ + {{ $t('model.editor.dimensionOverrideDesc') }} +
+
+
@@ -413,6 +421,7 @@ interface ModelFormData { baseUrl?: string apiKey?: string dimension?: number + supportsDimensionOverride?: boolean interfaceType?: 'ollama' | 'openai' isDefault: boolean supportsVision?: boolean @@ -806,6 +815,7 @@ const formData = ref({ baseUrl: '', apiKey: '', dimension: undefined, + supportsDimensionOverride: false, interfaceType: 'ollama', isDefault: false, supportsVision: false, @@ -938,6 +948,7 @@ const selectModelType = async (type: EditorModelType) => { } if (type !== 'embedding') { formData.value.dimension = undefined + formData.value.supportsDimensionOverride = false dimensionChecked.value = false dimensionSuccess.value = false dimensionMessage.value = '' @@ -1044,6 +1055,7 @@ const resetForm = () => { baseUrl: '', apiKey: '', dimension: undefined, // 默认不填,让用户手动输入或通过检测按钮获取 + supportsDimensionOverride: false, interfaceType: undefined, isDefault: false, supportsVision: false, @@ -1235,7 +1247,8 @@ const checkOllamaDimension = async () => { const result = await testEmbeddingModel({ source: 'local', modelName: formData.value.modelName, - dimension: formData.value.dimension + dimension: formData.value.dimension, + supportsDimensionOverride: formData.value.supportsDimensionOverride ?? false, }) dimensionChecked.value = true @@ -1322,6 +1335,7 @@ const checkRemoteAPI = async () => { baseUrl: formData.value.baseUrl, apiKey: formData.value.apiKey || '', dimension: formData.value.dimension, + supportsDimensionOverride: formData.value.supportsDimensionOverride ?? false, provider: formData.value.provider, ...idPayload, ...headerPayload, diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts index 3c55097d..08a7bbcf 100755 --- a/frontend/src/i18n/locales/en-US.ts +++ b/frontend/src/i18n/locales/en-US.ts @@ -3611,6 +3611,8 @@ export default { dimensionDetected: 'Detection succeeded. Vector dimension: {value}', dimensionFailed: 'Detection failed, please enter the dimension manually', remoteDimensionDetected: 'Detected vector dimension: {value}', + dimensionOverrideLabel: 'Custom Output Dimension', + dimensionOverrideDesc: 'Enable only if the provider documentation says this model accepts a dimensions parameter.', supportsVisionLabel: 'Supports Vision / Multimodal', supportsVisionDesc: 'Whether the model accepts image and multimodal input', thinkingControlLabel: 'Thinking mode request format', diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.ts index 4c03c5a6..8f731085 100755 --- a/frontend/src/i18n/locales/ko-KR.ts +++ b/frontend/src/i18n/locales/ko-KR.ts @@ -2668,6 +2668,8 @@ export default { dimensionDetected: "감지 성공, 벡터 차원: {value}", dimensionFailed: "감지 실패, 차원을 수동으로 입력해주세요", remoteDimensionDetected: "감지된 벡터 차원: {value}", + dimensionOverrideLabel: "사용자 지정 출력 차원", + dimensionOverrideDesc: "제공자 문서에서 이 모델이 dimensions 매개변수를 지원한다고 확인한 경우에만 켜세요.", supportsVisionLabel: "비전/멀티모달 지원", supportsVisionDesc: "모델의 이미지 등 멀티모달 입력 지원 여부", thinkingControlLabel: "사고 모드 매개변수 형식", diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts index 80a57668..95eafd8a 100755 --- a/frontend/src/i18n/locales/ru-RU.ts +++ b/frontend/src/i18n/locales/ru-RU.ts @@ -2385,6 +2385,8 @@ export default { dimensionDetected: 'Определение выполнено, размерность: {value}', dimensionFailed: 'Не удалось определить, введите размерность вручную', remoteDimensionDetected: 'Обнаружена размерность: {value}', + dimensionOverrideLabel: 'Пользовательская выходная размерность', + dimensionOverrideDesc: 'Включайте только если документация провайдера подтверждает поддержку параметра dimensions.', supportsVisionLabel: 'Поддержка визуального / мультимодального ввода', supportsVisionDesc: 'Поддерживает ли модель изображения и другой мультимодальный ввод', thinkingControlLabel: 'Формат параметров режима размышления', diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts index 8c7692a7..1d00156a 100755 --- a/frontend/src/i18n/locales/zh-CN.ts +++ b/frontend/src/i18n/locales/zh-CN.ts @@ -2670,6 +2670,8 @@ export default { dimensionDetected: "检测成功,向量维度:{value}", dimensionFailed: "检测失败,请手动输入维度", remoteDimensionDetected: "检测到向量维度:{value}", + dimensionOverrideLabel: "自定义输出维度", + dimensionOverrideDesc: "仅在确认该模型支持 dimensions 参数时开启;默认只使用检测到的实际维度。", supportsVisionLabel: "支持视觉/多模态", supportsVisionDesc: "模型是否支持图片等多模态输入", thinkingControlLabel: "思考模式参数格式", diff --git a/frontend/src/views/settings/ModelSettings.vue b/frontend/src/views/settings/ModelSettings.vue index 2763ab96..e6a1342d 100644 --- a/frontend/src/views/settings/ModelSettings.vue +++ b/frontend/src/views/settings/ModelSettings.vue @@ -166,6 +166,7 @@ function convertToLegacyFormat(model: ModelConfig) { apiKey: '', provider: model.parameters.provider || '', dimension: model.parameters.embedding_parameters?.dimension, + supportsDimensionOverride: model.parameters.embedding_parameters?.supports_dimension_override || false, isBuiltin: model.is_builtin || false, supportsVision: model.parameters.supports_vision || false, customHeaders: model.parameters.custom_headers @@ -415,7 +416,8 @@ const handleModelSave = async (modelData: any) => { ...(saveType === 'embedding' && modelData.dimension ? { embedding_parameters: { dimension: modelData.dimension, - truncate_prompt_tokens: 0 + truncate_prompt_tokens: 0, + supports_dimension_override: modelData.supportsDimensionOverride ?? false } } : {}), ...(saveType === 'vllm' ? { diff --git a/internal/handler/initialization.go b/internal/handler/initialization.go index 4e48d98e..434dfa01 100644 --- a/internal/handler/initialization.go +++ b/internal/handler/initialization.go @@ -1529,15 +1529,16 @@ func (h *InitializationHandler) buildConfigResponse(ctx context.Context, models // 所有 provider/model 通用字段都在这里集中声明;若未来新增字段(比如现在的 // custom_headers),只需改一处,生产路径和测试路径会同时生效。 type ModelTestRequest struct { - Source string `json:"source"` // 为空时按需默认为 "remote" - ModelName string `json:"modelName" binding:"required"` - BaseURL string `json:"baseUrl"` - APIKey string `json:"apiKey"` - Provider string `json:"provider"` - InterfaceType string `json:"interfaceType,omitempty"` - Dimension int `json:"dimension,omitempty"` - CustomHeaders map[string]string `json:"customHeaders,omitempty"` - ExtraConfig map[string]string `json:"extraConfig,omitempty"` + Source string `json:"source"` // 为空时按需默认为 "remote" + ModelName string `json:"modelName" binding:"required"` + BaseURL string `json:"baseUrl"` + APIKey string `json:"apiKey"` + Provider string `json:"provider"` + InterfaceType string `json:"interfaceType,omitempty"` + Dimension int `json:"dimension,omitempty"` + SupportsDimensionOverride bool `json:"supportsDimensionOverride,omitempty"` + CustomHeaders map[string]string `json:"customHeaders,omitempty"` + ExtraConfig map[string]string `json:"extraConfig,omitempty"` // AppSecret 用于 LKEAP Rerank 等需要第二段密钥的场景(对应模型 Parameters.AppSecret)。 AppSecret string `json:"appSecret,omitempty"` // ModelID, when set, instructs the handler to substitute any missing @@ -1620,8 +1621,9 @@ func (h *InitializationHandler) buildTestModel( ExtraConfig: req.ExtraConfig, CustomHeaders: req.CustomHeaders, EmbeddingParameters: types.EmbeddingParameters{ - Dimension: req.Dimension, - TruncatePromptTokens: 256, + Dimension: req.Dimension, + TruncatePromptTokens: 256, + SupportsDimensionOverride: req.SupportsDimensionOverride, }, }, } diff --git a/internal/models/embedding/aliyun.go b/internal/models/embedding/aliyun.go index 70c6bce6..5580fd2c 100644 --- a/internal/models/embedding/aliyun.go +++ b/internal/models/embedding/aliyun.go @@ -21,16 +21,17 @@ const ( // AliyunEmbedder implements text vectorization using Aliyun DashScope multimodal embedding API type AliyunEmbedder struct { - apiKey string - baseURL string - modelName string - truncatePromptTokens int - dimensions int - modelID string - httpClient *http.Client - timeout time.Duration - maxRetries int - customHeaders map[string]string + apiKey string + baseURL string + modelName string + truncatePromptTokens int + dimensions int + modelID string + httpClient *http.Client + timeout time.Duration + maxRetries int + customHeaders map[string]string + supportsDimensionOverride bool EmbedderPooler } @@ -39,6 +40,10 @@ func (e *AliyunEmbedder) SetCustomHeaders(headers map[string]string) { e.customHeaders = headers } +func (e *AliyunEmbedder) SetSupportsDimensionOverride(supported bool) { + e.supportsDimensionOverride = supported +} + // AliyunEmbedParameters represents the parameters for Aliyun DashScope multimodal embedding type AliyunEmbedParameters struct { Dimension int `json:"dimension,omitempty"` @@ -46,8 +51,8 @@ type AliyunEmbedParameters struct { // AliyunEmbedRequest represents an Aliyun DashScope multimodal embedding request type AliyunEmbedRequest struct { - Model string `json:"model"` - Input AliyunEmbedInput `json:"input"` + Model string `json:"model"` + Input AliyunEmbedInput `json:"input"` Parameters *AliyunEmbedParameters `json:"parameters,omitempty"` } @@ -194,7 +199,7 @@ func (e *AliyunEmbedder) BatchEmbed(ctx context.Context, texts []string) ([][]fl Contents: contents, }, } - if e.dimensions > 0 { + if e.supportsDimensionsParam() { reqBody.Parameters = &AliyunEmbedParameters{Dimension: e.dimensions} } @@ -253,6 +258,10 @@ func (e *AliyunEmbedder) GetModelName() string { return e.modelName } +func (e *AliyunEmbedder) supportsDimensionsParam() bool { + return e.supportsDimensionOverride && e.dimensions > 0 +} + // GetDimensions returns the vector dimensions func (e *AliyunEmbedder) GetDimensions() int { return e.dimensions diff --git a/internal/models/embedding/azure_openai.go b/internal/models/embedding/azure_openai.go index 1a3d58bf..c4a068ec 100644 --- a/internal/models/embedding/azure_openai.go +++ b/internal/models/embedding/azure_openai.go @@ -7,7 +7,6 @@ import ( "fmt" "io" "net/http" - "strings" "time" "github.com/Tencent/WeKnora/internal/logger" @@ -16,16 +15,17 @@ import ( // AzureOpenAIEmbedder implements text vectorization using Azure OpenAI API type AzureOpenAIEmbedder struct { - apiKey string - baseURL string - modelName string - truncatePromptTokens int - dimensions int - modelID string - apiVersion string - httpClient *http.Client - maxRetries int - customHeaders map[string]string + apiKey string + baseURL string + modelName string + truncatePromptTokens int + dimensions int + modelID string + apiVersion string + httpClient *http.Client + maxRetries int + customHeaders map[string]string + supportsDimensionOverride bool EmbedderPooler } @@ -34,6 +34,10 @@ func (e *AzureOpenAIEmbedder) SetCustomHeaders(headers map[string]string) { e.customHeaders = headers } +func (e *AzureOpenAIEmbedder) SetSupportsDimensionOverride(supported bool) { + e.supportsDimensionOverride = supported +} + type azureOpenAIEmbedRequest struct { Model string `json:"model"` Input []string `json:"input"` @@ -175,27 +179,7 @@ func (e *AzureOpenAIEmbedder) doRequestWithRetry(ctx context.Context, jsonData [ } func (e *AzureOpenAIEmbedder) supportsDimensionsParam() bool { - if e.dimensions <= 0 { - return false - } - - // Azure only supports the dimensions parameter on newer embeddings APIs. - if strings.TrimSpace(e.apiVersion) < "2024-10-21" { - return false - } - - modelRef := strings.ToLower(strings.TrimSpace(e.modelID)) - if modelRef == "" { - modelRef = strings.ToLower(strings.TrimSpace(e.modelName)) - } - - // Fixed-dimension legacy models reject the field entirely. - if strings.Contains(modelRef, "ada-002") { - return false - } - - return strings.Contains(modelRef, "text-embedding-3-small") || - strings.Contains(modelRef, "text-embedding-3-large") + return e.supportsDimensionOverride && e.dimensions > 0 } func (e *AzureOpenAIEmbedder) GetModelName() string { return e.modelName } diff --git a/internal/models/embedding/azure_openai_test.go b/internal/models/embedding/azure_openai_test.go index 1e4d7212..b81110ef 100644 --- a/internal/models/embedding/azure_openai_test.go +++ b/internal/models/embedding/azure_openai_test.go @@ -47,6 +47,7 @@ func TestAzureOpenAIEmbedderBatchEmbedSendsConfiguredDimensions(t *testing.T) { if err != nil { t.Fatalf("create embedder: %v", err) } + embedder.SetSupportsDimensionOverride(true) embedder.httpClient = &http.Client{Transport: transport} if _, err := embedder.BatchEmbed(context.Background(), []string{"hello"}); err != nil { @@ -63,7 +64,7 @@ func TestAzureOpenAIEmbedderBatchEmbedSendsConfiguredDimensions(t *testing.T) { } } -func TestAzureOpenAIEmbedderBatchEmbedOmitsDimensionsForFixedSizeModels(t *testing.T) { +func TestAzureOpenAIEmbedderBatchEmbedOmitsDimensionsByDefault(t *testing.T) { t.Parallel() var requestBody map[string]any @@ -103,7 +104,7 @@ func TestAzureOpenAIEmbedderBatchEmbedOmitsDimensionsForFixedSizeModels(t *testi } } -func TestAzureOpenAIEmbedderBatchEmbedOmitsDimensionsForOlderAPIVersion(t *testing.T) { +func TestAzureOpenAIEmbedderBatchEmbedSendsDimensionsWhenOverrideEnabledRegardlessOfAPIVersion(t *testing.T) { t.Parallel() var requestBody map[string]any @@ -132,14 +133,19 @@ func TestAzureOpenAIEmbedderBatchEmbedOmitsDimensionsForOlderAPIVersion(t *testi if err != nil { t.Fatalf("create embedder: %v", err) } + embedder.SetSupportsDimensionOverride(true) embedder.httpClient = &http.Client{Transport: transport} if _, err := embedder.BatchEmbed(context.Background(), []string{"hello"}); err != nil { t.Fatalf("BatchEmbed returned error: %v", err) } - if _, ok := requestBody["dimensions"]; ok { - t.Fatalf("expected request body to omit dimensions for older API versions, got %v", requestBody) + got, ok := requestBody["dimensions"] + if !ok { + t.Fatalf("expected request body to include dimensions when override is enabled, got %v", requestBody) + } + if got != float64(256) { + t.Fatalf("unexpected dimensions value: got %v want 256", got) } } diff --git a/internal/models/embedding/config_from_model_test.go b/internal/models/embedding/config_from_model_test.go index dc4a335e..43822998 100644 --- a/internal/models/embedding/config_from_model_test.go +++ b/internal/models/embedding/config_from_model_test.go @@ -16,8 +16,9 @@ func TestConfigFromModel(t *testing.T) { APIKey: "sk-xxx", Provider: "openai", EmbeddingParameters: types.EmbeddingParameters{ - Dimension: 1536, - TruncatePromptTokens: 512, + Dimension: 1536, + TruncatePromptTokens: 512, + SupportsDimensionOverride: true, }, ExtraConfig: map[string]string{"region": "us-east"}, CustomHeaders: map[string]string{"X-Gateway": "g1"}, @@ -31,6 +32,9 @@ func TestConfigFromModel(t *testing.T) { if cfg.Dimensions != 1536 || cfg.TruncatePromptTokens != 512 { t.Errorf("embedding params mismatch: %+v", cfg) } + if !cfg.SupportsDimensionOverride { + t.Errorf("SupportsDimensionOverride not propagated: %+v", cfg) + } if cfg.CustomHeaders["X-Gateway"] != "g1" { t.Errorf("CustomHeaders not propagated: %+v", cfg.CustomHeaders) } diff --git a/internal/models/embedding/dimensions_policy_test.go b/internal/models/embedding/dimensions_policy_test.go new file mode 100644 index 00000000..2353bcb9 --- /dev/null +++ b/internal/models/embedding/dimensions_policy_test.go @@ -0,0 +1,70 @@ +package embedding + +import "testing" + +func TestEmbeddingDimensionsParamRequiresExplicitOverride(t *testing.T) { + tests := []struct { + name string + supports func(bool) bool + }{ + { + name: "aliyun", + supports: func(enabled bool) bool { + e := &AliyunEmbedder{dimensions: 1024} + e.SetSupportsDimensionOverride(enabled) + return e.supportsDimensionsParam() + }, + }, + { + name: "nvidia", + supports: func(enabled bool) bool { + e := &NvidiaEmbedder{dimensions: 1024} + e.SetSupportsDimensionOverride(enabled) + return e.supportsDimensionsParam() + }, + }, + { + name: "volcengine", + supports: func(enabled bool) bool { + e := &VolcengineEmbedder{dimensions: 1024} + e.SetSupportsDimensionOverride(enabled) + return e.supportsDimensionsParam() + }, + }, + { + name: "zhipu", + supports: func(enabled bool) bool { + e := &ZhipuEmbedder{dimensions: 1024} + e.SetSupportsDimensionOverride(enabled) + return e.supportsDimensionsParam() + }, + }, + { + name: "azure_openai", + supports: func(enabled bool) bool { + e := &AzureOpenAIEmbedder{dimensions: 1024} + e.SetSupportsDimensionOverride(enabled) + return e.supportsDimensionsParam() + }, + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + if got := tt.supports(false); got { + t.Fatalf("supportsDimensionsParam() = true with override disabled") + } + if got := tt.supports(true); !got { + t.Fatalf("supportsDimensionsParam() = false with override enabled") + } + }) + } +} + +func TestEmbeddingDimensionsParamRequiresPositiveDimension(t *testing.T) { + e := &OpenAIEmbedder{dimensions: 0} + e.SetSupportsDimensionOverride(true) + if e.supportsDimensionsParam() { + t.Fatal("expected dimensions param to be omitted when configured dimension is zero") + } +} diff --git a/internal/models/embedding/embedder.go b/internal/models/embedding/embedder.go index 8279c6fe..1d377828 100644 --- a/internal/models/embedding/embedder.go +++ b/internal/models/embedding/embedder.go @@ -41,15 +41,16 @@ type EmbedderType string // Config represents the embedder configuration type Config struct { - Source types.ModelSource `json:"source"` - BaseURL string `json:"base_url"` - ModelName string `json:"model_name"` - APIKey string `json:"api_key"` - TruncatePromptTokens int `json:"truncate_prompt_tokens"` - Dimensions int `json:"dimensions"` - ModelID string `json:"model_id"` - Provider string `json:"provider"` - ExtraConfig map[string]string `json:"extra_config"` + Source types.ModelSource `json:"source"` + BaseURL string `json:"base_url"` + ModelName string `json:"model_name"` + APIKey string `json:"api_key"` + TruncatePromptTokens int `json:"truncate_prompt_tokens"` + Dimensions int `json:"dimensions"` + SupportsDimensionOverride bool `json:"supports_dimension_override"` + ModelID string `json:"model_id"` + Provider string `json:"provider"` + ExtraConfig map[string]string `json:"extra_config"` // CustomHeaders 允许在调用远程 API 时附加自定义 HTTP 请求头(类似 OpenAI Python SDK 的 extra_headers)。 CustomHeaders map[string]string `json:"custom_headers"` AppID string @@ -64,18 +65,19 @@ func ConfigFromModel(m *types.Model, appID, appSecret string) Config { return Config{} } return Config{ - Source: m.Source, - BaseURL: m.Parameters.BaseURL, - APIKey: m.Parameters.APIKey, - ModelID: m.ID, - ModelName: m.Name, - Dimensions: m.Parameters.EmbeddingParameters.Dimension, - TruncatePromptTokens: m.Parameters.EmbeddingParameters.TruncatePromptTokens, - Provider: m.Parameters.Provider, - ExtraConfig: m.Parameters.ExtraConfig, - CustomHeaders: m.Parameters.CustomHeaders, - AppID: appID, - AppSecret: appSecret, + Source: m.Source, + BaseURL: m.Parameters.BaseURL, + APIKey: m.Parameters.APIKey, + ModelID: m.ID, + ModelName: m.Name, + Dimensions: m.Parameters.EmbeddingParameters.Dimension, + SupportsDimensionOverride: m.Parameters.EmbeddingParameters.SupportsDimensionOverride, + TruncatePromptTokens: m.Parameters.EmbeddingParameters.TruncatePromptTokens, + Provider: m.Parameters.Provider, + ExtraConfig: m.Parameters.ExtraConfig, + CustomHeaders: m.Parameters.CustomHeaders, + AppID: appID, + AppSecret: appSecret, } } @@ -85,6 +87,9 @@ func NewEmbedder(config Config, pooler EmbedderPooler, ollamaService *ollama.Oll if err != nil { return e, err } + if setter, ok := e.(interface{ SetSupportsDimensionOverride(bool) }); ok { + setter.SetSupportsDimensionOverride(config.SupportsDimensionOverride) + } if logger.LLMDebugEnabled() { e = &debugEmbedder{inner: e} } diff --git a/internal/models/embedding/gemini.go b/internal/models/embedding/gemini.go index 718f6d2b..589eeed0 100644 --- a/internal/models/embedding/gemini.go +++ b/internal/models/embedding/gemini.go @@ -19,16 +19,17 @@ const geminiEmbeddingBaseURL = "https://generativelanguage.googleapis.com/v1beta // GeminiEmbedder implements text vectorization using the native Gemini // embedContent / batchEmbedContents REST API. type GeminiEmbedder struct { - apiKey string - baseURL string - modelName string - truncatePromptTokens int - dimensions int - modelID string - httpClient *http.Client - timeout time.Duration - maxRetries int - customHeaders map[string]string + apiKey string + baseURL string + modelName string + truncatePromptTokens int + dimensions int + modelID string + httpClient *http.Client + timeout time.Duration + maxRetries int + customHeaders map[string]string + supportsDimensionOverride bool EmbedderPooler } @@ -96,6 +97,10 @@ func (e *GeminiEmbedder) SetCustomHeaders(headers map[string]string) { e.customHeaders = headers } +func (e *GeminiEmbedder) SetSupportsDimensionOverride(supported bool) { + e.supportsDimensionOverride = supported +} + func (e *GeminiEmbedder) Embed(ctx context.Context, text string) ([]float32, error) { embeddings, err := e.BatchEmbed(ctx, []string{text}) if err != nil { @@ -114,13 +119,16 @@ func (e *GeminiEmbedder) BatchEmbed(ctx context.Context, texts []string) ([][]fl requests := make([]geminiEmbedRequest, 0, len(texts)) for _, text := range texts { - requests = append(requests, geminiEmbedRequest{ + req := geminiEmbedRequest{ Model: "models/" + e.modelName, Content: geminiContent{Parts: []geminiPart{ {Text: text}, }}, - OutputDimensionality: e.dimensions, - }) + } + if e.supportsDimensionOverride && e.dimensions > 0 { + req.OutputDimensionality = e.dimensions + } + requests = append(requests, req) } jsonData, err := json.Marshal(geminiBatchEmbedRequest{Requests: requests}) diff --git a/internal/models/embedding/gemini_test.go b/internal/models/embedding/gemini_test.go index 6c96cbcf..31babede 100644 --- a/internal/models/embedding/gemini_test.go +++ b/internal/models/embedding/gemini_test.go @@ -54,8 +54,8 @@ func TestGeminiEmbedderBatchEmbedUsesNativeAPI(t *testing.T) { if gotReq.Requests[0].Model != "models/gemini-embedding-2" { t.Fatalf("request model = %q", gotReq.Requests[0].Model) } - if gotReq.Requests[0].OutputDimensionality != 768 { - t.Fatalf("output_dimensionality = %d", gotReq.Requests[0].OutputDimensionality) + if gotReq.Requests[0].OutputDimensionality != 0 { + t.Fatalf("output_dimensionality = %d, want omitted by default", gotReq.Requests[0].OutputDimensionality) } if gotReq.Requests[0].Content.Parts[0].Text != "hello" { t.Fatalf("first text = %q", gotReq.Requests[0].Content.Parts[0].Text) @@ -65,6 +65,32 @@ func TestGeminiEmbedderBatchEmbedUsesNativeAPI(t *testing.T) { } } +func TestGeminiEmbedderBatchEmbedSendsOutputDimensionalityWhenOverrideEnabled(t *testing.T) { + var gotReq geminiBatchEmbedRequest + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if err := json.NewDecoder(r.Body).Decode(&gotReq); err != nil { + t.Fatalf("decode request: %v", err) + } + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"embeddings":[{"values":[0.1,0.2]}]}`)) + })) + defer server.Close() + + embedder, err := NewGeminiEmbedder("test-key", server.URL, "gemini-embedding-2", + 0, 768, "model-id", nil) + if err != nil { + t.Fatalf("NewGeminiEmbedder: %v", err) + } + embedder.SetSupportsDimensionOverride(true) + + if _, err := embedder.BatchEmbed(context.Background(), []string{"hello"}); err != nil { + t.Fatalf("BatchEmbed: %v", err) + } + if gotReq.Requests[0].OutputDimensionality != 768 { + t.Fatalf("output_dimensionality = %d, want 768", gotReq.Requests[0].OutputDimensionality) + } +} + func TestGeminiEmbedderReturnsAPIErrorBody(t *testing.T) { server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { http.Error(w, `{"error":"not found"}`, http.StatusNotFound) diff --git a/internal/models/embedding/jina.go b/internal/models/embedding/jina.go index 78711db1..770e6006 100644 --- a/internal/models/embedding/jina.go +++ b/internal/models/embedding/jina.go @@ -16,15 +16,16 @@ import ( // JinaEmbedder implements text vectorization functionality using Jina AI API // Jina API is mostly OpenAI-compatible but does NOT support truncate_prompt_tokens type JinaEmbedder struct { - apiKey string - baseURL string - modelName string - dimensions int - modelID string - httpClient *http.Client - timeout time.Duration - maxRetries int - customHeaders map[string]string + apiKey string + baseURL string + modelName string + dimensions int + modelID string + httpClient *http.Client + timeout time.Duration + maxRetries int + customHeaders map[string]string + supportsDimensionOverride bool EmbedderPooler } @@ -33,6 +34,10 @@ func (e *JinaEmbedder) SetCustomHeaders(headers map[string]string) { e.customHeaders = headers } +func (e *JinaEmbedder) SetSupportsDimensionOverride(supported bool) { + e.supportsDimensionOverride = supported +} + // JinaEmbedRequest represents a Jina embedding request // Note: Jina uses 'truncate' (boolean) instead of 'truncate_prompt_tokens' (integer) type JinaEmbedRequest struct { @@ -146,8 +151,7 @@ func (e *JinaEmbedder) BatchEmbed(ctx context.Context, texts []string) ([][]floa Truncate: true, // Enable truncation for long texts } - // Only include dimensions if specified and greater than 0 - if e.dimensions > 0 { + if e.supportsDimensionOverride && e.dimensions > 0 { reqBody.Dimensions = e.dimensions } diff --git a/internal/models/embedding/llm_debug.go b/internal/models/embedding/llm_debug.go index 1900d268..c891f02b 100644 --- a/internal/models/embedding/llm_debug.go +++ b/internal/models/embedding/llm_debug.go @@ -32,9 +32,9 @@ func (d *debugEmbedder) BatchEmbedWithPool(ctx context.Context, model Embedder, return d.inner.BatchEmbedWithPool(ctx, d, texts) } -func (d *debugEmbedder) GetModelName() string { return d.inner.GetModelName() } -func (d *debugEmbedder) GetDimensions() int { return d.inner.GetDimensions() } -func (d *debugEmbedder) GetModelID() string { return d.inner.GetModelID() } +func (d *debugEmbedder) GetModelName() string { return d.inner.GetModelName() } +func (d *debugEmbedder) GetDimensions() int { return d.inner.GetDimensions() } +func (d *debugEmbedder) GetModelID() string { return d.inner.GetModelID() } func singleToDouble(v []float32) [][]float32 { if v == nil { diff --git a/internal/models/embedding/nvidia.go b/internal/models/embedding/nvidia.go index f1566b8b..03f39448 100644 --- a/internal/models/embedding/nvidia.go +++ b/internal/models/embedding/nvidia.go @@ -16,15 +16,16 @@ import ( // NvidiaEmbedder implements text vectorization functionality using NVIDIA API type NvidiaEmbedder struct { - apiKey string - baseURL string - modelName string - dimensions int - modelID string - httpClient *http.Client - timeout time.Duration - maxRetries int - customHeaders map[string]string + apiKey string + baseURL string + modelName string + dimensions int + modelID string + httpClient *http.Client + timeout time.Duration + maxRetries int + customHeaders map[string]string + supportsDimensionOverride bool EmbedderPooler } @@ -33,6 +34,10 @@ func (e *NvidiaEmbedder) SetCustomHeaders(headers map[string]string) { e.customHeaders = headers } +func (e *NvidiaEmbedder) SetSupportsDimensionOverride(supported bool) { + e.supportsDimensionOverride = supported +} + // NvidiaEmbedRequest represents an NVIDIA embedding request type NvidiaEmbedRequest struct { Model string `json:"model"` @@ -145,9 +150,11 @@ func (e *NvidiaEmbedder) BatchEmbed(ctx context.Context, texts []string) ([][]fl Model: e.modelName, Input: texts, EncodingFormat: "float", - Dimensions: e.dimensions, InputType: "passage", } + if e.supportsDimensionsParam() { + reqBody.Dimensions = e.dimensions + } isQuery, _ := ctx.Value(types.EmbedQueryContextKey).(bool) if isQuery { reqBody.InputType = "query" @@ -202,6 +209,10 @@ func (e *NvidiaEmbedder) GetModelName() string { return e.modelName } +func (e *NvidiaEmbedder) supportsDimensionsParam() bool { + return e.supportsDimensionOverride && e.dimensions > 0 +} + // GetDimensions returns the vector dimensions func (e *NvidiaEmbedder) GetDimensions() int { return e.dimensions diff --git a/internal/models/embedding/ollama.go b/internal/models/embedding/ollama.go index e47df3e2..daf11577 100644 --- a/internal/models/embedding/ollama.go +++ b/internal/models/embedding/ollama.go @@ -12,11 +12,12 @@ import ( // OllamaEmbedder implements text vectorization functionality using Ollama type OllamaEmbedder struct { - modelName string - truncatePromptTokens int - ollamaService *ollama.OllamaService - dimensions int - modelID string + modelName string + truncatePromptTokens int + ollamaService *ollama.OllamaService + dimensions int + modelID string + supportsDimensionOverride bool EmbedderPooler } @@ -65,6 +66,10 @@ func (e *OllamaEmbedder) ensureModelAvailable(ctx context.Context) error { return e.ollamaService.EnsureModelAvailable(ctx, e.modelName) } +func (e *OllamaEmbedder) SetSupportsDimensionOverride(supported bool) { + e.supportsDimensionOverride = supported +} + // Embed converts text to vector func (e *OllamaEmbedder) Embed(ctx context.Context, text string) ([]float32, error) { embedding, err := e.BatchEmbed(ctx, []string{text}) @@ -88,10 +93,12 @@ func (e *OllamaEmbedder) BatchEmbed(ctx context.Context, texts []string) ([][]fl // Create request req := &ollamaapi.EmbedRequest{ - Model: e.modelName, - Input: texts, - Dimensions: e.dimensions, - Options: make(map[string]interface{}), + Model: e.modelName, + Input: texts, + Options: make(map[string]interface{}), + } + if e.supportsDimensionOverride && e.dimensions > 0 { + req.Dimensions = e.dimensions } // Set truncation parameters diff --git a/internal/models/embedding/openai.go b/internal/models/embedding/openai.go index 71fdc3a0..fce035ad 100644 --- a/internal/models/embedding/openai.go +++ b/internal/models/embedding/openai.go @@ -15,16 +15,17 @@ import ( // OpenAIEmbedder implements text vectorization functionality using OpenAI API type OpenAIEmbedder struct { - apiKey string - baseURL string - modelName string - truncatePromptTokens int - dimensions int - modelID string - httpClient *http.Client - timeout time.Duration - maxRetries int - customHeaders map[string]string + apiKey string + baseURL string + modelName string + truncatePromptTokens int + dimensions int + modelID string + httpClient *http.Client + timeout time.Duration + maxRetries int + customHeaders map[string]string + supportsDimensionOverride bool EmbedderPooler } @@ -88,6 +89,10 @@ func (e *OpenAIEmbedder) SetCustomHeaders(headers map[string]string) { e.customHeaders = headers } +func (e *OpenAIEmbedder) SetSupportsDimensionOverride(supported bool) { + e.supportsDimensionOverride = supported +} + // Embed converts text to vector func (e *OpenAIEmbedder) Embed(ctx context.Context, text string) ([]float32, error) { for range 3 { @@ -162,9 +167,11 @@ func (e *OpenAIEmbedder) BatchEmbed(ctx context.Context, texts []string) ([][]fl Model: e.modelName, Input: texts, EncodingFormat: "float", - Dimensions: e.dimensions, TruncatePromptTokens: e.truncatePromptTokens, } + if e.supportsDimensionsParam() { + reqBody.Dimensions = e.dimensions + } jsonData, err := json.Marshal(reqBody) if err != nil { @@ -248,6 +255,10 @@ func (e *OpenAIEmbedder) GetModelName() string { return e.modelName } +func (e *OpenAIEmbedder) supportsDimensionsParam() bool { + return e.supportsDimensionOverride && e.dimensions > 0 +} + // GetDimensions returns the vector dimensions func (e *OpenAIEmbedder) GetDimensions() int { return e.dimensions diff --git a/internal/models/embedding/openai_test.go b/internal/models/embedding/openai_test.go new file mode 100644 index 00000000..95ff4aee --- /dev/null +++ b/internal/models/embedding/openai_test.go @@ -0,0 +1,82 @@ +package embedding + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "testing" +) + +func TestOpenAIEmbedderBatchEmbedOmitsDimensionsByDefault(t *testing.T) { + requestBody := captureOpenAIEmbeddingRequest(t, "text-embedding-3-small", 256, false) + + if _, ok := requestBody["dimensions"]; ok { + t.Fatalf("expected request body to omit dimensions by default, got %v", requestBody) + } +} + +func TestOpenAIEmbedderBatchEmbedSendsDimensionsWhenOverrideEnabled(t *testing.T) { + requestBody := captureOpenAIEmbeddingRequest(t, "text-embedding-3-small", 256, true) + + got, ok := requestBody["dimensions"] + if !ok { + t.Fatalf("expected request body to include dimensions, got %v", requestBody) + } + if got != float64(256) { + t.Fatalf("unexpected dimensions value: got %v want 256", got) + } +} + +func TestOpenAIEmbedderBatchEmbedOmitsDimensionsForOpenAICompatibleModels(t *testing.T) { + requestBody := captureOpenAIEmbeddingRequest(t, "text-embedding-v3", 1024, false) + + if _, ok := requestBody["dimensions"]; ok { + t.Fatalf("expected request body to omit dimensions for OpenAI-compatible model, got %v", requestBody) + } +} + +func TestOpenAIEmbedderBatchEmbedOmitsDimensionsForFixedSizeModels(t *testing.T) { + requestBody := captureOpenAIEmbeddingRequest(t, "text-embedding-ada-002", 1536, false) + + if _, ok := requestBody["dimensions"]; ok { + t.Fatalf("expected request body to omit dimensions for fixed-size model, got %v", requestBody) + } +} + +func captureOpenAIEmbeddingRequest(t *testing.T, modelName string, dimensions int, supportsDimensionOverride bool) map[string]any { + t.Helper() + + requestBody := map[string]any{} + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + if r.URL.Path != "/embeddings" { + t.Fatalf("unexpected request path: %s", r.URL.Path) + } + if err := json.NewDecoder(r.Body).Decode(&requestBody); err != nil { + t.Fatalf("decode request body: %v", err) + } + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"data":[{"embedding":[0.1,0.2],"index":0}]}`)) + })) + defer server.Close() + + embedder, err := NewOpenAIEmbedder( + "test-key", + server.URL, + modelName, + 511, + dimensions, + "8f7d6082-5a15-4f84-ae55-88b2bdac4ba0", + nil, + ) + if err != nil { + t.Fatalf("NewOpenAIEmbedder: %v", err) + } + embedder.SetSupportsDimensionOverride(supportsDimensionOverride) + + if _, err := embedder.BatchEmbed(context.Background(), []string{"hello"}); err != nil { + t.Fatalf("BatchEmbed: %v", err) + } + + return requestBody +} diff --git a/internal/models/embedding/volcengine.go b/internal/models/embedding/volcengine.go index b7078391..040d191c 100644 --- a/internal/models/embedding/volcengine.go +++ b/internal/models/embedding/volcengine.go @@ -21,16 +21,17 @@ const ( // VolcengineEmbedder implements text vectorization using Volcengine Ark multimodal embedding API type VolcengineEmbedder struct { - apiKey string - baseURL string - modelName string - truncatePromptTokens int - dimensions int - modelID string - httpClient *http.Client - timeout time.Duration - maxRetries int - customHeaders map[string]string + apiKey string + baseURL string + modelName string + truncatePromptTokens int + dimensions int + modelID string + httpClient *http.Client + timeout time.Duration + maxRetries int + customHeaders map[string]string + supportsDimensionOverride bool EmbedderPooler } @@ -39,6 +40,10 @@ func (e *VolcengineEmbedder) SetCustomHeaders(headers map[string]string) { e.customHeaders = headers } +func (e *VolcengineEmbedder) SetSupportsDimensionOverride(supported bool) { + e.supportsDimensionOverride = supported +} + // VolcengineEmbedRequest represents a Volcengine Ark multimodal embedding request type VolcengineEmbedRequest struct { Model string `json:"model"` @@ -200,9 +205,11 @@ func (e *VolcengineEmbedder) BatchEmbed(ctx context.Context, texts []string) ([] } reqBody := VolcengineEmbedRequest{ - Model: e.modelName, - Input: input, - Dimensions: e.dimensions, + Model: e.modelName, + Input: input, + } + if e.supportsDimensionsParam() { + reqBody.Dimensions = e.dimensions } jsonData, err := json.Marshal(reqBody) @@ -252,6 +259,10 @@ func (e *VolcengineEmbedder) GetModelName() string { return e.modelName } +func (e *VolcengineEmbedder) supportsDimensionsParam() bool { + return e.supportsDimensionOverride && e.dimensions > 0 +} + // GetDimensions returns the vector dimensions func (e *VolcengineEmbedder) GetDimensions() int { return e.dimensions diff --git a/internal/models/embedding/weknoracloud.go b/internal/models/embedding/weknoracloud.go index 8cdf72d8..421fb069 100644 --- a/internal/models/embedding/weknoracloud.go +++ b/internal/models/embedding/weknoracloud.go @@ -18,14 +18,15 @@ const weKnoraCloudEmbedPath = "/api/v1/embeddings" // WeKnoraCloudEmbedder 实现 embedding.Embedder 接口,对接 WeKnoraCloud /api/v1/embeddings type WeKnoraCloudEmbedder struct { - modelName string - remoteModelName string - modelID string - appID string - apiKey string - baseURL string - dimensions int - client *http.Client + modelName string + remoteModelName string + modelID string + appID string + apiKey string + baseURL string + dimensions int + supportsDimensionOverride bool + client *http.Client EmbedderPooler } @@ -42,14 +43,15 @@ func NewWeKnoraCloudEmbedder(config Config) (*WeKnoraCloudEmbedder, error) { remoteModelName = strings.TrimSpace(config.ExtraConfig["remote_model_name"]) } return &WeKnoraCloudEmbedder{ - modelName: config.ModelName, - remoteModelName: remoteModelName, - modelID: config.ModelID, - appID: config.AppID, - apiKey: config.AppSecret, - baseURL: strings.TrimRight(config.BaseURL, "/"), - dimensions: config.Dimensions, - client: &http.Client{Timeout: 60 * time.Second}, + modelName: config.ModelName, + remoteModelName: remoteModelName, + modelID: config.ModelID, + appID: config.AppID, + apiKey: config.AppSecret, + baseURL: strings.TrimRight(config.BaseURL, "/"), + dimensions: config.Dimensions, + supportsDimensionOverride: config.SupportsDimensionOverride, + client: &http.Client{Timeout: 60 * time.Second}, }, nil } @@ -79,7 +81,10 @@ func (e *WeKnoraCloudEmbedder) Embed(ctx context.Context, text string) ([]float3 } func (e *WeKnoraCloudEmbedder) BatchEmbed(ctx context.Context, texts []string) ([][]float32, error) { - reqBody := weKnoraCloudEmbedRequest{Model: e.effectiveModelName(), Input: texts, Dimensions: e.dimensions} + reqBody := weKnoraCloudEmbedRequest{Model: e.effectiveModelName(), Input: texts} + if e.supportsDimensionOverride && e.dimensions > 0 { + reqBody.Dimensions = e.dimensions + } bodyBytes, err := json.Marshal(reqBody) if err != nil { return nil, fmt.Errorf("weknoracloud embedder: marshal: %w", err) @@ -129,6 +134,10 @@ func (e *WeKnoraCloudEmbedder) BatchEmbedWithPool(ctx context.Context, model Emb return e.BatchEmbed(ctx, texts) } +func (e *WeKnoraCloudEmbedder) SetSupportsDimensionOverride(supported bool) { + e.supportsDimensionOverride = supported +} + func (e *WeKnoraCloudEmbedder) effectiveModelName() string { if e.remoteModelName != "" { return e.remoteModelName diff --git a/internal/models/embedding/zhipu.go b/internal/models/embedding/zhipu.go index 7bfee7b7..4206cdcf 100644 --- a/internal/models/embedding/zhipu.go +++ b/internal/models/embedding/zhipu.go @@ -16,16 +16,17 @@ import ( // ZhipuEmbedder implements text vectorization functionality using Zhipu AI API type ZhipuEmbedder struct { - apiKey string - baseURL string - modelName string - truncatePromptTokens int - dimensions int - modelID string - httpClient *http.Client - timeout time.Duration - maxRetries int - customHeaders map[string]string + apiKey string + baseURL string + modelName string + truncatePromptTokens int + dimensions int + modelID string + httpClient *http.Client + timeout time.Duration + maxRetries int + customHeaders map[string]string + supportsDimensionOverride bool EmbedderPooler } @@ -88,6 +89,10 @@ func (e *ZhipuEmbedder) SetCustomHeaders(headers map[string]string) { e.customHeaders = headers } +func (e *ZhipuEmbedder) SetSupportsDimensionOverride(supported bool) { + e.supportsDimensionOverride = supported +} + // Embed converts text to vector func (e *ZhipuEmbedder) Embed(ctx context.Context, text string) ([]float32, error) { for range 3 { @@ -149,9 +154,11 @@ func (e *ZhipuEmbedder) BatchEmbed(ctx context.Context, texts []string) ([][]flo reqBody := ZhipuEmbedRequest{ Model: e.modelName, Input: texts, - Dimensions: e.dimensions, TruncatePromptTokens: e.truncatePromptTokens, } + if e.supportsDimensionsParam() { + reqBody.Dimensions = e.dimensions + } jsonData, err := json.Marshal(reqBody) if err != nil { @@ -235,6 +242,10 @@ func (e *ZhipuEmbedder) GetModelName() string { return e.modelName } +func (e *ZhipuEmbedder) supportsDimensionsParam() bool { + return e.supportsDimensionOverride && e.dimensions > 0 +} + // GetDimensions returns the vector dimensions func (e *ZhipuEmbedder) GetDimensions() int { return e.dimensions diff --git a/internal/types/model.go b/internal/types/model.go index b0cdac21..e7d36d3b 100644 --- a/internal/types/model.go +++ b/internal/types/model.go @@ -56,8 +56,9 @@ const ( // EmbeddingParameters represents the embedding parameters for a model type EmbeddingParameters struct { - Dimension int `yaml:"dimension" json:"dimension"` - TruncatePromptTokens int `yaml:"truncate_prompt_tokens" json:"truncate_prompt_tokens"` + Dimension int `yaml:"dimension" json:"dimension"` + TruncatePromptTokens int `yaml:"truncate_prompt_tokens" json:"truncate_prompt_tokens"` + SupportsDimensionOverride bool `yaml:"supports_dimension_override" json:"supports_dimension_override"` } type ModelParameters struct {