mirror of
https://github.com/Tencent/WeKnora.git
synced 2026-06-04 13:30:32 +08:00
1c7171b2c6
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 + 字段说明）。
455 lines
17 KiB
Markdown
455 lines
17 KiB
Markdown
# 模型管理 API
|
||
|
||
[返回目录](./README.md)
|
||
|
||
模型管理接口用于维护当前租户下可用的 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 模型服务商，在创建模型时可通过 `parameters.provider` 字段指定服务商类型以获得更好的兼容性。
|
||
|
||
### 支持的服务商列表
|
||
|
||
| 服务商标识 | 名称 | 支持的模型类型 |
|
||
| -------------- | ---------------------------- | ------------------------------- |
|
||
| `generic` | 自定义 (OpenAI 兼容接口) | Chat, Embedding, Rerank, VLLM |
|
||
| `openai` | OpenAI | Chat, Embedding, Rerank, VLLM |
|
||
| `aliyun` | 阿里云 DashScope | Chat, Embedding, Rerank, VLLM |
|
||
| `zhipu` | 智谱 BigModel | Chat, Embedding, Rerank, VLLM |
|
||
| `volcengine` | 火山引擎 Volcengine | Chat, Embedding, VLLM |
|
||
| `hunyuan` | 腾讯混元 Hunyuan | Chat, Embedding |
|
||
| `deepseek` | DeepSeek | Chat |
|
||
| `minimax` | MiniMax | Chat |
|
||
| `mimo` | 小米 MiMo | Chat |
|
||
| `siliconflow` | 硅基流动 SiliconFlow | Chat, Embedding, Rerank, VLLM |
|
||
| `jina` | Jina | Embedding, Rerank |
|
||
| `openrouter` | OpenRouter | Chat, VLLM |
|
||
| `gemini` | Google Gemini | Chat |
|
||
| `modelscope` | 魔搭 ModelScope | Chat, Embedding, VLLM |
|
||
| `moonshot` | 月之暗面 Moonshot | Chat, VLLM |
|
||
| `qianfan` | 百度千帆 Baidu Cloud | Chat, Embedding, Rerank, VLLM |
|
||
| `qiniu` | 七牛云 Qiniu | Chat |
|
||
| `longcat` | LongCat AI | Chat |
|
||
| `gpustack` | GPUStack | Chat, Embedding, Rerank, VLLM |
|
||
|
||
> 实际可用的服务商以 `GET /models/providers` 返回为准。
|
||
|
||
## GET `/models/providers` - 获取模型服务商列表
|
||
|
||
根据模型类型获取支持的服务商列表及配置信息（系统级元数据，与租户无关）。
|
||
|
||
**查询参数**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| ---------- | ------ | ---- | --------------------------------------------------- |
|
||
| model_type | string | 否 | 模型类型，可选值：`chat` / `embedding` / `rerank` / `vllm` / `asr`；省略则返回全部 |
|
||
|
||
**请求**:
|
||
|
||
```curl
|
||
# 获取所有服务商
|
||
curl --location 'http://localhost:8080/api/v1/models/providers' \
|
||
--header 'X-API-Key: your_api_key'
|
||
|
||
# 获取支持 Embedding 类型的服务商
|
||
curl --location 'http://localhost:8080/api/v1/models/providers?model_type=embedding' \
|
||
--header 'X-API-Key: your_api_key'
|
||
```
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": [
|
||
{
|
||
"value": "aliyun",
|
||
"label": "阿里云 DashScope",
|
||
"description": "qwen-plus, tongyi-embedding-vision-plus, qwen3-rerank, etc.",
|
||
"defaultUrls": {
|
||
"chat": "https://dashscope.aliyuncs.com/compatible-mode/v1",
|
||
"embedding": "https://dashscope.aliyuncs.com/compatible-mode/v1",
|
||
"rerank": "https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank"
|
||
},
|
||
"modelTypes": ["chat", "embedding", "rerank", "vllm"]
|
||
},
|
||
{
|
||
"value": "zhipu",
|
||
"label": "智谱 BigModel",
|
||
"description": "glm-4.7, embedding-3, rerank, etc.",
|
||
"defaultUrls": {
|
||
"chat": "https://open.bigmodel.cn/api/paas/v4",
|
||
"embedding": "https://open.bigmodel.cn/api/paas/v4/embeddings",
|
||
"rerank": "https://open.bigmodel.cn/api/paas/v4/rerank"
|
||
},
|
||
"modelTypes": ["chat", "embedding", "rerank", "vllm"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
## 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 模型**:
|
||
|
||
```curl
|
||
curl --location 'http://localhost:8080/api/v1/models' \
|
||
--header 'Content-Type: application/json' \
|
||
--header 'X-API-Key: your_api_key' \
|
||
--data '{
|
||
"name": "qwen3:8b",
|
||
"type": "KnowledgeQA",
|
||
"source": "local",
|
||
"description": "LLM Model for Knowledge QA",
|
||
"parameters": {
|
||
"base_url": "",
|
||
"api_key": ""
|
||
}
|
||
}'
|
||
```
|
||
|
||
**远程 API 模型（指定服务商）**:
|
||
|
||
```curl
|
||
curl --location 'http://localhost:8080/api/v1/models' \
|
||
--header 'Content-Type: application/json' \
|
||
--header 'X-API-Key: your_api_key' \
|
||
--data '{
|
||
"name": "qwen-plus",
|
||
"type": "KnowledgeQA",
|
||
"source": "remote",
|
||
"description": "阿里云 Qwen 大模型",
|
||
"parameters": {
|
||
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
|
||
"api_key": "sk-your-dashscope-api-key",
|
||
"provider": "aliyun"
|
||
}
|
||
}'
|
||
```
|
||
|
||
### 创建嵌入模型（Embedding）
|
||
|
||
**本地 Ollama 模型**:
|
||
|
||
```curl
|
||
curl --location 'http://localhost:8080/api/v1/models' \
|
||
--header 'Content-Type: application/json' \
|
||
--header 'X-API-Key: your_api_key' \
|
||
--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
|
||
}
|
||
}
|
||
}'
|
||
```
|
||
|
||
**远程 API 模型（阿里云 DashScope）**:
|
||
|
||
```curl
|
||
curl --location 'http://localhost:8080/api/v1/models' \
|
||
--header 'Content-Type: application/json' \
|
||
--header 'X-API-Key: your_api_key' \
|
||
--data '{
|
||
"name": "text-embedding-v3",
|
||
"type": "Embedding",
|
||
"source": "remote",
|
||
"description": "阿里云通义千问 Embedding 模型",
|
||
"parameters": {
|
||
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
|
||
"api_key": "sk-your-dashscope-api-key",
|
||
"provider": "aliyun",
|
||
"embedding_parameters": {
|
||
"dimension": 1024,
|
||
"truncate_prompt_tokens": 0
|
||
}
|
||
}
|
||
}'
|
||
```
|
||
|
||
**远程 API 模型（Jina AI）**:
|
||
|
||
```curl
|
||
curl --location 'http://localhost:8080/api/v1/models' \
|
||
--header 'Content-Type: application/json' \
|
||
--header 'X-API-Key: your_api_key' \
|
||
--data '{
|
||
"name": "jina-embeddings-v3",
|
||
"type": "Embedding",
|
||
"source": "remote",
|
||
"description": "Jina AI Embedding 模型",
|
||
"parameters": {
|
||
"base_url": "https://api.jina.ai/v1",
|
||
"api_key": "jina_your_api_key",
|
||
"provider": "jina",
|
||
"embedding_parameters": {
|
||
"dimension": 1024,
|
||
"truncate_prompt_tokens": 0
|
||
}
|
||
}
|
||
}'
|
||
```
|
||
|
||
### 创建排序模型（Rerank）
|
||
|
||
**远程 API 模型（阿里云 DashScope）**:
|
||
|
||
```curl
|
||
curl --location 'http://localhost:8080/api/v1/models' \
|
||
--header 'Content-Type: application/json' \
|
||
--header 'X-API-Key: your_api_key' \
|
||
--data '{
|
||
"name": "gte-rerank",
|
||
"type": "Rerank",
|
||
"source": "remote",
|
||
"description": "阿里云 GTE Rerank 模型",
|
||
"parameters": {
|
||
"base_url": "https://dashscope.aliyuncs.com/api/v1/services/rerank/text-rerank/text-rerank",
|
||
"api_key": "sk-your-dashscope-api-key",
|
||
"provider": "aliyun"
|
||
}
|
||
}'
|
||
```
|
||
|
||
**远程 API 模型（Jina AI）**:
|
||
|
||
```curl
|
||
curl --location 'http://localhost:8080/api/v1/models' \
|
||
--header 'Content-Type: application/json' \
|
||
--header 'X-API-Key: your_api_key' \
|
||
--data '{
|
||
"name": "jina-reranker-v2-base-multilingual",
|
||
"type": "Rerank",
|
||
"source": "remote",
|
||
"description": "Jina AI Rerank 模型",
|
||
"parameters": {
|
||
"base_url": "https://api.jina.ai/v1",
|
||
"api_key": "jina_your_api_key",
|
||
"provider": "jina"
|
||
}
|
||
}'
|
||
```
|
||
|
||
### 创建视觉模型（VLLM）
|
||
|
||
```curl
|
||
curl --location 'http://localhost:8080/api/v1/models' \
|
||
--header 'Content-Type: application/json' \
|
||
--header 'X-API-Key: your_api_key' \
|
||
--data '{
|
||
"name": "qwen-vl-plus",
|
||
"type": "VLLM",
|
||
"source": "remote",
|
||
"description": "阿里云通义千问视觉模型",
|
||
"parameters": {
|
||
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
|
||
"api_key": "sk-your-dashscope-api-key",
|
||
"provider": "aliyun"
|
||
}
|
||
}'
|
||
```
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"id": "09c5a1d6-ee8b-4657-9a17-d3dcbd5c70cb",
|
||
"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": false,
|
||
"status": "active",
|
||
"created_at": "2025-08-12T10:39:01.454591766+08:00",
|
||
"updated_at": "2025-08-12T10:39:01.454591766+08:00",
|
||
"deleted_at": null
|
||
}
|
||
}
|
||
```
|
||
|
||
## GET `/models` - 获取模型列表
|
||
|
||
返回当前租户下的所有模型。内置模型（`is_builtin = true`）的 `base_url` 与 `api_key` 会被清空以隐藏敏感信息。
|
||
|
||
**请求**:
|
||
|
||
```curl
|
||
curl --location 'http://localhost:8080/api/v1/models' \
|
||
--header 'Content-Type: application/json' \
|
||
--header 'X-API-Key: your_api_key'
|
||
```
|
||
|
||
**响应**: `data` 为数组，每个元素的字段结构同 `POST /models` 响应。内置模型的 `base_url` 与 `api_key` 字段为空字符串。
|
||
|
||
## GET `/models/:id` - 获取模型详情
|
||
|
||
**路径参数**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| ---- | ------ | ---- | -------- |
|
||
| id | string | 是 | 模型 ID |
|
||
|
||
**请求**:
|
||
|
||
```curl
|
||
curl --location 'http://localhost:8080/api/v1/models/dff7bc94-7885-4dd1-bfd5-bd96e4df2fc3' \
|
||
--header 'Content-Type: application/json' \
|
||
--header 'X-API-Key: your_api_key'
|
||
```
|
||
|
||
**响应**: 字段结构同 `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
|
||
curl --location --request PUT 'http://localhost:8080/api/v1/models/8fdc464d-8eaa-44d4-a85b-094b28af5330' \
|
||
--header 'Content-Type: application/json' \
|
||
--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",
|
||
"api_key": "sk-your-new-api-key",
|
||
"provider": "aliyun"
|
||
}
|
||
}'
|
||
```
|
||
|
||
**响应**: 字段结构同 `POST /models` 响应，返回更新后的完整模型对象。
|
||
|
||
## DELETE `/models/:id` - 删除模型
|
||
|
||
**路径参数**:
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| ---- | ------ | ---- | -------- |
|
||
| id | string | 是 | 模型 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: your_api_key'
|
||
```
|
||
|
||
**响应**:
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "Model deleted"
|
||
}
|
||
```
|
||
|
||
404 表示模型不存在。
|
||
|
||
## 参数说明
|
||
|
||
### ModelType (模型类型)
|
||
|
||
| 值 | 前端别名 | 说明 | 用途 |
|
||
| ----------- | ----------- | ------------ | ------------------------------ |
|
||
| KnowledgeQA | `chat` | 对话模型 | 知识库问答、对话生成 |
|
||
| Embedding | `embedding` | 嵌入模型 | 文本向量化、知识库检索 |
|
||
| Rerank | `rerank` | 排序模型 | 检索结果重排序、相关性优化 |
|
||
| VLLM | `vllm` | 视觉语言模型 | 多模态分析、图文理解 |
|
||
| ASR | `asr` | 语音识别模型 | 音频转写 |
|
||
|
||
> 创建/更新接口请求体的 `type` 字段使用第一列的后端枚举值（如 `KnowledgeQA`）；`GET /models/providers?model_type=` 查询参数使用第二列的前端别名（如 `chat`）。
|
||
|
||
### ModelSource (模型来源)
|
||
|
||
| 值 | 说明 | 配置要求 |
|
||
| -------- | ---------- | -------------------------------- |
|
||
| local | 本地模型 | 需要已安装 Ollama 并拉取模型 |
|
||
| remote | 远程 API | 需要提供 `base_url` 和 `api_key` |
|
||
|
||
### Parameters (模型参数)
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| -------------------- | ----------------- | ---- | ---------------------------------------------------------- |
|
||
| 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 表示不截断） |
|