skills/modelstudioai__cli

Fork 0

mirror of https://github.com/modelstudioai/cli.git synced 2026-09-14 19:49:23 +08:00

Files

T

若麒 8906108744 refactor(knowledge): migrate high-risk commands to runtime confirmation

2026-08-27 19:42:51 +08:00

30 KiB

Raw Permalink Blame History

`kscli` 命令完整用法指南

Knowledge Studio CLI（kscli）命令总览，覆盖全部 37 个命令：34 个知识库命令 + 3 个配置/维护命令。完整参数与示例请参阅各子域手册。

概述
核心概念与实体关系
通用约定
典型工作流
命令手册
- 知识库管理 → 完整手册
- 文档管理 → 完整手册
- 检索服务管理 → 完整手册
- Chunk 管理 → 完整手册
- 数据中心文件管理 → 完整手册
- 数据中心集合与分类 → 完整手册
- 检索与对话 → 完整手册
- 配置与维护
常见错误与排查
附录：命令速查表

概述

kscli（knowledge-studio-cli）是面向 RAG 开发者的知识库专用 CLI，把知识库能力铺平成一级命令组，覆盖 RAG（检索增强生成）全链路：

知识库全生命周期管理：创建、查看、更新、删除、监控
文档管理：上传本地文件或目录、从 OSS 批量导入、查看解析状态、删除、打标签
Chunk 级运维：直接增删改查知识库中的内容切片
检索服务管理：创建/部署/复制/删除 Q&A 和检索服务（agent），管理 draft 与发布版本
数据中心管理：文件、集合（connector）、分类的增删查
检索与对话：语义检索（search）、多轮对话（chat）、兼容旧检索（retrieve）
配置与维护：查看/修改本地配置、自更新 CLI

共 37 个命令：34 个知识库命令（按功能域分为 7 组）+ config show / config set / update。所有知识库命令均使用 DashScope API Key 鉴权。

与 bl 的关系：kscli 与 bl knowledge 复用同一套命令实现，flag 名、行为逻辑、校验规则完全一致，只有命令路径不同 —— kscli 把知识库能力铺平（kscli kb list、kscli file list），bl 则把它们收在 bl knowledge 之下。用 bl 的读者请参阅 bl knowledge 指南。

安装与运行：

# 免安装执行（推荐，版本可控）
npx knowledge-studio-cli@latest --help

# 全局安装后使用 kscli
npm install -g knowledge-studio-cli
kscli --help

后文示例统一写作 kscli <command>；若未全局安装，把 kscli 换成 npx knowledge-studio-cli@latest 即可。

核心概念与实体关系

┌─────────────────────────────────────────────────────────────┐
│                     数据中心 (Data Center)                    │
│                                                             │
│  集合 (Collection) ──┬── 分类 (Category) ── 文件 (File)      │
│                      │   "connector"        可多级嵌套       │
│                      └── 默认分类                            │
│                                                             │
│  文件来源：doc upload(本地上传) / doc import-oss(OSS导入)     │
└──────────────────────────┬──────────────────────────────────┘
                           │ 导入 (import job)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                    知识库 (Knowledge Base)                    │
│                                                             │
│  知识库 (KB / pipeline / index)                              │
│    ├── 文档 (Doc) ── 解析状态: PENDING/RUNNING/COMPLETED     │
│    │     └── Chunk ── 内容切片，可增删改查、排除/恢复检索     │
│    └── 索引设置 (immutable): 向量模型、切片大小等             │
│                                                             │
│  知识库管理命令: kb create / list / info / update / delete / stats │
└──────────────────────────┬──────────────────────────────────┘
                           │ 绑定 (agent_config.kb_search_configs)
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                  检索服务 (Service / Agent)                   │
│                                                             │
│  Service (agent)                                            │
│    ├── scene: chat (Q&A) 或 search (检索)                    │
│    ├── 版本: beta (草稿) → 1, 2, 3... (已发布)               │
│    ├── 状态: draft → deployed → edited → deleted            │
│    └── 配置: 模型、温度、策略、rerank 等                      │
│                                                             │
│  消费方式: search (语义检索) / chat (多轮对话)               │
│  管理命令: create / update / deploy / copy / delete / list / get │
└─────────────────────────────────────────────────────────────┘

关键关系：

数据中心文件 → 知识库：通过 kscli kb create --doc-id 或 kscli doc upload --index-id 导入，文件解析后自动生成 chunk
知识库 → 检索服务：一个服务可绑定多个知识库，服务配置中 kb_search_configs 指定关联的知识库 ID
检索服务 → 检索/对话：kscli search 和 kscli chat 通过 --agent-id 指定服务来执行检索或对话

通用约定

鉴权

所有知识库命令均使用 DashScope API Key（Bearer token）鉴权。获取方式：百炼控制台 API Key 页面。

优先级（高 → 低）：

--api-key <key> 命令行参数
DASHSCOPE_API_KEY 环境变量
配置文件中的 api_key（kscli config set --key api_key --value <key>）

Workspace ID

知识库 API 使用 workspace 级域名（{workspaceId}.cn-beijing.maas.aliyuncs.com），因此 几乎所有知识库命令都需要 workspace ID。

优先级（高 → 低）：

--workspace-id <id> 命令行参数
BAILIAN_WORKSPACE_ID 环境变量
配置文件中的 workspace_id（kscli config set --key workspace_id --value <id>）

缺失时报错：Workspace ID is required.

全局通用参数

以下参数在所有知识库命令中通用，后续命令手册中不再逐条列出：

参数	类型	说明
`--output <format>`	string	输出格式：`text`（默认，人类友好）或 `json`（API 原始响应）
`--api-key <key>`	string	DashScope API Key
`--base-url <url>`	string	API 基地址（一般不需要指定）
`--timeout <seconds>`	number	请求超时秒数
`--quiet`	switch	静默模式，只输出关键结果（如 ID 列表）
`--verbose`	switch	详细模式，打印 HTTP 请求/响应详情到 stderr
`--dry-run`	switch	干跑模式，预览将发送的请求结构，不实际调用 API
`--config <name>`	string	使用指定配置 profile 执行命令

注意：命令手册中每个命令的参数表只列出该命令特有的参数。上述全局参数对所有命令有效。

输出格式约定

text 模式（默认）：人类友好的表格/结构化文本，适合终端查看。不同命令的输出格式见各命令的「输出」部分。
json 模式（--output json）：返回 API 原始 JSON 响应，适合程序化处理和 agent 解析。
quiet 模式（--quiet）：只输出最精简的结果（通常只有 ID），适合管道串联。

危险操作确认

涉及删除的命令（kb delete、doc delete、chunk delete、file delete、category delete、service delete）以及 service deploy 属于高风险操作。未带 --yes 时 CLI 不会执行，也不会弹出交互式 Y/N，而是返回 exit code 7 和 requires_confirmation；确认后在原命令中添加 --yes 重新执行。

Dry-run 模式

--dry-run 模式下，命令会输出将发送的 endpoint 和 request body，但不实际发起网络请求。部分命令在 dry-run 下仍会执行本地校验（如文件扩展名检查、参数约束检查）。

典型工作流

场景 A：从零搭建知识库并检索

# 1. 上传本地文件到数据中心
kscli doc upload --file ./docs/intro.md --workspace-id ws-xxx
# → 返回 file-id

# 2. 用文件创建知识库
kscli kb create --name my-kb --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx --wait
# → 返回 index-id (pipelineId) 和导入任务状态

# 3. 创建检索服务（search 场景）
kscli service create --name my-search --scene search --index-id idx-xxx --workspace-id ws-xxx
# → 返回 agent-id

# 4. 部署服务
kscli service deploy --agent-id aid-xxx --workspace-id ws-xxx --yes

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

场景 B：上传目录并导入到已有知识库

# 1. 上传整个目录到数据中心并直接导入到知识库（一步到位）
kscli doc upload --file ./docs/ --index-id idx-xxx --workspace-id ws-xxx --wait
# → 文件逐个上传到 OSS → 注册到数据中心 → 创建合并导入任务 → 轮询到完成

# 2. 检查文档状态
kscli doc list --index-id idx-xxx --workspace-id ws-xxx
# → 查看 doc_id 和解析状态

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

场景 C：创建并部署 Q&A 服务

# 1. 创建 chat 场景的检索服务
kscli service create --name my-qa --scene chat --index-id idx-xxx --workspace-id ws-xxx
# → 初始状态: draft, 版本: beta

# 2. 调整配置（如修改模型、温度）
kscli service update --agent-id aid-xxx --model qwen-max --temperature 0.7 --workspace-id ws-xxx

# 3. 用 beta 版本测试
kscli chat --message "什么是RAG?" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx

# 4. 测试通过后发布
kscli service deploy --agent-id aid-xxx --version-desc "首版" --workspace-id ws-xxx --yes

场景 D：知识库内容运维

# 1. 查看 chunk 列表
kscli chunk list --index-id idx-xxx --workspace-id ws-xxx
# → 返回 metadata._id (chunk id) 和 metadata.doc_id (document id)

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

# 3. 排除某个 chunk 不参与检索（不删除内容）
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id doc-xxx --exclude --workspace-id ws-xxx

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

# 5. 删除 chunk（批量，自动分批每 10 个一组）
kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --yes --workspace-id ws-xxx

场景 E：服务迁移/复用

# 1. 复制现有服务为新草稿
kscli service copy --agent-id aid-source --workspace-id ws-xxx
# → 返回新的 agent-id，名称加 copy_ 前缀

# 2. 修改新服务配置
kscli service update --agent-id aid-new --name "改进版" --temperature 0.5 --workspace-id ws-xxx

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

场景 F：从 OSS 批量导入文件

# 1. 从已授权的 OSS bucket 批量导入文件到数据中心
kscli doc import-oss \
  --bucket my-bucket --region cn-beijing \
  --oss-key docs/a.pdf --oss-key docs/b.docx \
  --workspace-id ws-xxx
# → 返回各文件的 fileId

# 2. 创建知识库并导入这些文件
kscli kb create --name oss-kb --description 'OSS 导入文档' --doc-id file-a --doc-id file-b --workspace-id ws-xxx --wait

# 3. 检索
kscli search --query "相关内容" --agent-id aid-xxx --workspace-id ws-xxx

命令手册

以下按功能域分组，覆盖全部 37 个命令。每个条目包含功能说明、用法签名和详细手册链接。

完整参数表、参数约束、输出说明、注意事项与示例请参阅各子域手册。

知识库管理

📖 完整手册 — 6 个命令

`kscli kb list`

列出工作区中的知识库。

kscli kb list [flags]

参数	类型	必填	说明
`--key <key>`	string	是	配置项名称：`language`、`base_url`、`output`、`output_dir`、`timeout`、`api_key`、`access_token`、`access_key_id`、`access_key_secret`、`security_token`、`default_*_model`、`workspace_id`
`--value <value>`	string	是	要写入的值（按 key 类型校验并转换）

命令	功能	关键参数
`kscli kb list`	列出知识库	`--name`
`kscli kb info`	知识库详情	`--index-id`
`kscli kb create`	创建知识库	`--name`, `--description`, `--doc-id`/`--category-id`
`kscli kb update`	更新知识库	`--index-id`, `--name`/`--description`/`--rerank-min-score`
`kscli kb delete`	删除知识库	`--index-id`, `--yes`
`kscli kb stats`	监控数据	`--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 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 chunk add`	添加 chunk	`--index-id`, `--content`/`--field`
`kscli chunk list`	chunk 列表	`--index-id`, `--doc-id`
`kscli chunk update`	更新 chunk	`--index-id`, `--chunk-id`, `--doc-id`
`kscli chunk delete`	删除 chunk	`--index-id`, `--chunk-id`, `--yes`
`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`
`kscli retrieve`	检索（废弃）	`--index-id`, `--query`
`kscli search`	语义检索	`--query`, `--agent-id`
`kscli chat`	RAG 对话	`--message`, `--agent-id`
`kscli config show`	查看配置	`--output`
`kscli config set`	写入配置	`--key`, `--value`
`kscli update`	自更新 CLI	`--to`

30 KiB Raw Permalink Blame History Unescape Escape

kscli 命令完整用法指南

目录

概述

核心概念与实体关系

通用约定

鉴权

Workspace ID

全局通用参数

输出格式约定

危险操作确认

Dry-run 模式

典型工作流

场景 A：从零搭建知识库并检索

场景 B：上传目录并导入到已有知识库

场景 C：创建并部署 Q&A 服务

场景 D：知识库内容运维

场景 E：服务迁移/复用

场景 F：从 OSS 批量导入文件

命令手册

知识库管理

kscli kb list

kscli kb info

kscli kb create

kscli kb update

kscli kb delete

kscli kb stats

文档管理

kscli doc list

kscli doc status

kscli doc upload

kscli doc delete

kscli doc tag

kscli doc import-oss

检索服务管理

kscli service list

kscli service get

kscli service create

kscli service update

kscli service deploy

kscli service delete

kscli service copy

Chunk 管理

kscli chunk add

kscli chunk list

kscli chunk update

kscli chunk delete

数据中心文件管理

kscli file list

kscli file get

kscli file delete

数据中心集合与分类

kscli collection create

kscli collection get

kscli category list

kscli category add

kscli category delete

检索与对话

kscli retrieve

kscli search

kscli chat

配置与维护

kscli config show

kscli config set

kscli update

常见错误与排查

Workspace ID 缺失

知识库 ID 不存在

导入任务 SystemError

doc_id 与 fileId 混淆

retrieve 已废弃

OSS 导入权限错误

Chat SSE error

file list 返回空

集合无法删除

附录：命令速查表

30 KiB

Raw Permalink Blame History

`kscli` 命令完整用法指南

`kscli kb list`

`kscli kb info`

`kscli kb create`

`kscli kb update`

`kscli kb delete`

`kscli kb stats`

`kscli doc list`

`kscli doc status`

`kscli doc upload`

`kscli doc delete`

`kscli doc tag`

`kscli doc import-oss`

`kscli service list`

`kscli service get`

`kscli service create`

`kscli service update`

`kscli service deploy`

`kscli service delete`

`kscli service copy`

`kscli chunk add`

`kscli chunk list`

`kscli chunk update`

`kscli chunk delete`

`kscli file list`

`kscli file get`

`kscli file delete`

`kscli collection create`

`kscli collection get`

`kscli category list`

`kscli category add`

`kscli category delete`

`kscli retrieve`

`kscli search`

`kscli chat`

`kscli config show`

`kscli config set`

`kscli update`