From b1b42abe230ed50d11e5b9a398f38e64a8db0c99 Mon Sep 17 00:00:00 2001 From: wizardchen Date: Mon, 20 Jul 2026 20:06:42 +0800 Subject: [PATCH] fix(rerank): batch Volcengine rerank requests over API document limit Split oversized candidate sets into concurrent batches instead of failing when retrieval exceeds the VikingDB rerank per-request cap, and align ko/ru locale hints with zh-CN. --- frontend/src/i18n/locales/ko-KR.ts | 8 ++ frontend/src/i18n/locales/ru-RU.ts | 8 ++ internal/models/provider/volcengine.go | 2 +- internal/models/rerank/volcengine_reranker.go | 68 +++++++++--- .../models/rerank/volcengine_reranker_test.go | 105 ++++++++++++++++++ 5 files changed, 172 insertions(+), 19 deletions(-) diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.ts index 0be71753..ca61fed2 100755 --- a/frontend/src/i18n/locales/ko-KR.ts +++ b/frontend/src/i18n/locales/ko-KR.ts @@ -3165,6 +3165,14 @@ export default { baseUrlPlaceholderAsr: "예: https://api.openai.com/v1", apiKeyOptional: "API 키 (선택)", apiKeyPlaceholder: "API 키 입력", + volcengine: { + accessKeyLabel: "Access Key ID", + accessKeyPlaceholder: "Volcengine Access Key ID", + secretKeyLabel: "Secret Access Key", + secretKeyPlaceholder: "Volcengine Secret Access Key", + rerankCredentialHint: + "Rerank은 Ark API 키가 아닌 VikingDB AK/SK 서명을 사용합니다. 권장 모델: doubao-seed-rerank.", + }, customHeadersLabel: "사용자 정의 요청 헤더 (선택)", customHeadersDesc: "원격 모델 API 호출 시 추가되는 HTTP 헤더입니다. 기업 게이트웨이 인증이나 추적 등에 사용할 수 있으며, Authorization / Content-Type 같은 예약 헤더는 무시됩니다.", customHeadersAdd: "헤더 추가", diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts index d70efa61..30bfb3fa 100755 --- a/frontend/src/i18n/locales/ru-RU.ts +++ b/frontend/src/i18n/locales/ru-RU.ts @@ -2853,6 +2853,14 @@ export default { baseUrlPlaceholderAsr: 'например: https://api.openai.com/v1', apiKeyOptional: 'API Key (опционально)', apiKeyPlaceholder: 'Введите API Key', + volcengine: { + accessKeyLabel: 'Access Key ID', + accessKeyPlaceholder: 'Volcengine Access Key ID', + secretKeyLabel: 'Secret Access Key', + secretKeyPlaceholder: 'Volcengine Secret Access Key', + rerankCredentialHint: + 'Rerank использует подпись VikingDB AK/SK, а не Ark API key. Рекомендуемая модель: doubao-seed-rerank.', + }, customHeadersLabel: 'Пользовательские заголовки запроса (опционально)', customHeadersDesc: 'Дополнительные HTTP-заголовки, добавляемые к запросам к удалённому API модели (например, для авторизации корпоративного шлюза или трассировки). Зарезервированные заголовки, такие как Authorization / Content-Type, игнорируются.', customHeadersAdd: 'Добавить заголовок', diff --git a/internal/models/provider/volcengine.go b/internal/models/provider/volcengine.go index 9db6a66b..b20a8122 100644 --- a/internal/models/provider/volcengine.go +++ b/internal/models/provider/volcengine.go @@ -27,7 +27,7 @@ func (p *VolcengineProvider) Info() ProviderInfo { return ProviderInfo{ Name: ProviderVolcengine, DisplayName: "火山引擎 Volcengine", - Description: "doubao-1-5-pro-32k-250115, doubao-embedding-vision-250615, etc.", + Description: "doubao-1-5-pro-32k-250115, doubao-embedding-vision-250615, doubao-seed-rerank, etc.", DefaultURLs: map[types.ModelType]string{ types.ModelTypeKnowledgeQA: VolcengineChatBaseURL, types.ModelTypeEmbedding: VolcengineEmbeddingBaseURL, diff --git a/internal/models/rerank/volcengine_reranker.go b/internal/models/rerank/volcengine_reranker.go index 57ae0fe2..2a1b5176 100644 --- a/internal/models/rerank/volcengine_reranker.go +++ b/internal/models/rerank/volcengine_reranker.go @@ -10,6 +10,7 @@ import ( "github.com/Tencent/WeKnora/internal/models/provider" "github.com/volcengine/vikingdb-go-sdk/knowledge" knowledgemodel "github.com/volcengine/vikingdb-go-sdk/knowledge/model" + "golang.org/x/sync/errgroup" ) const ( @@ -20,6 +21,10 @@ const ( volcengineRerankDefaultRegion = "cn-beijing" volcengineRerankDefaultInstruction = "Whether the Document answers the Query or matches the content retrieval intent" volcengineRerankMaxDocuments = 50 + // volcengineRerankMaxConcurrency bounds the number of in-flight batch + // requests when the candidate set exceeds volcengineRerankMaxDocuments, so a + // very large embedding_top_k cannot fan out into an unbounded burst of calls. + volcengineRerankMaxConcurrency = 4 ) // VolcengineReranker calls the managed Knowledge Service Rerank API with AK/SK signing. @@ -27,6 +32,7 @@ type VolcengineReranker struct { modelName string instruction string modelID string + endpoint string client *knowledge.Client } @@ -79,6 +85,7 @@ func NewVolcengineReranker(config *RerankerConfig) (*VolcengineReranker, error) modelName: modelName, instruction: instruction, modelID: config.ModelID, + endpoint: baseURL, client: client, }, nil } @@ -89,14 +96,48 @@ func (r *VolcengineReranker) Rerank( if len(documents) == 0 { return []RankResult{}, nil } - if len(documents) > volcengineRerankMaxDocuments { - return nil, fmt.Errorf( - "Volcengine rerank supports at most %d documents, got %d", - volcengineRerankMaxDocuments, - len(documents), - ) - } + // The managed Knowledge Service Rerank API rejects requests carrying more + // than volcengineRerankMaxDocuments items. Upstream callers (chat pipeline, + // agent knowledge search, message search) feed in every retrieval candidate + // and do not cap the count per provider, so a large embedding_top_k or a + // multi-target search can exceed the limit. Each Data item is scored + // independently against the same (query, instruction) pair, so the scores + // are comparable across requests — we can split the documents into limit- + // sized batches, rerank them concurrently, and merge without losing any + // candidate (unlike truncation) or biasing the ranking. + results := make([]RankResult, len(documents)) + g, gctx := errgroup.WithContext(ctx) + g.SetLimit(volcengineRerankMaxConcurrency) + for start := 0; start < len(documents); start += volcengineRerankMaxDocuments { + start := start + end := min(start+volcengineRerankMaxDocuments, len(documents)) + g.Go(func() error { + scores, err := r.rerankBatch(gctx, query, documents[start:end]) + if err != nil { + return err + } + for i, score := range scores { + results[start+i] = RankResult{ + Index: start + i, + Document: DocumentInfo{Text: documents[start+i]}, + RelevanceScore: score, + } + } + return nil + }) + } + if err := g.Wait(); err != nil { + return nil, err + } + return results, nil +} + +// rerankBatch scores a single batch of documents (already sized within the API +// limit) and returns the per-document relevance scores in input order. +func (r *VolcengineReranker) rerankBatch( + ctx context.Context, query string, documents []string, +) ([]float64, error) { data := make([]knowledgemodel.RerankDataItem, len(documents)) for i := range documents { data[i] = knowledgemodel.RerankDataItem{ @@ -113,7 +154,7 @@ func (r *VolcengineReranker) Rerank( logger.Debugf( ctx, "%s", - buildRerankRequestDebug(r.modelName, VolcengineRerankBaseURL+volcengineRerankPath, query, documents), + buildRerankRequestDebug(r.modelName, r.endpoint+volcengineRerankPath, query, documents), ) response, err := r.client.Rerank(ctx, request) if err != nil { @@ -132,16 +173,7 @@ func (r *VolcengineReranker) Rerank( len(documents), ) } - - results := make([]RankResult, len(documents)) - for i, score := range response.Data.Scores { - results[i] = RankResult{ - Index: i, - Document: DocumentInfo{Text: documents[i]}, - RelevanceScore: score, - } - } - return results, nil + return response.Data.Scores, nil } func (r *VolcengineReranker) GetModelName() string { diff --git a/internal/models/rerank/volcengine_reranker_test.go b/internal/models/rerank/volcengine_reranker_test.go index d567c644..43cf6207 100644 --- a/internal/models/rerank/volcengine_reranker_test.go +++ b/internal/models/rerank/volcengine_reranker_test.go @@ -2,9 +2,11 @@ package rerank import ( "encoding/json" + "fmt" "net/http" "net/http/httptest" "strings" + "sync" "testing" "github.com/stretchr/testify/assert" @@ -71,3 +73,106 @@ func TestNewVolcengineReranker_RequiresAKSK(t *testing.T) { require.Error(t, err) assert.Contains(t, err.Error(), "access key and secret key") } + +func newTestVolcengineReranker(t *testing.T, handler http.HandlerFunc) *VolcengineReranker { + t.Helper() + withRerankSSRFWhitelist(t, "127.0.0.1") + server := httptest.NewServer(handler) + t.Cleanup(server.Close) + reranker, err := NewVolcengineReranker(&RerankerConfig{ + APIKey: "AKLT-test", + AppSecret: "secret-test", + BaseURL: server.URL, + ModelName: "doubao-seed-rerank", + }) + require.NoError(t, err) + return reranker +} + +func TestVolcengineReranker_EmptyDocuments(t *testing.T) { + reranker := newTestVolcengineReranker(t, func(w http.ResponseWriter, r *http.Request) { + t.Fatalf("rerank endpoint should not be called for empty documents") + }) + + results, err := reranker.Rerank(t.Context(), "query", nil) + require.NoError(t, err) + assert.Empty(t, results) +} + +// TestVolcengineReranker_BatchesOverLimit verifies that a candidate set larger +// than the API document limit is split into batches and reranked in full, +// rather than truncated: every document gets a score and no batch exceeds the +// per-request limit. +func TestVolcengineReranker_BatchesOverLimit(t *testing.T) { + var ( + mu sync.Mutex + batchSizes []int + requestCount int + ) + reranker := newTestVolcengineReranker(t, func(w http.ResponseWriter, r *http.Request) { + var body struct { + Datas []struct { + Content *string `json:"content"` + } `json:"datas"` + } + require.NoError(t, json.NewDecoder(r.Body).Decode(&body)) + + mu.Lock() + requestCount++ + batchSizes = append(batchSizes, len(body.Datas)) + mu.Unlock() + + scores := make([]string, len(body.Datas)) + for i := range scores { + scores[i] = "0.5" + } + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"code":0,"message":"success","data":{"scores":[` + + strings.Join(scores, ",") + `]}}`)) + }) + + total := volcengineRerankMaxDocuments*2 + 10 + documents := make([]string, total) + for i := range documents { + documents[i] = fmt.Sprintf("doc-%d", i) + } + + results, err := reranker.Rerank(t.Context(), "query", documents) + require.NoError(t, err) + + // All documents reranked, each mapped back to its original index/text. + require.Len(t, results, total) + for i := range results { + assert.Equal(t, i, results[i].Index) + assert.Equal(t, documents[i], results[i].Document.Text) + } + + // Split into ceil(total/limit) batches, none exceeding the API limit. + assert.Equal(t, 3, requestCount) + for _, size := range batchSizes { + assert.LessOrEqual(t, size, volcengineRerankMaxDocuments) + } +} + +func TestVolcengineReranker_APIErrorCode(t *testing.T) { + reranker := newTestVolcengineReranker(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"code":100004,"message":"quota exceeded","data":{}}`)) + }) + + _, err := reranker.Rerank(t.Context(), "query", []string{"a", "b"}) + require.Error(t, err) + assert.Contains(t, err.Error(), "100004") + assert.Contains(t, err.Error(), "quota exceeded") +} + +func TestVolcengineReranker_ScoreCountMismatch(t *testing.T) { + reranker := newTestVolcengineReranker(t, func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + _, _ = w.Write([]byte(`{"code":0,"message":"success","data":{"scores":[0.9]}}`)) + }) + + _, err := reranker.Rerank(t.Context(), "query", []string{"a", "b"}) + require.Error(t, err) + assert.Contains(t, err.Error(), "score count mismatch") +}