mirror of
https://github.com/modelstudioai/cli.git
synced 2026-09-14 19:49:23 +08:00
Merge pull request #172 from modelstudioai/feat/iteration1-w1-foundation
Feat/iteration1 w1 foundation
This commit is contained in:
clark-fc
@@ -6,6 +6,23 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
|
||||
|
||||
[中文版](CHANGELOG.zh.md) · [README](README.md) · [Contributing](CONTRIBUTING.md)
|
||||
|
||||
## [1.17.1] - 2026-08-22
|
||||
|
||||
### Fixed
|
||||
|
||||
- **`knowledge create` now requires `--description`** — aligns with the server's required-description validation: the new `--description` flag is mandatory and its 1-500 character limit is checked locally before the request goes out. `bl knowledge create` / `kscli kb create` calls need to pass it.
|
||||
- **`knowledge service update` warned about config fields the server itself returned** — updating the draft config through scalar flags such as `--policy` reads the full draft and merges before writing back; the draft's `user_system_prompt`, `anti_leak_prompt`, `refusal_prompt`, `credibility_prompt`, `session_file_parse_mode`, and `enable_thinking` / `enable_temperature` / `enable_credibility` / `enable_max_completion_tokens` were not recognized by the CLI, so every update printed a run of `unknown agent_config field passed through` warnings. The config itself was always written correctly; the spurious warnings are gone.
|
||||
|
||||
### Added
|
||||
|
||||
- **`bailian-web-search` routing skill** — `bl skill init` now also installs a dedicated web-search routing skill, so agents pick the right search entry point instead of guessing.
|
||||
- **Knowledge Studio CLI command manual** — full `kscli` reference docs covering knowledge bases, documents, chunks, collections/categories, files, retrieval/Q&A services, and search/chat, with runnable examples for every command.
|
||||
|
||||
### Changed
|
||||
|
||||
- **Description flags explain what to write** — help text for the collection and service `--description` flags now states what the field is for (telling similar items apart in lists; for services, agents read it to pick the right one) rather than just repeating "required".
|
||||
- **`knowledge retrieve --rerank-model` documents its precondition** — help now states that the target knowledge base must already have a rerank model configured, otherwise every value is rejected.
|
||||
|
||||
## [1.17.0] - 2026-08-18
|
||||
|
||||
### Added
|
||||
|
||||
@@ -6,6 +6,23 @@
|
||||
|
||||
[English](CHANGELOG.md) · [README](README.zh.md) · [参与贡献](CONTRIBUTING.zh.md)
|
||||
|
||||
## [1.17.1] - 2026-08-22
|
||||
|
||||
### 修复
|
||||
|
||||
- **`knowledge create` 的 `--description` 更新为必填** —— 对齐服务端对知识库描述的必填校验：新增 `--description` 参数并设为必填，在发出请求前于本地校验 1–500 个字符的长度限制。`bl knowledge create` / `kscli kb create` 调用需带上该参数。
|
||||
- **`knowledge service update` 对服务端自己返回的配置字段误报警告** —— 通过 `--policy` 等标量参数更新草稿配置时，CLI 会先读取完整草稿再合并回写；草稿中的 `user_system_prompt`、`anti_leak_prompt`、`refusal_prompt`、`credibility_prompt`、`session_file_parse_mode` 以及 `enable_thinking` / `enable_temperature` / `enable_credibility` / `enable_max_completion_tokens` 此前不被 CLI 识别，导致每次更新都刷出一串 `unknown agent_config field passed through` 警告。配置本身始终被正确写入，现在不再误报。
|
||||
|
||||
### 新增
|
||||
|
||||
- **`bailian-web-search` 路由技能** —— `bl skill init` 现在会一并安装专门的联网搜索路由技能，让 agent 直接选中正确的搜索入口，不再靠猜。
|
||||
- **Knowledge Studio CLI 命令手册** —— 完整的 `kscli` 参考文档，覆盖知识库、文档、切片、集合/类目、文件、检索/问答服务以及 search/chat，每条命令均附可运行示例。
|
||||
|
||||
### 变更
|
||||
|
||||
- **描述类参数说明写清该填什么** —— 数据集合与服务的 `--description` 帮助文案现在会说明该字段的用途（在列表中区分同类项；服务描述供 agent 判断该调用哪个服务），不再只是重复「必填」。
|
||||
- **`knowledge retrieve --rerank-model` 补充前置条件说明** —— 帮助文案现在会说明目标知识库必须已配置重排序模型，否则任何取值都会被拒绝。
|
||||
|
||||
## [1.17.0] - 2026-08-18
|
||||
|
||||
### 新增
|
||||
|
||||
@@ -128,7 +128,7 @@ bl knowledge info --index-id idx-xxx --workspace-id ws-xxx
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
bl knowledge create --name <text> (--doc-id <id> | --category-id <id>) [flags]
|
||||
bl knowledge create --name <text> --description <text> (--doc-id <id> | --category-id <id>) [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
@@ -136,6 +136,7 @@ bl knowledge create --name <text> (--doc-id <id> | --category-id <id>) [flags]
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| --------------------------- | ------ | ---- | -------------------------------------------------------- |
|
||||
| `--name <text>` | string | 是 | 知识库名称（1-20 字符，工作区内唯一） |
|
||||
| `--description <text>` | string | 是 | 知识库装了什么内容、给谁用（1-500 字符） |
|
||||
| `--doc-id <id>` | array | 否¹ | 数据中心文件 ID（可重复）；与 `--category-id` 互斥 |
|
||||
| `--category-id <id>` | array | 否¹ | 按分类导入该分类下所有文件（可重复）；与 `--doc-id` 互斥 |
|
||||
| `--embedding-model <name>` | string | 否 | 向量模型名称（默认：`text-embedding-v4`） |
|
||||
@@ -148,6 +149,7 @@ bl knowledge create --name <text> (--doc-id <id> | --category-id <id>) [flags]
|
||||
**参数约束**
|
||||
|
||||
- `--name` 长度 1-20 字符
|
||||
- `--description` 长度 1-500 字符，缺失或超长会在本地被拦截
|
||||
- `--doc-id` 和 `--category-id` 互斥，必须提供其一
|
||||
|
||||
**输出**
|
||||
@@ -176,13 +178,13 @@ json 模式：返回 API 原始响应，包含 `pipelineId`（知识库 ID）和
|
||||
|
||||
```bash
|
||||
# 从指定文件创建知识库
|
||||
bl knowledge create --name demo --doc-id file-xxx --workspace-id ws-xxx
|
||||
bl knowledge create --name demo --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx
|
||||
|
||||
# 从分类导入并等待导入完成
|
||||
bl knowledge create --name demo --category-id cate-xxx --wait
|
||||
bl knowledge create --name demo --description '产品文档' --category-id cate-xxx --wait
|
||||
|
||||
# 指定向量模型和切片大小
|
||||
bl knowledge create --name my-kb --doc-id file-a --doc-id file-b --embedding-model text-embedding-v4 --chunk-size 400 --workspace-id ws-xxx
|
||||
bl knowledge create --name my-kb --description '产品文档 v2' --doc-id file-a --doc-id file-b --embedding-model text-embedding-v4 --chunk-size 400 --workspace-id ws-xxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -153,7 +153,7 @@ bl knowledge doc upload --file ./docs/intro.md --workspace-id ws-xxx
|
||||
# → 返回 file-id
|
||||
|
||||
# 2. 用文件创建知识库
|
||||
bl knowledge create --name my-kb --doc-id file-xxx --workspace-id ws-xxx --wait
|
||||
bl knowledge create --name my-kb --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx --wait
|
||||
# → 返回 index-id (pipelineId) 和导入任务状态
|
||||
|
||||
# 3. 创建检索服务（search 场景）
|
||||
@@ -245,7 +245,7 @@ bl knowledge doc import-oss \
|
||||
# → 返回各文件的 fileId
|
||||
|
||||
# 2. 创建知识库并导入这些文件
|
||||
bl knowledge create --name oss-kb --doc-id file-a --doc-id file-b --workspace-id ws-xxx --wait
|
||||
bl knowledge create --name oss-kb --description 'OSS 导入文档' --doc-id file-a --doc-id file-b --workspace-id ws-xxx --wait
|
||||
|
||||
# 3. 检索
|
||||
bl knowledge search --query "相关内容" --agent-id aid-xxx --workspace-id ws-xxx
|
||||
|
||||
@@ -142,14 +142,14 @@ bl knowledge service create --name <text> --scene <chat|search> [flags]
|
||||
| ------------------------ | ------ | ---- | ------------------------------------------------- |
|
||||
| `--name <text>` | string | 是 | 服务名称（最多 200 字符，同一场景下工作区内唯一） |
|
||||
| `--scene <chat\|search>` | string | 是 | 服务场景：`chat`（Q&A）或 `search`（检索） |
|
||||
| `--description <text>` | string | 否 | 服务描述（最多 1000 字符） |
|
||||
| `--description <text>` | string | 建议 | 这个服务能回答什么、给谁用（最多 1000 字符） |
|
||||
| `--index-id <id>` | string | 否 | 绑定此知识库；其他配置使用服务端默认值 |
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--name` 最多 200 字符
|
||||
- `--scene` 只能是 `chat` 或 `search`
|
||||
- `--description` 最多 1000 字符
|
||||
- `--description` 最多 1000 字符；建议填写 —— agent 靠它判断该调用哪个服务
|
||||
|
||||
**输出**
|
||||
|
||||
|
||||
@@ -0,0 +1,248 @@
|
||||
# Chunk 管理命令手册
|
||||
|
||||
Chunk 是知识库中最小的检索单元。文档导入后自动切分为 chunk，也可以手动添加。
|
||||
|
||||
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
|
||||
|
||||
---
|
||||
|
||||
#### `kscli chunk add`
|
||||
|
||||
直接向知识库添加 chunk。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
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 列名，值为字符串。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 添加文本 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，含内容和状态。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
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。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 列出所有 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 内容或切换其检索可见性。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
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 隐藏了此限制）。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 修改内容
|
||||
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（不可逆）。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
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 被永久移除，不可恢复。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 删除多个 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
← [返回总览](./kscli-cli-guide.md)
|
||||
@@ -0,0 +1,268 @@
|
||||
# 数据中心集合与分类命令手册
|
||||
|
||||
集合（collection）是数据中心的顶层容器，对应服务端的 connector。分类（category）用于组织集合内的文件，支持多级嵌套。
|
||||
|
||||
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
|
||||
|
||||
---
|
||||
|
||||
#### `kscli collection create`
|
||||
|
||||
创建 FILE 数据集合。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli collection create --name <text> --description <text> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ---------------------- | ------ | ---- | ---------------------------------------------------------------- |
|
||||
| `--name <text>` | string | 是 | 集合名称（1-20 字符） |
|
||||
| `--description <text>` | string | 是 | 集合描述 |
|
||||
| `--store-type <type>` | string | 否 | 存储类型：`platform`（托管，默认）或 `custom`（自有 OSS bucket） |
|
||||
| `--oss-region <id>` | string | 否 | OSS region ID（`--store-type custom` 时必填） |
|
||||
| `--oss-bucket <name>` | string | 否 | OSS bucket 名称（`--store-type custom` 时必填） |
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--name` 长度 1-20 字符
|
||||
- `--store-type` 只能是 `platform` 或 `custom`
|
||||
- `--store-type custom` 时 `--oss-region` 和 `--oss-bucket` 必填
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
created: conn-xxx (my-collection, PLATFORM)
|
||||
```
|
||||
|
||||
quiet 模式：输出集合 ID。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- `platform` 使用平台托管存储；`custom` 使用已授权的 OSS bucket。
|
||||
- 自定义 bucket 必须携带标签 `bailian-connector-access=ReadAndWrite`（百炼的标签访问控制），否则服务端报 `setBucketCORS failed` 误导性错误。
|
||||
- **无集合删除 API**，创建需谨慎。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 创建平台托管的集合
|
||||
kscli collection create --name my-collection --description "team docs" --workspace-id ws-xxx
|
||||
|
||||
# 创建使用自有 OSS bucket 的集合
|
||||
kscli collection create --name oss-coll --description "own bucket" --store-type custom --oss-region cn-beijing --oss-bucket my-bucket
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli collection get`
|
||||
|
||||
查看数据集合详情。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli collection get (--collection-id <id> | --name <text>) [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ---------------------- | ------ | ---- | -------- |
|
||||
| `--collection-id <id>` | string | 否¹ | 集合 ID |
|
||||
| `--name <text>` | string | 否¹ | 集合名称 |
|
||||
|
||||
> ¹ `--collection-id` 和 `--name` 二选一，必须提供其一。
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--collection-id` 和 `--name` 互斥，必须提供其一
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
id: conn-xxx
|
||||
name: my-collection
|
||||
description: team docs
|
||||
```
|
||||
|
||||
quiet 模式：输出集合 ID。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- getConnector 不返回 `fileConnectorConfig`（`storeType`/`regionId`/`bucketName`），这些字段仅在创建时通过请求体传入，查询时不可读回。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 按 ID 查询
|
||||
kscli collection get --collection-id conn-xxx --workspace-id ws-xxx
|
||||
|
||||
# 按名称查询
|
||||
kscli collection get --name my-collection
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli category list`
|
||||
|
||||
列出数据中心分类。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli category list [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ---------------------- | ------ | ---- | ------------------------------------------------------ |
|
||||
| `--collection-id <id>` | string | 否 | 按集合 ID 过滤 |
|
||||
| `--parent-id <id>` | string | 否 | 列出此分类的子分类 |
|
||||
| `--name <text>` | string | 否 | 按分类名称过滤（精确匹配，与知识库列表的模糊匹配不同） |
|
||||
| `--next-token <token>` | string | 否 | 游标分页令牌 |
|
||||
| `--max-result <n>` | number | 否 | 每页条数（默认：20） |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
cate-xxx product-docs
|
||||
cate-yyy system-docs [default]
|
||||
next: --next-token eyJ...
|
||||
```
|
||||
|
||||
> 标记 `[default]` 的是文件未指定分类时的默认归属。
|
||||
|
||||
quiet 模式：每行一个 `categoryId`。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 分页是游标方式：使用输出的 `next: --next-token <token>` 继续翻页。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 列出所有分类
|
||||
kscli category list --workspace-id ws-xxx
|
||||
|
||||
# 按名称过滤
|
||||
kscli category list --name my-category
|
||||
|
||||
# 翻页
|
||||
kscli category list --next-token eyJ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli category add`
|
||||
|
||||
创建数据中心分类。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli category add --name <text> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ---------------------- | ------ | ---- | -------------------------------- |
|
||||
| `--name <text>` | string | 是 | 分类名称（1-20 字符） |
|
||||
| `--parent-id <id>` | string | 否 | 创建为指定分类的子分类 |
|
||||
| `--collection-id <id>` | string | 否 | 创建在此集合下（默认：平台集合） |
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--name` 长度 1-20 字符
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
created: cate-xxx (product-docs)
|
||||
```
|
||||
|
||||
quiet 模式：输出分类 ID。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 用分类按业务域组织数据中心文件。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 创建分类
|
||||
kscli category add --name product-docs --workspace-id ws-xxx
|
||||
|
||||
# 创建子分类
|
||||
kscli category add --name sub --parent-id cate-xxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli category delete`
|
||||
|
||||
删除数据中心分类。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli category delete --category-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| -------------------- | ------ | ---- | ------------ |
|
||||
| `--category-id <id>` | string | 是 | 分类 ID |
|
||||
| `--yes` | switch | 否 | 跳过确认提示 |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
deleted: cate-xxx
|
||||
```
|
||||
|
||||
quiet 模式：无输出。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 含文件或子分类的分类的删除行为由服务端定义——服务端错误原样透传。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 删除分类（交互确认）
|
||||
kscli category delete --category-id cate-xxx --workspace-id ws-xxx
|
||||
|
||||
# 跳过确认
|
||||
kscli category delete --category-id cate-xxx --yes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
← [返回总览](./kscli-cli-guide.md)
|
||||
@@ -0,0 +1,344 @@
|
||||
# 文档管理命令手册
|
||||
|
||||
文档管理覆盖文件上传、OSS 导入、解析状态跟踪、文档删除和标签管理。文档导入知识库后自动解析为 chunk。
|
||||
|
||||
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
|
||||
|
||||
---
|
||||
|
||||
#### `kscli doc list`
|
||||
|
||||
列出知识库中的文档及其解析/索引状态。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli doc list --index-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ------------------- | ------ | ---- | ------------------------------ |
|
||||
| `--index-id <id>` | string | 是 | 知识库 ID |
|
||||
| `--page-number <n>` | number | 否 | 页码（默认：1） |
|
||||
| `--page-size <n>` | number | 否 | 每页条数（默认：10，最大 100） |
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--page-size` 范围 1-100
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：每行一个文档，`FAILED` 状态的文档红色高亮。
|
||||
|
||||
```
|
||||
doc-xxx COMPLETED intro.md md 1024
|
||||
total: 1
|
||||
```
|
||||
|
||||
quiet 模式：每行一个 `doc_id`。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- `doc_id` 与 `file_id` 的关系：通过 `kb create --doc-id` 导入的文档，`doc_id` 等于 `fileId`；通过 `doc upload --index-id` 导入的，`doc_id` 可能包含 workspace 后缀。
|
||||
- 页大小默认 10（服务端默认），最大 100。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 列出文档
|
||||
kscli doc list --index-id idx-xxx --workspace-id ws-xxx
|
||||
|
||||
# 每页 100 条
|
||||
kscli doc list --index-id idx-xxx --page-size 100
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli doc status`
|
||||
|
||||
查看知识库导入任务状态。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli doc status --index-id <id> --job-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| --------------------------- | ------ | ---- | --------------------------------------------------- |
|
||||
| `--index-id <id>` | string | 是 | 知识库 ID |
|
||||
| `--job-id <id>` | string | 是 | 导入任务 ID（`ingestionId`，由 create/upload 返回） |
|
||||
| `--page-number <n>` | number | 否 | 页码 |
|
||||
| `--page-size <n>` | number | 否 | 每页条数 |
|
||||
| `--wait` | switch | 否 | 轮询直到任务到达终态 |
|
||||
| `--poll-interval <seconds>` | number | 否 | 轮询间隔秒数（默认：5） |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
status: COMPLETED
|
||||
doc-xxx COMPLETED intro.md
|
||||
```
|
||||
|
||||
quiet 模式：输出任务状态（`PENDING`/`RUNNING`/`COMPLETED`）。
|
||||
|
||||
json 模式：返回 API 原始响应，`data.rows[]` 包含每个文档的状态。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- `--index-id` 和 `--job-id` 服务端均要求必传，只传一个会返回 `SystemError`。
|
||||
- 整体任务状态为 `PENDING` / `RUNNING` / `COMPLETED`（无 `FAILED` 值）。
|
||||
- 单个文档可能解析失败（如 `PARSE_FAILED`），此时 CLI 以非零退出码报错，服务端消息原样透传。
|
||||
- 如果服务端对空闲知识库返回 `SystemError`，说明该 job 可能不存在。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 查看任务状态
|
||||
kscli doc status --index-id idx-xxx --job-id job-xxx --workspace-id ws-xxx
|
||||
|
||||
# 轮询等待完成，10 秒间隔
|
||||
kscli doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli doc upload`
|
||||
|
||||
上传本地文件或目录到数据中心，可选导入到知识库。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli doc upload --file <path> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| --------------------------- | ------ | ---- | ---------------------------------------------------------------- |
|
||||
| `--file <path>` | array | 是 | 本地文件或目录路径（可重复）。目录递归扫描，不支持的格式自动跳过 |
|
||||
| `--index-id <id>` | string | 否 | 上传后导入到此知识库（所有文件合并为一个导入任务） |
|
||||
| `--category-id <id>` | string | 否 | 目标数据中心分类（默认：工作区默认分类） |
|
||||
| `--tag <text>` | array | 否 | 文件标签（可重复），应用到每个上传的文件 |
|
||||
| `--wait` | switch | 否 | 轮询导入任务直到终态（需要 `--index-id`） |
|
||||
| `--poll-interval <seconds>` | number | 否 | 轮询间隔秒数（默认：5） |
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--wait` 要求同时指定 `--index-id`
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
intro.md file-xxx registered
|
||||
job: job-xxx
|
||||
status: COMPLETED
|
||||
|
||||
Uploaded 1 file.
|
||||
```
|
||||
|
||||
quiet 模式：每行一个 `fileId`。
|
||||
|
||||
json 模式：返回自定义结构，包含 `files`（路径和 fileId）、`skipped`、`index_id`、`ingestion_id`、`final_status`。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 上传管道：申请 lease → PUT 到 OSS → 注册文件 →（可选）创建导入任务。
|
||||
- 目录递归扫描，`node_modules`、`.git` 等自动跳过。
|
||||
- 多文件按顺序处理（无并发），避免 OSS 限流。
|
||||
- 支持的文件格式：`.pdf .doc .docx .ppt .pptx .xls .xlsx .csv .md .txt .html .png .jpg .jpeg .bmp .gif`
|
||||
- 部分文件上传失败时，已注册的 fileId 会在错误 hint 中列出。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 上传单个文件
|
||||
kscli doc upload --file ./a.md --workspace-id ws-xxx
|
||||
|
||||
# 上传多个文件并导入到知识库，等待完成
|
||||
kscli doc upload --file ./a.md --file ./b.pdf --index-id idx-xxx --wait
|
||||
|
||||
# 上传整个目录
|
||||
kscli doc upload --file ./docs/ --workspace-id ws-xxx
|
||||
|
||||
# 干跑预览（查看将上传和跳过的文件）
|
||||
kscli doc upload --file ./docs/ --dry-run --verbose
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli doc delete`
|
||||
|
||||
从知识库中删除文档及其 chunk。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli doc delete --index-id <id> --doc-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ----------------- | ------ | ---- | ----------------- |
|
||||
| `--index-id <id>` | string | 是 | 知识库 ID |
|
||||
| `--doc-id <id>` | array | 是 | 文档 ID（可重复） |
|
||||
| `--yes` | switch | 否 | 跳过确认提示 |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
deleted: 2 document(s)
|
||||
doc-a
|
||||
doc-b
|
||||
```
|
||||
|
||||
quiet 模式：每行一个已删除的 `doc_id`。
|
||||
|
||||
json 模式：返回 API 原始响应，`data.deleted[]` 为实际删除的 ID 列表。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 只从知识库索引中移除文档，数据中心源文件不受影响（用 `file delete` 删除源文件）。
|
||||
- `doc_id` 应从 `doc list --quiet` 获取，而非 `doc upload` 返回的 `fileId`。
|
||||
- 删除是异步的：服务端立即返回 Success，但 `doc list` 中可能仍显示该文档（约 30 秒后传播完成）。
|
||||
- 输出的是服务端实际删除的 ID 列表，可能与请求的数量不一致（会在 stderr 警告）。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 删除单个文档
|
||||
kscli doc delete --index-id idx-xxx --doc-id doc-xxx --workspace-id ws-xxx
|
||||
|
||||
# 批量删除，跳过确认
|
||||
kscli doc delete --index-id idx-xxx --doc-id doc-a --doc-id doc-b --yes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli doc tag`
|
||||
|
||||
批量更新数据中心文件的标签。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli doc tag --doc-id <id> --tag <text> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| --------------- | ------ | ---- | ------------------------------------------------------ |
|
||||
| `--doc-id <id>` | array | 是 | 数据中心文件 ID（可重复，最多 20 个/次） |
|
||||
| `--tag <text>` | array | 是 | 标签（可重复），应用到每个 `--doc-id` |
|
||||
| `--mode <mode>` | string | 否 | 更新模式：`append`（默认，追加）或 `overwrite`（覆盖） |
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--doc-id` 最多 20 个/次
|
||||
- `--tag` 最多 100 个
|
||||
- 每个标签最多 32 字符
|
||||
- 标签总长度最多 700 字符
|
||||
- `--mode` 只能是 `append` 或 `overwrite`
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
tagged: 2 file(s) with [project-a, draft]
|
||||
```
|
||||
|
||||
quiet 模式：无输出。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 同一组标签应用到所有 `--doc-id`；不同标签集需多次执行。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 追加标签
|
||||
kscli doc tag --doc-id file-xxx --tag project-a --tag draft --workspace-id ws-xxx
|
||||
|
||||
# 覆盖标签
|
||||
kscli doc tag --doc-id file-a --doc-id file-b --tag final --mode overwrite
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli doc import-oss`
|
||||
|
||||
从已授权的 OSS bucket 批量导入文件到数据中心。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| -------------------- | ------ | ---- | ------------------------------------- |
|
||||
| `--bucket <name>` | string | 是 | 已授权的 OSS bucket 名称 |
|
||||
| `--region <id>` | string | 是 | OSS region ID（如 `cn-beijing`） |
|
||||
| `--oss-key <key>` | array | 是 | OSS 对象 key（可重复，最多 10 个/次） |
|
||||
| `--category-id <id>` | string | 否 | 目标数据中心分类（默认：默认分类） |
|
||||
| `--tag <text>` | array | 否 | 文件标签（可重复，最多 10 个） |
|
||||
| `--overwrite` | switch | 否 | 覆盖之前从相同 OSS key 导入的文件 |
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--oss-key` 最多 10 个/次
|
||||
- `--tag` 最多 10 个
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
imported: 2 file(s)
|
||||
file-a SUCCESS docs/a.pdf
|
||||
file-b SUCCESS docs/b.docx
|
||||
```
|
||||
|
||||
quiet 模式：每行一个 `fileId`。
|
||||
|
||||
json 模式：返回 API 原始响应，`data.addFileResultList[]` 包含每个文件的 fileId、status 和 ossKey。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- bucket 必须事先授权给平台服务角色（RAM 中的 `AliyunServiceRoleForBailian`）。
|
||||
- 文件名取自 OSS key 的 basename。
|
||||
- `--overwrite` 会替换之前导入的文件并生成**新的 fileId**（旧 fileId 失效）。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 导入单个文件
|
||||
kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --workspace-id ws-xxx
|
||||
|
||||
# 导入多个文件并覆盖
|
||||
kscli doc import-oss --bucket my-bucket --region cn-beijing --oss-key docs/a.pdf --oss-key docs/b.docx --overwrite
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
← [返回总览](./kscli-cli-guide.md)
|
||||
@@ -0,0 +1,157 @@
|
||||
# 数据中心文件管理命令手册
|
||||
|
||||
数据中心是知识库文件的存储层。文件通过 `doc upload` 或 `doc import-oss` 进入数据中心，再导入到知识库。数据中心文件可被多个知识库引用。
|
||||
|
||||
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
|
||||
|
||||
---
|
||||
|
||||
#### `kscli file list`
|
||||
|
||||
列出数据中心分类下的文件。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli file list --category-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ---------------------- | ------ | ---- | -------------------------------------------------- |
|
||||
| `--category-id <id>` | string | 是 | 分类 ID（通过 `category list` 或 `file get` 获取） |
|
||||
| `--name <text>` | string | 否 | 按文件名过滤 |
|
||||
| `--file-id <id>` | array | 否 | 按文件 ID 过滤（可重复） |
|
||||
| `--next-token <token>` | string | 否 | 游标分页令牌（从上次输出获取） |
|
||||
| `--max-result <n>` | number | 否 | 每页条数 |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
file-xxx SUCCESS intro.md 1024
|
||||
next: --next-token eyJ...
|
||||
```
|
||||
|
||||
quiet 模式：每行一个 `fileId`。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- `--category-id` 必须是真实的分类 ID。与上传 API 不同，字面量 `default` 在此不被解析，传入会返回空列表。通过 `file get` 的 category 字段或 `category list` 获取真实 ID。
|
||||
- 分页是游标方式：使用输出的 `next: --next-token <token>` 继续翻页。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 列出分类下文件
|
||||
kscli file list --category-id cate-xxx --workspace-id ws-xxx
|
||||
|
||||
# 按名称过滤
|
||||
kscli file list --category-id cate-xxx --name report
|
||||
|
||||
# 翻页
|
||||
kscli file list --category-id cate-xxx --next-token eyJ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli file get`
|
||||
|
||||
查看数据中心文件详情。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli file get --file-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ---------------- | ------ | ---- | --------------- |
|
||||
| `--file-id <id>` | string | 是 | 数据中心文件 ID |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
id: file-xxx
|
||||
name: intro.md
|
||||
type: md
|
||||
size: 1024
|
||||
status: SUCCESS
|
||||
parser: AUTO_SELECT
|
||||
category: cate-xxx
|
||||
uploaded: 2026-01-01T00:00:00Z
|
||||
tags: project-a, draft
|
||||
```
|
||||
|
||||
quiet 模式：输出 JSON 格式。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 无特殊注意事项。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 查看文件详情
|
||||
kscli file get --file-id file-xxx --workspace-id ws-xxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli file delete`
|
||||
|
||||
从数据中心永久删除文件。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli file delete --file-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ---------------- | ------ | ---- | --------------- |
|
||||
| `--file-id <id>` | string | 是 | 数据中心文件 ID |
|
||||
| `--yes` | switch | 否 | 跳过确认提示 |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
deleted: file-xxx
|
||||
```
|
||||
|
||||
quiet 模式：无输出。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- **不可逆操作**：如果知识库引用了此文件，相关文档索引会失效。
|
||||
- 与 `doc delete` 的区别：`doc delete` 只从单个知识库索引中移除文档，数据中心源文件保留；`file delete` 删除源文件本身，影响所有引用它的知识库。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 删除文件（交互确认）
|
||||
kscli file delete --file-id file-xxx --workspace-id ws-xxx
|
||||
|
||||
# 跳过确认
|
||||
kscli file delete --file-id file-xxx --yes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
← [返回总览](./kscli-cli-guide.md)
|
||||
@@ -0,0 +1,342 @@
|
||||
# 知识库管理命令手册
|
||||
|
||||
知识库（Knowledge Base / pipeline / index）是 RAG 的核心载体，存储文档解析后的向量索引。本组命令覆盖知识库的创建、查看、更新、删除和监控。
|
||||
|
||||
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
|
||||
|
||||
---
|
||||
|
||||
#### `kscli kb list`
|
||||
|
||||
列出工作区中的知识库。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli kb list [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ------------------- | ------ | ---- | --------------------------------- |
|
||||
| `--name <text>` | string | 否 | 按知识库名称模糊过滤（1-20 字符） |
|
||||
| `--page-number <n>` | number | 否 | 页码（默认：1） |
|
||||
| `--page-size <n>` | number | 否 | 每页条数（默认：20，最大 100） |
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--name` 长度 1-20 字符
|
||||
- `--page-size` 范围 1-100
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：每行一个知识库，字段以双空格分隔，末尾显示总数。
|
||||
|
||||
```
|
||||
idx-xxx my-kb text-embedding-v4 600 product docs
|
||||
total: 1
|
||||
```
|
||||
|
||||
quiet 模式：每行一个知识库 ID。
|
||||
|
||||
json 模式：返回 API 原始响应，`data.rows[]` 包含完整知识库信息。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 返回的 `id` 字段作为后续命令的 `--index-id` 使用。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 列出所有知识库
|
||||
kscli kb list --workspace-id ws-xxx
|
||||
|
||||
# 按名称过滤，第二页
|
||||
kscli kb list --name demo --page-number 2 --page-size 50
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli kb info`
|
||||
|
||||
查看知识库配置详情。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli kb info --index-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ----------------- | ------ | ---- | --------- |
|
||||
| `--index-id <id>` | string | 是 | 知识库 ID |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：按诊断维度分组展示。
|
||||
|
||||
```
|
||||
Basic:
|
||||
id: idx-xxx
|
||||
name: my-kb
|
||||
description: product docs
|
||||
dataType: ...
|
||||
Indexing: [immutable — recreate required to change]
|
||||
embeddingModelName: text-embedding-v4
|
||||
embeddingDimension: 1024
|
||||
chunkSize: 600
|
||||
overlapSize: ...
|
||||
chunkMode: ...
|
||||
separator: ...
|
||||
Retrieval:
|
||||
rerankModelName: ...
|
||||
rerankMinScore: ...
|
||||
rerankTopN: ...
|
||||
rerankMode: ...
|
||||
enableRewrite: ...
|
||||
denseSimilarityTopK: ...
|
||||
sparseSimilarityTopK: ...
|
||||
Data:
|
||||
sourceType: ...
|
||||
connectorId: ...
|
||||
```
|
||||
|
||||
quiet 模式：输出知识库 ID。
|
||||
|
||||
json 模式：返回知识库完整配置 JSON。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 查看知识库详情
|
||||
kscli kb info --index-id idx-xxx --workspace-id ws-xxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli kb create`
|
||||
|
||||
创建知识库并导入数据中心文件或分类。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli kb create --name <text> --description <text> (--doc-id <id> | --category-id <id>) [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| --------------------------- | ------ | ---- | -------------------------------------------------------- |
|
||||
| `--name <text>` | string | 是 | 知识库名称（1-20 字符，工作区内唯一） |
|
||||
| `--description <text>` | string | 是 | 知识库装了什么内容、给谁用（1-500 字符） |
|
||||
| `--doc-id <id>` | array | 否¹ | 数据中心文件 ID（可重复）；与 `--category-id` 互斥 |
|
||||
| `--category-id <id>` | array | 否¹ | 按分类导入该分类下所有文件（可重复）；与 `--doc-id` 互斥 |
|
||||
| `--embedding-model <name>` | string | 否 | 向量模型名称（默认：`text-embedding-v4`） |
|
||||
| `--chunk-size <n>` | number | 否 | 切片大小，字符数（默认：600，建议 300-800） |
|
||||
| `--wait` | switch | 否 | 轮询初始导入任务直到终态 |
|
||||
| `--poll-interval <seconds>` | number | 否 | 轮询间隔秒数（默认：5） |
|
||||
|
||||
> ¹ `--doc-id` 和 `--category-id` 二选一，必须提供其一。
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--name` 长度 1-20 字符
|
||||
- `--description` 长度 1-500 字符，缺失或超长会在本地被拦截
|
||||
- `--doc-id` 和 `--category-id` 互斥，必须提供其一
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
index_id: idx-xxx
|
||||
ingestion_id: job-xxx
|
||||
status: COMPLETED
|
||||
Next: check the import job status, then search against this knowledge base.
|
||||
```
|
||||
|
||||
quiet 模式：只输出知识库 ID。
|
||||
|
||||
json 模式：返回 API 原始响应，包含 `pipelineId`（知识库 ID）和 `ingestionId`（导入任务 ID）。`--wait` 时追加 `final_status` 字段。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 结构/存储类型固定为默认文档知识库（非结构化，BUILT_IN 存储）。
|
||||
- 返回知识库 ID（`pipelineId`）和初始导入任务 ID（`ingestionId`）。
|
||||
- 使用 `doc status` 或 `--wait` 跟踪导入进度。
|
||||
- 如果 `--wait` 后部分文档解析失败，CLI 以非零退出码报错，知识库已创建成功的事实会在 hint 中提示。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 从指定文件创建知识库
|
||||
kscli kb create --name demo --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx
|
||||
|
||||
# 从分类导入并等待导入完成
|
||||
kscli kb create --name demo --description '产品文档' --category-id cate-xxx --wait
|
||||
|
||||
# 指定向量模型和切片大小
|
||||
kscli kb create --name my-kb --description '产品文档 v2' --doc-id file-a --doc-id file-b --embedding-model text-embedding-v4 --chunk-size 400 --workspace-id ws-xxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli kb update`
|
||||
|
||||
更新知识库名称、描述或 rerank 阈值。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli kb update --index-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ---------------------------- | ------ | ---- | -------------------------------------------------------- |
|
||||
| `--index-id <id>` | string | 是 | 知识库 ID |
|
||||
| `--name <text>` | string | 否 | 新名称（1-20 字符） |
|
||||
| `--description <text>` | string | 否 | 新描述 |
|
||||
| `--rerank-min-score <score>` | number | 否 | rerank 最低分数阈值，范围 0-1（低于此分的 chunk 被过滤） |
|
||||
|
||||
**参数约束**
|
||||
|
||||
- 至少提供 `--name`、`--description`、`--rerank-min-score` 之一，否则报错 "Nothing to update"
|
||||
- `--name` 长度 1-20 字符
|
||||
- `--rerank-min-score` 范围 0-1
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
updated: idx-xxx
|
||||
```
|
||||
|
||||
quiet 模式：无输出。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 索引设置（向量模型、切片大小等）不可变，修改需重建知识库。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 更新描述
|
||||
kscli kb update --index-id idx-xxx --description "product docs v2" --workspace-id ws-xxx
|
||||
|
||||
# 调整 rerank 阈值
|
||||
kscli kb update --index-id idx-xxx --rerank-min-score 0.3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli kb delete`
|
||||
|
||||
删除知识库及其所有文档和 chunk。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli kb delete --index-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ----------------- | ------ | ---- | ------------ |
|
||||
| `--index-id <id>` | string | 是 | 知识库 ID |
|
||||
| `--yes` | switch | 否 | 跳过确认提示 |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
deleted: idx-xxx
|
||||
```
|
||||
|
||||
quiet 模式：无输出。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- **不可逆操作**：知识库及所有索引内容被永久删除。
|
||||
- 数据中心中的源文件不受影响，仅删除知识库索引。
|
||||
- 不带 `--yes` 时，CLI 会先查询知识库名称和文档数量作为确认摘要。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 删除（交互确认）
|
||||
kscli kb delete --index-id idx-xxx --workspace-id ws-xxx
|
||||
|
||||
# 跳过确认
|
||||
kscli kb delete --index-id idx-xxx --yes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli kb stats`
|
||||
|
||||
查看知识库存储和 QPS 监控数据。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli kb stats --index-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ----------------- | ------ | ---- | ----------------------------------------------- |
|
||||
| `--index-id <id>` | string | 是 | 知识库 ID |
|
||||
| `--start <time>` | string | 否 | 范围起始：Unix 秒或 ISO 日期（默认：24 小时前） |
|
||||
| `--end <time>` | string | 否 | 范围结束：Unix 秒或 ISO 日期（默认：当前时间） |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
plan: ...
|
||||
storage: 100 / 1000
|
||||
peak qps: 5
|
||||
qps windows: 24 data point(s)
|
||||
```
|
||||
|
||||
quiet 模式：输出 json 格式。
|
||||
|
||||
json 模式：返回 API 原始响应，包含 `storageMonitorData` 和 `qpsMonitorData`。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 默认查询最近 24 小时数据。
|
||||
- 时间戳自动转换为 epoch 秒（API 要求秒级字符串）。13 位毫秒时间戳会自动降为秒。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 查看最近 24 小时监控
|
||||
kscli kb stats --index-id idx-xxx --workspace-id ws-xxx
|
||||
|
||||
# 指定日期范围
|
||||
kscli kb stats --index-id idx-xxx --start 2026-07-30 --end 2026-07-31
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
← [返回总览](./kscli-cli-guide.md)
|
||||
@@ -0,0 +1,929 @@
|
||||
# `kscli` 命令完整用法指南
|
||||
|
||||
> Knowledge Studio CLI（`kscli`）命令总览，覆盖全部 37 个命令：34 个知识库命令 + 3 个配置/维护命令。完整参数与示例请参阅各子域手册。
|
||||
|
||||
---
|
||||
|
||||
## 目录
|
||||
|
||||
1. [概述](#概述)
|
||||
2. [核心概念与实体关系](#核心概念与实体关系)
|
||||
3. [通用约定](#通用约定)
|
||||
4. [典型工作流](#典型工作流)
|
||||
5. [命令手册](#命令手册)
|
||||
- [知识库管理](#知识库管理) → [完整手册](kb.md)
|
||||
- [文档管理](#文档管理) → [完整手册](doc.md)
|
||||
- [检索服务管理](#检索服务管理) → [完整手册](service.md)
|
||||
- [Chunk 管理](#chunk-管理) → [完整手册](chunk.md)
|
||||
- [数据中心文件管理](#数据中心文件管理) → [完整手册](file.md)
|
||||
- [数据中心集合与分类](#数据中心集合与分类) → [完整手册](collection-category.md)
|
||||
- [检索与对话](#检索与对话) → [完整手册](search-chat.md)
|
||||
- [配置与维护](#配置与维护)
|
||||
6. [常见错误与排查](#常见错误与排查)
|
||||
7. [附录：命令速查表](#附录命令速查表)
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
`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` 指南](../knowledge/knowledge-cli-guide.md)。
|
||||
|
||||
安装与运行：
|
||||
|
||||
```bash
|
||||
# 免安装执行（推荐，版本可控）
|
||||
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 页面。
|
||||
|
||||
优先级（高 → 低）：
|
||||
|
||||
1. `--api-key <key>` 命令行参数
|
||||
2. `DASHSCOPE_API_KEY` 环境变量
|
||||
3. 配置文件中的 `api_key`（`kscli config set --key api_key --value <key>`）
|
||||
|
||||
### Workspace ID
|
||||
|
||||
知识库 API 使用 workspace 级域名（`{workspaceId}.cn-beijing.maas.aliyuncs.com`），因此 **几乎所有知识库命令都需要 workspace ID**。
|
||||
|
||||
优先级（高 → 低）：
|
||||
|
||||
1. `--workspace-id <id>` 命令行参数
|
||||
2. `BAILIAN_WORKSPACE_ID` 环境变量
|
||||
3. 配置文件中的 `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` 可跳过确认，适用于自动化脚本。
|
||||
|
||||
### Dry-run 模式
|
||||
|
||||
`--dry-run` 模式下，命令会输出将发送的 endpoint 和 request body，但**不实际发起网络请求**。部分命令在 dry-run 下仍会执行本地校验（如文件扩展名检查、参数约束检查）。
|
||||
|
||||
---
|
||||
|
||||
## 典型工作流
|
||||
|
||||
### 场景 A：从零搭建知识库并检索
|
||||
|
||||
```bash
|
||||
# 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：上传目录并导入到已有知识库
|
||||
|
||||
```bash
|
||||
# 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 服务
|
||||
|
||||
```bash
|
||||
# 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：知识库内容运维
|
||||
|
||||
```bash
|
||||
# 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：服务迁移/复用
|
||||
|
||||
```bash
|
||||
# 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 批量导入文件
|
||||
|
||||
```bash
|
||||
# 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 个命令。每个条目包含功能说明、用法签名和详细手册链接。
|
||||
|
||||
> 完整参数表、参数约束、输出说明、注意事项与示例请参阅各子域手册。
|
||||
|
||||
---
|
||||
|
||||
### 知识库管理
|
||||
|
||||
> 📖 [完整手册](kb.md) — 6 个命令
|
||||
|
||||
#### `kscli kb list`
|
||||
|
||||
列出工作区中的知识库。
|
||||
|
||||
```bash
|
||||
kscli kb list [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](kb.md#kscli-kb-list)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli kb info`
|
||||
|
||||
查看知识库配置详情。
|
||||
|
||||
```bash
|
||||
kscli kb info --index-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](kb.md#kscli-kb-info)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli kb create`
|
||||
|
||||
创建知识库并导入数据中心文件或分类。
|
||||
|
||||
```bash
|
||||
kscli kb create --name <text> --description <text> (--doc-id <id> | --category-id <id>) [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](kb.md#kscli-kb-create)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli kb update`
|
||||
|
||||
更新知识库名称、描述或 rerank 阈值。
|
||||
|
||||
```bash
|
||||
kscli kb update --index-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](kb.md#kscli-kb-update)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli kb delete`
|
||||
|
||||
删除知识库及其所有文档和 chunk。
|
||||
|
||||
```bash
|
||||
kscli kb delete --index-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](kb.md#kscli-kb-delete)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli kb stats`
|
||||
|
||||
查看知识库存储和 QPS 监控数据。
|
||||
|
||||
```bash
|
||||
kscli kb stats --index-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](kb.md#kscli-kb-stats)
|
||||
|
||||
---
|
||||
|
||||
### 文档管理
|
||||
|
||||
> 📖 [完整手册](doc.md) — 6 个命令
|
||||
|
||||
#### `kscli doc list`
|
||||
|
||||
列出知识库中的文档及其解析/索引状态。
|
||||
|
||||
```bash
|
||||
kscli doc list --index-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](doc.md#kscli-doc-list)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli doc status`
|
||||
|
||||
查看知识库导入任务状态。
|
||||
|
||||
```bash
|
||||
kscli doc status --index-id <id> --job-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](doc.md#kscli-doc-status)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli doc upload`
|
||||
|
||||
上传本地文件或目录到数据中心，可选导入到知识库。
|
||||
|
||||
```bash
|
||||
kscli doc upload --file <path> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](doc.md#kscli-doc-upload)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli doc delete`
|
||||
|
||||
从知识库中删除文档及其 chunk。
|
||||
|
||||
```bash
|
||||
kscli doc delete --index-id <id> --doc-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](doc.md#kscli-doc-delete)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli doc tag`
|
||||
|
||||
批量更新数据中心文件的标签。
|
||||
|
||||
```bash
|
||||
kscli doc tag --doc-id <id> --tag <text> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](doc.md#kscli-doc-tag)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli doc import-oss`
|
||||
|
||||
从已授权的 OSS bucket 批量导入文件到数据中心。
|
||||
|
||||
```bash
|
||||
kscli doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](doc.md#kscli-doc-import-oss)
|
||||
|
||||
---
|
||||
|
||||
### 检索服务管理
|
||||
|
||||
> 📖 [完整手册](service.md) — 7 个命令
|
||||
|
||||
#### `kscli service list`
|
||||
|
||||
列出工作区中的检索/Q&A 服务。
|
||||
|
||||
```bash
|
||||
kscli service list --scene <chat|search> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](service.md#kscli-service-list)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli service get`
|
||||
|
||||
查看服务详情，含各版本配置。
|
||||
|
||||
```bash
|
||||
kscli service get --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](service.md#kscli-service-get)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli service create`
|
||||
|
||||
创建检索/Q&A 服务，初始状态为 draft，版本为 beta。
|
||||
|
||||
```bash
|
||||
kscli service create --name <text> --scene <chat|search> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](service.md#kscli-service-create)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli service update`
|
||||
|
||||
更新服务名称、描述或草稿配置。
|
||||
|
||||
```bash
|
||||
kscli service update --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](service.md#kscli-service-update)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli service deploy`
|
||||
|
||||
发布 beta 草稿为新版本。
|
||||
|
||||
```bash
|
||||
kscli service deploy --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](service.md#kscli-service-deploy)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli service delete`
|
||||
|
||||
删除检索/Q&A 服务（软删除，幂等）。
|
||||
|
||||
```bash
|
||||
kscli service delete --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](service.md#kscli-service-delete)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli service copy`
|
||||
|
||||
复制服务为新草稿（名称自动加 `copy_` 前缀）。
|
||||
|
||||
```bash
|
||||
kscli service copy --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](service.md#kscli-service-copy)
|
||||
|
||||
---
|
||||
|
||||
### Chunk 管理
|
||||
|
||||
> 📖 [完整手册](chunk.md) — 4 个命令
|
||||
|
||||
#### `kscli chunk add`
|
||||
|
||||
直接向知识库添加 chunk。
|
||||
|
||||
```bash
|
||||
kscli chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](chunk.md#kscli-chunk-add)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli chunk list`
|
||||
|
||||
列出知识库中的 chunk，含内容和状态。
|
||||
|
||||
```bash
|
||||
kscli chunk list --index-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](chunk.md#kscli-chunk-list)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli chunk update`
|
||||
|
||||
更新 chunk 内容或切换其检索可见性。
|
||||
|
||||
```bash
|
||||
kscli chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](chunk.md#kscli-chunk-update)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli chunk delete`
|
||||
|
||||
从知识库中删除 chunk（不可逆）。
|
||||
|
||||
```bash
|
||||
kscli chunk delete --index-id <id> --chunk-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](chunk.md#kscli-chunk-delete)
|
||||
|
||||
---
|
||||
|
||||
### 数据中心文件管理
|
||||
|
||||
> 📖 [完整手册](file.md) — 3 个命令
|
||||
|
||||
#### `kscli file list`
|
||||
|
||||
列出数据中心分类下的文件。
|
||||
|
||||
```bash
|
||||
kscli file list --category-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](file.md#kscli-file-list)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli file get`
|
||||
|
||||
查看数据中心文件详情。
|
||||
|
||||
```bash
|
||||
kscli file get --file-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](file.md#kscli-file-get)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli file delete`
|
||||
|
||||
从数据中心永久删除文件。
|
||||
|
||||
```bash
|
||||
kscli file delete --file-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](file.md#kscli-file-delete)
|
||||
|
||||
---
|
||||
|
||||
### 数据中心集合与分类
|
||||
|
||||
> 📖 [完整手册](collection-category.md) — 5 个命令
|
||||
|
||||
#### `kscli collection create`
|
||||
|
||||
创建 FILE 数据集合。
|
||||
|
||||
```bash
|
||||
kscli collection create --name <text> --description <text> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](collection-category.md#kscli-collection-create)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli collection get`
|
||||
|
||||
查看数据集合详情。
|
||||
|
||||
```bash
|
||||
kscli collection get (--collection-id <id> | --name <text>) [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](collection-category.md#kscli-collection-get)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli category list`
|
||||
|
||||
列出数据中心分类。
|
||||
|
||||
```bash
|
||||
kscli category list [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](collection-category.md#kscli-category-list)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli category add`
|
||||
|
||||
创建数据中心分类。
|
||||
|
||||
```bash
|
||||
kscli category add --name <text> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](collection-category.md#kscli-category-add)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli category delete`
|
||||
|
||||
删除数据中心分类。
|
||||
|
||||
```bash
|
||||
kscli category delete --category-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](collection-category.md#kscli-category-delete)
|
||||
|
||||
---
|
||||
|
||||
### 检索与对话
|
||||
|
||||
> 📖 [完整手册](search-chat.md) — 3 个命令
|
||||
|
||||
#### `kscli retrieve`
|
||||
|
||||
从知识库检索（已废弃，请用 `search` 替代）。
|
||||
|
||||
```bash
|
||||
kscli retrieve --index-id <id> --query <text> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](search-chat.md#kscli-retrieve)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli search`
|
||||
|
||||
对知识库执行语义检索（RAG 检索）。
|
||||
|
||||
```bash
|
||||
kscli search --query <text> --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](search-chat.md#kscli-search)
|
||||
|
||||
---
|
||||
|
||||
#### `kscli chat`
|
||||
|
||||
与知识库进行 RAG 对话（流式输出）。
|
||||
|
||||
```bash
|
||||
kscli chat --message <text> --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
→ [完整参数与示例](search-chat.md#kscli-chat)
|
||||
|
||||
---
|
||||
|
||||
### 配置与维护
|
||||
|
||||
这 3 个命令不调用知识库 API，用于管理本地配置与 CLI 自身版本。配置文件默认位于 `~/.bailian/config.json`（可用 `BAILIAN_CONFIG_DIR` 改写目录）。
|
||||
|
||||
#### `kscli config show`
|
||||
|
||||
显示当前生效配置（含 base_url、output、timeout、profile 名和配置文件路径；密钥类字段自动脱敏）。
|
||||
|
||||
```bash
|
||||
kscli config show [--output json]
|
||||
```
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
# 查看当前配置
|
||||
kscli config show
|
||||
|
||||
# JSON 输出，便于脚本解析
|
||||
kscli config show --output json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli config set`
|
||||
|
||||
写入一个配置项到配置文件。
|
||||
|
||||
```bash
|
||||
kscli config set --key <key> --value <value>
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ----------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--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 类型校验并转换） |
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
# 持久化 API Key
|
||||
kscli config set --key api_key --value sk-xxx
|
||||
|
||||
# 持久化 workspace，省去每次传 --workspace-id
|
||||
kscli config set --key workspace_id --value ws-xxx
|
||||
|
||||
# 默认输出 JSON
|
||||
kscli config set --key output --value json
|
||||
```
|
||||
|
||||
**注意事项**
|
||||
|
||||
- `--dry-run` 只打印将写入的键值和配置文件路径，不落盘。
|
||||
- 密钥类字段（`api_key`、`access_token` 等）在回显时被掩码。
|
||||
- 配合 `--config <name>` 可写入指定 profile。
|
||||
|
||||
---
|
||||
|
||||
#### `kscli update`
|
||||
|
||||
将 CLI 自更新到最新版本，或用 `--to` 指定目标版本。
|
||||
|
||||
```bash
|
||||
kscli update [--to <version>]
|
||||
```
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ---------------- | ------ | ---- | ------------------------------------------------------------------------- |
|
||||
| `--to <version>` | string | 否 | 目标版本（semver，如 `1.13.0` / `v1.13.0` / `0.0.0-beta-<sha>-<时间戳>`） |
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
# 更新到最新版
|
||||
kscli update
|
||||
|
||||
# 回滚/固定到指定版本
|
||||
kscli update --to 1.13.0
|
||||
```
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 更新方式按安装来源自动选择（npm 全局安装或二进制安装）。
|
||||
- `--to` 传入非法 semver 会在本地被拦截并报错。
|
||||
|
||||
---
|
||||
|
||||
## 常见错误与排查
|
||||
|
||||
### Workspace ID 缺失
|
||||
|
||||
**报错**：`Workspace ID is required.`
|
||||
|
||||
**原因**：所有知识库管理命令都需要 workspace ID 来构造 API 端点（`{workspaceId}.cn-beijing.maas.aliyuncs.com`）。
|
||||
|
||||
**解决**：
|
||||
|
||||
```bash
|
||||
# 方式1：命令行参数
|
||||
kscli kb list --workspace-id ws-xxx
|
||||
|
||||
# 方式2：环境变量
|
||||
export BAILIAN_WORKSPACE_ID=ws-xxx
|
||||
|
||||
# 方式3：配置文件
|
||||
kscli config set --key workspace_id --value ws-xxx
|
||||
```
|
||||
|
||||
### 知识库 ID 不存在
|
||||
|
||||
**报错**：`Knowledge base not found: idx-xxx`
|
||||
|
||||
**原因**：`--index-id` 指定的知识库在当前 workspace 中不存在。
|
||||
|
||||
**解决**：先 `kscli kb list` 确认知识库 ID。
|
||||
|
||||
### 导入任务 SystemError
|
||||
|
||||
**报错**：服务端返回 `SystemError`
|
||||
|
||||
**原因**：`doc status` 传入了不存在的 job ID，或知识库空闲无任务。
|
||||
|
||||
**解决**：检查 `doc list` 输出中的 `ingestionId`，或从 `doc upload` / `kb create` 的返回值获取。
|
||||
|
||||
### doc_id 与 fileId 混淆
|
||||
|
||||
**问题**：`doc delete` 时用了 `doc upload` 返回的 `fileId` 而非 `doc list` 返回的 `doc_id`。
|
||||
|
||||
**原因**：通过 `kb create --doc-id` 导入的文档，`doc_id` 等于 `fileId`；但通过 `doc upload --index-id` 导入的，`doc_id` 可能含 workspace 后缀。
|
||||
|
||||
**解决**：始终用 `kscli doc list --quiet` 获取 `doc_id`。
|
||||
|
||||
### retrieve 已废弃
|
||||
|
||||
**问题**：`retrieve` 命令输出废弃警告。
|
||||
|
||||
**解决**：改用 `search` 命令。`search` 通过 `--agent-id` 驱动检索策略，支持多知识库、路由、rerank 等高级特性。`retrieve` 直接操作 `--index-id`，功能受限且不再迭代。
|
||||
|
||||
### OSS 导入权限错误
|
||||
|
||||
**报错**：服务端返回权限相关错误。
|
||||
|
||||
**原因**：OSS bucket 未授权给平台服务角色。
|
||||
|
||||
**解决**：检查 RAM 控制台中的 `AliyunServiceRoleForBailian` 角色是否已正确授权。
|
||||
|
||||
### Chat SSE error
|
||||
|
||||
**报错**：`Chat API error` + API error code。
|
||||
|
||||
**原因**：流式对话过程中服务端返回 error 事件。
|
||||
|
||||
**解决**：检查 `--agent-id` 是否存在、服务是否已部署、API Key 是否有效。错误消息和 code 原样透传，不二次包装。
|
||||
|
||||
### file list 返回空
|
||||
|
||||
**问题**：`file list --category-id default` 返回空列表。
|
||||
|
||||
**原因**：与上传 API 不同，`file list` 不解析字面量 `default`，需要真实分类 ID。
|
||||
|
||||
**解决**：通过 `file get` 的 category 字段或 `category list` 获取真实分类 ID。
|
||||
|
||||
### 集合无法删除
|
||||
|
||||
**问题**：没有 `collection delete` 命令。
|
||||
|
||||
**原因**：暂不支持通过 CLI 删除。
|
||||
|
||||
**解决**：创建集合需谨慎。如需隔离，创建新集合并迁移文件。
|
||||
|
||||
---
|
||||
|
||||
## 附录：命令速查表
|
||||
|
||||
| 命令 | 功能 | 关键参数 |
|
||||
| ------------------------- | ------------ | ----------------------------------------------------------- |
|
||||
| `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` |
|
||||
@@ -0,0 +1,218 @@
|
||||
# 检索与对话命令手册
|
||||
|
||||
以下命令通过检索服务（agent）消费知识库。`search` 用于语义检索，`chat` 用于多轮对话。`retrieve` 已废弃。
|
||||
|
||||
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
|
||||
|
||||
---
|
||||
|
||||
#### `kscli retrieve`
|
||||
|
||||
从知识库检索（已废弃，请用 `search` 替代）。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli retrieve --index-id <id> --query <text> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ------------------------------- | ------ | ---- | --------------------------------------------------- |
|
||||
| `--index-id <id>` | string | 是 | 知识库 ID |
|
||||
| `--query <text>` | string | 是 | 检索查询文本 |
|
||||
| `--dense-similarity-top-k <n>` | number | 否 | 稠密检索 top K |
|
||||
| `--sparse-similarity-top-k <n>` | number | 否 | 稀疏检索 top K |
|
||||
| `--rerank` | switch | 否 | 启用 rerank |
|
||||
| `--rerank-top-n <n>` | number | 否 | rerank 返回 top N 结果 |
|
||||
| `--rerank-model <name>` | string | 否 | rerank 模型名，如 `qwen3-rerank-hybrid` |
|
||||
| `--rerank-mode <mode>` | string | 否 | rerank 模式：`qa`、`similar` 或 `custom` |
|
||||
| `--rerank-instruct <text>` | string | 否 | 自定义 rerank 指令（`--rerank-mode custom` 时使用） |
|
||||
| `--top-k <n>` | number | 否 | 返回结果数（已废弃，用 `--rerank-top-n` 替代） |
|
||||
|
||||
**输出**
|
||||
|
||||
text/quiet 模式：
|
||||
|
||||
```
|
||||
[1] (score: 0.9512)
|
||||
检索到的文本内容...
|
||||
|
||||
[2] (score: 0.8734)
|
||||
另一段文本内容...
|
||||
```
|
||||
|
||||
> 无结果时输出 `No results found.`
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- **已废弃**，推荐使用 `search` 命令。`search` 通过 agent_id 驱动检索策略，支持更多高级特性。
|
||||
- `--top-k` 已废弃，使用 `--rerank-top-n` 替代，传入 `--top-k` 会输出 stderr 警告。
|
||||
- 此命令直接用 `--index-id` 检索，不需要创建检索服务。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 基础检索
|
||||
kscli retrieve --index-id idx-xxx --query "How to use Alibaba Cloud Bailian" --workspace-id ws-xxx
|
||||
|
||||
# 启用 rerank
|
||||
kscli retrieve --index-id idx-xxx --query "RAG retrieval" --rerank --rerank-model qwen3-rerank-hybrid
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli search`
|
||||
|
||||
对知识库执行语义检索（RAG 检索）。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli search --query <text> --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| --------------------------- | ------ | ---- | ------------------------------------------------------------------- |
|
||||
| `--query <text>` | string | 是 | 检索查询文本（不可为空） |
|
||||
| `--agent-id <id>` | string | 是 | 检索服务 ID（在控制台知识检索页面获取，或通过 `service list` 查看） |
|
||||
| `--agent-version <version>` | string | 否 | 服务版本：`beta`（调试草稿）或已发布版本号；默认调用最新已发布版本 |
|
||||
| `--image <url>` | array | 否 | 图片 URL（可重复），用于多模态检索 |
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--query` 不可为空（API 要求 `minLength: 1`）
|
||||
|
||||
**输出**
|
||||
|
||||
text/quiet 模式：
|
||||
|
||||
```
|
||||
[1] (score: 0.9512)
|
||||
检索到的文本内容...
|
||||
|
||||
[2] (score: 0.8734)
|
||||
另一段文本内容...
|
||||
```
|
||||
|
||||
> 无结果时输出 `No results found.`
|
||||
|
||||
json 模式：返回 API 原始响应，`data.nodes[]` 包含检索结果。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 检索范围和策略（多知识库加权、路由、rerank 等）由 `--agent-id` 对应的服务配置驱动。只需 `--query` 和 `--agent-id` 即可调用。
|
||||
- `--agent-version beta` 调试草稿配置进行调试，部署前验证效果。
|
||||
- 与 `retrieve` 的区别：`search` 通过 agent_id 间接驱动检索策略（支持多知识库、路由、rerank 等），`retrieve` 直接操作 index_id 且功能较少。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 基础检索
|
||||
kscli search --query "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
|
||||
|
||||
# 多模态检索（带图片）
|
||||
kscli search --query "describe this image" --agent-id aid-xxx --workspace-id ws-xxx --image https://example.com/img.jpg
|
||||
|
||||
# 调试草稿版本
|
||||
kscli search --query "test" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli chat`
|
||||
|
||||
与知识库进行 RAG 对话（流式输出）。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli chat --message <text> --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| --------------------------- | ------ | ---- | ------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `--message <text>` | array | 是¹ | 消息文本（可重复）。支持 `role:content` 前缀设置角色（如 `user:hello`），默认角色为 `user`。也支持完整 JSON 对象传递结构化消息 |
|
||||
| `--agent-id <id>` | string | 是 | Q&A 服务 ID（在控制台知识问答页面获取，或通过 `service list --scene chat` 查看） |
|
||||
| `--agent-version <version>` | string | 否 | 服务版本：`beta`（调试草稿）或已发布版本号；默认调用最新已发布版本 |
|
||||
| `--image <url>` | array | 否 | 图片 URL（可重复）。附加到最后一条 user 消息作为多模态内容 |
|
||||
|
||||
> ¹ `--message` 或 `--image` 至少提供其一。纯图片查询可以只传 `--image`（CLI 会自动创建空 user 消息承载图片）。
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--message` 或 `--image` 至少提供一个
|
||||
- `--image` 不能与已包含 `image_url` 内容部分的消息同时使用
|
||||
|
||||
**输出**
|
||||
|
||||
**TTY text 模式**（实时流式）：
|
||||
|
||||
```
|
||||
🔍 Retrieving...
|
||||
✍️ Generating...
|
||||
这是AI生成的回答内容，逐字流式输出...
|
||||
```
|
||||
|
||||
> 进度标签由 SSE `step_change` 事件驱动：`tool_calling`（检索中）→ `plan_start`（规划中）→ `generation_start`（生成中）。
|
||||
|
||||
**非 TTY text 模式**（缓冲输出）：
|
||||
|
||||
```
|
||||
完整的回答文本...
|
||||
```
|
||||
|
||||
**json 模式**（`--output json`）：
|
||||
|
||||
```json
|
||||
{
|
||||
"answer": "完整的回答文本...",
|
||||
"request_id": "xxx"
|
||||
}
|
||||
```
|
||||
|
||||
quiet 模式：输出完整的回答文本。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- API 仅支持 SSE 流式响应。TTY 环境下实时打印 token；非 TTY 环境缓冲后输出完整文本。
|
||||
- SSE 事件生命周期：`tool_calling` → `tool_return` → `plan_start` → `planning` → `plan_end` → `generation_start` → `generating` → `generation_end`。`tool_calling` → `tool_return` 可能循环多次。
|
||||
- 多轮对话：用 `--message "user:..."` 和 `--message "assistant:..."` 传递对话历史。
|
||||
- `--agent-version beta` 调用草稿配置进行调试。
|
||||
- `--image` 附加到最后一条 user 消息上。如果消息中已包含 `image_url` 内容部分，则不能再用 `--image`。
|
||||
- `--verbose` 模式下，所有 SSE 事件详情会输出到 stderr。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 单轮对话
|
||||
kscli chat --message "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
|
||||
|
||||
# 多轮对话（带历史）
|
||||
kscli chat \
|
||||
--message "user:What is RAG?" \
|
||||
--message "assistant:RAG is retrieval-augmented generation..." \
|
||||
--message "How does it work?" \
|
||||
--agent-id aid-xxx --workspace-id ws-xxx
|
||||
|
||||
# 多模态对话（带图片）
|
||||
kscli chat \
|
||||
--message "Describe these images" \
|
||||
--image https://example.com/a.png \
|
||||
--image https://example.com/b.png \
|
||||
--agent-id aid-xxx --workspace-id ws-xxx
|
||||
|
||||
# 调试草稿版本
|
||||
kscli chat --message "test" --agent-id aid-xxx --agent-version beta --workspace-id ws-xxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
← [返回总览](./kscli-cli-guide.md)
|
||||
@@ -0,0 +1,401 @@
|
||||
# 检索服务管理命令手册
|
||||
|
||||
检索服务（也称 agent）是知识库的检索入口。通过 `--agent-id` 在 search/chat 命令中使用。服务有 `chat`（问答）和 `search`（检索）两种场景。
|
||||
|
||||
> **通用约定**（鉴权、Workspace ID、全局参数、输出格式、危险操作确认、Dry-run 模式）请参阅 [总览文档](./kscli-cli-guide.md#通用约定)。
|
||||
|
||||
---
|
||||
|
||||
#### `kscli service list`
|
||||
|
||||
列出工作区中的检索/Q&A 服务。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli service list --scene <chat|search> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ------------------------ | ------ | ---- | ------------------------------------------------------- |
|
||||
| `--scene <chat\|search>` | string | 是 | 服务场景：`chat`（Q&A）或 `search`（检索） |
|
||||
| `--status <status>` | string | 否 | 按状态过滤：`draft`、`deployed`（含 edited）、`deleted` |
|
||||
| `--name <text>` | string | 否 | 按服务名称模糊过滤 |
|
||||
| `--agent-id <id>` | string | 否 | 按精确 agent ID 过滤 |
|
||||
| `--index-id <id>` | string | 否 | 按关联知识库 ID 过滤 |
|
||||
| `--page-number <n>` | number | 否 | 页码（默认：1） |
|
||||
| `--page-size <n>` | number | 否 | 每页条数（默认：10，最大 100） |
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--scene` 只能是 `chat` 或 `search`
|
||||
- `--status` 只能是 `draft`、`deployed`、`deleted`
|
||||
- `--page-size` 范围 1-100
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
aid-xxx deployed 2 my-qa (kb: my-kb)
|
||||
total: 1
|
||||
Use an agent_id above with the chat command.
|
||||
```
|
||||
|
||||
> 最后一行根据 scene 自动提示用 `search` 还是 `chat` 命令消费。
|
||||
|
||||
quiet 模式：每行一个 `agent_id`。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 服务端要求 `--scene` 必填，要查看两种场景的服务需分别执行。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 列出 chat 服务
|
||||
kscli service list --scene chat --workspace-id ws-xxx
|
||||
|
||||
# 只看已部署的检索服务
|
||||
kscli service list --scene search --status deployed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli service get`
|
||||
|
||||
查看服务详情，含各版本配置。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli service get --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| --------------------------- | ------ | ---- | --------------------------------------------------------- |
|
||||
| `--agent-id <id>` | string | 是 | 服务（agent）ID |
|
||||
| `--agent-version <version>` | string | 否 | 指定版本查看（`beta` 或已发布版本号）；不传则返回所有版本 |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
Basic:
|
||||
id: aid-xxx
|
||||
name: my-qa
|
||||
desc: product Q&A
|
||||
scene: chat
|
||||
status: deployed
|
||||
Version beta:
|
||||
desc: draft
|
||||
policy: turbo
|
||||
model: qwen-max
|
||||
temperature: 0.7
|
||||
kb: idx-xxx (my-kb)
|
||||
Version 1:
|
||||
published: 2026-01-01
|
||||
...
|
||||
```
|
||||
|
||||
quiet 模式：输出 JSON 格式。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 不传 `--agent-version` 时返回所有版本（beta 草稿 + 已发布版本号）。
|
||||
- 版本值原样传递，有效值集合由服务端维护。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 查看服务完整详情
|
||||
kscli service get --agent-id aid-xxx --workspace-id ws-xxx
|
||||
|
||||
# 只看 beta 草稿配置
|
||||
kscli service get --agent-id aid-xxx --agent-version beta
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli service create`
|
||||
|
||||
创建检索/Q&A 服务，初始状态为 draft，版本为 beta。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli service create --name <text> --scene <chat|search> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ------------------------ | ------ | ---- | ------------------------------------------------- |
|
||||
| `--name <text>` | string | 是 | 服务名称（最多 200 字符，同一场景下工作区内唯一） |
|
||||
| `--scene <chat\|search>` | string | 是 | 服务场景：`chat`（Q&A）或 `search`（检索） |
|
||||
| `--description <text>` | string | 建议 | 这个服务能回答什么、给谁用（最多 1000 字符） |
|
||||
| `--index-id <id>` | string | 否 | 绑定此知识库；其他配置使用服务端默认值 |
|
||||
|
||||
**参数约束**
|
||||
|
||||
- `--name` 最多 200 字符
|
||||
- `--scene` 只能是 `chat` 或 `search`
|
||||
- `--description` 最多 1000 字符；建议填写 —— agent 靠它判断该调用哪个服务
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
created: aid-xxx (status: draft, version: beta)
|
||||
Test the draft with --agent-version beta on search/chat, then deploy it to publish.
|
||||
```
|
||||
|
||||
quiet 模式：输出 agent ID。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 不指定 `--index-id` 时，服务端使用默认 agent 配置。
|
||||
- beta 草稿可通过 search/chat 的 `--agent-version beta` 测试，部署后才生效。
|
||||
- 需要工作区的知识库创建权限。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 创建 Q&A 服务
|
||||
kscli service create --name my-qa --scene chat --workspace-id ws-xxx
|
||||
|
||||
# 创建检索服务并绑定知识库
|
||||
kscli service create --name my-search --scene search --index-id idx-xxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli service update`
|
||||
|
||||
更新服务名称、描述或草稿配置。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli service update --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ------------------------------ | ------ | ---- | ---------------------------------------------------------------------------------------- |
|
||||
| `--agent-id <id>` | string | 是 | 服务（agent）ID |
|
||||
| `--name <text>` | string | 否 | 新名称（最多 200 字符） |
|
||||
| `--description <text>` | string | 否 | 新描述（最多 1000 字符） |
|
||||
| `--agent-version <version>` | string | 否 | 目标版本（默认：beta 草稿。已发布版本只接受 `--version-desc`） |
|
||||
| `--version-desc <text>` | string | 否 | 版本描述 |
|
||||
| `--policy <policy>` | string | 否 | Agent 策略：`turbo`（快速）或 `agentic`（多轮） |
|
||||
| `--model <name>` | string | 否 | 生成模型代码（须在平台白名单中） |
|
||||
| `--temperature <n>` | number | 否 | 采样温度，范围 0-2 |
|
||||
| `--max-llm-calls <n>` | number | 否 | 单次请求最大 LLM 调用次数，范围 1-30 |
|
||||
| `--enable-session-file <bool>` | string | 否 | 启用会话文件：`true` 或 `false` |
|
||||
| `--enable-refusal <bool>` | string | 否 | 启用拒答：`true` 或 `false` |
|
||||
| `--enable-anti-leak <bool>` | string | 否 | 启用防泄漏：`true` 或 `false` |
|
||||
| `--enable-rich-text <bool>` | string | 否 | 启用富文本输出：`true` 或 `false` |
|
||||
| `--enable-citation <bool>` | string | 否 | 启用引用标注：`true` 或 `false` |
|
||||
| `--config-file <path>` | string | 否 | JSON 文件替换整个 `agent_config`（含嵌套设置如 `kb_search_configs`）；与标量配置参数互斥 |
|
||||
|
||||
**参数约束**
|
||||
|
||||
- 至少提供一个更新项（`--name`/`--description`/`--version-desc`/`--config-file`/标量配置参数），否则报错 "Nothing to update"
|
||||
- `--config-file` 与标量配置参数（`--policy`/`--model`/`--temperature` 等）互斥
|
||||
- 已发布版本 + 配置变更 → 报错（已发布版本只接受 `--version-desc`）
|
||||
- `--name` 最多 200 字符；`--description` 最多 1000 字符
|
||||
- `--policy` 只能是 `turbo` 或 `agentic`
|
||||
- `--temperature` 范围 0-2
|
||||
- `--max-llm-calls` 范围 1-30
|
||||
- 布尔参数（`--enable-*`）只能是 `true` 或 `false`
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
updated: aid-xxx
|
||||
Draft config changed — verify with --agent-version beta, then deploy.
|
||||
```
|
||||
|
||||
quiet 模式：无输出。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 配置变更只作用于 beta 草稿；已发布版本只接受 `--version-desc`。
|
||||
- 标量配置参数采用 read-merge-write：CLI 先读取当前 beta 配置，再合并变更后整体提交（API 是整替换语义）。
|
||||
- `--config-file` 替换整个配置，适合设置嵌套字段（如 `kb_search_configs`）。
|
||||
- 修改草稿后用 `--agent-version beta` 在 search/chat 上测试，通过后 `service deploy` 发布。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 调整温度
|
||||
kscli service update --agent-id aid-xxx --temperature 0.7 --workspace-id ws-xxx
|
||||
|
||||
# 用 JSON 文件替换整个配置
|
||||
kscli service update --agent-id aid-xxx --config-file ./agent-config.json
|
||||
|
||||
# 给已发布版本 1 加描述
|
||||
kscli service update --agent-id aid-xxx --agent-version 1 --version-desc "first stable release"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli service deploy`
|
||||
|
||||
发布 beta 草稿为新版本。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli service deploy --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ----------------------- | ------ | ---- | ---------------- |
|
||||
| `--agent-id <id>` | string | 是 | 服务（agent）ID |
|
||||
| `--version-desc <text>` | string | 否 | 新版本的描述说明 |
|
||||
| `--yes` | switch | 否 | 跳过确认提示 |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
deployed: aid-xxx version 2
|
||||
```
|
||||
|
||||
quiet 模式：输出新版本号。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 版本号自动递增，状态变为 `deployed`。
|
||||
- 发布影响线上调用方，确认提示会警告。
|
||||
- 如果当前状态为 `edited`（已发布后又改了草稿），确认提示会额外警告「发布会覆盖线上行为」。
|
||||
- 需要工作区的知识库修改权限。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 发布（交互确认）
|
||||
kscli service deploy --agent-id aid-xxx --workspace-id ws-xxx
|
||||
|
||||
# 带描述并跳过确认
|
||||
kscli service deploy --agent-id aid-xxx --version-desc "tuned rerank params" --yes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli service delete`
|
||||
|
||||
删除检索/Q&A 服务（软删除，幂等）。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli service delete --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ----------------- | ------ | ---- | --------------- |
|
||||
| `--agent-id <id>` | string | 是 | 服务（agent）ID |
|
||||
| `--yes` | switch | 否 | 跳过确认提示 |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
deleted: aid-xxx (status: deleted)
|
||||
```
|
||||
|
||||
quiet 模式：无输出。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 删除不可撤销，`agent_id` 不再可用于 search/chat 调用。
|
||||
- API 是幂等的：删除已删除的服务不会报错。
|
||||
- 如果服务状态为 `deployed` 或 `edited`，确认提示会额外警告「此服务正在线上运行」。
|
||||
- 需要工作区的知识库删除权限。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 删除（交互确认）
|
||||
kscli service delete --agent-id aid-xxx --workspace-id ws-xxx
|
||||
|
||||
# 跳过确认
|
||||
kscli service delete --agent-id aid-xxx --yes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### `kscli service copy`
|
||||
|
||||
复制服务为新草稿（名称自动加 `copy_` 前缀）。
|
||||
|
||||
**用法**
|
||||
|
||||
```bash
|
||||
kscli service copy --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
**参数**
|
||||
|
||||
| 参数 | 类型 | 必填 | 说明 |
|
||||
| ----------------- | ------ | ---- | ----------------- |
|
||||
| `--agent-id <id>` | string | 是 | 源服务（agent）ID |
|
||||
|
||||
**输出**
|
||||
|
||||
text 模式：
|
||||
|
||||
```
|
||||
new agent_id: aid-new (name: copy_my-qa, status: draft)
|
||||
Test the draft with --agent-version beta on search/chat, then deploy it to publish.
|
||||
```
|
||||
|
||||
quiet 模式：输出新 agent ID。
|
||||
|
||||
json 模式：返回 API 原始响应。
|
||||
|
||||
**注意事项**
|
||||
|
||||
- 副本初始为 beta 草稿，测试后需 deploy 发布。
|
||||
- 需要工作区的知识库创建权限。
|
||||
|
||||
**示例**
|
||||
|
||||
```bash
|
||||
# 复制服务
|
||||
kscli service copy --agent-id aid-source --workspace-id ws-xxx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
← [返回总览](./kscli-cli-guide.md)
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "bailian-cli",
|
||||
"version": "1.17.0",
|
||||
"version": "1.17.1",
|
||||
"description": "CLI for Aliyun Model Studio (DashScope) AI Platform.",
|
||||
"keywords": [
|
||||
"agent",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "bailian-cli-commands",
|
||||
"version": "1.17.0",
|
||||
"version": "1.17.1",
|
||||
"description": "Command library for bailian-cli products (knowledge, memory, media, …). See https://www.npmjs.com/package/bailian-cli for usage.",
|
||||
"homepage": "https://bailian.console.aliyun.com/cli",
|
||||
"bugs": {
|
||||
|
||||
@@ -20,8 +20,9 @@ const COLLECTION_CREATE_FLAGS = {
|
||||
type: "string",
|
||||
valueHint: "<text>",
|
||||
description: {
|
||||
"en-US": "Collection description (required by the server)",
|
||||
"zh-CN": "数据集合描述（服务端必填）",
|
||||
"en-US":
|
||||
"What this collection holds and what it is for — tells collections apart in the list",
|
||||
"zh-CN": "数据集合装了什么内容、给谁用，用于在列表中区分同类集合",
|
||||
},
|
||||
required: true,
|
||||
},
|
||||
|
||||
@@ -29,6 +29,16 @@ const KB_CREATE_FLAGS = {
|
||||
},
|
||||
required: true,
|
||||
},
|
||||
description: {
|
||||
type: "string",
|
||||
valueHint: "<text>",
|
||||
description: {
|
||||
"en-US":
|
||||
"What this knowledge base holds and what it is for — tells bases apart in the workspace list (1-500 chars)",
|
||||
"zh-CN": "知识库装了什么内容、给谁用，用于在 Workspace 列表中区分同类知识库（1–500 个字符）",
|
||||
},
|
||||
required: true,
|
||||
},
|
||||
docId: {
|
||||
type: "array",
|
||||
valueHint: "<id>",
|
||||
@@ -107,7 +117,7 @@ export default defineCommand({
|
||||
"zh-CN": "创建知识库并导入数据中心文件或类目",
|
||||
},
|
||||
auth: "apiKey",
|
||||
usageArgs: "--name <text> (--doc-id <id> | --category-id <id>) [flags]",
|
||||
usageArgs: "--name <text> --description <text> (--doc-id <id> | --category-id <id>) [flags]",
|
||||
flags: KB_CREATE_FLAGS,
|
||||
notes: [
|
||||
{
|
||||
@@ -126,11 +136,20 @@ export default defineCommand({
|
||||
},
|
||||
],
|
||||
exampleArgs: [
|
||||
"--name demo --doc-id file-xxx --workspace-id ws-xxx",
|
||||
"--name demo --category-id cate-xxx --wait",
|
||||
{
|
||||
"en-US": "--name demo --description 'product docs' --doc-id file-xxx --workspace-id ws-xxx",
|
||||
"zh-CN": "--name demo --description '产品文档' --doc-id file-xxx --workspace-id ws-xxx",
|
||||
},
|
||||
{
|
||||
"en-US": "--name demo --description 'product docs' --category-id cate-xxx --wait",
|
||||
"zh-CN": "--name demo --description '产品文档' --category-id cate-xxx --wait",
|
||||
},
|
||||
],
|
||||
validate(flags) {
|
||||
if (flags.name.length < 1 || flags.name.length > 20) return "--name must be 1-20 characters";
|
||||
if (flags.description.length < 1 || flags.description.length > 500) {
|
||||
return "--description must be 1-500 characters";
|
||||
}
|
||||
const hasDocIds = !!flags.docId?.length;
|
||||
const hasCategoryIds = !!flags.categoryId?.length;
|
||||
if (hasDocIds && hasCategoryIds) return "Use either --doc-id or --category-id, not both";
|
||||
@@ -147,6 +166,9 @@ export default defineCommand({
|
||||
// Note: the public docs' example uses sinkType DEFAULT, but BUILT_IN is what works against the live API.
|
||||
const body = {
|
||||
name: flags.name,
|
||||
// description is a required field; length limit is 1-500 (the public API docs
|
||||
// still list it as absent from CreateIndexV2Request.required).
|
||||
description: flags.description,
|
||||
structureType: "unstructured",
|
||||
sinkType: "BUILT_IN",
|
||||
embeddingModelName: flags.embeddingModel ?? "text-embedding-v4",
|
||||
|
||||
@@ -82,6 +82,13 @@ export default defineCommand({
|
||||
auth: "apiKey",
|
||||
usageArgs: "--index-id <id> --query <text> [flags]",
|
||||
flags: RETRIEVE_FLAGS,
|
||||
notes: [
|
||||
{
|
||||
"en-US":
|
||||
"--rerank-model requires the target knowledge base to already have a rerank model configured; otherwise every value is rejected.",
|
||||
"zh-CN": "--rerank-model 要求目标知识库已配置重排序模型，否则任何取值都会被拒绝。",
|
||||
},
|
||||
],
|
||||
exampleArgs: [
|
||||
{
|
||||
"en-US": '--index-id idx_xxx --query "How to use Alibaba Cloud Bailian"',
|
||||
|
||||
@@ -32,8 +32,10 @@ const SERVICE_CREATE_FLAGS = {
|
||||
type: "string",
|
||||
valueHint: "<text>",
|
||||
description: {
|
||||
"en-US": "Service description (up to 1000 chars)",
|
||||
"zh-CN": "服务描述（最多 1000 个字符）",
|
||||
"en-US":
|
||||
"What this service answers and who it serves — recommended: agents read it to pick the right service (up to 1000 chars)",
|
||||
"zh-CN":
|
||||
"这个服务能回答什么、给谁用 —— 建议填写：agent 靠它判断该调用哪个服务（最多 1000 个字符）",
|
||||
},
|
||||
},
|
||||
indexId: {
|
||||
@@ -71,7 +73,11 @@ export default defineCommand({
|
||||
},
|
||||
],
|
||||
exampleArgs: [
|
||||
"--name my-qa --scene chat --workspace-id ws-xxx",
|
||||
{
|
||||
"en-US":
|
||||
"--name my-qa --scene chat --description 'answers product FAQs' --workspace-id ws-xxx",
|
||||
"zh-CN": "--name my-qa --scene chat --description '回答产品常见问题' --workspace-id ws-xxx",
|
||||
},
|
||||
"--name my-search --scene search --index-id idx-xxx",
|
||||
],
|
||||
validate(flags) {
|
||||
|
||||
@@ -14,8 +14,8 @@ const SERVICE_LIST_FLAGS = {
|
||||
type: "string",
|
||||
valueHint: "<scene>",
|
||||
description: {
|
||||
"en-US": "Service scene: chat (Q&A) or search (retrieval). Required by the server",
|
||||
"zh-CN": "服务场景：chat（问答）或 search（检索），服务端必填",
|
||||
"en-US": "Service scene: chat (Q&A) or search (retrieval)",
|
||||
"zh-CN": "服务场景：chat（问答）或 search（检索）",
|
||||
},
|
||||
required: true,
|
||||
},
|
||||
|
||||
@@ -201,6 +201,15 @@ const KNOWN_CONFIG_KEYS = new Set([
|
||||
"session_file_max_parse_length",
|
||||
"enable_kb_router",
|
||||
"kb_router_model",
|
||||
"user_system_prompt",
|
||||
"anti_leak_prompt",
|
||||
"refusal_prompt",
|
||||
"credibility_prompt",
|
||||
"enable_thinking",
|
||||
"enable_temperature",
|
||||
"enable_credibility",
|
||||
"enable_max_completion_tokens",
|
||||
"session_file_parse_mode",
|
||||
"rerank_top_n",
|
||||
"hybrid_rerank",
|
||||
"kb_search_configs",
|
||||
|
||||
@@ -323,6 +323,8 @@ export async function createKbWithDocs(
|
||||
"create",
|
||||
"--name",
|
||||
kbName,
|
||||
"--description",
|
||||
`journey ${journeyId} fixture knowledge base (safe to delete)`,
|
||||
...fileIds.flatMap((fileId) => ["--doc-id", fileId]),
|
||||
"--workspace-id",
|
||||
workspaceId,
|
||||
|
||||
@@ -18,6 +18,7 @@ import {
|
||||
KNOWLEDGE_KB_DELETE_ROUTES,
|
||||
} from "../topic-routes.ts";
|
||||
import { deleteKbWithRetry, pollUntil } from "./journeys/journey-helpers.ts";
|
||||
import { VERIFIED_RERANK_MODEL } from "./verified-models.ts";
|
||||
|
||||
interface DryRunBody {
|
||||
endpoint?: string;
|
||||
@@ -1058,6 +1059,8 @@ describe.skipIf(!isKbAdminE2EReady())(
|
||||
"create",
|
||||
"--name",
|
||||
`e2e-cate-kb-${Date.now() % 100000000}`.slice(0, 20),
|
||||
"--description",
|
||||
"e2e fixture knowledge base (safe to delete)",
|
||||
"--category-id",
|
||||
categoryId,
|
||||
"--workspace-id",
|
||||
@@ -1158,6 +1161,8 @@ describe.skipIf(!isKbAdminE2EReady())(
|
||||
"create",
|
||||
"--name",
|
||||
`e2e-ck-${Date.now() % 100000000}`,
|
||||
"--description",
|
||||
"e2e fixture knowledge base (safe to delete)",
|
||||
"--doc-id",
|
||||
fileId,
|
||||
"--workspace-id",
|
||||
@@ -1319,7 +1324,7 @@ describe.skipIf(!isKbAdminE2EReady())(
|
||||
"chunk chain fixture",
|
||||
"--rerank",
|
||||
"--rerank-model",
|
||||
"qwen3-rerank-hybrid",
|
||||
VERIFIED_RERANK_MODEL,
|
||||
"--rerank-mode",
|
||||
"similar",
|
||||
"--rerank-top-n",
|
||||
@@ -1701,6 +1706,8 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: chunk/category/file 参数补全 (li
|
||||
"create",
|
||||
"--name",
|
||||
`e2e-pk-${Date.now() % 100000000}`.slice(0, 20),
|
||||
"--description",
|
||||
"e2e fixture knowledge base (safe to delete)",
|
||||
"--doc-id",
|
||||
fileId,
|
||||
"--workspace-id",
|
||||
|
||||
@@ -148,6 +148,8 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge doc status (live, 自清
|
||||
"create",
|
||||
"--name",
|
||||
`e2e-st-${Date.now() % 100000000}`,
|
||||
"--description",
|
||||
"e2e fixture knowledge base (safe to delete)",
|
||||
"--doc-id",
|
||||
fileIdA,
|
||||
"--workspace-id",
|
||||
|
||||
@@ -5,6 +5,7 @@ import { KNOWLEDGE_KB_CREATE_ROUTES } from "../topic-routes.ts";
|
||||
interface DryRunBody {
|
||||
endpoint?: string;
|
||||
request?: {
|
||||
description?: string;
|
||||
sourceType?: string;
|
||||
sinkType?: string;
|
||||
docIds?: string[];
|
||||
@@ -23,6 +24,7 @@ describe("e2e: knowledge kb create", () => {
|
||||
]);
|
||||
expect(exitCode, stderr).toBe(0);
|
||||
expect(stderr).toMatch(/--name/i);
|
||||
expect(stderr).toMatch(/--description/i);
|
||||
expect(stderr).toMatch(/--doc-id/i);
|
||||
expect(stderr).toMatch(/--category-id/i);
|
||||
expect(stderr).toMatch(/--embedding-model/i);
|
||||
@@ -33,6 +35,40 @@ describe("e2e: knowledge kb create", () => {
|
||||
const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [
|
||||
"knowledge",
|
||||
"create",
|
||||
"--description",
|
||||
"demo base",
|
||||
"--doc-id",
|
||||
"file_test",
|
||||
"--workspace-id",
|
||||
"ws_test",
|
||||
]);
|
||||
expect(exitCode).toBe(2);
|
||||
});
|
||||
|
||||
// The server rejects a missing description with HTTP 400 (Index.InvalidParameter);
|
||||
// the CLI must stop it locally instead.
|
||||
test("缺 --description 报 USAGE (2)", async () => {
|
||||
const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [
|
||||
"knowledge",
|
||||
"create",
|
||||
"--name",
|
||||
"demo",
|
||||
"--doc-id",
|
||||
"file_test",
|
||||
"--workspace-id",
|
||||
"ws_test",
|
||||
]);
|
||||
expect(exitCode).toBe(2);
|
||||
});
|
||||
|
||||
test("--description 501 字符报 USAGE (2)", async () => {
|
||||
const { exitCode } = await runCommandE2e(KNOWLEDGE_KB_CREATE_ROUTES, [
|
||||
"knowledge",
|
||||
"create",
|
||||
"--name",
|
||||
"demo",
|
||||
"--description",
|
||||
"x".repeat(501),
|
||||
"--doc-id",
|
||||
"file_test",
|
||||
"--workspace-id",
|
||||
@@ -47,6 +83,8 @@ describe("e2e: knowledge kb create", () => {
|
||||
"create",
|
||||
"--name",
|
||||
"demo",
|
||||
"--description",
|
||||
"demo base",
|
||||
"--workspace-id",
|
||||
"ws_test",
|
||||
]);
|
||||
@@ -59,6 +97,8 @@ describe("e2e: knowledge kb create", () => {
|
||||
"create",
|
||||
"--name",
|
||||
"demo",
|
||||
"--description",
|
||||
"demo base",
|
||||
"--doc-id",
|
||||
"file_test",
|
||||
"--category-id",
|
||||
@@ -75,6 +115,8 @@ describe("e2e: knowledge kb create", () => {
|
||||
"create",
|
||||
"--name",
|
||||
"x".repeat(21),
|
||||
"--description",
|
||||
"demo base",
|
||||
"--doc-id",
|
||||
"file_test",
|
||||
"--workspace-id",
|
||||
@@ -89,6 +131,8 @@ describe("e2e: knowledge kb create", () => {
|
||||
"create",
|
||||
"--name",
|
||||
"demo",
|
||||
"--description",
|
||||
"demo base",
|
||||
"--doc-id",
|
||||
"file_test",
|
||||
"--workspace-id",
|
||||
@@ -103,6 +147,8 @@ describe("e2e: knowledge kb create", () => {
|
||||
expect(data.request?.sourceType).toBe("DATA_CENTER_FILE");
|
||||
expect(data.request?.docIds).toEqual(["file_test"]);
|
||||
expect(data.request?.sinkType).toBe("BUILT_IN");
|
||||
// description is a server-required field — it must reach the request body verbatim
|
||||
expect(data.request?.description).toBe("demo base");
|
||||
// Defaults are part of the contract — the server applies no fallback of its own
|
||||
expect(data.request?.embeddingModelName).toBe("text-embedding-v4");
|
||||
expect(data.request?.chunkSize).toBe(600);
|
||||
@@ -114,6 +160,8 @@ describe("e2e: knowledge kb create", () => {
|
||||
"create",
|
||||
"--name",
|
||||
"demo",
|
||||
"--description",
|
||||
"demo base",
|
||||
"--doc-id",
|
||||
"file_test",
|
||||
"--embedding-model",
|
||||
@@ -138,6 +186,8 @@ describe("e2e: knowledge kb create", () => {
|
||||
"create",
|
||||
"--name",
|
||||
"demo",
|
||||
"--description",
|
||||
"demo base",
|
||||
"--category-id",
|
||||
"cate_test",
|
||||
"--workspace-id",
|
||||
|
||||
@@ -101,6 +101,8 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge kb 写链路 (live, 自清
|
||||
"create",
|
||||
"--name",
|
||||
kbName,
|
||||
"--description",
|
||||
"e2e fixture knowledge base (safe to delete)",
|
||||
"--doc-id",
|
||||
fileId,
|
||||
"--workspace-id",
|
||||
|
||||
@@ -7,6 +7,7 @@ import { join } from "node:path";
|
||||
import { describe, expect, test } from "vite-plus/test";
|
||||
import { isKbAdminE2EReady, parseStdoutJson, runCommandE2e } from "../helpers.ts";
|
||||
import { KNOWLEDGE_SERVICE_ROUTES } from "../topic-routes.ts";
|
||||
import { pickDifferentAgentModel } from "./verified-models.ts";
|
||||
|
||||
interface DryRunBody {
|
||||
endpoint?: string;
|
||||
@@ -780,6 +781,33 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge service 参数全覆盖 (l
|
||||
expect(listIndexIdRun.exitCode, listIndexIdRun.stderr).toBe(0);
|
||||
|
||||
// ── P0 组1: update --name --version-desc --model → get 读回 3 个 scalar ──
|
||||
// --model 取值自适应：先读回草稿当前模型，再挑一个不同的已验证模型写入,
|
||||
// 断言才能证明「值真的变了」而不是把默认值原样写回
|
||||
const baselineGetRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
|
||||
"knowledge",
|
||||
"service",
|
||||
"get",
|
||||
"--agent-id",
|
||||
agentId,
|
||||
"--agent-version",
|
||||
"beta",
|
||||
"--workspace-id",
|
||||
workspaceId,
|
||||
"--output",
|
||||
"json",
|
||||
]);
|
||||
expect(baselineGetRun.exitCode, baselineGetRun.stderr).toBe(0);
|
||||
const baselineModel = parseStdoutJson<{
|
||||
data?: { agent_details?: Array<{ agent_config?: { agent_model?: string } }> };
|
||||
}>(baselineGetRun.stdout).data?.agent_details?.[0]?.agent_config?.agent_model;
|
||||
const targetModel = pickDifferentAgentModel(baselineModel);
|
||||
if (targetModel === undefined) {
|
||||
// 白名单缩到只剩当前模型 —— 跳过模型断言而不是断言一个空操作
|
||||
process.stderr.write(
|
||||
`skip --model assertion: no verified model differs from ${baselineModel}\n`,
|
||||
);
|
||||
}
|
||||
|
||||
const newName = `${serviceName}-renamed`;
|
||||
const updateScalarRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
|
||||
"knowledge",
|
||||
@@ -791,8 +819,7 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge service 参数全覆盖 (l
|
||||
newName,
|
||||
"--version-desc",
|
||||
"beta-v1",
|
||||
"--model",
|
||||
"qwen-plus",
|
||||
...(targetModel === undefined ? [] : ["--model", targetModel]),
|
||||
"--workspace-id",
|
||||
workspaceId,
|
||||
]);
|
||||
@@ -816,14 +843,18 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge service 参数全覆盖 (l
|
||||
data?: {
|
||||
agent_name?: string;
|
||||
agent_details?: Array<{
|
||||
agent_version_desc?: string;
|
||||
agent_version_desc?: string | null;
|
||||
agent_config?: { agent_model?: string };
|
||||
}>;
|
||||
};
|
||||
}>(scalarGetRun.stdout);
|
||||
expect(scalarGetData.data?.agent_name).toBe(newName);
|
||||
expect(scalarGetData.data?.agent_details?.[0]?.agent_config?.agent_model).toBe("qwen-plus");
|
||||
expect(scalarGetData.data?.agent_details?.[0]?.agent_version_desc).toBe("beta-v1");
|
||||
if (targetModel !== undefined) {
|
||||
expect(scalarGetData.data?.agent_details?.[0]?.agent_config?.agent_model).toBe(targetModel);
|
||||
}
|
||||
// --version-desc 在 beta 草稿上是服务端空操作：update 返回 200 但存为 null。
|
||||
// 版本说明只在 deploy 时传入、或对已发布版本 update 才能落库（下方 P0 组4 覆盖）。
|
||||
expect(scalarGetData.data?.agent_details?.[0]?.agent_version_desc).toBeNull();
|
||||
|
||||
// ── P0 组2: update --policy turbo → get 读回 ──
|
||||
const updateTurboRun = await runCommandE2e(KNOWLEDGE_SERVICE_ROUTES, [
|
||||
|
||||
@@ -6,6 +6,7 @@ import {
|
||||
runCommandE2e,
|
||||
} from "../helpers.ts";
|
||||
import { KNOWLEDGE_ROUTES } from "../topic-routes.ts";
|
||||
import { VERIFIED_RERANK_MODEL } from "./verified-models.ts";
|
||||
|
||||
// ---- Types ----
|
||||
|
||||
@@ -168,7 +169,7 @@ describe("e2e: knowledge retrieve dry-run", () => {
|
||||
"hello",
|
||||
"--rerank",
|
||||
"--rerank-model",
|
||||
"qwen3-rerank-hybrid",
|
||||
VERIFIED_RERANK_MODEL,
|
||||
"--rerank-mode",
|
||||
"custom",
|
||||
"--rerank-instruct",
|
||||
@@ -187,7 +188,7 @@ describe("e2e: knowledge retrieve dry-run", () => {
|
||||
expect(data.request?.enable_reranking).toBe(true);
|
||||
expect(data.request?.dense_similarity_top_k).toBe(100);
|
||||
expect(data.request?.sparse_similarity_top_k).toBe(50);
|
||||
expect(data.request?.rerank?.[0]?.model_name).toBe("qwen3-rerank-hybrid");
|
||||
expect(data.request?.rerank?.[0]?.model_name).toBe(VERIFIED_RERANK_MODEL);
|
||||
expect(data.request?.rerank?.[0]?.rerank_mode).toBe("custom");
|
||||
expect(data.request?.rerank?.[0]?.rerank_instruct).toBe("按相关性排序");
|
||||
});
|
||||
@@ -220,7 +221,7 @@ describe.skipIf(!isKbAdminE2EReady())("e2e: knowledge retrieve 参数补全 (liv
|
||||
"e2e test",
|
||||
"--rerank",
|
||||
"--rerank-model",
|
||||
"qwen3-rerank-hybrid",
|
||||
VERIFIED_RERANK_MODEL,
|
||||
"--rerank-mode",
|
||||
"custom",
|
||||
"--rerank-instruct",
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
// Model values verified against the live API, shared by the knowledge e2e cases so a
|
||||
// server-side model rotation only needs one edit here.
|
||||
//
|
||||
// Deliberately test-only: the command layer must NOT mirror these lists into local
|
||||
// validation. Model catalogs churn with server-side launches/deprecations, so a
|
||||
// hardcoded allowlist in the CLI would block valid models until users upgrade.
|
||||
|
||||
/**
|
||||
* Accepted values for `agent_config.agent_model` (service create/update).
|
||||
* Everything else — including qwen-plus, qwen-max, qwen3-max, qwen3.7-flash,
|
||||
* qwen3.7-max and deepseek-v3 — is rejected with
|
||||
* HTTP 401 InvalidParameter "agent model not allowed: <name>".
|
||||
* The first entry is also the server-side default for a freshly created service.
|
||||
*/
|
||||
export const VERIFIED_AGENT_MODELS = ["qwen3.6-plus", "qwen3.7-plus"] as const;
|
||||
|
||||
/**
|
||||
* Accepted value for `rerank[].model_name` on index/retrieve.
|
||||
* Gotcha: the server only branches on the `-hybrid` suffix — the model prefix is
|
||||
* ignored (`qwen3-rerank` and `gte-rerank` score identically to omitting the field,
|
||||
* `qwen3-rerank-hybrid` and `gte-rerank-hybrid` score identically to each other), so
|
||||
* the effective scoring model is the index's own `rerankModelName`. Unknown names and
|
||||
* indexes without `rerankModelName` both fail with
|
||||
* HTTP 500 Index.IndexRerankError "index rerank config(<name>) error.".
|
||||
*/
|
||||
export const VERIFIED_RERANK_MODEL = "qwen3-rerank-hybrid";
|
||||
|
||||
/**
|
||||
* Pick a verified model that differs from the current one, so a write → read-back
|
||||
* assertion proves the value actually changed instead of re-writing the default.
|
||||
* Returns undefined when the allowlist has shrunk to the model already in use — the
|
||||
* caller must then skip the model assertion instead of asserting a no-op.
|
||||
*/
|
||||
export function pickDifferentAgentModel(currentModel: string | undefined): string | undefined {
|
||||
return VERIFIED_AGENT_MODELS.find((model) => model !== currentModel);
|
||||
}
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "bailian-cli-core",
|
||||
"version": "1.17.0",
|
||||
"version": "1.17.1",
|
||||
"description": "Core SDK for bailian-cli. See https://www.npmjs.com/package/bailian-cli for usage.",
|
||||
"homepage": "https://bailian.console.aliyun.com/cli",
|
||||
"bugs": {
|
||||
|
||||
@@ -186,6 +186,17 @@ export interface RagAgentConfig {
|
||||
session_file_max_parse_length?: number;
|
||||
enable_kb_router?: string;
|
||||
kb_router_model?: string;
|
||||
// Fields the server returns in the beta draft config; typed so read-merge-write
|
||||
// round-trips them without a passthrough warning. Observed value kinds, not docs.
|
||||
user_system_prompt?: string;
|
||||
anti_leak_prompt?: string;
|
||||
refusal_prompt?: string;
|
||||
credibility_prompt?: string;
|
||||
enable_thinking?: boolean;
|
||||
enable_temperature?: boolean;
|
||||
enable_credibility?: boolean;
|
||||
enable_max_completion_tokens?: boolean;
|
||||
session_file_parse_mode?: string;
|
||||
rerank_top_n?: number;
|
||||
hybrid_rerank?: Record<string, unknown>;
|
||||
kb_search_configs?: Array<Record<string, unknown>>;
|
||||
|
||||
@@ -42,6 +42,7 @@ npm install -g knowledge-studio-cli
|
||||
# 1. Create a knowledge base
|
||||
kscli kb create \
|
||||
--name "my-kb" \
|
||||
--description "my product docs knowledge base" \
|
||||
--embedding-model text-embedding-v3 \
|
||||
--workspace-id <your-workspace-id>
|
||||
|
||||
|
||||
@@ -42,6 +42,7 @@ npm install -g knowledge-studio-cli
|
||||
# 1. 创建知识库
|
||||
kscli kb create \
|
||||
--name "my-kb" \
|
||||
--description "我的产品文档知识库" \
|
||||
--embedding-model text-embedding-v3 \
|
||||
--workspace-id <your-workspace-id>
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "knowledge-studio-cli",
|
||||
"version": "1.17.0",
|
||||
"version": "1.17.1",
|
||||
"description": "Lightweight RAG CLI for Aliyun Model Studio — focused on knowledge-base retrieval.",
|
||||
"keywords": [
|
||||
"alibaba-cloud",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "bailian-cli-runtime",
|
||||
"version": "1.17.0",
|
||||
"version": "1.17.1",
|
||||
"description": "Runtime framework for bailian-cli (createCli, registry, args, output, pipeline). See https://www.npmjs.com/package/bailian-cli for usage.",
|
||||
"homepage": "https://bailian.console.aliyun.com/cli",
|
||||
"bugs": {
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: bailian-cli
|
||||
metadata:
|
||||
version: "1.17.0"
|
||||
version: "1.17.1"
|
||||
requires:
|
||||
bins: ["bl"]
|
||||
description: >-
|
||||
|
||||
@@ -362,16 +362,16 @@ bl knowledge chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-
|
||||
|
||||
#### Flags
|
||||
|
||||
| Flag | Type | Required | Description |
|
||||
| ---------------------- | ------ | -------- | --------------------------------------------------------------- |
|
||||
| `--name <text>` | string | yes | Collection name |
|
||||
| `--description <text>` | string | yes | Collection description (required by the server) |
|
||||
| `--store-type <type>` | string | no | Storage: platform (managed) or custom (your own OSS bucket) |
|
||||
| `--oss-region <id>` | string | no | OSS region id (required with --store-type custom) |
|
||||
| `--oss-bucket <name>` | string | no | OSS bucket name (required with --store-type custom) |
|
||||
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
|
||||
| `--api-key <key>` | string | no | API key |
|
||||
| `--base-url <url>` | string | no | API base URL |
|
||||
| Flag | Type | Required | Description |
|
||||
| ---------------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
|
||||
| `--name <text>` | string | yes | Collection name |
|
||||
| `--description <text>` | string | yes | What this collection holds and what it is for — tells collections apart in the list |
|
||||
| `--store-type <type>` | string | no | Storage: platform (managed) or custom (your own OSS bucket) |
|
||||
| `--oss-region <id>` | string | no | OSS region id (required with --store-type custom) |
|
||||
| `--oss-bucket <name>` | string | no | OSS bucket name (required with --store-type custom) |
|
||||
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
|
||||
| `--api-key <key>` | string | no | API key |
|
||||
| `--base-url <url>` | string | no | API base URL |
|
||||
|
||||
#### Notes
|
||||
|
||||
@@ -420,27 +420,28 @@ bl knowledge collection get --name my-collection
|
||||
|
||||
### `bl knowledge create`
|
||||
|
||||
| Field | Value |
|
||||
| ------------------ | --------------------------------------------------------------------------------- |
|
||||
| **Name** | `knowledge create` |
|
||||
| **Description** | Create a knowledge base and import data-center files or categories |
|
||||
| **Authentication** | API Key |
|
||||
| **Usage** | `bl knowledge create --name <text> (--doc-id <id> \| --category-id <id>) [flags]` |
|
||||
| Field | Value |
|
||||
| ------------------ | ------------------------------------------------------------------------------------------------------ |
|
||||
| **Name** | `knowledge create` |
|
||||
| **Description** | Create a knowledge base and import data-center files or categories |
|
||||
| **Authentication** | API Key |
|
||||
| **Usage** | `bl knowledge create --name <text> --description <text> (--doc-id <id> \| --category-id <id>) [flags]` |
|
||||
|
||||
#### Flags
|
||||
|
||||
| Flag | Type | Required | Description |
|
||||
| --------------------------- | ------ | -------- | ------------------------------------------------------------------------------------ |
|
||||
| `--name <text>` | string | yes | Knowledge base name (1-20 chars, unique in workspace) |
|
||||
| `--doc-id <id>` | array | no | Data-center file id to import (repeatable); mutually exclusive with --category-id |
|
||||
| `--category-id <id>` | array | no | Import every file under this category (repeatable); mutually exclusive with --doc-id |
|
||||
| `--embedding-model <name>` | string | no | Embedding model name (default: text-embedding-v4) |
|
||||
| `--chunk-size <n>` | number | no | Chunk size in characters (default: 600, recommended 300-800) |
|
||||
| `--wait` | switch | no | Poll the initial import job to a terminal state |
|
||||
| `--poll-interval <seconds>` | number | no | Polling interval when waiting (default: 5) |
|
||||
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
|
||||
| `--api-key <key>` | string | no | API key |
|
||||
| `--base-url <url>` | string | no | API base URL |
|
||||
| Flag | Type | Required | Description |
|
||||
| --------------------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `--name <text>` | string | yes | Knowledge base name (1-20 chars, unique in workspace) |
|
||||
| `--description <text>` | string | yes | What this knowledge base holds and what it is for — tells bases apart in the workspace list (1-500 chars) |
|
||||
| `--doc-id <id>` | array | no | Data-center file id to import (repeatable); mutually exclusive with --category-id |
|
||||
| `--category-id <id>` | array | no | Import every file under this category (repeatable); mutually exclusive with --doc-id |
|
||||
| `--embedding-model <name>` | string | no | Embedding model name (default: text-embedding-v4) |
|
||||
| `--chunk-size <n>` | number | no | Chunk size in characters (default: 600, recommended 300-800) |
|
||||
| `--wait` | switch | no | Poll the initial import job to a terminal state |
|
||||
| `--poll-interval <seconds>` | number | no | Polling interval when waiting (default: 5) |
|
||||
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
|
||||
| `--api-key <key>` | string | no | API key |
|
||||
| `--base-url <url>` | string | no | API base URL |
|
||||
|
||||
#### Notes
|
||||
|
||||
@@ -451,11 +452,11 @@ bl knowledge collection get --name my-collection
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
bl knowledge create --name demo --doc-id file-xxx --workspace-id ws-xxx
|
||||
bl knowledge create --name demo --description 'product docs' --doc-id file-xxx --workspace-id ws-xxx
|
||||
```
|
||||
|
||||
```bash
|
||||
bl knowledge create --name demo --category-id cate-xxx --wait
|
||||
bl knowledge create --name demo --description 'product docs' --category-id cate-xxx --wait
|
||||
```
|
||||
|
||||
### `bl knowledge delete`
|
||||
@@ -911,6 +912,10 @@ bl knowledge list --name demo --page-number 2 --page-size 50
|
||||
| `--api-key <key>` | string | no | API key |
|
||||
| `--base-url <url>` | string | no | API base URL |
|
||||
|
||||
#### Notes
|
||||
|
||||
- --rerank-model requires the target knowledge base to already have a rerank model configured; otherwise every value is rejected.
|
||||
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
@@ -999,15 +1004,15 @@ bl knowledge service copy --agent-id aid-xxx --workspace-id ws-xxx
|
||||
|
||||
#### Flags
|
||||
|
||||
| Flag | Type | Required | Description |
|
||||
| ---------------------- | ------ | -------- | ----------------------------------------------------------------- |
|
||||
| `--name <text>` | string | yes | Service name (up to 200 chars, unique per scene in the workspace) |
|
||||
| `--scene <scene>` | string | yes | Service scene: chat (Q&A) or search (retrieval) |
|
||||
| `--description <text>` | string | no | Service description (up to 1000 chars) |
|
||||
| `--index-id <id>` | string | no | Bind this knowledge base; other settings use server defaults |
|
||||
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
|
||||
| `--api-key <key>` | string | no | API key |
|
||||
| `--base-url <url>` | string | no | API base URL |
|
||||
| Flag | Type | Required | Description |
|
||||
| ---------------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
|
||||
| `--name <text>` | string | yes | Service name (up to 200 chars, unique per scene in the workspace) |
|
||||
| `--scene <scene>` | string | yes | Service scene: chat (Q&A) or search (retrieval) |
|
||||
| `--description <text>` | string | no | What this service answers and who it serves — recommended: agents read it to pick the right service (up to 1000 chars) |
|
||||
| `--index-id <id>` | string | no | Bind this knowledge base; other settings use server defaults |
|
||||
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
|
||||
| `--api-key <key>` | string | no | API key |
|
||||
| `--base-url <url>` | string | no | API base URL |
|
||||
|
||||
#### Notes
|
||||
|
||||
@@ -1018,7 +1023,7 @@ bl knowledge service copy --agent-id aid-xxx --workspace-id ws-xxx
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
bl knowledge service create --name my-qa --scene chat --workspace-id ws-xxx
|
||||
bl knowledge service create --name my-qa --scene chat --description 'answers product FAQs' --workspace-id ws-xxx
|
||||
```
|
||||
|
||||
```bash
|
||||
@@ -1141,18 +1146,18 @@ bl knowledge service get --agent-id aid-xxx --agent-version beta
|
||||
|
||||
#### Flags
|
||||
|
||||
| Flag | Type | Required | Description |
|
||||
| --------------------- | ------ | -------- | ----------------------------------------------------------------------- |
|
||||
| `--scene <scene>` | string | yes | Service scene: chat (Q&A) or search (retrieval). Required by the server |
|
||||
| `--status <status>` | string | no | Filter by status: draft, deployed (includes edited) or deleted |
|
||||
| `--name <text>` | string | no | Filter by service name (fuzzy match) |
|
||||
| `--agent-id <id>` | string | no | Filter by exact agent ID |
|
||||
| `--index-id <id>` | string | no | Filter by exact linked knowledge base (pipeline) ID |
|
||||
| `--page-number <n>` | number | no | Page number (default: 1) |
|
||||
| `--page-size <n>` | number | no | Page size per request |
|
||||
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
|
||||
| `--api-key <key>` | string | no | API key |
|
||||
| `--base-url <url>` | string | no | API base URL |
|
||||
| Flag | Type | Required | Description |
|
||||
| --------------------- | ------ | -------- | --------------------------------------------------------------- |
|
||||
| `--scene <scene>` | string | yes | Service scene: chat (Q&A) or search (retrieval) |
|
||||
| `--status <status>` | string | no | Filter by status: draft, deployed (includes edited) or deleted |
|
||||
| `--name <text>` | string | no | Filter by service name (fuzzy match) |
|
||||
| `--agent-id <id>` | string | no | Filter by exact agent ID |
|
||||
| `--index-id <id>` | string | no | Filter by exact linked knowledge base (pipeline) ID |
|
||||
| `--page-number <n>` | number | no | Page number (default: 1) |
|
||||
| `--page-size <n>` | number | no | Page size per request |
|
||||
| `--workspace-id <id>` | string | no | Workspace ID for API endpoint URL (or set BAILIAN_WORKSPACE_ID) |
|
||||
| `--api-key <key>` | string | no | API key |
|
||||
| `--base-url <url>` | string | no | API base URL |
|
||||
|
||||
#### Notes
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: bailian-finetune
|
||||
metadata:
|
||||
version: "1.17.0"
|
||||
version: "1.17.1"
|
||||
requires:
|
||||
bins: ["bl"]
|
||||
description: >-
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: bailian-gen
|
||||
metadata:
|
||||
version: "1.17.0"
|
||||
version: "1.17.1"
|
||||
requires:
|
||||
bins: ["bl"]
|
||||
description: >-
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: bailian-managed-agent
|
||||
metadata:
|
||||
version: "1.17.0"
|
||||
version: "1.17.1"
|
||||
requires:
|
||||
bins: ["bl"]
|
||||
description: >-
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: bailian-protocol
|
||||
metadata:
|
||||
version: "1.17.0"
|
||||
version: "1.17.1"
|
||||
requires:
|
||||
bins: ["bl"]
|
||||
description: >-
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
name: bailian-web-search
|
||||
metadata:
|
||||
version: "1.17.0"
|
||||
version: "1.17.1"
|
||||
requires:
|
||||
bins: ["bl"]
|
||||
description: >-
|
||||
|
||||
Reference in New Issue
Block a user