Skip to main content

切片管理命令

kscli chunk 命令组，直接增删改查知识库中的内容切片

切片（chunk）是知识库中最小的检索单元。文档导入后自动切分为切片，也可以手动添加或修正。本组共 4 个命令。 鉴权、业务空间 ID、全局参数、输出格式、二次确认和干跑模式等通用约定见 CLI 概述。以下示例默认已通过配置文件设置业务空间 ID。

kscli chunk add

直接向知识库添加切片。 
kscli chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]
参数
参数类型必填说明
--index-id <id>string是知识库 ID
--doc-id <id>string是所属文档 ID，从 chunk list 或 doc list 获取
--content <text>string二选一切片正文，最多 6000 字符（文档型知识库）；与 --content-file 互斥
--content-file <path>string二选一从 UTF-8 文本文件读取正文；与 --content 互斥
--title <text>string否切片标题，最多 50 字符（文档型知识库）
--image-url <url>array否切片图片 URL，可重复传入，最多 10 个（文档型知识库）
--field <key=value>array二选一任意字段键值对，可重复传入，用于表格和图片知识库，键为表格列名；与 --content、--content-file、--title、--image-url 互斥
内容参数（--content / --content-file / --title / --image-url）与 --field 互斥，必须提供其中一组。 输出 
chunk created (knowledge base: idx-xxx)
List chunks to find the new chunk id.
quiet 模式无输出，成功时退出码为 0。json 模式返回完整结果，但不包含新切片的 ID。 注意事项
  • 支持文档型、表格型和图片型知识库，音视频知识库不支持。
  • 返回结果不含新切片的 ID，需要通过 kscli chunk list 查找。
  • 写入频率约束为每秒 10 次，批量脚本需自行控制节奏，否则可能触发限流。
  • 表格和图片知识库使用 --field，键为表格的列名，值为字符串。
示例 
# 添加文本切片
kscli chunk add --index-id idx-xxx --doc-id doc-xxx --content "切片正文" --title "概述"

# 添加表格行
kscli chunk add --index-id idx-xxx --doc-id doc-xxx --field 列A=v1 --field 列B=v2

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

kscli chunk list

列出知识库中的切片，包含内容预览和检索状态。 
kscli chunk list --index-id <id> [flags]
参数
参数类型必填说明
--index-id <id>string是知识库 ID
--doc-id <id>string否只显示属于此文档的切片
--page-number <n>number否页码，默认 1
--page-size <n>number否每页条数，默认 20，范围 1–100
输出 text 模式每条切片显示 ID、所属文档和状态，正文预览截断至 200 字符： 
[chunk] chunk-xxx  (doc: intro.md, doc_id: file-xxx)  status: COMPLETED
  切片内容预览…
total: 1
已被排除出检索的切片，行尾显示 [excluded from retrieval]。 quiet 模式每行输出一个切片 ID，可直接管道传给 chunk update 或 chunk delete。json 模式返回每条切片的完整数据。 输出中的切片 ID 和 doc_id 是 chunk update、chunk delete 的必需参数。 示例 
# 列出全部切片
kscli chunk list --index-id idx-xxx

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

kscli chunk update

更新切片内容，或切换其是否参与检索。 
kscli chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]
参数
参数类型必填说明
--index-id <id>string是知识库 ID
--chunk-id <id>string是切片 ID，来自 chunk list 输出
--doc-id <id>string是所属文档 ID，来自 chunk list 输出
--content <text>string否新内容，10–6000 字符；与 --content-file 互斥
--content-file <path>string否从 UTF-8 文本文件读取新内容；与 --content 互斥
--title <text>string否切片标题，0–50 字符。传空字符串清除标题，不传则保持不变
--excludeswitch否将此切片排除出检索；与 --include 互斥
--includeswitch否恢复此切片参与检索；与 --exclude 互斥
--content、--content-file、--title、--exclude、--include 至少提供一个。 输出 
updated: chunk-xxx
quiet 模式无输出。json 模式返回完整结果。 注意事项
  • 新内容长度必须在 10–6000 字符之间，且不超过知识库的切片大小上限。
  • --content-file 只接受 UTF-8 纯文本文件，不解析 .docx、.pdf 等文档格式。
  • 可以只切换 --exclude 或 --include 而不提供新内容，此时切片内容保持不变。排除后切片仍保留在知识库中，只是不再被检索命中，适合处理过时但需要留档的内容。
示例 
# 修正内容
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx \
  --content "修正后的内容"

# 排除出检索
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

从知识库中删除切片。 
kscli chunk delete --index-id <id> --chunk-id <id> [flags]
参数
参数类型必填说明
--index-id <id>string是知识库 ID
--chunk-id <id>array是切片 ID，可重复传入，每批最多 10 个，超出自动分批
--yesswitch否跳过确认提示
输出 
deleted: 2 chunk(s) in 1 batch(es)
quiet 模式无输出。json 模式返回 deleted_count 和 batches 字段。
切片被永久移除，不可恢复。如果只是想让内容暂时不参与检索，改用 kscli chunk update --exclude，该操作保留内容且可逆。
传入超过 10 个切片 ID 时自动分批提交。如果某一批失败，操作立即停止，已成功删除的批次会在错误提示中列出。 示例 
# 删除多个切片
kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b

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