Skip to content

Commit e292b20

Browse files
clark-fcclark-fc
committed
docs(knowledge): 添加知识库各类资源及操作命令手册
- 新增 Chunk 管理命令手册，涵盖添加、列出、更新、删除操作详解 - 新增数据中心集合与分类命令文档，介绍集合创建、查看，分类增删查等功能 - 新增文档管理命令，包含文档上传、导入 OSS、状态查询、删除及标签管理 - 新增数据中心文件管理文档，涵盖文件列表、详情查看、删除等命令说明 - 新增知识库管理命令手册，包含知识库创建、查看、更新、删除和监控 - 各命令均详细说明参数、输出格式及多模式支持（text/quiet/json） - 提供丰富示例及注意事项，帮助用户正确使用相关命令
1 parent 12e7a22 commit e292b20

10 files changed

Lines changed: 3074 additions & 35 deletions

File tree

‎docs/knowledge/chunk.md‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
# Chunk 管理命令手册
2+
3+
Chunk 是知识库中最小的检索单元。文档导入后自动切分为 chunk，也可以手动添加。
4+
5+
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](../knowledge-cli-guide.md#通用约定)。
6+
7+
---
8+
9+
#### `bl knowledge chunk add`
10+
11+
直接向知识库添加 chunk。
12+
13+
**用法**
14+
15+
```bash
16+
bl knowledge chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]
17+
```
18+
19+
**参数**
20+
21+
| 参数 | 类型 | 必填 | 说明 |
22+
| ----------------------- | ------ | ---- | ------------------------------------------------------------------------------------------- |
23+
| `--index-id <id>` | string | 是 | 知识库 ID |
24+
| `--doc-id <id>` | string | 否² | 所属文档 ID；表格/图片知识库必填，文档型可选 |
25+
| `--content <text>` | string | 否¹ | Chunk 正文，最多 6000 字符（文档型）；与 `--content-file` 互斥 |
26+
| `--content-file <path>` | string | 否¹ | 从 UTF-8 文本文件读取正文（`.md`/`.txt` 等）；与 `--content` 互斥 |
27+
| `--title <text>` | string | 否 | Chunk 标题，最多 50 字符（文档型） |
28+
| `--image-url <url>` | array | 否 | Chunk 图片 URL（可重复，最多 10 个；文档型） |
29+
| `--field <key=value>` | array | 否¹ | 任意字段键值对（可重复），用于表格/图片知识库，键为 Excel 列名；与 content/title/image 互斥 |
30+
31+
> ¹ `--content`/`--content-file`/`--title`/`--image-url` 与 `--field` 互斥，必须提供其一。
32+
> ² 表格/图片知识库必须提供 `--doc-id`，服务端无此字段会返回 HTTP 500（`dataId不能为空`）。文档型知识库可选。
33+
34+
**参数约束**
35+
36+
- `--field` 与 `--content`/`--content-file`/`--title`/`--image-url` 互斥
37+
- `--content` 与 `--content-file` 互斥
38+
- `--content` 最多 6000 字符
39+
- `--title` 最多 50 字符
40+
- `--image-url` 最多 10 个
41+
42+
**输出**
43+
44+
text 模式：
45+
46+
```
47+
chunk created (pipeline: idx-xxx)
48+
List chunks to find the new chunk id.
49+
```
50+
51+
quiet 模式：无输出（成功退出码 0）。
52+
53+
json 模式：返回 API 原始响应（不含 chunk ID）。
54+
55+
**注意事项**
56+
57+
- 支持文档/表格/图片知识库；音视频知识库不支持。
58+
- API 响应不含 chunk ID，需用 `chunk list` 查找新 chunk。
59+
- API 幂等但限流 10 次/秒，批量脚本需自行节流。
60+
- 表格/图片知识库用 `--field`，键为 Excel 列名，值为字符串。
61+
62+
**示例**
63+
64+
```bash
65+
# 添加文本 chunk
66+
bl knowledge chunk add --index-id idx-xxx --content "chunk text" --title intro --workspace-id ws-xxx
67+
68+
# 添加表格行（字段方式）
69+
bl knowledge chunk add --index-id idx-xxx --field 列A=v1 --field 列B=v2
70+
71+
# 从文件读取内容
72+
bl knowledge chunk add --index-id idx-xxx --content-file ./chunk.md --doc-id doc-xxx
73+
```
74+
75+
---
76+
77+
#### `bl knowledge chunk list`
78+
79+
列出知识库中的 chunk，含内容和状态。
80+
81+
**用法**
82+
83+
```bash
84+
bl knowledge chunk list --index-id <id> [flags]
85+
```
86+
87+
**参数**
88+
89+
| 参数 | 类型 | 必填 | 说明 |
90+
| ------------------- | ------ | ---- | ------------------------------ |
91+
| `--index-id <id>` | string | 是 | 知识库 ID |
92+
| `--doc-id <id>` | string | 否 | 只显示属于此文档的 chunk |
93+
| `--page-number <n>` | number | 否 | 页码（默认：1） |
94+
| `--page-size <n>` | number | 否 | 每页条数（默认：20，最大 100） |
95+
96+
**参数约束**
97+
98+
- `--page-size` 范围 1-100
99+
100+
**输出**
101+
102+
text 模式：
103+
104+
```
105+
[chunk] chunk-xxx (doc: intro.md, doc_id: file-xxx) status: COMPLETED
106+
chunk content preview (truncated at 200 chars)…
107+
total: 1
108+
```
109+
110+
> 如果 chunk 被排除检索，行尾会显示 `[excluded from retrieval]`。
111+
112+
quiet 模式：每行一个 `metadata._id`（chunk ID），用于管道传给 update/delete。
113+
114+
json 模式：返回 API 原始响应，`data.nodes[]` 含完整 chunk 数据。
115+
116+
**注意事项**
117+
118+
- 用 `metadata._id` 作为 chunk ID，`metadata.doc_id` 作为文档 ID，在 chunk update/delete 中使用。
119+
- 页大小默认 20，最大 100。
120+
121+
**示例**
122+
123+
```bash
124+
# 列出所有 chunk
125+
bl knowledge chunk list --index-id idx-xxx --workspace-id ws-xxx
126+
127+
# 只看某文档的 chunk
128+
bl knowledge chunk list --index-id idx-xxx --doc-id file-xxx --page-size 50
129+
```
130+
131+
---
132+
133+
#### `bl knowledge chunk update`
134+
135+
更新 chunk 内容或切换其检索可见性。
136+
137+
**用法**
138+
139+
```bash
140+
bl knowledge chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]
141+
```
142+
143+
**参数**
144+
145+
| 参数 | 类型 | 必填 | 说明 |
146+
| ----------------------- | ------ | ---- | ------------------------------------------------------ |
147+
| `--index-id <id>` | string | 是 | 知识库 ID |
148+
| `--chunk-id <id>` | string | 是 | Chunk ID（`metadata._id`，来自 chunk list 输出） |
149+
| `--doc-id <id>` | string | 是 | 所属文档 ID（`metadata.doc_id`，来自 chunk list 输出） |
150+
| `--content <text>` | string | 否¹ | 新内容，10-6000 字符；与 `--content-file` 互斥 |
151+
| `--content-file <path>` | string | 否¹ | 从 UTF-8 文本文件读取新内容 |
152+
| `--title <text>` | string | 否 | Chunk 标题，0-50 字符（空字符串清除标题；不传则不变） |
153+
| `--exclude` | switch | 否² | 将此 chunk 排除出检索 |
154+
| `--include` | switch | 否² | 将此 chunk 恢复检索（默认行为） |
155+
156+
> ¹ `--content` 与 `--content-file` 互斥。
157+
> ² `--exclude` 与 `--include` 互斥。
158+
159+
**参数约束**
160+
161+
- `--content` 与 `--content-file` 互斥
162+
- `--exclude` 与 `--include` 互斥
163+
- 至少提供一个更新项（`--content`/`--content-file`/`--title`/`--exclude`/`--include`）
164+
- `--content` 长度 10-6000 字符
165+
- `--title` 最多 50 字符
166+
167+
**输出**
168+
169+
text 模式：
170+
171+
```
172+
updated: chunk-xxx
173+
```
174+
175+
quiet 模式：无输出。
176+
177+
json 模式：返回 API 原始响应。
178+
179+
**注意事项**
180+
181+
- 内容必须 10-6000 字符，且不超过知识库的 max chunk size。
182+
- `--content-file` 期望 UTF-8 纯文本文件，不解析 `.docx`/`.pdf` 等文档格式。
183+
- 仅切换 `--exclude`/`--include` 而不提供新内容时，CLI 自动读回当前内容并重新提交（API 要求 content 字段必填，CLI 隐藏了此限制）。
184+
185+
**示例**
186+
187+
```bash
188+
# 修改内容
189+
bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text" --workspace-id ws-xxx
190+
191+
# 排除 chunk 不参与检索
192+
bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude
193+
194+
# 恢复检索
195+
bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --include
196+
```
197+
198+
---
199+
200+
#### `bl knowledge chunk delete`
201+
202+
从知识库中删除 chunk（不可逆）。
203+
204+
**用法**
205+
206+
```bash
207+
bl knowledge chunk delete --index-id <id> --chunk-id <id> [flags]
208+
```
209+
210+
**参数**
211+
212+
| 参数 | 类型 | 必填 | 说明 |
213+
| ----------------- | ------ | ---- | ------------------------------------------------ |
214+
| `--index-id <id>` | string | 是 | 知识库 ID |
215+
| `--chunk-id <id>` | array | 是 | Chunk ID（可重复，每批最多 10 个，超出自动分批） |
216+
| `--yes` | switch | 否 | 跳过确认提示 |
217+
218+
**输出**
219+
220+
text 模式：
221+
222+
```
223+
deleted: 2 chunk(s) in 1 batch(es)
224+
```
225+
226+
quiet 模式：无输出。
227+
228+
json 模式：返回 `{ deleted_count, batches }`。
229+
230+
**注意事项**
231+
232+
- 服务端每次最多接受 10 个 chunk ID，CLI 自动分批。
233+
- 如果某批失败，操作停止，已删除的批次会在错误 hint 中列出。
234+
- Chunk 被永久移除，不可恢复。
235+
236+
**示例**
237+
238+
```bash
239+
# 删除多个 chunk
240+
bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --workspace-id ws-xxx
241+
242+
# 跳过确认
243+
bl knowledge chunk delete --index-id idx-xxx --chunk-id chunk-a --yes
244+
```
245+
246+
---
247+
248+
← [返回总览](../knowledge-cli-guide.md)

0 commit comments

Comments
 (0)