mirror of
https://github.com/Tencent/WeKnora.git
synced 2026-06-04 13:30:32 +08:00
0e8de6192c
Wires KnowledgeBase.VectorStoreID and the ownership-aware retrieve factory into the user-facing knowledge-base lifecycle: - POST /knowledge-bases validates the requested vector_store_id against the caller's tenant scope and the engine registry. New error codes ErrVectorStoreBindingInvalid (2200) and ErrVectorStoreUnavailable (2201) distinguish the typed branches without echoing UUIDs to the client. - GET / POST / PUT / PUT-pin responses embed the bound store's display metadata (name, source, engine_type, status) without exposing any connection credentials. Cross-tenant shared KBs receive a suppressed payload (vector_store_id stripped, source="shared") so operator-chosen store names cannot be enumerated across tenants. - POST /knowledge-bases/copy synchronously rejects clones whose target has a different embedding model or vector store, before the async clone task is enqueued. The async clone worker re-applies the same checks for defense in depth. - DELETE /vector-stores/:id refuses to remove a store with bound KBs, inside a transaction that row-locks the store on PostgreSQL and serializes via WAL on SQLite. unregister-from-registry is wrapped in defer/recover so a panic surfaces as a structured warning instead of silently leaking a stale engine. - vector_store_id is immutable after creation. The GORM <-:create tag blocks every ORM update path; the service-layer DTO omits the field entirely; a reflection-based regression test catches any future maintainer who adds it back to either layer. - Empty-string vector_store_id is normalized to nil at both the create path and inside SharesStoreWith, so rows persisted by callers that did not run Normalize first cannot trip false same-store comparisons. Part of #993. Depends on #994 and #1310.
WeKnora API 文档
目录
概述
WeKnora 提供了一系列 RESTful API，用于创建和管理知识库、检索知识，以及进行基于知识的问答。本文档详细描述了这些 API 的使用方式。
最权威参考：Swagger UI
WeKnora 同时提供基于 OpenAPI 的 Swagger 文档。启动服务后访问 http://localhost:8080/swagger/index.html，可看到所有端点的完整参数、请求/响应 schema，并可直接在浏览器内试调——它随代码自动更新，是最准确的接口参考。
本目录下的 markdown 文档提供更易读的示例与场景说明，与 swagger 同步维护；当二者出现差异时，以 swagger 为准。
Swagger UI 仅在非 release 模式（
GIN_MODE != release）下挂载；生产部署默认关闭。
基础信息
- 基础 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 状态码表示请求状态，并返回统一的错误响应格式：
{
"success": false,
"error": {
"code": "错误代码",
"message": "错误信息",
"details": "错误详情"
}
}
API 概览
WeKnora API 按功能分为以下几类：
| 分类 | 描述 | 文档链接 |
|---|---|---|
| 认证管理 | 用户注册、登录、令牌管理；OIDC 流程 | auth.md · OIDC认证调用流程.md |
| 租户管理 | 创建和管理租户账户 | tenant.md |
| 知识库管理 | 创建、查询和管理知识库 | knowledge-base.md |
| 知识管理 | 上传、检索和管理知识内容 | knowledge.md |
| 模型管理 | 配置和管理各种AI模型 | model.md |
| 分块管理 | 管理知识的分块内容 | chunk.md |
| 标签管理 | 管理知识库的标签分类 | tag.md |
| FAQ管理 | 管理FAQ问答对 | faq.md |
| 智能体管理 | 创建和管理自定义智能体 | agent.md |
| 会话管理 | 创建和管理对话会话 | session.md |
| 知识搜索 | 在知识库中搜索内容 | knowledge-search.md |
| 聊天功能 | 基于知识库和 Agent 进行问答 | chat.md |
| 消息管理 | 获取和管理对话消息 | message.md |
| 评估功能 | 评估模型性能 | evaluation.md |
| 初始化管理 | 知识库模型配置与 Ollama 管理 | initialization.md |
| 系统管理 | 系统信息、解析引擎、存储引擎 | system.md |
| MCP 服务 | MCP 工具服务管理 | mcp-service.md |
| 组织管理 | 组织、成员、知识库/智能体共享 | organization.md |
| Skills | 预装智能体技能 | skill.md |
| 网络搜索 | 网络搜索服务商 | web-search.md |
| 向量存储 | 向量数据库连接管理 | vector-store.md |
| IM 渠道 | 企业微信 / 飞书 / Slack 等 IM 平台对接，含渠道 CRUD 与回调 | ../IM集成开发文档.md |
| 数据源导入 | 飞书 / 企微 / Notion / Confluence 等外部数据源接入与同步 | ../数据源导入开发文档.md |