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
parent
e7241e4d91
commit
58acd8b33c
|
|
@ -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
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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 被截断的引用会先缓冲再改写,客户端拿到的始终是完整链接。
|
||||
|
||||
### 注意事项
|
||||
|
|
|
|||
|
|
@ -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`。
|
||||
|
||||
**请求参数**:
|
||||
|
||||
|
|
|
|||
|
|
@ -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 '{
|
||||
|
|
|
|||
22
docs/docs.go
22
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": {
|
||||
|
|
|
|||
|
|
@ -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": {
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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),
|
||||
})
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
}
|
||||
|
|
@ -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
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -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 截断的引用会先缓冲再改写,客户端拿到的始终是完整链接。
|
||||
|
||||
使用前需要知道的几件事:
|
||||
|
||||
|
|
|
|||
|
|
@ -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}'
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -115,7 +115,7 @@ kb, err := apiClient.GetKnowledgeBase(ctx, kbID)
|
|||
| `UpdateKnowledgeBase` | 更新知识库 |
|
||||
| `DeleteKnowledgeBase` | 删除知识库 |
|
||||
| `ClearKnowledgeBaseContents` | 清空知识库内容 |
|
||||
| `HybridSearch` | 在知识库内混合检索(向量 + 关键词) |
|
||||
| `HybridSearch` | 在知识库内混合检索(向量 + 关键词);可传 `ResourceURLOptions` 返回文件直链 |
|
||||
| `TogglePinKnowledgeBase` | 置顶/取消置顶 |
|
||||
| `ListMoveTargets` | 列出知识可迁移的目标知识库 |
|
||||
| `CopyKnowledgeBase` | 复制知识库 |
|
||||
|
|
|
|||
Loading…
Reference in New Issue