From ef54e835c907718cedf7316bfa93daf69a28b2ba Mon Sep 17 00:00:00 2001 From: lyingbug Date: Mon, 12 Oct 2026 17:40:56 +0800 Subject: [PATCH] docs(api): clarify knowledge-search scope union of knowledge_base_ids and knowledge_ids (#4191) --- website-docs/04-api/01-api-overview.md | 2 +- website-docs/04-api/02-api-chat.md | 8 +++++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/website-docs/04-api/01-api-overview.md b/website-docs/04-api/01-api-overview.md index 7653b3b6c..27c268ced 100644 --- a/website-docs/04-api/01-api-overview.md +++ b/website-docs/04-api/01-api-overview.md @@ -239,7 +239,7 @@ X-Accel-Buffering: no | --- | --- | --- | | 给自己的 RAG / 智能体拿检索结果，排序和页面问答一致 | `knowledge-search` | `query` + `knowledge_base_ids`，其余不填 | | 同时搜多个知识库，且它们用的 embedding 模型不同 | `knowledge-search` | `knowledge_base_ids` | -| 只在某几个文档或标签里搜 | `knowledge-search` | `knowledge_ids` / `tag_ids` | +| 只在某几个文档或标签里搜 | `knowledge-search` | `knowledge_ids` / `tag_ids`；只搜指定文档时不要再传它们所在的 `knowledge_base_ids`，两者取并集 | | 调整返回条数或召回阈值，但仍然要 rerank | `knowledge-search` | `match_count`、`vector_threshold`、`keyword_threshold` | | 换一个 rerank 模型，或改 rerank 阈值 | `knowledge-search` | `rerank.model_id`、`rerank.threshold` | | 不要 rerank，直接拿召回结果 | `knowledge-search` 或 `hybrid-search` | 前者传 `"rerank":{"enabled":false}`；后者不传 `rerank` | diff --git a/website-docs/04-api/02-api-chat.md b/website-docs/04-api/02-api-chat.md index e613b72ce..c8c82773e 100644 --- a/website-docs/04-api/02-api-chat.md +++ b/website-docs/04-api/02-api-chat.md @@ -424,7 +424,7 @@ curl -N -X POST $BASE/api/v1/agent-chat/s-1 -H "Authorization: Bearer $TOKEN" \ | `query` | string | 是（`binding:"required"`） | 查询 | | `knowledge_base_id` | string | 否 | 单 KB（兼容旧版） | | `knowledge_base_ids` | []string | 否 | 多 KB | -| `knowledge_ids` | []string | 否 | 限定文件 | +| `knowledge_ids` | []string | 否 | 指定文件，与 `knowledge_base_id(s)` 取并集（见下方说明） | | `tag_ids` | []string | 否 | 标签过滤 | | `mentioned_items` | []object | 否 | 带 KB 范围的标签提及 | | `vector_threshold` / `keyword_threshold` | float | 否 | 召回阈值；省略时用空间检索配置（默认 0.15 / 0.3） | @@ -434,6 +434,8 @@ curl -N -X POST $BASE/api/v1/agent-chat/s-1 -H "Authorization: Bearer $TOKEN" \ 省略的字段都沿用空间的检索配置（`GET /tenants/kv/retrieval-config`），不传任何新字段时行为和以前一样。 +检索范围是 `knowledge_base_id(s)` 与 `knowledge_ids` 的并集，与产品内 @ 提及的语义一致：每个知识库整库检索，`knowledge_ids` 中属于这些知识库的文件已被覆盖，不再单独限定；属于其他知识库的文件会额外加入检索。**只想在指定文件里搜时，只传 `knowledge_ids`，不要同时传它们所在的知识库**，否则会检索整个知识库。 + 响应：200 `{"success":true,"data":[SearchResult],"meta":{"rerank":{...}}}`。`SearchResult` 含 `id,content,knowledge_id,knowledge_title,score,chunk_type,knowledge_base_id,...`；经过 rerank 的结果 `metadata` 带 `model_score` 和 `base_score`。`data` 为空时看 `meta.rerank.outcome` 判断原因，见 [meta.rerank 诊断](./01-api-overview.md#retrieval-api)。 ```bash @@ -444,6 +446,10 @@ curl -X POST $BASE/api/v1/knowledge-search -H "X-API-Key: $API_KEY" \ curl -X POST $BASE/api/v1/knowledge-search -H "X-API-Key: $API_KEY" \ -H 'Content-Type: application/json' \ -d '{"query":"部署要求","knowledge_base_ids":["kb-1"],"disable_keywords_match":true,"match_count":5,"rerank":{"enabled":false}}' + +# 只在指定文件里搜（不传 knowledge_base_ids） +curl -X POST $BASE/api/v1/knowledge-search -H "X-API-Key: $API_KEY" \ + -H 'Content-Type: application/json' -d '{"query":"部署要求","knowledge_ids":["k-1","k-2"]}' ``` ## 消息（/api/v1/messages）