docs(api): rewrite markdown to match current routes

Refs #890 #1049 #1168.

按集成方视角全量审计 17 个 API markdown 文档与 internal/router/router.go
对齐。每个端点新增参数说明小节(path/query/body 字段含义)和响应字段
含义说明(#1168 的核心诉求)。

【与代码对齐】
- 删除已下线端点:system.md 中的 /system/minio/buckets(代码中已无对
  应路由)。
- 修正路径错误:chunk.md 中 /chunks/get-by-id/:id → /chunks/by-id/:id;
  /chunks/:id/delete-question → /chunks/by-id/:id/questions;
  organization.md 中 /organizations/preview/:invite_code → :code。
- 修正字段类型:faq tag_id / entry_id 由 string 改为 int64;
  knowledge.search 响应结构纠正。
- 补齐缺失端点(move-targets、batch-delete、move/progress、pin/unpin/
  stop/continue-stream、tool-approvals、organization agent-shares 等
  30+ 条)。

【精简】
- knowledge-base.md / model.md 把重复 5 次 / 3 次的完整对象样例
  收敛为指向首次出现("字段结构同 POST /xxx 响应"),节省约 400 行
  而不损失信息(仅去重,原作者写的每个字段定义都保留可达)。
- 示例 X-API-Key 统一为 sk-xxxxx(避免读者复制看似真实的 key)。

【清理】
- 删除内部实现细节引用:mcp-service.md 中 6 处 "issue #1173"、
  organization.md 中 "RegisterOrganizationRoutes" 等。

不动 initialization.md:其中端点(KB 配置、模型连通性测试、Ollama 管理)
对集成方有实用价值,保留原作者写好的内容不删。

格式统一遵循 web-search.md 重写后的范式(路由表 + 每端点方法/路径 +
参数表 + curl + 响应 JSON + 字段说明)。
This commit is contained in:
nullkey
2026-05-11 17:37:14 +08:00
committed by lyingbug
parent 54b6f2dc35
commit 1c7171b2c6
17 changed files with 3312 additions and 2393 deletions
+99 -146
View File
@@ -2,24 +2,26 @@
[返回目录](./README.md)
| 方法 | 路径 | 描述 |
| ------ | ----------------------- | --------------------- |
| POST | `/models` | 创建模型 |
| GET | `/models` | 获取模型列表 |
| GET | `/models/:id` | 获取模型详情 |
| PUT | `/models/:id` | 更新模型 |
| DELETE | `/models/:id` | 删除模型 |
| GET | `/models/providers` | 获取模型服务商列表 |
模型管理接口用于维护当前租户下可用的 LLM / Embedding / Rerank / VLLM / ASR 模型配置。
| 方法 | 路径 | 描述 |
| ------ | ------------------- | --------------------- |
| GET | `/models/providers` | 获取模型服务商列表 |
| POST | `/models` | 创建模型 |
| GET | `/models` | 获取模型列表 |
| GET | `/models/:id` | 获取模型详情 |
| PUT | `/models/:id` | 更新模型 |
| DELETE | `/models/:id` | 删除模型 |
## 服务商支持 (Provider Support)
WeKnora 支持多种主流 AI 模型服务商,在创建模型时可通过 `provider` 字段指定服务商类型以获得更好的兼容性。
WeKnora 支持多种主流 AI 模型服务商,在创建模型时可通过 `parameters.provider` 字段指定服务商类型以获得更好的兼容性。
### 支持的服务商列表
| 服务商标识 | 名称 | 支持的模型类型 |
| -------------- | ---------------------------- | ------------------------------- |
| `generic` | 自定义 (OpenAI兼容接口) | Chat, Embedding, Rerank, VLLM |
| `generic` | 自定义 (OpenAI 兼容接口) | Chat, Embedding, Rerank, VLLM |
| `openai` | OpenAI | Chat, Embedding, Rerank, VLLM |
| `aliyun` | 阿里云 DashScope | Chat, Embedding, Rerank, VLLM |
| `zhipu` | 智谱 BigModel | Chat, Embedding, Rerank, VLLM |
@@ -39,15 +41,17 @@ WeKnora 支持多种主流 AI 模型服务商,在创建模型时可通过 `pro
| `longcat` | LongCat AI | Chat |
| `gpustack` | GPUStack | Chat, Embedding, Rerank, VLLM |
> 实际可用的服务商以 `GET /models/providers` 返回为准。
## GET `/models/providers` - 获取模型服务商列表
根据模型类型获取支持的服务商列表及配置信息。
根据模型类型获取支持的服务商列表及配置信息(系统级元数据,与租户无关)。
**请求参数**:
**查询参数**:
| 参数 | 类型 | 必填 | 描述 |
| ---------- | ------ | ---- | ---------------------------------------------- |
| model_type | string | 否 | 模型类型:`chat`, `embedding`, `rerank`, `vllm` |
| 字段 | 类型 | 必填 | 说明 |
| ---------- | ------ | ---- | --------------------------------------------------- |
| model_type | string | 否 | 模型类型,可选值:`chat` / `embedding` / `rerank` / `vllm` / `asr`;省略则返回全部 |
**请求**:
@@ -95,6 +99,20 @@ curl --location 'http://localhost:8080/api/v1/models/providers?model_type=embedd
## POST `/models` - 创建模型
为当前租户创建一个新的模型配置。
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------- | ------ | ---- | --------------------------------------------------------------- |
| name | string | 是 | 模型名称(远程模型对应服务商的 model id,本地模型为 Ollama tag)|
| type | string | 是 | 模型类型,可选值:`KnowledgeQA` / `Embedding` / `Rerank` / `VLLM` / `ASR` |
| source | string | 是 | 模型来源,可选值:`local` / `remote` |
| description | string | 否 | 模型描述 |
| parameters | object | 是 | 模型参数,详见下方 [Parameters](#parameters-模型参数) |
> 当 `parameters.base_url` 不为空时,后端会执行 SSRF 校验,校验失败将返回 400。
### 创建对话模型(KnowledgeQA)
**本地 Ollama 模型**:
@@ -295,6 +313,8 @@ curl --location 'http://localhost:8080/api/v1/models' \
## GET `/models` - 获取模型列表
返回当前租户下的所有模型。内置模型(`is_builtin = true`)的 `base_url` 与 `api_key` 会被清空以隐藏敏感信息。
**请求**:
```curl
@@ -303,62 +323,16 @@ curl --location 'http://localhost:8080/api/v1/models' \
--header 'X-API-Key: your_api_key'
```
**响应**:
```json
{
"success": true,
"data": [
{
"id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"tenant_id": 1,
"name": "text-embedding-v3",
"type": "Embedding",
"source": "remote",
"description": "阿里云通义千问 Embedding 模型",
"parameters": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"api_key": "sk-***",
"provider": "aliyun",
"embedding_parameters": {
"dimension": 1024,
"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": "qwen-plus",
"type": "KnowledgeQA",
"source": "remote",
"description": "阿里云 Qwen 大模型",
"parameters": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"api_key": "sk-***",
"provider": "aliyun",
"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
}
]
}
```
**响应**: `data` 为数组,每个元素的字段结构同 `POST /models` 响应。内置模型的 `base_url` 与 `api_key` 字段为空字符串。
## GET `/models/:id` - 获取模型详情
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | -------- |
| id | string | 是 | 模型 ID |
**请求**:
```curl
@@ -367,38 +341,28 @@ curl --location 'http://localhost:8080/api/v1/models/dff7bc94-7885-4dd1-bfd5-bd9
--header 'X-API-Key: your_api_key'
```
**响应**:
```json
{
"success": true,
"data": {
"id": "dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3",
"tenant_id": 1,
"name": "text-embedding-v3",
"type": "Embedding",
"source": "remote",
"description": "阿里云通义千问 Embedding 模型",
"parameters": {
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"api_key": "sk-***",
"provider": "aliyun",
"embedding_parameters": {
"dimension": 1024,
"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
}
}
```
**响应**: 字段结构同 `POST /models` 响应。404 表示模型不存在。
## PUT `/models/:id` - 更新模型
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | -------- |
| id | string | 是 | 模型 ID |
**参数说明(请求体)**:
| 字段 | 类型 | 必填 | 说明 |
| ----------- | ------ | ---- | --------------------------------------------------------------- |
| name | string | 否 | 模型名称(为空字符串时保留原值) |
| description | string | 否 | 模型描述(始终覆盖,传空字符串会清空) |
| type | string | 否 | 模型类型,取值同创建接口 |
| source | string | 否 | 模型来源,取值同创建接口 |
| parameters | object | 否 | 模型参数;`parameter_size` 由后端管理,请求中无需提供;`extra_config` 为空时会沿用旧值 |
> 同样会对 `parameters.base_url` 做 SSRF 校验,失败时返回 400。
**请求**:
```curl
@@ -407,6 +371,8 @@ curl --location --request PUT 'http://localhost:8080/api/v1/models/8fdc464d-8eaa
--header 'X-API-Key: your_api_key' \
--data '{
"name": "gte-rerank-v2",
"type": "Rerank",
"source": "remote",
"description": "阿里云 GTE Rerank 模型 V2",
"parameters": {
"base_url": "https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank",
@@ -416,38 +382,16 @@ curl --location --request PUT 'http://localhost:8080/api/v1/models/8fdc464d-8eaa
}'
```
**响应**:
```json
{
"success": true,
"data": {
"id": "8fdc464d-8eaa-44d4-a85b-094b28af5330",
"tenant_id": 1,
"name": "gte-rerank-v2",
"type": "Rerank",
"source": "remote",
"description": "阿里云 GTE Rerank 模型 V2",
"parameters": {
"base_url": "https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank",
"api_key": "sk-***",
"provider": "aliyun",
"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
}
}
```
**响应**: 字段结构同 `POST /models` 响应,返回更新后的完整模型对象。
## DELETE `/models/:id` - 删除模型
**路径参数**:
| 字段 | 类型 | 必填 | 说明 |
| ---- | ------ | ---- | -------- |
| id | string | 是 | 模型 ID |
**请求**:
```curl
@@ -465,37 +409,46 @@ curl --location --request DELETE 'http://localhost:8080/api/v1/models/8fdc464d-8
}
```
404 表示模型不存在。
## 参数说明
### ModelType (模型类型)
| 值 | 说明 | 用途 |
| ------------ | ------------ | ------------------------------ |
| KnowledgeQA | 对话模型 | 知识库问答、对话生成 |
| Embedding | 嵌入模型 | 文本向量化、知识库检索 |
| Rerank | 排序模型 | 检索结果重排序、相关性优化 |
| VLLM | 视觉语言模型 | 多模态分析、图文理解 |
| 值 | 前端别名 | 说明 | 用途 |
| ----------- | ----------- | ------------ | ------------------------------ |
| KnowledgeQA | `chat` | 对话模型 | 知识库问答、对话生成 |
| Embedding | `embedding` | 嵌入模型 | 文本向量化、知识库检索 |
| Rerank | `rerank` | 排序模型 | 检索结果重排序、相关性优化 |
| VLLM | `vllm` | 视觉语言模型 | 多模态分析、图文理解 |
| ASR | `asr` | 语音识别模型 | 音频转写 |
> 创建/更新接口请求体的 `type` 字段使用第一列的后端枚举值(如 `KnowledgeQA`);`GET /models/providers?model_type=` 查询参数使用第二列的前端别名(如 `chat`)。
### ModelSource (模型来源)
| 值 | 说明 | 配置要求 |
| -------- | ---------- | ------------------------------ |
| local | 本地模型 | 需要已安装 Ollama 并拉取模型 |
| 值 | 说明 | 配置要求 |
| -------- | ---------- | -------------------------------- |
| local | 本地模型 | 需要已安装 Ollama 并拉取模型 |
| remote | 远程 API | 需要提供 `base_url` 和 `api_key` |
### Parameters (模型参数)
| 字段 | 类型 | 说明 |
| -------------------- | ------ | -------------------------------------------- |
| base_url | string | API 服务地址(远程模型必填) |
| api_key | string | API 密钥(远程模型必填) |
| provider | string | 服务商标识(可选,用于选择特定的 API 适配器)|
| embedding_parameters | object | Embedding 模型专用参数 |
| extra_config | object | 服务商特定的额外配置 |
| 字段 | 类型 | 必填 | 说明 |
| -------------------- | ----------------- | ---- | ---------------------------------------------------------- |
| base_url | string | 否 | API 服务地址;远程模型必填,会经过 SSRF 校验 |
| api_key | string | 否 | API 密钥;远程模型必填,存储时使用 AES-256 加密 |
| provider | string | 否 | 服务商标识(见上方支持列表),用于选择特定的 API 适配器 |
| interface_type | string | 否 | 接口风格标识(OpenAI 兼容请留空) |
| embedding_parameters | object | 否 | Embedding 模型专用参数,见下方 |
| parameter_size | string | 否 | 模型参数规模(如 `7B`/`13B`/`70B`),通常由后端写入 |
| extra_config | object<string,string> | 否 | 服务商特定的额外配置 |
| custom_headers | object<string,string> | 否 | 调用上游 API 时附加的自定义 HTTP 头;保留头会被忽略 |
| supports_vision | bool | 否 | 模型是否支持图像/多模态输入 |
### EmbeddingParameters (嵌入参数)
| 字段 | 类型 | 说明 |
| ---------------------- | ---- | -------------------------- |
| dimension | int | 向量维度(如:768, 1024) |
| truncate_prompt_tokens | int | 截断 Token 数(0 表示不截断)|
| 字段 | 类型 | 必填 | 说明 |
| ---------------------- | ---- | ---- | ------------------------------- |
| dimension | int | 否 | 向量维度(如 768、1024) |
| truncate_prompt_tokens | int | 否 | 截断 Token 数(0 表示不截断) |