2026-08-06 10:22:10 +00:00
|
|
|
|
# API 参考:模型与初始化
|
|
|
|
|
|
|
2026-09-08 02:54:41 +00:00
|
|
|
|
管理模型、测试连接、初始化知识库,并发起评估任务。WeKnoraCloud 接口用于相关云服务接入。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
系统信息与系统管理(`/system`、`/system/admin`)接口见[系统与平台管理](./02-api-system.md)。
|
|
|
|
|
|
|
|
|
|
|
|
## 模型(/api/v1/models)
|
|
|
|
|
|
|
|
|
|
|
|
API key:`manage_models` 或 full-access。
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/models/providers
|
|
|
|
|
|
|
2026-09-20 13:28:23 +00:00
|
|
|
|
用途:厂商目录(前端据此动态渲染厂商下拉、图标、额外字段与模型选择)。权限:Viewer+。查询参数:`model_type`(可选:`chat/embedding/rerank/vllm/asr`)。Handler: `internal/handler/model_catalog.go`
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
2026-09-20 13:28:23 +00:00
|
|
|
|
响应:200 `{"success":true,"data":[ModelProviderDTO]}`,每项:
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 说明 |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| `value` / `label` / `labels` / `description` / `descriptions` / `website` | 厂商 id、品牌名、按语言的名称与描述 |
|
|
|
|
|
|
| `icon` | `data:image/svg+xml;base64,...`,可直接用于 `<img src>` |
|
|
|
|
|
|
| `api` / `auth` / `requiresAuth` | 默认协议(`openai-completions` 等)、鉴权方式、是否需要密钥 |
|
|
|
|
|
|
| `defaultUrls` / `modelTypes` | 按模型类型的默认地址与支持的类型 |
|
|
|
|
|
|
| `extraFields` | 厂商额外配置字段定义(`key,label,type,required,default,options,model_types,secret`),值存入 `parameters.extra_config` |
|
|
|
|
|
|
| `models` | 内置模型目录(`id,name,type,api,reasoning,input,context_window,max_output_tokens,dimension,thinking_levels,cost`) |
|
|
|
|
|
|
| `thinking` | 厂商级思考编码摘要(`format`、`levels`) |
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/models/providers?model_type=chat" -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-09-20 13:28:23 +00:00
|
|
|
|
### GET /api/v1/models/catalog/resolve
|
|
|
|
|
|
|
|
|
|
|
|
用途:按厂商、模型名、`base_url` 与 `extra_config` 解析有效接入配置(协议、思考等级、上下文),供模型编辑器实时展示。权限:Viewer+。查询参数:`provider`(必填)、`model`、`base_url`、`model_type`、`api`、`thinking_control`、`remote_model_name`。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{provider,api,base_url,remote_model,cataloged,model,capabilities}}`,其中 `capabilities` 为 `{provider,api,cataloged,reasoning,thinking_levels,thinking_format,input,context_window,max_output_tokens,max_tokens_field}`。同一结构也随对话/视觉模型的 `ModelResponse.capabilities` 返回。
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
### POST /api/v1/models
|
|
|
|
|
|
|
|
|
|
|
|
用途:创建模型。权限:Admin+。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `name` | string | 是(`binding:"required"`) | 模型名 |
|
|
|
|
|
|
| `display_name` | string | 否 | 显示名 |
|
|
|
|
|
|
| `type` | string | 是(`binding:"required"`) | 模型类型 |
|
|
|
|
|
|
| `source` | string | 是(`binding:"required"`) | 来源(local/remote…) |
|
|
|
|
|
|
| `description` | string | 否 | 描述 |
|
|
|
|
|
|
| `parameters` | object | 是(`binding:"required"`) | 连接参数(base_url 等;密钥经 credentials 子资源管理) |
|
|
|
|
|
|
|
|
|
|
|
|
响应:201 `{"success":true,"data":{ModelResponse}}`(`id,name,type,source,parameters,is_default,is_builtin,status,credentials,...`)
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/models -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
|
|
|
|
|
|
-d '{"name":"gpt-4o-mini","type":"chat","source":"remote","parameters":{"base_url":"https://api.openai.com/v1"}}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/models
|
|
|
|
|
|
|
|
|
|
|
|
用途:模型列表。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[ModelResponse]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/models -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/models/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:模型详情。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{ModelResponse}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/models/m-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/models/:id/debug
|
|
|
|
|
|
|
|
|
|
|
|
用途:调试已保存模型(发起真实上游调用,产生费用)。权限:Admin+。form-data 字段:`input`(≤64KB)、`options`(JSON 编码调试选项)、`documents`(JSON 数组,≤100 条)、`file`(可选)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"ok",elapsed_ms,request,raw_response,observations,error}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/models/m-1/debug -H "Authorization: Bearer $TOKEN" -F 'input=你好'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/models/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:更新模型(内置模型由服务层限定 SystemAdmin)。权限:Admin+ 或 SystemAdmin(`AdminOrSystemAdmin`)。请求体:`name`、`display_name`(指针)、`description`、`parameters`(保留已存密钥)、`source`、`type`(均可选)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{ModelResponse}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/models/m-1 -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"display_name":"GPT-4o mini"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### DELETE /api/v1/models/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:删除模型。权限:Admin+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Model deleted"}`
|
|
|
|
|
|
|
2026-09-02 09:20:37 +00:00
|
|
|
|
仍被当前空间的知识库、智能体或长期记忆引用时,响应为 HTTP 400;兼容 message 保留,同时 `error.code=2300`,`error.details` 给出具体对象和引用位置:
|
|
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
|
{
|
|
|
|
|
|
"success": false,
|
|
|
|
|
|
"error": {
|
|
|
|
|
|
"code": 2300,
|
|
|
|
|
|
"message": "model is used by 2 knowledge base(s); reconfigure or remove those references before deleting",
|
|
|
|
|
|
"details": {
|
|
|
|
|
|
"knowledge_bases": [
|
|
|
|
|
|
{"id": "kb-1", "name": "Product docs", "bindings": ["vlm_model"]},
|
|
|
|
|
|
{"id": "kb-2", "name": "Engineering", "bindings": ["vlm_model"]}
|
|
|
|
|
|
],
|
|
|
|
|
|
"agents": [],
|
|
|
|
|
|
"long_term_memory": {"bindings": []},
|
|
|
|
|
|
"knowledge_base_total": 2,
|
|
|
|
|
|
"agent_total": 0
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
}
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-09-14 09:57:49 +00:00
|
|
|
|
知识库绑定值:`embedding_model`、`summary_model`、`image_processing_model`、`vlm_model`、`asr_model`、`wiki_synthesis_model`、`auto_tag_model`;智能体绑定值:`chat_model`、`rerank_model`、`vlm_model`、`asr_model`、`query_understand_model`、`follow_up_model`;长期记忆绑定值:`embedding_model`、`extract_model`。详情包含对象 `id`、`name`、合并后的 `bindings`,以及 `knowledge_base_total` / `agent_total`。列表最多各 50 条,删除守卫以总数为准。
|
2026-09-02 09:20:37 +00:00
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
```bash
|
|
|
|
|
|
curl -X DELETE $BASE/api/v1/models/m-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/models/:id/credentials
|
|
|
|
|
|
|
|
|
|
|
|
用途:设置模型密钥(密钥不经主 PUT 传输)。权限:Admin+ 或 SystemAdmin。Handler: `internal/handler/model_credentials.go`
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `api_key` | *string | 否 | 新 API Key |
|
|
|
|
|
|
| `app_secret` | *string | 否 | 新 App Secret(两者均省略时仅返回状态) |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"fields":{"api_key":{"configured":bool},"app_secret":{"configured":bool}}}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/models/m-1/credentials -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"api_key":"sk-..."}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### DELETE /api/v1/models/:id/credentials/:field
|
|
|
|
|
|
|
|
|
|
|
|
用途:删除某个密钥字段(`api_key` 或 `app_secret`)。权限:Admin+ 或 SystemAdmin。
|
|
|
|
|
|
|
|
|
|
|
|
响应:204 No Content
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X DELETE $BASE/api/v1/models/m-1/credentials/api_key -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## WeKnoraCloud
|
|
|
|
|
|
|
|
|
|
|
|
Handler: `internal/handler/weknoracloud.go`。API key:`manage_models`/full。
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/weknoracloud/credentials
|
|
|
|
|
|
|
|
|
|
|
|
用途:保存 WeKnoraCloud SaaS 凭证。权限:Admin+。请求体:`{"app_id":"...","app_secret":"..."}`(均 `binding:"required"`)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"凭证保存成功"}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/weknoracloud/credentials -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"app_id":"app","app_secret":"secret"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/models/weknoracloud/status
|
|
|
|
|
|
|
|
|
|
|
|
用途:WeKnoraCloud 就绪状态探测。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 服务状态对象。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/models/weknoracloud/status -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 初始化(/api/v1/initialization)
|
|
|
|
|
|
|
|
|
|
|
|
Handler: `internal/handler/initialization.go`。KB 配置类:API key `manage_kbs`(写)/`retrieve`(读);模型检测类:`manage_models`(均可 full-access)。
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/initialization/config/:kbId
|
|
|
|
|
|
|
|
|
|
|
|
用途:读取 KB 当前模型/解析配置。权限:Viewer+,KB read。
|
|
|
|
|
|
|
fix(security): close cross-workspace access paths in shared spaces (#3408)
* fix(security): close cross-workspace access paths in shared spaces
A review of how shared-space (organization) members reach each other's
resources found six paths that bypass the org-share permission model:
- presigned-preview signed any resource handle or storage path, turning a
known resource:// handle into an anonymous /r/ URL that outlives share
revocation. It now requires the path to belong to the caller's tenant,
like /files.
- POST /initialization/initialize let a shared-KB editor rewrite the owner
workspace's models (base URL, API key) in place. Only the KB's own
workspace may call it, and rewriting a stored model needs the same
authority as PUT /models/:id.
- KB JSON carried the legacy inline credentials (storage_config
secret_id/secret_key, which initialization fills with the MinIO env
keys, and vlm_config api_key) to every share receiver. They are withheld
from JSON; their DB columns are unchanged.
- A chat without agent_source_tenant_id resolved shares before the
caller's own agent, so a member sharing a same-ID built-in agent took
over other workspaces' default agent. Own agents now win, built-in
agents can no longer be shared (existing such shares no longer resolve),
and embed channels drop a visitor-supplied source workspace.
- Any org-admin tenant (even a tenant Viewer inside it) could raise another
workspace's KB share to editor/admin, and the route guard was bypassable
via an unrelated :id. Share management is now: the sharer from the source
tenant (Contributor+), source-tenant Admin+, or an org-admin tenant's
Admin+ that may only remove or lower. share_id must belong to :id.
- Wiki write tools were registered for every wiki KB in the search targets,
which only need read access, so a viewer share (e.g. via the built-in
wiki fixer) could edit or delete another workspace's wiki pages. They now
act only on KBs the caller may edit.
* fix(security): close the KB settings path and owner details for share receivers
Follow-up to the shared-space review:
- PUT /initialization/config shares the route guard that admits share
editors, so an editor could still rebind the owner's KB models, chunking
and storage, and storage backends resolved against the caller's workspace
let it bind the owner's KB to its own backend. Another workspace now needs
an admin share (the only share level the frontend offers settings to) and
may not change the storage binding at all.
- GET /initialization/config showed model base URLs and bucket locations to
any admin of the caller's own workspace, including share receivers. They
now only see whether credentials are configured.
- Wiki write tools on the caller's own KBs had no role floor, so a tenant
Viewer (and the IM, embed and MCP endpoint principals that run as Viewer)
could write through an agent what the HTTP routes deny. Writes now need
Contributor+, or the ingest capability for a scoped API key, following
the RBAC rollout switch.
- resolveAgent logs the share lookup error instead of a nil own-agent error
when a shared selector fails.
* fix(security): close the medium shared-space access findings
Follow-up to the high-risk fixes, from the same review:
- Wiki fixer moved into a shared KB's workspace ran with the caller's own
config there: an unset MCP mode registered all of the owner's MCP
services, and an "all" KB scope reached the owner's other KBs. The scoped
run now uses the built-in config pinned to that one KB, without MCP,
skills, sandbox or web search, and falls back to the KB's own model.
- An unset MCP mode means "all" at runtime but is shown as none in the share
scope; shared runs now treat it as none.
- Quick-answer mode used the request's web_search_enabled alone, so a
receiver could turn on search the agent disables and spend the owner's
provider quota. It now requires the agent setting too, as agent mode does.
- summary_model_id picked any model of the workspace a run executes in. It
is ignored for shared agents and the relocated wiki fixer.
- A workspace that left or was removed from an organization kept sharing its
KBs and agents. Its shares are revoked on departure, and share queries and
permission checks require the source workspace's membership and a live
organization, which also covers rows left behind earlier.
- Sharing an agent exposes its KB scope to all members, so a Contributor
could share colleagues' KBs (or "all") through an agent. The sharer must
now be able to share each KB directly (creator or Admin+; "all" needs
Admin+), also when a shared agent's scope is widened later.
- A scoped API key with manage_channels could mint an MCP endpoint token
wider than itself. Endpoints it creates, updates or rotates must stay
within its KB allow-list and capabilities.
- A shared agent's run indexed the receiver's Q&A into the owner's chat
history KB; indexing now uses the session owner's configuration.
- Sharing an agent with skills keeps injecting the owner's skill
environment values (product decision); the share panel now warns that
members can read them. Preview of originals through read-only shares is
kept as designed and documented.
2026-09-18 14:00:02 +00:00
|
|
|
|
模型 `baseUrl` 仅对 KB 所属空间的 Admin+(或 full-access / `manage_tenant_settings` API key)返回。通过组织分享访问的空间只能看到凭证是否已配置(`credentials.*`),看不到来源空间的模型地址和存储桶信息。
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
响应:200 `{"success":true,"data":{"hasFiles",llm,embedding,rerank,multimodal,documentSplitting,nodeExtract,questionGeneration}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/initialization/config/kb-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/initialization/initialize/:kbId
|
|
|
|
|
|
|
|
|
|
|
|
用途:初始化 KB 的模型与解析配置(首次配置向导)。权限:KB 创建者 OR Admin+,KB write。
|
|
|
|
|
|
|
fix(security): close cross-workspace access paths in shared spaces (#3408)
* fix(security): close cross-workspace access paths in shared spaces
A review of how shared-space (organization) members reach each other's
resources found six paths that bypass the org-share permission model:
- presigned-preview signed any resource handle or storage path, turning a
known resource:// handle into an anonymous /r/ URL that outlives share
revocation. It now requires the path to belong to the caller's tenant,
like /files.
- POST /initialization/initialize let a shared-KB editor rewrite the owner
workspace's models (base URL, API key) in place. Only the KB's own
workspace may call it, and rewriting a stored model needs the same
authority as PUT /models/:id.
- KB JSON carried the legacy inline credentials (storage_config
secret_id/secret_key, which initialization fills with the MinIO env
keys, and vlm_config api_key) to every share receiver. They are withheld
from JSON; their DB columns are unchanged.
- A chat without agent_source_tenant_id resolved shares before the
caller's own agent, so a member sharing a same-ID built-in agent took
over other workspaces' default agent. Own agents now win, built-in
agents can no longer be shared (existing such shares no longer resolve),
and embed channels drop a visitor-supplied source workspace.
- Any org-admin tenant (even a tenant Viewer inside it) could raise another
workspace's KB share to editor/admin, and the route guard was bypassable
via an unrelated :id. Share management is now: the sharer from the source
tenant (Contributor+), source-tenant Admin+, or an org-admin tenant's
Admin+ that may only remove or lower. share_id must belong to :id.
- Wiki write tools were registered for every wiki KB in the search targets,
which only need read access, so a viewer share (e.g. via the built-in
wiki fixer) could edit or delete another workspace's wiki pages. They now
act only on KBs the caller may edit.
* fix(security): close the KB settings path and owner details for share receivers
Follow-up to the shared-space review:
- PUT /initialization/config shares the route guard that admits share
editors, so an editor could still rebind the owner's KB models, chunking
and storage, and storage backends resolved against the caller's workspace
let it bind the owner's KB to its own backend. Another workspace now needs
an admin share (the only share level the frontend offers settings to) and
may not change the storage binding at all.
- GET /initialization/config showed model base URLs and bucket locations to
any admin of the caller's own workspace, including share receivers. They
now only see whether credentials are configured.
- Wiki write tools on the caller's own KBs had no role floor, so a tenant
Viewer (and the IM, embed and MCP endpoint principals that run as Viewer)
could write through an agent what the HTTP routes deny. Writes now need
Contributor+, or the ingest capability for a scoped API key, following
the RBAC rollout switch.
- resolveAgent logs the share lookup error instead of a nil own-agent error
when a shared selector fails.
* fix(security): close the medium shared-space access findings
Follow-up to the high-risk fixes, from the same review:
- Wiki fixer moved into a shared KB's workspace ran with the caller's own
config there: an unset MCP mode registered all of the owner's MCP
services, and an "all" KB scope reached the owner's other KBs. The scoped
run now uses the built-in config pinned to that one KB, without MCP,
skills, sandbox or web search, and falls back to the KB's own model.
- An unset MCP mode means "all" at runtime but is shown as none in the share
scope; shared runs now treat it as none.
- Quick-answer mode used the request's web_search_enabled alone, so a
receiver could turn on search the agent disables and spend the owner's
provider quota. It now requires the agent setting too, as agent mode does.
- summary_model_id picked any model of the workspace a run executes in. It
is ignored for shared agents and the relocated wiki fixer.
- A workspace that left or was removed from an organization kept sharing its
KBs and agents. Its shares are revoked on departure, and share queries and
permission checks require the source workspace's membership and a live
organization, which also covers rows left behind earlier.
- Sharing an agent exposes its KB scope to all members, so a Contributor
could share colleagues' KBs (or "all") through an agent. The sharer must
now be able to share each KB directly (creator or Admin+; "all" needs
Admin+), also when a shared agent's scope is widened later.
- A scoped API key with manage_channels could mint an MCP endpoint token
wider than itself. Endpoints it creates, updates or rotates must stay
within its KB allow-list and capabilities.
- A shared agent's run indexed the receiver's Q&A into the owner's chat
history KB; indexing now uses the session owner's configuration.
- Sharing an agent with skills keeps injecting the owner's skill
environment values (product decision); the share panel now warns that
members can read them. Preview of originals through read-only shares is
kept as designed and documented.
2026-09-18 14:00:02 +00:00
|
|
|
|
只有 KB 所属空间可以调用;通过组织分享获得编辑权限的空间会被拒绝(403)。KB 已绑定模型时,该接口会原地更新这些模型的配置,这一步需要与 `PUT /models/:id` 相同的权限(Admin+,或拥有 `manage_models` 能力的 API key),否则 403。
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
主要字段(`InitializationRequest`):
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `llm.source` / `llm.modelName` | string | 是 | LLM 来源与模型名 |
|
|
|
|
|
|
| `llm.baseUrl` / `llm.apiKey` | string | 否 | 连接参数 |
|
|
|
|
|
|
| `embedding.source` / `embedding.modelName` | string | 是 | Embedding 模型 |
|
|
|
|
|
|
| `embedding.baseUrl` / `embedding.apiKey` / `embedding.dimension` | — | 否 | 连接与维度 |
|
|
|
|
|
|
| `rerank.enabled` + `rerank.modelName/baseUrl/apiKey` | — | 否 | Rerank 配置 |
|
|
|
|
|
|
| `multimodal.enabled` + `multimodal.vlm.*` + `multimodal.storageType` + `multimodal.cos.*|minio.*` | — | 否 | 多模态与图床 |
|
|
|
|
|
|
| `documentSplitting.chunkSize` / `separators` | int / []string | 是 | 分块配置 |
|
|
|
|
|
|
| `documentSplitting.chunkOverlap` | int | 否 | 重叠 |
|
|
|
|
|
|
| `nodeExtract.*` | — | 否 | 图谱抽取(enabled/text/tags/nodes/relations) |
|
|
|
|
|
|
| `questionGeneration.*` | — | 否 | 问题生成(enabled/questionCount) |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"知识库配置更新成功","data":{"models":[Model],"knowledge_base":{KnowledgeBase}}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/initialization/initialize/kb-1 -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' \
|
|
|
|
|
|
-d '{"llm":{"source":"remote","modelName":"gpt-4o-mini"},"embedding":{"source":"remote","modelName":"text-embedding-3-small"},"documentSplitting":{"chunkSize":512,"separators":["\n\n"]}}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/initialization/config/:kbId
|
|
|
|
|
|
|
|
|
|
|
|
用途:更新 KB 模型/分块配置(`KBModelConfigRequest`:`llmModelId` 必填,`embeddingModelId`、`vlm_config`、`asr_config`、`documentSplitting.*`、`multimodal.enabled`、`storageProvider`、`storageBackendId`、`nodeExtract.*`、`questionGeneration.*` 可选)。权限:KB 创建者 OR Admin+,KB write。
|
|
|
|
|
|
|
fix(security): close cross-workspace access paths in shared spaces (#3408)
* fix(security): close cross-workspace access paths in shared spaces
A review of how shared-space (organization) members reach each other's
resources found six paths that bypass the org-share permission model:
- presigned-preview signed any resource handle or storage path, turning a
known resource:// handle into an anonymous /r/ URL that outlives share
revocation. It now requires the path to belong to the caller's tenant,
like /files.
- POST /initialization/initialize let a shared-KB editor rewrite the owner
workspace's models (base URL, API key) in place. Only the KB's own
workspace may call it, and rewriting a stored model needs the same
authority as PUT /models/:id.
- KB JSON carried the legacy inline credentials (storage_config
secret_id/secret_key, which initialization fills with the MinIO env
keys, and vlm_config api_key) to every share receiver. They are withheld
from JSON; their DB columns are unchanged.
- A chat without agent_source_tenant_id resolved shares before the
caller's own agent, so a member sharing a same-ID built-in agent took
over other workspaces' default agent. Own agents now win, built-in
agents can no longer be shared (existing such shares no longer resolve),
and embed channels drop a visitor-supplied source workspace.
- Any org-admin tenant (even a tenant Viewer inside it) could raise another
workspace's KB share to editor/admin, and the route guard was bypassable
via an unrelated :id. Share management is now: the sharer from the source
tenant (Contributor+), source-tenant Admin+, or an org-admin tenant's
Admin+ that may only remove or lower. share_id must belong to :id.
- Wiki write tools were registered for every wiki KB in the search targets,
which only need read access, so a viewer share (e.g. via the built-in
wiki fixer) could edit or delete another workspace's wiki pages. They now
act only on KBs the caller may edit.
* fix(security): close the KB settings path and owner details for share receivers
Follow-up to the shared-space review:
- PUT /initialization/config shares the route guard that admits share
editors, so an editor could still rebind the owner's KB models, chunking
and storage, and storage backends resolved against the caller's workspace
let it bind the owner's KB to its own backend. Another workspace now needs
an admin share (the only share level the frontend offers settings to) and
may not change the storage binding at all.
- GET /initialization/config showed model base URLs and bucket locations to
any admin of the caller's own workspace, including share receivers. They
now only see whether credentials are configured.
- Wiki write tools on the caller's own KBs had no role floor, so a tenant
Viewer (and the IM, embed and MCP endpoint principals that run as Viewer)
could write through an agent what the HTTP routes deny. Writes now need
Contributor+, or the ingest capability for a scoped API key, following
the RBAC rollout switch.
- resolveAgent logs the share lookup error instead of a nil own-agent error
when a shared selector fails.
* fix(security): close the medium shared-space access findings
Follow-up to the high-risk fixes, from the same review:
- Wiki fixer moved into a shared KB's workspace ran with the caller's own
config there: an unset MCP mode registered all of the owner's MCP
services, and an "all" KB scope reached the owner's other KBs. The scoped
run now uses the built-in config pinned to that one KB, without MCP,
skills, sandbox or web search, and falls back to the KB's own model.
- An unset MCP mode means "all" at runtime but is shown as none in the share
scope; shared runs now treat it as none.
- Quick-answer mode used the request's web_search_enabled alone, so a
receiver could turn on search the agent disables and spend the owner's
provider quota. It now requires the agent setting too, as agent mode does.
- summary_model_id picked any model of the workspace a run executes in. It
is ignored for shared agents and the relocated wiki fixer.
- A workspace that left or was removed from an organization kept sharing its
KBs and agents. Its shares are revoked on departure, and share queries and
permission checks require the source workspace's membership and a live
organization, which also covers rows left behind earlier.
- Sharing an agent exposes its KB scope to all members, so a Contributor
could share colleagues' KBs (or "all") through an agent. The sharer must
now be able to share each KB directly (creator or Admin+; "all" needs
Admin+), also when a shared agent's scope is widened later.
- A scoped API key with manage_channels could mint an MCP endpoint token
wider than itself. Endpoints it creates, updates or rotates must stay
within its KB allow-list and capabilities.
- A shared agent's run indexed the receiver's Q&A into the owner's chat
history KB; indexing now uses the session owner's configuration.
- Sharing an agent with skills keeps injecting the owner's skill
environment values (product decision); the share panel now warns that
members can read them. Preview of originals through read-only shares is
kept as designed and documented.
2026-09-18 14:00:02 +00:00
|
|
|
|
通过组织分享访问时,需要有效分享权限为 admin;editor 只能编辑内容,不能改设置(403)。存储绑定(`storageBackendId` / `storageProvider`)只有 KB 所属空间可以修改,其他空间提交与当前不同的值会返回 403。
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
响应:200 `{"success":true,"message":"配置更新成功"}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/initialization/config/kb-1 -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"llmModelId":"m-1","embeddingModelId":"m-2"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/initialization/ollama/status
|
|
|
|
|
|
|
|
|
|
|
|
用途:Ollama 可用性探测。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"available","version","baseUrl","error"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/initialization/ollama/status -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/initialization/ollama/models
|
|
|
|
|
|
|
|
|
|
|
|
用途:列出本地 Ollama 模型。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"models":[...]}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/initialization/ollama/models -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/initialization/ollama/models/check
|
|
|
|
|
|
|
|
|
|
|
|
用途:批量检查模型是否已存在。权限:Admin+。请求体:`{"models":["llama3"]}`(`binding:"required"`)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"models":{"llama3":true}}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/initialization/ollama/models/check -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"models":["llama3"]}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/initialization/ollama/models/download
|
|
|
|
|
|
|
|
|
|
|
|
用途:拉取 Ollama 模型(异步任务)。权限:Admin+。请求体:`{"modelName":"llama3"}`(`binding:"required"`)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"taskId","modelName","status","progress"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/initialization/ollama/models/download -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"modelName":"llama3"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/initialization/ollama/download/progress/:taskId
|
|
|
|
|
|
|
|
|
|
|
|
用途:下载任务进度。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{id,modelName,status,progress,message,startTime,endTime}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/initialization/ollama/download/progress/task-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/initialization/ollama/download/tasks
|
|
|
|
|
|
|
|
|
|
|
|
用途:全部下载任务列表。权限:Viewer+。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[DownloadTask]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/initialization/ollama/download/tasks -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### 模型连通性检测(均 POST,权限 Admin+)
|
|
|
|
|
|
|
|
|
|
|
|
请求体统一为 `ModelTestRequest`:
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `source` | string | 否 | 默认 `remote` |
|
|
|
|
|
|
| `modelName` | string | 是 | 模型名 |
|
|
|
|
|
|
| `baseUrl` / `apiKey` / `appSecret` | string | 否 | 连接参数 |
|
|
|
|
|
|
| `provider` / `interfaceType` | string | 否 | 厂商/接口类型 |
|
|
|
|
|
|
| `dimension` | int | 否 | embedding 维度 |
|
|
|
|
|
|
| `customHeaders` / `extraConfig` | map | 否 | 扩展 |
|
|
|
|
|
|
| `modelId` | string | 否 | 从已存模型取密钥 |
|
|
|
|
|
|
|
|
|
|
|
|
| 端点 | 用途 | 响应 data |
|
|
|
|
|
|
| --- | --- | --- |
|
|
|
|
|
|
| `POST /api/v1/initialization/remote/check` | LLM 远程连通性 | `{available,message}` |
|
|
|
|
|
|
| `POST /api/v1/initialization/embedding/test` | Embedding 测试 | `{available,message,dimension}` |
|
|
|
|
|
|
| `POST /api/v1/initialization/rerank/check` | Rerank 测试 | `{available,message}` |
|
|
|
|
|
|
| `POST /api/v1/initialization/asr/check` | ASR 测试 | `{available,message}` |
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/initialization/remote/check -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"modelName":"gpt-4o-mini","baseUrl":"https://api.openai.com/v1","apiKey":"sk-..."}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/initialization/multimodal/test
|
|
|
|
|
|
|
|
|
|
|
|
用途:多模态(VLM+图床)端到端测试。权限:Admin+。multipart 字段:`image`(必填)、`vlm_model`、`vlm_base_url`(必填)、`vlm_api_key`、`vlm_interface_type`、`storage_type`(`cos|minio`,必填)及对应 `cos_*`/`minio_*` 字段、`chunk_size`、`chunk_overlap`、`separators`。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"success","caption","ocr","processing_time"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/initialization/multimodal/test -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-F 'image=@demo.png' -F 'vlm_model=qwen-vl' -F 'vlm_base_url=http://x' -F 'storage_type=minio'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/initialization/extract/text-relation
|
|
|
|
|
|
|
|
|
|
|
|
用途:文本图谱抽取测试。权限:Admin+。请求体:`text`(必填,≤5000 字符)、`tags`(必填,至少一个)、`model_id`(必填)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"nodes":[GraphNode],"relations":[GraphRelation]}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/initialization/extract/text-relation -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"text":"小明在腾讯工作","tags":["人物","公司"],"model_id":"m-1"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/initialization/extract/fabri-tag
|
|
|
|
|
|
|
|
|
|
|
|
用途:生成示例标签。权限:Admin+。无请求体。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"tags":[...]}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/initialization/extract/fabri-tag -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/initialization/extract/fabri-text
|
|
|
|
|
|
|
|
|
|
|
|
用途:按标签生成示例文本。权限:Admin+。请求体:`{"tags":[...],"model_id":"m-1"}`(model_id 必填)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"text":"..."}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/initialization/extract/fabri-text -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"model_id":"m-1","tags":["人物"]}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 评估(/api/v1/evaluation)
|
|
|
|
|
|
|
|
|
|
|
|
Handler: `internal/handler/evaluation.go`。API key:`run_evaluations`/full。
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/evaluation
|
|
|
|
|
|
|
|
|
|
|
|
用途:发起评估任务(驱动 LLM 调用,产生费用)。权限:Admin+。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `dataset_id` | string | 否 | 数据集 ID |
|
|
|
|
|
|
| `knowledge_base_id` | string | 否 | 目标 KB |
|
|
|
|
|
|
| `chat_id` | string | 否 | 对话模型 ID |
|
|
|
|
|
|
| `rerank_id` | string | 否 | Rerank 模型 ID |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{评估任务}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/evaluation -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"knowledge_base_id":"kb-1","chat_id":"m-1"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/evaluation
|
|
|
|
|
|
|
|
|
|
|
|
用途:查询评估结果。权限:Viewer+。查询参数:`task_id`(必填)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{评估结果}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/evaluation?task_id=task-1" -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
2026-09-08 02:54:41 +00:00
|
|
|
|
|
|
|
|
|
|
## 实现参考
|
|
|
|
|
|
|
|
|
|
|
|
路由注册:`internal/router/router.go` 的 `RegisterModelRoutes`、`RegisterInitializationRoutes`、`RegisterEvaluationRoutes`、`RegisterWeKnoraCloudRoutes`。Handler:`internal/handler/model.go`、`internal/handler/model_credentials.go`、`internal/handler/initialization.go`、`internal/handler/evaluation.go`、`internal/handler/weknoracloud.go`。
|