Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

feat(api): honor resource_urls=public on hybrid-search

wizardchen58acd8b33cf5
diff --git a/client/knowledgebase.go b/client/knowledgebase.go
index 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.go
index 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.md
index 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.md
index 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.md
index 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.go
index 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.json
index 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.yaml
index d33c6f087..334ca9c22 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 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 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 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 ![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 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.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 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.md
index 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.md
index 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` | 复制知识库 |