modelstudioai__cli/docs/kscli/chunk.md

Chunk 管理命令手册

Chunk 是知识库中最小的检索单元。文档导入后自动切分为 chunk，也可以手动添加。

通用约定（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 总览文档。

---

kscli chunk add

直接向知识库添加 chunk。

用法

kscli chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]

参数

参数	类型	必填	说明
--index-id <id>	string	是	知识库 ID
--doc-id <id>	string	否²	所属文档 ID；表格/图片知识库必填，文档型可选
--content <text>	string	否¹	Chunk 正文，最多 6000 字符（文档型）；与 --content-file 互斥
--content-file <path>	string	否¹	从 UTF-8 文本文件读取正文（.md/.txt 等）；与 --content 互斥
--title <text>	string	否	Chunk 标题，最多 50 字符（文档型）
--image-url <url>	array	否	Chunk 图片 URL（可重复，最多 10 个；文档型）
--field <key=value>	array	否¹	任意字段键值对（可重复），用于表格/图片知识库，键为 Excel 列名；与 content/title/image 互斥

¹ --content/--content-file/--title/--image-url 与 --field 互斥，必须提供其一。 ² 表格/图片知识库必须提供 --doc-id。文档型知识库可选。

参数约束

• --field 与 --content/--content-file/--title/--image-url 互斥
• --content 与 --content-file 互斥
• --content 最多 6000 字符
• --title 最多 50 字符
• --image-url 最多 10 个

输出

text 模式：

chunk created (pipeline: idx-xxx)
List chunks to find the new chunk id.

quiet 模式：无输出（成功退出码 0）。

json 模式：返回 API 原始响应（不含 chunk ID）。

注意事项

• 支持文档/表格/图片知识库；音视频知识库不支持。
• API 响应不含 chunk ID，需用 chunk list 查找新 chunk。
• API 幂等但限流 10 次/秒，批量脚本需自行节流。
• 表格/图片知识库用 --field，键为 Excel 列名，值为字符串。

示例

# 添加文本 chunk
kscli chunk add --index-id idx-xxx --content "chunk text" --title intro --workspace-id ws-xxx

# 添加表格行（字段方式）
kscli chunk add --index-id idx-xxx --field 列A=v1 --field 列B=v2

# 从文件读取内容
kscli chunk add --index-id idx-xxx --content-file ./chunk.md --doc-id doc-xxx

---

kscli chunk list

列出知识库中的 chunk，含内容和状态。

用法

kscli chunk list --index-id <id> [flags]

参数

参数	类型	必填	说明
--index-id <id>	string	是	知识库 ID
--doc-id <id>	string	否	只显示属于此文档的 chunk
--page-number <n>	number	否	页码（默认：1）
--page-size <n>	number	否	每页条数（默认：20，最大 100）

参数约束

• --page-size 范围 1-100

输出

text 模式：

[chunk] chunk-xxx  (doc: intro.md, doc_id: file-xxx)  status: COMPLETED
  chunk content preview (truncated at 200 chars)…
total: 1

如果 chunk 被排除检索，行尾会显示 [excluded from retrieval]。

quiet 模式：每行一个 metadata._id（chunk ID），用于管道传给 update/delete。

json 模式：返回 API 原始响应，data.nodes[] 含完整 chunk 数据。

注意事项

• 用 metadata._id 作为 chunk ID，metadata.doc_id 作为文档 ID，在 chunk update/delete 中使用。
• 页大小默认 20，最大 100。

示例

# 列出所有 chunk
kscli chunk list --index-id idx-xxx --workspace-id ws-xxx

# 只看某文档的 chunk
kscli chunk list --index-id idx-xxx --doc-id file-xxx --page-size 50

---

kscli chunk update

更新 chunk 内容或切换其检索可见性。

用法

kscli chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]

参数

参数	类型	必填	说明
--index-id <id>	string	是	知识库 ID
--chunk-id <id>	string	是	Chunk ID（metadata._id，来自 chunk list 输出）
--doc-id <id>	string	是	所属文档 ID（metadata.doc_id，来自 chunk list 输出）
--content <text>	string	否¹	新内容，10-6000 字符；与 --content-file 互斥
--content-file <path>	string	否¹	从 UTF-8 文本文件读取新内容
--title <text>	string	否	Chunk 标题，0-50 字符（空字符串清除标题；不传则不变）
--exclude	switch	否²	将此 chunk 排除出检索
--include	switch	否²	将此 chunk 恢复检索（默认行为）

¹ --content 与 --content-file 互斥。 ² --exclude 与 --include 互斥。

参数约束

• --content 与 --content-file 互斥
• --exclude 与 --include 互斥
• 至少提供一个更新项（--content/--content-file/--title/--exclude/--include）
• --content 长度 10-6000 字符
• --title 最多 50 字符

输出

text 模式：

updated: chunk-xxx

quiet 模式：无输出。

json 模式：返回 API 原始响应。

注意事项

• 内容必须 10-6000 字符，且不超过知识库的 max chunk size。
• --content-file 期望 UTF-8 纯文本文件，不解析 .docx/.pdf 等文档格式。
• 仅切换 --exclude/--include 而不提供新内容时，CLI 自动读回当前内容并重新提交（API 要求 content 字段必填，CLI 隐藏了此限制）。

示例

# 修改内容
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text" --workspace-id ws-xxx

# 排除 chunk 不参与检索
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude

# 恢复检索
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --include

---

kscli chunk delete

从知识库中删除 chunk（不可逆）。

用法

kscli chunk delete --index-id <id> --chunk-id <id> [flags]

参数

参数	类型	必填	说明
--index-id <id>	string	是	知识库 ID
--chunk-id <id>	array	是	Chunk ID（可重复，每批最多 10 个，超出自动分批）
--yes	switch	否	显式确认执行高风险操作

输出

text 模式：

deleted: 2 chunk(s) in 1 batch(es)

quiet 模式：无输出。

json 模式：返回 { deleted_count, batches }。

注意事项

• 服务端每次最多接受 10 个 chunk ID，CLI 自动分批。
• 如果某批失败，操作停止，已删除的批次会在错误 hint 中列出。
• Chunk 被永久移除，不可恢复。

示例

# 删除多个 chunk
kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --workspace-id ws-xxx

# 跳过确认
kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --yes

---

← 返回总览