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.
main
wizardchen 2026-08-26 17:31:05 +08:00 committed by lyingbug
parent e7241e4d91
commit 58acd8b33c
14 changed files with 240 additions and 14 deletions

View File

@ -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
}

View File

@ -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
}

View File

@ -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 被截断的引用会先缓冲再改写,客户端拿到的始终是完整链接。
### 注意事项

View File

@ -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`。
**请求参数**:

View File

@ -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 '{

View File

@ -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": {

View File

@ -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": {

View File

@ -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:

View File

@ -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),
})
}

View File

@ -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)
}

View File

@ -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
}

View File

@ -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 截断的引用会先缓冲再改写,客户端拿到的始终是完整链接。
使用前需要知道的几件事:

View File

@ -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}'
```

View File

@ -115,7 +115,7 @@ kb, err := apiClient.GetKnowledgeBase(ctx, kbID)
| `UpdateKnowledgeBase` | 更新知识库 |
| `DeleteKnowledgeBase` | 删除知识库 |
| `ClearKnowledgeBaseContents` | 清空知识库内容 |
| `HybridSearch` | 在知识库内混合检索(向量 + 关键词) |
| `HybridSearch` | 在知识库内混合检索(向量 + 关键词);可传 `ResourceURLOptions` 返回文件直链 |
| `TogglePinKnowledgeBase` | 置顶/取消置顶 |
| `ListMoveTargets` | 列出知识可迁移的目标知识库 |
| `CopyKnowledgeBase` | 复制知识库 |