From 58acd8b33cf57fc5ccf318d74a2a2cc57ea302bf Mon Sep 17 00:00:00 2001 From: wizardchen Date: Wed, 26 Aug 2026 17:31:05 +0800 Subject: [PATCH] feat(api): honor resource_urls=public on hybrid-search Single-KB retrieval was still returning resource:// handles even when callers asked for public URLs, unlike knowledge-search. --- client/knowledgebase.go | 16 ++- client/resource_urls.go | 2 +- docs/api/README.md | 3 +- docs/api/chat.md | 2 +- docs/api/knowledge-base.md | 6 +- docs/docs.go | 22 ++++ docs/swagger.json | 22 ++++ docs/swagger.yaml | 16 +++ internal/handler/knowledgebase.go | 45 +++++++- ...gebase_hybrid_search_resource_urls_test.go | 108 ++++++++++++++++++ .../knowledgebase_hybrid_search_test.go | 4 + website-docs/04-api/01-api-overview.md | 2 +- website-docs/04-api/02-api-knowledge.md | 4 +- website-docs/05-clients/03-go-sdk.md | 2 +- 14 files changed, 240 insertions(+), 14 deletions(-) create mode 100644 internal/handler/knowledgebase_hybrid_search_resource_urls_test.go diff --git a/client/knowledgebase.go b/client/knowledgebase.go index 99839ceb..dbf2186f 100644 --- a/client/knowledgebase.go +++ b/client/knowledgebase.go @@ -9,6 +9,7 @@ import ( "encoding/json" "fmt" "net/http" + "net/url" "time" ) @@ -407,10 +408,21 @@ type SearchParams struct { } // HybridSearch performs hybrid search. -func (c *Client) HybridSearch(ctx context.Context, knowledgeBaseID string, params *SearchParams) ([]*SearchResult, error) { +// Pass ResourceURLOptions to receive public HTTP(S) file URLs in results. +func (c *Client) HybridSearch( + ctx context.Context, + knowledgeBaseID string, + params *SearchParams, + opts ...ResourceURLOptions, +) ([]*SearchResult, error) { path := fmt.Sprintf("/api/v1/knowledge-bases/%s/hybrid-search", knowledgeBaseID) - resp, err := c.doRequest(ctx, http.MethodPost, path, params, nil) + queryParams := url.Values{} + if len(opts) > 0 { + applyResourceURLQuery(queryParams, &opts[0]) + } + + resp, err := c.doRequest(ctx, http.MethodPost, path, params, queryParams) if err != nil { return nil, err } diff --git a/client/resource_urls.go b/client/resource_urls.go index 442fae48..57f3adb5 100644 --- a/client/resource_urls.go +++ b/client/resource_urls.go @@ -17,7 +17,7 @@ const ( ) // ResourceURLOptions carries the optional resource_urls query parameter shared -// by chat, message-history, and knowledge-search endpoints. +// by chat, message-history, knowledge-search, and hybrid-search endpoints. type ResourceURLOptions struct { ResourceURLs ResourceURLMode } diff --git a/docs/api/README.md b/docs/api/README.md index a705f500..47c11628 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -88,8 +88,9 @@ X-Request-ID: unique_request_id - `GET /api/v1/sessions/continue-stream/{session_id}`(SSE) - `GET /api/v1/messages/{session_id}/load` - `POST /api/v1/knowledge-search` +- `POST /api/v1/knowledge-bases/{id}/hybrid-search`(兼容 GET) -改写覆盖答案正文、`knowledge_references`(含 `image_info`)、Agent 执行步骤与工具结果,以及消息 +改写覆盖答案正文、检索结果 `content` / `image_info`、`knowledge_references`、Agent 执行步骤与工具结果,以及消息 上的图片附件。流式回答里跨两个 chunk 被截断的引用会先缓冲再改写,客户端拿到的始终是完整链接。 ### 注意事项 diff --git a/docs/api/chat.md b/docs/api/chat.md index b84b4c1c..1cc040cd 100644 --- a/docs/api/chat.md +++ b/docs/api/chat.md @@ -21,7 +21,7 @@ |------|------|------| | `resource_urls` | `handle`(默认)/ `public` | `public` 让答案与引用里的图片直接返回可加载的 http(s) 链接,省去逐个调用 `/files` 代理。详见[文件与图片引用](./README.md#文件与图片引用resource-与直链) | -同样适用于下面的 `/agent-chat/:session_id`、`/knowledge-search` 与 `/sessions/continue-stream/:session_id`。 +同样适用于下面的 `/agent-chat/:session_id`、`/knowledge-search`、`/knowledge-bases/:id/hybrid-search` 与 `/sessions/continue-stream/:session_id`。 **请求参数**: diff --git a/docs/api/knowledge-base.md b/docs/api/knowledge-base.md index 2219648b..65f06a2e 100644 --- a/docs/api/knowledge-base.md +++ b/docs/api/knowledge-base.md @@ -400,6 +400,10 @@ curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-0 | ---- | ------ | --------- | | id | string | 知识库 ID | +**查询参数**: + +- `resource_urls`: `handle`(默认)或 `public`。`public` 把检索结果 `content` / `image_info` 里的 `resource://` 引用换成可加载的 http(s) 链接,详见[文件与图片引用](./README.md#文件与图片引用resource-与直链) + **参数说明(请求体)**: | 字段 | 类型 | 必填 | 说明 | @@ -419,7 +423,7 @@ curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-0 **请求**: ```curl -curl --location --request POST 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/hybrid-search' \ +curl --location --request POST 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/hybrid-search?resource_urls=public' \ --header 'X-API-Key: sk-xxxxx' \ --header 'Content-Type: application/json' \ --data '{ diff --git a/docs/docs.go b/docs/docs.go index 4a9fdc04..60f51e69 100644 --- a/docs/docs.go +++ b/docs/docs.go @@ -4928,6 +4928,17 @@ const docTemplate = `{ "schema": { "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams" } + }, + { + "enum": [ + "handle", + "public" + ], + "type": "string", + "default": "handle", + "description": "文件引用形式,public 返回可加载直链", + "name": "resource_urls", + "in": "query" } ], "responses": { @@ -4982,6 +4993,17 @@ const docTemplate = `{ "schema": { "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams" } + }, + { + "enum": [ + "handle", + "public" + ], + "type": "string", + "default": "handle", + "description": "文件引用形式,public 返回可加载直链", + "name": "resource_urls", + "in": "query" } ], "responses": { diff --git a/docs/swagger.json b/docs/swagger.json index 82ec7d4a..17ed9bc5 100644 --- a/docs/swagger.json +++ b/docs/swagger.json @@ -4921,6 +4921,17 @@ "schema": { "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams" } + }, + { + "enum": [ + "handle", + "public" + ], + "type": "string", + "default": "handle", + "description": "文件引用形式,public 返回可加载直链", + "name": "resource_urls", + "in": "query" } ], "responses": { @@ -4975,6 +4986,17 @@ "schema": { "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams" } + }, + { + "enum": [ + "handle", + "public" + ], + "type": "string", + "default": "handle", + "description": "文件引用形式,public 返回可加载直链", + "name": "resource_urls", + "in": "query" } ], "responses": { diff --git a/docs/swagger.yaml b/docs/swagger.yaml index d33c6f08..334ca9c2 100644 --- a/docs/swagger.yaml +++ b/docs/swagger.yaml @@ -9349,6 +9349,14 @@ paths: required: true schema: $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams' + - default: handle + description: 文件引用形式,public 返回可加载直链 + enum: + - handle + - public + in: query + name: resource_urls + type: string produces: - application/json responses: @@ -9383,6 +9391,14 @@ paths: required: true schema: $ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams' + - default: handle + description: 文件引用形式,public 返回可加载直链 + enum: + - handle + - public + in: query + name: resource_urls + type: string produces: - application/json responses: diff --git a/internal/handler/knowledgebase.go b/internal/handler/knowledgebase.go index 387f59be..f531b8f3 100644 --- a/internal/handler/knowledgebase.go +++ b/internal/handler/knowledgebase.go @@ -15,6 +15,7 @@ import ( "github.com/Tencent/WeKnora/internal/errors" apperrors "github.com/Tencent/WeKnora/internal/errors" "github.com/Tencent/WeKnora/internal/logger" + "github.com/Tencent/WeKnora/internal/storageurl" "github.com/Tencent/WeKnora/internal/tracing/langfuse" "github.com/Tencent/WeKnora/internal/types" "github.com/Tencent/WeKnora/internal/types/interfaces" @@ -35,6 +36,11 @@ type KnowledgeBaseHandler struct { // userService 仅在 list 类接口里用于批量回填 creator_name; // 真正的鉴权由 RBAC 中间件 + Lookup 完成,这里不参与决策。 userService interfaces.UserService + // fileService and storageResolver back the optional `resource_urls=public` + // mode on hybrid-search. Both may be nil in tests, in which case only the + // default handle mode is available. + fileService interfaces.FileService + storageResolver interfaces.StorageBackendResolver } // NewKnowledgeBaseHandler creates a new knowledge base handler instance @@ -46,6 +52,8 @@ func NewKnowledgeBaseHandler( asynqClient interfaces.TaskEnqueuer, vectorStoreService interfaces.VectorStoreService, userService interfaces.UserService, + fileService interfaces.FileService, + storageResolver interfaces.StorageBackendResolver, ) *KnowledgeBaseHandler { return &KnowledgeBaseHandler{ service: service, @@ -55,9 +63,27 @@ func NewKnowledgeBaseHandler( asynqClient: asynqClient, vectorStoreService: vectorStoreService, userService: userService, + fileService: fileService, + storageResolver: storageResolver, } } +// resolveResourceRewriter builds the storage-reference rewriter for one response +// from the request's `resource_urls` parameter, falling back to the deployment +// default. The returned error is already an AppError the caller can hand to +// c.Error: a rejected scope is a 403, a typo in the parameter is a 400. +func (h *KnowledgeBaseHandler) resolveResourceRewriter(c *gin.Context) (*storageurl.Rewriter, error) { + ctx := c.Request.Context() + mode, err := storageurl.ResolveMode(ctx, c.Query(storageurl.QueryParam)) + if err != nil { + if stderrors.Is(err, storageurl.ErrPublicModeForbidden) { + return nil, apperrors.NewForbiddenError(err.Error()) + } + return nil, apperrors.NewBadRequestError(err.Error()) + } + return storageurl.NewRequestRewriter(ctx, mode, h.fileService, h.storageResolver), nil +} + // buildKBResponse turns a knowledge base into a JSON-ready response shape, // merging the bound vector store's display metadata and any caller-supplied // extras (e.g., my_permission for shared KBs). Returns the kb pointer @@ -275,10 +301,11 @@ func (h *KnowledgeBaseHandler) resolveKBStoreView( // @Tags 知识库 // @Accept json // @Produce json -// @Param id path string true "知识库ID" -// @Param request body types.SearchParams true "搜索参数" -// @Success 200 {object} map[string]interface{} "搜索结果" -// @Failure 400 {object} errors.AppError "请求参数错误" +// @Param id path string true "知识库ID" +// @Param request body types.SearchParams true "搜索参数" +// @Param resource_urls query string false "文件引用形式,public 返回可加载直链" Enums(handle, public) default(handle) +// @Success 200 {object} map[string]interface{} "搜索结果" +// @Failure 400 {object} errors.AppError "请求参数错误" // @Security Bearer // @Security ApiKeyAuth // @Router /knowledge-bases/{id}/hybrid-search [post] @@ -311,6 +338,14 @@ func (h *KnowledgeBaseHandler) HybridSearch(c *gin.Context) { logger.Infof(ctx, "Executing hybrid search, knowledge base ID: %s, query: %s, effectiveTenantID: %d", secutils.SanitizeForLog(id), secutils.SanitizeForLog(req.QueryText), effectiveTenantID) + // Resolve before retrieving so a typo or a rejected scope costs nothing. + rewriter, err := h.resolveResourceRewriter(c) + if err != nil { + logger.Warnf(ctx, "Rejected resource URL mode: %v", err) + _ = c.Error(err) + return + } + // Execute hybrid search with default search parameters // Note: For shared KBs, the service uses effectiveTenantID internally via context results, err := h.service.HybridSearch(ctx, id, req) @@ -333,7 +368,7 @@ func (h *KnowledgeBaseHandler) HybridSearch(c *gin.Context) { secutils.SanitizeForLog(id), len(results)) c.JSON(http.StatusOK, gin.H{ "success": true, - "data": results, + "data": rewriter.CopyReferences(ctx, results), }) } diff --git a/internal/handler/knowledgebase_hybrid_search_resource_urls_test.go b/internal/handler/knowledgebase_hybrid_search_resource_urls_test.go new file mode 100644 index 00000000..513110dc --- /dev/null +++ b/internal/handler/knowledgebase_hybrid_search_resource_urls_test.go @@ -0,0 +1,108 @@ +package handler + +import ( + "bytes" + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + + "github.com/gin-gonic/gin" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" + + "github.com/Tencent/WeKnora/internal/middleware" + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" +) + +func newHybridSearchResourceURLRouter(svc interfaces.KnowledgeBaseService, fileSvc interfaces.FileService) *gin.Engine { + gin.SetMode(gin.TestMode) + router := gin.New() + router.Use(middleware.ErrorHandler()) + router.Use(func(c *gin.Context) { + c.Set(types.TenantIDContextKey.String(), uint64(1)) + c.Set(types.UserIDContextKey.String(), "u-test") + c.Next() + }) + h := &KnowledgeBaseHandler{service: svc, fileService: fileSvc} + router.POST("/knowledge-bases/:id/hybrid-search", h.HybridSearch) + router.GET("/knowledge-bases/:id/hybrid-search", h.HybridSearch) + return router +} + +func performHybridSearchResourceURLRequest( + svc interfaces.KnowledgeBaseService, + fileSvc interfaces.FileService, + method, query, body string, +) *httptest.ResponseRecorder { + response := httptest.NewRecorder() + request := httptest.NewRequest( + method, + "/knowledge-bases/kb-1/hybrid-search"+query, + bytes.NewBufferString(body), + ) + request.Header.Set("Content-Type", "application/json") + newHybridSearchResourceURLRouter(svc, fileSvc).ServeHTTP(response, request) + return response +} + +func TestHybridSearch_PublicResourceURLs(t *testing.T) { + svc := &hybridSearchTestService{ + results: []*types.SearchResult{{ + Content: "chunk ![c](" + testResourceHandle + ")", + ImageInfo: `[{"url":"` + testResourceHandle + `"}]`, + }}, + } + fileSvc := &stubResourceFileService{url: "https://cdn.example.com/signed.png"} + + for _, method := range []string{http.MethodPost, http.MethodGet} { + t.Run(method, func(t *testing.T) { + response := performHybridSearchResourceURLRequest( + svc, fileSvc, method, "?resource_urls=public", + `{"query_text":"diagram"}`, + ) + + require.Equal(t, http.StatusOK, response.Code, "body=%s", response.Body.String()) + assert.NotContains(t, response.Body.String(), testResourceHandle) + assert.Contains(t, response.Body.String(), "cdn.example.com") + }) + } +} + +func TestHybridSearch_InvalidResourceURLMode(t *testing.T) { + svc := &hybridSearchTestService{} + response := performHybridSearchResourceURLRequest( + svc, &stubResourceFileService{url: "https://cdn.example.com/signed.png"}, + http.MethodPost, "?resource_urls=signed", + `{"query_text":"diagram"}`, + ) + + require.Equal(t, http.StatusBadRequest, response.Code, "body=%s", response.Body.String()) + assert.Contains(t, response.Body.String(), "resource_urls") + assert.Equal(t, 0, svc.searchCalls, "invalid mode must not reach HybridSearch") +} + +func TestHybridSearch_DefaultKeepsHandles(t *testing.T) { + svc := &hybridSearchTestService{ + results: []*types.SearchResult{{ + Content: "chunk ![c](" + testResourceHandle + ")", + }}, + } + response := performHybridSearchResourceURLRequest( + svc, &stubResourceFileService{url: "https://cdn.example.com/signed.png"}, + http.MethodPost, "", + `{"query_text":"diagram"}`, + ) + + require.Equal(t, http.StatusOK, response.Code, "body=%s", response.Body.String()) + + var resp struct { + Data []struct { + Content string `json:"content"` + } `json:"data"` + } + require.NoError(t, json.Unmarshal(response.Body.Bytes(), &resp)) + require.Len(t, resp.Data, 1) + assert.Contains(t, resp.Data[0].Content, testResourceHandle) +} diff --git a/internal/handler/knowledgebase_hybrid_search_test.go b/internal/handler/knowledgebase_hybrid_search_test.go index e1d6e28a..4ded29b6 100644 --- a/internal/handler/knowledgebase_hybrid_search_test.go +++ b/internal/handler/knowledgebase_hybrid_search_test.go @@ -18,6 +18,7 @@ type hybridSearchTestService struct { interfaces.KnowledgeBaseService searchCalls int searchParams types.SearchParams + results []*types.SearchResult } func (s *hybridSearchTestService) GetKnowledgeBaseByID(_ context.Context, id string) (*types.KnowledgeBase, error) { @@ -31,6 +32,9 @@ func (s *hybridSearchTestService) HybridSearch( ) ([]*types.SearchResult, error) { s.searchCalls++ s.searchParams = params + if s.results != nil { + return s.results, nil + } return []*types.SearchResult{}, nil } diff --git a/website-docs/04-api/01-api-overview.md b/website-docs/04-api/01-api-overview.md index 305ed63e..c0387b26 100644 --- a/website-docs/04-api/01-api-overview.md +++ b/website-docs/04-api/01-api-overview.md @@ -188,7 +188,7 @@ X-Accel-Buffering: no 取值只有 `handle`(默认)与 `public`,传其它值返回 400。单次请求参数优先于环境变量,所以把部署默认设成 `public` 之后,仍可以用 `?resource_urls=handle` 单独退回。 -支持该参数的接口:`POST /knowledge-chat/{session_id}`、`POST /agent-chat/{session_id}`、`GET /sessions/continue-stream/{session_id}`、`GET /messages/{session_id}/load`、`POST /knowledge-search`。改写覆盖答案正文、`knowledge_references`(含 `image_info`)、Agent 执行步骤与工具结果,以及消息上的图片附件;流式回答里跨 chunk 截断的引用会先缓冲再改写,客户端拿到的始终是完整链接。 +支持该参数的接口:`POST /knowledge-chat/{session_id}`、`POST /agent-chat/{session_id}`、`GET /sessions/continue-stream/{session_id}`、`GET /messages/{session_id}/load`、`POST /knowledge-search`、`POST /knowledge-bases/{id}/hybrid-search`(兼容 GET)。改写覆盖答案正文、检索结果 `content` / `image_info`、`knowledge_references`、Agent 执行步骤与工具结果,以及消息上的图片附件;流式回答里跨 chunk 截断的引用会先缓冲再改写,客户端拿到的始终是完整链接。 使用前需要知道的几件事: diff --git a/website-docs/04-api/02-api-knowledge.md b/website-docs/04-api/02-api-knowledge.md index d4f49197..40ce28f0 100644 --- a/website-docs/04-api/02-api-knowledge.md +++ b/website-docs/04-api/02-api-knowledge.md @@ -100,6 +100,8 @@ curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/pin -H "Authorization: Bearer $TOK 用途:KB 内混合检索(向量+关键词)。权限:Viewer+,KB read;API key `retrieve`/full。GET 携带 JSON body 仅为向后兼容(#1727),推荐 POST。 +查询参数:`resource_urls=handle|public`(`public` 把结果 `content` / `image_info` 里的 `resource://` 换成可加载直链,详见 [API 总览](./01-api-overview.md))。 + 请求体(`types.SearchParams`): | 字段 | 类型 | 必填 | 说明 | @@ -117,7 +119,7 @@ curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/pin -H "Authorization: Bearer $TOK 响应:200 `{"success":true,"data":[SearchResult]}` ```bash -curl -X POST $BASE/api/v1/knowledge-bases/kb-1/hybrid-search -H "X-API-Key: $API_KEY" \ +curl -X POST "$BASE/api/v1/knowledge-bases/kb-1/hybrid-search?resource_urls=public" -H "X-API-Key: $API_KEY" \ -H 'Content-Type: application/json' -d '{"query_text":"退款流程","match_count":5}' ``` diff --git a/website-docs/05-clients/03-go-sdk.md b/website-docs/05-clients/03-go-sdk.md index 94a5d744..797f98f0 100644 --- a/website-docs/05-clients/03-go-sdk.md +++ b/website-docs/05-clients/03-go-sdk.md @@ -115,7 +115,7 @@ kb, err := apiClient.GetKnowledgeBase(ctx, kbID) | `UpdateKnowledgeBase` | 更新知识库 | | `DeleteKnowledgeBase` | 删除知识库 | | `ClearKnowledgeBaseContents` | 清空知识库内容 | -| `HybridSearch` | 在知识库内混合检索(向量 + 关键词) | +| `HybridSearch` | 在知识库内混合检索(向量 + 关键词);可传 `ResourceURLOptions` 返回文件直链 | | `TogglePinKnowledgeBase` | 置顶/取消置顶 | | `ListMoveTargets` | 列出知识可迁移的目标知识库 | | `CopyKnowledgeBase` | 复制知识库 |