WeKnora/docs/api/knowledge-search.md

102 lines
4.0 KiB
Markdown
Raw Normal View History

# 知识搜索 API
[返回目录](./README.md)
| 方法 | 路径 | 描述 |
| ---- | ------------------ | -------- |
| POST | `/knowledge-search` | 知识搜索 |
## POST `/knowledge-search` - 知识搜索
在知识库中搜索相关内容(不使用 LLM 总结),直接返回检索结果。
docs(api): rewrite markdown to match current routes Refs #890 #1049 #1168. 按集成方视角全量审计 17 个 API markdown 文档与 internal/router/router.go 对齐。每个端点新增参数说明小节(path/query/body 字段含义)和响应字段 含义说明(#1168 的核心诉求)。 【与代码对齐】 - 删除已下线端点:system.md 中的 /system/minio/buckets(代码中已无对 应路由)。 - 修正路径错误:chunk.md 中 /chunks/get-by-id/:id → /chunks/by-id/:id; /chunks/:id/delete-question → /chunks/by-id/:id/questions; organization.md 中 /organizations/preview/:invite_code → :code。 - 修正字段类型:faq tag_id / entry_id 由 string 改为 int64; knowledge.search 响应结构纠正。 - 补齐缺失端点(move-targets、batch-delete、move/progress、pin/unpin/ stop/continue-stream、tool-approvals、organization agent-shares 等 30+ 条)。 【精简】 - knowledge-base.md / model.md 把重复 5 次 / 3 次的完整对象样例 收敛为指向首次出现("字段结构同 POST /xxx 响应"),节省约 400 行 而不损失信息(仅去重,原作者写的每个字段定义都保留可达)。 - 示例 X-API-Key 统一为 sk-xxxxx(避免读者复制看似真实的 key)。 【清理】 - 删除内部实现细节引用:mcp-service.md 中 6 处 "issue #1173"、 organization.md 中 "RegisterOrganizationRoutes" 等。 不动 initialization.md:其中端点(KB 配置、模型连通性测试、Ollama 管理) 对集成方有实用价值,保留原作者写好的内容不删。 格式统一遵循 web-search.md 重写后的范式(路由表 + 每端点方法/路径 + 参数表 + curl + 响应 JSON + 字段说明)。
2026-05-11 09:37:14 +00:00
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ------------------- | -------- | ---- | ---------------------------------------------------------- |
| query | string | 是 | 搜索查询文本 |
| knowledge_base_id | string | 否 | 单个知识库 ID(向后兼容);与 `knowledge_base_ids` 互斥 |
| knowledge_base_ids | string[] | 否 | 多个知识库 ID 列表,跨知识库搜索 |
| knowledge_ids | string[] | 否 | 进一步限定到指定知识(文件);不传则在整库范围内搜索 |
> 必须指定 `knowledge_base_id` 或 `knowledge_base_ids` 中的至少一个。
**查询参数**:
- `resource_urls`: `handle`(默认)或 `public`。`public` 把检索结果 `content` / `image_info` 里的 `resource://` 引用换成可加载的 http(s) 链接,详见[文件与图片引用](./README.md#文件与图片引用resource-与直链)
**请求**:
```curl
# 搜索单个知识库
curl --location 'http://localhost:8080/api/v1/knowledge-search' \
docs(api): rewrite markdown to match current routes Refs #890 #1049 #1168. 按集成方视角全量审计 17 个 API markdown 文档与 internal/router/router.go 对齐。每个端点新增参数说明小节(path/query/body 字段含义)和响应字段 含义说明(#1168 的核心诉求)。 【与代码对齐】 - 删除已下线端点:system.md 中的 /system/minio/buckets(代码中已无对 应路由)。 - 修正路径错误:chunk.md 中 /chunks/get-by-id/:id → /chunks/by-id/:id; /chunks/:id/delete-question → /chunks/by-id/:id/questions; organization.md 中 /organizations/preview/:invite_code → :code。 - 修正字段类型:faq tag_id / entry_id 由 string 改为 int64; knowledge.search 响应结构纠正。 - 补齐缺失端点(move-targets、batch-delete、move/progress、pin/unpin/ stop/continue-stream、tool-approvals、organization agent-shares 等 30+ 条)。 【精简】 - knowledge-base.md / model.md 把重复 5 次 / 3 次的完整对象样例 收敛为指向首次出现("字段结构同 POST /xxx 响应"),节省约 400 行 而不损失信息(仅去重,原作者写的每个字段定义都保留可达)。 - 示例 X-API-Key 统一为 sk-xxxxx(避免读者复制看似真实的 key)。 【清理】 - 删除内部实现细节引用:mcp-service.md 中 6 处 "issue #1173"、 organization.md 中 "RegisterOrganizationRoutes" 等。 不动 initialization.md:其中端点(KB 配置、模型连通性测试、Ollama 管理) 对集成方有实用价值,保留原作者写好的内容不删。 格式统一遵循 web-search.md 重写后的范式(路由表 + 每端点方法/路径 + 参数表 + curl + 响应 JSON + 字段说明)。
2026-05-11 09:37:14 +00:00
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"query": "如何使用知识库",
"knowledge_base_id": "kb-00000001"
}'
# 搜索多个知识库
curl --location 'http://localhost:8080/api/v1/knowledge-search' \
docs(api): rewrite markdown to match current routes Refs #890 #1049 #1168. 按集成方视角全量审计 17 个 API markdown 文档与 internal/router/router.go 对齐。每个端点新增参数说明小节(path/query/body 字段含义)和响应字段 含义说明(#1168 的核心诉求)。 【与代码对齐】 - 删除已下线端点:system.md 中的 /system/minio/buckets(代码中已无对 应路由)。 - 修正路径错误:chunk.md 中 /chunks/get-by-id/:id → /chunks/by-id/:id; /chunks/:id/delete-question → /chunks/by-id/:id/questions; organization.md 中 /organizations/preview/:invite_code → :code。 - 修正字段类型:faq tag_id / entry_id 由 string 改为 int64; knowledge.search 响应结构纠正。 - 补齐缺失端点(move-targets、batch-delete、move/progress、pin/unpin/ stop/continue-stream、tool-approvals、organization agent-shares 等 30+ 条)。 【精简】 - knowledge-base.md / model.md 把重复 5 次 / 3 次的完整对象样例 收敛为指向首次出现("字段结构同 POST /xxx 响应"),节省约 400 行 而不损失信息(仅去重,原作者写的每个字段定义都保留可达)。 - 示例 X-API-Key 统一为 sk-xxxxx(避免读者复制看似真实的 key)。 【清理】 - 删除内部实现细节引用:mcp-service.md 中 6 处 "issue #1173"、 organization.md 中 "RegisterOrganizationRoutes" 等。 不动 initialization.md:其中端点(KB 配置、模型连通性测试、Ollama 管理) 对集成方有实用价值,保留原作者写好的内容不删。 格式统一遵循 web-search.md 重写后的范式(路由表 + 每端点方法/路径 + 参数表 + curl + 响应 JSON + 字段说明)。
2026-05-11 09:37:14 +00:00
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"query": "如何使用知识库",
"knowledge_base_ids": ["kb-00000001", "kb-00000002"]
}'
# 搜索指定文件
curl --location 'http://localhost:8080/api/v1/knowledge-search' \
docs(api): rewrite markdown to match current routes Refs #890 #1049 #1168. 按集成方视角全量审计 17 个 API markdown 文档与 internal/router/router.go 对齐。每个端点新增参数说明小节(path/query/body 字段含义)和响应字段 含义说明(#1168 的核心诉求)。 【与代码对齐】 - 删除已下线端点:system.md 中的 /system/minio/buckets(代码中已无对 应路由)。 - 修正路径错误:chunk.md 中 /chunks/get-by-id/:id → /chunks/by-id/:id; /chunks/:id/delete-question → /chunks/by-id/:id/questions; organization.md 中 /organizations/preview/:invite_code → :code。 - 修正字段类型:faq tag_id / entry_id 由 string 改为 int64; knowledge.search 响应结构纠正。 - 补齐缺失端点(move-targets、batch-delete、move/progress、pin/unpin/ stop/continue-stream、tool-approvals、organization agent-shares 等 30+ 条)。 【精简】 - knowledge-base.md / model.md 把重复 5 次 / 3 次的完整对象样例 收敛为指向首次出现("字段结构同 POST /xxx 响应"),节省约 400 行 而不损失信息(仅去重,原作者写的每个字段定义都保留可达)。 - 示例 X-API-Key 统一为 sk-xxxxx(避免读者复制看似真实的 key)。 【清理】 - 删除内部实现细节引用:mcp-service.md 中 6 处 "issue #1173"、 organization.md 中 "RegisterOrganizationRoutes" 等。 不动 initialization.md:其中端点(KB 配置、模型连通性测试、Ollama 管理) 对集成方有实用价值,保留原作者写好的内容不删。 格式统一遵循 web-search.md 重写后的范式(路由表 + 每端点方法/路径 + 参数表 + curl + 响应 JSON + 字段说明)。
2026-05-11 09:37:14 +00:00
--header 'X-API-Key: sk-xxxxx' \
--header 'Content-Type: application/json' \
--data '{
"query": "如何使用知识库",
"knowledge_ids": ["4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5"]
}'
```
**响应**:
```json
{
"data": [
{
"id": "chunk-00000001",
"content": "知识库是用于存储和检索知识的系统...",
"knowledge_id": "knowledge-00000001",
"chunk_index": 0,
"knowledge_title": "知识库使用指南",
"start_at": 0,
"end_at": 500,
"seq": 1,
"score": 0.95,
"chunk_type": "text",
"image_info": "",
"metadata": {},
"knowledge_filename": "guide.pdf",
"knowledge_source": "file"
}
],
"success": true
}
```
docs(api): rewrite markdown to match current routes Refs #890 #1049 #1168. 按集成方视角全量审计 17 个 API markdown 文档与 internal/router/router.go 对齐。每个端点新增参数说明小节(path/query/body 字段含义)和响应字段 含义说明(#1168 的核心诉求)。 【与代码对齐】 - 删除已下线端点:system.md 中的 /system/minio/buckets(代码中已无对 应路由)。 - 修正路径错误:chunk.md 中 /chunks/get-by-id/:id → /chunks/by-id/:id; /chunks/:id/delete-question → /chunks/by-id/:id/questions; organization.md 中 /organizations/preview/:invite_code → :code。 - 修正字段类型:faq tag_id / entry_id 由 string 改为 int64; knowledge.search 响应结构纠正。 - 补齐缺失端点(move-targets、batch-delete、move/progress、pin/unpin/ stop/continue-stream、tool-approvals、organization agent-shares 等 30+ 条)。 【精简】 - knowledge-base.md / model.md 把重复 5 次 / 3 次的完整对象样例 收敛为指向首次出现("字段结构同 POST /xxx 响应"),节省约 400 行 而不损失信息(仅去重,原作者写的每个字段定义都保留可达)。 - 示例 X-API-Key 统一为 sk-xxxxx(避免读者复制看似真实的 key)。 【清理】 - 删除内部实现细节引用:mcp-service.md 中 6 处 "issue #1173"、 organization.md 中 "RegisterOrganizationRoutes" 等。 不动 initialization.md:其中端点(KB 配置、模型连通性测试、Ollama 管理) 对集成方有实用价值,保留原作者写好的内容不删。 格式统一遵循 web-search.md 重写后的范式(路由表 + 每端点方法/路径 + 参数表 + curl + 响应 JSON + 字段说明)。
2026-05-11 09:37:14 +00:00
**响应字段说明(data[])**:
| 字段 | 类型 | 说明 |
| ------------------ | ------- | ------------------------------------- |
| id | string | 分块 ID |
| content | string | 命中的分块文本 |
| knowledge_id | string | 该分块所属的知识 ID |
| chunk_index | int | 分块在知识中的序号 |
| knowledge_title | string | 来源知识标题 |
| start_at / end_at | int | 分块在源文档中的字符偏移 |
| seq | int | 命中排序号 |
| score | number | 相似度(rerank 后归一化后的最终得分) |
| chunk_type | string | 分块类型(`text` / `image` / ...) |
| image_info | string | 图像分块的额外信息(JSON 字符串) |
| metadata | object | 自定义元数据 |
| knowledge_filename | string | 来源文件名 |
| knowledge_source | string | 来源类型(`file` / `url` / `manual`) |