docs: 更新API文档链接至新路径；新增知识搜索API文档；增强FAQ和标签删除接口说明；移除Swagger文档中的硬编码主机配置

2026-06-04 13:30:32 +08:00 · 2025-12-24 15:45:42 +08:00
parent 762a906a1b
commit 5e16af8cf9
11 changed files with 361 additions and 2604 deletions
--- a/README.md
+++ b/README.md
@@ -323,7 +323,7 @@ Please refer to the [MCP Configuration Guide](./mcp-server/MCP_CONFIG.md) for th

 Troubleshooting FAQ: [Troubleshooting FAQ](./docs/QA.md)

-Detailed API documentation is available at: [API Docs](./docs/API.md)
+Detailed API documentation is available at: [API Docs](./docs/api/README.md)

 ## 🧭 Developer Guide

--- a/README_CN.md
+++ b/README_CN.md
@@ -325,7 +325,7 @@ WeKnora 支持将文档转化为知识图谱，展示文档中不同段落之间

 常见问题排查：[常见问题排查](./docs/QA.md)

-详细接口说明请参考：[API 文档](./docs/API.md)
+详细接口说明请参考：[API 文档](./docs/api/README.md)

 ## 🧭 开发指南

--- a/README_JA.md
+++ b/README_JA.md
@@ -325,7 +325,7 @@ WeKnoraは文書をナレッジグラフに変換し、文書内の異なる段

 よくある問題の解決：[よくある問題](./docs/QA.md)

-詳細なAPIドキュメントは：[APIドキュメント](./docs/API.md)を参照してください
+詳細なAPIドキュメントは：[APIドキュメント](./docs/api/README.md)を参照してください

 ## 🧭 開発ガイド

--- a/cmd/server/main.go
+++ b/cmd/server/main.go
@@ -9,7 +9,6 @@
 // @contact.name   WeKnora Github
 // @contact.url    https://github.com/Tencent/WeKnora
 //
-// @host      localhost:8080
 // @BasePath  /api/v1
 //
 // @securityDefinitions.apikey Bearer
--- a/docs/API.md
+++ b/docs/API.md
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -67,6 +67,7 @@ WeKnora API 按功能分为以下几类：
 | 标签管理 | 管理知识库的标签分类 | [tag.md](./tag.md) |
 | FAQ管理 | 管理FAQ问答对 | [faq.md](./faq.md) |
 | 会话管理 | 创建和管理对话会话 | [session.md](./session.md) |
+| 知识搜索 | 在知识库中搜索内容 | [knowledge-search.md](./knowledge-search.md) |
 | 聊天功能 | 基于知识库和 Agent 进行问答 | [chat.md](./chat.md) |
 | 消息管理 | 获取和管理对话消息 | [message.md](./message.md) |
 | 评估功能 | 评估模型性能 | [evaluation.md](./evaluation.md) |
--- a/docs/api/faq.md
+++ b/docs/api/faq.md
@@ -20,13 +20,32 @@
 - `page_size`: 每页条数（默认 20）
 - `tag_id`: 按标签ID筛选（可选）
 - `keyword`: 关键字搜索（可选）
+- `search_field`: 搜索字段（可选），可选值：
+  - `standard_question`: 只搜索标准问题
+  - `similar_questions`: 只搜索相似问法
+  - `answers`: 只搜索答案
+  - 留空或不传：搜索全部字段
+- `sort_order`: 排序方式（可选），`asc` 表示按更新时间正序，默认按更新时间倒序

 **请求**:

 ```curl
-curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?page=1&page_size=10' \
+# 搜索全部字段
+curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?page=1&page_size=10&keyword=密码' \
 --header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
 --header 'Content-Type: application/json'
+
+# 只搜索标准问题
+curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?keyword=密码&search_field=standard_question' \
+--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ'
+
+# 只搜索相似问法
+curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?keyword=忘记&search_field=similar_questions' \
+--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ'
+
+# 只搜索答案
+curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?keyword=点击&search_field=answers' \
+--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ'
 ```

 **响应**:
--- a/docs/api/knowledge-search.md
+++ b/docs/api/knowledge-search.md
@@ -0,0 +1,74 @@
+# 知识搜索 API
+
+[返回目录](./README.md)
+
+| 方法 | 路径               | 描述     |
+| ---- | ------------------ | -------- |
+| POST | `/knowledge-search` | 知识搜索 |
+
+## POST `/knowledge-search` - 知识搜索
+
+在知识库中搜索相关内容（不使用 LLM 总结），直接返回检索结果。
+
+**请求参数**:
+- `query`: 搜索查询文本（必填）
+- `knowledge_base_id`: 单个知识库ID（向后兼容）
+- `knowledge_base_ids`: 知识库ID列表（支持多知识库搜索）
+- `knowledge_ids`: 指定知识（文件）ID列表
+
+**请求**:
+
+```curl
+# 搜索单个知识库
+curl --location 'http://localhost:8080/api/v1/knowledge-search' \
+--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
+--header 'Content-Type: application/json' \
+--data '{
+    "query": "如何使用知识库",
+    "knowledge_base_id": "kb-00000001"
+}'
+
+# 搜索多个知识库
+curl --location 'http://localhost:8080/api/v1/knowledge-search' \
+--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
+--header 'Content-Type: application/json' \
+--data '{
+    "query": "如何使用知识库",
+    "knowledge_base_ids": ["kb-00000001", "kb-00000002"]
+}'
+
+# 搜索指定文件
+curl --location 'http://localhost:8080/api/v1/knowledge-search' \
+--header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \
+--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
+}
+```
--- a/docs/docs.go
+++ b/docs/docs.go
@@ -265,6 +265,12 @@ const docTemplate = `{
                        "schema": {
                            "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
                        }
+                    },
+                    "403": {
+                        "description": "注册功能已禁用",
+                        "schema": {
+                            "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+                        }
                    }
                }
            }
@@ -1947,6 +1953,18 @@ const docTemplate = `{
                        "description": "关键词搜索",
                        "name": "keyword",
                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "搜索字段: standard_question(标准问题), similar_questions(相似问法), answers(答案), 默认搜索全部",
+                        "name": "search_field",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "排序方式: asc(按更新时间正序), 默认按更新时间倒序",
+                        "name": "sort_order",
+                        "in": "query"
                    }
                ],
                "responses": {
@@ -2241,6 +2259,64 @@ const docTemplate = `{
            }
        },
        "/knowledge-bases/{id}/faq/entries/{entry_id}": {
+            "get": {
+                "security": [
+                    {
+                        "Bearer": []
+                    },
+                    {
+                        "ApiKeyAuth": []
+                    }
+                ],
+                "description": "根据ID获取单个FAQ条目的详情",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "FAQ管理"
+                ],
+                "summary": "获取FAQ条目详情",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "知识库ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "FAQ条目ID",
+                        "name": "entry_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "FAQ条目详情",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "请求参数错误",
+                        "schema": {
+                            "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+                        }
+                    },
+                    "404": {
+                        "description": "条目不存在",
+                        "schema": {
+                            "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+                        }
+                    }
+                }
+            },
            "put": {
                "security": [
                    {
@@ -2958,7 +3034,7 @@ const docTemplate = `{
                        "ApiKeyAuth": []
                    }
                ],
-                "description": "删除标签，可使用force=true强制删除被引用的标签",
+                "description": "删除标签，可使用force=true强制删除被引用的标签，content_only=true仅删除标签下的内容而保留标签本身",
                "consumes": [
                    "application/json"
                ],
@@ -2989,6 +3065,12 @@ const docTemplate = `{
                        "description": "强制删除",
                        "name": "force",
                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "仅删除内容，保留标签",
+                        "name": "content_only",
+                        "in": "query"
                    }
                ],
                "responses": {
@@ -7796,14 +7878,27 @@ const docTemplate = `{
        "internal_handler_session.SearchKnowledgeRequest": {
            "type": "object",
            "required": [
-                "knowledge_base_id",
                "query"
            ],
            "properties": {
                "knowledge_base_id": {
-                    "description": "ID of the knowledge base to search",
+                    "description": "Single knowledge base ID (for backward compatibility)",
                    "type": "string"
                },
+                "knowledge_base_ids": {
+                    "description": "IDs of knowledge bases to search (multi-KB support)",
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "knowledge_ids": {
+                    "description": "IDs of specific knowledge (files) to search",
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
                "query": {
                    "description": "Query text to search for",
                    "type": "string"
@@ -7906,7 +8001,7 @@ const docTemplate = `{
 // SwaggerInfo holds exported Swagger Info so clients can modify it
 var SwaggerInfo = &swag.Spec{
 	Version:          "1.0",
-	Host:             "localhost:8080",
+	Host:             "",
 	BasePath:         "/api/v1",
 	Schemes:          []string{},
 	Title:            "WeKnora API",
--- a/docs/swagger.json
+++ b/docs/swagger.json
@@ -10,7 +10,6 @@
        },
        "version": "1.0"
    },
-    "host": "localhost:8080",
    "basePath": "/api/v1",
    "paths": {
        "/auth/change-password": {
@@ -259,6 +258,12 @@
                        "schema": {
                            "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
                        }
+                    },
+                    "403": {
+                        "description": "注册功能已禁用",
+                        "schema": {
+                            "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+                        }
                    }
                }
            }
@@ -1941,6 +1946,18 @@
                        "description": "关键词搜索",
                        "name": "keyword",
                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "搜索字段: standard_question(标准问题), similar_questions(相似问法), answers(答案), 默认搜索全部",
+                        "name": "search_field",
+                        "in": "query"
+                    },
+                    {
+                        "type": "string",
+                        "description": "排序方式: asc(按更新时间正序), 默认按更新时间倒序",
+                        "name": "sort_order",
+                        "in": "query"
                    }
                ],
                "responses": {
@@ -2235,6 +2252,64 @@
            }
        },
        "/knowledge-bases/{id}/faq/entries/{entry_id}": {
+            "get": {
+                "security": [
+                    {
+                        "Bearer": []
+                    },
+                    {
+                        "ApiKeyAuth": []
+                    }
+                ],
+                "description": "根据ID获取单个FAQ条目的详情",
+                "consumes": [
+                    "application/json"
+                ],
+                "produces": [
+                    "application/json"
+                ],
+                "tags": [
+                    "FAQ管理"
+                ],
+                "summary": "获取FAQ条目详情",
+                "parameters": [
+                    {
+                        "type": "string",
+                        "description": "知识库ID",
+                        "name": "id",
+                        "in": "path",
+                        "required": true
+                    },
+                    {
+                        "type": "string",
+                        "description": "FAQ条目ID",
+                        "name": "entry_id",
+                        "in": "path",
+                        "required": true
+                    }
+                ],
+                "responses": {
+                    "200": {
+                        "description": "FAQ条目详情",
+                        "schema": {
+                            "type": "object",
+                            "additionalProperties": true
+                        }
+                    },
+                    "400": {
+                        "description": "请求参数错误",
+                        "schema": {
+                            "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+                        }
+                    },
+                    "404": {
+                        "description": "条目不存在",
+                        "schema": {
+                            "$ref": "#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError"
+                        }
+                    }
+                }
+            },
            "put": {
                "security": [
                    {
@@ -2952,7 +3027,7 @@
                        "ApiKeyAuth": []
                    }
                ],
-                "description": "删除标签，可使用force=true强制删除被引用的标签",
+                "description": "删除标签，可使用force=true强制删除被引用的标签，content_only=true仅删除标签下的内容而保留标签本身",
                "consumes": [
                    "application/json"
                ],
@@ -2983,6 +3058,12 @@
                        "description": "强制删除",
                        "name": "force",
                        "in": "query"
+                    },
+                    {
+                        "type": "boolean",
+                        "description": "仅删除内容，保留标签",
+                        "name": "content_only",
+                        "in": "query"
                    }
                ],
                "responses": {
@@ -7790,14 +7871,27 @@
        "internal_handler_session.SearchKnowledgeRequest": {
            "type": "object",
            "required": [
-                "knowledge_base_id",
                "query"
            ],
            "properties": {
                "knowledge_base_id": {
-                    "description": "ID of the knowledge base to search",
+                    "description": "Single knowledge base ID (for backward compatibility)",
                    "type": "string"
                },
+                "knowledge_base_ids": {
+                    "description": "IDs of knowledge bases to search (multi-KB support)",
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
+                "knowledge_ids": {
+                    "description": "IDs of specific knowledge (files) to search",
+                    "type": "array",
+                    "items": {
+                        "type": "string"
+                    }
+                },
                "query": {
                    "description": "Query text to search for",
                    "type": "string"
--- a/docs/swagger.yaml
+++ b/docs/swagger.yaml
@@ -1690,13 +1690,22 @@ definitions:
  internal_handler_session.SearchKnowledgeRequest:
    properties:
      knowledge_base_id:
-        description: ID of the knowledge base to search
+        description: Single knowledge base ID (for backward compatibility)
        type: string
+      knowledge_base_ids:
+        description: IDs of knowledge bases to search (multi-KB support)
+        items:
+          type: string
+        type: array
+      knowledge_ids:
+        description: IDs of specific knowledge (files) to search
+        items:
+          type: string
+        type: array
      query:
        description: Query text to search for
        type: string
    required:
-    - knowledge_base_id
    - query
    type: object
  internal_handler_session.SessionStrategy:
@@ -1750,7 +1759,6 @@ definitions:
    required:
    - message_id
    type: object
-host: localhost:8080
 info:
  contact:
    name: WeKnora Github
@@ -1917,6 +1925,10 @@ paths:
          description: 请求参数错误
          schema:
            $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+        "403":
+          description: 注册功能已禁用
+          schema:
+            $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
      summary: 用户注册
      tags:
      - 认证
@@ -2940,6 +2952,15 @@ paths:
        in: query
        name: keyword
        type: string
+      - description: '搜索字段: standard_question(标准问题), similar_questions(相似问法), answers(答案),
+          默认搜索全部'
+        in: query
+        name: search_field
+        type: string
+      - description: '排序方式: asc(按更新时间正序), 默认按更新时间倒序'
+        in: query
+        name: sort_order
+        type: string
      produces:
      - application/json
      responses:
@@ -2993,6 +3014,43 @@ paths:
      tags:
      - FAQ管理
  /knowledge-bases/{id}/faq/entries/{entry_id}:
+    get:
+      consumes:
+      - application/json
+      description: 根据ID获取单个FAQ条目的详情
+      parameters:
+      - description: 知识库ID
+        in: path
+        name: id
+        required: true
+        type: string
+      - description: FAQ条目ID
+        in: path
+        name: entry_id
+        required: true
+        type: string
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: FAQ条目详情
+          schema:
+            additionalProperties: true
+            type: object
+        "400":
+          description: 请求参数错误
+          schema:
+            $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+        "404":
+          description: 条目不存在
+          schema:
+            $ref: '#/definitions/github_com_Tencent_WeKnora_internal_errors.AppError'
+      security:
+      - Bearer: []
+      - ApiKeyAuth: []
+      summary: 获取FAQ条目详情
+      tags:
+      - FAQ管理
    put:
      consumes:
      - application/json
@@ -3503,7 +3561,7 @@ paths:
    delete:
      consumes:
      - application/json
-      description: 删除标签，可使用force=true强制删除被引用的标签
+      description: 删除标签，可使用force=true强制删除被引用的标签，content_only=true仅删除标签下的内容而保留标签本身
      parameters:
      - description: 知识库ID
        in: path
@@ -3519,6 +3577,10 @@ paths:
        in: query
        name: force
        type: boolean
+      - description: 仅删除内容，保留标签
+        in: query
+        name: content_only
+        type: boolean
      produces:
      - application/json
      responses: