CLI 概述

kscli（Knowledge Studio CLI）是知识库的命令行工具，覆盖知识库搭建、内容运维、检索服务管理和检索问答全流程，共 34 个命令。适合本地调试、脚本集成和 CI/CD 流程。

安装

需要 Node.js 20 及以上版本。

npm install -g knowledge-studio-cli

验证安装：

kscli --version

升级到最新版本：

kscli update

初始配置

将 API Key 和默认业务空间 ID 写入配置文件，后续命令无需重复指定：

kscli config set --key api_key --value sk-xxxxxxxxxxxxxxxx
kscli config set --key workspace_id --value ws-xxxxxxxx

查看当前配置：

kscli config show

配置完成后即可直接执行命令：

kscli kb list

API Key 在控制台 API Key 页创建，业务空间 ID 在控制台页面地址栏或业务空间详情中获取。

核心概念

命令按三层资源组织，理解层级关系有助于选择正确的命令：

层级	资源	说明	对应命令组
数据层	集合 / 分类 / 文件	文件的存储与组织。文件先进入数据中心，再导入知识库，可被多个知识库引用	`collection`、`category`、`file`
索引层	知识库 / 文档 / 切片	文档解析后生成切片并建立索引。索引设置创建后不可修改	`kb`、`doc`、`chunk`
服务层	检索服务	知识库的检索入口，承载模型、策略、重排等配置，有 beta 草稿和已发布版本	`service`

数据流向：本地文件或 OSS 对象 → 数据中心（doc upload / doc import-oss）→ 知识库（kb create / doc upload --index-id）→ 检索服务（service create --index-id）→ 检索或问答（search / chat）。

通用约定

鉴权

所有命令使用 API Key 鉴权，读取优先级从高到低：

--api-key <key> 命令行参数
DASHSCOPE_API_KEY 环境变量
配置文件中的 api_key

业务空间 ID

知识库资源归属于业务空间，除 retrieve 外的所有命令都需要业务空间 ID。读取优先级从高到低：

--workspace-id <id> 命令行参数
BAILIAN_WORKSPACE_ID 环境变量
配置文件中的 workspace_id

缺失时报错 Workspace ID is required.。本文档及各命令手册的示例默认已通过配置文件设置，因此省略 --workspace-id。

全局参数

以下参数对所有命令有效，各命令手册的参数表中不再重复列出：

参数	类型	说明
`--output <format>`	string	输出格式，`text`（默认）或 `json`
`--api-key <key>`	string	API Key
`--workspace-id <id>`	string	业务空间 ID
`--base-url <url>`	string	API 基地址，一般无需指定
`--timeout <seconds>`	number	请求超时秒数
`--quiet`	switch	静默模式，只输出关键结果
`--verbose`	switch	详细模式，将请求详情打印到 stderr
`--dry-run`	switch	干跑模式，预览将执行的操作但不提交
`--config <name>`	string	使用指定的配置 profile 执行

输出格式

text（默认）：结构化文本，适合终端阅读。
json（--output json）：完整 JSON 结果，适合脚本处理和程序解析。
quiet（--quiet）：最精简输出，通常只有 ID，适合管道串联。

例如将某文档的所有切片 ID 传给删除命令：

kscli chunk list --index-id idx-xxx --doc-id doc-xxx --quiet

二次确认

以下命令执行前会弹出确认提示：kb delete、doc delete、chunk delete、file delete、category delete、service delete、service deploy。自动化脚本中使用 --yes 跳过确认。

Dry-Run 模式

--dry-run 输出将执行的操作预览但不提交变更。部分命令在干跑下仍执行本地校验，例如 doc upload 会检查文件格式并列出将跳过的文件，可用于提前发现问题：

kscli doc upload --file ./docs/ --dry-run --verbose

典型工作流

从零搭建知识库并检索

# 1. 上传本地文件到数据中心，返回文件 ID
kscli doc upload --file ./docs/intro.md

# 2. 用文件创建知识库，返回知识库 ID 和导入任务 ID
kscli kb create --name my-kb --doc-id file-xxx --wait

# 3. 创建检索服务并绑定知识库，返回服务 ID
kscli service create --name my-search --scene search --index-id idx-xxx

# 4. 发布服务
kscli service deploy --agent-id aid-xxx --yes

# 5. 执行检索
kscli search --query "什么是 RAG" --agent-id aid-xxx

批量导入目录到已有知识库

# 1. 上传整个目录并直接导入知识库，轮询至完成
kscli doc upload --file ./docs/ --index-id idx-xxx --wait

# 2. 检查文档解析状态
kscli doc list --index-id idx-xxx

# 3. 若有文档解析失败，查看导入任务详情
kscli doc status --index-id idx-xxx --job-id job-xxx

创建并调优问答服务

# 1. 创建 chat 场景服务，初始为 draft 状态、beta 版本
kscli service create --name my-qa --scene chat --index-id idx-xxx

# 2. 调整草稿配置
kscli service update --agent-id aid-xxx --model qwen-max --temperature 0.7

# 3. 用 beta 草稿验证效果
kscli chat --message "什么是 RAG" --agent-id aid-xxx --agent-version beta

# 4. 验证通过后发布
kscli service deploy --agent-id aid-xxx --version-desc "首版" --yes

修正知识库内容

# 1. 查看切片列表，获取切片 ID 和所属文档 ID
kscli chunk list --index-id idx-xxx

# 2. 修改切片内容
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id doc-xxx --content "修正后的内容"

# 3. 将过时切片排除出检索，保留内容
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id doc-xxx --exclude

# 4. 手动补充切片
kscli chunk add --index-id idx-xxx --doc-id doc-xxx --content "新增的知识片段" --title "补充说明"

复用现有服务配置

# 1. 复制服务为新草稿，名称自动加 copy_ 前缀
kscli service copy --agent-id aid-source

# 2. 修改副本配置
kscli service update --agent-id aid-new --name "改进版" --temperature 0.5

# 3. 验证并发布
kscli chat --message "测试" --agent-id aid-new --agent-version beta
kscli service deploy --agent-id aid-new --yes

从 OSS 批量导入

# 1. 从已授权的 OSS bucket 导入文件到数据中心
kscli doc import-oss \
  --bucket my-bucket --region cn-beijing \
  --oss-key docs/a.pdf --oss-key docs/b.docx

# 2. 用这些文件创建知识库
kscli kb create --name oss-kb --doc-id file-a --doc-id file-b --wait

命令总览

知识库管理

kb 命令组，6 个命令。创建、查看、更新、删除知识库，查询存储与 QPS 监控。

文档管理

doc 命令组，6 个命令。上传本地文件、OSS 导入、跟踪解析状态、删除、打标签。

切片管理

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

检索服务管理

service 命令组，7 个命令。创建、配置、发布、复制、删除检索与问答服务。

检索与对话

search、chat、retrieve 三个命令。通过检索服务消费知识库。

数据中心集合

collection 与 category 命令组，5 个命令。管理数据中心的容器与分类层级。

数据中心文件

file 命令组，3 个命令。查看和删除数据中心的源文件。

命令速查表

命令	功能	关键参数
`kscli kb list`	列出知识库	`--name`
`kscli kb info`	知识库详情	`--index-id`
`kscli kb create`	创建知识库	`--name`、`--doc-id` / `--category-id`
`kscli kb update`	更新知识库	`--index-id`、`--name` / `--description` / `--rerank-min-score`
`kscli kb delete`	删除知识库	`--index-id`、`--yes`
`kscli kb stats`	存储与 QPS 监控	`--index-id`、`--start` / `--end`
`kscli doc list`	文档列表	`--index-id`
`kscli doc status`	导入任务状态	`--index-id`、`--job-id`、`--wait`
`kscli doc upload`	上传文件	`--file`、`--index-id`、`--wait`
`kscli doc delete`	删除文档	`--index-id`、`--doc-id`
`kscli doc tag`	文件打标签	`--doc-id`、`--tag`、`--mode`
`kscli doc import-oss`	从 OSS 导入	`--bucket`、`--region`、`--oss-key`
`kscli chunk add`	添加切片	`--index-id`、`--content` / `--field`
`kscli chunk list`	切片列表	`--index-id`、`--doc-id`
`kscli chunk update`	更新切片	`--index-id`、`--chunk-id`、`--doc-id`
`kscli chunk delete`	删除切片	`--index-id`、`--chunk-id`、`--yes`
`kscli service list`	服务列表	`--scene`
`kscli service get`	服务详情	`--agent-id`
`kscli service create`	创建服务	`--name`、`--scene`、`--index-id`
`kscli service update`	更新服务	`--agent-id` 及配置参数
`kscli service deploy`	发布服务	`--agent-id`、`--yes`
`kscli service delete`	删除服务	`--agent-id`、`--yes`
`kscli service copy`	复制服务	`--agent-id`
`kscli search`	语义检索	`--query`、`--agent-id`
`kscli chat`	RAG 对话	`--message`、`--agent-id`
`kscli retrieve`	直连检索（已废弃）	`--index-id`、`--query`
`kscli file list`	文件列表	`--category-id`
`kscli file get`	文件详情	`--file-id`
`kscli file delete`	删除文件	`--file-id`、`--yes`
`kscli collection create`	创建集合	`--name`、`--description`
`kscli collection get`	集合详情	`--collection-id` / `--name`
`kscli category list`	分类列表	`--collection-id`、`--parent-id`
`kscli category add`	创建分类	`--name`、`--parent-id`
`kscli category delete`	删除分类	`--category-id`、`--yes`

常见问题

报错 Workspace ID is required

知识库资源归属于业务空间，命令需要业务空间 ID 才能定位资源。通过以下任一方式提供：

# 命令行参数
kscli kb list --workspace-id ws-xxx

# 环境变量
export BAILIAN_WORKSPACE_ID=ws-xxx

# 配置文件（推荐）
kscli config set --key workspace_id --value ws-xxx

报错 Knowledge base not found

--index-id 指定的知识库在当前业务空间中不存在。先执行 kscli kb list 确认知识库 ID，并检查配置的业务空间是否正确。

查询导入任务返回 SystemError

通常说明 --job-id 传入的任务 ID 不存在，或该知识库当前没有导入任务。任务 ID 从 kscli doc upload 或 kscli kb create 的返回结果中获取。

删除文档时提示文档不存在

文档在知识库中的 doc_id 与上传时返回的文件 ID 不一定相同，取决于导入方式。删除知识库文档前，用 kscli doc list --quiet 获取准确的 doc_id。

retrieve 输出废弃警告

retrieve 已废弃，改用 search。search 通过 --agent-id 驱动检索策略，支持多知识库、路由、重排等能力；retrieve 直接操作单个知识库 ID，功能受限且不再迭代。

OSS 导入返回权限错误

目标 bucket 未授权给平台服务。在 RAM 控制台确认 AliyunServiceRoleForBailian 服务角色已对该 bucket 正确授权。

chat 返回 Chat API error

检查 --agent-id 是否存在、服务是否已发布、API Key 是否有效。错误码和错误信息由服务端原样返回，按提示内容排查。

file list 返回空列表

--category-id 必须是真实的分类 ID，不接受字面量 default。通过 kscli category list 或 kscli file get 输出中的 category 字段获取真实 ID。

没有删除集合的命令

平台暂不支持删除数据集合，因此 CLI 没有对应命令。创建集合前请确认命名与用途；如需隔离数据，创建新集合并迁移文件。

​安装

​初始配置

​核心概念

​通用约定

​鉴权

​业务空间 ID

​全局参数

​输出格式

​二次确认

​Dry-Run 模式

​典型工作流

​从零搭建知识库并检索

​批量导入目录到已有知识库

​创建并调优问答服务

​修正知识库内容

​复用现有服务配置

​从 OSS 批量导入

​命令总览