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.
This commit is contained in:
wizardchen
2026-07-20 20:06:42 +08:00
committed by lyingbug
parent 3011f132e9
commit b1b42abe23
5 changed files with 172 additions and 19 deletions
+8
View File
@@ -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: "헤더 추가",
+8
View File
@@ -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: 'Добавить заголовок',
+1 -1
View File
@@ -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,
+50 -18
View File
@@ -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 {
@@ -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")
}