Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
feat(api): honor resource_urls=public on hybrid-search
wizardchen58acd8b33cf5
diff --git a/client/knowledgebase.go b/client/knowledgebase.goindex 99839cebf..dbf2186f9 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.goindex 442fae488..57f3adb5f 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.mdindex a705f5005..47c116282 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.mdindex b84b4c1c7..1cc040cd8 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.mdindex 2219648b2..65f06a2e9 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.goindex 4a9fdc04c..60f51e691 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.jsonindex 82ec7d4a4..17ed9bc50 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.yamlindex d33c6f087..334ca9c22 100644--- a/docs/swagger.yaml+++ b/docs/swagger.yaml@@ -9349,6 +9349,14 @@ paths:required: trueschema:$ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams'+ - default: handle+ description: 文件引用形式,public 返回可加载直链+ enum:+ - handle+ - public+ in: query+ name: resource_urls+ type: stringproduces:- application/jsonresponses:@@ -9383,6 +9391,14 @@ paths:required: trueschema:$ref: '#/definitions/github_com_Tencent_WeKnora_internal_types.SearchParams'+ - default: handle+ description: 文件引用形式,public 返回可加载直链+ enum:+ - handle+ - public+ in: query+ name: resource_urls+ type: stringproduces:- application/jsonresponses:diff --git a/internal/handler/knowledgebase.go b/internal/handler/knowledgebase.goindex 387f59be0..f531b8f3e 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 contextresults, 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.gonew file mode 100644index 000000000..513110dc8--- /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 ",+ 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 ",+ }},+ }+ 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.goindex e1d6e28a7..4ded29b65 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.KnowledgeBaseServicesearchCalls intsearchParams 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.mdindex 305ed63ea..c0387b26c 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.mdindex d4f49197e..40ce28f08 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.mdindex 94a5d744c..797f98f0a 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` | 复制知识库 |