diff --git a/README.md b/README.md index 06af5d61..0f7ba67f 100644 --- 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 diff --git a/README_CN.md b/README_CN.md index 9b69b4fd..e6d4f17d 100644 --- 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) ## 🧭 开发指南 diff --git a/README_JA.md b/README_JA.md index f718315a..6d70ee5a 100644 --- 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)を参照してください ## 🧭 開発ガイド diff --git a/client/faq.go b/client/faq.go index 5f2f32c9..039016fe 100644 --- a/client/faq.go +++ b/client/faq.go @@ -17,6 +17,7 @@ type FAQEntry struct { KnowledgeID string `json:"knowledge_id"` KnowledgeBaseID string `json:"knowledge_base_id"` TagID string `json:"tag_id"` + TagName string `json:"tag_name"` IsEnabled bool `json:"is_enabled"` IsRecommended bool `json:"is_recommended"` StandardQuestion string `json:"standard_question"` @@ -139,8 +140,10 @@ type faqSimpleResponse struct { } // ListFAQEntries returns paginated FAQ entries under a knowledge base. +// searchField: specifies which field to search in ("standard_question", "similar_questions", "answers", "" for all) +// sortOrder: "asc" for time ascending (updated_at ASC), default is time descending (updated_at DESC) func (c *Client) ListFAQEntries(ctx context.Context, - knowledgeBaseID string, page, pageSize int, tagID string, keyword string, + knowledgeBaseID string, page, pageSize int, tagID string, keyword string, searchField string, sortOrder string, ) (*FAQEntriesPage, error) { path := fmt.Sprintf("/api/v1/knowledge-bases/%s/faq/entries", knowledgeBaseID) query := url.Values{} @@ -156,6 +159,12 @@ func (c *Client) ListFAQEntries(ctx context.Context, if keyword != "" { query.Add("keyword", keyword) } + if searchField != "" { + query.Add("search_field", searchField) + } + if sortOrder != "" { + query.Add("sort_order", sortOrder) + } resp, err := c.doRequest(ctx, http.MethodGet, path, nil, query) if err != nil { diff --git a/client/session.go b/client/session.go index 7b9de4ee..ff6ad437 100644 --- a/client/session.go +++ b/client/session.go @@ -423,8 +423,10 @@ func (c *Client) StopSession(ctx context.Context, sessionID string, messageID st // SearchKnowledgeRequest knowledge search request type SearchKnowledgeRequest struct { - Query string `json:"query"` // Query content - KnowledgeBaseID string `json:"knowledge_base_id"` // Knowledge base ID + Query string `json:"query"` // Query content + KnowledgeBaseID string `json:"knowledge_base_id,omitempty"` // Single knowledge base ID (for backward compatibility) + KnowledgeBaseIDs []string `json:"knowledge_base_ids,omitempty"` // Knowledge base IDs (multi-KB support) + KnowledgeIDs []string `json:"knowledge_ids,omitempty"` // Specific knowledge (file) IDs } // SearchKnowledgeResponse search results response @@ -435,8 +437,8 @@ type SearchKnowledgeResponse struct { // SearchKnowledge performs knowledge base search without LLM summarization func (c *Client) SearchKnowledge(ctx context.Context, request *SearchKnowledgeRequest) ([]*SearchResult, error) { - fmt.Printf("Starting SearchKnowledge request, knowledge base ID: %s, query: %s\n", - request.KnowledgeBaseID, request.Query) + fmt.Printf("Starting SearchKnowledge request, knowledge base IDs: %v, knowledge IDs: %v, query: %s\n", + request.KnowledgeBaseIDs, request.KnowledgeIDs, request.Query) resp, err := c.doRequest(ctx, http.MethodPost, "/api/v1/knowledge-search", request, nil) if err != nil { diff --git a/cmd/server/main.go b/cmd/server/main.go index 23b5cd8e..e27f431e 100644 --- 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 diff --git a/docs/API.md b/docs/API.md deleted file mode 100644 index 3dcef43c..00000000 --- a/docs/API.md +++ /dev/null @@ -1,2587 +0,0 @@ -# WeKnora API 文档 - -## 目录 - -- [概述](#概述) -- [基础信息](#基础信息) -- [认证机制](#认证机制) -- [错误处理](#错误处理) -- [API 概览](#api-概览) -- [API 详细说明](#api-详细说明) - - [租户管理 API](#租户管理api) - - [知识库管理 API](#知识库管理api) - - [知识管理 API](#知识管理api) - - [模型管理 API](#模型管理api) - - [分块管理 API](#分块管理api) - - [标签管理 API](#标签管理api) - - [FAQ管理 API](#faq管理api) - - [会话管理 API](#会话管理api) - - [聊天功能 API](#聊天功能api) - - [消息管理 API](#消息管理api) - - [评估功能 API](#评估功能api) - -## 概述 - -WeKnora 提供了一系列 RESTful API,用于创建和管理知识库、检索知识,以及进行基于知识的问答。本文档详细描述了这些 API 的使用方式。 - -## 基础信息 - -- **基础 URL**: `/api/v1` -- **响应格式**: JSON -- **认证方式**: API Key - -## 认证机制 - -所有 API 请求需要在 HTTP 请求头中包含 `X-API-Key` 进行身份认证: - -``` -X-API-Key: your_api_key -``` - -为便于问题追踪和调试,建议每个请求的 HTTP 请求头中添加 `X-Request-ID`: - -``` -X-Request-ID: unique_request_id -``` - -### 获取 API Key - -在 web 页面完成账户注册后,请前往账户信息页面获取您的 API Key。 - -请妥善保管您的 API Key,避免泄露。API Key 代表您的账户身份,拥有完整的 API 访问权限。 - -## 错误处理 - -所有 API 使用标准的 HTTP 状态码表示请求状态,并返回统一的错误响应格式: - -```json -{ - "success": false, - "error": { - "code": "错误代码", - "message": "错误信息", - "details": "错误详情" - } -} -``` - -## API 概览 - -WeKnora API 按功能分为以下几类: - -1. **租户管理**:创建和管理租户账户 -2. **知识库管理**:创建、查询和管理知识库 -3. **知识管理**:上传、检索和管理知识内容 -4. **模型管理**:配置和管理各种AI模型 -5. **分块管理**:管理知识的分块内容 -6. **标签管理**:管理知识库的标签分类 -7. **FAQ管理**:管理FAQ问答对 -8. **会话管理**:创建和管理对话会话 -9. **聊天功能**:基于知识库进行问答 -10. **消息管理**:获取和管理对话消息 -11. **评估功能**:评估模型性能 - -## API 详细说明 - -以下是每个API的详细说明和示例。 - -### 租户管理API - -| 方法 | 路径 | 描述 | -| ------ | -------------- | --------------------- | -| POST | `/tenants` | 创建新租户 | -| GET | `/tenants/:id` | 获取指定租户信息 | -| PUT | `/tenants/:id` | 更新租户信息 | -| DELETE | `/tenants/:id` | 删除租户 | -| GET | `/tenants` | 获取租户列表 | - -#### POST `/tenants` - 创建新租户 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/tenants' \ ---header 'Content-Type: application/json' \ ---data '{ - "name": "weknora", - "description": "weknora tenants", - "business": "wechat", - "retriever_engines": { - "engines": [ - { - "retriever_type": "keywords", - "retriever_engine_type": "postgres" - }, - { - "retriever_type": "vector", - "retriever_engine_type": "postgres" - } - ] - } -}' -``` - -**响应**: - -```json -{ - "data": { - "id": 10000, - "name": "weknora", - "description": "weknora tenants", - "api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG", - "status": "active", - "retriever_engines": { - "engines": [ - { - "retriever_engine_type": "postgres", - "retriever_type": "keywords" - }, - { - "retriever_engine_type": "postgres", - "retriever_type": "vector" - } - ] - }, - "business": "wechat", - "storage_quota": 10737418240, - "storage_used": 0, - "created_at": "2025-08-11T20:37:28.396980093+08:00", - "updated_at": "2025-08-11T20:37:28.396980301+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/tenants/:id` - 获取指定租户信息 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/tenants/10000' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG' -``` - -**响应**: - -```json -{ - "data": { - "id": 10000, - "name": "weknora", - "description": "weknora tenants", - "api_key": "sk-aaLRAgvCRJcmtiL2vLMeB1FB5UV0Q-qB7DlTE1pJ9KA93XZG", - "status": "active", - "retriever_engines": { - "engines": [ - { - "retriever_engine_type": "postgres", - "retriever_type": "keywords" - }, - { - "retriever_engine_type": "postgres", - "retriever_type": "vector" - } - ] - }, - "business": "wechat", - "storage_quota": 10737418240, - "storage_used": 0, - "created_at": "2025-08-11T20:37:28.39698+08:00", - "updated_at": "2025-08-11T20:37:28.405693+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### PUT `/tenants/:id` - 更新租户信息 - -注意 API Key 会变更 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/tenants/10000' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-KREi84yPtahKxMtIMOW-Cxx2dxb9xROpUuDSpi3vbiC1QVDe' \ ---data '{ - "name": "weknora new", - "description": "weknora tenants new", - "status": "active", - "retriever_engines": { - "engines": [ - { - "retriever_engine_type": "postgres", - "retriever_type": "keywords" - }, - { - "retriever_engine_type": "postgres", - "retriever_type": "vector" - } - ] - }, - "business": "wechat", - "storage_quota": 10737418240 -}' -``` - -**响应**: - -```json -{ - "data": { - "id": 10000, - "name": "weknora new", - "description": "weknora tenants new", - "api_key": "sk-IKtd9JGV4-aPGQ6RiL8YJu9Vzb3-ae4lgFkjFJZmhvUn2mLu", - "status": "active", - "retriever_engines": { - "engines": [ - { - "retriever_engine_type": "postgres", - "retriever_type": "keywords" - }, - { - "retriever_engine_type": "postgres", - "retriever_type": "vector" - } - ] - }, - "business": "wechat", - "storage_quota": 10737418240, - "storage_used": 0, - "created_at": "0001-01-01T00:00:00Z", - "updated_at": "2025-08-11T20:49:02.13421034+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### DELETE `/tenants/:id` - 删除租户 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/tenants/10000' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-IKtd9JGV4-aPGQ6RiL8YJu9Vzb3-ae4lgFkjFJZmhvUn2mLu' -``` - -**响应**: - -```json -{ - "message": "Tenant deleted successfully", - "success": true -} -``` - -#### GET `/tenants` - 获取租户列表 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/tenants' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-An7_t_izCKFIJ4iht9Xjcjnj_MC48ILvwezEDki9ScfIa7KA' -``` - -**响应**: - -```json -{ - "data": { - "items": [ - { - "id": 10002, - "name": "weknora", - "description": "weknora tenants", - "api_key": "sk-An7_t_izCKFIJ4iht9Xjcjnj_MC48ILvwezEDki9ScfIa7KA", - "status": "active", - "retriever_engines": { - "engines": [ - { - "retriever_engine_type": "postgres", - "retriever_type": "keywords" - }, - { - "retriever_engine_type": "postgres", - "retriever_type": "vector" - } - ] - }, - "business": "wechat", - "storage_quota": 10737418240, - "storage_used": 0, - "created_at": "2025-08-11T20:52:58.05679+08:00", - "updated_at": "2025-08-11T20:52:58.060495+08:00", - "deleted_at": null - } - ] - }, - "success": true -} -``` - -
返回顶部 ↑
- -### 知识库管理API - -| 方法 | 路径 | 描述 | -| ------ | ------------------------------------ | ------------------------ | -| POST | `/knowledge-bases` | 创建知识库 | -| GET | `/knowledge-bases` | 获取知识库列表 | -| GET | `/knowledge-bases/:id` | 获取知识库详情 | -| PUT | `/knowledge-bases/:id` | 更新知识库 | -| DELETE | `/knowledge-bases/:id` | 删除知识库 | -| POST | `/knowledge-bases/copy` | 拷贝知识库 | -| GET | `/knowledge-bases/:id/hybrid-search` | 混合搜索(向量+关键词) | - -#### POST `/knowledge-bases` - 创建知识库 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---data '{ - "name": "weknora", - "description": "weknora description", - "chunking_config": { - "chunk_size": 1000, - "chunk_overlap": 200, - "separators": [ - "." - ], - "enable_multimodal": true - }, - "image_processing_config": { - "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" - }, - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", - "vlm_config": { - "enabled": true, - "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" - }, - "cos_config": { - "secret_id": "", - "secret_key": "", - "region": "", - "bucket_name": "", - "app_id": "", - "path_prefix": "" - } -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "b5829e4a-3845-4624-a7fb-ea3b35e843b0", - "name": "weknora", - "description": "weknora description", - "tenant_id": 1, - "chunking_config": { - "chunk_size": 1000, - "chunk_overlap": 200, - "separators": [ - "." - ], - "enable_multimodal": true - }, - "image_processing_config": { - "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" - }, - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", - "vlm_config": { - "enabled": true, - "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" - }, - "cos_config": { - "secret_id": "", - "secret_key": "", - "region": "", - "bucket_name": "", - "app_id": "", - "path_prefix": "" - }, - "created_at": "2025-08-12T11:30:09.206238645+08:00", - "updated_at": "2025-08-12T11:30:09.206238854+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/knowledge-bases` - 获取知识库列表 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "kb-00000001", - "name": "Default Knowledge Base", - "description": "System Default Knowledge Base", - "tenant_id": 1, - "chunking_config": { - "chunk_size": 1000, - "chunk_overlap": 200, - "separators": [ - "\n\n", - "\n", - "。", - "!", - "?", - ";", - ";" - ], - "enable_multimodal": true - }, - "image_processing_config": { - "model_id": "" - }, - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", - "vlm_config": { - "enabled": true, - "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" - }, - "cos_config": { - "secret_id": "", - "secret_key": "", - "region": "", - "bucket_name": "", - "app_id": "", - "path_prefix": "" - }, - "created_at": "2025-08-11T20:10:41.817794+08:00", - "updated_at": "2025-08-12T11:23:00.593097+08:00", - "deleted_at": null - } - ], - "success": true -} -``` - -#### GET `/knowledge-bases/:id` - 获取知识库详情 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' -``` - -**响应**: - -```json -{ - "data": { - "id": "kb-00000001", - "name": "Default Knowledge Base", - "description": "System Default Knowledge Base", - "tenant_id": 1, - "chunking_config": { - "chunk_size": 1000, - "chunk_overlap": 200, - "separators": [ - "\n\n", - "\n", - "。", - "!", - "?", - ";", - ";" - ], - "enable_multimodal": true - }, - "image_processing_config": { - "model_id": "" - }, - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", - "vlm_config": { - "enabled": true, - "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" - }, - "cos_config": { - "secret_id": "", - "secret_key": "", - "region": "", - "bucket_name": "", - "app_id": "", - "path_prefix": "" - }, - "created_at": "2025-08-11T20:10:41.817794+08:00", - "updated_at": "2025-08-12T11:23:00.593097+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### PUT `/knowledge-bases/:id` - 更新知识库 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/b5829e4a-3845-4624-a7fb-ea3b35e843b0' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---data '{ - "name": "weknora new", - "description": "weknora description new", - "config": { - "chunking_config": { - "chunk_size": 1000, - "chunk_overlap": 200, - "separators": [ - "\n\n", - "\n", - "。", - "!", - "?", - ";", - ";" - ], - "enable_multimodal": true - }, - "image_processing_config": { - "model_id": "" - } - } -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "b5829e4a-3845-4624-a7fb-ea3b35e843b0", - "name": "weknora new", - "description": "weknora description new", - "tenant_id": 1, - "chunking_config": { - "chunk_size": 1000, - "chunk_overlap": 200, - "separators": [ - "\n\n", - "\n", - "。", - "!", - "?", - ";", - ";" - ], - "enable_multimodal": true - }, - "image_processing_config": { - "model_id": "" - }, - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", - "vlm_config": { - "enabled": true, - "model_id": "f2083ad7-63e3-486d-a610-e6c56e58d72e" - }, - "cos_config": { - "secret_id": "", - "secret_key": "", - "region": "", - "bucket_name": "", - "app_id": "", - "path_prefix": "" - }, - "created_at": "2025-08-12T11:30:09.206238+08:00", - "updated_at": "2025-08-12T11:36:09.083577609+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### DELETE `/knowledge-bases/:id` - 删除知识库 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/b5829e4a-3845-4624-a7fb-ea3b35e843b0' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' -``` - -**响应**: - -```json -{ - "message": "Knowledge base deleted successfully", - "success": true -} -``` - -#### GET `/knowledge-bases/:id/hybrid-search` - 混合搜索 - -执行向量搜索和关键词搜索的混合检索。 - -**注意**:此接口使用 GET 方法但需要 JSON 请求体。 - -**请求参数**: -- `query_text`: 搜索查询文本(必填) -- `vector_threshold`: 向量相似度阈值(0-1,可选) -- `keyword_threshold`: 关键词匹配阈值(可选) -- `match_count`: 返回结果数量(可选) -- `disable_keywords_match`: 是否禁用关键词匹配(可选) -- `disable_vector_match`: 是否禁用向量匹配(可选) - -**请求**: - -```curl -curl --location --request GET 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/hybrid-search' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "query_text": "如何使用知识库", - "vector_threshold": 0.5, - "match_count": 10 -}' -``` - -**响应**: - -```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 -} -``` - -
返回顶部 ↑
- -### 知识管理API - -| 方法 | 路径 | 描述 | -| ------ | ------------------------------------- | ------------------------ | -| POST | `/knowledge-bases/:id/knowledge/file` | 从文件创建知识 | -| POST | `/knowledge-bases/:id/knowledge/url` | 从 URL 创建知识 | -| POST | `/knowledge-bases/:id/knowledge/manual` | 创建手工 Markdown 知识 | -| GET | `/knowledge-bases/:id/knowledge` | 获取知识库下的知识列表 | -| GET | `/knowledge/:id` | 获取知识详情 | -| DELETE | `/knowledge/:id` | 删除知识 | -| GET | `/knowledge/:id/download` | 下载知识文件 | -| PUT | `/knowledge/:id` | 更新知识 | -| PUT | `/knowledge/manual/:id` | 更新手工 Markdown 知识 | -| PUT | `/knowledge/image/:id/:chunk_id` | 更新图像分块信息 | -| PUT | `/knowledge/tags` | 批量更新知识标签 | -| GET | `/knowledge/batch` | 批量获取知识 | - -#### POST `/knowledge-bases/:id/knowledge/file` - 从文件创建知识 - -**表单参数**: -- `file`: 上传的文件(必填) -- `metadata`: JSON 格式的元数据(可选) -- `enable_multimodel`: 是否启用多模态处理(可选,true/false) -- `fileName`: 自定义文件名,用于文件夹上传时保留路径(可选) - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge/file' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---form 'file=@"/Users/xxxx/tests/彗星.txt"' \ ---form 'enable_multimodel="true"' -``` - -**响应**: - -```json -{ - "data": { - "id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "file", - "title": "彗星.txt", - "description": "", - "source": "", - "parse_status": "processing", - "enable_status": "disabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "彗星.txt", - "file_type": "txt", - "file_size": 7710, - "file_hash": "d69476ddbba45223a5e97e786539952c", - "file_path": "data/files/1/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/1754970756171067621.txt", - "storage_size": 0, - "metadata": null, - "created_at": "2025-08-12T11:52:36.168632288+08:00", - "updated_at": "2025-08-12T11:52:36.173612121+08:00", - "processed_at": null, - "error_message": "", - "deleted_at": null - }, - "success": true -} -``` - -#### POST `/knowledge-bases/:id/knowledge/url` - 从 URL 创建知识 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge/url' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "url":"https://github.com/Tencent/WeKnora", - "enable_multimodel":true -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "9c8af585-ae15-44ce-8f73-45ad18394651", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "url", - "title": "", - "description": "", - "source": "https://github.com/Tencent/WeKnora", - "parse_status": "processing", - "enable_status": "disabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "", - "file_type": "", - "file_size": 0, - "file_hash": "", - "file_path": "", - "storage_size": 0, - "metadata": null, - "created_at": "2025-08-12T11:55:05.709266776+08:00", - "updated_at": "2025-08-12T11:55:05.712918234+08:00", - "processed_at": null, - "error_message": "", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/knowledge-bases/:id/knowledge` - 获取知识库下的知识列表 - -**查询参数**: -- `page`: 页码(默认 1) -- `page_size`: 每页条数(默认 20) -- `tag_id`: 按标签ID筛选(可选) - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/knowledge?page_size=1&page=1&tag_id=tag-00000001' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "9c8af585-ae15-44ce-8f73-45ad18394651", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "url", - "title": "", - "description": "", - "source": "https://github.com/Tencent/WeKnora", - "parse_status": "pending", - "enable_status": "disabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "", - "file_type": "", - "file_size": 0, - "file_hash": "", - "file_path": "", - "storage_size": 0, - "metadata": null, - "created_at": "2025-08-12T11:55:05.709266+08:00", - "updated_at": "2025-08-12T11:55:05.709266+08:00", - "processed_at": null, - "error_message": "", - "deleted_at": null - } - ], - "page": 1, - "page_size": 1, - "success": true, - "total": 2 -} -``` - -注:parse_status 包含 `pending/processing/failed/completed` 四种状态 - -#### GET `/knowledge/:id` - 获取知识详情 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": { - "id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "file", - "title": "彗星.txt", - "description": "彗星是由冰和尘埃构成的太阳系小天体,接近太阳时会形成彗发和彗尾。其轨道周期差异大,来源包括柯伊伯带和奥尔特云。彗星与小行星的区别逐渐模糊,部分彗星已失去挥发物质,类似小行星。截至2019年,已知彗星超6600颗,数量庞大。彗星在古代被视为凶兆,现代研究揭示其复杂结构与起源。", - "source": "", - "parse_status": "completed", - "enable_status": "enabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "彗星.txt", - "file_type": "txt", - "file_size": 7710, - "file_hash": "d69476ddbba45223a5e97e786539952c", - "file_path": "data/files/1/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/1754970756171067621.txt", - "storage_size": 33689, - "metadata": null, - "created_at": "2025-08-12T11:52:36.168632+08:00", - "updated_at": "2025-08-12T11:52:53.376871+08:00", - "processed_at": "2025-08-12T11:52:53.376573+08:00", - "error_message": "", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/knowledge/batch` - 批量获取知识 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge/batch?ids=9c8af585-ae15-44ce-8f73-45ad18394651&ids=4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "9c8af585-ae15-44ce-8f73-45ad18394651", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "url", - "title": "", - "description": "", - "source": "https://github.com/Tencent/WeKnora", - "parse_status": "pending", - "enable_status": "disabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "", - "file_type": "", - "file_size": 0, - "file_hash": "", - "file_path": "", - "storage_size": 0, - "metadata": null, - "created_at": "2025-08-12T11:55:05.709266+08:00", - "updated_at": "2025-08-12T11:55:05.709266+08:00", - "processed_at": null, - "error_message": "", - "deleted_at": null - }, - { - "id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "type": "file", - "title": "彗星.txt", - "description": "彗星是由冰和尘埃构成的太阳系小天体,接近太阳时会形成彗发和彗尾。其轨道周期差异大,来源包括柯伊伯带和奥尔特云。彗星与小行星的区别逐渐模糊,部分彗星已失去挥发物质,类似小行星。截至2019年,已知彗星超6600颗,数量庞大。彗星在古代被视为凶兆,现代研究揭示其复杂结构与起源。", - "source": "", - "parse_status": "completed", - "enable_status": "enabled", - "embedding_model_id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "file_name": "彗星.txt", - "file_type": "txt", - "file_size": 7710, - "file_hash": "d69476ddbba45223a5e97e786539952c", - "file_path": "data/files/1/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/1754970756171067621.txt", - "storage_size": 33689, - "metadata": null, - "created_at": "2025-08-12T11:52:36.168632+08:00", - "updated_at": "2025-08-12T11:52:53.376871+08:00", - "processed_at": "2025-08-12T11:52:53.376573+08:00", - "error_message": "", - "deleted_at": null - } - ], - "success": true -} -``` - -#### DELETE `/knowledge/:id` - 删除知识 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge/9c8af585-ae15-44ce-8f73-45ad18394651' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "message": "Deleted successfully", - "success": true -} -``` - -#### GET `/knowledge/:id/download` - 下载知识文件 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/download' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -``` -attachment -``` - -
返回顶部 ↑
- -### 模型管理API - -| 方法 | 路径 | 描述 | -| ------ | --------------------- | --------------------- | -| POST | `/models` | 创建模型 | -| GET | `/models` | 获取模型列表 | -| GET | `/models/:id` | 获取模型详情 | -| PUT | `/models/:id` | 更新模型 | -| DELETE | `/models/:id` | 删除模型 | - -#### POST `/models` - 创建模型 - -创建对话模型(KnowledgeQA)请求体: - -```curl -curl --location 'http://localhost:8080/api/v1/models' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---data '{ - "name": "qwen3:8b", - "type": "KnowledgeQA", - "source": "local", - "description": "LLM Model for Knowledge QA", - "parameters": { - "base_url": "", - "api_key": "" - }, - "is_default": false -}' -``` - -创建嵌入模型(Embedding)请求体: - -```curl -curl --location 'http://localhost:8080/api/v1/models' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---data '{ - "name": "nomic-embed-text:latest", - "type": "Embedding", - "source": "local", - "description": "Embedding Model", - "parameters": { - "base_url": "", - "api_key": "", - "embedding_parameters": { - "dimension": 768, - "truncate_prompt_tokens": 0 - } - }, - "is_default": false -}' -``` - -创建排序模型(Rerank)请求体: - -```curl -curl --location 'http://localhost:8080/api/v1/models' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---data '{ - "name": "linux6200/bge-reranker-v2-m3:latest", - "type": "Rerank", - "source": "local", - "description": "Rerank Model for Knowledge QA", - "parameters": { - "base_url": "", - "api_key": "" - }, - "is_default": false -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "09c5a1d6-ee8b-4657-9a17-d3dcbd5c70cb", - "tenant_id": 1, - "name": "nomic-embed-text:latest3", - "type": "Embedding", - "source": "local", - "description": "Embedding Model", - "parameters": { - "base_url": "", - "api_key": "", - "embedding_parameters": { - "dimension": 768, - "truncate_prompt_tokens": 0 - } - }, - "is_default": false, - "status": "downloading", - "created_at": "2025-08-12T10:39:01.454591766+08:00", - "updated_at": "2025-08-12T10:39:01.454591766+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/models` - 获取模型列表 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/models' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "tenant_id": 1, - "name": "nomic-embed-text:latest", - "type": "Embedding", - "source": "local", - "description": "Embedding Model", - "parameters": { - "base_url": "", - "api_key": "", - "embedding_parameters": { - "dimension": 768, - "truncate_prompt_tokens": 0 - } - }, - "is_default": true, - "status": "active", - "created_at": "2025-08-11T20:10:41.813832+08:00", - "updated_at": "2025-08-11T20:10:41.822354+08:00", - "deleted_at": null - }, - { - "id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "tenant_id": 1, - "name": "qwen3:8b", - "type": "KnowledgeQA", - "source": "local", - "description": "LLM Model for Knowledge QA", - "parameters": { - "base_url": "", - "api_key": "", - "embedding_parameters": { - "dimension": 0, - "truncate_prompt_tokens": 0 - } - }, - "is_default": true, - "status": "active", - "created_at": "2025-08-11T20:10:41.811761+08:00", - "updated_at": "2025-08-11T20:10:41.825381+08:00", - "deleted_at": null - } - ], - "success": true -} -``` - -#### GET `/models/:id` - 获取模型详情 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/models/dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' -``` - -**响应**: - -```json -{ - "data": { - "id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3", - "tenant_id": 1, - "name": "nomic-embed-text:latest", - "type": "Embedding", - "source": "local", - "description": "Embedding Model", - "parameters": { - "base_url": "", - "api_key": "", - "embedding_parameters": { - "dimension": 768, - "truncate_prompt_tokens": 0 - } - }, - "is_default": true, - "status": "active", - "created_at": "2025-08-11T20:10:41.813832+08:00", - "updated_at": "2025-08-11T20:10:41.822354+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### PUT `/models/:id` - 更新模型 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/models/8fdc464d-8eaa-44d4-a85b-094b28af5330' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---data '{ - "name": "linux6200/bge-reranker-v2-m3:latest", - "description": "Rerank Model for Knowledge QA new", - "parameters": { - "base_url": "", - "api_key": "" - }, - "is_default": false -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "8fdc464d-8eaa-44d4-a85b-094b28af5330", - "tenant_id": 1, - "name": "linux6200/bge-reranker-v2-m3:latest", - "type": "Rerank", - "source": "local", - "description": "Rerank Model for Knowledge QA new", - "parameters": { - "base_url": "", - "api_key": "", - "embedding_parameters": { - "dimension": 0, - "truncate_prompt_tokens": 0 - } - }, - "is_default": false, - "status": "active", - "created_at": "2025-08-12T10:57:39.512681+08:00", - "updated_at": "2025-08-12T11:00:27.271678+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### DELETE `/models/:id` - 删除模型 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/models/8fdc464d-8eaa-44d4-a85b-094b28af5330' \ ---header 'Content-Type: application/json' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' -``` - -**响应**: - -```json -{ - "message": "Model deleted", - "success": true -} -``` - -
返回顶部 ↑
- -### 分块管理API - -| 方法 | 路径 | 描述 | -| ------ | --------------------------- | ------------------------ | -| GET | `/chunks/:knowledge_id` | 获取知识的分块列表 | -| DELETE | `/chunks/:knowledge_id/:id` | 删除分块 | -| DELETE | `/chunks/:knowledge_id` | 删除知识下的所有分块 | - -#### GET `/chunks/:knowledge_id?page=&page_size=` - 获取知识的分块列表 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5?page=1&page_size=1' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7", - "tenant_id": 1, - "knowledge_id": "4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5", - "knowledge_base_id": "kb-00000001", - "tag_id": "", - "content": "彗星xxxx", - "chunk_index": 0, - "is_enabled": true, - "status": 2, - "start_at": 0, - "end_at": 964, - "pre_chunk_id": "", - "next_chunk_id": "", - "chunk_type": "text", - "parent_chunk_id": "", - "relation_chunks": null, - "indirect_relation_chunks": null, - "metadata": null, - "content_hash": "", - "image_info": "", - "created_at": "2025-08-12T11:52:36.168632+08:00", - "updated_at": "2025-08-12T11:52:53.376871+08:00", - "deleted_at": null - } - ], - "page": 1, - "page_size": 1, - "success": true, - "total": 5 -} -``` - -#### DELETE `/chunks/:knowledge_id/:id` - 删除分块 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5/df10b37d-cd05-4b14-ba8a-e1bd0eb3bbd7' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "message": "Chunk deleted", - "success": true -} -``` - -#### DELETE `/chunks/:knowledge_id` - 删除知识下的所有分块 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/chunks/4c4e7c1a-09cf-485b-a7b5-24b8cdc5acf5' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "message": "All chunks under knowledge deleted", - "success": true -} -``` - -
返回顶部 ↑
- -### 标签管理API - -| 方法 | 路径 | 描述 | -| ------ | ------------------------------------- | ------------------------ | -| GET | `/knowledge-bases/:id/tags` | 获取知识库标签列表 | -| POST | `/knowledge-bases/:id/tags` | 创建标签 | -| PUT | `/knowledge-bases/:id/tags/:tag_id` | 更新标签 | -| DELETE | `/knowledge-bases/:id/tags/:tag_id` | 删除标签 | - -#### GET `/knowledge-bases/:id/tags` - 获取知识库标签列表 - -**查询参数**: -- `page`: 页码(默认 1) -- `page_size`: 每页条数(默认 20) -- `keyword`: 标签名称关键字搜索(可选) - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/tags?page=1&page_size=10' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": { - "total": 2, - "page": 1, - "page_size": 10, - "data": [ - { - "id": "tag-00000001", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "name": "技术文档", - "color": "#1890ff", - "sort_order": 1, - "created_at": "2025-08-12T10:00:00+08:00", - "updated_at": "2025-08-12T10:00:00+08:00", - "knowledge_count": 5, - "chunk_count": 120 - }, - { - "id": "tag-00000002", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "name": "常见问题", - "color": "#52c41a", - "sort_order": 2, - "created_at": "2025-08-12T10:00:00+08:00", - "updated_at": "2025-08-12T10:00:00+08:00", - "knowledge_count": 3, - "chunk_count": 45 - } - ] - }, - "success": true -} -``` - -#### POST `/knowledge-bases/:id/tags` - 创建标签 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/tags' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "name": "产品手册", - "color": "#faad14", - "sort_order": 3 -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "tag-00000003", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "name": "产品手册", - "color": "#faad14", - "sort_order": 3, - "created_at": "2025-08-12T11:00:00+08:00", - "updated_at": "2025-08-12T11:00:00+08:00" - }, - "success": true -} -``` - -#### PUT `/knowledge-bases/:id/tags/:tag_id` - 更新标签 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/tags/tag-00000003' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "name": "产品手册更新", - "color": "#ff4d4f" -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "tag-00000003", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "name": "产品手册更新", - "color": "#ff4d4f", - "sort_order": 3, - "created_at": "2025-08-12T11:00:00+08:00", - "updated_at": "2025-08-12T11:30:00+08:00" - }, - "success": true -} -``` - -#### DELETE `/knowledge-bases/:id/tags/:tag_id` - 删除标签 - -**查询参数**: -- `force`: 设置为 `true` 时强制删除(即使标签被引用) - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/tags/tag-00000003?force=true' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "success": true -} -``` - -
返回顶部 ↑
- -### FAQ管理API - -| 方法 | 路径 | 描述 | -| ------ | ------------------------------------------- | ------------------------ | -| GET | `/knowledge-bases/:id/faq/entries` | 获取FAQ条目列表 | -| POST | `/knowledge-bases/:id/faq/entries` | 批量导入FAQ条目 | -| POST | `/knowledge-bases/:id/faq/entry` | 创建单个FAQ条目 | -| PUT | `/knowledge-bases/:id/faq/entries/:entry_id`| 更新单个FAQ条目 | -| PUT | `/knowledge-bases/:id/faq/entries/status` | 批量更新FAQ启用状态 | -| PUT | `/knowledge-bases/:id/faq/entries/tags` | 批量更新FAQ标签 | -| DELETE | `/knowledge-bases/:id/faq/entries` | 批量删除FAQ条目 | -| POST | `/knowledge-bases/:id/faq/search` | 混合搜索FAQ | - -#### GET `/knowledge-bases/:id/faq/entries` - 获取FAQ条目列表 - -**查询参数**: -- `page`: 页码(默认 1) -- `page_size`: 每页条数(默认 20) -- `tag_id`: 按标签ID筛选(可选) -- `keyword`: 关键字搜索(可选) - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries?page=1&page_size=10' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": { - "total": 100, - "page": 1, - "page_size": 10, - "data": [ - { - "id": "faq-00000001", - "chunk_id": "chunk-00000001", - "knowledge_id": "knowledge-00000001", - "knowledge_base_id": "kb-00000001", - "tag_id": "tag-00000001", - "is_enabled": true, - "standard_question": "如何重置密码?", - "similar_questions": ["忘记密码怎么办", "密码找回"], - "negative_questions": ["如何修改用户名"], - "answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"], - "index_mode": "hybrid", - "chunk_type": "faq", - "created_at": "2025-08-12T10:00:00+08:00", - "updated_at": "2025-08-12T10:00:00+08:00" - } - ] - }, - "success": true -} -``` - -#### POST `/knowledge-bases/:id/faq/entries` - 批量导入FAQ条目 - -**请求参数**: -- `mode`: 导入模式,`append`(追加)或 `replace`(替换) -- `entries`: FAQ条目数组 -- `knowledge_id`: 关联的知识ID(可选) - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "mode": "append", - "entries": [ - { - "standard_question": "如何联系客服?", - "similar_questions": ["客服电话", "在线客服"], - "answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"], - "tag_id": "tag-00000001" - }, - { - "standard_question": "退款政策是什么?", - "answers": ["我们提供7天无理由退款服务。"] - } - ] -}' -``` - -**响应**: - -```json -{ - "data": { - "task_id": "task-00000001" - }, - "success": true -} -``` - -注:批量导入为异步操作,返回任务ID用于追踪进度。 - -#### POST `/knowledge-bases/:id/faq/entry` - 创建单个FAQ条目 - -同步创建单个FAQ条目,适用于单条录入场景。会自动检查标准问和相似问是否与已有FAQ重复。 - -**请求参数**: -- `standard_question`: 标准问(必填) -- `similar_questions`: 相似问数组(可选) -- `negative_questions`: 反例问题数组(可选) -- `answers`: 答案数组(必填) -- `tag_id`: 标签ID(可选) -- `is_enabled`: 是否启用(可选,默认true) - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entry' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "standard_question": "如何联系客服?", - "similar_questions": ["客服电话", "在线客服"], - "answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"], - "tag_id": "tag-00000001", - "is_enabled": true -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "faq-00000001", - "chunk_id": "chunk-00000001", - "knowledge_id": "knowledge-00000001", - "knowledge_base_id": "kb-00000001", - "tag_id": "tag-00000001", - "is_enabled": true, - "standard_question": "如何联系客服?", - "similar_questions": ["客服电话", "在线客服"], - "negative_questions": [], - "answers": ["您可以通过拨打400-xxx-xxxx联系我们的客服。"], - "index_mode": "hybrid", - "chunk_type": "faq", - "created_at": "2025-08-12T10:00:00+08:00", - "updated_at": "2025-08-12T10:00:00+08:00" - }, - "success": true -} -``` - -**错误响应**(标准问或相似问重复时): - -```json -{ - "success": false, - "error": { - "code": "BAD_REQUEST", - "message": "标准问与已有FAQ重复" - } -} -``` - -#### PUT `/knowledge-bases/:id/faq/entries/:entry_id` - 更新单个FAQ条目 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/faq-00000001' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "standard_question": "如何重置账户密码?", - "similar_questions": ["忘记密码怎么办", "密码找回", "重置密码"], - "answers": ["您可以通过以下步骤重置密码:1. 点击登录页面的"忘记密码" 2. 输入注册邮箱 3. 查收重置邮件"], - "is_enabled": true -}' -``` - -**响应**: - -```json -{ - "success": true -} -``` - -#### PUT `/knowledge-bases/:id/faq/entries/status` - 批量更新FAQ启用状态 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/status' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "updates": { - "faq-00000001": true, - "faq-00000002": false, - "faq-00000003": true - } -}' -``` - -**响应**: - -```json -{ - "success": true -} -``` - -#### PUT `/knowledge-bases/:id/faq/entries/tags` - 批量更新FAQ标签 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries/tags' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "updates": { - "faq-00000001": "tag-00000001", - "faq-00000002": "tag-00000002", - "faq-00000003": null - } -}' -``` - -注:设置为 `null` 可清除标签关联。 - -**响应**: - -```json -{ - "success": true -} -``` - -#### DELETE `/knowledge-bases/:id/faq/entries` - 批量删除FAQ条目 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/entries' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "ids": ["faq-00000001", "faq-00000002"] -}' -``` - -**响应**: - -```json -{ - "success": true -} -``` - -#### POST `/knowledge-bases/:id/faq/search` - 混合搜索FAQ - -**请求参数**: -- `query_text`: 搜索查询文本 -- `vector_threshold`: 向量相似度阈值(0-1) -- `match_count`: 返回结果数量(最大200) - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-bases/kb-00000001/faq/search' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "query_text": "如何重置密码", - "vector_threshold": 0.5, - "match_count": 10 -}' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "faq-00000001", - "chunk_id": "chunk-00000001", - "knowledge_id": "knowledge-00000001", - "knowledge_base_id": "kb-00000001", - "tag_id": "tag-00000001", - "is_enabled": true, - "standard_question": "如何重置密码?", - "similar_questions": ["忘记密码怎么办", "密码找回"], - "answers": ["您可以通过点击登录页面的'忘记密码'链接来重置密码。"], - "chunk_type": "faq", - "score": 0.95, - "match_type": "vector", - "created_at": "2025-08-12T10:00:00+08:00", - "updated_at": "2025-08-12T10:00:00+08:00" - } - ], - "success": true -} -``` - -
返回顶部 ↑
- -### 会话管理API - -| 方法 | 路径 | 描述 | -| ------ | --------------------------------------- | --------------------- | -| POST | `/sessions` | 创建会话 | -| GET | `/sessions/:id` | 获取会话详情 | -| GET | `/sessions` | 获取租户的会话列表 | -| PUT | `/sessions/:id` | 更新会话 | -| DELETE | `/sessions/:id` | 删除会话 | -| POST | `/sessions/:session_id/generate_title` | 生成会话标题 | -| GET | `/sessions/continue-stream/:session_id` | 继续未完成的会话 | - -#### POST `/sessions` - 创建会话 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/sessions' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "knowledge_base_id": "kb-00000001", - "session_strategy": { - "max_rounds": 5, - "enable_rewrite": true, - "fallback_strategy": "FIXED_RESPONSE", - "fallback_response": "对不起,我无法回答这个问题", - "embedding_top_k": 10, - "keyword_threshold": 0.5, - "vector_threshold": 0.7, - "rerank_model_id": "排序模型ID", - "rerank_top_k": 3, - "rerank_threshold": 0.7, - "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "summary_parameters": { - "max_tokens": 0, - "repeat_penalty": 1, - "top_k": 0, - "top_p": 0, - "frequency_penalty": 0, - "presence_penalty": 0, - "prompt": "这是用户和助手之间的对话。xxx", - "context_template": "你是一个专业的智能信息检索助手xxx", - "no_match_prefix": "\n\nNO_MATCH", - "temperature": 0.3, - "seed": 0, - "max_completion_tokens": 2048 - }, - "no_match_prefix": "\n\nNO_MATCH" - } -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "411d6b70-9a85-4d03-bb74-aab0fd8bd12f", - "title": "", - "description": "", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "max_rounds": 5, - "enable_rewrite": true, - "fallback_strategy": "FIXED_RESPONSE", - "fallback_response": "对不起,我无法回答这个问题", - "embedding_top_k": 10, - "keyword_threshold": 0.5, - "vector_threshold": 0.7, - "rerank_model_id": "排序模型ID", - "rerank_top_k": 3, - "rerank_threshold": 0.7, - "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "summary_parameters": { - "max_tokens": 0, - "repeat_penalty": 1, - "top_k": 0, - "top_p": 0, - "frequency_penalty": 0, - "presence_penalty": 0, - "prompt": "这是用户和助手之间的对话。xxx", - "context_template": "你是一个专业的智能信息检索助手xxx", - "no_match_prefix": "\n\nNO_MATCH", - "temperature": 0.3, - "seed": 0, - "max_completion_tokens": 2048 - }, - "agent_config": null, - "context_config": null, - "created_at": "2025-08-12T12:26:19.611616669+08:00", - "updated_at": "2025-08-12T12:26:19.611616919+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/sessions/:id` - 获取会话详情 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-fd584954304b' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": { - "id": "ceb9babb-1e30-41d7-817d-fd584954304b", - "title": "模型优化策略", - "description": "", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "max_rounds": 5, - "enable_rewrite": true, - "fallback_strategy": "fixed", - "fallback_response": "抱歉,我无法回答这个问题。", - "embedding_top_k": 10, - "keyword_threshold": 0.3, - "vector_threshold": 0.5, - "rerank_model_id": "", - "rerank_top_k": 5, - "rerank_threshold": 0.7, - "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "summary_parameters": { - "max_tokens": 0, - "repeat_penalty": 1, - "top_k": 0, - "top_p": 0, - "frequency_penalty": 0, - "presence_penalty": 0, - "prompt": "这是用户和助手之间的对话", - "context_template": "你是一个专业的智能信息检索助手", - "no_match_prefix": "\n\nNO_MATCH", - "temperature": 0.3, - "seed": 0, - "max_completion_tokens": 2048 - }, - "agent_config": null, - "context_config": null, - "created_at": "2025-08-12T10:24:38.308596+08:00", - "updated_at": "2025-08-12T10:25:41.317761+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### GET `/sessions?page=&page_size=` - 获取租户的会话列表 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/sessions?page=1&page_size=1' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "411d6b70-9a85-4d03-bb74-aab0fd8bd12f", - "title": "", - "description": "", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "max_rounds": 5, - "enable_rewrite": true, - "fallback_strategy": "FIXED_RESPONSE", - "fallback_response": "对不起,我无法回答这个问题", - "embedding_top_k": 10, - "keyword_threshold": 0.5, - "vector_threshold": 0.7, - "rerank_model_id": "排序模型ID", - "rerank_top_k": 3, - "rerank_threshold": 0.7, - "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "summary_parameters": { - "max_tokens": 0, - "repeat_penalty": 1, - "top_k": 0, - "top_p": 0, - "frequency_penalty": 0, - "presence_penalty": 0, - "prompt": "这是用户和助手之间的对话。xxx", - "context_template": "你是一个专业的智能信息检索助手xxx", - "no_match_prefix": "\n\nNO_MATCH", - "temperature": 0.3, - "seed": 0, - "max_completion_tokens": 2048 - }, - "created_at": "2025-08-12T12:26:19.611616+08:00", - "updated_at": "2025-08-12T12:26:19.611616+08:00", - "deleted_at": null - } - ], - "page": 1, - "page_size": 1, - "success": true, - "total": 2 -} -``` - -#### PUT `/sessions/:id` - 更新会话 - -**请求**: - -```curl -curl --location --request PUT 'http://localhost:8080/api/v1/sessions/411d6b70-9a85-4d03-bb74-aab0fd8bd12f' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "title": "weknora", - "description": "weknora description", - "knowledge_base_id": "kb-00000001", - "max_rounds": 5, - "enable_rewrite": true, - "fallback_strategy": "FIXED_RESPONSE", - "fallback_response": "对不起,我无法回答这个问题", - "embedding_top_k": 10, - "keyword_threshold": 0.5, - "vector_threshold": 0.7, - "rerank_model_id": "排序模型ID", - "rerank_top_k": 3, - "rerank_threshold": 0.7, - "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "summary_parameters": { - "max_tokens": 0, - "repeat_penalty": 1, - "top_k": 0, - "top_p": 0, - "frequency_penalty": 0, - "presence_penalty": 0, - "prompt": "这是用户和助手之间的对话。xxx", - "context_template": "你是一个专业的智能信息检索助手xxx", - "no_match_prefix": "\n\nNO_MATCH", - "temperature": 0.3, - "seed": 0, - "max_completion_tokens": 2048 - } -}' -``` - -**响应**: - -```json -{ - "data": { - "id": "411d6b70-9a85-4d03-bb74-aab0fd8bd12f", - "title": "weknora", - "description": "weknora description", - "tenant_id": 1, - "knowledge_base_id": "kb-00000001", - "max_rounds": 5, - "enable_rewrite": true, - "fallback_strategy": "FIXED_RESPONSE", - "fallback_response": "对不起,我无法回答这个问题", - "embedding_top_k": 10, - "keyword_threshold": 0.5, - "vector_threshold": 0.7, - "rerank_model_id": "排序模型ID", - "rerank_top_k": 3, - "rerank_threshold": 0.7, - "summary_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "summary_parameters": { - "max_tokens": 0, - "repeat_penalty": 1, - "top_k": 0, - "top_p": 0, - "frequency_penalty": 0, - "presence_penalty": 0, - "prompt": "这是用户和助手之间的对话。xxx", - "context_template": "你是一个专业的智能信息检索助手xxx", - "no_match_prefix": "\n\nNO_MATCH", - "temperature": 0.3, - "seed": 0, - "max_completion_tokens": 2048 - }, - "created_at": "0001-01-01T00:00:00Z", - "updated_at": "2025-08-12T14:20:56.738424351+08:00", - "deleted_at": null - }, - "success": true -} -``` - -#### DELETE `/sessions/:id` - 删除会话 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/sessions/411d6b70-9a85-4d03-bb74-aab0fd8bd12f' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "message": "Session deleted successfully", - "success": true -} -``` - -#### POST `/sessions/:session_id/generate_title` - 生成会话标题 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/sessions/ceb9babb-1e30-41d7-817d-fd584954304b/generate_title' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "messages": [ - { - "role": "user", - "content": "你好,我想了解关于人工智能的知识" - }, - { - "role": "assistant", - "content": "人工智能是计算机科学的一个分支..." - } - ] -}' -``` - -**响应**: - -```json -{ - "data": "模型优化策略", - "success": true -} -``` - -#### GET `/sessions/continue-stream/:session_id` - 继续未完成的会话 - -**查询参数**: -- `message_id`: 从 `/messages/:session_id/load` 接口中获取的 `is_completed` 为 `false` 的消息 ID - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/sessions/continue-stream/ceb9babb-1e30-41d7-817d-fd584954304b?message_id=b8b90eeb-7dd5-4cf9-81c6-5ebcbd759451' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应格式**: -服务器端事件流(Server-Sent Events),与 `/knowledge-chat/:session_id` 返回结果一致 - -
返回顶部 ↑
- -### 聊天功能API - -| 方法 | 路径 | 描述 | -| ---- | ----------------------------- | ------------------------ | -| POST | `/knowledge-chat/:session_id` | 基于知识库的问答 | -| POST | `/knowledge-search` | 基于知识库的搜索知识 | - -#### POST `/knowledge-chat/:session_id` - 基于知识库的问答 - -**请求**: - -```curl -curl --location 'http://localhost:8080/api/v1/knowledge-chat/ceb9babb-1e30-41d7-817d-fd584954304b' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "query": "彗尾的形状" -}' -``` - -**响应格式**: -服务器端事件流(Server-Sent Events,Content-Type: text/event-stream) - -**响应**: - -``` -event: message -data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"references","content":"","done":false,"knowledge_references":[{"id":"c8347bef-127f-4a22-b962-edf5a75386ec","content":"彗星xxx。","knowledge_id":"a6790b93-4700-4676-bd48-0d4804e1456b","chunk_index":0,"knowledge_title":"彗星.txt","start_at":0,"end_at":2760,"seq":0,"score":4.038836479187012,"match_type":3,"sub_chunk_id":["688821f0-40bf-428e-8cb6-541531ebeb76","c1e9903e-2b4d-4281-be15-0149288d45c2","7d955251-3f79-4fd5-a6aa-02f81e044091"],"metadata":{},"chunk_type":"text","parent_chunk_id":"","image_info":"","knowledge_filename":"彗星.txt","knowledge_source":""},{"id":"fa3aadee-cadb-4a84-9941-c839edc3e626","content":"# 文档名称\n彗星.txt\n\n# 摘要\n彗星是由冰和尘埃构成的太阳系小天体,接近太阳时会释放气体形成彗发和彗尾。其轨道周期差异大,来源包括柯伊伯带和奥尔特云。彗星与小行星的区别逐渐模糊,部分彗星已失去挥发物质,类似小行星。目前已知彗星数量众多,且存在系外彗星。彗星在古代被视为凶兆,现代研究揭示其复杂结构与起源。","knowledge_id":"a6790b93-4700-4676-bd48-0d4804e1456b","chunk_index":6,"knowledge_title":"彗星.txt","start_at":0,"end_at":0,"seq":6,"score":0.6131043121858466,"match_type":3,"sub_chunk_id":null,"metadata":{},"chunk_type":"summary","parent_chunk_id":"c8347bef-127f-4a22-b962-edf5a75386ec","image_info":"","knowledge_filename":"彗星.txt","knowledge_source":""}]} - -event: message -data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"表现为","done":false,"knowledge_references":null} - -event: message -data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"结构","done":false,"knowledge_references":null} - -event: message -data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"。","done":false,"knowledge_references":null} - -event: message -data: {"id":"3475c004-0ada-4306-9d30-d7f5efce50d2","response_type":"answer","content":"","done":true,"knowledge_references":null} -``` - -
返回顶部 ↑
- -### 消息管理API - -| 方法 | 路径 | 描述 | -| ------ | ---------------------------- | ------------------------ | -| GET | `/messages/:session_id/load` | 获取最近的会话消息列表 | -| DELETE | `/messages/:session_id/:id` | 删除消息 | - -#### GET `/messages/:session_id/load?before_time=2025-04-18T11:57:31.310671+08:00&limit=20` - 获取最近的会话消息列表 - -**查询参数**: - -- `before_time`: 上一次拉取的最早一条消息的 created_at 字段,为空拉取最近的消息 -- `limit`: 每页条数(默认 20) - -**请求**: - -```curl -curl --location --request GET 'http://localhost:8080/api/v1/messages/ceb9babb-1e30-41d7-817d-fd584954304b/load?limit=3&before_time=2030-08-12T14%3A35%3A42.123456789Z' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "query": "彗尾的形状" -}' -``` - -**响应**: - -```json -{ - "data": [ - { - "id": "b8b90eeb-7dd5-4cf9-81c6-5ebcbd759451", - "session_id": "ceb9babb-1e30-41d7-817d-fd584954304b", - "request_id": "hCA8SDjxcAvv", - "content": "\n好的", - "role": "assistant", - "knowledge_references": [ - { - "id": "c8347bef-127f-4a22-b962-edf5a75386ec", - "content": "彗星xxx", - "knowledge_id": "a6790b93-4700-4676-bd48-0d4804e1456b", - "chunk_index": 0, - "knowledge_title": "彗星.txt", - "start_at": 0, - "end_at": 2760, - "seq": 0, - "score": 4.038836479187012, - "match_type": 4, - "sub_chunk_id": [ - "688821f0-40bf-428e-8cb6-541531ebeb76", - "c1e9903e-2b4d-4281-be15-0149288d45c2", - "7d955251-3f79-4fd5-a6aa-02f81e044091" - ], - "metadata": {}, - "chunk_type": "text", - "parent_chunk_id": "", - "image_info": "", - "knowledge_filename": "彗星.txt", - "knowledge_source": "" - }, - { - "id": "fa3aadee-cadb-4a84-9941-c839edc3e626", - "content": "# 文档名称\n彗星.txt\n\n# 摘要\n彗星是由冰和尘埃构成的太阳系小天体,接近太阳时会释放气体形成彗发和彗尾。其轨道周期差异大,来源包括柯伊伯带和奥尔特云。彗星与小行星的区别逐渐模糊,部分彗星已失去挥发物质,类似小行星。目前已知彗星数量众多,且存在系外彗星。彗星在古代被视为凶兆,现代研究揭示其复杂结构与起源。", - "knowledge_id": "a6790b93-4700-4676-bd48-0d4804e1456b", - "chunk_index": 6, - "knowledge_title": "彗星.txt", - "start_at": 0, - "end_at": 0, - "seq": 6, - "score": 0.6131043121858466, - "match_type": 0, - "sub_chunk_id": null, - "metadata": {}, - "chunk_type": "summary", - "parent_chunk_id": "c8347bef-127f-4a22-b962-edf5a75386ec", - "image_info": "", - "knowledge_filename": "彗星.txt", - "knowledge_source": "" - } - ], - "agent_steps": [], - "is_completed": true, - "created_at": "2025-08-12T10:24:38.370548+08:00", - "updated_at": "2025-08-12T10:25:40.416382+08:00", - "deleted_at": null - }, - { - "id": "7fa136ae-a045-424e-baac-52113d92ae94", - "session_id": "ceb9babb-1e30-41d7-817d-fd584954304b", - "request_id": "3475c004-0ada-4306-9d30-d7f5efce50d2", - "content": "彗尾的形状", - "role": "user", - "knowledge_references": [], - "agent_steps": [], - "is_completed": true, - "created_at": "2025-08-12T14:30:39.732246+08:00", - "updated_at": "2025-08-12T14:30:39.733277+08:00", - "deleted_at": null - }, - { - "id": "9bcafbcf-a758-40af-a9a3-c4d8e0f49439", - "session_id": "ceb9babb-1e30-41d7-817d-fd584954304b", - "request_id": "3475c004-0ada-4306-9d30-d7f5efce50d2", - "content": "\n好的", - "role": "assistant", - "knowledge_references": [ - { - "id": "c8347bef-127f-4a22-b962-edf5a75386ec", - "content": "彗星xxx", - "knowledge_id": "a6790b93-4700-4676-bd48-0d4804e1456b", - "chunk_index": 0, - "knowledge_title": "彗星.txt", - "start_at": 0, - "end_at": 2760, - "seq": 0, - "score": 4.038836479187012, - "match_type": 3, - "sub_chunk_id": [ - "688821f0-40bf-428e-8cb6-541531ebeb76", - "c1e9903e-2b4d-4281-be15-0149288d45c2", - "7d955251-3f79-4fd5-a6aa-02f81e044091" - ], - "metadata": {}, - "chunk_type": "text", - "parent_chunk_id": "", - "image_info": "", - "knowledge_filename": "彗星.txt", - "knowledge_source": "" - }, - { - "id": "fa3aadee-cadb-4a84-9941-c839edc3e626", - "content": "# 文档名称\n彗星.txt\n\n# 摘要\n彗星是由冰和尘埃构成的太阳系小天体,接近太阳时会释放气体形成彗发和彗尾。其轨道周期差异大,来源包括柯伊伯带和奥尔特云。彗星与小行星的区别逐渐模糊,部分彗星已失去挥发物质,类似小行星。目前已知彗星数量众多,且存在系外彗星。彗星在古代被视为凶兆,现代研究揭示其复杂结构与起源。", - "knowledge_id": "a6790b93-4700-4676-bd48-0d4804e1456b", - "chunk_index": 6, - "knowledge_title": "彗星.txt", - "start_at": 0, - "end_at": 0, - "seq": 6, - "score": 0.6131043121858466, - "match_type": 3, - "sub_chunk_id": null, - "metadata": {}, - "chunk_type": "summary", - "parent_chunk_id": "c8347bef-127f-4a22-b962-edf5a75386ec", - "image_info": "", - "knowledge_filename": "彗星.txt", - "knowledge_source": "" - } - ], - "agent_steps": [], - "is_completed": true, - "created_at": "2025-08-12T14:30:39.735108+08:00", - "updated_at": "2025-08-12T14:31:17.829926+08:00", - "deleted_at": null - } - ], - "success": true -} -``` - -#### DELETE `/messages/:session_id/:id` - 删除消息 - -**请求**: - -```curl -curl --location --request DELETE 'http://localhost:8080/api/v1/messages/ceb9babb-1e30-41d7-817d-fd584954304b/9bcafbcf-a758-40af-a9a3-c4d8e0f49439' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "message": "Message deleted successfully", - "success": true -} -``` - -
返回顶部 ↑
- -### 评估功能API - -| 方法 | 路径 | 描述 | -| ---- | ------------- | --------------------- | -| GET | `/evaluation` | 获取评估任务 | -| POST | `/evaluation` | 创建评估任务 | - -#### GET `/evaluation` - 获取评估任务 - -**请求参数**: -- `task_id`: 从 `POST /evaluation` 接口中获取到的任务 ID -- `X-API-Key`: 用户 API Key - -**请求**: - -```bash -curl --location 'http://localhost:8080/api/v1/evaluation?task_id=c34563ad-b09f-4858-b72e-e92beb80becb' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' -``` - -**响应**: - -```json -{ - "data": { - "task": { - "id": "c34563ad-b09f-4858-b72e-e92beb80becb", - "tenant_id": 1, - "dataset_id": "default", - "start_time": "2025-08-12T14:54:26.221804768+08:00", - "status": 2, - "total": 1, - "finished": 1 - }, - "params": { - "session_id": "", - "knowledge_base_id": "2ef57434-8c8d-4442-b967-2f7fc578a2fc", - "vector_threshold": 0.5, - "keyword_threshold": 0.3, - "embedding_top_k": 10, - "vector_database": "", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", - "rerank_top_k": 5, - "rerank_threshold": 0.7, - "chat_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "summary_config": { - "max_tokens": 0, - "repeat_penalty": 1, - "top_k": 0, - "top_p": 0, - "frequency_penalty": 0, - "presence_penalty": 0, - "prompt": "这是用户和助手之间的对话。", - "context_template": "你是一个专业的智能信息检索助手", - "no_match_prefix": "\n\nNO_MATCH", - "temperature": 0.3, - "seed": 0, - "max_completion_tokens": 2048 - }, - "fallback_strategy": "", - "fallback_response": "抱歉,我无法回答这个问题。" - }, - "metric": { - "retrieval_metrics": { - "precision": 0, - "recall": 0, - "ndcg3": 0, - "ndcg10": 0, - "mrr": 0, - "map": 0 - }, - "generation_metrics": { - "bleu1": 0.037656734016532384, - "bleu2": 0.04067392145167686, - "bleu4": 0.048963321289052536, - "rouge1": 0, - "rouge2": 0, - "rougel": 0 - } - } - }, - "success": true -} -``` - -#### POST `/evaluation` - 创建评估任务 - -**请求参数**: -- `dataset_id`: 评估使用的数据集,暂时只支持官方测试数据集 `default` -- `knowledge_base_id`: 评估使用的知识库 -- `chat_id`: 评估使用的对话模型 -- `rerank_id`: 评估使用的重排序模型 - -**请求**: - -```bash -curl --location 'http://localhost:8080/api/v1/evaluation' \ ---header 'X-API-Key: sk-vQHV2NZI_LK5W7wHQvH3yGYExX8YnhaHwZipUYbiZKCYJbBQ' \ ---header 'Content-Type: application/json' \ ---data '{ - "dataset_id": "default", - "knowledge_base_id": "kb-00000001", - "chat_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "rerank_id": "b30171a1-787b-426e-a293-735cd5ac16c0" -}' -``` - -**响应**: - -```json -{ - "data": { - "task": { - "id": "c34563ad-b09f-4858-b72e-e92beb80becb", - "tenant_id": 1, - "dataset_id": "default", - "start_time": "2025-08-12T14:54:26.221804768+08:00", - "status": 1 - }, - "params": { - "session_id": "", - "knowledge_base_id": "2ef57434-8c8d-4442-b967-2f7fc578a2fc", - "vector_threshold": 0.5, - "keyword_threshold": 0.3, - "embedding_top_k": 10, - "vector_database": "", - "rerank_model_id": "b30171a1-787b-426e-a293-735cd5ac16c0", - "rerank_top_k": 5, - "rerank_threshold": 0.7, - "chat_model_id": "8aea788c-bb30-4898-809e-e40c14ffb48c", - "summary_config": { - "max_tokens": 0, - "repeat_penalty": 1, - "top_k": 0, - "top_p": 0, - "frequency_penalty": 0, - "presence_penalty": 0, - "prompt": "这是用户和助手之间的对话。", - "context_template": "你是一个专业的智能信息检索助手,xxx", - "no_match_prefix": "\n\nNO_MATCH", - "temperature": 0.3, - "seed": 0, - "max_completion_tokens": 2048 - }, - "fallback_strategy": "", - "fallback_response": "抱歉,我无法回答这个问题。" - } - }, - "success": true -} -``` - -
返回顶部 ↑
\ No newline at end of file diff --git a/docs/api/README.md b/docs/api/README.md index 7803030d..ee968ede 100644 --- 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) | diff --git a/docs/api/faq.md b/docs/api/faq.md index 993a06e0..7aa141c1 100644 --- 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' ``` **响应**: diff --git a/docs/api/knowledge-search.md b/docs/api/knowledge-search.md new file mode 100644 index 00000000..2ca7afc7 --- /dev/null +++ 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 +} +``` diff --git a/docs/docs.go b/docs/docs.go index 037808a1..819434e0 100644 --- 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", diff --git a/docs/swagger.json b/docs/swagger.json index 757c1348..6fd8f2b9 100644 --- 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" diff --git a/docs/swagger.yaml b/docs/swagger.yaml index 5025deb1..301cba7f 100644 --- 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: diff --git a/helm/.helmignore b/helm/.helmignore new file mode 100644 index 00000000..83b56a95 --- /dev/null +++ b/helm/.helmignore @@ -0,0 +1,29 @@ +# Patterns to ignore when building packages. +.git/ +.gitignore +.bzr/ +.bzrignore +.hg/ +.hgignore +.svn/ +*.swp +*.bak +*.tmp +*.orig +*~ +.project +.idea/ +*.tmproj +.vscode/ +.DS_Store +*.md +!README.md +docs/ +tests/ +*_test.yaml +.github/ +.gitlab-ci.yml +.travis.yml +Makefile +values-*.yaml +!values.yaml diff --git a/helm/Chart.yaml b/helm/Chart.yaml new file mode 100644 index 00000000..468b71fe --- /dev/null +++ b/helm/Chart.yaml @@ -0,0 +1,26 @@ +apiVersion: v2 +name: weknora +description: | + WeKnora - AI-powered Knowledge RAG Platform for building intelligent knowledge bases + with document parsing, vector search, and LLM integration. +type: application +version: 0.1.0 +appVersion: "v0.2.5" +kubeVersion: ">=1.25.0-0" +home: https://github.com/Tencent/WeKnora +icon: https://raw.githubusercontent.com/Tencent/WeKnora/main/docs/images/logo.png +sources: + - https://github.com/Tencent/WeKnora +keywords: + - ai + - rag + - knowledge-base + - llm + - document-parsing + - vector-search + - chatbot +maintainers: + - name: WeKnora Community + url: https://github.com/Tencent/WeKnora +annotations: + artifacthub.io/license: MIT diff --git a/helm/README.md b/helm/README.md new file mode 100644 index 00000000..260d74a3 --- /dev/null +++ b/helm/README.md @@ -0,0 +1,326 @@ +# WeKnora Helm Chart + +[![Artifact Hub](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/weknora)](https://artifacthub.io/packages/helm/weknora/weknora) +[![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) + +Helm chart for deploying [WeKnora](https://github.com/Tencent/WeKnora) - an AI-powered Knowledge RAG Platform. + +## Overview + +WeKnora is an intelligent knowledge base platform that combines: +- Document parsing and understanding +- Vector search with BM25 hybrid retrieval +- LLM integration for conversational AI +- Multi-tenant support with encryption + +## Prerequisites + +- Kubernetes 1.25+ +- Helm 3.10+ +- PV provisioner support in the underlying infrastructure +- Ingress controller (nginx-ingress recommended) for external access + +## Quick Start + +```bash +# Add required secrets +helm install weknora ./helm \ + --namespace weknora \ + --create-namespace \ + --set secrets.dbPassword= \ + --set secrets.redisPassword= \ + --set secrets.jwtSecret= +``` + +## Architecture + +``` + ┌─────────────┐ + │ Ingress │ + └──────┬──────┘ + │ + ┌───────────────┴───────────────┐ + │ │ + ▼ ▼ + ┌─────────────┐ ┌─────────────┐ + │ Frontend │ │ Backend │ + │ (Vue.js) │ │ (Go/Gin) │ + └─────────────┘ └──────┬──────┘ + │ + ┌──────────────────────┼──────────────────────┐ + │ │ │ + ▼ ▼ ▼ + ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ + │ Docreader │ │ PostgreSQL │ │ Redis │ + │ (gRPC) │ │ (ParadeDB) │ │ (Queue) │ + └─────────────┘ └─────────────┘ └─────────────┘ +``` + +## Installation + +### Basic Installation + +```bash +helm install weknora ./helm \ + --namespace weknora \ + --create-namespace \ + --set secrets.dbPassword=secure-password \ + --set secrets.redisPassword=secure-password \ + --set secrets.jwtSecret=$(openssl rand -base64 32) +``` + +### With Ingress + +```bash +helm install weknora ./helm \ + --namespace weknora \ + --create-namespace \ + --set ingress.enabled=true \ + --set ingress.host=weknora.example.com \ + --set ingress.tls.enabled=true \ + --set ingress.tls.secretName=weknora-tls \ + --set secrets.dbPassword=secure-password \ + --set secrets.redisPassword=secure-password \ + --set secrets.jwtSecret=$(openssl rand -base64 32) +``` + +### With External LLM (Ollama) + +```bash +helm install weknora ./helm \ + --namespace weknora \ + --create-namespace \ + --set app.extraEnv[0].name=OLLAMA_BASE_URL \ + --set app.extraEnv[0].value=http://ollama.ollama:11434 \ + --set app.extraEnv[1].name=INIT_LLM_MODEL_NAME \ + --set app.extraEnv[1].value=qwen2.5:7b \ + --set secrets.dbPassword=secure-password \ + --set secrets.redisPassword=secure-password \ + --set secrets.jwtSecret=$(openssl rand -base64 32) +``` + +### Production Installation + +For production, use a values file: + +```yaml +# values-production.yaml +global: + storageClass: "fast-ssd" + +app: + replicaCount: 3 + resources: + requests: + cpu: 500m + memory: 1Gi + limits: + cpu: 2 + memory: 4Gi + +postgresql: + persistence: + size: 100Gi + +ingress: + enabled: true + host: weknora.company.com + tls: + enabled: true + secretName: weknora-tls + +secrets: + existingSecret: weknora-secrets # Use pre-created secret +``` + +```bash +helm install weknora ./helm \ + --namespace weknora \ + --create-namespace \ + -f values-production.yaml +``` + +## Configuration + +### Global Parameters + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `global.storageClass` | Storage class for PVCs | `""` | +| `global.imagePullSecrets` | Image pull secrets | `[]` | +| `global.podSecurityContext` | Pod security context | See values.yaml | +| `global.containerSecurityContext` | Container security context | See values.yaml | + +### ServiceAccount + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `serviceAccount.create` | Create ServiceAccount | `true` | +| `serviceAccount.name` | ServiceAccount name | `""` | +| `serviceAccount.annotations` | ServiceAccount annotations | `{}` | + +### App (Backend) + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `app.enabled` | Enable backend | `true` | +| `app.replicaCount` | Number of replicas | `1` | +| `app.image.repository` | Image repository | `wechatopenai/weknora-app` | +| `app.image.tag` | Image tag | `""` (uses appVersion) | +| `app.resources` | Resource limits | See values.yaml | +| `app.env` | Environment variables | See values.yaml | +| `app.extraEnv` | Additional env vars | `[]` | + +### Frontend + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `frontend.enabled` | Enable frontend | `true` | +| `frontend.replicaCount` | Number of replicas | `1` | +| `frontend.image.repository` | Image repository | `wechatopenai/weknora-ui` | +| `frontend.image.tag` | Image tag | `latest` | + +### PostgreSQL (ParadeDB) + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `postgresql.enabled` | Enable PostgreSQL | `true` | +| `postgresql.image.repository` | Image repository | `paradedb/paradedb` | +| `postgresql.image.tag` | Image tag | `v0.18.9-pg17` | +| `postgresql.persistence.enabled` | Enable persistence | `true` | +| `postgresql.persistence.size` | PVC size | `10Gi` | + +### Redis + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `redis.enabled` | Enable Redis | `true` | +| `redis.image.repository` | Image repository | `redis` | +| `redis.image.tag` | Image tag | `7-alpine` | +| `redis.persistence.enabled` | Enable persistence | `true` | +| `redis.persistence.size` | PVC size | `1Gi` | + +### Ingress + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `ingress.enabled` | Enable ingress | `false` | +| `ingress.className` | Ingress class | `nginx` | +| `ingress.host` | Hostname | `weknora.example.com` | +| `ingress.tls.enabled` | Enable TLS | `false` | +| `ingress.tls.secretName` | TLS secret name | `""` | + +### Secrets + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `secrets.dbUser` | Database username | `postgres` | +| `secrets.dbPassword` | Database password | `""` (required) | +| `secrets.dbName` | Database name | `weknora` | +| `secrets.redisPassword` | Redis password | `""` (required) | +| `secrets.jwtSecret` | JWT signing secret | `""` (required) | +| `secrets.existingSecret` | Use existing secret | `""` | + +### Optional Components + +These map to docker-compose profiles: + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `minio.enabled` | Enable MinIO storage | `false` | +| `neo4j.enabled` | Enable Neo4j (GraphRAG) | `false` | +| `qdrant.enabled` | Enable Qdrant vector DB | `false` | +| `jaeger.enabled` | Enable Jaeger tracing | `false` | + +## Security Best Practices + +### Secret Management + +**Never commit secrets to Git!** Use one of these approaches: + +1. **Helm --set flags** (for testing) + ```bash + helm install weknora ./helm --set secrets.dbPassword=xxx + ``` + +2. **External Secrets Operator** (recommended for production) + ```yaml + secrets: + existingSecret: weknora-external-secret + ``` + +3. **Sealed Secrets** (for GitOps) + ```bash + kubeseal < secret.yaml > sealed-secret.yaml + ``` + +### Pod Security + +The chart follows CNCF security best practices: +- Runs as non-root user +- Read-only root filesystem where possible +- Drops all capabilities +- Uses seccomp profiles + +## Upgrading + +```bash +helm upgrade weknora ./helm \ + --namespace weknora \ + --reuse-values +``` + +## Uninstalling + +```bash +helm uninstall weknora --namespace weknora + +# Optional: Remove PVCs +kubectl delete pvc -n weknora -l app.kubernetes.io/instance=weknora +``` + +## Troubleshooting + +### Check Pod Status +```bash +kubectl get pods -n weknora +``` + +### View Logs +```bash +# Backend logs +kubectl logs -n weknora -l app.kubernetes.io/component=app -f + +# Frontend logs +kubectl logs -n weknora -l app.kubernetes.io/component=frontend -f +``` + +### Common Issues + +**Pod stuck in Pending** +- Check if PVCs are bound: `kubectl get pvc -n weknora` +- Verify storage class exists: `kubectl get sc` + +**Connection refused errors** +- Wait for all pods to be Ready +- Check service endpoints: `kubectl get endpoints -n weknora` + +**Database connection errors** +- Verify secrets are correct +- Check PostgreSQL logs: `kubectl logs -n weknora -l app.kubernetes.io/component=database` + +## Contributing + +See [CONTRIBUTING.md](https://github.com/Tencent/WeKnora/blob/main/CONTRIBUTING.md) in the main repository. + +## References + +This Helm chart follows best practices from: +- [Helm Best Practices](https://helm.sh/docs/chart_best_practices/) +- [ArgoCD Helm Chart](https://github.com/argoproj/argo-helm) +- [Prometheus Helm Charts](https://github.com/prometheus-community/helm-charts) +- [cert-manager Helm Chart](https://github.com/cert-manager/cert-manager) + +## License + +This chart is licensed under the MIT License - see the [LICENSE](https://github.com/Tencent/WeKnora/blob/main/LICENSE) file for details. diff --git a/helm/templates/NOTES.txt b/helm/templates/NOTES.txt new file mode 100644 index 00000000..e88e2f6f --- /dev/null +++ b/helm/templates/NOTES.txt @@ -0,0 +1,121 @@ +{{/* +Copyright 2025 Tencent +SPDX-License-Identifier: MIT + +Post-installation notes for WeKnora Helm chart. +Ref: https://github.com/argoproj/argo-helm/blob/main/charts/argo-cd/templates/NOTES.txt +*/}} + +================================================================================ + WeKnora has been installed successfully! +================================================================================ + +Release: {{ .Release.Name }} +Namespace: {{ .Release.Namespace }} +Version: {{ .Chart.AppVersion }} + +-------------------------------------------------------------------------------- + ACCESSING WEKNORA +-------------------------------------------------------------------------------- + +{{- if .Values.ingress.enabled }} +WeKnora is accessible via Ingress: + + URL: {{ if .Values.ingress.tls.enabled }}https{{ else }}http{{ end }}://{{ .Values.ingress.host }} + +{{- else }} + +To access WeKnora, use port-forwarding: + + # Frontend (Web UI) + kubectl port-forward svc/frontend -n {{ .Release.Namespace }} 8080:80 + + # Then open: http://localhost:8080 + +{{- end }} + +{{- if not .Values.ingress.enabled }} + +To expose WeKnora externally, enable Ingress: + + helm upgrade {{ .Release.Name }} ./helm \ + --set ingress.enabled=true \ + --set ingress.host=weknora.example.com + +{{- end }} + +-------------------------------------------------------------------------------- + CONFIGURATION +-------------------------------------------------------------------------------- + +Components deployed: +{{- if .Values.app.enabled }} + - Backend API ({{ include "weknora.app.image" . }}) +{{- end }} +{{- if .Values.frontend.enabled }} + - Frontend UI ({{ include "weknora.frontend.image" . }}) +{{- end }} +{{- if .Values.docreader.enabled }} + - Document Reader ({{ include "weknora.docreader.image" . }}) +{{- end }} +{{- if .Values.postgresql.enabled }} + - PostgreSQL/ParadeDB ({{ include "weknora.postgresql.image" . }}) +{{- end }} +{{- if .Values.redis.enabled }} + - Redis ({{ include "weknora.redis.image" . }}) +{{- end }} + +{{- if or .Values.minio.enabled .Values.neo4j.enabled .Values.qdrant.enabled .Values.jaeger.enabled }} + +Optional components enabled: +{{- if .Values.minio.enabled }} + - MinIO (S3-compatible storage) +{{- end }} +{{- if .Values.neo4j.enabled }} + - Neo4j (Knowledge Graph) +{{- end }} +{{- if .Values.qdrant.enabled }} + - Qdrant (Vector Database) +{{- end }} +{{- if .Values.jaeger.enabled }} + - Jaeger (Distributed Tracing) +{{- end }} +{{- end }} + +-------------------------------------------------------------------------------- + CONNECTING TO LLM +-------------------------------------------------------------------------------- + +WeKnora requires an LLM backend. Configure via environment variables: + + helm upgrade {{ .Release.Name }} ./helm \ + --set app.extraEnv[0].name=OLLAMA_BASE_URL \ + --set app.extraEnv[0].value=http://ollama:11434 \ + --set app.extraEnv[1].name=INIT_LLM_MODEL_NAME \ + --set app.extraEnv[1].value=qwen2.5:7b + +Supported LLM backends: + - Ollama (local) + - OpenAI API compatible endpoints + - Qwen, DeepSeek, and other Chinese LLMs + +-------------------------------------------------------------------------------- + DOCUMENTATION +-------------------------------------------------------------------------------- + + GitHub: https://github.com/Tencent/WeKnora + API Docs: https://github.com/Tencent/WeKnora/blob/main/docs/API.md + FAQ: https://github.com/Tencent/WeKnora/blob/main/docs/QA.md + +-------------------------------------------------------------------------------- + TROUBLESHOOTING +-------------------------------------------------------------------------------- + +Check pod status: + kubectl get pods -n {{ .Release.Namespace }} -l app.kubernetes.io/instance={{ .Release.Name }} + +View logs: + kubectl logs -n {{ .Release.Namespace }} -l app.kubernetes.io/component=app -f + kubectl logs -n {{ .Release.Namespace }} -l app.kubernetes.io/component=frontend -f + +================================================================================ diff --git a/helm/templates/_helpers.tpl b/helm/templates/_helpers.tpl new file mode 100644 index 00000000..939a7883 --- /dev/null +++ b/helm/templates/_helpers.tpl @@ -0,0 +1,188 @@ +{{/* +Copyright 2025 Tencent +SPDX-License-Identifier: MIT + +WeKnora Helm Chart Template Helpers + +Best Practices References: +- https://helm.sh/docs/chart_best_practices/templates/ +- https://github.com/argoproj/argo-helm/blob/main/charts/argo-cd/templates/_helpers.tpl +*/}} + +{{/* +Expand the name of the chart. +*/}} +{{- define "weknora.name" -}} +{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }} +{{- end }} + +{{/* +Create a default fully qualified app name. +*/}} +{{- define "weknora.fullname" -}} +{{- if .Values.fullnameOverride }} +{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }} +{{- else }} +{{- $name := default .Chart.Name .Values.nameOverride }} +{{- if contains $name .Release.Name }} +{{- .Release.Name | trunc 63 | trimSuffix "-" }} +{{- else }} +{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }} +{{- end }} +{{- end }} +{{- end }} + +{{/* +Create chart name and version as used by the chart label. +Ref: https://helm.sh/docs/chart_best_practices/labels/ +*/}} +{{- define "weknora.chart" -}} +{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }} +{{- end }} + +{{/* +Common labels following Kubernetes recommended labels. +Ref: https://kubernetes.io/docs/concepts/overview/working-with-objects/common-labels/ +*/}} +{{- define "weknora.labels" -}} +helm.sh/chart: {{ include "weknora.chart" . }} +{{ include "weknora.selectorLabels" . }} +{{- if .Chart.AppVersion }} +app.kubernetes.io/version: {{ .Chart.AppVersion | quote }} +{{- end }} +app.kubernetes.io/managed-by: {{ .Release.Service }} +app.kubernetes.io/part-of: weknora +{{- end }} + +{{/* +Selector labels +*/}} +{{- define "weknora.selectorLabels" -}} +app.kubernetes.io/name: {{ include "weknora.name" . }} +app.kubernetes.io/instance: {{ .Release.Name }} +{{- end }} + +{{/* +Component labels - use for individual components +Usage: {{ include "weknora.componentLabels" (dict "component" "app" "context" .) }} +*/}} +{{- define "weknora.componentLabels" -}} +{{ include "weknora.labels" .context }} +app.kubernetes.io/component: {{ .component }} +{{- end }} + +{{/* +Component selector labels +Usage: {{ include "weknora.componentSelectorLabels" (dict "component" "app" "context" .) }} +*/}} +{{- define "weknora.componentSelectorLabels" -}} +{{ include "weknora.selectorLabels" .context }} +app.kubernetes.io/component: {{ .component }} +{{- end }} + +{{/* +Create the name of the service account to use. +Ref: https://helm.sh/docs/chart_best_practices/rbac/ +*/}} +{{- define "weknora.serviceAccountName" -}} +{{- if .Values.serviceAccount.create }} +{{- default (include "weknora.fullname" .) .Values.serviceAccount.name }} +{{- else }} +{{- default "default" .Values.serviceAccount.name }} +{{- end }} +{{- end }} + +{{/* +Secret name - supports existing secret +*/}} +{{- define "weknora.secretName" -}} +{{- if .Values.secrets.existingSecret }} +{{- .Values.secrets.existingSecret }} +{{- else }} +{{- include "weknora.fullname" . }}-secrets +{{- end }} +{{- end }} + +{{/* +Return the app image with tag. +Defaults to Chart.appVersion if tag is not specified. +*/}} +{{- define "weknora.app.image" -}} +{{- $tag := default .Chart.AppVersion .Values.app.image.tag }} +{{- printf "%s:%s" .Values.app.image.repository $tag }} +{{- end }} + +{{/* +Return the frontend image with tag. +*/}} +{{- define "weknora.frontend.image" -}} +{{- printf "%s:%s" .Values.frontend.image.repository .Values.frontend.image.tag }} +{{- end }} + +{{/* +Return the docreader image with tag. +*/}} +{{- define "weknora.docreader.image" -}} +{{- printf "%s:%s" .Values.docreader.image.repository .Values.docreader.image.tag }} +{{- end }} + +{{/* +Return the PostgreSQL image with tag. +*/}} +{{- define "weknora.postgresql.image" -}} +{{- printf "%s:%s" .Values.postgresql.image.repository .Values.postgresql.image.tag }} +{{- end }} + +{{/* +Return the Redis image with tag. +*/}} +{{- define "weknora.redis.image" -}} +{{- printf "%s:%s" .Values.redis.image.repository .Values.redis.image.tag }} +{{- end }} + +{{/* +Create image pull secrets list. +*/}} +{{- define "weknora.imagePullSecrets" -}} +{{- with .Values.global.imagePullSecrets }} +imagePullSecrets: +{{- toYaml . | nindent 2 }} +{{- end }} +{{- end }} + +{{/* +Return the storage class name. +*/}} +{{- define "weknora.storageClass" -}} +{{- if .Values.global.storageClass }} +{{- if eq .Values.global.storageClass "-" }} +storageClassName: "" +{{- else }} +storageClassName: {{ .Values.global.storageClass | quote }} +{{- end }} +{{- end }} +{{- end }} + +{{/* +Pod security context. +Merges global defaults with component-specific overrides. +*/}} +{{- define "weknora.podSecurityContext" -}} +{{- $global := .Values.global.podSecurityContext | default dict }} +{{- $component := .componentSecurityContext | default dict }} +{{- $merged := merge $component $global }} +{{- if $merged }} +securityContext: +{{- toYaml $merged | nindent 2 }} +{{- end }} +{{- end }} + +{{/* +Container security context. +*/}} +{{- define "weknora.containerSecurityContext" -}} +{{- if . }} +securityContext: +{{- toYaml . | nindent 2 }} +{{- end }} +{{- end }} diff --git a/helm/templates/app.yaml b/helm/templates/app.yaml new file mode 100644 index 00000000..0c39a4d3 --- /dev/null +++ b/helm/templates/app.yaml @@ -0,0 +1,173 @@ +{{/* +Copyright 2025 Tencent +SPDX-License-Identifier: MIT + +WeKnora Backend API Server Deployment and Service. +*/}} +{{- if .Values.app.enabled }} +apiVersion: apps/v1 +kind: Deployment +metadata: + name: {{ include "weknora.fullname" . }}-app + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "app" "context" .) | nindent 4 }} +spec: + replicas: {{ .Values.app.replicaCount }} + selector: + matchLabels: + {{- include "weknora.componentSelectorLabels" (dict "component" "app" "context" .) | nindent 6 }} + strategy: + type: RollingUpdate + rollingUpdate: + maxSurge: 1 + maxUnavailable: 0 + template: + metadata: + labels: + {{- include "weknora.componentSelectorLabels" (dict "component" "app" "context" .) | nindent 8 }} + spec: + {{- include "weknora.imagePullSecrets" . | nindent 6 }} + serviceAccountName: {{ include "weknora.serviceAccountName" . }} + {{- with .Values.app.podSecurityContext | default .Values.global.podSecurityContext }} + securityContext: + {{- toYaml . | nindent 8 }} + {{- end }} + containers: + - name: app + image: {{ include "weknora.app.image" . }} + imagePullPolicy: {{ .Values.app.image.pullPolicy }} + {{- with .Values.app.securityContext }} + securityContext: + {{- toYaml . | nindent 12 }} + {{- end }} + ports: + - containerPort: 8080 + name: http + protocol: TCP + env: + # Application settings + - name: GIN_MODE + value: {{ .Values.app.env.GIN_MODE | quote }} + - name: TZ + value: {{ .Values.app.env.TZ | quote }} + # Database configuration + - name: DB_DRIVER + value: "postgres" + - name: DB_HOST + value: "postgres" + - name: DB_PORT + value: "5432" + - name: DB_USER + valueFrom: + secretKeyRef: + name: {{ include "weknora.secretName" . }} + key: DB_USER + - name: DB_PASSWORD + valueFrom: + secretKeyRef: + name: {{ include "weknora.secretName" . }} + key: DB_PASSWORD + - name: DB_NAME + valueFrom: + secretKeyRef: + name: {{ include "weknora.secretName" . }} + key: DB_NAME + # Redis configuration + - name: REDIS_ADDR + value: "redis:6379" + - name: REDIS_PASSWORD + valueFrom: + secretKeyRef: + name: {{ include "weknora.secretName" . }} + key: REDIS_PASSWORD + - name: REDIS_DB + value: "0" + - name: REDIS_PREFIX + value: "stream:" + - name: STREAM_MANAGER_TYPE + value: {{ .Values.app.env.STREAM_MANAGER_TYPE | quote }} + # Security + - name: JWT_SECRET + valueFrom: + secretKeyRef: + name: {{ include "weknora.secretName" . }} + key: JWT_SECRET + - name: TENANT_AES_KEY + valueFrom: + secretKeyRef: + name: {{ include "weknora.secretName" . }} + key: TENANT_AES_KEY + # Retrieval & Storage + - name: RETRIEVE_DRIVER + value: {{ .Values.app.env.RETRIEVE_DRIVER | quote }} + - name: STORAGE_TYPE + value: {{ .Values.app.env.STORAGE_TYPE | quote }} + - name: LOCAL_STORAGE_BASE_DIR + value: {{ .Values.app.env.LOCAL_STORAGE_BASE_DIR | quote }} + # Document reader + - name: DOCREADER_ADDR + value: "docreader:50051" + # Processing + - name: AUTO_RECOVER_DIRTY + value: {{ .Values.app.env.AUTO_RECOVER_DIRTY | quote }} + - name: CONCURRENCY_POOL_SIZE + value: {{ .Values.app.env.CONCURRENCY_POOL_SIZE | quote }} + - name: ENABLE_GRAPH_RAG + value: {{ .Values.app.env.ENABLE_GRAPH_RAG | quote }} + {{- with .Values.app.extraEnv }} + # Additional environment variables + {{- toYaml . | nindent 12 }} + {{- end }} + volumeMounts: + - name: data-files + mountPath: /data/files + resources: + {{- toYaml .Values.app.resources | nindent 12 }} + {{- with .Values.app.livenessProbe }} + livenessProbe: + {{- toYaml . | nindent 12 }} + {{- end }} + {{- with .Values.app.readinessProbe }} + readinessProbe: + {{- toYaml . | nindent 12 }} + {{- end }} + volumes: + - name: data-files + {{- if .Values.dataFiles.persistence.enabled }} + persistentVolumeClaim: + claimName: {{ .Values.dataFiles.persistence.existingClaim | default (printf "%s-data-files" (include "weknora.fullname" .)) }} + {{- else }} + emptyDir: {} + {{- end }} + {{- with .Values.app.nodeSelector }} + nodeSelector: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.app.affinity }} + affinity: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.app.tolerations }} + tolerations: + {{- toYaml . | nindent 8 }} + {{- end }} +--- +apiVersion: v1 +kind: Service +metadata: + # Service name must be "app" - frontend nginx config hardcodes this + name: app + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "app" "context" .) | nindent 4 }} +spec: + type: {{ .Values.app.service.type }} + selector: + {{- include "weknora.componentSelectorLabels" (dict "component" "app" "context" .) | nindent 4 }} + ports: + - name: http + port: {{ .Values.app.service.port }} + targetPort: http + protocol: TCP +{{- end }} diff --git a/helm/templates/docreader.yaml b/helm/templates/docreader.yaml new file mode 100644 index 00000000..c95ebe7b --- /dev/null +++ b/helm/templates/docreader.yaml @@ -0,0 +1,102 @@ +{{/* +Copyright 2025 Tencent +SPDX-License-Identifier: MIT + +WeKnora Document Reader (gRPC) Deployment and Service. +*/}} +{{- if .Values.docreader.enabled }} +apiVersion: apps/v1 +kind: Deployment +metadata: + name: {{ include "weknora.fullname" . }}-docreader + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "docreader" "context" .) | nindent 4 }} +spec: + replicas: {{ .Values.docreader.replicaCount }} + selector: + matchLabels: + {{- include "weknora.componentSelectorLabels" (dict "component" "docreader" "context" .) | nindent 6 }} + strategy: + type: RollingUpdate + rollingUpdate: + maxSurge: 1 + maxUnavailable: 0 + template: + metadata: + labels: + {{- include "weknora.componentSelectorLabels" (dict "component" "docreader" "context" .) | nindent 8 }} + spec: + {{- include "weknora.imagePullSecrets" . | nindent 6 }} + serviceAccountName: {{ include "weknora.serviceAccountName" . }} + {{- with .Values.global.podSecurityContext }} + securityContext: + {{- toYaml . | nindent 8 }} + {{- end }} + containers: + - name: docreader + image: {{ include "weknora.docreader.image" . }} + imagePullPolicy: {{ .Values.docreader.image.pullPolicy }} + {{- with .Values.docreader.securityContext }} + securityContext: + {{- toYaml . | nindent 12 }} + {{- end }} + ports: + - containerPort: 50051 + name: grpc + protocol: TCP + env: + - name: STORAGE_TYPE + value: {{ .Values.docreader.env.STORAGE_TYPE | quote }} + resources: + {{- toYaml .Values.docreader.resources | nindent 12 }} + # gRPC health check using grpc_health_probe + livenessProbe: + exec: + command: + - grpc_health_probe + - -addr=:50051 + initialDelaySeconds: 30 + periodSeconds: 10 + timeoutSeconds: 5 + failureThreshold: 3 + readinessProbe: + exec: + command: + - grpc_health_probe + - -addr=:50051 + initialDelaySeconds: 10 + periodSeconds: 5 + timeoutSeconds: 3 + failureThreshold: 3 + {{- with .Values.docreader.nodeSelector }} + nodeSelector: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.docreader.affinity }} + affinity: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.docreader.tolerations }} + tolerations: + {{- toYaml . | nindent 8 }} + {{- end }} +--- +apiVersion: v1 +kind: Service +metadata: + # Service name must be "docreader" - app references this + name: docreader + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "docreader" "context" .) | nindent 4 }} +spec: + type: {{ .Values.docreader.service.type }} + selector: + {{- include "weknora.componentSelectorLabels" (dict "component" "docreader" "context" .) | nindent 4 }} + ports: + - name: grpc + port: {{ .Values.docreader.service.port }} + targetPort: grpc + protocol: TCP +{{- end }} diff --git a/helm/templates/frontend.yaml b/helm/templates/frontend.yaml new file mode 100644 index 00000000..96754a91 --- /dev/null +++ b/helm/templates/frontend.yaml @@ -0,0 +1,107 @@ +{{/* +Copyright 2025 Tencent +SPDX-License-Identifier: MIT + +WeKnora Frontend Web UI Deployment and Service. +*/}} +{{- if .Values.frontend.enabled }} +apiVersion: apps/v1 +kind: Deployment +metadata: + name: {{ include "weknora.fullname" . }}-frontend + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "frontend" "context" .) | nindent 4 }} +spec: + replicas: {{ .Values.frontend.replicaCount }} + selector: + matchLabels: + {{- include "weknora.componentSelectorLabels" (dict "component" "frontend" "context" .) | nindent 6 }} + strategy: + type: RollingUpdate + rollingUpdate: + maxSurge: 1 + maxUnavailable: 0 + template: + metadata: + labels: + {{- include "weknora.componentSelectorLabels" (dict "component" "frontend" "context" .) | nindent 8 }} + spec: + {{- include "weknora.imagePullSecrets" . | nindent 6 }} + serviceAccountName: {{ include "weknora.serviceAccountName" . }} + {{- with .Values.global.podSecurityContext }} + securityContext: + {{- toYaml . | nindent 8 }} + {{- end }} + containers: + - name: frontend + image: {{ include "weknora.frontend.image" . }} + imagePullPolicy: {{ .Values.frontend.image.pullPolicy }} + {{- with .Values.frontend.securityContext }} + securityContext: + {{- toYaml . | nindent 12 }} + {{- end }} + ports: + - containerPort: 80 + name: http + protocol: TCP + resources: + {{- toYaml .Values.frontend.resources | nindent 12 }} + livenessProbe: + httpGet: + path: / + port: http + initialDelaySeconds: 10 + periodSeconds: 10 + timeoutSeconds: 5 + failureThreshold: 3 + readinessProbe: + httpGet: + path: / + port: http + initialDelaySeconds: 5 + periodSeconds: 5 + timeoutSeconds: 3 + failureThreshold: 3 + # nginx requires writable directories for temp files + volumeMounts: + - name: nginx-cache + mountPath: /var/cache/nginx + - name: nginx-run + mountPath: /var/run + volumes: + - name: nginx-cache + emptyDir: {} + - name: nginx-run + emptyDir: {} + {{- with .Values.frontend.nodeSelector }} + nodeSelector: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.frontend.affinity }} + affinity: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.frontend.tolerations }} + tolerations: + {{- toYaml . | nindent 8 }} + {{- end }} +--- +apiVersion: v1 +kind: Service +metadata: + # Service name must be "frontend" - ingress references this + name: frontend + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "frontend" "context" .) | nindent 4 }} +spec: + type: {{ .Values.frontend.service.type }} + selector: + {{- include "weknora.componentSelectorLabels" (dict "component" "frontend" "context" .) | nindent 4 }} + ports: + - name: http + port: {{ .Values.frontend.service.port }} + targetPort: http + protocol: TCP +{{- end }} diff --git a/helm/templates/ingress.yaml b/helm/templates/ingress.yaml new file mode 100644 index 00000000..7b491a3e --- /dev/null +++ b/helm/templates/ingress.yaml @@ -0,0 +1,52 @@ +{{/* +Copyright 2025 Tencent +SPDX-License-Identifier: MIT + +Ingress resource for WeKnora. +Routes /api to backend, / to frontend. +*/}} +{{- if .Values.ingress.enabled }} +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: {{ include "weknora.fullname" . }} + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "ingress" "context" .) | nindent 4 }} + {{- with .Values.ingress.annotations }} + annotations: + {{- toYaml . | nindent 4 }} + {{- end }} +spec: + {{- if .Values.ingress.className }} + ingressClassName: {{ .Values.ingress.className }} + {{- end }} + {{- if .Values.ingress.tls.enabled }} + tls: + - hosts: + - {{ .Values.ingress.host | quote }} + {{- if .Values.ingress.tls.secretName }} + secretName: {{ .Values.ingress.tls.secretName }} + {{- end }} + {{- end }} + rules: + - host: {{ .Values.ingress.host | quote }} + http: + paths: + # API routes - must come first (more specific path) + - path: /api + pathType: Prefix + backend: + service: + name: app + port: + name: http + # Frontend routes - catch-all + - path: / + pathType: Prefix + backend: + service: + name: frontend + port: + name: http +{{- end }} diff --git a/helm/templates/postgres.yaml b/helm/templates/postgres.yaml new file mode 100644 index 00000000..fbc3674f --- /dev/null +++ b/helm/templates/postgres.yaml @@ -0,0 +1,128 @@ +{{/* +Copyright 2025 Tencent +SPDX-License-Identifier: MIT + +PostgreSQL (ParadeDB) Deployment and Service. +ParadeDB provides vector search and BM25 full-text search capabilities. +*/}} +{{- if .Values.postgresql.enabled }} +apiVersion: apps/v1 +kind: Deployment +metadata: + name: {{ include "weknora.fullname" . }}-postgres + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "database" "context" .) | nindent 4 }} +spec: + replicas: 1 + selector: + matchLabels: + {{- include "weknora.componentSelectorLabels" (dict "component" "database" "context" .) | nindent 6 }} + # Use Recreate strategy for database to avoid data corruption + strategy: + type: Recreate + template: + metadata: + labels: + {{- include "weknora.componentSelectorLabels" (dict "component" "database" "context" .) | nindent 8 }} + spec: + {{- include "weknora.imagePullSecrets" . | nindent 6 }} + serviceAccountName: {{ include "weknora.serviceAccountName" . }} + {{- with .Values.global.podSecurityContext }} + securityContext: + {{- toYaml . | nindent 8 }} + {{- end }} + containers: + - name: postgres + image: {{ include "weknora.postgresql.image" . }} + imagePullPolicy: IfNotPresent + {{- with .Values.postgresql.securityContext }} + securityContext: + {{- toYaml . | nindent 12 }} + {{- end }} + ports: + - containerPort: 5432 + name: postgresql + protocol: TCP + env: + - name: POSTGRES_USER + valueFrom: + secretKeyRef: + name: {{ include "weknora.secretName" . }} + key: DB_USER + - name: POSTGRES_PASSWORD + valueFrom: + secretKeyRef: + name: {{ include "weknora.secretName" . }} + key: DB_PASSWORD + - name: POSTGRES_DB + valueFrom: + secretKeyRef: + name: {{ include "weknora.secretName" . }} + key: DB_NAME + - name: PGDATA + value: /var/lib/postgresql/data/pgdata + volumeMounts: + - name: postgres-data + mountPath: /var/lib/postgresql/data + resources: + {{- toYaml .Values.postgresql.resources | nindent 12 }} + livenessProbe: + exec: + command: + - pg_isready + - -U + - postgres + initialDelaySeconds: 30 + periodSeconds: 10 + timeoutSeconds: 5 + failureThreshold: 6 + readinessProbe: + exec: + command: + - pg_isready + - -U + - postgres + initialDelaySeconds: 5 + periodSeconds: 5 + timeoutSeconds: 3 + failureThreshold: 3 + volumes: + - name: postgres-data + {{- if .Values.postgresql.persistence.enabled }} + persistentVolumeClaim: + claimName: {{ .Values.postgresql.persistence.existingClaim | default (printf "%s-postgres" (include "weknora.fullname" .)) }} + {{- else }} + emptyDir: {} + {{- end }} + {{- with .Values.postgresql.nodeSelector }} + nodeSelector: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.postgresql.affinity }} + affinity: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.postgresql.tolerations }} + tolerations: + {{- toYaml . | nindent 8 }} + {{- end }} +--- +apiVersion: v1 +kind: Service +metadata: + # Service name must be "postgres" - app references this + name: postgres + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "database" "context" .) | nindent 4 }} +spec: + type: ClusterIP + selector: + {{- include "weknora.componentSelectorLabels" (dict "component" "database" "context" .) | nindent 4 }} + ports: + - name: postgresql + port: 5432 + targetPort: postgresql + protocol: TCP +{{- end }} diff --git a/helm/templates/pvc.yaml b/helm/templates/pvc.yaml new file mode 100644 index 00000000..99e73669 --- /dev/null +++ b/helm/templates/pvc.yaml @@ -0,0 +1,62 @@ +{{/* +Copyright 2025 Tencent +SPDX-License-Identifier: MIT + +Persistent Volume Claims for stateful components. +*/}} + +{{/* PostgreSQL PVC */}} +{{- if and .Values.postgresql.enabled .Values.postgresql.persistence.enabled (not .Values.postgresql.persistence.existingClaim) }} +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: {{ include "weknora.fullname" . }}-postgres + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "database" "context" .) | nindent 4 }} +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: {{ .Values.postgresql.persistence.size }} + {{- include "weknora.storageClass" . | nindent 2 }} +--- +{{- end }} + +{{/* Redis PVC */}} +{{- if and .Values.redis.enabled .Values.redis.persistence.enabled (not .Values.redis.persistence.existingClaim) }} +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: {{ include "weknora.fullname" . }}-redis + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "cache" "context" .) | nindent 4 }} +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: {{ .Values.redis.persistence.size }} + {{- include "weknora.storageClass" . | nindent 2 }} +--- +{{- end }} + +{{/* Data Files PVC */}} +{{- if and .Values.dataFiles.persistence.enabled (not .Values.dataFiles.persistence.existingClaim) }} +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: {{ include "weknora.fullname" . }}-data-files + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "storage" "context" .) | nindent 4 }} +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: {{ .Values.dataFiles.persistence.size }} + {{- include "weknora.storageClass" . | nindent 2 }} +{{- end }} diff --git a/helm/templates/redis.yaml b/helm/templates/redis.yaml new file mode 100644 index 00000000..e64f243e --- /dev/null +++ b/helm/templates/redis.yaml @@ -0,0 +1,124 @@ +{{/* +Copyright 2025 Tencent +SPDX-License-Identifier: MIT + +Redis Deployment and Service. +Redis is used for stream management and async task queuing. +*/}} +{{- if .Values.redis.enabled }} +apiVersion: apps/v1 +kind: Deployment +metadata: + name: {{ include "weknora.fullname" . }}-redis + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "cache" "context" .) | nindent 4 }} +spec: + replicas: 1 + selector: + matchLabels: + {{- include "weknora.componentSelectorLabels" (dict "component" "cache" "context" .) | nindent 6 }} + # Use Recreate strategy to avoid data corruption + strategy: + type: Recreate + template: + metadata: + labels: + {{- include "weknora.componentSelectorLabels" (dict "component" "cache" "context" .) | nindent 8 }} + spec: + {{- include "weknora.imagePullSecrets" . | nindent 6 }} + serviceAccountName: {{ include "weknora.serviceAccountName" . }} + {{- with .Values.global.podSecurityContext }} + securityContext: + {{- toYaml . | nindent 8 }} + {{- end }} + containers: + - name: redis + image: {{ include "weknora.redis.image" . }} + imagePullPolicy: IfNotPresent + {{- with .Values.redis.securityContext }} + securityContext: + {{- toYaml . | nindent 12 }} + {{- end }} + command: + - redis-server + - --requirepass + - $(REDIS_PASSWORD) + - --appendonly + - "yes" + - --dir + - /data + env: + - name: REDIS_PASSWORD + valueFrom: + secretKeyRef: + name: {{ include "weknora.secretName" . }} + key: REDIS_PASSWORD + ports: + - containerPort: 6379 + name: redis + protocol: TCP + volumeMounts: + - name: redis-data + mountPath: /data + resources: + {{- toYaml .Values.redis.resources | nindent 12 }} + livenessProbe: + exec: + command: + - sh + - -c + - redis-cli -a $REDIS_PASSWORD ping | grep PONG + initialDelaySeconds: 10 + periodSeconds: 10 + timeoutSeconds: 5 + failureThreshold: 3 + readinessProbe: + exec: + command: + - sh + - -c + - redis-cli -a $REDIS_PASSWORD ping | grep PONG + initialDelaySeconds: 5 + periodSeconds: 5 + timeoutSeconds: 3 + failureThreshold: 3 + volumes: + - name: redis-data + {{- if .Values.redis.persistence.enabled }} + persistentVolumeClaim: + claimName: {{ .Values.redis.persistence.existingClaim | default (printf "%s-redis" (include "weknora.fullname" .)) }} + {{- else }} + emptyDir: {} + {{- end }} + {{- with .Values.redis.nodeSelector }} + nodeSelector: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.redis.affinity }} + affinity: + {{- toYaml . | nindent 8 }} + {{- end }} + {{- with .Values.redis.tolerations }} + tolerations: + {{- toYaml . | nindent 8 }} + {{- end }} +--- +apiVersion: v1 +kind: Service +metadata: + # Service name must be "redis" - app references this + name: redis + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.componentLabels" (dict "component" "cache" "context" .) | nindent 4 }} +spec: + type: ClusterIP + selector: + {{- include "weknora.componentSelectorLabels" (dict "component" "cache" "context" .) | nindent 4 }} + ports: + - name: redis + port: 6379 + targetPort: redis + protocol: TCP +{{- end }} diff --git a/helm/templates/secrets.yaml b/helm/templates/secrets.yaml new file mode 100644 index 00000000..a7b89a11 --- /dev/null +++ b/helm/templates/secrets.yaml @@ -0,0 +1,32 @@ +{{/* +Copyright 2025 Tencent +SPDX-License-Identifier: MIT + +Secrets for WeKnora components. + +IMPORTANT: For production deployments, use one of these approaches: +1. Set values via --set flags during installation +2. Use External Secrets Operator with cloud secret managers +3. Use sealed-secrets for GitOps workflows +4. Provide an existing secret via secrets.existingSecret +*/}} +{{- if not .Values.secrets.existingSecret }} +apiVersion: v1 +kind: Secret +metadata: + name: {{ include "weknora.secretName" . }} + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.labels" . | nindent 4 }} +type: Opaque +stringData: + # Database credentials + DB_USER: {{ .Values.secrets.dbUser | quote }} + DB_PASSWORD: {{ required "secrets.dbPassword is required" .Values.secrets.dbPassword | quote }} + DB_NAME: {{ .Values.secrets.dbName | quote }} + # Redis credentials + REDIS_PASSWORD: {{ required "secrets.redisPassword is required" .Values.secrets.redisPassword | quote }} + # Application secrets + JWT_SECRET: {{ required "secrets.jwtSecret is required" .Values.secrets.jwtSecret | quote }} + TENANT_AES_KEY: {{ .Values.secrets.tenantAesKey | default (randAlphaNum 32) | quote }} +{{- end }} diff --git a/helm/templates/serviceaccount.yaml b/helm/templates/serviceaccount.yaml new file mode 100644 index 00000000..8ee9a454 --- /dev/null +++ b/helm/templates/serviceaccount.yaml @@ -0,0 +1,24 @@ +{{/* +Copyright 2025 Tencent +SPDX-License-Identifier: MIT + +ServiceAccount for WeKnora components. +Ref: https://helm.sh/docs/chart_best_practices/rbac/ +*/}} +{{- if .Values.serviceAccount.create }} +apiVersion: v1 +kind: ServiceAccount +metadata: + name: {{ include "weknora.serviceAccountName" . }} + namespace: {{ .Release.Namespace }} + labels: + {{- include "weknora.labels" . | nindent 4 }} + {{- with .Values.serviceAccount.labels }} + {{- toYaml . | nindent 4 }} + {{- end }} + {{- with .Values.serviceAccount.annotations }} + annotations: + {{- toYaml . | nindent 4 }} + {{- end }} +automountServiceAccountToken: {{ .Values.serviceAccount.automountServiceAccountToken }} +{{- end }} diff --git a/helm/values.yaml b/helm/values.yaml new file mode 100644 index 00000000..237a9c73 --- /dev/null +++ b/helm/values.yaml @@ -0,0 +1,453 @@ +# Copyright 2025 Tencent +# SPDX-License-Identifier: MIT +# +# WeKnora Helm Chart Values +# +# Best Practices References: +# - https://helm.sh/docs/chart_best_practices/values/ +# - https://github.com/argoproj/argo-helm/blob/main/charts/argo-cd/values.yaml +# - https://github.com/cert-manager/cert-manager/blob/master/deploy/charts/cert-manager/values.yaml + +# -- Global configuration shared across all components +# @default -- See values.yaml +global: + # -- Storage class for all PersistentVolumeClaims + # Set to "-" to use cluster default, or specify a storage class name + storageClass: "" + + # -- Image pull secrets for private registries + # @default -- [] + imagePullSecrets: [] + # - name: regcred + + # -- Default security context for all pods + # Note: Official images (nginx, postgres, redis) run as root by default + # Enable runAsNonRoot only if using non-root compatible images + # Ref: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/ + podSecurityContext: + seccompProfile: + type: RuntimeDefault + + # -- Default security context for all containers + # Note: readOnlyRootFilesystem disabled as images require writable filesystem + containerSecurityContext: + allowPrivilegeEscalation: false + +# -- ServiceAccount configuration +# Ref: https://helm.sh/docs/chart_best_practices/rbac/ +serviceAccount: + # -- Create a ServiceAccount + create: true + # -- ServiceAccount name (auto-generated if empty) + name: "" + # -- Annotations to add to the ServiceAccount + annotations: {} + # -- Labels to add to the ServiceAccount + labels: {} + # -- Automount API credentials for the ServiceAccount + automountServiceAccountToken: false + +# ----------------------------------------------------------------------------- +# App (Backend API Server) +# ----------------------------------------------------------------------------- +app: + # -- Enable the app component + enabled: true + + # -- Number of replicas + replicaCount: 1 + + image: + # -- Image repository + repository: wechatopenai/weknora-app + # -- Image tag (defaults to Chart.appVersion if empty) + tag: "" + # -- Image pull policy + pullPolicy: IfNotPresent + + # -- Resource requests and limits + # Ref: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/ + resources: + requests: + cpu: 100m + memory: 256Mi + limits: + cpu: "1" + memory: 1Gi + + # -- Pod security context override + podSecurityContext: {} + + # -- Container security context override + # Note: App requires write access for file storage + securityContext: + # runAsNonRoot: true # Disabled - official images run as root + allowPrivilegeEscalation: false + + # -- Environment variables for the app container + # Ref: https://github.com/Tencent/WeKnora/blob/main/docker-compose.yml + env: + GIN_MODE: release + # -- Retrieval driver: postgres, elasticsearch_v7, elasticsearch_v8, qdrant + RETRIEVE_DRIVER: postgres + # -- Storage type: local, minio, cos + STORAGE_TYPE: local + LOCAL_STORAGE_BASE_DIR: /data/files + AUTO_RECOVER_DIRTY: "true" + STREAM_MANAGER_TYPE: redis + CONCURRENCY_POOL_SIZE: "5" + ENABLE_GRAPH_RAG: "false" + TZ: UTC + + # -- Additional environment variables + extraEnv: [] + # - name: OLLAMA_BASE_URL + # value: "http://ollama:11434" + + # -- Service configuration + service: + type: ClusterIP + port: 8080 + + # -- Liveness probe configuration + livenessProbe: + httpGet: + path: /health + port: http + initialDelaySeconds: 30 + periodSeconds: 10 + timeoutSeconds: 5 + failureThreshold: 3 + + # -- Readiness probe configuration + readinessProbe: + httpGet: + path: /health + port: http + initialDelaySeconds: 10 + periodSeconds: 5 + timeoutSeconds: 3 + failureThreshold: 3 + + # -- Node selector + nodeSelector: {} + + # -- Tolerations + tolerations: [] + + # -- Affinity rules + affinity: {} + +# ----------------------------------------------------------------------------- +# Frontend (Web UI) +# ----------------------------------------------------------------------------- +frontend: + # -- Enable the frontend component + enabled: true + + # -- Number of replicas + replicaCount: 1 + + image: + # -- Image repository + repository: wechatopenai/weknora-ui + # -- Image tag + tag: latest + # -- Image pull policy + pullPolicy: IfNotPresent + + # -- Resource requests and limits + resources: + requests: + cpu: 50m + memory: 64Mi + limits: + cpu: 200m + memory: 256Mi + + # -- Container security context + securityContext: + # runAsNonRoot: true # Disabled - official images run as root + # readOnlyRootFilesystem: true # Disabled - images require writable fs + allowPrivilegeEscalation: false + + # -- Service configuration + service: + type: ClusterIP + port: 80 + + # -- Node selector + nodeSelector: {} + + # -- Tolerations + tolerations: [] + + # -- Affinity rules + affinity: {} + +# ----------------------------------------------------------------------------- +# Docreader (Document Parser - gRPC) +# ----------------------------------------------------------------------------- +docreader: + # -- Enable the docreader component + enabled: true + + # -- Number of replicas + replicaCount: 1 + + image: + # -- Image repository + repository: wechatopenai/weknora-docreader + # -- Image tag + tag: latest + # -- Image pull policy + pullPolicy: IfNotPresent + + # -- Resource requests and limits + resources: + requests: + cpu: 100m + memory: 256Mi + limits: + cpu: 500m + memory: 512Mi + + # -- Container security context + securityContext: + # runAsNonRoot: true # Disabled - official images run as root + allowPrivilegeEscalation: false + + # -- Environment variables + env: + STORAGE_TYPE: local + + # -- Service configuration + service: + type: ClusterIP + port: 50051 + + # -- Node selector + nodeSelector: {} + + # -- Tolerations + tolerations: [] + + # -- Affinity rules + affinity: {} + +# ----------------------------------------------------------------------------- +# PostgreSQL (ParadeDB - Vector + BM25 Search) +# ----------------------------------------------------------------------------- +postgresql: + # -- Enable PostgreSQL + enabled: true + + image: + # -- Image repository (ParadeDB for vector search) + repository: paradedb/paradedb + # -- Image tag + tag: v0.18.9-pg17 + + # -- Resource requests and limits + resources: + requests: + cpu: 100m + memory: 256Mi + limits: + cpu: 500m + memory: 512Mi + + # -- Container security context + # Note: PostgreSQL requires specific user permissions + securityContext: + # runAsNonRoot: true # Disabled - official images run as root + allowPrivilegeEscalation: false + + # -- Persistence configuration + persistence: + # -- Enable persistence + enabled: true + # -- Size of the PVC + size: 10Gi + # -- Use existing PVC (leave empty to create new) + existingClaim: "" + + # -- Node selector + nodeSelector: {} + + # -- Tolerations + tolerations: [] + + # -- Affinity rules + affinity: {} + +# ----------------------------------------------------------------------------- +# Redis (Stream & Task Queue) +# ----------------------------------------------------------------------------- +redis: + # -- Enable Redis + enabled: true + + image: + # -- Image repository + repository: redis + # -- Image tag + tag: 7-alpine + + # -- Resource requests and limits + resources: + requests: + cpu: 50m + memory: 64Mi + limits: + cpu: 200m + memory: 256Mi + + # -- Container security context + securityContext: + # runAsNonRoot: true # Disabled - official images run as root + # readOnlyRootFilesystem: true # Disabled - images require writable fs + allowPrivilegeEscalation: false + + # -- Persistence configuration + persistence: + # -- Enable persistence + enabled: true + # -- Size of the PVC + size: 1Gi + # -- Use existing PVC (leave empty to create new) + existingClaim: "" + + # -- Node selector + nodeSelector: {} + + # -- Tolerations + tolerations: [] + + # -- Affinity rules + affinity: {} + +# ----------------------------------------------------------------------------- +# Data Files Storage +# ----------------------------------------------------------------------------- +dataFiles: + persistence: + # -- Enable persistence for uploaded files + enabled: true + # -- Size of the PVC + size: 10Gi + # -- Use existing PVC (leave empty to create new) + existingClaim: "" + +# ----------------------------------------------------------------------------- +# Ingress Configuration +# ----------------------------------------------------------------------------- +ingress: + # -- Enable ingress + enabled: false + + # -- Ingress class name + className: nginx + + # -- Ingress hostname + host: weknora.example.com + + # -- TLS configuration + tls: + # -- Enable TLS + enabled: false + # -- TLS secret name + secretName: "" + + # -- Additional annotations + # Ref: https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/ + annotations: + nginx.ingress.kubernetes.io/proxy-body-size: "100m" + nginx.ingress.kubernetes.io/proxy-connect-timeout: "60" + nginx.ingress.kubernetes.io/proxy-read-timeout: "3600" + nginx.ingress.kubernetes.io/proxy-send-timeout: "3600" + +# ----------------------------------------------------------------------------- +# Secrets Configuration +# ----------------------------------------------------------------------------- +# IMPORTANT: Do NOT use default values in production! +# Use --set or external secret management (External Secrets Operator, Vault, etc.) +# +# Example installation: +# helm install weknora ./helm \ +# --set secrets.dbPassword= \ +# --set secrets.redisPassword= \ +# --set secrets.jwtSecret= +# +secrets: + # -- Database username + dbUser: postgres + # -- Database password (REQUIRED: change in production) + dbPassword: "" + # -- Database name + dbName: weknora + # -- Redis password (REQUIRED: change in production) + redisPassword: "" + # -- JWT signing secret (REQUIRED: change in production) + jwtSecret: "" + # -- Tenant AES encryption key + tenantAesKey: "" + + # -- Use existing secret instead of creating one + # The secret must contain keys: DB_USER, DB_PASSWORD, DB_NAME, REDIS_PASSWORD, JWT_SECRET, TENANT_AES_KEY + existingSecret: "" + +# ----------------------------------------------------------------------------- +# Optional Components (Profiles from docker-compose) +# ----------------------------------------------------------------------------- + +# -- MinIO configuration (S3-compatible storage) +# Equivalent to: docker compose --profile minio +minio: + # -- Enable MinIO + enabled: false + image: + repository: minio/minio + tag: latest + # -- Root user + rootUser: minioadmin + # -- Root password (REQUIRED if enabled) + rootPassword: "" + persistence: + enabled: true + size: 20Gi + +# -- Neo4j configuration (Knowledge Graph) +# Equivalent to: docker compose --profile neo4j +neo4j: + # -- Enable Neo4j for GraphRAG + enabled: false + image: + repository: neo4j + tag: 5-community + # -- Authentication password (REQUIRED if enabled) + password: "" + persistence: + enabled: true + size: 10Gi + +# -- Qdrant configuration (Vector Database) +# Equivalent to: docker compose --profile qdrant +qdrant: + # -- Enable Qdrant as alternative vector store + enabled: false + image: + repository: qdrant/qdrant + tag: latest + persistence: + enabled: true + size: 10Gi + +# -- Jaeger configuration (Distributed Tracing) +# Equivalent to: docker compose --profile jaeger +jaeger: + # -- Enable Jaeger tracing + enabled: false + image: + repository: jaegertracing/all-in-one + tag: latest diff --git a/internal/agent/tools/get_document_info.go b/internal/agent/tools/get_document_info.go index ff5c0360..c5c7b9b2 100644 --- a/internal/agent/tools/get_document_info.go +++ b/internal/agent/tools/get_document_info.go @@ -139,7 +139,7 @@ func (t *GetDocumentInfoTool) Execute(ctx context.Context, args map[string]inter ListPagedChunksByKnowledgeID(ctx, t.tenantID, id, &types.Pagination{ Page: 1, PageSize: 1000, - }, []types.ChunkType{"text"}, "", "") + }, []types.ChunkType{"text"}, "", "", "", "") if err != nil { mu.Lock() results[id] = &docInfo{ diff --git a/internal/agent/tools/knowledge_search.go b/internal/agent/tools/knowledge_search.go index 79482b90..5ef49053 100644 --- a/internal/agent/tools/knowledge_search.go +++ b/internal/agent/tools/knowledge_search.go @@ -1052,7 +1052,7 @@ func (t *KnowledgeSearchTool) formatOutput( _, total, err := t.chunkService.GetRepository().ListPagedChunksByKnowledgeID(ctx, t.tenantID, result.KnowledgeID, &types.Pagination{Page: 1, PageSize: 1}, - []types.ChunkType{types.ChunkTypeText}, "", "", + []types.ChunkType{types.ChunkTypeText}, "", "", "", "", ) if err != nil { logger.Warnf( diff --git a/internal/agent/tools/list_knowledge_chunks.go b/internal/agent/tools/list_knowledge_chunks.go index 839d957b..0747ee90 100644 --- a/internal/agent/tools/list_knowledge_chunks.go +++ b/internal/agent/tools/list_knowledge_chunks.go @@ -117,7 +117,7 @@ func (t *ListKnowledgeChunksTool) Execute(ctx context.Context, args map[string]i } chunks, total, err := t.chunkService.GetRepository().ListPagedChunksByKnowledgeID(ctx, - t.tenantID, knowledgeID, pagination, []types.ChunkType{types.ChunkTypeText, types.ChunkTypeFAQ}, "", "") + t.tenantID, knowledgeID, pagination, []types.ChunkType{types.ChunkTypeText, types.ChunkTypeFAQ}, "", "", "", "") if err != nil { return &types.ToolResult{ Success: false, diff --git a/internal/application/repository/chunk.go b/internal/application/repository/chunk.go index 03fa97cc..81216dbf 100644 --- a/internal/application/repository/chunk.go +++ b/internal/application/repository/chunk.go @@ -27,7 +27,9 @@ func (r *chunkRepository) CreateChunks(ctx context.Context, chunks []*types.Chun for _, chunk := range chunks { chunk.Content = common.CleanInvalidUTF8(chunk.Content) } - return r.db.WithContext(ctx).CreateInBatches(chunks, 100).Error + // Use Select("*") to ensure all fields including zero values (IsEnabled=false, Flags=0) + // are inserted, bypassing GORM's default value behavior for zero values + return r.db.WithContext(ctx).Select("*").CreateInBatches(chunks, 100).Error } // GetChunkByID retrieves a chunk by its ID and tenant ID @@ -78,6 +80,8 @@ func (r *chunkRepository) ListPagedChunksByKnowledgeID( chunkType []types.ChunkType, tagID string, keyword string, + searchField string, + sortOrder string, ) ([]*types.Chunk, int64, error) { var chunks []*types.Chunk var total int64 @@ -94,7 +98,20 @@ func (r *chunkRepository) ListPagedChunksByKnowledgeID( } if keyword != "" { like := "%" + keyword + "%" - db = db.Where("(content LIKE ? OR metadata::text LIKE ?)", like, like) + switch searchField { + case "standard_question": + // Search only in standard_question field of metadata + db = db.Where("metadata->>'standard_question' ILIKE ?", like) + case "similar_questions": + // Search in similar_questions array of metadata + db = db.Where("metadata->'similar_questions'::text ILIKE ?", like) + case "answers": + // Search in answers array of metadata + db = db.Where("metadata->'answers'::text ILIKE ?", like) + default: + // Search in all fields (content and metadata) + db = db.Where("(content ILIKE ? OR metadata::text ILIKE ?)", like, like) + } } return db } @@ -109,8 +126,14 @@ func (r *chunkRepository) ListPagedChunksByKnowledgeID( // Then query the paginated data dataQuery := baseFilter(r.db.WithContext(ctx)) + // Default is time descending, "asc" for time ascending + orderClause := "updated_at DESC" + if sortOrder == "asc" { + orderClause = "updated_at ASC" + } + if err := dataQuery. - Order("chunk_index ASC"). + Order(orderClause). Offset(page.Offset()). Limit(page.Limit()). Find(&chunks).Error; err != nil { diff --git a/internal/application/repository/tag.go b/internal/application/repository/tag.go index 8dbcac09..c47564a3 100644 --- a/internal/application/repository/tag.go +++ b/internal/application/repository/tag.go @@ -40,6 +40,20 @@ func (r *knowledgeTagRepository) GetByID(ctx context.Context, tenantID uint64, i return &tag, nil } +// GetByIDs retrieves multiple tags by their IDs in a single query +func (r *knowledgeTagRepository) GetByIDs(ctx context.Context, tenantID uint64, ids []string) ([]*types.KnowledgeTag, error) { + if len(ids) == 0 { + return []*types.KnowledgeTag{}, nil + } + var tags []*types.KnowledgeTag + if err := r.db.WithContext(ctx). + Where("tenant_id = ? AND id IN (?)", tenantID, ids). + Find(&tags).Error; err != nil { + return nil, err + } + return tags, nil +} + // GetByName gets a knowledge tag by name func (r *knowledgeTagRepository) GetByName(ctx context.Context, tenantID uint64, kbID string, name string) (*types.KnowledgeTag, error) { var tag types.KnowledgeTag diff --git a/internal/application/service/agent_service.go b/internal/application/service/agent_service.go index f4e6bace..1c707c13 100644 --- a/internal/application/service/agent_service.go +++ b/internal/application/service/agent_service.go @@ -345,7 +345,7 @@ func (s *agentService) getKnowledgeBaseInfos(ctx context.Context, kbIDs []string pageResult, err := s.knowledgeService.ListFAQEntries(ctx, kbID, &types.Pagination{ Page: 1, PageSize: 10, - }, "", "") + }, "", "", "", "") if err == nil && pageResult != nil { docCount = int(pageResult.Total) if entries, ok := pageResult.Data.([]*types.FAQEntry); ok { diff --git a/internal/application/service/chunk.go b/internal/application/service/chunk.go index 938232e2..c73107e7 100644 --- a/internal/application/service/chunk.go +++ b/internal/application/service/chunk.go @@ -151,6 +151,8 @@ func (s *chunkService) ListPagedChunksByKnowledgeID(ctx context.Context, chunkType, "", "", + "", + "", ) if err != nil { logger.ErrorWithFields(ctx, err, map[string]interface{}{ diff --git a/internal/application/service/evaluation.go b/internal/application/service/evaluation.go index b71ea63d..cf3c01fe 100644 --- a/internal/application/service/evaluation.go +++ b/internal/application/service/evaluation.go @@ -395,6 +395,15 @@ func (e *EvaluationService) EvalDataset(ctx context.Context, detail *types.Evalu // Prepare chat management parameters for this QA pair chatManage := detail.Params.Clone() chatManage.Query = qaPair.Question + chatManage.RewriteQuery = qaPair.Question + // Set knowledge base ID and search targets for this evaluation + chatManage.KnowledgeBaseIDs = []string{knowledgeBaseID} + chatManage.SearchTargets = types.SearchTargets{ + &types.SearchTarget{ + Type: types.SearchTargetTypeKnowledgeBase, + KnowledgeBaseID: knowledgeBaseID, + }, + } // Execute knowledge QA pipeline logger.Infof(ctx, "Running knowledge QA for question: %s", qaPair.Question) diff --git a/internal/application/service/knowledge.go b/internal/application/service/knowledge.go index 6c1e2662..fe18c966 100644 --- a/internal/application/service/knowledge.go +++ b/internal/application/service/knowledge.go @@ -2548,6 +2548,8 @@ func (s *knowledgeService) CloneChunk(ctx context.Context, src, dst *types.Knowl chunkType, "", "", + "", + "", ) chunkPage++ if err != nil { @@ -2642,7 +2644,7 @@ func (s *knowledgeService) CloneChunk(ctx context.Context, src, dst *types.Knowl // ListFAQEntries lists FAQ entries under a FAQ knowledge base. func (s *knowledgeService) ListFAQEntries(ctx context.Context, - kbID string, page *types.Pagination, tagID string, keyword string, + kbID string, page *types.Pagination, tagID string, keyword string, searchField string, sortOrder string, ) (*types.PageResult, error) { if page == nil { page = &types.Pagination{} @@ -2662,11 +2664,33 @@ func (s *knowledgeService) ListFAQEntries(ctx context.Context, } chunkType := []types.ChunkType{types.ChunkTypeFAQ} chunks, total, err := s.chunkRepo.ListPagedChunksByKnowledgeID( - ctx, tenantID, faqKnowledge.ID, page, chunkType, tagID, keyword, + ctx, tenantID, faqKnowledge.ID, page, chunkType, tagID, keyword, searchField, sortOrder, ) if err != nil { return nil, err } + + // Build tag ID to name mapping for all unique tag IDs (batch query) + tagNameMap := make(map[string]string) + tagIDs := make([]string, 0) + tagIDSet := make(map[string]struct{}) + for _, chunk := range chunks { + if chunk.TagID != "" { + if _, exists := tagIDSet[chunk.TagID]; !exists { + tagIDSet[chunk.TagID] = struct{}{} + tagIDs = append(tagIDs, chunk.TagID) + } + } + } + if len(tagIDs) > 0 { + tags, err := s.tagRepo.GetByIDs(ctx, tenantID, tagIDs) + if err == nil { + for _, tag := range tags { + tagNameMap[tag.ID] = tag.Name + } + } + } + kb.EnsureDefaults() entries := make([]*types.FAQEntry, 0, len(chunks)) for _, chunk := range chunks { @@ -2674,6 +2698,10 @@ func (s *knowledgeService) ListFAQEntries(ctx context.Context, if err != nil { return nil, err } + // Set tag name from mapping + if entry.TagID != "" { + entry.TagName = tagNameMap[entry.TagID] + } entries = append(entries, entry) } return types.NewPageResult(total, page, entries), nil @@ -3315,6 +3343,63 @@ func (s *knowledgeService) CreateFAQEntry(ctx context.Context, return nil, err } + // 查询TagName + if entry.TagID != "" { + tag, tagErr := s.tagRepo.GetByID(ctx, tenantID, entry.TagID) + if tagErr == nil && tag != nil { + entry.TagName = tag.Name + } + } + + return entry, nil +} + +// GetFAQEntry retrieves a single FAQ entry by ID. +func (s *knowledgeService) GetFAQEntry(ctx context.Context, + kbID string, entryID string, +) (*types.FAQEntry, error) { + if entryID == "" { + return nil, werrors.NewBadRequestError("条目ID不能为空") + } + + kb, err := s.validateFAQKnowledgeBase(ctx, kbID) + if err != nil { + return nil, err + } + kb.EnsureDefaults() + + tenantID := ctx.Value(types.TenantIDContextKey).(uint64) + + // 获取chunk + chunk, err := s.chunkService.GetChunkByID(ctx, entryID) + if err != nil { + return nil, err + } + + // 验证chunk属于当前知识库 + if chunk.KnowledgeBaseID != kb.ID || chunk.TenantID != tenantID { + return nil, werrors.NewNotFoundError("FAQ条目不存在") + } + + // 验证是FAQ类型 + if chunk.ChunkType != types.ChunkTypeFAQ { + return nil, werrors.NewNotFoundError("FAQ条目不存在") + } + + // 转换为FAQEntry返回 + entry, err := s.chunkToFAQEntry(chunk, kb) + if err != nil { + return nil, err + } + + // 查询TagName + if entry.TagID != "" { + tag, tagErr := s.tagRepo.GetByID(ctx, tenantID, entry.TagID) + if tagErr == nil && tag != nil { + entry.TagName = tag.Name + } + } + return entry, nil } diff --git a/internal/application/service/session.go b/internal/application/service/session.go index 49b8274d..d27af700 100644 --- a/internal/application/service/session.go +++ b/internal/application/service/session.go @@ -915,24 +915,46 @@ func getTenantConversationConfig(ctx context.Context) (*types.ConversationConfig } // SearchKnowledge performs knowledge base search without LLM summarization +// knowledgeBaseIDs: list of knowledge base IDs to search (supports multi-KB) +// knowledgeIDs: list of specific knowledge (file) IDs to search func (s *sessionService) SearchKnowledge(ctx context.Context, - knowledgeBaseID, query string, + knowledgeBaseIDs []string, knowledgeIDs []string, query string, ) ([]*types.SearchResult, error) { logger.Info(ctx, "Start knowledge base search without LLM summary") - logger.Infof(ctx, "Knowledge base search parameters, knowledge base ID: %s, query: %s", knowledgeBaseID, query) + logger.Infof(ctx, "Knowledge base search parameters, knowledge base IDs: %v, knowledge IDs: %v, query: %s", + knowledgeBaseIDs, knowledgeIDs, query) + + // Get tenant ID from context + tenantID, ok := ctx.Value(types.TenantIDContextKey).(uint64) + if !ok { + logger.Error(ctx, "Failed to get tenant ID from context") + return nil, fmt.Errorf("tenant ID not found in context") + } + + // Build unified search targets (computed once, used throughout pipeline) + searchTargets, err := s.buildSearchTargets(ctx, tenantID, knowledgeBaseIDs, knowledgeIDs) + if err != nil { + logger.Warnf(ctx, "Failed to build search targets: %v", err) + } + + if len(searchTargets) == 0 { + logger.Warn(ctx, "No search targets available, returning empty results") + return []*types.SearchResult{}, nil + } // Create default retrieval parameters chatManage := &types.ChatManage{ - Query: query, - RewriteQuery: query, - VectorThreshold: s.cfg.Conversation.VectorThreshold, // Use default configuration - KeywordThreshold: s.cfg.Conversation.KeywordThreshold, // Use default configuration - EmbeddingTopK: s.cfg.Conversation.EmbeddingTopK, // Use default configuration - RerankTopK: s.cfg.Conversation.RerankTopK, // Use default configuration - RerankThreshold: s.cfg.Conversation.RerankThreshold, // Use default configuration - MaxRounds: s.cfg.Conversation.MaxRounds, - RewritePromptSystem: s.cfg.Conversation.RewritePromptSystem, - RewritePromptUser: s.cfg.Conversation.RewritePromptUser, + Query: query, + RewriteQuery: query, + KnowledgeBaseIDs: knowledgeBaseIDs, + KnowledgeIDs: knowledgeIDs, + SearchTargets: searchTargets, + VectorThreshold: s.cfg.Conversation.VectorThreshold, // Use default configuration + KeywordThreshold: s.cfg.Conversation.KeywordThreshold, // Use default configuration + EmbeddingTopK: s.cfg.Conversation.EmbeddingTopK, // Use default configuration + RerankTopK: s.cfg.Conversation.RerankTopK, // Use default configuration + RerankThreshold: s.cfg.Conversation.RerankThreshold, // Use default configuration + MaxRounds: s.cfg.Conversation.MaxRounds, } // Get default models @@ -974,7 +996,8 @@ func (s *sessionService) SearchKnowledge(ctx context.Context, logger.Infof(ctx, "Trigger search event list: %v", methods) span.SetAttributes( attribute.String("query", query), - attribute.String("knowledge_base_id", knowledgeBaseID), + attribute.StringSlice("knowledge_base_ids", knowledgeBaseIDs), + attribute.StringSlice("knowledge_ids", knowledgeIDs), attribute.String("method", strings.Join(methods, ",")), ) diff --git a/internal/handler/faq.go b/internal/handler/faq.go index 8a7ef256..a481648f 100644 --- a/internal/handler/faq.go +++ b/internal/handler/faq.go @@ -28,11 +28,13 @@ func NewFAQHandler(knowledgeService interfaces.KnowledgeService) *FAQHandler { // @Tags FAQ管理 // @Accept json // @Produce json -// @Param id path string true "知识库ID" -// @Param page query int false "页码" -// @Param page_size query int false "每页数量" -// @Param tag_id query string false "标签ID筛选" -// @Param keyword query string false "关键词搜索" +// @Param id path string true "知识库ID" +// @Param page query int false "页码" +// @Param page_size query int false "每页数量" +// @Param tag_id query string false "标签ID筛选" +// @Param keyword query string false "关键词搜索" +// @Param search_field query string false "搜索字段: standard_question(标准问题), similar_questions(相似问法), answers(答案), 默认搜索全部" +// @Param sort_order query string false "排序方式: asc(按更新时间正序), 默认按更新时间倒序" // @Success 200 {object} map[string]interface{} "FAQ列表" // @Failure 400 {object} errors.AppError "请求参数错误" // @Security Bearer @@ -49,8 +51,10 @@ func (h *FAQHandler) ListEntries(c *gin.Context) { tagID := secutils.SanitizeForLog(c.Query("tag_id")) keyword := secutils.SanitizeForLog(c.Query("keyword")) + searchField := secutils.SanitizeForLog(c.Query("search_field")) + sortOrder := secutils.SanitizeForLog(c.Query("sort_order")) - result, err := h.knowledgeService.ListFAQEntries(ctx, secutils.SanitizeForLog(c.Param("id")), &page, tagID, keyword) + result, err := h.knowledgeService.ListFAQEntries(ctx, secutils.SanitizeForLog(c.Param("id")), &page, tagID, keyword, searchField, sortOrder) if err != nil { logger.ErrorWithFields(ctx, err, nil) c.Error(err) diff --git a/internal/handler/session/qa.go b/internal/handler/session/qa.go index ea993233..4a4ae8c0 100644 --- a/internal/handler/session/qa.go +++ b/internal/handler/session/qa.go @@ -297,18 +297,38 @@ func (h *Handler) SearchKnowledge(c *gin.Context) { return } - if request.KnowledgeBaseID == "" { - logger.Error(ctx, "Knowledge base ID is empty") - c.Error(errors.NewBadRequestError("Knowledge base ID cannot be empty")) + // Merge single knowledge_base_id into knowledge_base_ids for backward compatibility + knowledgeBaseIDs := request.KnowledgeBaseIDs + if request.KnowledgeBaseID != "" { + // Check if it's already in the list to avoid duplicates + found := false + for _, id := range knowledgeBaseIDs { + if id == request.KnowledgeBaseID { + found = true + break + } + } + if !found { + knowledgeBaseIDs = append(knowledgeBaseIDs, request.KnowledgeBaseID) + } + } + + if len(knowledgeBaseIDs) == 0 && len(request.KnowledgeIDs) == 0 { + logger.Error(ctx, "No knowledge base IDs or knowledge IDs provided") + c.Error(errors.NewBadRequestError("At least one knowledge_base_id, knowledge_base_ids or knowledge_ids must be provided")) return } - logger.Infof(ctx, "Knowledge search request, knowledge base ID: %s, query: %s", - secutils.SanitizeForLog(request.KnowledgeBaseID), - secutils.SanitizeForLog(request.Query)) + logger.Infof( + ctx, + "Knowledge search request, knowledge base IDs: %v, knowledge IDs: %v, query: %s", + secutils.SanitizeForLogArray(knowledgeBaseIDs), + secutils.SanitizeForLogArray(request.KnowledgeIDs), + secutils.SanitizeForLog(request.Query), + ) - // Perform search - searchResults, err := h.sessionService.SearchKnowledge(ctx, request.KnowledgeBaseID, request.Query) + // Directly call knowledge retrieval service without LLM summarization + searchResults, err := h.sessionService.SearchKnowledge(ctx, knowledgeBaseIDs, request.KnowledgeIDs, request.Query) if err != nil { logger.ErrorWithFields(ctx, err, nil) c.Error(errors.NewInternalServerError(err.Error())) diff --git a/internal/handler/session/types.go b/internal/handler/session/types.go index a3e4a956..d0492ddb 100644 --- a/internal/handler/session/types.go +++ b/internal/handler/session/types.go @@ -73,8 +73,10 @@ type CreateKnowledgeQARequest struct { // SearchKnowledgeRequest defines the request structure for searching knowledge without LLM summarization type SearchKnowledgeRequest struct { - Query string `json:"query" binding:"required"` // Query text to search for - KnowledgeBaseID string `json:"knowledge_base_id" binding:"required"` // ID of the knowledge base to search + Query string `json:"query" binding:"required"` // Query text to search for + KnowledgeBaseID string `json:"knowledge_base_id"` // Single knowledge base ID (for backward compatibility) + KnowledgeBaseIDs []string `json:"knowledge_base_ids"` // IDs of knowledge bases to search (multi-KB support) + KnowledgeIDs []string `json:"knowledge_ids"` // IDs of specific knowledge (files) to search } // StopSessionRequest represents the stop session request diff --git a/internal/types/chat_manage.go b/internal/types/chat_manage.go index 576507ba..22bf529a 100644 --- a/internal/types/chat_manage.go +++ b/internal/types/chat_manage.go @@ -65,12 +65,27 @@ func (c *ChatManage) Clone() *ChatManage { knowledgeIDs := make([]string, len(c.KnowledgeIDs)) copy(knowledgeIDs, c.KnowledgeIDs) + // Deep copy search targets slice + searchTargets := make(SearchTargets, len(c.SearchTargets)) + for i, t := range c.SearchTargets { + if t != nil { + kidsCopy := make([]string, len(t.KnowledgeIDs)) + copy(kidsCopy, t.KnowledgeIDs) + searchTargets[i] = &SearchTarget{ + Type: t.Type, + KnowledgeBaseID: t.KnowledgeBaseID, + KnowledgeIDs: kidsCopy, + } + } + } + return &ChatManage{ Query: c.Query, RewriteQuery: c.RewriteQuery, SessionID: c.SessionID, KnowledgeBaseIDs: knowledgeBaseIDs, KnowledgeIDs: knowledgeIDs, + SearchTargets: searchTargets, VectorThreshold: c.VectorThreshold, KeywordThreshold: c.KeywordThreshold, EmbeddingTopK: c.EmbeddingTopK, @@ -101,6 +116,7 @@ func (c *ChatManage) Clone() *ChatManage { RewritePromptUser: c.RewritePromptUser, EnableRewrite: c.EnableRewrite, EnableQueryExpansion: c.EnableQueryExpansion, + TenantID: c.TenantID, } } diff --git a/internal/types/faq.go b/internal/types/faq.go index 7729ba30..96f1c03b 100644 --- a/internal/types/faq.go +++ b/internal/types/faq.go @@ -180,6 +180,7 @@ type FAQEntry struct { KnowledgeID string `json:"knowledge_id"` KnowledgeBaseID string `json:"knowledge_base_id"` TagID string `json:"tag_id"` + TagName string `json:"tag_name"` IsEnabled bool `json:"is_enabled"` IsRecommended bool `json:"is_recommended"` StandardQuestion string `json:"standard_question"` diff --git a/internal/types/interfaces/chunk.go b/internal/types/interfaces/chunk.go index 57c5a90a..a704bb00 100644 --- a/internal/types/interfaces/chunk.go +++ b/internal/types/interfaces/chunk.go @@ -18,6 +18,8 @@ type ChunkRepository interface { ListChunksByKnowledgeID(ctx context.Context, tenantID uint64, knowledgeID string) ([]*types.Chunk, error) // ListPagedChunksByKnowledgeID lists paged chunks by knowledge id. // When tagID is non-empty, results are filtered by tag_id. + // sortOrder: "asc" for time ascending (updated_at ASC), default is time descending (updated_at DESC) + // searchField: specifies which field to search in (for FAQ: "standard_question", "similar_questions", "answers", "" for all) ListPagedChunksByKnowledgeID( ctx context.Context, tenantID uint64, @@ -26,6 +28,8 @@ type ChunkRepository interface { chunkType []types.ChunkType, tagID string, keyword string, + searchField string, + sortOrder string, ) ([]*types.Chunk, int64, error) ListChunkByParentID(ctx context.Context, tenantID uint64, parentID string) ([]*types.Chunk, error) // UpdateChunk updates a chunk diff --git a/internal/types/interfaces/knowledge.go b/internal/types/interfaces/knowledge.go index ad0a25b5..ac1bf388 100644 --- a/internal/types/interfaces/knowledge.go +++ b/internal/types/interfaces/knowledge.go @@ -74,12 +74,16 @@ type KnowledgeService interface { UpdateImageInfo(ctx context.Context, knowledgeID string, chunkID string, imageInfo string) error // ListFAQEntries lists FAQ entries under a FAQ knowledge base. // When tagID is non-empty, results are filtered by tag_id on FAQ chunks. + // searchField: specifies which field to search in ("standard_question", "similar_questions", "answers", "" for all) + // sortOrder: "asc" for time ascending (updated_at ASC), default is time descending (updated_at DESC) ListFAQEntries( ctx context.Context, kbID string, page *types.Pagination, tagID string, keyword string, + searchField string, + sortOrder string, ) (*types.PageResult, error) // UpsertFAQEntries imports or appends FAQ entries asynchronously. // Returns task ID (Knowledge ID) for tracking import progress. diff --git a/internal/types/interfaces/session.go b/internal/types/interfaces/session.go index b47d224d..339f089b 100644 --- a/internal/types/interfaces/session.go +++ b/internal/types/interfaces/session.go @@ -41,7 +41,9 @@ type SessionService interface { // KnowledgeQAByEvent performs knowledge-based question answering by event KnowledgeQAByEvent(ctx context.Context, chatManage *types.ChatManage, eventList []types.EventType) error // SearchKnowledge performs knowledge-based search, without summarization - SearchKnowledge(ctx context.Context, knowledgeBaseID, query string) ([]*types.SearchResult, error) + // knowledgeBaseIDs: list of knowledge base IDs to search (supports multi-KB) + // knowledgeIDs: list of specific knowledge (file) IDs to search + SearchKnowledge(ctx context.Context, knowledgeBaseIDs []string, knowledgeIDs []string, query string) ([]*types.SearchResult, error) // AgentQA performs agent-based question answering with conversation history and streaming support // eventBus is optional - if nil, uses service's default EventBus // customAgent is optional - if provided, uses custom agent configuration instead of tenant defaults diff --git a/internal/types/interfaces/tag.go b/internal/types/interfaces/tag.go index 471c2d2e..9f6e0411 100644 --- a/internal/types/interfaces/tag.go +++ b/internal/types/interfaces/tag.go @@ -26,6 +26,8 @@ type KnowledgeTagRepository interface { Create(ctx context.Context, tag *types.KnowledgeTag) error Update(ctx context.Context, tag *types.KnowledgeTag) error GetByID(ctx context.Context, tenantID uint64, id string) (*types.KnowledgeTag, error) + // GetByIDs retrieves multiple tags by their IDs in a single query. + GetByIDs(ctx context.Context, tenantID uint64, ids []string) ([]*types.KnowledgeTag, error) GetByName(ctx context.Context, tenantID uint64, kbID string, name string) (*types.KnowledgeTag, error) ListByKB( ctx context.Context,