mirror of
https://github.com/modelstudioai/cli.git
synced 2026-09-14 19:49:23 +08:00
docs(tool-bailian-kb): 完善阿里云百炼知识库管理文档与命令参考
- 更新技能描述，补充命令行工具 kscli 的使用范围与说明 - 细化安装与鉴权步骤，明确不同发行通道及 Node.js 版本要求 - 增加详细的命令用途对照表，便于用户区分不同操作命令 - 优化核心工作流示例，简化上传、建库、部署检索服务步骤 - 补充多种 ID 类型说明，帮助用户正确使用各类标识 - 添加关于危险和不可逆操作的说明及确认要求 - 强调服务版本状态及发布流程，规范草稿与发布版切换 - 新增详细的命令参考文档，覆盖 chunk、config、datacenter、 doc、kb、query、service 等命令组 - 更新 package 版本号至 0.1.5，标识本次文档与功能更新
This commit is contained in:
zeyu.fz
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "@ali/bailian-kb-dsh",
|
||||
"version": "0.1.4",
|
||||
"version": "0.1.5",
|
||||
"description": "Bailian knowledge-base tools for DeepSeek Harness: kb_search and kb_chat over the DashScope RAG API, plus the kscli management skill.",
|
||||
"type": "module",
|
||||
"main": "lib/index.js",
|
||||
|
||||
@@ -1,6 +1,12 @@
|
||||
---
|
||||
name: bailian-kb-management
|
||||
description: 管理阿里云百炼知识库（建库、上传文档、部署检索服务、Chunk 运维）。当用户要创建/更新/删除知识库、上传或导入文档、部署检索服务、管理数据中心文件时使用 kscli。检索与问答不走本 skill——用原生工具 kb_search / kb_chat。
|
||||
description: >-
|
||||
管理阿里云百炼知识库（建库、上传文档、部署检索服务、Chunk 运维、数据中心文件管理），命令行工具为 kscli。
|
||||
当用户要创建/更新/删除知识库、上传或导入文档（本地/OSS）、创建/部署/调参检索或问答服务、
|
||||
增删改查 Chunk、管理数据中心类目/文件/集合时使用本 skill。
|
||||
检索与问答不走本 skill——用原生工具 kb_search（取证据）/ kb_chat（成品问答）；
|
||||
kscli search / chat 仅用于部署后的验证调试（如 --agent-version beta 调试草稿版）。
|
||||
普通问答、编程、写作、翻译、泛搜索不触发本 skill。
|
||||
---
|
||||
|
||||
# 百炼知识库管理（kscli）
|
||||
@@ -9,26 +15,78 @@ description: 管理阿里云百炼知识库（建库、上传文档、部署检
|
||||
|
||||
## 前置检查
|
||||
|
||||
1. `kscli --version` —— 未安装则运行 `npm install -g knowledge-studio-cli`（需 Node.js ≥ 18.17）；安装失败时把错误原样报告给用户，不要静默跳过。
|
||||
1. 安装校验：运行 `kscli kb list --help`。若报 `Unknown command` 或 kscli 未安装，执行
|
||||
`npm install -g knowledge-studio-cli@knowledge`（需 Node.js ≥ 18.17）。
|
||||
**管理命令（kb/doc/service/chunk/category/file/collection）只在 `knowledge` 发行通道；
|
||||
`latest` 通道只有 search/chat/config，装错通道会导致所有管理命令不可用。**
|
||||
安装失败时把错误原样报告给用户，不要静默跳过。
|
||||
2. 鉴权：需要 `DASHSCOPE_API_KEY`（环境变量，或 `kscli config set --key api_key --value sk-xxx`）。
|
||||
3. workspace 解析优先级：`--workspace-id` 参数 > 环境变量 `BAILIAN_WORKSPACE_ID` > `kscli config set --key workspace_id --value ws-xxx`。
|
||||
|
||||
## 常用工作流：建库到可检索
|
||||
## 何时用哪个命令
|
||||
|
||||
| 用户意图 | 命令 | 备注 |
|
||||
| --- | --- | --- |
|
||||
| 查知识 / 问答（日常检索） | 原生工具 `kb_search` / `kb_chat` | 不走 kscli |
|
||||
| 建库 / 查看 / 改名 / 删库 / 监控 | `kscli kb create/list/info/update/delete/stats` | [reference/kb.md](reference/kb.md) |
|
||||
| 上传本地文档、看解析状态、删文档、打标签 | `kscli doc upload/list/status/delete/tag` | [reference/doc.md](reference/doc.md) |
|
||||
| 从 OSS 批量导入 | `kscli doc import-oss` | Bucket 需预先授权服务角色 |
|
||||
| 创建 / 部署 / 调参检索（问答）服务 | `kscli service create/update/deploy/…` | [reference/service.md](reference/service.md) |
|
||||
| 修正错误切片、屏蔽某段内容 | `kscli chunk add/list/update/delete` | [reference/chunk.md](reference/chunk.md) |
|
||||
| 数据中心类目 / 文件 / 集合管理 | `kscli category/file/collection …` | [reference/datacenter.md](reference/datacenter.md) |
|
||||
| CLI 配置、升级 | `kscli config show/set`、`kscli update` | [reference/config.md](reference/config.md) |
|
||||
| 部署后验证、调试草稿版服务 | `kscli search/chat --agent-version beta` | [reference/query.md](reference/query.md) |
|
||||
|
||||
## 核心工作流：建库到可检索
|
||||
|
||||
```bash
|
||||
kscli kb create --name "my-kb" --embedding-model text-embedding-v3 # 1. 建库
|
||||
kscli doc upload --kb-id <kb-id> --file ./docs.pdf # 2. 上传本地文档
|
||||
kscli doc status --kb-id <kb-id> --doc-id <doc-id> # 3. 轮询至 COMPLETED
|
||||
kscli service create ... && kscli service deploy ... # 4. 建/部署检索服务 → 得到 agent_id
|
||||
kscli doc upload --file ./docs/ --workspace-id ws-xxx # 1. 上传本地文件/目录 → 得 fileId
|
||||
kscli kb create --name my-kb --doc-id <fileId> --wait # 2. 建库并导入 → 得 index-id (pipelineId)
|
||||
kscli service create --name my-search --scene search --index-id <index-id> # 3. 建检索服务 → 得 agent-id（draft）
|
||||
kscli service deploy --agent-id <agent-id> --yes # 4. 发布服务（此后可被默认版本调用）
|
||||
kscli service list --scene search --status deployed # 5. 确认服务可见
|
||||
```
|
||||
|
||||
部署完成后用 `kscli service list` 确认服务可见，再用 `kb_search` 带该 `agent_id` 验证检索。
|
||||
部署完成后用原生工具 `kb_search` 带该 `agent_id` 验证检索；若要在部署前调试草稿配置，用 `kscli search --agent-id <id> --agent-version beta`。
|
||||
|
||||
## 命令组速查
|
||||
已有文件再入库的简写：`kscli doc upload --file ./a.md --index-id <index-id> --wait`（上传+导入一步完成）。
|
||||
|
||||
`kb`（list/info/create/update/delete/stats）· `doc`（list/upload/status/delete/tag/import-oss）· `service`（list/get/create/update/deploy/delete/copy）· `chunk`（add/list/update/delete）· `file` / `collection` / `category`（数据中心）。全部命令支持 `--output json`（结构化输出）、`--dry-run`（预览请求）、`--quiet`。完整手册：https://github.com/modelstudioai/cli/blob/main/docs/knowledge-cli-guide.md
|
||||
## ID 速查（极易混淆）
|
||||
|
||||
| ID | 来源 | 用在哪 |
|
||||
| --- | --- | --- |
|
||||
| `index-id` | `kb create` 返回的 pipelineId / `kb list` | 所有 kb/doc/chunk 命令的 `--index-id` |
|
||||
| `fileId` | `doc upload` / `doc import-oss` 返回 | 数据中心命令（`file get/delete`、`kb create --doc-id`、`doc tag`） |
|
||||
| `doc_id`（库内文档 ID） | `doc list` 输出 | `doc delete`、`chunk add/update` 的 `--doc-id`；**可能带 workspace 后缀，≠ fileId** |
|
||||
| `job-id` | 导入命令返回的 ingestionId | `doc status`（必须同时给 `--index-id` 和 `--job-id`） |
|
||||
| chunk id | `chunk list` 输出的 `metadata._id` | `chunk update/delete` 的 `--chunk-id` |
|
||||
| `agent-id` | `service create/list` | `service *`、`kb_search`/`kb_chat`、`kscli search/chat` |
|
||||
|
||||
## 命令参考（权威）
|
||||
|
||||
命令的完整 Usage / Flags / Notes / Examples 在 [`reference/`](reference/index.md)：
|
||||
|
||||
- [reference/index.md](reference/index.md) — 全命令速查表、全局 flag、鉴权说明
|
||||
- reference/<group>.md — 按命令组分文件（kb / doc / service / chunk / datacenter / config / query）
|
||||
|
||||
执行不熟悉的命令前，先读对应 reference 或跑 `kscli <命令> --help`。**不要猜 flag。**
|
||||
全部命令支持 `--output json`（结构化输出）、`--dry-run`（预览请求）、`--quiet`、`--verbose`。
|
||||
|
||||
## 危险与不可逆操作
|
||||
|
||||
执行以下操作前须向用户确认，脚本化时才用 `--yes` 跳过交互确认：
|
||||
|
||||
- `kb delete`：不可逆，库和全部索引内容永久删除（数据中心源文件保留）。
|
||||
- `file delete`：不可逆，且引用该文件的知识库文档索引会失效；只想从单个库移除用 `doc delete`。
|
||||
- `chunk delete`：不可逆。
|
||||
- `service deploy`：发布影响线上调用方；`service delete` 后 agent_id 不可再用（软删、幂等）。
|
||||
- `collection create`：**没有删除 API**，创建集合要慎重。
|
||||
- 索引配置（embedding 模型、chunk size 等）建库后不可改，只能重建。
|
||||
|
||||
## 最佳实践
|
||||
|
||||
- 用户反复使用同一检索服务时，建议其把 agent_id 写入项目指令（如 AGENTS.md）或让 agent 记住，后续 kb_search / kb_chat 直接携带。
|
||||
- 服务有 draft/deployed 两种状态：只有 deployed 可被默认版本调用；draft 调试用 `--agent-version beta`。
|
||||
- 服务有 draft/deployed 两种状态：只有 deployed 可被默认版本调用；draft 调试用 `--agent-version beta`。改已发布版本的配置：先改 beta 草稿（`service update`），验证后 `service deploy` 发新版本。
|
||||
- 导入类命令（`kb create`、`doc upload --index-id`、`doc status`）优先带 `--wait` 轮询到终态，避免手工轮询；文档解析失败（如 PARSE_FAILED）会以非零退出码透传错误。
|
||||
- `chunk add` 有 10 QPS 限流，批量脚本注意节流；响应不带 chunk id，需要 `chunk list` 反查。
|
||||
- `service list` 必须带 `--scene chat|search`，两个场景要分别查询。
|
||||
|
||||
@@ -0,0 +1,100 @@
|
||||
# `kscli chunk` — Chunk 运维
|
||||
|
||||
> 通用鉴权/全局 flag 见 [index.md](index.md)。以下 Flags 只列命令专属项。
|
||||
> chunk id = `chunk list` 输出的 `metadata._id`；文档 id = `metadata.doc_id`。
|
||||
|
||||
## `kscli chunk add`
|
||||
|
||||
直接向库内添加 chunk。
|
||||
|
||||
```
|
||||
Usage: kscli chunk add --index-id <id> (--content <text> | --field <k=v>) [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--doc-id <id>` | 归属文档 ID（取自 `doc list`）；**实践中所有库类型都必填** |
|
||||
| `--content <text>` | Chunk 正文，≤6000 字符（文档型库）；与 `--content-file` 二选一 |
|
||||
| `--content-file <path>` | 从 UTF-8 纯文本文件读正文（.md/.txt 等） |
|
||||
| `--title <text>` | Chunk 标题，≤50 字符 |
|
||||
| `--image-url <url>` | Chunk 图片 URL（可重复，≤10 个） |
|
||||
| `--field <key=value>` | 表格/图片型库的任意字段（可重复，key 为 Excel 列头）；与 content/title/image 互斥 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 支持文档/表格/图片型知识库；音视频型不支持。
|
||||
- `--doc-id` 用 `doc list` 的文档级 id；`chunk list` 输出里的行级 doc_id 不被接受。
|
||||
- 图片型文档不支持文本 chunk，需指向文本型文档（docx/pdf/txt）。
|
||||
- API 幂等但限流 10 QPS——批量脚本注意节流。
|
||||
- 响应不带 chunk id；添加后用 `chunk list` 反查。
|
||||
|
||||
```bash
|
||||
kscli chunk add --index-id idx-xxx --content "chunk text" --title intro --doc-id file-xxx
|
||||
kscli chunk add --index-id idx-xxx --field 列A=v1 --field 列B=v2
|
||||
```
|
||||
|
||||
## `kscli chunk list`
|
||||
|
||||
列出 chunk 内容与状态。
|
||||
|
||||
```
|
||||
Usage: kscli chunk list --index-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--doc-id <id>` | 只看该文档的 chunk |
|
||||
| `--page-number <n>` / `--page-size <n>` | 分页（服务端默认 20，上限 100） |
|
||||
|
||||
Notes：
|
||||
|
||||
- 后续 update/delete 用输出中的 `metadata._id`（chunk id）与 `metadata.doc_id`（文档 id）。
|
||||
|
||||
```bash
|
||||
kscli chunk list --index-id idx-xxx --doc-id file-xxx --page-size 50
|
||||
```
|
||||
|
||||
## `kscli chunk update`
|
||||
|
||||
改 chunk 内容或切换检索可见性。
|
||||
|
||||
```
|
||||
Usage: kscli chunk update --index-id <id> --chunk-id <id> --doc-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--chunk-id <id>` | Chunk ID（`chunk list` 的 `metadata._id`） |
|
||||
| `--doc-id <id>` | 归属文档 ID（`chunk list` 的 `metadata.doc_id`） |
|
||||
| `--content <text>` | 新内容，10-6000 字符；与 `--content-file` 二选一 |
|
||||
| `--content-file <path>` | 从 UTF-8 纯文本文件读新内容 |
|
||||
| `--title <text>` | 标题，0-50 字符（空串清除；省略保持不变） |
|
||||
| `--exclude` / `--include` | 从检索中排除 / 恢复（默认 include） |
|
||||
|
||||
Notes：
|
||||
|
||||
- 内容须在 10-6000 字符且不超过库的最大 chunk size。
|
||||
- `--content-file` 只接受纯文本；.docx/.pdf 不在这里解析。
|
||||
- 只切 `--exclude/--include` 不给新内容时，自动重提交现有内容。
|
||||
|
||||
```bash
|
||||
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --content "corrected text"
|
||||
kscli chunk update --index-id idx-xxx --chunk-id chunk-xxx --doc-id file-xxx --exclude
|
||||
```
|
||||
|
||||
## `kscli chunk delete`
|
||||
|
||||
删除 chunk。**不可逆，执行前须向用户确认。**
|
||||
|
||||
```
|
||||
Usage: kscli chunk delete --index-id <id> --chunk-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--chunk-id <id>` | 要删的 chunk ID（可重复；超过 10 个自动分批发送） |
|
||||
| `--yes` | 跳过交互确认 |
|
||||
|
||||
```bash
|
||||
kscli chunk delete --index-id idx-xxx --chunk-id chunk-a --chunk-id chunk-b --yes
|
||||
```
|
||||
@@ -0,0 +1,55 @@
|
||||
# `kscli config` / `update` — 配置与升级
|
||||
|
||||
> 通用全局 flag 见 [index.md](index.md)。这两组命令无需鉴权。
|
||||
|
||||
## `kscli config show`
|
||||
|
||||
显示当前配置。
|
||||
|
||||
```
|
||||
Usage: kscli config show
|
||||
```
|
||||
|
||||
```bash
|
||||
kscli config show
|
||||
kscli config show --output json
|
||||
```
|
||||
|
||||
## `kscli config set`
|
||||
|
||||
设置配置项。
|
||||
|
||||
```
|
||||
Usage: kscli config set --key <key> --value <value>
|
||||
```
|
||||
|
||||
可用 key：`base_url`、`output`、`output_dir`、`timeout`、`api_key`、`access_token`、
|
||||
`access_key_id`、`access_key_secret`、`security_token`、`default_*_model`、`workspace_id`。
|
||||
|
||||
```bash
|
||||
kscli config set --key workspace_id --value ws-xxx
|
||||
kscli config set --key output --value json
|
||||
kscli config set --key timeout --value 600
|
||||
```
|
||||
|
||||
## `kscli update`
|
||||
|
||||
升级 CLI 到最新或指定版本。
|
||||
|
||||
```
|
||||
Usage: kscli update [--to <version>]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--to <version>` | 安装该精确版本而非最新版 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 管理命令在 `knowledge` 发行通道；若 `kscli update` 后管理命令消失（升到了 latest），用
|
||||
`npm install -g knowledge-studio-cli@knowledge` 装回。
|
||||
|
||||
```bash
|
||||
kscli update
|
||||
kscli update --to 0.1.14
|
||||
```
|
||||
@@ -0,0 +1,158 @@
|
||||
# `kscli category` / `file` / `collection` — 数据中心
|
||||
|
||||
> 通用鉴权/全局 flag 见 [index.md](index.md)。以下 Flags 只列命令专属项。
|
||||
> 数据中心是文件的原始存储层：collection（集合）> category（类目）> file（文件）。知识库只是索引层，删库不影响这里的文件。
|
||||
|
||||
## `kscli category list`
|
||||
|
||||
列出数据中心类目。
|
||||
|
||||
```
|
||||
Usage: kscli category list [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--collection-id <id>` | 按集合 ID 精确过滤 |
|
||||
| `--parent-id <id>` | 列出该父类目下的子类目 |
|
||||
| `--name <text>` | 按名称过滤（**精确匹配**，与 kb list 的模糊匹配不同） |
|
||||
| `--next-token <token>` | 游标分页（取自上一页输出） |
|
||||
| `--max-result <n>` | 每页条数（默认 20） |
|
||||
|
||||
Notes：
|
||||
|
||||
- 标 `[default]` 的类目是未指定类目时文件的默认落点。
|
||||
|
||||
```bash
|
||||
kscli category list --workspace-id ws-xxx
|
||||
kscli category list --name my-category
|
||||
```
|
||||
|
||||
## `kscli category add`
|
||||
|
||||
创建数据中心类目。
|
||||
|
||||
```
|
||||
Usage: kscli category add --name <text> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--name <text>` | 类目名（1-20 字符） |
|
||||
| `--parent-id <id>` | 作为该类目的子类目创建 |
|
||||
| `--collection-id <id>` | 建在该集合下（默认平台集合） |
|
||||
|
||||
```bash
|
||||
kscli category add --name product-docs --workspace-id ws-xxx
|
||||
kscli category add --name sub --parent-id cate-xxx
|
||||
```
|
||||
|
||||
## `kscli category delete`
|
||||
|
||||
删除数据中心类目。**执行前须向用户确认。**
|
||||
|
||||
```
|
||||
Usage: kscli category delete --category-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--yes` | 跳过交互确认 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 含文件或子类目时的行为由服务端决定——服务端错误原样透传。
|
||||
|
||||
```bash
|
||||
kscli category delete --category-id cate-xxx --yes
|
||||
```
|
||||
|
||||
## `kscli file list`
|
||||
|
||||
列出类目下的文件。
|
||||
|
||||
```
|
||||
Usage: kscli file list --category-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--category-id <id>` | 必须是真实类目 id（通过 `category list` 查）；精确匹配 |
|
||||
| `--name <text>` | 按**不含扩展名的完整文件名**精确过滤（a.md → 传 a）；部分关键词查不到 |
|
||||
| `--file-id <id>` | 按文件 ID 精确过滤（可重复） |
|
||||
| `--next-token <token>` / `--max-result <n>` | 游标分页 |
|
||||
|
||||
```bash
|
||||
kscli file list --category-id cate-xxx --workspace-id ws-xxx
|
||||
kscli file list --category-id cate-xxx --name report
|
||||
```
|
||||
|
||||
## `kscli file get`
|
||||
|
||||
查看文件详情（大小、MD5、标签、时间戳）。
|
||||
|
||||
```
|
||||
Usage: kscli file get --file-id <id> [flags]
|
||||
```
|
||||
|
||||
```bash
|
||||
kscli file get --file-id file-xxx --workspace-id ws-xxx
|
||||
```
|
||||
|
||||
## `kscli file delete`
|
||||
|
||||
永久删除数据中心文件。**不可逆，执行前须向用户确认。**
|
||||
|
||||
```
|
||||
Usage: kscli file delete --file-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--yes` | 跳过交互确认 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 不可逆。引用该文件的知识库文档索引会失效。
|
||||
- 只想从单个知识库移除文档时用 `doc delete`。
|
||||
|
||||
```bash
|
||||
kscli file delete --file-id file-xxx --yes
|
||||
```
|
||||
|
||||
## `kscli collection create`
|
||||
|
||||
创建 FILE 数据集合。**没有删除 API——创建须慎重，执行前须向用户确认。**
|
||||
|
||||
```
|
||||
Usage: kscli collection create --name <text> --description <text> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--name <text>` | 集合名 |
|
||||
| `--description <text>` | 描述（服务端必填） |
|
||||
| `--store-type <type>` | 存储：platform（托管，默认）或 custom（自有 OSS bucket） |
|
||||
| `--oss-region <id>` / `--oss-bucket <name>` | `--store-type custom` 时必填 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 自有 bucket 必须带标签 `bailian-connector-access=ReadAndWrite`（百炼基于标签的访问控制）；缺失时服务端会以有误导性的 “setBucketCORS failed” 报错拒绝创建。
|
||||
|
||||
```bash
|
||||
kscli collection create --name my-collection --description 'team docs' --workspace-id ws-xxx
|
||||
kscli collection create --name oss-coll --description 'own bucket' --store-type custom --oss-region cn-beijing --oss-bucket my-bucket
|
||||
```
|
||||
|
||||
## `kscli collection get`
|
||||
|
||||
查看数据集合详情。
|
||||
|
||||
```
|
||||
Usage: kscli collection get (--collection-id <id> | --name <text>) [flags]
|
||||
```
|
||||
|
||||
```bash
|
||||
kscli collection get --collection-id conn-xxx --workspace-id ws-xxx
|
||||
kscli collection get --name my-collection
|
||||
```
|
||||
@@ -0,0 +1,151 @@
|
||||
# `kscli doc` — 文档上传与导入
|
||||
|
||||
> 通用鉴权/全局 flag 见 [index.md](index.md)。以下 Flags 只列命令专属项。
|
||||
|
||||
## `kscli doc upload`
|
||||
|
||||
上传本地文件/目录到数据中心，可选同时导入知识库。
|
||||
|
||||
```
|
||||
Usage: kscli doc upload --file <path> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--file <path>` | 本地文件或目录（可重复）。目录递归扫描，不支持的格式自动跳过 |
|
||||
| `--index-id <id>` | 注册后同时导入该知识库（所有文件合并为一个导入任务） |
|
||||
| `--category-id <id>` | 目标数据中心类目；默认 workspace 默认类目 |
|
||||
| `--tag <text>` | 文件标签（可重复），应用到每个上传文件 |
|
||||
| `--wait` | 轮询导入任务到终态（需配合 `--index-id`） |
|
||||
| `--poll-interval <seconds>` | 轮询间隔（默认 5） |
|
||||
|
||||
Notes：
|
||||
|
||||
- 流水线：申请上传租约 → PUT 到 OSS → 注册文件 →（带 `--index-id` 时）创建导入任务。
|
||||
- 目录递归扫描时自动跳过 node_modules、.git 等。
|
||||
- 多文件顺序处理；中途失败时，已注册的 fileId 会列在错误提示里。
|
||||
|
||||
```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/ --dry-run --verbose
|
||||
```
|
||||
|
||||
## `kscli doc list`
|
||||
|
||||
列出库内文档及解析/索引状态。
|
||||
|
||||
```
|
||||
Usage: kscli doc list --index-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--page-number <n>` | 页码（默认 1） |
|
||||
| `--page-size <n>` | 每页条数（服务端默认 10，上限 100） |
|
||||
|
||||
Notes：
|
||||
|
||||
- FAILED 状态的文档在 text 模式下高亮；用 `doc status` 查失败原因。
|
||||
- 输出的 doc_id 才是 `doc delete` / `chunk add` 应使用的文档 ID。
|
||||
|
||||
```bash
|
||||
kscli doc list --index-id idx-xxx --workspace-id ws-xxx
|
||||
kscli doc list --index-id idx-xxx --page-size 100
|
||||
```
|
||||
|
||||
## `kscli doc status`
|
||||
|
||||
查看导入任务状态。
|
||||
|
||||
```
|
||||
Usage: kscli doc status --index-id <id> --job-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--job-id <id>` | 导入任务 ID（导入命令返回的 ingestionId） |
|
||||
| `--wait` | 轮询到终态 |
|
||||
| `--poll-interval <seconds>` | 轮询间隔（默认 5） |
|
||||
|
||||
Notes：
|
||||
|
||||
- `--index-id` 和 `--job-id` 缺一不可（只传一个返回 SystemError）。
|
||||
- 任务整体状态：PENDING / RUNNING / COMPLETED；单文档失败（如 PARSE_FAILED）以非零退出码透传错误。
|
||||
|
||||
```bash
|
||||
kscli doc status --index-id idx-xxx --job-id job-xxx --wait --poll-interval 10
|
||||
```
|
||||
|
||||
## `kscli doc delete`
|
||||
|
||||
从库中删除文档及其 chunk。**执行前须向用户确认。**
|
||||
|
||||
```
|
||||
Usage: kscli doc delete --index-id <id> --doc-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--doc-id <id>` | 要删除的文档 ID（可重复） |
|
||||
| `--yes` | 跳过交互确认 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 只从知识库索引移除，数据中心源文件保留。
|
||||
- **用 `doc list` 输出的 doc_id，不是 `doc upload` 返回的 fileId**：经 `kb create --doc-id` 入库的文档二者相等；经 `doc upload --index-id` 入库的 doc_id 可能带 workspace 后缀。
|
||||
- 删除传播最多 ~30s，期间文档可能仍出现在 doc list 里。
|
||||
|
||||
```bash
|
||||
kscli doc delete --index-id idx-xxx --doc-id file-a --doc-id file-b --yes
|
||||
```
|
||||
|
||||
## `kscli doc tag`
|
||||
|
||||
批量更新数据中心文件标签。
|
||||
|
||||
```
|
||||
Usage: kscli doc tag --doc-id <id> --tag <text> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--doc-id <id>` | 数据中心文件 ID（可重复，每次 1-20 个） |
|
||||
| `--tag <text>` | 应用到每个 `--doc-id` 的标签（可重复，单个 ≤32 字符） |
|
||||
| `--mode <mode>` | 更新模式：append（默认）或 overwrite |
|
||||
|
||||
Notes：
|
||||
|
||||
- 同一批标签应用到所有 `--doc-id`；不同标签集要分多次执行。
|
||||
- 服务端限制：每文件 ≤100 个标签，标签总长 ≤700 字符。
|
||||
|
||||
```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 批量导入到数据中心。
|
||||
|
||||
```
|
||||
Usage: kscli doc import-oss --bucket <name> --region <id> --oss-key <key> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--bucket <name>` | 已授权的 OSS bucket |
|
||||
| `--region <id>` | OSS region（如 cn-beijing） |
|
||||
| `--oss-key <key>` | 要导入的 OSS object key（可重复，每次 1-10 个） |
|
||||
| `--overwrite` | 覆盖之前导入的同名文件 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 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
|
||||
```
|
||||
@@ -0,0 +1,73 @@
|
||||
# `kscli` 命令参考索引
|
||||
|
||||
> 由 `knowledge-studio-cli@knowledge`（0.0.0-beta-4086da5-202608141600）各命令 `--help` 输出整理。
|
||||
> 命令详情在同目录 `<group>.md`；本索引只放速查表、全局 flag 与鉴权说明。
|
||||
> 版本更新后以 `kscli <命令> --help` 为准。
|
||||
|
||||
## 速查表
|
||||
|
||||
| 命令 | 鉴权 | 说明 | 详情 |
|
||||
| --- | --- | --- | --- |
|
||||
| `kscli kb list` | API Key | 列出 workspace 内知识库 | [kb.md](kb.md) |
|
||||
| `kscli kb info` | API Key | 查看知识库配置详情 | [kb.md](kb.md) |
|
||||
| `kscli kb create` | API Key | 建库并导入数据中心文件或类目 | [kb.md](kb.md) |
|
||||
| `kscli kb update` | API Key | 改名、描述或 rerank 阈值 | [kb.md](kb.md) |
|
||||
| `kscli kb delete` | API Key | 删库（含全部文档与 chunk，不可逆） | [kb.md](kb.md) |
|
||||
| `kscli kb stats` | API Key | 存储量与 QPS 监控数据 | [kb.md](kb.md) |
|
||||
| `kscli doc list` | API Key | 列出库内文档及解析/索引状态 | [doc.md](doc.md) |
|
||||
| `kscli doc status` | API Key | 查看导入任务状态 | [doc.md](doc.md) |
|
||||
| `kscli doc upload` | API Key | 上传本地文件/目录，可选同时入库 | [doc.md](doc.md) |
|
||||
| `kscli doc delete` | API Key | 从库中删除文档及其 chunk | [doc.md](doc.md) |
|
||||
| `kscli doc tag` | API Key | 批量更新数据中心文件标签 | [doc.md](doc.md) |
|
||||
| `kscli doc import-oss` | API Key | 从已授权 OSS bucket 批量导入 | [doc.md](doc.md) |
|
||||
| `kscli service list` | API Key | 列出检索/问答服务 | [service.md](service.md) |
|
||||
| `kscli service get` | API Key | 查看服务各版本配置 | [service.md](service.md) |
|
||||
| `kscli service create` | API Key | 创建服务（初始为 draft/beta） | [service.md](service.md) |
|
||||
| `kscli service update` | API Key | 更新名称、描述或草稿配置 | [service.md](service.md) |
|
||||
| `kscli service deploy` | API Key | 把 beta 草稿发布为新版本 | [service.md](service.md) |
|
||||
| `kscli service delete` | API Key | 删除服务（软删、幂等） | [service.md](service.md) |
|
||||
| `kscli service copy` | API Key | 复制服务为新草稿（名称加 copy\_ 前缀） | [service.md](service.md) |
|
||||
| `kscli chunk add` | API Key | 直接向库内添加 chunk | [chunk.md](chunk.md) |
|
||||
| `kscli chunk list` | API Key | 列出 chunk 内容与状态 | [chunk.md](chunk.md) |
|
||||
| `kscli chunk update` | API Key | 改 chunk 内容或切换检索可见性 | [chunk.md](chunk.md) |
|
||||
| `kscli chunk delete` | API Key | 删除 chunk（不可逆） | [chunk.md](chunk.md) |
|
||||
| `kscli category list` | API Key | 列出数据中心类目 | [datacenter.md](datacenter.md) |
|
||||
| `kscli category add` | API Key | 创建数据中心类目 | [datacenter.md](datacenter.md) |
|
||||
| `kscli category delete` | API Key | 删除数据中心类目 | [datacenter.md](datacenter.md) |
|
||||
| `kscli file list` | API Key | 列出类目下的文件 | [datacenter.md](datacenter.md) |
|
||||
| `kscli file get` | API Key | 查看文件详情（大小/MD5/标签/时间） | [datacenter.md](datacenter.md) |
|
||||
| `kscli file delete` | API Key | 永久删除数据中心文件 | [datacenter.md](datacenter.md) |
|
||||
| `kscli collection create` | API Key | 创建 FILE 数据集合（无删除 API） | [datacenter.md](datacenter.md) |
|
||||
| `kscli collection get` | API Key | 查看数据集合详情 | [datacenter.md](datacenter.md) |
|
||||
| `kscli config show` | 无需 | 显示当前配置 | [config.md](config.md) |
|
||||
| `kscli config set` | 无需 | 设置配置项 | [config.md](config.md) |
|
||||
| `kscli update` | 无需 | 升级 CLI | [config.md](config.md) |
|
||||
| `kscli search` | API Key | RAG 语义检索（部署验证用；日常检索走原生工具 kb_search） | [query.md](query.md) |
|
||||
| `kscli chat` | API Key | RAG 问答，SSE 流式（部署验证用；日常问答走原生工具 kb_chat） | [query.md](query.md) |
|
||||
| `kscli retrieve` | API Key | 已废弃，改用 `search` | [query.md](query.md) |
|
||||
|
||||
## 全局 flag（所有命令可用）
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--output <format>` | 输出格式：text、json |
|
||||
| `--timeout <seconds>` | 请求超时 |
|
||||
| `--quiet` | 抑制非必要输出 |
|
||||
| `--verbose` | 打印 HTTP 请求/响应详情 |
|
||||
| `--dry-run` | 只预览请求不执行 |
|
||||
| `--config <name>` | 本次命令使用指定配置 profile |
|
||||
| `--help` / `--version` | 帮助 / 版本 |
|
||||
|
||||
## 鉴权 flag（API Key 类命令可用）
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--api-key <key>` | API key（优先于环境变量 `DASHSCOPE_API_KEY` 与 config） |
|
||||
| `--base-url <url>` | API base URL |
|
||||
| `--workspace-id <id>` | Workspace ID（或环境变量 `BAILIAN_WORKSPACE_ID`，或 config `workspace_id`） |
|
||||
|
||||
## 说明
|
||||
|
||||
- 所有管理命令使用 DashScope API Key（Bearer token）鉴权，无 console 登录态。
|
||||
- 默认输出为 text；agent 解析结果时建议显式加 `--output json`。
|
||||
- 分页有两种风格：kb/doc/service/chunk 用 `--page-number/--page-size`（page-size 上限 100）；category/file 用游标 `--next-token/--max-result`。
|
||||
@@ -0,0 +1,137 @@
|
||||
# `kscli kb` — 知识库生命周期
|
||||
|
||||
> 通用鉴权/全局 flag 见 [index.md](index.md)。以下 Flags 只列命令专属项。
|
||||
|
||||
## `kscli kb list`
|
||||
|
||||
列出 workspace 内知识库。
|
||||
|
||||
```
|
||||
Usage: kscli kb list [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--name <text>` | 按名称过滤（模糊匹配，1-20 字符） |
|
||||
| `--page-number <n>` | 页码（默认 1） |
|
||||
| `--page-size <n>` | 每页条数 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 返回的 id 即后续 kb/doc/chunk 管理命令的 `--index-id`。
|
||||
|
||||
```bash
|
||||
kscli kb list --workspace-id ws-xxx
|
||||
kscli kb list --name demo --page-number 2 --page-size 50
|
||||
```
|
||||
|
||||
## `kscli kb info`
|
||||
|
||||
查看知识库配置详情。
|
||||
|
||||
```
|
||||
Usage: kscli kb info --index-id <id> [flags]
|
||||
```
|
||||
|
||||
Notes：
|
||||
|
||||
- 索引配置不可变，改配置需重建知识库。
|
||||
|
||||
```bash
|
||||
kscli kb info --index-id idx-xxx --workspace-id ws-xxx
|
||||
```
|
||||
|
||||
## `kscli kb create`
|
||||
|
||||
建库并导入数据中心文件或类目。
|
||||
|
||||
```
|
||||
Usage: kscli kb create --name <text> (--doc-id <id> | --category-id <id>) [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--name <text>` | 库名（1-20 字符，workspace 内唯一） |
|
||||
| `--doc-id <id>` | 数据中心文件 id（可重复）；与 `--category-id` 互斥 |
|
||||
| `--category-id <id>` | 导入该类目下所有文件（可重复）；与 `--doc-id` 互斥 |
|
||||
| `--embedding-model <name>` | Embedding 模型（默认 text-embedding-v4） |
|
||||
| `--chunk-size <n>` | Chunk 大小（默认 600，建议 300-800） |
|
||||
| `--wait` | 轮询首次导入任务到终态 |
|
||||
| `--poll-interval <seconds>` | 轮询间隔（默认 5） |
|
||||
|
||||
Notes：
|
||||
|
||||
- 结构/存储类型固定为默认文档知识库（非结构化，BUILT_IN 存储）。
|
||||
- 返回知识库 id（pipelineId）与首次导入任务 id（ingestionId）；用 `doc status`（或 `--wait`）跟踪导入。
|
||||
|
||||
```bash
|
||||
kscli kb create --name demo --doc-id file-xxx --workspace-id ws-xxx
|
||||
kscli kb create --name demo --category-id cate-xxx --wait
|
||||
```
|
||||
|
||||
## `kscli kb update`
|
||||
|
||||
改名、描述或 rerank 阈值。
|
||||
|
||||
```
|
||||
Usage: kscli kb update --index-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--name <text>` | 新库名（1-20 字符） |
|
||||
| `--description <text>` | 新描述 |
|
||||
| `--rerank-min-score <score>` | Rerank 最低分阈值，0-1（低于该分的 chunk 被过滤） |
|
||||
|
||||
Notes：
|
||||
|
||||
- 索引配置（embedding 模型、chunk size 等）不可变——要改只能重建。
|
||||
|
||||
```bash
|
||||
kscli kb update --index-id idx-xxx --description 'product docs v2' --workspace-id ws-xxx
|
||||
kscli kb update --index-id idx-xxx --rerank-min-score 0.3
|
||||
```
|
||||
|
||||
## `kscli kb delete`
|
||||
|
||||
删库（含全部文档与 chunk）。**不可逆，执行前须向用户确认。**
|
||||
|
||||
```
|
||||
Usage: kscli kb delete --index-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--yes` | 跳过交互确认 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 不可逆——知识库与全部索引内容永久删除。
|
||||
- 数据中心内的源文件不受影响，只删索引。
|
||||
|
||||
```bash
|
||||
kscli kb delete --index-id idx-xxx --workspace-id ws-xxx
|
||||
kscli kb delete --index-id idx-xxx --yes
|
||||
```
|
||||
|
||||
## `kscli kb stats`
|
||||
|
||||
存储量与 QPS 监控数据。
|
||||
|
||||
```
|
||||
Usage: kscli kb stats --index-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--start <time>` | 区间起点：Unix 秒或 ISO 日期，须为过去时间（默认 24 小时前） |
|
||||
| `--end <time>` | 区间终点（默认现在） |
|
||||
|
||||
Notes：
|
||||
|
||||
- 监控 API 只返回历史数据：`--start` 拒绝未来时间，`--end` 的未来值被截断到当前。
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
@@ -0,0 +1,58 @@
|
||||
# `kscli search` / `chat` — 检索与问答（仅部署验证用）
|
||||
|
||||
> **日常检索/问答走原生工具 `kb_search` / `kb_chat`，不走 kscli。**
|
||||
> 这两条命令只在两种场景下使用：(1) 部署前用 `--agent-version beta` 调试草稿配置；(2) 排查原生工具与 CLI 行为差异。
|
||||
> 通用鉴权/全局 flag 见 [index.md](index.md)。
|
||||
|
||||
## `kscli search`
|
||||
|
||||
RAG 语义检索。
|
||||
|
||||
```
|
||||
Usage: kscli search --query <text> --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--query <text>` | 查询文本（必填，不能为空） |
|
||||
| `--agent-id <id>` | 检索服务 ID |
|
||||
| `--agent-version <version>` | 调用版本：beta（草稿调试）或已发布版本号；默认最新发布版 |
|
||||
| `--image <url>` | 多模态检索图片 URL（可重复） |
|
||||
|
||||
Notes：
|
||||
|
||||
- 检索范围与策略（多库加权、路由、rerank 等）由 agent_id 的服务配置决定，只有 query 和 agent_id 必填。
|
||||
|
||||
```bash
|
||||
kscli search --query "What is RAG?" --agent-id aid-xxx --workspace-id ws-xxx
|
||||
kscli search --query "test" --agent-id aid-xxx --agent-version beta
|
||||
```
|
||||
|
||||
## `kscli chat`
|
||||
|
||||
RAG 问答（SSE 流式）。
|
||||
|
||||
```
|
||||
Usage: kscli chat --message <text> --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--message <text>` | 消息（可重复）。支持 `role:content` 前缀设角色（如 `user:hello`），默认 user，遵循 OpenAI 消息格式 |
|
||||
| `--agent-id <id>` | 问答服务 ID |
|
||||
| `--agent-version <version>` | beta 或已发布版本号；默认最新发布版 |
|
||||
| `--image <url>` | 图片 URL（可重复），作为多模态内容附加到最后一条 user 消息 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 响应为 SSE 流。事件生命周期：tool_calling → tool_return →（可循环）→ plan_start → planning → plan_end → generation_start → generating → generation_end。
|
||||
- 多轮对话：用 `--message "user:..."` 和 `--message "assistant:..."` 传历史。
|
||||
|
||||
```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..." --message "How does it work?" --agent-id aid-xxx
|
||||
```
|
||||
|
||||
## `kscli retrieve`（已废弃）
|
||||
|
||||
改用 `kscli search`。
|
||||
@@ -0,0 +1,159 @@
|
||||
# `kscli service` — 检索 / 问答服务（agent）
|
||||
|
||||
> 通用鉴权/全局 flag 见 [index.md](index.md)。以下 Flags 只列命令专属项。
|
||||
> 服务状态机：create → draft（beta 草稿，用 `--agent-version beta` 调试）→ deploy → deployed（版本号自增，可被默认版本调用）。
|
||||
|
||||
## `kscli service list`
|
||||
|
||||
列出检索/问答服务。
|
||||
|
||||
```
|
||||
Usage: kscli service list --scene <chat|search> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--scene <scene>` | 服务场景：chat（问答）或 search（检索）。**服务端必填** |
|
||||
| `--status <status>` | 按状态过滤：draft、deployed（含 edited）或 deleted |
|
||||
| `--name <text>` | 按名称过滤（模糊匹配） |
|
||||
| `--agent-id <id>` | 按 agent ID 精确过滤 |
|
||||
| `--index-id <id>` | 按关联知识库 ID 精确过滤 |
|
||||
| `--page-number <n>` / `--page-size <n>` | 分页 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 场景必填——要看全两类服务需分别执行两次。
|
||||
- 返回的 agent_id 用于 search/chat 调用及 service 管理命令。
|
||||
|
||||
```bash
|
||||
kscli service list --scene chat --workspace-id ws-xxx
|
||||
kscli service list --scene search --status deployed
|
||||
```
|
||||
|
||||
## `kscli service get`
|
||||
|
||||
查看服务各版本配置。
|
||||
|
||||
```
|
||||
Usage: kscli service get --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--agent-version <version>` | 只看指定版本（beta 或已发布版本号）；缺省返回全部版本 |
|
||||
|
||||
```bash
|
||||
kscli service get --agent-id aid-xxx --workspace-id ws-xxx
|
||||
kscli service get --agent-id aid-xxx --agent-version beta
|
||||
```
|
||||
|
||||
## `kscli service create`
|
||||
|
||||
创建检索/问答服务（初始 status: draft，version: beta）。
|
||||
|
||||
```
|
||||
Usage: kscli service create --name <text> --scene <chat|search> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--name <text>` | 服务名（≤200 字符，同场景内唯一） |
|
||||
| `--scene <scene>` | chat（问答）或 search（检索） |
|
||||
| `--description <text>` | 描述（≤1000 字符） |
|
||||
| `--index-id <id>` | 绑定知识库；其余配置用服务端默认值 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 草稿（beta）版可在 deploy 前用 search/chat 的 `--agent-version beta` 测试。
|
||||
- 需要 workspace 的知识库创建权限。
|
||||
|
||||
```bash
|
||||
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`
|
||||
|
||||
更新名称、描述或草稿配置。
|
||||
|
||||
```
|
||||
Usage: kscli service update --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--name <text>` / `--description <text>` | 新名称 / 描述 |
|
||||
| `--agent-version <version>` | 目标版本（默认 beta 草稿）。已发布版本只接受 `--version-desc` |
|
||||
| `--version-desc <text>` | 版本描述 |
|
||||
| `--policy <policy>` | Agent 策略：turbo（快）或 agentic（多轮） |
|
||||
| `--model <name>` | 生成模型 code（须在平台白名单内） |
|
||||
| `--temperature <n>` | 采样温度，0-2 |
|
||||
| `--max-llm-calls <n>` | 单请求最大 LLM 调用次数，1-30 |
|
||||
| `--enable-session-file/-refusal/-anti-leak/-rich-text/-citation <bool>` | 功能开关（true/false） |
|
||||
| `--config-file <path>` | JSON 文件整体替换 agent_config（含 kb_search_configs 等嵌套配置）；与标量配置 flag 互斥 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 配置变更只作用于 beta 草稿；已发布版本只能改 `--version-desc`。
|
||||
- 要改已发布版本的配置：先改 beta 草稿 → `--agent-version beta` 验证 → `service deploy` 发新版本。
|
||||
- 标量 flag 合并进当前草稿配置（读-合-写）；`--config-file` 整体替换，二者互斥。
|
||||
- 需要 workspace 的知识库修改权限。
|
||||
|
||||
```bash
|
||||
kscli service update --agent-id aid-xxx --temperature 0.7 --workspace-id ws-xxx
|
||||
kscli service update --agent-id aid-xxx --config-file ./agent-config.json
|
||||
kscli service update --agent-id aid-xxx --agent-version 1 --version-desc 'first stable release'
|
||||
```
|
||||
|
||||
## `kscli service deploy`
|
||||
|
||||
把 beta 草稿发布为新版本。**发布影响线上调用方，执行前须向用户确认。**
|
||||
|
||||
```
|
||||
Usage: kscli service deploy --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--version-desc <text>` | 新版本描述 |
|
||||
| `--yes` | 跳过交互确认 |
|
||||
|
||||
Notes：
|
||||
|
||||
- 版本号自增；状态变为 deployed。需要 workspace 的知识库修改权限。
|
||||
|
||||
```bash
|
||||
kscli service deploy --agent-id aid-xxx --version-desc 'tuned rerank params' --yes
|
||||
```
|
||||
|
||||
## `kscli service delete`
|
||||
|
||||
删除服务（软删、幂等）。**删除后 agent_id 不可再用于 search/chat，执行前须向用户确认。**
|
||||
|
||||
```
|
||||
Usage: kscli service delete --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
| Flag | 说明 |
|
||||
| --- | --- |
|
||||
| `--yes` | 跳过交互确认 |
|
||||
|
||||
```bash
|
||||
kscli service delete --agent-id aid-xxx --yes
|
||||
```
|
||||
|
||||
## `kscli service copy`
|
||||
|
||||
复制服务为新草稿（名称加 copy\_ 前缀）。
|
||||
|
||||
```
|
||||
Usage: kscli service copy --agent-id <id> [flags]
|
||||
```
|
||||
|
||||
Notes：
|
||||
|
||||
- 副本以 beta 草稿开始；用 `--agent-version beta` 测试后 deploy 发布。需要知识库创建权限。
|
||||
|
||||
```bash
|
||||
kscli service copy --agent-id aid-xxx --workspace-id ws-xxx
|
||||
```
|
||||
Reference in New Issue
Block a user