2026-08-06 10:22:10 +00:00
|
|
|
|
# API 参考:知识库与知识
|
|
|
|
|
|
|
2026-09-08 02:54:41 +00:00
|
|
|
|
创建知识库,导入与管理文档,并查询处理进度、复制或移动内容。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
权限速记:读路由为 Viewer+ 且需对 KB 有 read 权限(自有/组织共享/共享 Agent 可见);写路由为“KB 创建者 OR Admin+”且需 write 权限。API key:读需 `retrieve`,内容写需 `ingest`,KB 生命周期需 `manage_kbs`(均可被 full-access 覆盖),并受 KB 白名单约束。
|
|
|
|
|
|
|
|
|
|
|
|
分块、标签与分块预览接口(`/chunks`、`/knowledge-bases/:id/tags`、`/chunker/preview`)在[分块与标签](./02-api-chunks.md)。
|
|
|
|
|
|
|
|
|
|
|
|
## 知识库(/api/v1/knowledge-bases)
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases
|
|
|
|
|
|
|
|
|
|
|
|
用途:创建知识库。权限:Contributor+;API key `manage_kbs`/full。Handler: `internal/handler/knowledgebase.go`
|
|
|
|
|
|
|
|
|
|
|
|
请求体(`types.KnowledgeBase`):
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `name` | string | 是 | 名称 |
|
|
|
|
|
|
| `description` | string | 否 | 描述 |
|
|
|
|
|
|
| `type` | string | 否 | `document`(默认)/`faq`/`wiki` |
|
|
|
|
|
|
| `embedding_model_id` | string | 否 | Embedding 模型 ID |
|
|
|
|
|
|
| `chunking_config` | object | 否 | 分块配置(chunk_size/overlap/separators/strategy…) |
|
|
|
|
|
|
| `image_processing_config` | object | 否 | 图像处理(多模态)配置 |
|
|
|
|
|
|
| `storage_provider_config` | object | 否 | 存储配置 |
|
|
|
|
|
|
| `vector_store_id` | string | 否 | 向量库绑定(非法返回 code 2200/2201) |
|
|
|
|
|
|
| `faq_config` / `wiki_config` / `extract_config` / `indexing_strategy` | object | 否 | 类型相关配置 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:201 `{"success":true,"data":{KnowledgeBase}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"name":"产品文档","type":"document"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-09-08 02:54:41 +00:00
|
|
|
|
### 文档自动标签配置
|
|
|
|
|
|
|
feat(knowledge): derive knowledge base descriptions from document profiles (#3370)
* feat(knowledge): derive knowledge base descriptions from document profiles
Knowledge bases only had a hand-written description, which most users
leave empty, so agents bound to several knowledge bases had nothing to
route on and searched all of them. This adds a generated description
that is derived from per-document data instead of maintained by a model.
Document profile: the summary call now returns JSON with a 2-3 sentence
summary plus a gist, 3-5 topic keywords, a document type and one
typical question (knowledges.profile). Input is capped at 8k chars and
output at 1024 tokens; plain-text replies from custom templates still
work and simply carry no profile. The summary chunk embeds the gist and
short summary.
Knowledge base aggregate: a database-only fold over those rows (counts
per file type, tag, normalized topic and doc type; stratified samples of
titles and questions; a hash of the inputs). Deleting, moving or
re-parsing a document changes nothing but the rows, so the next rebuild
is exact without any model judgement.
Description text: one small model call over the aggregate yields a
gist, merged topics and typical questions (knowledge_bases.
generated_profile). The call is skipped when the aggregate hash is
unchanged; failures keep the previous text and record the error; an
empty knowledge base clears it. The manual description is never
touched, and the agent runtime context renders both so the model can
pass knowledge_base_ids instead of fanning out.
Refreshes are requested from summary task exit, post-process completion,
deletion, cross-KB moves and enabling the option, debounced per
knowledge base in 30 s windows via kb:profile on the summary queue.
POST /knowledge-bases/:id/profile/generate regenerates synchronously.
profile_config (enabled, model_id, custom_instructions) opts a document
knowledge base in; the settings dialog shows the generated card with
regenerate and adopt-as-description actions in five locales. Search
results now log hits per chunk type so the value of indexing summary
chunks can be measured.
Migrations 000101 (PostgreSQL) and 000021 (SQLite) add the columns; the
SQLite schema test expects the new version and columns.
* fix(knowledge): keep generated descriptions out of duplicates and refresh clones
DuplicateKnowledgeBase copies the source row through JSON, which carried
generated_profile onto a knowledge base that has no documents yet, so
an empty duplicate advertised the source's topics. The duplicate now
starts without a generated description and keeps profile_config so it
derives its own once documents arrive.
CopyKnowledgeBase builds the target field by field and skipped
profile_config, and the clone task never asked for a description after
copying the documents, so a clone stayed undescribed until its next
upload. The target now carries a copy of profile_config and both clone
paths request a refresh on completion.
* fix(knowledge): refresh the loaded clone target and carry document profiles
ProcessKBClone requested the description refresh with the reservation
stub it builds before CopyKnowledgeBase runs. For the main create path
that stub has neither a type nor profile_config, so the refresh helper
rejected it and nothing was enqueued. The refresh now uses the loaded
target returned by CopyKnowledgeBase.
cloneKnowledge copied the summary text but not the structured profile,
so even a scheduled refresh would have aggregated titles without topics
until every clone was re-summarized. Cloned documents now carry an
independent copy of the profile.
2026-09-17 14:21:55 +00:00
|
|
|
|
创建知识库时 `auto_tag_config`、`profile_config` 位于顶层;更新时放在 `config.auto_tag_config`、`config.profile_config`。两者仅 document 知识库支持,默认 enabled=false。`profile_config` 开启后,文档新增/删除/摘要更新会自动刷新 `generated_profile`(AI 知识库描述,见下文 `profile/generate`)。
|
2026-09-08 02:54:41 +00:00
|
|
|
|
|
|
|
|
|
|
| 字段 | 默认 | 说明 |
|
|
|
|
|
|
| --- | --- | --- |
|
|
|
|
|
|
| enabled | false | 解析后异步从已有标签中选择 |
|
|
|
|
|
|
| model_id | 空 | 回退知识库 summary_model_id |
|
|
|
|
|
|
| max_tags | 3 | 最多 10 个 |
|
|
|
|
|
|
| skip_if_tagged | true | 已有标签则跳过;false 允许补充标签 |
|
|
|
|
|
|
|
|
|
|
|
|
开启后对新解析/重新解析的文档生效,不自动扫描全部旧文档。无候选标签或无可用模型时不阻断入库。更新示例:
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT "$BASE/api/v1/knowledge-bases/kb-1" \
|
|
|
|
|
|
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
|
|
|
|
|
|
-d '{"name":"产品文档","config":{"auto_tag_config":{"enabled":true,"max_tags":3,"skip_if_tagged":true}}}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
### GET /api/v1/knowledge-bases
|
|
|
|
|
|
|
|
|
|
|
|
用途:知识库列表。权限:Viewer+;API key `retrieve`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `agent_id` | string | 否 | 过滤某共享 Agent 可见的 KB |
|
|
|
|
|
|
| `agent_source_tenant_id` | uint64 | 否 | 同名 Agent 被多个空间共享时,指定来源空间;取值会与共享关系校验,非法值直接 400 |
|
|
|
|
|
|
| `creator` | string | 否 | `mine` / `others` |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[KnowledgeBase],"total","page","page_size"}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge-bases -H "X-API-Key: $API_KEY"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge-bases/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:知识库详情(共享 KB 携带 `my_permission`)。权限:Viewer+,KB read。查询参数:`agent_id`(可选)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{KnowledgeBase}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge-bases/kb-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge-bases/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:更新知识库。权限:创建者 OR Admin+,KB write;API key `manage_kbs`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `name` | string | 是(`binding:"required"`) | 名称 |
|
|
|
|
|
|
| `description` | string | 否 | 描述 |
|
|
|
|
|
|
| `config` | object | 否 | 局部配置更新(分块/图像/wiki/索引策略) |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{KnowledgeBase}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1 -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"name":"产品文档 v2"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### DELETE /api/v1/knowledge-bases/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:删除知识库(锁定为属主空间 + Admin;共享 editor 不可删)。权限:创建者 OR Admin+,KB write;API key `manage_kbs`/full。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Knowledge base deleted successfully"}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X DELETE $BASE/api/v1/knowledge-bases/kb-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge-bases/:id/pin
|
|
|
|
|
|
|
|
|
|
|
|
用途:置顶/取消置顶(按用户维度存储)。权限:Viewer+,KB read。无请求体。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{KnowledgeBase(is_pinned 已切换)}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/pin -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases/:id/hybrid-search(兼容 GET)
|
|
|
|
|
|
|
|
|
|
|
|
用途:KB 内混合检索(向量+关键词)。权限:Viewer+,KB read;API key `retrieve`/full。GET 携带 JSON body 仅为向后兼容(#1727),推荐 POST。
|
|
|
|
|
|
|
2026-08-26 09:31:05 +00:00
|
|
|
|
查询参数:`resource_urls=handle|public`(`public` 把结果 `content` / `image_info` 里的 `resource://` 换成可加载直链,详见 [API 总览](./01-api-overview.md))。
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
请求体(`types.SearchParams`):
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `query_text` | string | 条件必填 | 查询文本(除非提供 `query_embedding`) |
|
|
|
|
|
|
| `query_embedding` | []float32 | 否 | 预计算向量 |
|
|
|
|
|
|
| `vector_threshold` / `keyword_threshold` | float64 | 否 | 匹配阈值 |
|
|
|
|
|
|
| `match_count` | int | 否 | 返回条数上限 |
|
|
|
|
|
|
| `disable_keywords_match` / `disable_vector_match` | bool | 否 | 关闭某一路召回 |
|
|
|
|
|
|
| `knowledge_ids` | []string | 否 | 限定知识条目 |
|
|
|
|
|
|
| `tag_ids` | []string | 否 | 标签过滤(OR) |
|
|
|
|
|
|
| `only_recommended` | bool | 否 | FAQ 仅推荐条目 |
|
|
|
|
|
|
| `skip_context_enrichment` | bool | 否 | 跳过父块/上下文补齐 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[SearchResult]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-08-26 09:31:05 +00:00
|
|
|
|
curl -X POST "$BASE/api/v1/knowledge-bases/kb-1/hybrid-search?resource_urls=public" -H "X-API-Key: $API_KEY" \
|
2026-08-06 10:22:10 +00:00
|
|
|
|
-H 'Content-Type: application/json' -d '{"query_text":"退款流程","match_count":5}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases/copy
|
|
|
|
|
|
|
|
|
|
|
|
用途:跨 KB 拷贝内容(异步任务)。权限:Contributor+;API key `manage_kbs`/full(源/目标 KB 白名单在 handler 校验)。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `source_id` | string | 是(`binding:"required"`) | 源 KB |
|
|
|
|
|
|
| `target_id` | string | 否 | 目标 KB(为空则自动创建) |
|
|
|
|
|
|
| `task_id` | string | 否 | 自定义任务 ID |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"task_id","source_id","target_id","message"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases/copy -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"source_id":"kb-1"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases/:id/duplicate
|
|
|
|
|
|
|
|
|
|
|
|
用途:创建 KB 副本(仅复制设置,不复制内容/索引/分享)。权限:Contributor+,源 KB read;API key `manage_kbs`/full。无请求体。
|
|
|
|
|
|
|
|
|
|
|
|
响应:201 `{"success":true,"data":{"source_id","target_id","message","knowledge_base":{...}}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/duplicate -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
feat(knowledge): derive knowledge base descriptions from document profiles (#3370)
* feat(knowledge): derive knowledge base descriptions from document profiles
Knowledge bases only had a hand-written description, which most users
leave empty, so agents bound to several knowledge bases had nothing to
route on and searched all of them. This adds a generated description
that is derived from per-document data instead of maintained by a model.
Document profile: the summary call now returns JSON with a 2-3 sentence
summary plus a gist, 3-5 topic keywords, a document type and one
typical question (knowledges.profile). Input is capped at 8k chars and
output at 1024 tokens; plain-text replies from custom templates still
work and simply carry no profile. The summary chunk embeds the gist and
short summary.
Knowledge base aggregate: a database-only fold over those rows (counts
per file type, tag, normalized topic and doc type; stratified samples of
titles and questions; a hash of the inputs). Deleting, moving or
re-parsing a document changes nothing but the rows, so the next rebuild
is exact without any model judgement.
Description text: one small model call over the aggregate yields a
gist, merged topics and typical questions (knowledge_bases.
generated_profile). The call is skipped when the aggregate hash is
unchanged; failures keep the previous text and record the error; an
empty knowledge base clears it. The manual description is never
touched, and the agent runtime context renders both so the model can
pass knowledge_base_ids instead of fanning out.
Refreshes are requested from summary task exit, post-process completion,
deletion, cross-KB moves and enabling the option, debounced per
knowledge base in 30 s windows via kb:profile on the summary queue.
POST /knowledge-bases/:id/profile/generate regenerates synchronously.
profile_config (enabled, model_id, custom_instructions) opts a document
knowledge base in; the settings dialog shows the generated card with
regenerate and adopt-as-description actions in five locales. Search
results now log hits per chunk type so the value of indexing summary
chunks can be measured.
Migrations 000101 (PostgreSQL) and 000021 (SQLite) add the columns; the
SQLite schema test expects the new version and columns.
* fix(knowledge): keep generated descriptions out of duplicates and refresh clones
DuplicateKnowledgeBase copies the source row through JSON, which carried
generated_profile onto a knowledge base that has no documents yet, so
an empty duplicate advertised the source's topics. The duplicate now
starts without a generated description and keeps profile_config so it
derives its own once documents arrive.
CopyKnowledgeBase builds the target field by field and skipped
profile_config, and the clone task never asked for a description after
copying the documents, so a clone stayed undescribed until its next
upload. The target now carries a copy of profile_config and both clone
paths request a refresh on completion.
* fix(knowledge): refresh the loaded clone target and carry document profiles
ProcessKBClone requested the description refresh with the reservation
stub it builds before CopyKnowledgeBase runs. For the main create path
that stub has neither a type nor profile_config, so the refresh helper
rejected it and nothing was enqueued. The refresh now uses the loaded
target returned by CopyKnowledgeBase.
cloneKnowledge copied the summary text but not the structured profile,
so even a scheduled refresh would have aggregated titles without topics
until every clone was re-summarized. Cloned documents now carry an
independent copy of the profile.
2026-09-17 14:21:55 +00:00
|
|
|
|
### POST /api/v1/knowledge-bases/:id/profile/generate
|
|
|
|
|
|
|
|
|
|
|
|
用途:立即重新生成知识库的 AI 描述(`generated_profile`),同步执行一次文档画像聚合和一次小模型调用,不修改手写 `description`。权限:与更新知识库相同(创建者/Admin 且 KB write);API key `manage_kbs`/full。无请求体。仅 document 类型;未配置模型返回 400。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"gist","topics":[...],"typical_questions":[...],"stats":{"document_count",...},"status":"ready","model_id","generated_at"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/profile/generate -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
2026-08-06 10:22:10 +00:00
|
|
|
|
### GET /api/v1/knowledge-bases/copy/progress/:task_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:查询拷贝进度(任务按空间隔离)。权限:Viewer+;API key `retrieve`/`manage_kbs`/full。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{status,progress,message,...}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge-bases/copy/progress/task-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge-bases/:id/move-targets
|
|
|
|
|
|
|
|
|
|
|
|
用途:列出可作为移动目标的 KB(同类型/同 embedding)。权限:Viewer+,KB read。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[KnowledgeBase]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge-bases/kb-1/move-targets -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge-bases/:id/files
|
|
|
|
|
|
|
|
|
|
|
|
用途:KB 范围文件代理(渲染共享 KB 内容中的图片;上下文 tenant 已被重写为 KB 属主)。权限:Viewer+,KB read;KB 受限 key 拒绝,全空间 `retrieve`/full key 放行。注册于 `serveKBScopedFiles`(`internal/router/router.go`)。
|
|
|
|
|
|
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `file_path` | string | 是 | `provider://...` 存储路径(禁止 `..`) |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 文件流(`Content-Type` 按扩展名推断;`Cache-Control: private`)。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/knowledge-bases/kb-1/files?file_path=local://1/exports/chart.png" \
|
|
|
|
|
|
-H "Authorization: Bearer $TOKEN" -o chart.png
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 知识(KB 内容,/api/v1/knowledge-bases/:id/knowledge 与 /api/v1/knowledge)
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases/:id/knowledge/file
|
|
|
|
|
|
|
|
|
|
|
|
用途:上传文件创建知识。权限:KB 创建者 OR Admin+,KB write;API key `ingest`/full。Handler: `internal/handler/knowledge.go`
|
|
|
|
|
|
|
|
|
|
|
|
multipart/form-data 字段:
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `file` | file | 是 | 上传文件 |
|
|
|
|
|
|
| `fileName` | string | 否 | 覆盖显示名 |
|
|
|
|
|
|
| `metadata` | JSON 字符串 | 否 | 自定义元数据 |
|
|
|
|
|
|
| `enable_multimodel` | bool | 否 | 多模态处理开关 |
|
|
|
|
|
|
| `tag_ids` | string | 否 | 逗号分隔标签 ID |
|
|
|
|
|
|
| `channel` | string | 否 | 摄取渠道 |
|
|
|
|
|
|
| `process_config` | JSON 字符串 | 否 | 解析配置覆盖(KnowledgeProcessOverrides) |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{Knowledge}}`;重复文件返回 409 且 `data` 为已存在的 Knowledge。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/file \
|
|
|
|
|
|
-H "X-API-Key: $API_KEY" -F 'file=@./manual.pdf' -F 'enable_multimodel=true'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases/:id/knowledge/url
|
|
|
|
|
|
|
|
|
|
|
|
用途:从 URL 抓取创建知识。权限/API key 同上。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `url` | string | 是(`binding:"required"`) | 抓取地址 |
|
|
|
|
|
|
| `file_name` / `file_type` / `title` | string | 否 | 覆盖信息 |
|
|
|
|
|
|
| `enable_multimodel` | *bool | 否 | 多模态开关 |
|
|
|
|
|
|
| `tag_ids` | []string | 否 | 标签 |
|
|
|
|
|
|
| `channel` | string | 否 | 渠道 |
|
|
|
|
|
|
| `process_config` | object | 否 | 解析覆盖 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:201 `{"success":true,"data":{Knowledge}}`;重复 URL 返回 409。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/url -H "X-API-Key: $API_KEY" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"url":"https://example.com/doc"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge-bases/:id/knowledge/manual
|
|
|
|
|
|
|
|
|
|
|
|
用途:创建手工(Markdown)知识。权限/API key 同上。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `title` | string | 否 | 标题 |
|
|
|
|
|
|
| `content` | string | 否 | Markdown 内容 |
|
|
|
|
|
|
| `status` | string | 否 | `draft` / `publish` |
|
|
|
|
|
|
| `tag_ids` | []string | 否 | 标签 |
|
|
|
|
|
|
| `channel` | string | 否 | 渠道 |
|
|
|
|
|
|
| `process_config` | object | 否 | 解析覆盖 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge-bases/kb-1/knowledge/manual -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"title":"FAQ 汇总","content":"# 内容","status":"publish"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge-bases/:id/knowledge
|
|
|
|
|
|
|
|
|
|
|
|
用途:KB 下知识列表。权限:Viewer+,KB read;API key `retrieve`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `page` / `page_size` | int | 否 | 分页(默认 1/20) |
|
|
|
|
|
|
| `tag_ids` | string | 否 | 逗号分隔标签(OR) |
|
|
|
|
|
|
| `keyword` | string | 否 | 关键字 |
|
|
|
|
|
|
| `file_type` | string | 否 | 文件类型过滤 |
|
|
|
|
|
|
| `parse_status` | string | 否 | `pending/processing/completed/failed` |
|
|
|
|
|
|
| `source` | string | 否 | 渠道或 `manual`/`url` |
|
|
|
|
|
|
| `start_time` / `end_time` | string | 否 | RFC3339,按 `updated_at` 过滤 |
|
2026-09-23 04:00:21 +00:00
|
|
|
|
| `sort_by` | string | 否 | 排序字段:`updated_at`、`created_at` 或 `file_name`;默认 `created_at` |
|
|
|
|
|
|
| `sort_order` | string | 否 | 排序方向:`asc` 或 `desc`;默认 `desc` |
|
|
|
|
|
|
|
|
|
|
|
|
未传排序参数时,接口保持原有的 `created_at desc` 行为。显式使用 `updated_at` 时,重新解析、编辑或状态变化会影响顺序;使用 `file_name` 时按展示文件名忽略大小写排序,文件名为空会依次回退到标题和来源。所有排序都会使用知识 ID 作为稳定的次级排序条件,避免相同排序值下翻页结果漂移。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[Knowledge],"total","page","page_size"}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/knowledge-bases/kb-1/knowledge?page=1&parse_status=completed" -H "X-API-Key: $API_KEY"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge-bases/:id/knowledge/folders
|
|
|
|
|
|
|
2026-09-08 02:54:41 +00:00
|
|
|
|
用途:获取知识库的文件夹目录树。整目录上传时目录结构会被保留(migration `000079` 起存在 `knowledges.folder_path` 列,历史 `file_name` 中的路径已回填到该字段)。权限:Viewer+ + KBAccessRead。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[{FolderNode}]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge-bases/kb-1/knowledge/folders -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge-bases/:id/knowledge/folders
|
|
|
|
|
|
|
|
|
|
|
|
用途:重命名或移动文件夹,连同其所有子目录一起改路径。目标路径已存在时两个文件夹合并;不允许移动到自己的子目录下。权限:KB owner 或 Admin+ + KBAccessWrite。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `from` | string | 是 | 原路径 |
|
|
|
|
|
|
| `to` | string | 是 | 新路径 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge-bases/kb-1/knowledge/folders -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"from":"设计文档/旧版","to":"归档/设计文档"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### DELETE /api/v1/knowledge-bases/:id/knowledge
|
|
|
|
|
|
|
|
|
|
|
|
用途:清空 KB 全部内容(破坏性)。权限:Admin+,KB write;API key 仅 full-access。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Knowledge base contents clear task submitted","data":{"deleted_count":N}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X DELETE $BASE/api/v1/knowledge-bases/kb-1/knowledge -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/batch
|
|
|
|
|
|
|
|
|
|
|
|
用途:按 ID 批量获取知识(跨 KB,handler 自行校验访问)。权限:Viewer+;API key `retrieve`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `ids` | []string | 是 | 知识 ID(可重复传参或逗号分隔) |
|
|
|
|
|
|
| `kb_id` | string | 否 | 限定 KB |
|
|
|
|
|
|
| `agent_id` | string | 否 | 共享 Agent 范围 |
|
|
|
|
|
|
| `agent_source_tenant_id` | uint64 | 否 | 共享 Agent 的来源空间选择器,与共享关系校验 |
|
|
|
|
|
|
|
feat(knowledge): flag documents that stop making progress (#3557)
* feat(knowledge): flag documents that stop making progress
A document stuck in processing looked the same as one still working: a
spinner that polled forever, no hint of where it stopped, and, hours
later, a generic housekeeping failure.
- The batch and spans endpoints return last_activity_at for in-flight
rows: the later of updated_at and the newest span write. updated_at
only moves at stage transitions; span writes keep moving while a long
stage still works.
- After 20 minutes with no progress, the list and card views show
"may be stuck" with a tooltip. The timeline shows the stage it
stopped at and a stop-parsing button, plus a "last progress" stat.
Both pollers back off to 15s while everything in flight is stalled.
- When housekeeping fails a row, the error names the stalled stage and
the time of the last progress. It closes the row's open spans with
TASK_STALLED (the running stage fails, the rest are cancelled), so
the timeline shows where the run stopped instead of a spinner.
* fix(knowledge): locate stalls in finalizing and tell backlog from stuck
- Housekeeping reads the stall site from the latest attempt. It takes
the running stages, or, when none runs (post-process closes its stage
once enrichment is fanned out), the innermost running spans, mapped
back to their stage. Those spans fail with TASK_STALLED and are named
in the message; every stalled stage is listed in pipeline order. The
other open spans are cancelled. Every closed span gets a duration, and
the message leaves out the time when the heartbeat query failed.
- The spans tree prefers a TASK_STALLED failure for last_error over a
later subtask failure. current_stage falls back to the stage owning a
running subspan.
- Batch and spans responses flag rows quiet past the stall hint whose
work is still queued (waiting_in_queue), using the sweep's own probes.
At most 20 rows are probed per request, cached for a minute. The UI
shows these as queued, with no stop button in the banner.
* fix(knowledge): answer stall verdicts from one shared queue scan
- Probing a quiet document for a backlog rescanned the whole queue once
per document. When the document was absent, which is exactly the
stuck case, the scan ran to the end, and it read a Redis error as
"nothing queued". QueuedKnowledgeIDs now collects every referenced
knowledge ID in one pass and returns list errors. HousekeepingService
keeps that snapshot for a minute, shared across requests and
single-flight. A failed scan is not cached.
- With the per-request cap of 20 gone, every quiet row on a page gets a
verdict. The response carries it as stall_state (queued or stalled),
replacing waiting_in_queue. The UI marks a row as stuck only on a
"stalled" verdict. A row with no verdict, because the probe failed,
shows as ordinary processing instead of inviting a stop.
2026-09-22 13:34:08 +00:00
|
|
|
|
响应:200 `{"success":true,"data":[Knowledge]}`。处于 `pending`/`processing`/`finalizing` 的知识额外带 `last_activity_at`(RFC3339),取行的 `updated_at` 与该知识所有 span 最近一次写入中较晚的一个。超过 20 分钟无进展的知识再带 `stall_state`:`queued` 表示仍有任务在 asynq 队列或 Wiki 持久队列中等待(积压),`stalled` 表示已无任务可推进它(疑似卡住)。判定与 housekeeping 的积压判定相同;队列侧是一次全队列扫描,所有请求共享、缓存 60 秒。探测失败时不返回 `stall_state`,前端按普通解析中显示。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/knowledge/batch?ids=k-1&ids=k-2" -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:知识详情。权限:Viewer+,父 KB read。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge/k-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/:id/stages 与 GET /api/v1/knowledge/:id/spans
|
|
|
|
|
|
|
|
|
|
|
|
用途:解析阶段/trace(两条路径同一 handler `GetKnowledgeSpans`)。权限:Viewer+,父 KB read。查询参数:`attempt`(int,0=最新一次)。
|
|
|
|
|
|
|
feat(knowledge): flag documents that stop making progress (#3557)
* feat(knowledge): flag documents that stop making progress
A document stuck in processing looked the same as one still working: a
spinner that polled forever, no hint of where it stopped, and, hours
later, a generic housekeeping failure.
- The batch and spans endpoints return last_activity_at for in-flight
rows: the later of updated_at and the newest span write. updated_at
only moves at stage transitions; span writes keep moving while a long
stage still works.
- After 20 minutes with no progress, the list and card views show
"may be stuck" with a tooltip. The timeline shows the stage it
stopped at and a stop-parsing button, plus a "last progress" stat.
Both pollers back off to 15s while everything in flight is stalled.
- When housekeeping fails a row, the error names the stalled stage and
the time of the last progress. It closes the row's open spans with
TASK_STALLED (the running stage fails, the rest are cancelled), so
the timeline shows where the run stopped instead of a spinner.
* fix(knowledge): locate stalls in finalizing and tell backlog from stuck
- Housekeeping reads the stall site from the latest attempt. It takes
the running stages, or, when none runs (post-process closes its stage
once enrichment is fanned out), the innermost running spans, mapped
back to their stage. Those spans fail with TASK_STALLED and are named
in the message; every stalled stage is listed in pipeline order. The
other open spans are cancelled. Every closed span gets a duration, and
the message leaves out the time when the heartbeat query failed.
- The spans tree prefers a TASK_STALLED failure for last_error over a
later subtask failure. current_stage falls back to the stage owning a
running subspan.
- Batch and spans responses flag rows quiet past the stall hint whose
work is still queued (waiting_in_queue), using the sweep's own probes.
At most 20 rows are probed per request, cached for a minute. The UI
shows these as queued, with no stop button in the banner.
* fix(knowledge): answer stall verdicts from one shared queue scan
- Probing a quiet document for a backlog rescanned the whole queue once
per document. When the document was absent, which is exactly the
stuck case, the scan ran to the end, and it read a Redis error as
"nothing queued". QueuedKnowledgeIDs now collects every referenced
knowledge ID in one pass and returns list errors. HousekeepingService
keeps that snapshot for a minute, shared across requests and
single-flight. A failed scan is not cached.
- With the per-request cap of 20 gone, every quiet row on a page gets a
verdict. The response carries it as stall_state (queued or stalled),
replacing waiting_in_queue. The UI marks a row as stuck only on a
"stalled" verdict. A row with no verdict, because the probe failed,
shows as ordinary processing instead of inviting a stop.
2026-09-22 13:34:08 +00:00
|
|
|
|
响应:200 `{"success":true,"data":{"knowledge_id","attempt","latest_attempt","parse_status","current_stage","last_activity_at","stall_state","trace":{...},"last_error":{...}}}`
|
|
|
|
|
|
|
|
|
|
|
|
`last_activity_at` 只在解析进行中返回,取行的 `updated_at` 与本次 attempt 各 span 最近一次写入中较晚的一个;`stall_state` 含义同上。`current_stage` 是仍在运行的阶段;没有运行中的阶段时(如 `finalizing`,后处理阶段已关闭、摘要等子任务仍在跑),取仍在运行的子 span 所属的阶段。被 housekeeping 判定卡死的知识,其卡住位置的 span 会以 `TASK_STALLED` 标为失败,`last_error` 优先指向它。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge/k-1/spans -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### DELETE /api/v1/knowledge/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:删除知识(异步)。权限:KB 创建者 OR Admin+,KB write;API key `ingest`/full。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Delete task submitted","data":{"task_id"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X DELETE $BASE/api/v1/knowledge/k-1 -H "X-API-Key: $API_KEY"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge/:id
|
|
|
|
|
|
|
2026-09-08 02:54:41 +00:00
|
|
|
|
用途:更新知识元信息。权限同上。请求体(`types.Knowledge` 子集):`title`、`description`、`tags`、`custom_metadata`(均可选)。description 省略保持原摘要,显式空字符串清空摘要,非空值保存手工摘要;界面可在文档内容页编辑。
|
2026-08-06 10:22:10 +00:00
|
|
|
|
|
|
|
|
|
|
`custom_metadata` 是用户自填的描述性元数据(与系统内部使用的 `metadata` 分开存放,migration `000078`),校验规则见 `internal/application/service/knowledge.go`:
|
|
|
|
|
|
|
|
|
|
|
|
| 约束 | 值 |
|
|
|
|
|
|
| --- | --- |
|
|
|
|
|
|
| 字段数 | ≤ 20 |
|
|
|
|
|
|
| 键长度 | 1-64 字符,不能为空白 |
|
|
|
|
|
|
| 值类型 | string / number / boolean / null |
|
|
|
|
|
|
| 值长度 | ≤ 1000 字符 |
|
|
|
|
|
|
|
|
|
|
|
|
整体覆盖式更新(传入的对象替换原有对象)。元数据发生变化且该文档已有摘要时,会自动入队一次摘要刷新(`summary_status` 转为 `pending`)。元数据文本会参与摘要生成与文档级模型上下文(`Knowledge.CustomMetadataText()`)。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Knowledge updated successfully","data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge/k-1 -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' \
|
|
|
|
|
|
-d '{"title":"新标题","custom_metadata":{"部门":"研发中心","密级":"内部","版本":3}}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/:id/regenerate-summary
|
|
|
|
|
|
|
|
|
|
|
|
用途:在分块内容或自定义元数据被编辑后,重新生成该文档的摘要。权限:KB owner 或 Admin+,且对父 KB 有 write 权限。
|
|
|
|
|
|
|
|
|
|
|
|
行为分两种:文档此前没有摘要(`summary_status` 为空或 `none`)时同步触发一次生成;已有摘要时改为入队刷新任务,`summary_status` 转为 `pending`,由 `knowledge_summary_refresh.go` 异步执行。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/k-1/regenerate-summary -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge/manual/:id
|
|
|
|
|
|
|
|
|
|
|
|
用途:更新手工知识内容(`ManualKnowledgePayload` 子集:`title/content/status/...`)。权限同上。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge/manual/k-1 -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"content":"# 更新内容","status":"publish"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/:id/reparse
|
|
|
|
|
|
|
|
|
|
|
|
用途:重新解析知识。权限同上。请求体(可选):`{"process_config":{...}}`。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Reparse task submitted","data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/k-1/reparse -H "X-API-Key: $API_KEY"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/:id/cancel-parse
|
|
|
|
|
|
|
|
|
|
|
|
用途:取消解析。权限同上。无请求体。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Knowledge parse cancelled","data":{Knowledge}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/k-1/cancel-parse -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/:id/download
|
|
|
|
|
|
|
|
|
|
|
|
用途:下载原始源文件(比预览更严格:Contributor+ 且 KB write;组织共享 Viewer 不可下载源文件)。API key `retrieve`/full。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 二进制流(`application/octet-stream`)。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -OJ $BASE/api/v1/knowledge/k-1/download -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/:id/preview
|
|
|
|
|
|
|
|
|
|
|
|
用途:预览解析后的文件内容。权限:Viewer+,KB read。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 预览流(文本/HTML)。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge/k-1/preview -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge/image/:id/:chunk_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:更新某分块的图片信息(caption/OCR 等)。权限:KB 创建者 OR Admin+,KB write。路径参数:`id` 知识 ID、`chunk_id` 分块 ID。请求体为图片信息 JSON。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,...}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge/image/k-1/c-1 -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"caption":"架构图"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/search
|
|
|
|
|
|
|
|
|
|
|
|
用途:跨 KB 文件搜索(会话 @文件 选择器)。权限:Viewer+;API key `retrieve`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 查询参数 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `q` | string | 否 | 关键字(为空且 `recent=true` 返回最近文件) |
|
|
|
|
|
|
| `file_type` / `file_types` | string | 否 | 类型过滤(后者逗号分隔) |
|
|
|
|
|
|
| `page` / `page_size` | int | 否 | 分页 |
|
|
|
|
|
|
| `recent` | bool | 否 | 最近文件模式 |
|
|
|
|
|
|
| `agent_id` | string | 否 | 共享 Agent 范围 |
|
|
|
|
|
|
| `agent_source_tenant_id` | uint64 | 否 | 共享 Agent 的来源空间选择器,与共享关系校验 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":[Knowledge]}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl "$BASE/api/v1/knowledge/search?q=报告&recent=false" -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### GET /api/v1/knowledge/move/progress/:task_id
|
|
|
|
|
|
|
|
|
|
|
|
用途:查询移动任务进度。权限:Viewer+;API key `retrieve`/full。
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{MoveProgress}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl $BASE/api/v1/knowledge/move/progress/task-1 -H "Authorization: Bearer $TOKEN"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### PUT /api/v1/knowledge/tags
|
|
|
|
|
|
|
|
|
|
|
|
用途:批量更新知识标签。权限:Contributor+;API key `ingest`/full(KB 白名单在 handler 校验)。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `updates` | map[string][]string | 是(`binding:"required,min=1"`) | knowledge_id → tag_ids |
|
|
|
|
|
|
| `kb_id` | string | 否 | 限定 KB |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X PUT $BASE/api/v1/knowledge/tags -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"updates":{"k-1":["t-1"]},"kb_id":"kb-1"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/batch-reparse
|
|
|
|
|
|
|
|
|
|
|
|
用途:批量重解析。权限:Contributor+;API key `ingest`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `kb_id` | string | 是(`binding:"required"`) | KB ID |
|
|
|
|
|
|
| `ids` | []string | 是(`binding:"required"`) | 知识 ID 列表 |
|
|
|
|
|
|
| `process_config` | object | 否 | 解析覆盖 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Batch reparse task submitted","data":{"task_id"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/batch-reparse -H "X-API-Key: $API_KEY" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"kb_id":"kb-1","ids":["k-1","k-2"]}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/batch-delete
|
|
|
|
|
|
|
|
|
|
|
|
用途:批量删除(≤200 条)。权限:Contributor+;API key `ingest`/full。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `kb_id` | string | 是(`binding:"required"`) | KB ID |
|
|
|
|
|
|
| `ids` | []string | 是(`binding:"required"`) | 知识 ID 列表(≤200) |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"message":"Batch delete task submitted","data":{"task_id","deleted_count"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/batch-delete -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' -d '{"kb_id":"kb-1","ids":["k-1"]}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/folder
|
|
|
|
|
|
|
|
|
|
|
|
用途:把若干文档归类到指定文件夹(只改归类,不动知识库归属,也不重新解析)。权限:Contributor+ / API key `ingest`。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `kb_id` | string | 是 | 知识库 ID |
|
|
|
|
|
|
| `knowledge_ids` | []string | 是 | 待移动的文档 |
|
|
|
|
|
|
| `folder_path` | string | 否 | 目标文件夹;空字符串表示移回知识库根目录 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/folder -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' \
|
|
|
|
|
|
-d '{"kb_id":"kb-1","knowledge_ids":["k-1","k-2"],"folder_path":"设计文档"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
### POST /api/v1/knowledge/move
|
|
|
|
|
|
|
|
|
|
|
|
用途:跨 KB 移动知识(异步)。权限:Contributor+;API key `ingest`/full(源+目标 KB 均需在白名单)。
|
|
|
|
|
|
|
|
|
|
|
|
| 字段 | 类型 | 必填 | 说明 |
|
|
|
|
|
|
| --- | --- | --- | --- |
|
|
|
|
|
|
| `knowledge_ids` | []string | 是(`binding:"required,min=1"`) | 待移动知识 |
|
|
|
|
|
|
| `source_kb_id` | string | 是(`binding:"required"`) | 源 KB |
|
|
|
|
|
|
| `target_kb_id` | string | 是(`binding:"required"`) | 目标 KB |
|
|
|
|
|
|
| `mode` | string | 是(`binding:"required,oneof=reuse_vectors reparse"`) | 复用向量或重解析 |
|
|
|
|
|
|
|
|
|
|
|
|
响应:200 `{"success":true,"data":{"task_id","source_kb_id","target_kb_id","knowledge_count","message"}}`
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
|
curl -X POST $BASE/api/v1/knowledge/move -H "Authorization: Bearer $TOKEN" \
|
|
|
|
|
|
-H 'Content-Type: application/json' \
|
|
|
|
|
|
-d '{"knowledge_ids":["k-1"],"source_kb_id":"kb-1","target_kb_id":"kb-2","mode":"reuse_vectors"}'
|
|
|
|
|
|
```
|
2026-09-08 02:54:41 +00:00
|
|
|
|
|
|
|
|
|
|
## 实现参考
|
|
|
|
|
|
|
|
|
|
|
|
路由注册:`internal/router/routes_knowledge.go` 的 `RegisterKnowledgeBaseRoutes`、`RegisterKnowledgeRoutes`。Handler:`internal/handler/knowledgebase.go`、`internal/handler/knowledge.go`。
|